Empires Modding

Modding Guide

Getting Started

Empires saves user files in your Documents\My Games\FieldOfGloryEmpires folder, which will be referred to as your 'user' folder. In addition to saved games, logs, and options files, this is where user created mods are located. Editing files directly in the game install folder (ex C:\Program Files (x86)\Slitherine\Field of Glory Empires) is NOT recommended, doing so may prevent multiplayer games from working correctly and interfere with game updates.

Before you begin modding, you may wish to open the USER.TXT file in your user folder and the following line to enable additional debugging tools:

DEBUGMODE 1

See Empires Version for additional topics.

Create a Scenario

Empires currently only support mods by the creation of a new, modified scenario. The quickest way to create a new scenario and get started modding is to copy an existing scenario. For example, to start with the grand campaign, browse to the Scenarios folder in your game install folder (ex. C:\Program Files (x86)\Slitherine\Field of Glory Empires\Scenarios). Copy the d310BCGrandCampaign folder into the SCENARIOS folder of your user folder (ex Documents\My Games\FieldOfGloryEmpires\SCENARIOS). Rename the pasted folder to something new (it is recommended the new folder name not contain spaces). You should also make sure this new folder and its contents are not Read-Only. Inside this folder, you should see a number of files:

MYSCENARIO
│   SCENARIO.BSF
│   TEXT1.TXT
│   TEXT1_FRE.TXT
│   TEXT1_GER.TXT
│   TEXT1_SPA.TXT
│   SCENARIO.TXT
├───DATA
│   │   SETUP.csv
│   │   SETUP_FACTIONS.csv
│   │   REGIONS.csv
│   │   SETUP_GROUPS.csv
│   └───SCRIPTS
│           Events_Plugin.BSF

A good place to start would be to open TEXT1.TXT in a text editor. Here you can give your mod a unique name, description, and starting message. See Modding#Custom_Text for details on modifying string files in the Archon engine. TEXT1_FRE.TXT, TEXT1_GER.TXT, and TEXT1_SPA.TXT contain the translations of the strings in TEXT1.TXT. If you do not plan to translate your mod into other languages, you should just remove these three files and the strings entered in TEXT1.TXT will be used for all languages.

SCENARIO.BSF is another place you can make some quick edits to you scenario. Refer to Scripting for a description of the Archon scripting language. The InitScenario function near the beginning of this file sets up a number of parameters for your scenario, try changing gTurnInfos.dateFirstTurn to adjust the starting date for your mod.

If you start the game and select Scenarios, your modified scenario should now appear near the bottom of the list and be selectable for play.

Changing the Scenario Setup

Three files of particular interest when changing the setup of the scenario are found in the DATA folder - SETUP.csv, SETUP_FACTIONS.csv, and REGIONS.csv. These files are semi-colon separated CSVs and can be opened and edited in most spreadsheet software (ex Excel, OpenOffice), be sure to save them in the same format.

SETUP_FACTIONS.CSV

This file defines which factions are available in your scenario.

Coming soon...

REGIONS.CSV

This file specifies the basic properties of each region on the map.

• Alias: This is used as a reference to this region elsewhere. It is not recommended that you change this column, as it is used to associate this region with an area in the map used by this scenario.
• Name: This is a reference to the name used for this region. To edit the name, do not change the reference itself, but create a new entry with this id in the TEXT1.TXT file you edited above.
• Terrain: This is the terrain type of this region. For a list of valid terrain types, see DATA\TERRAINS.CSV, although some terrain types are not valid to assign directly to a region. Note that the reference must begin with $. This is generally the case when referring to an Alias from another CSV.
• Res[0], Res[1], Res[2], Res[3]: These are the natural resources present in the region. For a list of possible resources, see DATA\RESOURCES.CSV.
• Disabled: This controls which regions defined in the map are included in the scenario.
• Faction: This is the faction which initially owns this region (see SETUP_FACTIONS.CSV)
• CitizensID[0], CitizensAmount[0]: CitizensID[0] is the ethnicity of a the citizens to add, see DATA\ETHNICS.CSV for a list of possible ethnicities. CitizensAmount[0] is the number of citizens of the given ethnicity to add. Citizens will initially be distributed among the four possible jobs. To add citizens of multiple ethnicities, use CitizensID[1-3] and CitizensAmount[1-3].
• SlavesID[0], SlavesAmount[0]: add slaves to the region, similar to citizens above, although they will only be initially assigned to Agriculture or Infrastructure.
• City_Name: This is a reference to the name of the city in this region. As with the region name, you can override the name by adding a new entry to your TEXT1.TXT file.

