Any scenario saved in the up to date world builder should be functional; contact me if you find a case where it doesn't work.
That said, there may be tweaks you want to make directly in the scenario text file, either because it is easier than launching the game and doing it in world builder, or because the world builder is incapable of customizing a given value.
It is then nice to know what's what, the structural rules of its content.
The scenario file contains several sections types, and nested inside each section are multiple named values.
Within these sections the general structure per line is token=value.
The section begin/end name, e.g. EndGame, is a token without a value.
Now the term token is established. ^^
Within a section, the order of the tokens doesn't really matter.
I will color code tokens from now on:
RED means it is required, if it is missing the scenario won't initialize correctly
Cyan means it is required in some situations, optional in others.
GREEN means it is optional and has a valid default value
The ◘◘◘ symbol signify that a specific token can have multiple entries where each value is added to a list.
If a token doesn't have ◘◘◘ and is listed multiple times in its section then the last one will overwrite its earlier cousins.
Don't order them differently, e.g. if the map section is after the player section then it won't read in any player or team data because it read in map data before that and skipped past the team and player sections in the file to find the map section, it does not rewind to the top of the file after each section it has read because it assumes this order to optimize read time (less redundant line read operations).
▬▬▬▬▬▬▬▬▬▬▬▬
Section 0 - Meta data
▬▬▬▬▬▬▬▬▬▬▬▬
Section 1 - Game data
This section is optional if you only have default values set for it.
By optional I mean that the read code will cope fine with the section not being there at all.
▬▬▬▬▬▬▬▬▬▬▬▬
Section 2 - Map data
If Randomize Resources is set to true then the code will ignore all resources defined in the plot sections.
▬▬▬▬▬▬▬▬▬▬▬▬
Section 3 - Team data
If the team is not supposed to be alive on game start then there's no need to include its section in the scenario file. If you want all players to start with no techs and otherwise be a clean slate then there's also no need to include their sections.
TeamSlot must be ordered from low to high, if a previous team section had a higher TeamSlot then what this section has, then the read code will fail to read in this and any later team sections.
▬▬▬▬▬▬▬▬▬▬▬▬
Section 4 - Player data
If your scenario got at least one player section that has valid values for both LeaderType and CivType, then this scenario cannot have random leaders at all, and only player sections with valid values for these two will be available when starting the scenario.
If there are no player sections with valid values for them, then all starting players will be random civs/leaders.
In a random leader setup the scenario file itself cannot influence the amount of starting civs in any way. If the player starts the scenario through "play scenario" the exe will use the world size xml value called iDefaultPlayers to determine the amount of starting civs. You can however still specify the starting coordinates for each player slot in the scenario file, any player slots that doesn't have such coordinates will get a random starting plot. The human player will always be player slot 0 in this setup.
PlayerSlot is cyan because it is not needed if its value always equal the amount of player sections that came before the player section it is defined in. It must be ordered from low to high, if a previous player section had a higher PlayerSlot than what this section has, then the read code will fail to read in this and any later player sections.
If you want specific players for this scenario then each starting player requires a player section.
▬▬▬▬▬▬▬▬▬▬▬▬
Section 5 - Plot data
I won't list all tokens here, the plot section is a bit special as it can contain city and unit sections within them.
Section 5 - Sign data
Doesn't work at the moment, the sign are created when starting the game, but then they are all purged by some other code after the scenario read code is all done and finished.[/SPOILER]
That said, there may be tweaks you want to make directly in the scenario text file, either because it is easier than launching the game and doing it in world builder, or because the world builder is incapable of customizing a given value.
It is then nice to know what's what, the structural rules of its content.
The scenario file contains several sections types, and nested inside each section are multiple named values.
Within these sections the general structure per line is token=value.
The section begin/end name, e.g. EndGame, is a token without a value.
Now the term token is established. ^^
Within a section, the order of the tokens doesn't really matter.
I will color code tokens from now on:
RED means it is required, if it is missing the scenario won't initialize correctly
Cyan means it is required in some situations, optional in others.
GREEN means it is optional and has a valid default value
The ◘◘◘ symbol signify that a specific token can have multiple entries where each value is added to a list.
If a token doesn't have ◘◘◘ and is listed multiple times in its section then the last one will overwrite its earlier cousins.
Spoiler The section order matters !! :
BeginMeta
EndMeta
BeginGame
EndGame
BeginMap
EndMap
BeginTeam
EndTeam
BeginPlayer
EndPlayer
BeginPlot
EndPlot
BeginSign
EndSign
EndMeta
BeginGame
EndGame
BeginMap
EndMap
BeginTeam
EndTeam
BeginPlayer
EndPlayer
BeginPlot
EndPlot
BeginSign
EndSign
Spoiler P.S. comment lines :
The read code ignores all lines where it doesn't find what it is looking for, which means it is ok to add comment lines wherever one please.
e.g.
▬▬
Author: I made this scenario!
Version=X
This is just some metadata I want to have in the file at this point.
### Because why not ###
BeginGame
I don't respect the section indentation
Calendar=CALENDAR_DEFAULT
And so on
BeginMap
▬▬
The bold text will be correctly read in while the un-bold is just extra junk to shift through.
e.g.
▬▬
Author: I made this scenario!
Version=X
This is just some metadata I want to have in the file at this point.
### Because why not ###
BeginGame
I don't respect the section indentation
Era=C2C_ERA_PREHISTORIC, a comma act as a separator for the parser
Speed=GAMESPEED_MARATHON
This calendar line will be read without errors, indentation isn't really important, it just looks niceSpeed=GAMESPEED_MARATHON
Calendar=CALENDAR_DEFAULT
Victory=VICTORY_TIME
&%/()=?
Victory=VICTORY_CONQUEST
EndGame, lol&%/()=?
Victory=VICTORY_CONQUEST
And so on
BeginMap
▬▬
The bold text will be correctly read in while the un-bold is just extra junk to shift through.
Section 0 - Meta data
Spoiler Tokens :
Version=C2C_1
Description=text ▬ The text seen when selecting the scenario in the scenario list.
ModPath=text/path ▬ Used by the exe to load the correct mod when starting the scenario
Description=text ▬ The text seen when selecting the scenario in the scenario list.
ModPath=text/path ▬ Used by the exe to load the correct mod when starting the scenario
Section 1 - Game data
This section is optional if you only have default values set for it.
By optional I mean that the read code will cope fine with the section not being there at all.
Spoiler Tokens :
Era=KEY ▬ This is the scenario start era
Speed=KEY ▬ This is the authors preferred gamespeed and will be the default selection
Calendar=KEY ▬ The default value is standard, don't worry about it.
◘◘◘ Option=KEY ▬ Game option used by this scenario.
◘◘◘ MPOption=KEY ▬ Multiplayer option used by this scenario.
◘◘◘ ForceControl=KEY ▬ Force a specific option on the player even in custom scenario.
◘◘◘ Victory=KEY ▬ Victory condition used by this scenario
GameTurn=integer (int) ▬ Not working as it should atm, don't know why yet. Turn 0 is forced as start turn by some code, possibly in the dll, though the exe is involved as it asks the scenario read code to give it the start turn value; could someone check if scenarios can have a custom start turn in vanilla BtS?
MaxTurns=int ▬ Used by the time victory condition
MaxCityElimination=int ▬ Not entirely sure what this does.
NumAdvancedStartPoints=int ▬ self-explanatory
TargetScore=int ▬ Used by score victory condition.
StartYear=int ▬ self-explanatory
CircumnavigatedTeam=int ▬ Which team circumnavigated the globe.
Speed=KEY ▬ This is the authors preferred gamespeed and will be the default selection
Calendar=KEY ▬ The default value is standard, don't worry about it.
◘◘◘ Option=KEY ▬ Game option used by this scenario.
◘◘◘ MPOption=KEY ▬ Multiplayer option used by this scenario.
◘◘◘ ForceControl=KEY ▬ Force a specific option on the player even in custom scenario.
◘◘◘ Victory=KEY ▬ Victory condition used by this scenario
GameTurn=integer (int) ▬ Not working as it should atm, don't know why yet. Turn 0 is forced as start turn by some code, possibly in the dll, though the exe is involved as it asks the scenario read code to give it the start turn value; could someone check if scenarios can have a custom start turn in vanilla BtS?
MaxTurns=int ▬ Used by the time victory condition
MaxCityElimination=int ▬ Not entirely sure what this does.
NumAdvancedStartPoints=int ▬ self-explanatory
TargetScore=int ▬ Used by score victory condition.
StartYear=int ▬ self-explanatory
CircumnavigatedTeam=int ▬ Which team circumnavigated the globe.
Spoiler Valid KEY's for ForceControl are :
FORCECONTROL_SPEED
FORCECONTROL_HANDICAP
FORCECONTROL_OPTIONS
FORCECONTROL_VICTORIES
FORCECONTROL_MAX_TURNS
FORCECONTROL_MAX_CITY_ELIMINATION
FORCECONTROL_ADVANCED_START
FORCECONTROL_HANDICAP
FORCECONTROL_OPTIONS
FORCECONTROL_VICTORIES
FORCECONTROL_MAX_TURNS
FORCECONTROL_MAX_CITY_ELIMINATION
FORCECONTROL_ADVANCED_START
Section 2 - Map data
Spoiler Tokens :
grid width=int ▬ Number of plots horizontally
grid height=int ▬ Number of plots vertically
top latitude=int ▬ defaults to 90
bottom latitude=int ▬ defaults to -90
wrap X=int ▬ Bigger than zero is "True", zero and negative are "False", defaults to False
wrap Y=int ▬ - - | | - -
Randomize Resources=int ▬ - - | | - -
world size=KEY ▬ worldsize affect game rules probably more than you think.
climate=KEY ▬ Doesn't matter much, very little use this value.
sealevel=KEY ▬ - - | | - -
grid height=int ▬ Number of plots vertically
top latitude=int ▬ defaults to 90
bottom latitude=int ▬ defaults to -90
wrap X=int ▬ Bigger than zero is "True", zero and negative are "False", defaults to False
wrap Y=int ▬ - - | | - -
Randomize Resources=int ▬ - - | | - -
world size=KEY ▬ worldsize affect game rules probably more than you think.
climate=KEY ▬ Doesn't matter much, very little use this value.
sealevel=KEY ▬ - - | | - -
▬▬▬▬▬▬▬▬▬▬▬▬
Section 3 - Team data
If the team is not supposed to be alive on game start then there's no need to include its section in the scenario file. If you want all players to start with no techs and otherwise be a clean slate then there's also no need to include their sections.
Spoiler Tokens :
TeamSlot=int ▬ Not really needed.unless you for some reason want empty team slots (dead teams) to have lower index number than this team has, this is mostly useful if making a scenario from an ongoing game where some teams have died, you don't want the team slot index of the alive players to change because a lot of stuff relies on them being what they are.
◘◘◘ Tech=KEY ▬ self-explanatory
MinorNationCiv=int ▬ Bigger than zero is "True", zero and negative are "False", defaults to False
◘◘◘ ContactWithTeam=int ▬ self-explanatory
EspionageTeam=int, EspionageAmount=int ▬ If you have one you need the other.
◘◘◘ AtWar=int ▬ This team is at war with the team with the given team index value
◘◘◘ PermanentWarPeace=int ▬ Value is other team index
◘◘◘ OpenBordersWithTeam=int ▬ - - | | - -
◘◘◘ DefensivePactWithTeam=int ▬ - - | | - -
◘◘◘ VassalOfTeam=int, Type=string ▬ type is either "FREE" for vassal or "CAP" for surrender (satellite)
◘◘◘ ProjectType=KEY ▬ projects finished by this team
VassalPower=int ▬ TBD
MasterPower=int ▬ TBD
◘◘◘ Tech=KEY ▬ self-explanatory
MinorNationCiv=int ▬ Bigger than zero is "True", zero and negative are "False", defaults to False
◘◘◘ ContactWithTeam=int ▬ self-explanatory
EspionageTeam=int, EspionageAmount=int ▬ If you have one you need the other.
◘◘◘ AtWar=int ▬ This team is at war with the team with the given team index value
◘◘◘ PermanentWarPeace=int ▬ Value is other team index
◘◘◘ OpenBordersWithTeam=int ▬ - - | | - -
◘◘◘ DefensivePactWithTeam=int ▬ - - | | - -
◘◘◘ VassalOfTeam=int, Type=string ▬ type is either "FREE" for vassal or "CAP" for surrender (satellite)
◘◘◘ ProjectType=KEY ▬ projects finished by this team
VassalPower=int ▬ TBD
MasterPower=int ▬ TBD
▬▬▬▬▬▬▬▬▬▬▬▬
Section 4 - Player data
If your scenario got at least one player section that has valid values for both LeaderType and CivType, then this scenario cannot have random leaders at all, and only player sections with valid values for these two will be available when starting the scenario.
If there are no player sections with valid values for them, then all starting players will be random civs/leaders.
In a random leader setup the scenario file itself cannot influence the amount of starting civs in any way. If the player starts the scenario through "play scenario" the exe will use the world size xml value called iDefaultPlayers to determine the amount of starting civs. You can however still specify the starting coordinates for each player slot in the scenario file, any player slots that doesn't have such coordinates will get a random starting plot. The human player will always be player slot 0 in this setup.
Spoiler Valid tokens in the random leader setup :
BeginPlayer
PlayerSlot=int
Team=int
StartingX=int, StartingY=int
Handicap=KEY
EndPlayer
Team=int
StartingX=int, StartingY=int
Handicap=KEY
If you want specific players for this scenario then each starting player requires a player section.
Spoiler Required tokens in the specific leader setup :
BeginPlayer
PlayerSlot=int
LeaderType=KEY
CivType=KEY
EndPlayer
LeaderType=KEY
CivType=KEY
Section 5 - Plot data
I won't list all tokens here, the plot section is a bit special as it can contain city and unit sections within them.
Section 5.1 - City data
Section 5.2 - Unit data
▬▬▬▬▬▬▬▬▬▬▬▬Section 5.2 - Unit data
Section 5 - Sign data
Doesn't work at the moment, the sign are created when starting the game, but then they are all purged by some other code after the scenario read code is all done and finished.[/SPOILER]
Last edited: