# Map making guide

Warning: the third part, called "Single player campaigns", is unfinished, and I don't guarantee backward compatibility for versions following the 1.0 beta 10 versions.

Contents

- Introduction
- Multiplayer maps
  - Where to store a new multiplayer map
  - How to edit a map
  - How to test a map
  - How to find and remove an error
  - Comments
  - Basic properties
    - Title
    - Objective
    - Nb_players_min and nb_players_max
    - Global_food_limit
  - Defining the terrain
    - Square_width
    - Nb_lines and nb_columns
    - West_east_paths and south_north_paths
    - West_east_bridges and south_north_bridges
    - Goldmines and woods
    - Additional_meadows
    - Remove_meadows
  - Defining the starting resources of the players
    - Case 1: same resources for everybody
      - starting_resources
      - starting_units
      - starting_squares
    - Case 2: different resources depending on the player
      - player
      - computer_only
    - Types list
  - #random_choice, #end_choice and #end_random_choice
- Single player campaigns
  - Where to store a new single player campaign
  - Structure of the campaign folder
    - Chapter files
    - The "sounds" folder
    - The "stream" folder
  - Syntax of a chapter file
    - Syntax of a mission chapter file
      - Intro
      - Add_objective
      - Objective_complete (action in a trigger)
      - Cut_scene (action in a trigger)
    - Syntax of a cut scene chapter file

# Introduction

The best way to start is probably to make a multiplayer map.

# Multiplayer maps

## Where to store a new multiplayer map

If you are allowed to write in the folder where SoundRTS (or SoundRTS test) is installed, then you can store your first multiplayer map in the "mapscustommulti" folder. There is a sample map file called "multi_example.txt". Copy-and-paste it and rename it to the name of your choice. You can copy-and-paste the map files in the "mapsofficialmulti" folder too, but don't store new maps in this folder: they would be ignored.

If you are not allowed to write in the program files folder because you work in non-admin mode, you can store your working map file in the "mapscustommulti" folder in "C:Documents and SettingsYour LoginApplication DataSoundRTS" or "SoundRTS test". These folders are created the first time you start SoundRTS. Another solution is to install SoundRTS in a folder where you are allowed to write, and to work in the folder mentionned in the previous paragraph.

## How to edit a map

Open the file with a text editor. Write in lowercase, even if case will be probably ignored anyway.

## How to test a map

To test a map, start SoundRTS and go to the single player menu. You can play against the computer on multiplayer maps. The map is reloaded each time you start a game, so you don't need to restart SoundRTS to test the modifications. A useful key combination is Control Shift F2: if you are the only human on the map, you will be able to examine the whole map (no fog of war).

## How to find and remove an error