SETUP.CSV

This file defines the initial placement of structures and groups (armies and navies) in your scenario.

Coming soon...

Adding Units

Before starting, if your custom scenario doesn't already contain these files, copy them from the game install folder (as above, do not edit them directly in your game installation):

• DATA\UNITS.CSV
• DATA\UNITVISUALS.CSV
• DATA\FACTIONS.CSV

To add a new unit, start by adding a new row to your UNITS.CSV, or copying the row describing a similar unit. You must fill in these fields:

• ID - This must be a unique number greater than zero, start with something well beyond the range of values in the standard unit list to avoid conflicts later, ex 10000.
• Alias - This must be a unique and descriptive string starting with "ID_UNI_" that you will use to identify this unit later in other data files.
• Name - This is a reference to the name used for this unit type. Add a new, unique string id in this table (by convention, starting with IDS_UNIT_NAME_ and ending with the unique portion of the Alias) and then define a new string with this id in your scenario's TEXT1.TXT file.
• Text - This is a reference to the description used for this unit type. Add a new, unique string id in this table (by convention, starting with IDS_UNIT_TEXT_ and ending with the unique portion of the Alias) and then define a new string with this id in your scenario's TEXT1.TXT file.

To complete your new unit, or if you are simply modifying an existing unit, also set these fields:

• FOG2_Name - This is the type of unit this will be exported as when a battle is exported to Field of Glory 2. This must match a value in the Name column of Field of Glory II\Data\Squads.csv, or copy a value from a similar unit if you are unsure.
• FOG2_QualityMOD - When exported to Field of Glory 2, this is the base quality of a unit relative to the type given above, as a percentage. Set this to 100 if you are unsure.
• AGEOD_Cost - When exported to Field of Glory 2, this is used in the calculation of how many units are created in FOG2 for each Empires unit.
• Family - The category of this unit, possibly values are: $famInfantry, $famHvyInfantry, $famArcher, $famSkirmisher, $famLtCavalry, $famSkirmisherCavalry, $famCavalry, $famHvyCavalry, $famHvyBeast, $famSiege, $famLtWarship, $famWarship, $famHvyWarship, $famTransport
• EvolveFamily - If non-zero - if this unit becomes obsolete it can be replaced by another unit with the same value, or another unit with the same value becomes obsolete it can be replaced by this unit.
• EvolvePriority - If an EvolveFamily is set, it is used to pick the best unit to evolve an obsolete unit to.
• UpdgradeNext - Used in Event/Decision driven unit upgrades.
• MoveSpeed - The movement speed of the unit.
• Hits - The maximum number of Hits of the unit.
• Effectiveness - The maximum Effectiveness value of the unit.
• Attack - The base Attack value of the unit.
• Defense - The base Defense value of the unit.
• IsSupport - Does the unit behave as a support unit in combat.
• DistanceToCenter - Low values will cause a unit to be deployed near the center of combat, high values will deploy the unit near the flanks.
• AssaultDistanceToCenter - As DistanceToCenter, but used during assaults.
• Siege - The Siege value of the unit.
• SiegeResist - The Siege Resist value of the unit.
• SupplyUsage - The amount of supply consumed by the unit per turn (1 food typically provides 5 supply, before bonuses and penalties).
• AttackingRange - During the ranged attack phase of combat, can the unit target the opponent front line (0), support line (1), or reserves (2).
• RangedAttack - The Ranged Attack score of the unit, or 0 for units without a ranged attack.
• RangedDefense - The Ranged Defense score of the unit.
• RangedMaxDamages - The limit of Effectiveness damage done by the unit during the ranged attack phase.
• FlankingModifier - A bonus used when calculating flanking or pursuit damage inflicted by this unit.
• Modifier[0 - 3] - Modifiers for this unit, a reference to a row in DATA\MODIFIERS.CSV.
• NotBuildable - If set to 1, this unit will not be recruitable normally (ex. units that only appear in garrisons).
• BuildPointsCost, ManpowerCost, MoneyCost, MetalCost - Equipment, Manpower, Money and Metal costs to recruit.
• ManpowerUpkeep, MoneyUpkeep, MetalUpkeep - Manpower, Money, and Metal maintenance costs.
• MoneyInflationCost - The increase in Money cost per unit of this type.
• ShipyardNeed - The level of shipyard needed in a region to recruit the unit.
• Recruit_Weight - A weight given to this unit when doing randomized unit recruitment.
• RecruitArea - Optionally limits recruitment of this unit to a specific group or regions, a reference to a row in DATA\AREAS.CSV
• RequiredStructures - If a structure or | separated list of structures is given, the unit can only be recruited in regions where at least one of the structures is present. The structures are references to rows in DATA\STRUCTURES.CSV
• NationalUnique - If non-zero, a faction cannot recruit the unit if it already has one.
• ProgRate - The experience points required to reach Experience Level 1.
• InitialXPLevel - The base initial Experience Level for this unit.
• Garrison_Category - For units which can be recruited as automatic garrisons, this must correspond to one of the Garrison_Category entries of the structure which provides the garrison, in DATA\STRUCTURES.CSV.

