Mission reference
Folder structure
Events
Actions
Numeric Constants
The folder structure is frankly easy. The following explains each folder and it's use.
| Level 1 | Level 2 | Level 3 | Desription |
|---|---|---|---|
| CAMPAIGN | This is the base folder containing all campaigns shown in the campaign screen | ||
| Folder | This is the folder that contains all files for an campaign. The folder name is also the campaign display name. Do not use spaces but instead underscores, they are replaced in the game. | ||
| Description.dat | This file contains the description shown for your campaign. You have 12 lines with 27 characters each. Only the first 12 lines are read | ||
| Mapfile.smf | This is a mapfile. Missions are ordered by name, thats why you should prefix them with numbers. The first 3 letters of every mapfile are removed when loading them. Do not use spaces, use underscores instead, they are replaced in the game. | ||
| Mapfile.msf | This is a map script file. They need to have the same name as the corresponding map. |
For the example:
| Level 1 | Level 2 | Level 3 | Desription |
|---|---|---|---|
| CAMPAIGN | Basefolder | ||
| AN_EXAMPLE | Campaignfolder. Resulting in the name "An Example" ingame | ||
| Description.dat | Contains the description shown when the campaign is selected | ||
| 01_THE_BEGINNING.smf | This is the first map shown in the selection screen. It's shown as "The Beginning" | ||
| 01_THE_BEGINNING.msf | This is the scriptfile loaded for the map 01_THE_BEGINNING.smf | ||
| 02_TO_BATTLE.smf | This is the second map shown in the selection screen. It's shown as "To Battle" | ||
| 02_TO_BATTLE.msf | This is the scriptfile loaded for the map 02_TO_BATTLE.smf | ||
| 03_SWEET_HOME.smf | This is the third map shown in the selection screen. It's shown as "Sweet Home" | ||
| 03_SWEET_HOME.msf | This is the scriptfile loaded for the map 03_SWEET_HOME.smf |
Events are triggered by different actions. Some may be just happen while a round is in progress, others may occur at the end of a round. Be warned, you may create situations where two events are triggered at the end of a round.
ON_ARMY_AT
This event is triggered when an army is moved to a specific point. This is mostly used for victory conditions.
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
| PlayerID | This is the ID of the player reaching that point | 1 |
| X | This is the X-position | 10 |
| Y | This is the Y-position | 10 |
ON_ARMY_BATTLE
This event is triggered whenever 2 armies battle each other. This also omits the combat result display (if enabled).
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
| PlayerID1 | This is the ID of one of the combatants. May also be -1 for any | 1 |
| PlayerID2 | This is the ID of the other combatant. May also be -1 for any | 2 |
| WinnerID | This is the ID of the winner. May also be -1 for any | 1 |
ON_ARMY_RAISED
This event is triggered whenever a player raises an army and has the required number of armies.
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
| PlayerID | ID of the player who raised hat army | 1 |
| SumArmies | Number of armies the player needs. Use -1 for any | 2 |
ON_BUILDING_ATTACKED
This event is triggered whenever a player attacks a building.
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
| PlayerID | ID of the player who is attacked | 2 |
| BuildingID | ID of the building that is attacked. Use -1 for any | -1 |
| AttackerID | ID of the player who attacked the building. Use -1 for any | -1 |
ON_BUILDING_COUNT
This is triggered whenever a player has finished a specific amount of buildings.
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
| PlayerID | ID of the player who needs the building count | 1 |
| BuildingID | ID of the building that needs a specific count | 1 |
| CountDone | Amount of buildings needed | 2 |
ON_BUILDING_LOST
This event is triggered whenever a player loses a building.
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
| PlayerID | ID of the player who lost a building. Use -1 for any | 1 |
| BuildingID | ID of the building that is lost. Use -1 for any | -1 |
| AttackerID | ID of the player who destroyed the building. Use -1 for any | -1 |
ON_BUILDING_PLACED
This event is triggered whenever a player places a new building site.
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
| PlayerID | ID of the player who needs the building site | 1 |
| BuildingID | ID of the building that needs to be placed | 1 |
ON_ENEMY_DEFEATED
This event is triggered whenever a player is defeated.
Note: This event is not implemented yet! Open an issue if you need this.
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
| PlayerID | ID of the player who is defeated. Use -1 for any | 1 |
| isLast | Should there be any players left? O = no, any other = yes | 0 |
ON_EVENTS_MET
This event is triggered whenever 2 events have been triggered. That way you can chain together multiple events.
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
| EventID1 | This is the first event that needs to be triggered | 1 |
| EventID2 | This is the second event that needs to be triggered | 2 |
ON_LOAD_GAME
This event is triggered when loading a game.
Note: Saving and loading is not implemented!
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
ON_LOAD_GAME
This event is triggered when the map is loaded.
Note: This event should only trigger setting events, any other event may result in unexpected behavior or crashes!
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 0 |
| ActionGroup | This is the action group that is excecuted | 0 |
ON_ROUND
This event is triggered when a specific round starts.
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
| RoundNo | Number of the round at which this event should be triggered | 3 |
ON_START
This event is triggered when the the game starts the first time, not if it's loaded.
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
ON_TILE_CLICKED
This event is triggered when the player clicks on a specific tile.
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
| X | X-position of the tile | 10 |
| Y | Y-position of the tile | 10 |
ON_WARE_AMOUNT
This event is triggered whenever a specific amount of ware is exceeded.
Note: This event is not triggered yet. Open an issue if you need this event.
| Parameter | Description | Example |
|---|---|---|
| EventID | This is your ID for referencing this event | 1 |
| ActionGroup | This is the action group that is excecuted | 1 |
| PlayerID | This is the ID of the player | 1 |
| WareID | This is the ID of the ware | 1 |
| RequiredAmount | The amount needed | 100 |
Actions are actions that can be taken uppon events. Every action has an action group assigned as first parameter. This one is used as external ID which you can use for reference.
ADD_ARMY
This function adds an army for any player. Please note that you have to provide valid player IDs and a valid combination of set armies.
| Parameter | Description | Example |
|---|---|---|
| ActionGroup | This is your ID for referencing this group | 1 |
| PlayerID | This is the ID of the player this army is added for. Uses values from 1 (human) to 4 | 1 |
| Rank | This indicates weather the army has a melee division or not. Use 0 for no, 1 for yes | 0 |
| X | X-Position the army should be added | 5 |
| Y | Y-Position the army should be added | 5 |
ADD_BUILDING
This function adds a building for any player. Please note that you have to provide valid player IDs and a valid value for the state.
| Parameter | Description | Example |
|---|---|---|
| ActionGroup | This is your ID for referencing this group | 1 |
| PlayerID | This is the ID of the player this army is added for. Uses values from 1 (human) to 4 | 1 |
| BuildingID | This is the numeric ID for building, see reference for further information | 3 |
| State | This indicates the state of the building. Any value < 0.0 results in 0.0, any value > 1.0 results in a a finished building | 0.3 |
| X | X-Position the building should be added | 5 |
| Y | Y-Position the building should be added | 5 |
ADD_WARE
This function adds a wares for any player. Please note that you have to provide valid player IDs and a valid value for the ware.
| Parameter | Description | Example |
|---|---|---|
| ActionGroup | This is your ID for referencing this group | 1 |
| PlayerID | This is the ID of the player this army is added for. Uses values from 1 (human) to 4 | 1 |
| WareID | This is the ID of the ware that should be added, see reference for further information | 1 |
| Amount | This is the numeric amount of a ware that should be added | 100 |
GAME_LOSE
This function shows the lose window. It's not possible to continue the game after!
| Parameter | Description | Example |
|---|---|---|
| ActionGroup | This is your ID for referencing this group | 1 |
GAME_WIN
This function shows the win window. It's possible to continue the game after.
| Parameter | Description | Example |
|---|---|---|
| ActionGroup | This is your ID for referencing this group | 1 |
SET_EVENT_STATE
This function can be used to set an event state. You can either enable or disable an event. If an event state is actually changed, the ON_EVENTS_MET event is checked and possibly triggered!
| Parameter | Description | Example |
|---|---|---|
| ActionGroup | This is your ID for referencing this group | 1 |
| EventID | This is the ID you set for the event | 12 |
| State | This is the state the event should have. Use 0 for disabled and 1 for enabled | 0 |
SET_FOW
This function is used to toggle the Fog of War state.
Note: Enabling should be done in ON_LOAD_MAP only, disabling is always save
| Parameter | Description | Example |
|---|---|---|
| ActionGroup | This is your ID for referencing this group | 1 |
| FowState | A value of 0 disables Fog of War, any other value enables it | 1 |
SET_NAME
This function changes the name of a player.
| Parameter | Description | Example |
|---|---|---|
| ActionGroup | This is your ID for referencing this group | 1 |
| PlayerID | This is the ID of the player the name is changed. Uses values from 1 (human) to 4 | 2 |
| Name | This is the new name of the player. | The enemy |
SET_WARE
This function sets the ware amount of the player ignoring any current stock.
| Parameter | Description | Example |
|---|---|---|
| ActionGroup | This is your ID for referencing this group | 1 |
| PlayerID | This is the ID of the player the name is changed. Uses values from 1 (human) to 4 | 2 |
| WareID | This is the ID of the ware that should be added, see reference for further information | 1 |
| Amount | This is the numeric amount of a ware that should be set | 55 |
SHOW_TEXT
This function shows a text window to the player. It has 12 lines with up to 67 characters. If the window is to narrow, multiple pages will be shown. Linebreaking is done automatically, but you can also use " \n " (with leading and tailing spaces) to force a linebreak.
| Parameter | Description | Example |
|---|---|---|
| ActionGroup | This is your ID for referencing this group | 1 |
| Text | This is the text that is shown | I'm showing a nice text here, \n \n \n \n but I like 4 new lines as well! |
The game uses numeric values for building IDs and for ware IDs which you can find in the following tables.
Ware IDs
| Value | Description |
|---|---|
| <1 | Invalid! |
| 1 | Gold |
| 2 | Wood |
| 3 | Food |
| >3 | Invalid! |
Building IDs
| Value | Description |
|---|---|
| <0 | Invalid! |
| 0 | HQ |
| 1 | HOUSE_SMALL |
| 2 | HOUSE_MEDIUM |
| 3 | HOUSE_LARGE |
| 4 | FARM |
| 5 | FIELD |
| 6 | WELL |
| 7 | MINE |
| 8 | SAWMILL |
| 9 | BARRACKS |
| 10 | ARCHERRANGE |
| 11 | Stable |
| 12 | TOWER |
| >12 | Invalid! |
Player IDs
| Value | Description |
|---|---|
| <1 | Invalid! |
| 1 | Human player |
| 2 | AI#1 |
| 3 | AI#2 |
| 4 | AI#3 |
| >4 | Invalid! |
State
| Value | Description |
|---|---|
| <=0.0 | Set to 0% |
| 0.0 < n < 1.0 | Percent of the building state |
| >=1.0 | Set to done |
