Skip to content

Commit

Permalink
Improve readme docs (#2679)
Browse files Browse the repository at this point in the history 
* improve README's

* improve docs

* improve generate JS Docs
  • Loading branch information
@ximex
ximex authored May 27, 2022
1 parent e08f8d2 commit 41f1e4c
Show file tree
Hide file tree
Showing 10 changed files with 154 additions and 145 deletions.
96 changes: 48 additions & 48 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ State of the game
After the liberation of the Warzone 2100 source-code on December 6th, 2004, all
proprietary technologies have been replaced with open-source counterparts.

Right now supported platforms are Linux, Windows, and macOS. There are reports
Right now supported platforms are Linux, Windows, and macOS. There are reports
that Warzone 2100 is working on BSD, too.

Installation
Expand All @@ -28,7 +28,7 @@ Installation
Visit https://wz2100.net for the latest stable release for Windows, macOS and Ubuntu.

Note for videos in Ubuntu: For important information during the game, download the videos manually. Assuming the game is installed in the standard `~/.local/share/` folder, use these commands:
```
```shell
mkdir ~/.local/share/warzone2100
wget https://github.com/Warzone2100/wz-sequences/releases/download/v3/standard-quality-en-sequences.wz -O ~/.local/share/warzone2100/sequences.wz
```
Expand Down Expand Up @@ -74,12 +74,12 @@ How to get the latest Ubuntu development builds:
> Note: A free GitHub account is currently required to download the artifacts.
4. Extract the contents of the downloaded .zip (`warzone2100_ubuntu<version>_amd64.deb`) to your Desktop.
5. Execute the following commands in Terminal:
```
```shell
cd ~/Desktop
sudo apt install ./warzone2100_ubuntu<version>_amd64.deb
```
6. Download the video for crucial information during the game, for more see "Videos" section. Assuming the game is installed in the standard `~/.local/share/` folder, use this command (update `warzone2100-<version>`):
```
```shell
wget https://github.com/Warzone2100/wz-sequences/releases/download/v3/standard-quality-en-sequences.wz -O ~/.local/share/warzone2100-<version>/sequences.wz
```

Expand All @@ -88,12 +88,12 @@ wget https://github.com/Warzone2100/wz-sequences/releases/download/v3/standard-q
Clone this Git repo and build, following the instructions under:
[How to Build](#how-to-build)

> Development builds are a snapshot of the current state of development, from the
> Development builds are a snapshot of the current state of development, from the
> latest (successfully-built) commit. Help testing these builds is always welcomed,
> but they should be considered a work-in-progress.
### Videos
You can download videos from [here](https://github.com/Warzone2100/wz-sequences/releases/tag/v3), or [here](https://sourceforge.net/projects/warzone2100/files/warzone2100/Videos/). You will need to rename the downloaded file to `sequences.wz`, and place it into your Warzone directory, as described above.
You can download videos from [here](https://github.com/Warzone2100/wz-sequences/releases/tag/v3), or [here](https://sourceforge.net/projects/warzone2100/files/warzone2100/Videos/). You will need to rename the downloaded file to `sequences.wz`, and place it into your Warzone 2100 directory, as described above.
Note that `.wz` files are just `.zip` in disguise, you can rename it and extract the content if wish to inspect them.

Reporting bugs
Expand Down Expand Up @@ -128,36 +128,36 @@ configuration data, save-games and certain other things. Additionally you can
use this directory to place custom maps and mods so the game can find them. The
location of this directory depends on the operating system.

### Warzone directory under GNU/Linux
### Warzone 2100 directory under GNU/Linux

Under GNU/Linux, Warzone conforms to the [XDG base directory spec](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html).
Under GNU/Linux, Warzone 2100 conforms to the [XDG base directory spec](https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html).

By default, the directory `warzone2100-<version>` can be found in your home-directory
By default, the directory `warzone2100-<version>` can be found in your home-directory
under the path `~/.local/share/`.
(If the `XDG_DATA_HOME` environment variable is defined, the Warzone folder will
(If the `XDG_DATA_HOME` environment variable is defined, the Warzone 2100 folder will
be located within `$XDG_DATA_HOME`.)

The leading dot in the `.local` part of the path indicates that it is a hidden
directory, so depending on your configuration you may not be able to see it.
directory, so depending on your configuration you may not be able to see it.
However, you can still access it by typing the path into your address-bar.

### Warzone directory under Windows
### Warzone 2100 directory under Windows

The directory `Warzone 2100 Project\Warzone 2100 <version>` is located under the
The directory `Warzone 2100 Project\Warzone 2100 <version>` is located under the
`%APPDATA%` folder.

Typical `%APPDATA%` paths:
- Windows XP: `\Documents and Settings\$USER$\Application Data`
- Windows Vista+: `\Users\$USER$\AppData\Roaming`

Hence, the default path for the Warzone configuration data on Windows Vista+ would be:
Hence, the default path for the Warzone 2100 configuration data on Windows Vista+ would be:
`C:\Users\$USER$\AppData\Roaming\Warzone 2100 Project\Warzone 2100 <version>\`

By default, the `%APPDATA%` folder is hidden. Entering:
`%APPDATA%\Warzone 2100 Project\` into the address bar of Windows Explorer
will browse to your Warzone directory.
will browse to your Warzone 2100 directory.

### Warzone directory under macOS
### Warzone 2100 directory under macOS

The directory `Warzone 2100 <version>` can be found in your home-directory at:
`~/Library/Application Support/`
Expand All @@ -173,7 +173,7 @@ options, some of them can be changed by using command-line options or using
the in-game menus, others can only be changed by editing the file by hand.

If at any point you did something wrong, you can delete the old configuration
file and just restart Warzone 2100. Then the game will regenerate a new
file and just restart Warzone 2100. Then the game will regenerate a new
configuration file with default values.

Command-line options
Expand Down Expand Up @@ -246,34 +246,34 @@ function. Cheats are ordered by their use and where they can be used.

There are many cheat commands. Some examples:

* "biffer baker" - Your units do more damage and are stronger
* "double up" - Your units are twice as strong
* "give all" - Allows you to build and research everything
* "work harder" - All currently active research topics are instantly researched
* "research all" - Everything is researched instantly
* "let me win" - You win the current campaign mission
* "superpower" - Gives you maximum power
* "teach us" - Gives experience to selected units
* "makemehero" - Makes selected units Heros
* "clone wars" - Clone selected units (x10)
* "clone wars!" - Clone selected units (x40)
* "clone wars!!" - Clone selected units (x135)
* "kill" - Kills selected object
* "john kettley" - Toggles weather conditions
* "get off my land" - Kills all enemy units and structures
* "showfps" - Show average FPS
* "reload me" - Reloads selected weapon instantly
* "damage me" - Selected object takes 20% damage
* "showunits" - Displays unit count information
* "showorders" - Displays unit order/action state
* "droidinfo" - Show unit stats
* `biffer baker` - Your units do more damage and are stronger
* `double up` - Your units are twice as strong
* `give all` - Allows you to build and research everything
* `work harder` - All currently active research topics are instantly researched
* `research all` - Everything is researched instantly
* `let me win` - You win the current campaign mission
* `superpower` - Gives you maximum power
* `teach us` - Gives experience to selected units
* `makemehero` - Makes selected units Heros
* `clone wars` - Clone selected units (x10)
* `clone wars!` - Clone selected units (x40)
* `clone wars!!` - Clone selected units (x135)
* `kill` - Kills selected object
* `john kettley` - Toggles weather conditions
* `get off my land` - Kills all enemy units and structures
* `showfps` - Show average FPS
* `reload me` - Reloads selected weapon instantly
* `damage me` - Selected object takes 20% damage
* `showunits` - Displays unit count information
* `showorders` - Displays unit order/action state
* `droidinfo` - Show unit stats

All available commands can be found in the file: https://github.com/Warzone2100/warzone2100/blob/master/src/cheat.cpp

Modding information
-------------------

Warzone AI, maps and campaign can be scripted using javascript.
Warzone 2100 AI, maps and campaign can be scripted using JavaScript.

Links to further information
* [Scripting](doc/Scripting.md)
Expand All @@ -291,7 +291,7 @@ To properly build the game, either:
_OR_

- Clone the Git repo:
```
```shell
git clone https://github.com/Warzone2100/warzone2100.git
cd warzone2100
git fetch --tags
Expand Down Expand Up @@ -327,40 +327,40 @@ Do **not** use GitHub's "Download Zip" option, as it does not contain submodules
* Using `get-dependencies_linux.sh`:
1. Specify one of the linux distros supported by the script: (`ubuntu`, `fedora`, `alpine`, `archlinux`, `opensuse-tumbleweed`) _REQUIRED_
2. Specify a mode: (`build-all` (default), `build-dependencies`) _OPTIONAL_

Example:
```
```shell
sudo ./get-dependencies_linux.sh ubuntu build-dependencies
```
* Manually (Ubuntu 18.04)+:
```
```shell
sudo apt-get -u update
sudo apt-get -y install git gcc g++ clang cmake libc-dev dpkg-dev ninja-build zip unzip pkg-config gettext asciidoctor
sudo apt-get -y install libpng-dev libsdl2-dev libopenal-dev libphysfs-dev libvorbis-dev libtheora-dev libxrandr-dev libfribidi-dev libfreetype6-dev libharfbuzz-dev libfontconfig1-dev libcurl4-gnutls-dev gnutls-dev libsodium-dev libsqlite3-dev
```
* Manually (Fedora):
```
```shell
sudo dnf -y update && dnf clean all
sudo dnf -y install git gcc gcc-c++ cmake ninja-build p7zip gettext rubygem-asciidoctor
sudo dnf -y install libpng-devel SDL2-devel openal-soft-devel physfs-devel libogg-devel libvorbis-devel libtheora-devel freetype-devel harfbuzz-devel libcurl-devel openssl-devel libsodium-devel sqlite-devel
```
* **Building from the command-line:**
1. Starting from the _parent_ directory of the warzone2100 source code (which is assumed to be in a folder named `warzone2100`), create a **sibling** build directory:
```
```shell
mkdir build
```
2. Change directory into the sibling `build` directory:
```
```shell
cd build
```
3. Run CMake configure to generate the build files:
```
```shell
cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX:PATH=~/wz/install -GNinja ../warzone2100
```
> - [Modify the `CMAKE_INSTALL_PREFIX` parameter value as desired](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) to configure the base installation path.
> - The `../warzone2100` path at the end should point to the warzone2100 source directory.
4. Run CMake build:
```
```shell
cmake --build . --target install
```

Expand Down
5 changes: 2 additions & 3 deletions doc/CmdInterface.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,9 +56,9 @@ All messages are sent in plain-text UTF-8 and end with 0x0a (`\n`).

`stdin` interface is super basic but at the same time a powerful tool for automation.

All messages **must end with 0x0a (`\n`) in order to be processed!**
All messages **must end with `0x0a` (`\n`) in order to be processed!**

If state of interface buffer is unknown and/or corrupted, interface can send a few 0x0a in order to clean reader buffer.
If state of interface buffer is unknown and/or corrupted, interface can send a few `0x0a` in order to clean reader buffer.

* `exit`\
Shuts down **stdin reader interface**
Expand All @@ -81,4 +81,3 @@ If state of interface buffer is unknown and/or corrupted, interface can send a f

* `shutdown now`\
Trigger graceful shutdown of the game regardless of state.

20 changes: 10 additions & 10 deletions doc/CodingStyle.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

## Introduction

We are trying to follow the coding style that is predominant in the old Warzone code.
We are trying to follow the coding style that is predominant in the old Warzone 2100 code.
Please use this style in your patches.

This means your code should look like this (note spaces, braces and line endings):

```
```cpp
void functionName(const char *variableName, int *anotherVar, STRUCTURE *psStruct)
{
if (variableName == NULL)
Expand All @@ -21,18 +21,18 @@ void functionName(const char *variableName, int *anotherVar, STRUCTURE *psStruct
}
```
This is not considered "good" c++ style anymore, but we think consistency is good
This is not considered "good" C++ style anymore, but we think consistency is good
for making the code easy to read, so we want to stick to the old style even for new
code and new patches.
Indentation for scope should use tabs, while indentation for lining up wrapped lines
should use tabs to align with the start of previous line, then spaces. This way the
code will look readable with any tab size. For example, when a line with a two-line
printf begins, use tab to indent it, then use tab then spaces to indent the following
line, like this (\t for tabs):
line, like this (`\t` for tabs):
```
\t\tprintf("some text on this line that got long, "
\t\tprintf("some text on this line that got long",
\t\t "some more text on the next line");
```
Expand All @@ -41,11 +41,11 @@ line, like this (\t for tabs):
* Comment always why you do something if this is not obvious.
* Comment how you do it if it may be difficult to follow.
* Do not comment out code you want to remove. Just remove it. Git can always get it back.
* Always add braces following conditionals (if).
* Always add braces following conditionals (`if`).
* Put curly braces on lines of their own
* Use stdint.h fixed size types (uint32_t etc.) when necessary, otherwise usual C types.
* Don't use Pumpkin's legacy basic types (UDWORD etc.) in new code.
* Try to avoid changing a ton of code when porting something C-ish to something more c++-ish
* Use `stdint.h` fixed size types (`uint32_t` etc.) when necessary, otherwise usual C types.
* Don't use Pumpkin's legacy basic types (`UDWORD` etc.) in new code.
* Try to avoid changing a ton of code when porting something C-ish to something more C++-ish
* Do not rewrite code to C++ just to rewrite stuff to C++
* Avoid templates unless they have clear benefit.
* We do not use exceptions.
Expand Down Expand Up @@ -77,7 +77,7 @@ astyle --options=astyle <files>
We want the code to be easily readable and accessible to newcomers. That means
keeping it simple, rather than writing the coolest possible code. Don't use
fancy c++ features if basic features can do the job just as well. Don't write
fancy C++ features if basic features can do the job just as well. Don't write
clever optimizations if it makes the code hard to read, unless you are in a
performance critical section of the code.
Expand Down
46 changes: 22 additions & 24 deletions doc/Debugging.md
View file
Original file line number Diff line number Diff line change
@@ -1,72 +1,70 @@
Debugging issues
================

Here are some hints and tips for how to debug Warzone problems.
Here are some hints and tips for how to debug Warzone 2100 problems.

In-game tools: Debug menu
-------------------------

The first tool you should learn how to use is the debug menu. You can
open it by going into cheat mode (shift+backspace by default), then
press ctrl+o. The 'Selected' tab can give you information about the
open it by going into cheat mode (`shift+backspace` by default), then
press `ctrl+o`. The **Selected** tab can give you information about the
currently selected game object - if you are missing some information
here, please add it and submit a patch. This tab does not update by
itself, so click again to refresh.

The 'Contexts' tab shows you the script contexts currently active,
and their global variables. The 'Run' button in this tab allows you
The **Contexts** tab shows you the script contexts currently active,
and their global variables. The **Run** button in this tab allows you
to run your own JavaScript code in the selected script context while
the game is running.

In-game tools: Object tracing
-----------------------------

When in debug mode, you can press ctrl+l to trace one game object.
When in debug mode, you can press `ctrl+l` to trace one game object.
This object may now start to emit a lot of information on standard
out. If you are missing some information, just go into the source
and add objTrace(id, ...) calls. This is especially useful when
adding a debug() or printf() call would cause way too much spam on
the standard out. Please think twice about committing objTrace()
and add `objTrace(id, ...)` calls. This is especially useful when
adding a `debug()` or `printf()` call would cause way too much spam on
the standard out. Please think twice about committing `objTrace()`
calls that could be called every frame, as this makes them less
useful for others. Other than that, adding more trace calls is a
good idea, as they are very low overhead when not active.

Anything includes the campaign library has access to camTrace(...).
Anything includes the campaign library has access to `camTrace(...)`.
These can be placed in scripts to show the value of something or something like
printing a string to the terminal when in cheat mode.

Cheats
------

There are some cheat codes that might help. For example, if you are
tracking down an orders related bug, then 'showorders' will show
tracking down an orders related bug, then `showorders` will show
you shorthand strings on each unit about which order it currently
has.

One very useful cheat is 'research all', which teaches you (and
One very useful cheat is `research all`, which teaches you (and
your allies, if shared) every available research in the game.

Another useful cheat is 'deity'. It allows you to see everything on the map
Another useful cheat is `deity`. It allows you to see everything on the map
much like having an uplink built. It does cause radar blips to misbehave if
used repeatedly in campaign.

'biffer baker' makes everything you own very tough to destroy.
`biffer baker` makes everything you own very tough to destroy.

The 'let me win' cheat allows you to skip to the next campaign
level.
The `let me win` cheat allows you to skip to the next campaign level.

There is a cheat exclusive to campaign with the format 'ascend sub-X-Ys'. Do
There is a cheat exclusive to campaign with the format `ascend sub-X-Ys`. Do
note that research is not granted from the skipped missions.
X = what campaign you are on (Alpha = 1, Beta = 2, Gamma = 3).
Y = mission number.
- `X` = what campaign you are on (Alpha = 1, Beta = 2, Gamma = 3).
- `Y` = mission number.
This cheat only warps to pre-offworld missions and not those where a mission
is active on map, ie Alpha 2. So if for example you want to skip to
the last Alpha offworld campaign mission type 'ascend sub1-ds'.
the last Alpha offworld campaign mission type `ascend sub1-ds`.

Possible levels to warp to:
1-1s, 1-2s, 1-3s, 1-4as, 1-5s, 1-7s, 1-ds,
2-1s, 2-2s, 2-5s, 2-ds, 2-6s, 2-7s, 2-8s,
3-1s, 3-2s, 3-4s.
`1-1s`, `1-2s`, `1-3s`, `1-4as`, `1-5s`, `1-7s`, `1-ds`, `2-1s`, `2-2s`,
`2-5s`, `2-ds`, `2-6s`, `2-7s`, `2-8s`, `3-1s`, `3-2s`, `3-4s`.

Used in conjunction with 'let me win' you will be able to get to any mission
Used in conjunction with `let me win` you will be able to get to any mission
in the campaign fairly quick.
Loading

0 comments on commit 41f1e4c

Please sign in to comment.