Next, in your UNITVISUALS.CSV, you will need to have an entry for added units. Each unit type must have at least one 'garment' specified:

• Unit - A reference to the Alias of the unit in UNITS.CSV.
• Garment - Allows the same type of unit to have different appearances in different factions. This value is either $GARMENT_DEFAULT if it is the default appearance, or a match to the Garment entry for a faction in DATA\FACTIONS.CSV.
• Asset - Specifies the 3D model used for this unit, this is a reference to a row in DATA\SQUADS.CSV (note this is not prefixed with a $ as most references are). Typically, this corresponds to a model in DATA\ASSETS\UNITS in S4F format which is a proprietary Slitherine model and animation format.
• TextureSet - Used to control which color and pattern variation to use for this unit. Unit models typically have multiple sets of possible textures, you can preview these by viewing the 'diffuse' textures in DATA\ASSETS\UNITS. Texture set 0 is found in the root of that folder. Other texture sets are found in the texture# subfolders.
• TextureVariant - Within each texture set are up to 4 variants (cavalry and other complex units may only have 2 or 1 variants per set). 0 is the top left variant, 1 is the top right, 2 is the bottom left, and 3 is the bottom right. For example, TextureSet 1, Texture Variant 3 of the african_spearmen, uses the lower right quadrant of DATA\ASSETS\UNITS\texture1\African_Spearman_Diffuse.dds when drawing the unit.

Finally, new units will need to be added to the pool of factions that they are available to. In your FACTIONS.CSV, update:

• UnitsAge1 - a | separated list of unit references for units available to the faction in the lowest category of government (Horde, Tyranny, Kingdom, Oligarchy, or Sect).
• UnitsAge2 - a | separated list of unit references for units available to the faction in the second category of government (Tribe, City State, Monarchy, Republic, or Hierocracy).
• UnitsAge3 - a | separated list of unit references for units available to the faction in the third category of government (Confederation, Commonwealth, Empire, Federation, or Theocracy).

You should now be able to start your scenario and have your new or modified units available.

Advanced

If an existing modifier doesn't suit your unit, you can create a new modifier by copying MODIFIERS.CSV from the DATA folder of the game installation to the DATA folder of your custom scenario. Then add a new modifier following the pattern of the existing modifiers. You can now refer to this new modifier from your unit.

Modifiers refer to effects to apply statistical bonuses or penalties. These effects are defined in DATA/EFFECTS.CSV, so as above you can create a new effect by copying the shared EFFECTS.CSV to your scenario's DATA folder and creating a new effect.

Many unit effects only apply in specific terrain categories (indicated if the effect terrains column is 1). In that case, the modifier will specify the terrains as the fourth parameter associated with that effect, using a combination of 1: Open, 2: Forest, 4: Arid, 8: Rough, 16: Swampy, 32: Assault, 64: Coastal Water, 128: Open Water, 256: Steppe, 512: Mountainous. For example:

ID_MOD_UNIT_MOUNTAINMEN has multiple effects, effectID[0] is $MOD_EFFECT_MOVE_BONUS, which is means the first effect is a movement speed bonus. params0[3] is 520, which is 512 + 8, indicating that this bonus applies in Mountainous and Rough terrain. Referring to the terrain categories in DATA/TERRAINS.CSV, we see that the Mountainous category includes both Mountain and Alpine terrain types, and the Rough category includes Hills and Arid Hills.

