Basic Scripting

1.   What do I need to make a scenario? 

To make a scenario or a single mission you will need to make (or download ) a map (.m3d file).  It can have as few or as many resources and units as you want on it, within the limits of the game.  How much of what to put in is entirely up to you; see no. 2 below ("How do I make a map?") for a little more information. Then you will have to go to the Scenario Editor and put your Triggers in place.  When doing so, it's a good idea to have no other applications open, otherwise some irregularities may crop up. To create a mission, select "New Mission" in the File menu.  You will need to find and select a map to work with.  NOTE:  Only one scenario can be made per map.   

2.   How do I make a map?    

Load Cossacks and choose the Editor from the Main Menu. You will need to place units and  peasants, buildings, ore deposits, trees, stones, and zones.  At least one unit needs to be placed on the map, though through scripting additional units can be placed later.  It is beyond the scope of this document to tell you how to make a map; however, a decent map can be made using the "paste" function.

3.   What is a Mission Group? 

A Mission Group is a collection of Units created in the Map Editor and defined using the Mission Group tool (which looks like a square formation of troops).  Turn "Scroll Lock" on your keyboard, select units to be grouped, click on the tool, and give them a name.  Mission Groups are fixed elements and cannot be added to in the course of a game.  While you don't need to create Mission Groups for every map, they greatly simplify scripting for Fixed Force style missions by pre-defining the groups with which the Scenario Editor can work.

The units making up a Mission Group don't have to be all of the same kind -- or even "units" as we tend to think of them.  A Mission Group can be buildings, troops, artillery etc.  If they are all grouped together and labeled as a group (identified by a rectangle encompassing them in the Map Editor) then they are a Mission Group.NOTE:  Mission Group names CANNOT include spaces; see Question 5 for more tips.

4.   What's a Zone?   

A Zone is, as the name suggests, an area on the map (marked out by you).  They can be very small or large, but use care in creating large zones; a zone encompassing the entire map often will crash the game.  Zones can be created with the Zone tool in the Map Editor, which looks a little like a bullseye, and are demarcated with a yellow circle surrounding a central "signpost."  Turn "Scroll Lock" on, make sure no units are selected, then click on the Zone tool.  You will be asked to name the zone.  Click and drag to place the zone on the map.NOTE:  Zone names CANNOT include spaces; see next question for more tips.

5.   Are there limitations on how I can name Mission Groups and Zones?

Zone and Mission Group names CANNOT include spaces, or they will not be recognized by the game.  Zones and Mission Groups also need to have unique names.  An easy way to ensure this is by attaching "Zone" or "Group" respectively to the name of a zone/group.  E.g. you can't tell the game to order a group called "Muskets" into a zone called "Muskets" (it won't work), but you CAN order "MusketGroup" into "MusketZone" without problem.  Also, Triggers cannot have the same name as a Mission Group or Zone, so plan all these elements carefully to make your life simpler.   

6.   How many Mission Groups and Zones can I use in a scenario?  

Cossacks: The Art of War allows only 256 Mission Groups and Zones each.  Therefor, if you're planning a large map, it's a good idea to think through your zones and groups carefully.  Both can be used in multiple contexts, e.g. a zone can be used both as a trigger condition and as a waypoint for traveling units.  Economy of elements is a good design principle anyway, to help reduce the load on the player's CPU - and the scriptwriter's brain.

7.   How do triggers work?    

Triggers come in 2 parts: a Condition and an Action.  You define the Condition(s). And if the Condition(s) is (or are) met then the Action will take place.  Essentially, each trigger is an IF-THEN statement. NOTE:  The default condition for a trigger is "ALWAYS."  This means there is no real condition -- the only one to be met is that the scenario is being played! 


8.   How does Cossacks deal with math?  

At some point you'll notice Cossacks is a little quirky when it comes to arithmetic, which it defines in terms of "ratios."  The ratios available to you are:

- is equal to

- is not equal to

- is more than

- is less than

In practice, however, only the last two really work.  This is because during the course of a game, numbers of units, game ticks, etc. is in constant flux.  Your computer simply can't do everything at once, and so that fleeting moment when there are exactly 200 Algerian archers left in the enemy battalion is usually missed in the blink of a computer processing eye.  Thankfully, the game is better at understanding when X is more or less than Y than figuring out if X=Y.

This makes for some counterintuitive conditions at times.  For example, if you want to check that there are no units left in a particular group, "Number of units in group <name> is equal to 0" can't be relied upon.  You CAN, however, check if "Number of units in group <name> is less than 1."  Mathematically speaking these two statements are equivalent, since Cossacks deals only with integers greater than 0.

