CAOS Modding Guide

This guide is intended to provide an introduction to modding CAOS, explain the data and assets, and provide a basic overview of how to modify your game.

Overview

This guide will provide an introduction to modding CAOS, explain the data and assets, and provide examples to help you create you own content.

We will start with an overview of the current modding possibilities and limitations.

What can you do?

• Change stats for any weapon or equipment in the game.
  
• Change the composition and strength for any unit in the game.
  
• Change scenario settings, such as: randomization parameters, turn length, and point options, and battle grouping, and engineering restrictions.
  
• Change ai strategy and requisition parameters.
  
• Change or replace any graphical assets in the game, including counters, cursors, order indicators, flags, backgrounds, and UI graphics etc.
  
• Change sound files.
  
• Change, add, or replace music.

What can’t you do?

• You cannot currently add new maps.
  
• You cannot currently add new orders of battle.
  
• You cannot currently add new scenarios, although you can modify existing ones.

Getting Started

Mods for CAOS can be uploaded to the Steam Workshop directly from the options menu in game.

To create a mod for CAOS begin by locating the mod folder, you will place the required files for you mod here. Note that you will need to run the game at least once after installing CAOS, to create this folder.
Users\Username\AppData\Local\CAOS\mods


A mod for CAOS consists of three components. First, a .mod file, such as “Example.mod.” This file contains the title, description, tags, and relative file paths for uploading you mod. Second, a 1Mb or smaller picture in .jpg or .png format used as a picture for the mod on the Workshop, for example “Example.png”. Third, a folder with the game files to be uploaded.

Once the core mod files have been uploaded through the game, and a file id has been established by Steam, you can access your mod from the your files section of the CAOS workshop page. There you can manage your mod, change it's visibility settings, upload additional pictures, or videos, and write more detailed descriptions.

An example mod template for CAOS can be found here:
https://www.ns2games.com/Mod_Example.zip
An second example, showing the file structure for a scenario mod can be found here:
https://www.ns2games.com/Mod_Example_Scenario.zip

Creating A Mod

After locating the CAOS\mods directory create a text file and rename it “modname.mod.” Copy the following lines of code into this file and make any required changes for you mod.

//This is a mod upload template
//This file should be placed in the App Data CAOS\mods directory found in the application data folder. 

//The title of your mod - Steam Workshop titles are limited to 128 bytes.
Title=Mod_Name

//A short description of your mod - Steam Workshop titles are limited to 8000 bytes. You can edit this later from the steamworks mod page.
Description=Mod description .

//Search tags - limited to 255 characters Can only include printable characters, excluding ',' 5 tags maximum.
Tags=Example,Test

//Picture to use as the preview image for this mod. Must be a JPG, PNG or GIF and must not exceed the maximum size of 1MB. This file should be placed in the CAOS\mods directory found in the application data folder. 
Picture=Mod_Name.png

//File name for this mod. CAOS\mods directory found in the application data folder. This directory contains the files your mod will upload
Directory=Mod_Name

//Change notes
Notes=Version 1.0 

Second, create a .png or .jpg file less than 1 Mb in size in the CAOS\mods directory and set the Picture= line in the .mod file to this file name. This will be the cover image for you mod. You can change it later from the Steamworks page for your mod.

Third, create a content directory for you mod in the CAOS\mods directory and place all of your mod files (discussed below in detail) into this directory. Finally, update the Directory= line in the .mod file to the name of the mod content directory.

Fourth, create a Mod_Title.txt file and place it in the content directory for you mod. Place the name of you mod, for example, “Example Mod” in this file. This title will be used in the mod list in game to identify your mod.

Once these steps are complete launch CAOS, click “options” and press the “upload” button, a file explorer prompt will appear. If the file browser does not immediatly popup try pressing the Windows key, or Alt-Tab, it may open behind the game application on some computers. Select the .mod file for you mod. An uploading screen will appear, and your mod will then be uploaded to the Steam Workshop. This may take a few seconds.

Mod Files

Warning! Although it is possible to modify the base game files, these changes can be overwritten by game updates. Instead place copies of your modified files into the content directory for you mod. Mod files will automatically replace or update base files when the game is run.

Mod File Examples

