diff --git a/README.md b/README.md index b5a97a485cc..0a498dd784d 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 ``` @@ -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_amd64.deb`) to your Desktop. 5. Execute the following commands in Terminal: -``` +```shell cd ~/Desktop sudo apt install ./warzone2100_ubuntu_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-`): -``` +```shell wget https://github.com/Warzone2100/wz-sequences/releases/download/v3/standard-quality-en-sequences.wz -O ~/.local/share/warzone2100-/sequences.wz ``` @@ -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 @@ -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-` can be found in your home-directory +By default, the directory `warzone2100-` 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 ` is located under the +The directory `Warzone 2100 Project\Warzone 2100 ` 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 \` 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 ` can be found in your home-directory at: `~/Library/Application Support/` @@ -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 @@ -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) @@ -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 @@ -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 ``` diff --git a/doc/CmdInterface.md b/doc/CmdInterface.md index a103689284d..77777fb24ca 100644 --- a/doc/CmdInterface.md +++ b/doc/CmdInterface.md @@ -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** @@ -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. - diff --git a/doc/CodingStyle.md b/doc/CodingStyle.md index 267e5909e5a..8863b873088 100644 --- a/doc/CodingStyle.md +++ b/doc/CodingStyle.md @@ -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) @@ -21,7 +21,7 @@ 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. @@ -29,10 +29,10 @@ Indentation for scope should use tabs, while indentation for lining up wrapped l 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"); ``` @@ -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. @@ -77,7 +77,7 @@ astyle --options=astyle 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. diff --git a/doc/Debugging.md b/doc/Debugging.md index cf3866f6f0f..1f923903039 100644 --- a/doc/Debugging.md +++ b/doc/Debugging.md @@ -1,37 +1,37 @@ 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. @@ -39,34 +39,32 @@ 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. diff --git a/doc/PIE.md b/doc/PIE.md index 91143833a07..c80ace2aecb 100644 --- a/doc/PIE.md +++ b/doc/PIE.md @@ -31,16 +31,16 @@ The first line specifies the version number -- either 2 or 3. This indicates the type of the file through a hexadecimal combination of the flags 0x200, 0x10 and 0x1. The following flags are available: -* 0x00001 -- Disables additive rendering -* 0x00002 -- Enables additive rendering -* 0x00004 -- Enables premultiplied rendering +* `0x00001` -- Disables additive rendering +* `0x00002` -- Enables additive rendering +* `0x00004` -- Enables premultiplied rendering -* 0x00010 -- Rolls object to face the camera. Used for projectiles shaped like a cylinder. -* 0x00020 -- Pitches object to completely face the camera. Used for projectiles shaped like a sphere. +* `0x00010` -- Rolls object to face the camera. Used for projectiles shaped like a cylinder. +* `0x00020` -- Pitches object to completely face the camera. Used for projectiles shaped like a sphere. -* 0x00200 -- Reserved for backward compatibility. -* 0x01000 -- Specifies that the model should not be stretched to fit terrain. For defensive buildings that have a deep foundation. -* 0x10000 -- Specifies the usage of the TCMask feature, for which a texture named 'page-N_tcmask.png' (*N* being a number) should be used together with the model's ordinary texture. This flag replaced old team coloration methods (read ticket #851). +* `0x00200` -- Reserved for backward compatibility. +* `0x01000` -- Specifies that the model should not be stretched to fit terrain. For defensive buildings that have a deep foundation. +* `0x10000` -- Specifies the usage of the TCMask feature, for which a texture named 'page-N_tcmask.png' (*N* being a number) should be used together with the model's ordinary texture. This flag replaced old team coloration methods (read ticket #851). ### INTERPOLATE diff --git a/doc/Release.md b/doc/Release.md index 8136e21c6bf..d5c4a6b3dc5 100644 --- a/doc/Release.md +++ b/doc/Release.md @@ -12,7 +12,9 @@ Starting off ------------ We do releases off of the git `master` branch. - git pull origin master +```shell +git pull origin master +``` Update the changelog @@ -26,7 +28,7 @@ Edit the `ChangeLog` to be in sync with the latest changes. Also make sure to pu Commit the (above) changes to master -``` +```shell git commit -p ``` @@ -80,9 +82,9 @@ Verify that each installer works, and the game runs. (Start by testing the porta On both Linux & Windows, you can also test the crash handler now. Note, it is better to test the portable version on windows, since then you will always be starting with a virgin config directory. - * Test the crash handler via the --crash command line option, to make sure it produces a good dump file! + * Test the crash handler via the `--crash` command line option, to make sure it produces a good dump file! * You will see a assert() in debug builds, and we do NOT want to release debug builds. - * If you are testing the crash handler in debug builds, use --noassert to skip it. + * If you are testing the crash handler in debug builds, use `--noassert` to skip it. * '''The Crash dumps it produces should be sane.''' ### Test the game @@ -97,9 +99,11 @@ Create the tag for the new release Since everything works (since you tested it), it is time to make the **annotated** tag. Verify you are on the appropriate branch + commit, then tag it: - git tag -a 4.0.0 - git push - git push origin 4.0.0 +```shell +git tag -a 4.0.0 +git push +git push origin 4.0.0 +``` Where `4.0.0` is the name of the tag. @@ -107,7 +111,7 @@ Where `4.0.0` is the name of the tag. > The expected tag version format is: `()` > > Where `` is `#.#.#` (examples: `4.0.0`, `4.0.1`, `4.9.12`) -> +> > And the _optional_ `` is a hyphen-prefixed pre-release identifier + version like: `-beta1` or `-rc1` > > #### Valid tag examples: @@ -205,7 +209,7 @@ The release automation process will then: Post-Release checklist ---------------------- - [x] Add a new milestone to https://github.com/Warzone2100/warzone2100/milestones -- [x] Tell everyone about it in the forums. You can use the build_tools/changelog2bbcode.sh script to massage the changelog into BBCode. +- [x] Tell everyone about it in the forums. You can use the `build_tools/changelog2bbcode.sh` script to massage the changelog into BBCode. - [x] Send mail about it on the developer mailing list. - [x] Change the title on our IRC channels about the new release. - [x] Ask for a raise for doing all this work that nobody else wanted to do, and you got suckered into doing it. diff --git a/doc/Scripting.md b/doc/Scripting.md index 92a4e430641..e1cf1595e98 100644 --- a/doc/Scripting.md +++ b/doc/Scripting.md @@ -2,16 +2,16 @@ ## Introduction -Warzone2100 contains a scripting language for implementing AIs, campaigns and some of the game +Warzone 2100 contains a scripting language for implementing AIs, campaigns and some of the game rules. It uses JavaScript, so you should become familiar with this language before proceeding with this document. A number of very good guides to JavaScript exist on the Internet. The following hard-coded files exist for game rules that use this API: -* multiplay/skirmish/rules.js Default game rules - base setup, starting research, winning and losing. -* multiplay/script/scavfact.js Scavenger AI. This script is active if scavengers are. +* `multiplay/skirmish/rules.js` Default game rules - base setup, starting research, winning and losing. +* `multiplay/script/scavfact.js` Scavenger AI. This script is active if scavengers are. -For ordinary AI scripts, these are controlled using AI JSON files that are present in the ```multiplayer/skirmish``` +For ordinary AI scripts, these are controlled using AI JSON files that are present in the `multiplayer/skirmish` directory. Here is an example of such a file that defines an AI implemented using this API: ```json @@ -24,9 +24,9 @@ directory. Here is an example of such a file that defines an AI implemented usin } ``` -It references a '.js' JavaScript file that needs to be in the same directory as the '.json' file. +It references a `.js` JavaScript file that needs to be in the same directory as the `.json` file. -The code in a javascript file is accessed through specially named functions called 'events'. These are defined below. +The code in a JavaScript file is accessed through specially named functions called **events**. These are defined below. An event is expected to carry out some computation then return immediately. The game is on hold while an event is processed, so do not do too many things at once, or else the player will experience stuttering. @@ -36,12 +36,12 @@ bad things may happen. If you need to keep static arrays around, it is better to function, as they will then not be saved and loaded. One error that it is easy to make upon initially learning JavaScript and using this API, is to try to use -the 'for (... in ...)' construct to iterate over an array of objects. This does not work! Instead, use code +the `for (... in ...)` construct to iterate over an array of objects. This does not work! Instead, use code like the following: -```javascript +```js const droidList = enumDroid(me, DROID_CONSTRUCT); -for (let i = 0; i < droidList.length; i++) +for (let i = 0; i < droidList.length; ++i) { const droid = droidList[i]; ... @@ -54,35 +54,39 @@ The droid object that you receive here has multiple properties that can be acces These properties are read-only, and cannot be changed. In fact, objects that you get are just copies of game state, and do not give any access to changing the game state itself. -Any value written in ALL_CAPS_WITH_UNDERSCORES are enums, special read-only constants defined by the +Any value written in `ALL_CAPS_WITH_UNDERSCORES` are enums, special read-only constants defined by the game. ## Challenges -Challenges may load scripts as well, if a 'scripts' dictionary is present in the challenge file, and has the keys -"extra" or "rules". The "extra" key sets up an additional script to be run during the challenge. The "rules" -key sets up an alternative rules file, which means that the "rules.js" mentioned above is *not* run. In +Challenges may load scripts as well, if a `scripts` object is present in the challenge file, and has the keys +`extra` or `rules`. The `extra` key sets up an additional script to be run during the challenge. The `rules` +key sets up an alternative rules file, which means that the `rules.js` mentioned above is *not* run. In this case, you must implement your own rules for winning and losing, among other things. Here is an example of such a scripts section: ```json -"scripts": { - "rules": "towerdefense.js" +{ + "scripts": { + "rules": "towerdefense.js" + } } ``` You can also specify which AI scripts are to be run for each player. These must be given a path to the script, -since you may sometimes want them from the AI directory (```multiplay/skirmish/```) and sometimes from the challenge -directory (```challenges/```). If you do not want an AI script to be loaded for a player (for example, if you want -this player to be controlled from one of your challenge scripts), then you can give it the special value "null". +since you may sometimes want them from the AI directory (`multiplay/skirmish/`) and sometimes from the challenge +directory (`challenges/`). If you do not want an AI script to be loaded for a player (for example, if you want +this player to be controlled from one of your challenge scripts), then you can give it the special value `null`. Here is an example if a challenge player definition with its AI specified: ```json -"player_1": { - "name": "Alpha", - "ai": "multiplay/skirmish/nb_generic.js", - "difficulty": "Hard", - "team": 1 +{ + "player_1": { + "name": "Alpha", + "ai": "multiplay/skirmish/nb_generic.js", + "difficulty": "Hard", + "team": 1 + } } ``` @@ -92,7 +96,7 @@ Some objects are described under the functions creating them. The following obje multiple functions and widely used throughout, so it is better to learn about them first. Note the special term **game object** that is used in several places in this document. This refers -to the results of any function returning a Structure, Droid, Feature or Base Object as described below. +to the results of any function returning a **Structure**, **Droid**, **Feature** or **Base Object** as described below. Some functions may take such objects as input parameters, in this case they may not take any other kind of object as input parameter instead. @@ -102,15 +106,11 @@ Read more in depth about the following topics in their own pages. For newcomers, the order we recommended reading them in. If you do not intend to change the campaign (or write a new campaign), you can skip the campaign topic. -[Game objects](js-objects.md) - -[Events](js-events.md) - -[Globals](js-globals.md) - -[Functions](js-functions.md) - -[Campaign](js-campaign.md) +- [Game objects](js-objects.md) +- [Events](js-events.md) +- [Globals](js-globals.md) +- [Functions](js-functions.md) +- [Campaign](js-campaign.md) ## Gotchas / Bugs @@ -118,8 +118,8 @@ new campaign), you can skip the campaign topic. Due to a bug that is not so easy to fix in the short term, variables defined in global must be case insensitive. Otherwise, they may collide on savegame loading. This is only for variables defined in your script. There is no -need to maintain case insensitivity in regards to variables defined in global by the game itself, such as ```FACTORY``` -(you can safely define your own 'factory' variable) -- the only exception to this is ```me```. +need to maintain case insensitivity in regards to variables defined in global by the game itself, such as `FACTORY` +(you can safely define your own 'factory' variable) -- the only exception to this is `me`. ### Global objects @@ -145,7 +145,7 @@ adding a custom property. Note that this property will not be remembered when it ### Early research -You cannot set research topics for research labs directly from eventStartLevel. Instead, queue up a function +You cannot set research topics for research labs directly from `eventStartLevel()`. Instead, queue up a function call to set it at some later frame. ### Cyborg construction diff --git a/doc/build_tools/GenerateJSDocs.cmake b/doc/build_tools/GenerateJSDocs.cmake index 6c3bd268bab..40dd6a21ecc 100644 --- a/doc/build_tools/GenerateJSDocs.cmake +++ b/doc/build_tools/GenerateJSDocs.cmake @@ -94,6 +94,8 @@ function(PROCESS_LINES inputfile) endif() endfunction() +# js-globals.md + PROCESS_LINES("src/qtscript.cpp" MATCHING_LINE_REGEX "//==" STRIP_LINE_PREFIX_REGEX "== ?" @@ -104,11 +106,15 @@ PROCESS_LINES("src/wzapi.cpp" STRIP_LINE_PREFIX_REGEX "//== ?" OUTPUT_FILE "${OUTPUT_DIR}/js-globals.md" APPEND) +# js-events.md + PROCESS_LINES("src/wzapi.h" MATCHING_LINE_REGEX "//__" STRIP_LINE_PREFIX_REGEX "//__ ?" OUTPUT_FILE "${OUTPUT_DIR}/js-events.md") +# js-functions.md + PROCESS_LINES("src/wzapi.h" MATCHING_LINE_REGEX "//--" STRIP_LINE_PREFIX_REGEX "//-- ?" @@ -129,6 +135,8 @@ PROCESS_LINES("src/wzapi.cpp" STRIP_LINE_PREFIX_REGEX "//-- ?" OUTPUT_FILE "${OUTPUT_DIR}/js-functions.md" APPEND) +# js-objects.md + PROCESS_LINES("src/wzapi.h" MATCHING_LINE_REGEX "//[;][;]" STRIP_LINE_PREFIX_REGEX "//[;][;] ?" @@ -139,6 +147,8 @@ PROCESS_LINES("src/quickjs_backend.cpp" STRIP_LINE_PREFIX_REGEX "//[;][;] ?" OUTPUT_FILE "${OUTPUT_DIR}/js-objects.md" APPEND) +# js-campaign.md + PROCESS_LINES("data/base/script/campaign/libcampaign.js" MATCHING_LINE_REGEX ".*//[;][;]" STRIP_LINE_PREFIX_REGEX "//[;][;] ?" @@ -184,7 +194,6 @@ PROCESS_LINES("data/base/script/campaign/libcampaign_includes/nexus.js" STRIP_LINE_PREFIX_REGEX "//[;][;] ?" OUTPUT_FILE "${OUTPUT_DIR}/js-campaign.md" APPEND) - PROCESS_LINES("data/base/script/campaign/libcampaign_includes/production.js" MATCHING_LINE_REGEX ".*//[;][;]" STRIP_LINE_PREFIX_REGEX "//[;][;] ?" @@ -215,7 +224,6 @@ PROCESS_LINES("data/base/script/campaign/libcampaign_includes/transport.js" STRIP_LINE_PREFIX_REGEX "//[;][;] ?" OUTPUT_FILE "${OUTPUT_DIR}/js-campaign.md" APPEND) - PROCESS_LINES("data/base/script/campaign/libcampaign_includes/truck.js" MATCHING_LINE_REGEX ".*//[;][;]" STRIP_LINE_PREFIX_REGEX "//[;][;] ?" diff --git a/docker/Readme.md b/docker/Readme.md index 0f964ef8ee8..c16f31bdb00 100644 --- a/docker/Readme.md +++ b/docker/Readme.md @@ -4,20 +4,20 @@ In the root of the WZ repo: - `docker build -f docker//Dockerfile -t .` For example: -``` +```shell docker build -f docker/ubuntu-20.04/Dockerfile -t ubuntu . ``` For more information, see the documentation on [`docker build`](https://docs.docker.com/engine/reference/commandline/build/). -# How to build Warzone using the docker image: +# How to build Warzone 2100 using the docker image: Beware of line ending mismatch between Windows and Linux when cloning repo. ### Ubuntu - via CMake -``` +```shell docker run --rm -v $(pwd):/code cmake '-H.' -Bbuild -DCMAKE_BUILD_TYPE=Debug -G"Ninja" docker run --rm -v $(pwd):/code cmake --build build ``` @@ -25,7 +25,7 @@ docker run --rm -v $(pwd):/code cmake --build build ### Cross-compile (for Windows) - via CMake -``` +```shell docker run --rm -v $(pwd):/code i686-w64-mingw32.static-cmake '-H.' -Bbuild -DCMAKE_BUILD_TYPE=Debug -G"Ninja" docker run --rm -v $(pwd):/code cmake --build build --target package ``` diff --git a/macosx/README.md b/macosx/README.md index 67930f8ddd7..a82df7cf49a 100644 --- a/macosx/README.md +++ b/macosx/README.md @@ -1,4 +1,4 @@ -# Building Warzone for macOS +# Building Warzone 2100 for macOS ## Prerequisites: