1. We have added a Gift Upgrades feature that allows you to gift an account upgrade to another member, just in time for the holiday season. You can see the gift option when going to the Account Upgrades screen, or on any user profile screen.
    Dismiss Notice

[TUTORIAL] The scenario file - a dissection

Discussion in 'Maps & Scenarios' started by Toffer90, Jun 25, 2020.

  1. Toffer90

    Toffer90 C2C Modder

    Joined:
    Oct 16, 2011
    Messages:
    6,710
    Location:
    Norway
    Any scenario saved in the world builder will be functional.

    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
    And this 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

    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).

    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
    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 nice
    Calendar=CALENDAR_DEFAULT
    Victory=VICTORY_TIME
    &%/()=?
    Victory=VICTORY_CONQUEST
    EndGame, lol
    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
    ▬▬▬▬▬▬▬▬▬▬▬▬
    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.
    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
    ▬▬▬▬▬▬▬▬▬▬▬▬
    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 ▬ - - | | - -
    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.
    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
    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.
    Spoiler Valid tokens in the random leader setup :
    BeginPlayer
    PlayerSlot=int
    Team=int
    StartingX=int, StartingY=int
    Handicap=KEY​
    EndPlayer
    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 then 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.
    Spoiler Required tokens in the specific leader setup :
    BeginPlayer
    PlayerSlot=int
    LeaderType=KEY
    CivType=KEY​
    EndPlayer
    ▬▬▬▬▬▬▬▬▬▬▬▬
    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 - 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: Jun 27, 2020
    lobosan and Snofru1 like this.
  2. Toffer90

    Toffer90 C2C Modder

    Joined:
    Oct 16, 2011
    Messages:
    6,710
    Location:
    Norway
    reserved

    The opening post is a WIP atm.

    I'll probably finish it during the weekend.
     
    Last edited: Jun 25, 2020
  3. Toffer90

    Toffer90 C2C Modder

    Joined:
    Oct 16, 2011
    Messages:
    6,710
    Location:
    Norway
    reserved
     
  4. Toffer90

    Toffer90 C2C Modder

    Joined:
    Oct 16, 2011
    Messages:
    6,710
    Location:
    Norway
    reserved
     
    Last edited: Jun 27, 2020

Share This Page