If you wish to create your own 'skin' for an existing unit model, you can add a new texture set for the unit by using an existing texture set as a template and following the naming of the texture exactly (although you may use a TGA file with the .tga extension instead of a DDS file) in the correct location for the next texture set within your scenario. For example, the Hoplite_vet_arm model uses the Hoplite_Vet_Diffuse.dds texture. The highest numbered texture set defined in the game is DATA\ASSETS\UNITS\Hoplite_Vet_Diffuse.dds, texture set 5. If you create a new texture set and place it within your scenario at DATA\ASSETS\UNITS\texture6\Hoplite_Vet_Arm_Diffuse.tga, you can then refer to Asset Hoplite_Vet_Arm and TextureSet 6 in UNITVISUALS.CSV and it will use your new texture set. If specular and normal maps aren't provided for a texture set, the versions from set 0 for that model will be used.

If you have a new 3D model in the S4F format, you will need to add a row in a copy of DATA/SQUADS.CSV that refers to that model before you can use it in your UNITVISUALS.CSV.

Adding Structures

Coming soon...

Adding Events

If you copied an existing scenario as above, your scenario should already contain a DATA\SCRIPTS\Events_Plugin.BSF containing one function, Event_EntryPoint(). Standard Empires events are found the Data\scripts\Events.BSF in the game installation folder. You may refer to the events in this file as a reference when creating events.

At the bottom of Events_Plugin, create a new function for your event, this function will be called at the end of each turn and will determine if the event should occur, what factions are affected, and apply the gameplay effects of the event. By convention, the function name should start with EventCustom_ followed by a descriptive name for the event. Once you have written your event function, add a call to it in the Event_EntryPoint function at the top of your Events_Plugin.

For example, if you want to create an event that will give 100 metal once during the scenario to each faction with a 1% chance each turn, your file should like this:

FUNCTION Event_EntryPoint()
{
	EventCustom_MetalStrike();
}

//// METAL STRIKE ////

// turn to start checking for the event (0 based)
#define EVTCUSTOM_METALSTRIKE_TURNSTART 1

// % chance per turn per faction
#define EVTCUSTOM_METALSTRIKE_CHANCE 1

// amount of resource given
#define EVTCUSTOM_METALSTRIKE_AMOUNT 100

// record of which factions have received the event
int EvtCustom_MetalStrike[FACTION_MAX];

FUNCTION EventCustom_MetalStrike()
{
	int facCount;
	int facIndex;
	int factionID;
	
	if (GetTurn() >= EVTCUSTOM_METALSTRIKE_TURNSTART)
	{
		// iterate over all factions
		facCount = GetNumFactions();	
		for (facIndex = 0; facIndex < facCount; facIndex++)
		{
			// has this faction already received this event (by index)
			if (EvtCustom_MetalStrike[facIndex] == FALSE)
			{
				// get the ID of this function
				factionID = GetFactionID(facIndex);
				
				// only applies to active factions, excluding independents
				if (Faction_IsWorldFactionOrInactive(factionID) == FALSE)
				{
					// has a chance to get a metal strike this turn
					if (Dice(100) <= EVTCUSTOM_METALSTRIKE_CHANCE)
					{
						// add the metal to the faction's stockpile
						Faction_AddResource(factionID, gResourceMetal, EVTCUSTOM_METALSTRIKE_AMOUNT);
						
						// send a message to the receiving faction
						Message_Faction_ChangeResourcePrivate(factionID, Faction_Politic_SeatOfPower(factionID), EVTCUSTOM_METALSTRIKE_AMOUNT, MSG_IMP_TOP, "IDS_MSG_EVENT_METAL_STRIKE");
						
						// remember that this faction has already had a metal strike
						EvtCustom_MetalStrike[facIndex] = TRUE;
					}
				}
			}
		}
	}
}

You will also need to add the string to display for this event to your scenario's TEXT1.TXT file:

IDS_MSG_EVENT_METAL_STRIKE, "Prospectors discover metal deposits in %{1}u totalling %{0}u metal.",

Advanced Modding

Many files not specifically covered elsewhere can still be overridden in a modified scenario. Generally, if a file is found anywhere in the Data folder of the game installation, you can place a modified version of that file in the same relative location of the DATA folder of your modified scenario and your scenario will use that instead.

