Modding Campaigns and Scenarios

== '''General Principles''' ==


#Scenarios in AACW have the .scn extension. They are to be placed in the ACW\Scens directory. If you created some events tied to this scenario, a file named as the scenario, but with the .sct extension must be placed to the ACW\Events directory.
#You first create a scenario by using an existing one, in Excel format (XLS extension, if you don't have Excel, the free Open Office suite is perfect for that too). The scenario XLS is made of three tabs: the [[Setup tab]], the [[Events&Reinforcements tab]] (also called Events tab), the [[Cities&Regions tab]] (also called the Cities tab).
#Each of these three tabs contains commands for the game. When you are finished with your edits, you will export these three tabs in .CSV format (do a 'save as..' in Excel), choose 'save as .CSV'. Don't bother with the warnings, respond yes to all questions. Be sure to save the three files generated with different names.
#Each of these three files will have to be converted into the scripting language the game understand. This is very important to understand that the commands you type in the XLS are not the final language, but a more convenient and user friendly one. The only language understood by the game is the scripting one. So theorically, you can type your scenarios directly in the scripting language, to be in touch with the 'real' things, but fortunally you don't have to do that (although this is basically the same language, but with some simplifications done for you when you are in the XLS format). 
#So the next step is to convert these CSV files into the scripting language. You do that by using the CSVSplitter utility, provided on the AGEOD Modding forum. 
#The CSVSplitter has several tabs, one for each kind of data to be interpreted. The Setup tab and the Events tab use one, the Cities tab use another. 
#The Setup (in CSV) is thus converted in another file, always named script.ini. Put this file in the  game's \scripts directory.
#The Events (in CSV) are converted into a file which should be properly named (youscenarioname.sct). Put this file in the  game's\events directory. 
#The Cities (in CSV) are converted into a file which is called cities.inc. You will have to rename this file (with the name you gave to the cities [[include]] in your scenario, for example CitiesBullRun.inc). Put this file in the  game's \includes directory.
#Once you have done that, you are ready to try your new scenario. 
Launch the game. As soon as you see the splash screen with the AGEOD logo, hit F9. You should see in the top right the text 'Edit Mode'. In this mode, the game will look for a script.ini file in the scripts directory. If one is there, it will interprets the commands and create the scenario.
#If you manage to get to the map without error, you can save your scenario. Just hit 'save turn' and you will have a new .scn file created in the \scenarios directory. You can now quit the game and launch it in normal mode.
#If you get error, see the [[#Launch the Editor]] section.


== '''Scenario Creation''' ==

=== Foreword ===
AGEOD Games [AACW, BoA, NCP, WIA, RoP] allow for the creation of new scenarios (including new units and models or new pictures and events – see below). In order to do so, you have some basic tools to use and a specific but not excessively complex procedure to follow: 
:* Gather data: OOB, reinforcements, geographic and historical data 
:* Prepare the Excel scenario 
:* modify models, units and strings Excel© files if need be 
:* Export data with the CSV Splitter 
:* Edit scenario with the ingame Editor 
:* Test 

=== Collecting Data === 
This is the starting point. You need to prepare in advance all the required information for the scenario, such as (non-exhaustive list): 

:*OOB: get the names and locations of leaders and units. Same for initial city existence, region control, forts and depots, Indian tribes location and status, etc… 
:*Reinforcement: list all units and leaders that appeared during the course of the scenario length, incl. when and where they show up.  
:*If you plan to have events in the scenario, get textual data and images that could fit with them in the game’s image bank. Check also which effect you want them to have.
:*Geography: check carefully who owns what, city and port levels when and where they exist, civilization level, control, loyalty, victory point locations (i.e. strategic towns), playable area, etc… 
:*find a title! 


=== The Excel Sheet ===
The first step requires you to use Excel© or Open Office© to prepare the whole scenario data in a usable spreadsheet format that will be required to export data in a format that can be read by the game tools. The steps to follow are indicated below, based on the sample setup file enclosed with this documentation.  

Please load and refer to [[media:RoP_Setup_Saxony_Wiki.xls|Example Scenario Spreadsheet]].

==== The columns ====
In all cases, where a single 'cell' contains multiple data refereces, each data point must be separated by the 'pipe' symbol   '{{!}}' 

The columns of the spreadsheet have specific uses.  The useage changes when a command is used vs. creating a unit, structure, group,etc...
:*Column A = [[Faction]] or NULL.  One of the playing factions in the scenario.
:*Column B = Name.  Used for the "name" of a unit or group. Used for the name of an event. Used for certain text values in some commands.
:*Column C = Command.  The scripting commands. The [[alias]] of a unit or structure. "Group" to define start of a group creation.
:*Column D = Param0. A vast majority of the command parameters will be entered here. Domain (LAND, NAV) (Group creation), or number of [[element]]s (Unit creation)
:*Column E = Param1. Posture (Group creation), Event type (Event start), Experience (Unit creation) 
:*Column F = Param2. Flavor Name of the unit Leader or Unit name - display purposes.
:*Column G = Param3. Fixed (group creation) or SubUnit Flavor names (in unit creation)
:*Column H = Param4. Location. Alias of a [[region]].  Places a group or structure there.
:*Column I = Param5. Entrenched. Starting entrenchment level of a group. Also defines a sound for certain commands.
:*Column J = Param6. InFort. If = 0, Group starts outside any city or fort in region. If = 1, start inside the city or fort.

==== Sheet #1 – Setup ====
The first page/tab of the Excel sheet contains the elements required at start of scenario, as well as scenario data.

===== General Data – Sides, Scenario Parameters, Rules in effect =====
See [[:Category:Script commands|Scripting Commands]] for script language details and explanations. Note that a scenario Setup is in actuality one very large [[event]]! 

This first part is the scenario definition commands and general data. The playing sides, general rules, [[Objectives]], Scenario descriptions, rules, etc are located here.

===== Includes =====
Often, there are commands or definitions that are common for several scenarios.  These are inserted via the [[include]] command. The most common types are:
:*Garrisons
:*City setup (required if you want to have cities, ports, etc on the map!!!)
:*[[SubFaction]]s

===== Setup and OOB =====
In order to make things easier to understand, the setup is organized in homogeneous blocks one side after the other. For clarity, you should enter the elements in the following order:

:Side 1
::*Structures: Enter all the existing structures (forts and depots), as this is mandatory for the loading process. 
::*OOB: As a rule (it is not an obligation, but makes checking easier), we suggest displaying data in the following order: 
:::*Large Armies and : either from one end of the map to the other, or by decreasing size. 
:::*Garrisons and fixed units: same as above 
:::*Fleets, Lake flotillas and bateaux: same as above 
:::*Subfaction forces (Indian allies, other allies)
:::*Special Rules (like region specific ownerships or other rules)

:Side 2
::*repeat above order

:End Section
:*AutoRaise instructions
:*Initial Replacements

===== Detailed Explanations =====
Groups: 
:*land and naval units are assembled inside individual groups, either of the LAND (for armies) or NAV (for naval units and the land units that start on board of them) types.  
:*Each group corresponds to one specific stack (and related thumbnail) on the map. 
:*Groups are identified by bold characters in the excel file.
:*If you enter def in column E (Param1), the group will start the game in defensive attitude, both when human and AI-controlled.
:*If you enter a value in column G (Param3), you will change the group’s fixing. It applies to all units in the group (if you want to differentiate, then you must create different groups). The keys for fixing are:
::*NULL or 0: the group is not fixed
::*-1 to -998: the group is fixed for that number of turns, but will become unfixed by friendly units (of higher strength) entering its region before the term.
::*1 to 998: the group is fixed for that number of turns, and cannot become unfixed by friendly units entering its region before the term.
::*-999: the group is fixed permanently until unfixed by friendly units (of higher strength) entering its region.
::*999: the group is fixed permanently.
:*In columns I and J (respectively Param5 and Param6), you enter whether the group is entrenched or not and whether it’s inside the fort/city (if present) or not.
:Note that once you have set these parameters for the group, they will apply of course to all units belonging to that group (which are listed below the group till the next), with no need to repeat the same information (we enter the value NULL instead).