Warning! We recommend using Notepad++ to make changes to CAOS data files. Windows notepad may be used, but files must be saved in UTF-8 encoding or they may crash the game.

Units

When you open a unit in game in CAOS, each attachment that you see has a corresponding definition type defined in the arsenal files, usually representing a battalion or company. The strength and stats of attachments can be modified by changing the appropriate file in CAOS\Data\arsenal. The unit_defenitions.ini contains this information for every company type in the game.

This is a commented example from a US mechanized battalion in 1942:

[US Mech. Infantry Bn 42]
cohesion=1                                   The starting cohesion 0.01 - 1
max_movment_points=15.01       The movement rate 9/12/15, add .01 if force march capable 
morale=1                                       The training level of this formation .7 - 1.3 
stack_weight=.9                            The stacking weight of this formation.
strength1=18                                 Strength of the nth weapon slot
strength2=11
strength3=12
strength4=3
strength5=3
type=mechanized                          Formation type
counter=mechanized                     map counter to display
size=Bn                                         formation size
wep1=US Mech. Inf '42                 equipment defined in weps.ini
wep2=US Mech. MG '42
wep3=37mm Gun M3 '42
wep4=T30 75mm HMC '42
wep5=M4 Mortar Carrier '42
card=mechanized                          The graphical card to display behind this information when the unit is opened in game.[/b]

You can change the stats for any attachment type, altering how they perform in game: how many of what type of equipment are in each, how far they move, and the attachments type. You cannot add new attachments, because the attachment types are defined by the orders of battle data files. However, you can alter any existing attachment in any way you want. For example, changing the number, or type of tanks a unit contains, of modifying a unit type to be over, or under strength. Any definitions you change in your mod will be loaded after the base game data, and supersede it. You only need to include entries that you change in your mod.

Weapons

Weps.ini: CAOS\Data\arsenal

The weapons file defines the combat values for each strength point in an attachment. The wep[1-5] entry in the unit_defenitions.ini is coupled with an entry in the weps.ini file. You can modify or add new weapon entries and assign them to definitions.