When modding gameplay scripts from Data\Scripts, you must also copy Data\Scripts\MAP.BSF to your modified scenario to ensure your changes are included, even if you do not require changes to MAP.BSF.

The Editor

Empires contains a rudimentary editor for modifying or creating BAM files, which control the map. If you have started by copying the Grand Campaign, your scenario will be set up to load the shared Empires map, Data\Maps\AEP.BAM in the game install folder. If you open your scenario in the editor, changes you make will be saved to Data\Maps\AEP.BAM within your custom scenario. Note, you currently need to create an empty Maps folder within the Data folder of your scenario before you save the first time.

If you have enabled DebugMode above, when you open the Options screen from the Main Menu the will be an Editor button at the top of the screen. This editor has a small number of useful features. Select your scenario when prompted and click OK.

Please note that there is no Undo feature in the Editor and saving and backing up frequently is strongly recommended if you are making multiple edits.

Region Mode

The default editor mode is Region Mode. When you left click on the map to select a region, it will be highlighted in red and details will be displayed in the Region Properties panel on the right.

The top section of Region Properties specifies which row in REGIONS.CSV corresponds to the selected region on the map. Generally you will not need to change this unless you are creating a new map from scratch.

The second section lists a number of properties of the region. They cannot be edited here, they are specified by REGIONS.CSV or other setup files described above.

The third section is used to edit the connections between this region and its neighbors. On the map, the connections to the selected region are visualized with colored arrows.

If you right click on a region that is already connected to the current selection, it will be highlighted in purple and the Region Properties panel will update to let you Disconnect that region or change the connection 'terrain'. Although all terrains are offered, the relevant choices are:

• Strait - for crossing between nearby land regions without transporting through the water region which separates them
• Big River Crossing - indicates regions are separated by a large river
• River Crossing - indicates regions are separated by a smaller river
• Land Interdiction - prevents land units from moving between regions when the rules would otherwise allow it
• Naval Interdiction - prevents naval units from moving between regions when the rules would otherwise allow it
• No Cost - standard connection, there is no extra cost or limitation for moving between regions

See TERRAINS.CSV for the exact costs associated with the different connection types.

If you right click on a region that is not connected to the current region, it will be highlighted in green and you will be able to Connect it from the Region Properties panel and then set the connection terrain.

The bottom section of the Region Properties panel describes the anchor points defined for the selected region. Anchor points are used to set the locations of many dynamic objects during the game. The default anchor assignment is:

• 0: city
• 1: harbor
• 2: allied or neutral army
• 3: external wonder, 3d notifications, visual effects
• 4: second external wonder, second visual effect
• 5: icon
• 6: volcano
• 7: player army
• 8: overlay text
• 9: enemy army

The anchor locations are displayed for the current region as either a yellow triangle, or another 3D model that indicates its use. To move an anchor, first select it either by clicking on its representation on the map or selecting it from the list. Then drag and drop it to the desired location.

Border Mode

The Border Mode contains a number of rudimentary tools for creating or modifying the boundaries of a region. The border mode has a palette of four tools, which perform a variety of related operations depending on the context, button, and key modifiers. The exact functionality is described on the left of the editor when you select the different tools.

Unit Mode

Unit Mode allows you to visualize initial armies created during scenario initialization as described above. You may select an army to view its details. The armies are not edited here, this is done in Empires_Modding#SETUP.CSV

Scenario Properties

This mode lists miscellaneous read only information about the scenario, determined by the setup files.

Advanced

In some cases, the map file could have a different name. The SCENARIO.TXT file at the root of your scenario contains a line specifying the name of the BAM file.

See Empires_Terrain#Creating_a_Scenario for information on creating a new map using the editor.

Sharing Mods

As mods are self-contained scenarios, you can share a mod simply by packing and distributing your custom scenario's subfolder from your user folder, which is then placed on the equivalent location in another player's user folder.

Empires also supports the CPF and LST files in the same format as some previous Slitherine games to make installation easier for other players. To create a CPF file, select Editor, select the scenario to package from the list of custom scenarios, and then press the Create Campaign Package File (CPF) button. The CPF will be saved to your user SCENARIOS folder.

See http://www.slitherinebravo.net/GameWiki/doku.php?id=mod_older_hot#share_unofficial_user_scenarios_on_any_platform for more information.