If, when you start the map, you get the message: "server error" and go back to the server menu, then the details of the error are in a file called "maperror.txt". This file is in your default temporary folder (for example C:Documents and SettingsYour LoginLocal SettingsTemp") or in the SoundRTS folder.

In the same directory you may find additional (but cryptic) information in a file called "SoundRTS-local-server.log".

If you still don't understand where the error is, feel free to contact me, directly or at the soundRTSChat list.

## Comments

The lines that start with a semicolon are comments. Comments are ignored at runtime. Everything after a semicolon until the end of the line is a comment too.

## Basic properties

### Title

"title 4018 5000" means: "the title of the map is the sound 4018 followed by the sound 5000".

### Objective

"objective 145 88" means: "the objective of the map is the sound 145 followed by the sound 88".

### Nb_players_min and nb_players_max

"nb_players_min 2" means: "2 players are needed to start the game." "nb_players_max 4" means: "4 players in this map is a maximum."

### Global_food_limit

New in version beta 9e.

Update in version beta 10 o: this food limit is not divided among the players anymore.

"global_food_limit 200" means: "Every player cannot have more than 200 food, even if he builds more farms."

## Defining the terrain

### Square_width

"square_width 12" means: "the square width is 12 meters". You shouldn't modify this parameter, since objects may be inaudible if they are too far.

### Nb_lines and nb_columns

"nb_lines 7" mean: "the grid has 7 lines". "nb_columns 7" mean: "the grid has 7 columns". The limit for columns is 26 and there is no limit for lines, but the actual limit is probably not far from 26 anyway, because of performance. Warning: nb_rows is deprecated and has the same meaning as nb_columns.

### West_east_paths and south_north_paths

"west_east_paths a1 c1 d1 f1" means: "add a path from a1 to b1, from c1 to d1, from d1 to e1, and from f1 to g1". You only need to give the west-most square of the path. "south_north_paths a1 a3 a4 a6" means: "add a path from a1 to a2, from a3 to a4, from a4 to a5, and from a6 to a7". You only need to give the south-most square of the path.

### West_east_bridges and south_north_bridges

Bridges work exactly like paths.

### Goldmines and woods

"goldmines 150 a2 b7 g6 f1" means: "add goldmines with 150 gold at a2, b7, g6 and f1". Woods work exactly like goldmines. Nb_meadows_by_square

"nb_meadows_by_square 2" means: "auto fill the map with 2 meadows in each square".

### Additional_meadows

"additional_meadows a2 b7 g6 f1" means: "add 1 meadow in the squares a2, b7, g6 and f1". "additional_meadows a2 a2 g6" means: "add 2 meadows in a2 and 1 meadow in g6".

### Remove_meadows

remove_meadows do the opposite of additional_meadows.

## Defining the starting resources of the players

### Case 1: same resources for everybody

Use the following commands in combination:

#### starting_resources

"starting_resources 10 10" means: "each player starts with 10 gold and 10 wood."

#### starting_units

"starting_units townhall farm peasant" means: "each player starts with 1 townhall, 1 farm and 1 peasant."

"starting_units townhall 2 farm peasant" means: "each player starts with 1 townhall, 2 farms and 1 peasant."

Since SoundRTS 1.1, starting_units can also contain:

- upgrades and research: "starting_units u_teleportation" means: "each player has teleportation already researched."
- forbidden units, buildings, abilities, upgrades/research (they won't appear on the menu):
  - "starting_units -u_teleportation" means: "each player cannot research teleportation."
  - "starting_units -a_teleportation" means: "each player cannot use teleportation."

#### starting_squares

"starting_squares a2 b7 g6 f1" means: "the starting squares of the players are a2, b7, g6 and f1."

The starting units and buildings will be created in these squares.

### Case 2: different resources depending on the player

#### player

The "player" command defines a starting point that might be used by a human player or by a computer AI (in multiplayer games).

This command can be repeated several times in a multiplayer map.

"player 5 10 -townhall a1 townhall peasant c1 footman" means: "a player will start with 5 gold, 10 wood, won't be allowed to build a town hall, will have a townhall and a peasant at A1, a footman at C1.

#### computer_only

The "computer_only" command defines a starting point that will always be played by a computer AI. This AI will be hostile to any other player or AI.

This command can be repeated several times but be careful: too many AI can slow the game. So use one AI if these units are not supposed to fight each other (several dragons all over the map for example).

computer_only 0 0 a3 dragon b1 dragon means: "add a computer AI with 0 gold, 0 wood, a dragon at A3 and a dragon at B1."

### Types list

Here are some correct names for types used in starting_units, player and computer_only . For a full list, examine the rules.txt file: the name is just after the "def" statement.

- units: peasant footman archer knight catapult dragon mage priest necromancer
- buildings: farm barracks lumbermill blacksmith townhall stables workshop dragonslair magestower
- abilities: a_teleportation
- upgrade/research: u_teleportation melee_weapon

## #random_choice, #end_choice and #end_random_choice

(new in beta 9g) This preprocessor directive chooses randomly between 2 or more choices delimited by #random_choice, #end_choice and by #end_random_choice for the last choice. Each choice consists in zero or more lines. More than one #random_choice directives can be used in a map file, but they cannot be nested.

This can be used for example to place random resources. For example: #random_choice goldmines 500 e2 c6 b3 f5 #end_choice goldmines 500 d2 d6 b4 f4 #end_choice goldmines 500 c2 e6 b5 f3 #end_random_choice The preceding lines mean: "add a goldmine at e2, c6, b3 and f5, or at d2, d6, b4 and f4, or at c2, e6, b5 and f3". This way, the resources are balanced (if I didn't make a mistake of course). This is only an example.

The title of the map and the number of players cannot be changed this way because the preprocessor is run when the map is loaded (that is to say: long after the single player menu is loaded).

# Single player campaigns

## Where to store a new single player campaign

If you are allowed to write in the folder where SoundRTS (or SoundRTS test) is installed, then you can store your first campaign in the "mapscustomsingle" folder. There is a sample campaign folder called "campaign_example". Copy-and-paste it and rename it to the name of your choice. You can copy-and-paste the campaign folder in the "mapsofficialsingle" folder too, but don't store new campaigns in this folder: they would be ignored.

If you are not allowed to write in the program files folder because you work in non-admin mode, you can store your working map file in the "mapscustomsingle" folder in "C:Documents and SettingsYour LoginApplication DataSoundRTS" or "SoundRTS test". These folders are created the first time you start SoundRTS. Another solution is to install SoundRTS in a folder where you are allowed to write, and to work in the folder mentionned in the previous paragraph.

## Structure of the campaign folder

The name of the campaign folder will be used by the single player menu. Official campaigns will have their own title in the "sounds" folder. The folder contains chapter files, a sounds folder, and a stream folder.

### Chapter files

Chapter files are text files called "0.txt", "1.txt", "2.txt", etc. When a campaign is started for the first time, only the chapter 0 is available. When a chapter is finished, the next chapter can be run. The number of the higher chapter available is automatically stored in the player's configuration file called campaigns.ini.

A chapter file describes a mission chapter or a cut scene chapter.

There must be at least one chapter file, called "0.txt".

### The "sounds" folder

The "sounds" folder contains additional or replacement ogg sound files (usually mono) that will be loaded in memory when the campaign menu is entered, and unloaded when the campaign menu is quitted. The sounds that have a name that is already in the default "sounds" folder of SoundRTS are replacement sound files. They will be played instead of the default sounds. The sounds that have a name that is not already used are additional sound files. Use file names starting from 7000.ogg to 7499.ogg (this range will not be used for the default sounds of soundRTS).

### The "stream" folder

The "stream" folder contains ogg sound files (usually stereo) that will not be played often (essentially the intros and the cut scenes) and will be loaded at run time in streaming mode. Use file names starting from 7500.ogg to 7999.ogg (this range will not be used for the default sounds of soundRTS).

## Syntax of a chapter file

A chapter is a mission or a cut scene.

### Syntax of a mission chapter file

A mission file is not very different from a multiplayer map. The following commands are not used in a single player mission: nb_players_min, nb_players_max, starting_squares, starting_units, starting_resources.

#### Intro

Example: "intro 7500 7501 7502" means: "before the game starts, play 7500.ogg, 7501.ogg and 7502.ogg". The intro command defines a sequence of sounds that will be played before the game starts. When the player presses a key, the next sound in the sequence is played. An intro can be for example a title with music, then a scene with a discussion between characters, then a briefing. After the intro, the game will tell the objectives of the mission.

The sounds used by this command must be stored in a "stream" folder.

#### Add_objective

"add_objective player1 1 7000" means: "add objective number 1 with the sound 7000.ogg"

The sounds used by this command must be stored in a "sounds" folder.

All the objectives must be completed to win a mission. If a primary objective fails, for example when an important character dies, the mission is aborted.

#### Objective_complete (action in a trigger)

This action can only be included in the action part of a trigger.

"objective_complete 1" means: "now objective 1 is complete"

Trigger example:

"trigger player1 (has barracks) (objective_complete 2)" means: "add the following trigger for player1: if he has at least 1 barracks then the objective 2 is completed"

#### Cut_scene (action in a trigger)

A cut scene can be triggered in the middle of a game: when something is discovered, when reinforcements arrive, etc.

"cut_scene 7500 7501" means: play the cut scene made up of the sounds 7500 and 7501.

The sounds must be in the "stream" folder.

Trigger example:

"trigger player1 (has_entered d5) (cut_scene 7500)" means: "add the following trigger for player1: if he has entered the square d5, then play the cut scene made up of the sound 7500.ogg" Timer and timer_coefficient (condition in a trigger)

"timer_coefficient 60"

'trigger player1 (timer 2) (cut_scene 7500)" means: "after 2 minutes (2 x 60 seconds) play the 7500.ogg sound file."

### Syntax of a cut scene chapter file

A cut scene chapter is an interruptible sequence of streaming sounds. When the cut scene chapter has been played, the next chapter is unlocked. Do not confuse with shorter cut scenes run by a trigger during a mission when a condition is met (discovery of a square for example), or with the mission's introduction (or briefing).

The cut scene chapters have only 3 lines. For example: cut_scene_chapter title 7000 sequence 7500 7501 7502

The first line is a keyword used to tell the game that this chapter is a cut scene and not a mission. The title line is used in the campaign menu. The sound must be a preloaded sound, not a streaming sound. The sequence line means: "play the sound 7500.ogg followed by 7501 and 7502 in streaming mode; if the player presses a key, skip the current sound and play the next one."