Add documentation and example for getting started

README.md

@@ -68,6 +68,10 @@ You now run `make` manually or use `./scripts/make_release.sh` or `./scripts/mak
 
 The resulting binaries can be found in `build/bin/<Debug_x86|Release_x86>`.
 
+## Using the tools
+
+For information about how to use the tools see the ["Getting started" guide](docs/GettingStarted.md)
+
 ## Legal
 
 OAT source code is licensed under [GPLv3](./LICENSE).

docs/GettingStarted.md

@@ -0,0 +1,43 @@
+# Getting started
+
+## Unlinking a fastfile
+
+A good starting point is dumping an existing zone from your game installation to get a glance at how the raw asset data is structured.
+The `Unlinker` tool will create a dump of a fastfile that can be linked again in the same form with the `Linker` tool.
+
+The `Unlinker` tool can be used the following:
+```shell
+# Load the original zone from the game folder.
+# Change this if you have installed your game somewhere else
+GAME_FOLDER='C:/Program Files (x86)/Steam/steamapps/common/Call of Duty Modern Warfare 3'
+
+# Verbose mode logs more details which can be useful to find errors
+ARGS='--verbose'
+
+# Specify the search-path to include the main folder to automatically load its IWD files for image dumping.
+# For T6 also specify sounds;zone/all;zone/english to load appropriate IPAKs and sound banks.
+# You can skip specifying the search path but it will not dump images then.
+ARGS="$ARGS --search-path \"$GAME_FOLDER/main;$GAME_FOLDER/zone/english\""
+
+ZONE_TO_UNLINK="$GAME_FOLDER/zone/english/ui.ff"
+
+Unlinker $ARGS "$ZONE_TO_UNLINK"
+```
+
+The variables are only to better demonstrate the different parameters.
+You can also of course combine them:
+
+```shell
+Unlinker --verbose "C:/Program Files (x86)/Steam/steamapps/common/Call of Duty Modern Warfare 3/zone/english/ui.ff"
+```
+
+When using Windows you can also drag and drop a fastfile onto `Unlinker` which will run the unlinking tool with just the fastfile path and no additional parameters.
+
+After `Unlinker` ran successfully, you will have a `zone_dump` folder in your working directory.
+It contains another folder `zone_raw` which contains the definitions for the unlinked fastfiles.
+You can move the project definitions one level up in the folder structure to be able to use them with the `Linker` tool.
+That means `zone_dump/zone_raw/ui` becomes `zone_raw/ui`
+
+## Extending a vanilla fastfile
+
+For an example of extending a fastfile, see [the example "ExtendZone"](example/ExtendZone).

docs/example/ExtendZone/build.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+# Load the original zone from the game folder.
+GAME_FOLDER='C:/Program Files (x86)/Steam/steamapps/common/Call of Duty Modern Warfare 3'
+
+# Load the original zone into the Linker to be able to use its assets from in-memory.
+# If you want to overwrite the vanilla zone later
+Linker --load "$GAME_FOLDER/zone/english/ui.ff" ExtendZoneProject

docs/example/ExtendZone/ui/menu_custom.menu

@@ -0,0 +1,126 @@
+{
+    menuDef
+    {
+        name                        "menu_custom"
+        fullscreen                  1
+        rect                        0 0 640 480 0 0
+        style                       1
+        focuscolor                  1 1 1 1
+        onOpen
+        {
+            focusFirst;
+        }
+        onESC
+        {
+            close menu_custom;
+        }
+        itemDef
+        {
+            text                        "abcdefghijklmnopqrstuvwxzy ABCDEFGHIJKLMNOPQRSTUVWXYZ !@#$%^&*(){}~`/=\-',;"
+            rect                        10 10 150 50 1 0
+            decoration                  
+            type                        20
+            border                      1
+            visible                     1
+            textscale                   0.375
+            textfont                    5
+            forecolor                   1 1 1 0.5
+            bordercolor                 0 1 1 0.5
+            speed                       10
+        }
+        itemDef
+        {
+            text                        "a long and narrow ticker, at 40 units per second. !@&#(?"
+            rect                        200 10 250 25 1 0
+            decoration                  
+            type                        20
+            border                      1
+            visible                     1
+            textscale                   0.375
+            textfont                    4
+            forecolor                   1 0 1 0.5
+            bordercolor                 0 1 1 0.5
+            speed                       40
+        }
+        itemDef
+        {
+            text                        "abcdefghijklmnopqrstuvwxzy ABCDEFGHIJKLMNOPQRSTUVWXYZ !@#$%^&*(){}~`/=\-',;"
+            rect                        10 70 150 50 1 0
+            decoration                  
+            type                        20
+            border                      1
+            visible                     1
+            textscale                   0.4583
+            forecolor                   1 1 1 0.5
+            bordercolor                 0 1 1 0.5
+            speed                       20
+        }
+        itemDef
+        {
+            text                        "Big Texted News Ticker.  20 units per second."
+            rect                        200 70 150 50 1 0
+            decoration                  
+            type                        20
+            border                      1
+            visible                     1
+            textscale                   0.5833
+            forecolor                   1 1 1 0.5
+            bordercolor                 0 1 1 0.5
+            speed                       20
+        }
+        itemDef
+        {
+            text                        "A short ticker with a bunch of text."
+            rect                        10 130 50 50 1 0
+            decoration                  
+            type                        20
+            border                      1
+            visible                     1
+            textscale                   0.375
+            textfont                    6
+            forecolor                   1 1 1 0.5
+            bordercolor                 0 1 1 0.5
+            speed                       10
+        }
+        itemDef
+        {
+            text                        "<>@#$%^&*()\tA ticker with no borders.       And many spaces.           $%^13"
+            rect                        70 130 500 25 1 0
+            decoration                  
+            type                        20
+            visible                     1
+            textscale                   0.375
+            textfont                    3
+            forecolor                   1 1 1 0.5
+            spacing                     10
+            speed                       35
+        }
+        itemDef
+        {
+            text                        "Color Test: ^1Red ^2Green ^3Yellow ^4Blue ^5Cyan ^6Magenta ^7White"
+            rect                        10 220 500 25 1 0
+            decoration                  
+            type                        20
+            border                      1
+            visible                     1
+            textscale                   0.375
+            forecolor                   1 1 1 0.5
+            bordercolor                 0 1 1 0.5
+            speed                       50
+        }
+        itemDef
+        {
+            rect                        10 190 500 25 1 0
+            decoration                  
+            type                        20
+            border                      1
+            visible                     1
+            textscale                   0.375
+            forecolor                   1 1 1 0.5
+            bordercolor                 0 1 1 0.5
+            spacing                     30
+            speed                       50
+            newsfeed                    1
+        }
+    }
+}

docs/example/ExtendZone/ui/mod.txt

@@ -0,0 +1,9 @@
+{
+    functionDef
+    {
+        name                        "FUNC_0"
+        value                       (player("teamname") == "TEAM_ALLIES");
+    }
+
+    loadMenu { "ui/menu_custom.menu" }
+}

docs/example/ExtendZone/zone_source/ExtendZoneProject.zone

@@ -0,0 +1,14 @@
+// Set the game to "Call Of Duty: Modern Warfare 3"
+>game,IW5
+
+// Overwrite the name of the zone to be "ui"
+>name,ui
+
+// Add custom assets
+material,,clanlvl_box
+material,,xp
+material,,gxp
+menulist,ui/mod.txt
+
+// Include the assets of the original zone
+include,ui