Last update: August 22, 2008.
Warning: the third part, called "Single player campaigns",
is unfinished, and I don't guarantee backward compatibility
for versions following the beta 10 versions.
- 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
- Title
- Objective
- Square_width
- Nb_lines and
nb_columns
- West_east_paths
and south_north_paths
- West_east_bridges
and south_north_bridges
- Goldmines
and woods
- Nb_meadows_by_square
- Additional_meadows
- Remove_meadows
- Nb_players_min
and nb_players_max
- Global_food_limit
- Starting_squares,
starting_units and starting_resources
- Unit
types list
- Building 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 file
- Intro
- Add_objective
- Add_secondary_objective
- Objective_completed,
objective_failed, secondary_objective_completed,
secondary_objective_failed (action in a trigger)
- Cut_scene
(action in a trigger)
- Syntax of a
cut scene 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 "maps\custom\multi" 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
"maps\official\multi" 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
"maps\custom\multi" folder in "C:\Documents and Settings\Your
Login\Application Data\SoundRTS" 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 Settings\Your Login\Local Settings\Temp")
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.
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".
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.
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.
"global_food_limit 200" means: "The players cannot have more
than
200 food, even if they build more farms. This limit is divided among
the players (including non-player computers): for 2 players, the food
limit is 200 / 2 = 100 food for each player."
Starting_squares,
starting_units and starting_resources
These commands are useful only when the players start with the
same
resources and units. To give different starting units and resources to
players, use the "player" command.
"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.
"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."
"starting_resources 10 10" means: "each player starts with 10 gold and
10 wood."
Unit
types list
peasant
footman
archer
knight
catapult
dragon
mage
Building types
list
farm
barracks
lumbermill
blacksmith
townhall
stables
workshop
dragonslair
magestower
#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 "maps\custom\single" 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
"maps\official\single" 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
"maps\custom\single" folder in "C:\Documents and Settings\Your
Login\Application Data\SoundRTS" 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."