Modding

Modding Guide

NOTE: This documentation is ongoing. For additional information and tips see our forums, as well as the older STUB wikis Here or Here.

The Basics

You will create all your mods inside their own 'campaign', a folder which holds all your maps, scripts, or other custom files - or alternatively as a global mod in the MODS folder. At no point should you alter the main game files. This will likely cause you to either not be able to play multiplayer, or cause multiplayer games to behave incorrectly. It is also likely to cause problems when the game updates.

Creating a Mod

Globals mods currently support skinning, and a custom squads file. To use mods, you must first create a MODS folder in your local folder (e.g. My Documents/My Games/Sanctus). Then create a named folder for each mod (no spaces!). You can place a modded SQUADS.CSV in the root of your mod folder, this will always replace the in-game version, so generally you should copy the main game file and then edit it as desired. You may have as many mods installed as desired, but only one (or, of course, none) can be active at any time.

.../MODS/MYMOD/SQUADS.CSV

To apply skins to units you would create a UNITTEXTURES folder to mirror the one in the main game data

.../MODS/MYMOD/DATA/BATTLE/UNITTEXTURES

You can then place modded unit textures into this folder and they will be used ingame. Note that the code will attempt to load these textures even for saved games, to allow you to switch skins.

Note that some other textures are skinnable, if their folder paths are duplicated. The skinability of other textures depends on a variety of internal code factors, including how the code searches for an uses the textures. But it can never hurt to try!

Creating a Campaign

The simplest way to start modding is to select the Editor from the main menu, enter names for your campaign, and then use the editor to build a map. You will then be able to select your campaign from the Campaign Screen, and then choose which of your maps to play.

TIP:Select the Plugins list in the editor, and choose the Random Map Plugin. This will create random maps for you in the editor, which you can then populate with units. It's a quick way to get started!

Once you have a campaign, you can then begin to add other functionality, up to and including your own mission scripts, AI logic, UI screens, or even new 3D objects.

In a simple Campaign, the order in which scenarios appear on the scenario selection screen is not defined.

Advanced Campaigns

If you want to control the order in which scenarios are listed, set up custom text for scenarios, or customise any other aspects of the game when playing your scenarios, you will need to edit additional files. Editing these files is easy, and their contents are explained below.

CAMPAIGN.TXT

This file denotes the order of any campaigns that are included on the scenario selection screen. Note that if this file does not exist, then the game will attempt to use all the scenarios in the SCENARIOS directory.

The form of the file is simply:

[Scenario1]
[Scenario2]

Where the scenario names are the filenames of your user scenarios. So in this case you would have Scenario1 and Scenario2 BAM files from the editor.

Custom Text

You can have multiple text files inside the campaign directory. They must all be named TEXT<N>.TXT where N can be any number from 0 to 63. For example text0.txt or text12.txt.

These text files must be UNICODE files, and so support non-ASCII characters [Note: you may need to use applicable fonts to allow the display of non-ASCII characters].

Notepad++ easily allows you to save UNICODE files, as do most standard text editors.

The format of these (and all) strings files is:

<stringTag>, “<string>”,

The commas are important! Note that to insert a newline into a string, you need to use the ~ character.

Strings used by the game are:

IDS_CAMPAIGN_NAME, “The campaign name shown on the campaign selection screen”,
IDS_SCENARIO_DESC_<scenarioName>, “one string per scenario, shown over the scenario selection display if there is no custom UI for the scenario (see below)”, 
IDS_CAMPAIGN_TEXT, “Text describing the campaign, shown on the campaign selection screen if there is no custom UI”,

Some of these strings are set up for you when you create the campaign, others you can add if you want to have more customised text shown when people play your campaign.

Campaign Graphics

There are two files you can create to customise the look of your campaign. These files can be in either TGA or DDS (recommended) format. If either of these files are not defined, then the game uses some default images. 1024×1024 or 512×512 are usual sizes for these two images.

BACKDROP.DDS (or TGA) This file is used as the backdrop behind your scenarios after you select your campaign to play.

ICON.DDS (or TGA) Shown on the campaign selection screen.

Campaign Scripts

If you create a CAMPAIGN.BSF script file, then it will enable you to have campaign-level logic which you can then deal with within your battles.

Campaign scripts make use of campaign variables, which are special global variables defined in the CAMPAIGN.TXT file. To define a campaign variable, you need to add a line of the form:

VAR <name>

for example

VAR TotalKills