9.   How does Cossacks deal with time?  

Time is measured in terms of game ticks in Cossacks.  A game tick is defined as a certain number of "frames," or screen refreshes.  This makes a good deal of sense from a programming perspective, since the actual time in minutes that any particular game action takes varies from computer to computer:  Player A might be able to build a Russian 18th Century Barracks with 20 peasants in 3 minutes, while for Player B the exact same action takes only 2 -- but counted in ticks, that time period is exactly the same.

This makes life difficult for those writing scripts, however, because a game tick seems instantaneous to the human perception (unless something is seriously wrong with your computer setup).  A rule of thumb to go by is 1000 ticks = 1 minute, give or take.  It's better to think in terms of game progress, however, rather than minutes.  E.g. time an attack based on about how long it would take to build two town halls and a barracks -- and of course test to see how good your guess was.

Note also that small units of time give Cossacks a bit of trouble, too.  In practice, if you need to closely time two events, the smallest practical interval you can use is about 20 ticks.  Keep this in mind when the need arises.

10.  How does Cossacks deal with directions?
The directional compass can be a little bit confusing, as it is NOT set out in terms of degrees!  Instead the compass is divided into 256 directions (0-255) with 0 at the RIGHT (or "East").   Here's a quick guide:

N = 191

NE = 223

E = 0

SE = 31

S = 63

SW = 95

W = 127

NW = 159

11.  Are there any conditions that don't work?

All of those listed below either do not work, or produce a Mission Script Error upon starting a scenario:

- Upgrade is already accomplished.

- Number of units of a certain type in zone by player.

- Number of units of a certain type by player

- Number of deceased units of a certain type by player.

- Number of killings done by group units.

There is ONE workaround for "Number of units of a certain type in zone by player:"


      Number of units of player <color> in zone <zone> is <more/less than> <number>


      Deselect units of player <color>

      Select <type> units of player <color> in zone <zone> by <changing/adding> to previous selection.

      Save selected units of player <color> to dynamic group <name> by <changing/adding to> previous units.

      Activate current trigger.

What this trigger does is, if units of a color (say Red) are present, it will select any and all Red units of a particular type (say musketeers) and save them to a Dynamic Group (see below).  Then, this Dynamic Group can be checked for its size, e.g.


      Number of units of player <color> in group <name> is <more/less than> <number>.


      ...whatever you want to happen, based on the above condition.

This wastes a lot of trigger space, but is the only way around this particular bug.

12.  Are there any actions that don't work?

- Attack enemy in zone with group units.

- Attack zone with artillery.

- Attack buildings in zone.

- Disable upgrade.

- Launching AI for certain countries.

- Building peasants for most countries.

Ways of coping for these shortcomings are mentioned under appropriate questions below.  As the possibilities of the Scenario Editor are nearly endless, there may be additional bugs yet to be discovered.

13.  How many triggers can I use in a scenario?

 Technically speaking, you have up to 256 triggers available to you -- but that number is drastically reduced by the number of lines of code you have.  Problems seem to arise between approx. 700-1000 lines of code.  If your script is starting to get beyond 60 triggers (especially if any of them are particularly long), it's a good idea to proceed slowly and test often.  Too many command lines will cause a scenario to crash to desktop upon loading.NOTE:  Flags are treated as triggers by the game engine, so the more flags you use, the fewer triggers you have available to you.  The main limitation still seems to be total lines of code, however.

14.  How do I play a mission I've made?  

Save the mission from the Scenario Editor.  The appropriate files and folders will then be made; read the message that pops up for an explanation.  To play the mission you can either select it as a Designed Map (from Single Player > Random Map) or as a Single Mission.  It's best to play it as a Single Mission, as one will see the mission brief, picture, etc.

16.  Are there any other bugs I should know about?

A.   The Duplicate Bug

Never, EVER use the "Duplicate" function of the Scenario Editor, no matter how tempting it is to avoid tedious clicks and typing. 

B.   The Message Bug


The Scenario Editor doesn't seem to like dialogue very well.  In writing the message file for a scenario (the .txt file generated when saving), if there's too much info to keep track of, it can start introducing errors into the file which are impossible to fix

A couple more bugs are known but less serious than the above.  When opening and saving a mission, the bitmap "preview" picture is reverted to the default.  Thus, if you want something other than the Cossacks medallion to appear here, save placing it for the last thing you do to your script. 

Also, while the mission briefing (set within Scenario > Properties) can be as long as you want, the player will only be able to see about 700 characters' worth of it.  This is actually a bug of Cossacks: as the scroll bar does not properly scroll in Mission Briefing screen.