[Pz. IV F2 '42]             The name of the equipment used in a wep1-5 slot in definitions.
off_combat=6.9           The offensive combat value of this equipment.
def_combat=6.9          The defensive combat value of this equipment.
low_anti_air=0             low altitude AAA value.
med_anti_air=0           medium altitude AAA value.      
high_anti_air=0           high altitude AAA value.                
anti_armor=8.8            Anti-tank value.
armor_defence=4.2     Armor protection value.
fire_res=27                  Resilience of this unit in armored combat 1-100
skirmish=-.05               Modification to combat values when skirmishing.
breakdown=.15            Probability of breakdown when moving.
Nat=German                Nationality
counter=armor             Counter to display on weapon card.

Any equipment you change in your mod will be loaded after the base game data, and supersede it. You only need to include entries that you change in your mod.

Air Units

air_unit_defenitions.ini: CAOS\Data\arsenal

The air units definitions file contains the combat missions and stats for air units in CAOS. You can modify the number of missions each unit can provide, as well as their weapons stats, and cohesion regain rates.

[P-39N Airacobra 42]             //equipment name
superiority=2                          //maximum number of air superiority missions provided.
interdiction=2                        //maximum number of interdiction missions provided.
bombing=0                           //maximum number of bombing missions provided.                          
support=0                            //maximum number of close support missions provided.
strike=1                               //maximum number of strike missions provided.
recon=0                               //maximum number of recon missions provided.
wep_stat=49.7                    //weapon stat used by this unit.
cohesion_regain=.3            //cohesion regain rate when resting.

You cannot add or remove air units from the existing orders of battle, but you can change any of their values.

AI

AI: CAOS\Data\ai

You can change the strategy used by the AI when purchasing units in each game mode. The required ai strategies are located in CAOS\Data\ai\strategies. This file has two parts, the first section defines the available strategies for each game type. Each of these strategies is then defined below. If multiple strategies are defined for a given game type the ai will randomly select between them. Each nation has a based generic strategy, and order of battle specific strategies. The game will look for an OB specific strategy first, and then a national default second.

Skirmish
{
	offensive:armor1
	defensive:inf2
	general:inf1
	general:wildcard1
}

Meeting
{
	general:armor1
	general:wildcard1
}

Attack
{
	offensive:armor1
	offensive:inf1
	general:wildcard1
	defensive:inf2
	defensive:support1
}

Each of these strategy sections has a corresponding set of purchasing guidelines.

armor1
{
	//purchasing percentage instructions for this strategy
	Purchase
	[
	//total amount to spend on air units
	air=.30
	//ammounts of the above to spend on types
	multi=0
	fighter=.40
	bomber=.35
	strike=.15
	recon=.10
	//amounts to spend on ground units
	armor=.40
	mech=.30
	inf=0
	arty=.20
	]
}

You may add as many new strategy types as you like. The Ai will attempt to draw from offensive strategies when it is attacking, defensive strategies when defending, and general strategies in either case. If it is given multiple strategies of a given type it will select randomly.

Scenario Files

Scenario Files: CAOS\Data\Scenarios\[scenario name]\database_data\game\scenario_config.dat

The scenario_config.dat file contains scenario options and randomization settings, it can be edited with a text editor. In this file you can configure the requisition point levels available for scenario creation, the turn length of games, random scenario deployment parameters for each game type, and battle grouping and engineering restrictions.

Requisition Points

This section defines the base points provided to each side BLUFOR/REDFOR, by game type, in a scenario. The final points used in game will be scaled based on the OB year selected from these values. You may add additional levels and descriptions as shown.

//Random Scenario Points Settings BLUFOR/REDFOR - new levels may be added
Points
[
	Skirmish
	{
		Division = 64/83
		Taskforce = 85/110
		Corps = 128/166
		Corps+ = 213/276
		Army = 340/443
	}
	Meeting
	{
		Division = 64/64
		Taskforce = 85/85
		Corps = 128/128
		Corps+ = 213/213
		Army = 340/340
	}
	Attack
	{
		Division = 64/83
		Taskforce = 85/110
		Corps = 128/166
		Corps+ = 213/276
		Army = 340/443
	}
	
	//The order and number of descriptions should match point settings above.
	Description
	{
		Division = A very small engagement averaging 1 division per side.
		Taskforce = A small engagement averaging 2 divisions per side.
		Corps = A medium engagement averaging 3-4 divisions per side.
		Corps+ = A large engagement averaging 6 divisions per side.
		Army = A very large engagement averaging 9 or more divisions per side.
	}
]

Scenario Length

You may change the number of turns available for each scenario and game type, new values may be added.

//Scenario Length in turns
Turns
{
	Skirmish = 10,15,20
	Meeting = 10,15,20
	Attack = 10,20,30
}

Random Scenario Settings

You may change the base randomization values used in scenario creation. Including, for example, the randomly selected distance ranges between the objective and the attacker, the distance ahead of the objective to spawn the defender, and the range in move points of any supply depots on the map.

ranges, such as: attkdist=8-10,10-15,15-20 will cause the game to randomly select an attacker distance of either, 8 to 10 hexes, 10 to 15 hexes, or 15 to 20 hexes, and then randomly select an actual value within this final range. For example 10-15 hexes. This can be used to modify the distances in initial deployment. New values can be added to each list. Note that allowing larger values, especially on small maps may limit the number of potential objectives which are actually usable.

//Random Scenario Settings
Random
[
	//attkdist - distance from selected objective to start attacking side
	//defdist - distance from objective in direction of attacker to draw line
	//mapedgedply - should a map edge deployment be established
	//mapedgesupply - should a map edge supply be established
	//spldist - supply range to use for spawned supply points

	Skirmish
	{
	attkdist=8-10,10-15,15-20
	defdist=3-5,5-7,5-10
	mapedgedply=1
	mapedgesupply=0
	spldist=20
	}
	Meeting
	{
	attkdist=8-10,10-15,15-20
	defdist=3-5,5-7,5-10
	mapedgedply=1
	mapedgesupply=0
	spldist=20
	}
	Attack
	{
	attkdist=8-10,10-15,15-20
	defdist=3-5,5-7,5-10
	mapedgedply=1
	mapedgesupply=0
	spldist=20
	}
]

Battle Group Restrictions

By default all nations may produce battle groups. You may limit this per nation, or disable it for an entire side in a given scenario.

//Battle Group Restrictions
BattleGroup
{
//change to none to turn off for a side
BLUFOR=normal
REDFOR=normal
//remove or add nations to this list to enable or disable
nations=American,British,French,German,Italian,Russian
}

Engineering Orders

By default all nations may produce conduct all engineering orders. You may limit this for a specific scenario as shown below.

//Engineering Orders
Engineering
{
enable=1
destroy_bridge=1
mining=American,British,German,Italian,Soviet,French
demining=American,British,German,Italian,Soviet,French
forts=American,British,German,Italian,Soviet,French
bridge=American,British,German,Italian,Soviet,French
}

Graphics

Graphics:

Virtually any graphic located in the assets folder in CAOS can be modified using your preferred graphical editing program.

Unit graphics:

CAOS\assets\units
Unit graphics are located in CAOS\assets\units

You can edit existing graphics and assign different graphics to different types of units. For example, if you wanted to create an alternative counter set, or change the existing color scheme you could substitute your own graphics in place of the NATO style counter set.

To edit a unit graphic:
To change a unit graphic simply locate the desired unit and edit it with a graphical editor or replace it with another graphic. Unit graphics in CAOS are 42x45 pixel wide .png files.

To change the graphic used by a unit.
To assign a different graphic to a unit locate the unit type definition file, CAOS\Data\arsenal\unit_defenitions.ini. Locate the appropriate unit definition (unit definitions are attachment types) and change the counter key value to another graphic name.

For example:
counter=heavy weapon can be changed to counter=artillery, this would cause heavy weapons battalions, usually mortars, to use an artillery symbol instead.

Flags and Background Images CAOS\assets\images

The shields shown in the game start screen and on the unit card can be changed.

To change the flags used in unit cards, the multiplayer game ready screen, and the requisition system simply locate the desired graphic and edit or replace it with your desired image. Similarly, loading screens, background images, and terrain images used in combat reports can all me modified in the same way.

Interface: CAOS\assets\interface

The interface graphics including, order graphics, cursors and interface can be modified.

To modify or replace a graphic simply locate the appropriate graphic in the assets folder and modify or replace it. Note that changing the size of a graphic can cause graphical issues when the game is played.

Summary and Mod Upload

Although you cannot currently add new maps or totally new orders of battle you can customize most other elements of the game. Including attachments, equipment, unit stats, ai strategies, scenario settings and graphics.

Can I replace the counter set?
Yes! You can replace the existing NATO style counters with any design of your choosing. Simply locate the counters you wish to replace and modify them with a graphic editor.

Can I add equipment to a different year, or make an entire division of Tiger tanks?
Yes, you can. Simply locate the units you would like to change in game, then find the definition entries for that nation and year in the definitions file and swap the weapon tags out with the desired equipment.

Can I rebalance the capabilities of specific equipment?
Absolutely! Just find the equipment you would like to modify in the weapons file and change the desired stats.

Uploading your mod to the Steam Workshop
Once you have created the required files for you mod simply launch the game and open the options menu. From the options menu click “Upload” and select the .mod file for you mod. This will upload your mod to the Workshop, if this is the first time the mod has been uploaded it will create a new workshop file, otherwise it will update the existing mod. If the upload fails for some reason it will instead return an error code and message.

Note that if you are editing a scenario configuration file then your mod folder structure should look like this: CAOS\mods\[my mod name]\[scenario name]\database_data\game\scenario_config.dat

All other mod files, such as weapons, definitions, ai files, and graphics can simply be placed into the mod file: CAOS\mods\[my mod name]\

Please note that by default any uploaded mods will be set to public. If you would like to make your mod private, or edit the associated images or description you must login to the Steam Workshop on a browser, select the mod and edit the required settings.

Happy modding, and as always feel free to ask question in the modding discussion section!

Using Mods

To use a mod in CAOS simply subscribe to it on the Steam Workshop and enable it in game. Once you have subscribed to a mod and Steam has downloaded it, launch the game, select options and open the mod list. Select the name of the mod you wish to activate and press apply. Once you are satisfied close the mod list and restart the game. Any enabled mods will load at start up. Note that mods which change the weapons, or definitions data will also change your checksum, visible in the bottom right of the menu. If you are playing multiplayer both sides must have the same mods enabled.