You can then use the SetCampaignVar and GetCampaignVar commands any scripts that you use, including any campaign script. You are limited to 64 campaign variables, although each one can be accessed as an array of 8 entries (see the documentation for Get/SetCampaignVar for more details). NOTE: This has now been superceded by the use of global singleton variables in the script - that is, any globals defined in the campaign script will be saved and loaded during the campaign playthrough, and so are a simpler way to save campaign logic data.

Campaign Script Callbacks

Many times we want to be able to respond to events from within the game. The game uses callback function to do this. These are specifically named functions which are passed information by the game.

You can define certain campaign functions which will be called when specific actions happen in the game. They are:

// Called whenever a unit is destroyed.
FUNCTION KILL_CALLBACK(side, id)
 
// called every time a campaign is loaded up.   
// Note:  Not just when a new campaign is started.
FUNCTION INIT_CAMPAIGN()

Summary

You can create your own campaigns entirely from within the game, but you can also create custom text and images to change the look of your campaign. You can also create custom UI, animated briefings, custom units, and even give units entirely different behaviors!

Scenarios

Without a special script, a scenario will end once all of the enemy's units are destroyed. But a scenario script allows you to have much finer control of the course of a battle.

The Scenario Script

The scenario script interacts with the mission through a number of callback functions.

Tick

// Called every tick
FUNCTION TICK( side )

This callback is called every tick of the model (30 times a second). The side is the side currently having its turn. Use this function to track ongoing events, like the death of units, or movement of the enemy.

StartTurn

// Called at the beginning of each turn
FUNCTION STARTTURN( side, mode )

At the start of each new turn, this function is called. The mode parameter describes the type of game in progress (e.g. single player, PBEM, etc), and is generally not needed. Use this function to trigger events based on the turn.

Note that this function is called once per turn, and the sequence of turns is as follows:

-1	: This is a pre-turn called when a scenario is first begun
 0	: First turn for side 0
 1	: First turn for side 1
 2	: Second turn for side 0
 3	: Second turn for side 1
 4	: etc

StartTurnPost

// Called after all the default start turn logic has been done
FUNCTION STARTTURNPOST( side, mode )

After the StartTurn function is called, there is other internal logic which occurs (for example, updating the APs for each unit, and calling any unit script functions). This function can be used optionally to make changes once all the normal logic and value resets are done. And example is altering the default sight ranges, or number of APs a unit has.

Win_Scenario_Callback

// Called each tick.   Can determine whether there is a winner for the scenario.
FUNCTION WIN_SCENARIO_CALLBACK( winner )<//nowiki>
This callback if called every tick provided no winner has been selected. The code passes in the side it thinks is the winner (-1 for no winner yet). It returns a new winner value. 0 or 1 for a winning side, and -1 for no winner. Thus it can prevent the default game logic from ending a battle should it need to.

Note that this function is no longer called once a winner is set in any way (e.g. through the EndBattle command).

====DrawScenarioUI====
 <nowiki>// Called every frame to render out any scenario specific UI
FUNCTION DRAWSCENARIOUI()

You can use this function to render any custom UI which your scenario might desire. Examples would be tracking achievements, showing a turn countdown if there is a limit in the mission. But it could be anything you like using the UI script commands (see the list of script commands in the autodocs).

Note that this display can be disabled by the user using the toggle which appears just below the Exit Battle button whenever this function is defined in the scenario.

File Layout Guide

MYCAMPAIGN
│   backdrop.dds
│   Campaign.txt
│   icon.dds
│   sides.txt
│   Squads.csv
|   ArmyList.txt
│   Terrain.txt
│   text1.txt
│   uniticons.dds
│
├───AI
│       AI.bsf
│
├───ANIM
│       MyAnim.s3f
│
├───BONUS
│       MyBonus.BSF
│
├───DATA
│   │   music.txt
│   │   sfx0.txt
│   │
│   ├───BATTLE
│   │   ├───SCRIPTS
│   │   ├───UNITS
│   │   │       MyUnit.txt
│   │   │       MyUnit_0.s3f
│   │   │
│   │   └───UNITTEXTURES
│   ├───MUSIC
│   ├───SOUNDS
│   └───UI
│       │   Campaign_Overlay.txt
│       │   EndCamp.txt
│       │   SCENUI_MyScenario.txt
│       │
│       └───TEXTURES
│           │   CampaignListIcon.dds
│           │
│           └───ICONS
│                   MyUnit.dds
│                   MyUnit_SLOT.dds
│
├───OBJECTS
├───TILES
├───SCENARIOS
│       MyScenario.bam
│       MyScenario.bsf
│       MyScenario.dds