Units: 
:*land and naval units individually are listed within groups. LAND may only contain land units and leaders, while NAV groups may contain land units which are then considered to be onboard the naval units of the group (provided said naval units have enough transport capacity for them, lest the scenario will crash!).  
:*Each unit may be assigned a name in column B (of your liking/custom, or more frequently from your OOB’s research). This name may be different from the default name assigned to the unit in the unit’s database. 
:*In column C (alias), you have to enter the unit’s alias (as per unit database). If you enter a non-existing alias, the game will crash. 
:*Column D (Param0) lists the current strength of the unit in terms of sub-unit (SU) component. If you enter NULL, the unit will have its full set of SU component (usually 4 in BOA, but not for all units). If you enter another value, the unit will have that number of SU (must be below to full value). 
:*Column E (Param1) lists the current experience of the unit. It is a numerical value between 1 and 6. 

[[OnAttack]]: 
:this mention in column C serves to trigger events related to the other faction attacking some specific area of owning faction. In 1775 WIA or BoA, for instance, it is used to activate all Indians in the North in favor of England if any one is attacked by the other faction. The area covered by the event, and the event themselves have to be defined separately.

NB: do not forget to always have the line with “EndEvent” at the bottom of this first excel page.

==== Sheet #2 – Reinforcement - Events ====
The second tab of the Excel sheet is dedicated to the “events” script, more generally everything that is related to reinforcements in the game, as well as some events that can change some game data or situation (such as region or unit unlock, new nation entering war, etc…).

 Note: Each game has several "Events only" spreadsheets that are used to organize events and to
 facilitate sharing of common events across several scenarios.  In these spreadsheets, ONLY the
 Event tab is used for Modding or Scenarios.  {Also note that some of these files may contain
 multiple Events tabs: typically the "Options" files.  When in doubt about what is used or not
 used, ask in the Modding Forums!!!!

===== Include Section =====
At the top of the sheet, you can select which other script files you can include in the scenario. These files either have an ‘.inc’ or ‘.sct’ extension. For instance, in theSaxony scenario, the first include line allows for the inclusion of the '''1756 SaxonyEvents.sct''' file (which is the name of the event file of the scenario), while the second line provides for the inclusion of the '''PrussianAllianceForcePools_Campaign.sct''' file, i.e. the file handling all Prussian Force Pool settings.
 
Technically, you may include as many files as you want (which in themselves may hold their own includes), as long as these files are valid ones.
 
===== Individual Events =====
Next in the sheet are the individual events. There can be as many as you want. For ease of reading, we strive to make them in chronological order, and this for each nation/side. You may however order them the way you want, just keep in mind the game engine reads the file from top to bottom, side by side, so a logical organization makes for a faster implementation of the events. 

===== Adding Units to the Game =====
It works just like in the first tab (i.e. the original OOB, see previous section). One first line covers the group name, the following ones are for each individual units part of same group.

===== Adding Replacements to the Game =====
It also works more or less just like in the first tab (i.e. the original OOB, see previous section). The instruction works likewise:

==== Sheet #3 - Cities: Geographical Data ====
The last tab in the excel scenario file concentrates the relevant geographical data for the scenario. Only some of the information in this sheet is used, the rest being there for quick reference, checking and sorting (because it is mostly already in the game’s database elsewhere).  By convention, the db file extracted from this section is called “CitiesXXX.inc” and will be called by the scenario under that name.

 Note: In row 2, a special command is inserted: "ScriptName" in Column A, the desired filename for the
 City Includes file in column B. This filename must match the filename of the "Include" command entered
 in the Setup tab.

===== UID & Name =====
The fist two columns are for sorting and reference only. Never alter the data in it, otherwise the game would be unable to trace the various regions and the data change you may have entered in the other columns. 

===== Transport Level ===== 
The column is used to assign to the region a certain level of transport network. The transport network level has a direct incidence on the movement speed of units in the region. Note that this only concerns land regions (no transport network on sea or river regions), and affects movement only, not combat. Weather effect still come in addition.

:The authorized keywords and the associated effects are: 

:*$NoNetwork: region has no transport network of any kind. Basically, the cost of movement in the region is directly impacted by the terrain type. 
:*$Track: the region has some tracks. Tracks make the terrain move cost equivalent to that of Wood terrain, if the current terrain has a more difficult and severe impact on movement. If current terrain has same or better effect, the Tracks “benefit” does not apply (e.g. case of clear or wood terrain)
:*$Roads: the region has some roads. Roads make the terrain move cost equivalent to that of Clear terrain, if the current terrain has a more difficult and severe impact on movement. If current terrain has same or better effect, the Roads “benefit” does not apply (e.g. case of clear terrain)

===== State & Region =====  
For reference only. Do not change (if you do, it should normally have no direct effect). 

===== Faction & Mil Control ===== 
The first of these two column is used to assign the region control to one of the game’s faction. The second lists the percentage of military control the faction has in that same region.
NB: note that columns J & K have same headers – see below

===== Loyalty ===== 
It is a percentage value that indicates the percentage of loyalty, as compared to side1. If you enter a 0, the region will be 100% Loyal to side2. 

===== Faction & Mil Control ===== 
These two columns work exactly like those in columns G & H described above, except that this time they apply to city control within region. The term city is generic, it also applies to infrastructure control (ports for instance). 

===== City Name ===== 
You can use this column to enter the city specific name for the scenario. It will be spelled exactly as entered here, whatever the game language used.

===== City Level ===== 
The column contains the city level, a number from 0 (no city) to 10 (or more, for very large cities). The number directly affects the quantity of supply chips received by units, depots and supply units when staying in the region with said city. 
Important: Indian villages are identified by the -1 value.

===== IsPort&Level ===== 
The column tells if there is a port in the region (there may be a port without a city). If the number is 0, the region does not have a port. If there is a value, it also indicates the port value (the higher the more supply chips are received there). 
Important: do not enter ports in region where there are no body of water (lake, river, ocean) adjacent to it, as it will not be accepted. In some of the game regions, the port symbol will not be displayed if the region cannot have physically a port site (i.e. inland region without river / lake). 

===== VP ===== 
The column lists whether the region’s city is a [[Strategic Cities|strategic city]] or not in the scenario (objectives are listed on the first sheet, not here). A -1 value indicates a non-city region (hence not eligible). A 1 will indicate a strategic city, a 0 will be entered for a normal city.  
:[[Victory points]] are awarded for [[control]] of Strategic Cities.

===== Block State ===== 
The column is important as it lists which region can be entered in the scenario or not. See [[BlockState]] for accepted vallues. 

===== Supply; Ammo; Power; Money; WSU; Csc =====
These columns define the quantities of these resources created each turn in each region.

=== Exporting data – the CSV Splitter ===
The CSV Splitter is a specific tool we provide you with in order to export the data created in those excel files into something the game engine can read easily (usually a text file). The reason we used Excel files in the first place was to have something easier to design and read by the developers / modders. Have a look at one of the game’s data file (scn file for instance) and you will understand why!.

The tool works rather simply using a variant Excel ©save format, the csv format (csv means comma separated values). We recommend you use the splitter on one scenario at a time, to avoid confusion over save names or accidental copy pasting of files.
In Open Office©, the method is “Save As” then set file type csv.

 CRITICAL NOTE:
 When exporting the csv files, you must define the “Field Delimiter' as a semicolon ; and the 'text delimiter'
 as none or blank.  [these are the English language terms from Open Office©] 
 This is absolutely required for ALL files from the spreadsheet DB being prepared for use [Models, Units,
 weathers, abilities, etc.], not just scenarios.

==== Preparing data ====
The first step to undertake before using the tool is to open your Excel© file with the scenario and save EACH of its thumbnails/sheets, under a different name, in CSV format (see “Save as” options of your Excel software). 

:Hint
:*Save Sheet #1 as “ScenXX.csv”
:*Save Sheet #2 as “EventXX.csv”  
:*Save Sheet #3 as “CitiesXX.csv” 
This may prove very helpful in finding the right file later on.

===== Save the Geographical data =====
Open the CSV Splitter tool and select the Cities thumbnail in it. Then load the CSV file you have made from the geographical sheet of the Excel scenario file [CitiesXX.csv] and click on OK to export it.
It will create in the destination folder (which you can change) a file called “Citiesxxx.inc”. 
Be certain that this file has the same name as the one listed in the first sheet of the Excel file for the City include. Example: in the 1756 Saxony Scenario, the include file is “CitiesSaxony.inc” in the first sheet, so that’s the name we must use.

===== Save the OOB =====
Open the CSV Splitter tool again and select the Setup, Events thumbnail in it. Then load the CSV file you have made from the first sheet of the Excel scenario [ScenXX.csv] file and click on OK to export it.
It will create in the destination folder (which you can change) a file called “Script.ini”. 

===== Save the Events =====
Open the CSV Splitter tool one last time and select the Setup,Events thumbnail again. Then load the CSV file you have made from the second sheet of the Excel scenario [EventXX.csv] file and click on OK to export it.
It will create in the destination folder (which you can change) a file called “XXXXX.sct”, where XXXX.sct is exactly the name you have entered for the event file in Line 3 "ScriptName" of the Reinforcement/Events tab.

 Note: The "common" or referenced Events and includes files are created exactly the same way as the "Events Tab" of a setup.

See also: [[media:ScenCreation01.pdf|Scenario creation example]]

=== Compiling the data: Using the game Editor ===
Once you have exported the three above files with the CSV Splitter, you will now create the scenario thanks to the Ingame Scenario Editor tool provided with Birth of America. 

==== Add the files to the game ====
Select each of the three files, one after the other, and copy paste them into the following game directory: 

CitiesXX.inc 	into	\Includes
Script.ini 	into 	\Script
XXXXX.sct	into 	\Events

NB: make sure that in \Scens there are no already existing scenario file(s) – those with an scn extension – that bears the same name as the one you have chosen for your newly created scenario.

==== Launch the Editor ====
Run the game. As soon as you see the message about loading textures (10%...), strike on the F9 key. You will noticed on the top right-hand side of the loading screen the mention “Editor Mode”.

Wait until you see the game map and your scenario units magically appears in front of you…
If they don’t, you’ll either get an error message or nothing (more exactly you get the load menu)…in which case you did something wrong in the previous steps!

If you get errors, you should check the !MainLog.txt in \Logs, and the ScriptReport.txt in \Scripts for messages.

==== Check and Save ====
Once the scenario appears on the screen, you can have a look around it as you wish. The major difference with a complete scenario is that you can check all units from all nations everywhere on the map. This allows you to quickly see if everything you planned is well in there.

If you are satisfied, then center the map where you want the scenario to open upon normal play and click on the save button. Your scenario is now saved. 

If you are not pleased or want to improve it a bit more, then just Quit the game and proceed with the changes you wish to add.

== Testing your Scenario ==
Before submitting the scenario, we strongly advise you to play it at least twice, once for each side involved. Play until scenario is complete, and check in particular if all the reinforcements and events you plan are will in there. It particularly includes the checking of events descriptions and names. We now the hard way how easy it comes to have one or two mistakes and omissions escape your attention.