Empires Modding

From Archon Wiki
Jump to navigation Jump to search

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

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

Coming soon?

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.

The Editor

Coming soon??

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.

Retrieved from "https://archonwiki.slitherine.com/index.php?title=Empires_Modding&oldid=504"