Tutorial: Adding new units (long)

Introduction
============

This guide is intended for modders who wish to add a new hull to their games. It is primarily written with a new Unit type in mind, although with some extrapolation it works just as well for new ship sizes if you skip a couple of steps.

This guide is written primarily with newbie modders in mind so there is a fair amount of step-by-step processing that more experienced modders should be able to skim through quickly. I recommend that you look up all the fields referenced in the following text in the modding docs provided by Malfador Machinations.

Getting Started
===============

In order to show you what needs to be done, we'll go through step by step and add a new unit type called Militia. This new unit will represent the hastily-assembled militia units drawn from the population of a world that has been invaded by enemy Troops (which we might now think of as professional armies).

To start off, we'll create a new mod so that we can fiddle around with the data files and AI scripts safe in the knowledge that, whatever we do, it won't destroy our game. Open up the Gametypes folder and make a copy of the Standard SE5 folder. Let's call it New Unit Tutorial - the name isn't important, but it will help remind us of the purpose of this new mod. Open up this folder and edit the Mod_Definition.txt file, changing the value of the Mod Name field to New Unit Tutorial.

Next, you'll need to create two new folders inside the New Unit Tutorial folder. Call the first one Data and the second one Empires. Inside the Empires folder, make one folder for each empire within the game, not including the neutrals, and another folder called Default. If you can't remember all the empire names, just have a look in the stock Empires folder.

We are now ready to start making our new unit.

Part One - Creating the Hull
============================

Copy the stock VehicleUnitTypes.txt file into our mod's Data folder and open it up. Find the entry for Troop. Our new Militia unit will be doing very similar things to Troops, so we'll use that as a basic starting point. Make a copy the entire Troop entry and change the value of the Vehicle Unit Type Name field to Militia.

Now have a look at the abilities this unit has. Our intention is not that this unit as a professional soldier, rather it is an ad-hoc formation used only by defending population. The first two abilities are Can Be Scrapped and Takes Part in Ground Combat. Well obviously we want to keep the second one - that's the whole point of this unit, after all - and the first one is fine as well. This lets us scrap (ie disband) our units if cargo space is at a premium and we don't need them anymore.

The third ability is Can Be Transferred While In Cargo. With this ability, the unit can be moved around in cargo - that is to say, it can be loaded onto a ship and then moved to another colony. We don't want this, so delete the entire line. The same with the fourth ability (Can Be Dropped For Ground Combat). This is a defensive unit, not to be used to invade enemy worlds, so delete this line as well. Finally, because we've changed the number of abilities this unit has, you'll need to change the value of the Number Of Unit Capabilities field from 4 down to 2. Our new unit entry should look like this:

Vehicle Unit Type Name                       := Militia
Unit Texture Start X                         := 0.00
Unit Texture Start Y                         := 0.00
Unit Texture End X                           := 0.00
Unit Texture End Y                           := 0.00
Maximum In Space Per Player Per Sector       := 0
Number Of Unit Capabilities                  := 2
Unit Capability 1 Type                       := Can Be Scrapped
Unit Capability 2 Type                       := Takes Part in Ground Combat

Save your changes and close the file.

Next, copy the stock VehicleSizes.txt into your mod's Data file and start editing. Make a copy of the Small Troop entry.

Change the Name and Short Name fields to Militia. Change the Code to something appropriate like ML. Change the Vehicle Type field to Militia - this field is the one that tells the game to use the Militia unit type we just created in VehicleUnitTypes.txt.

Now we'll set the size and cost of our unit. Change the Tonnage Space Formula field to "4 + ([%Level%] - 1)" (without the quotes). This tells the game that our Militia can hold 4 Kt worth of components, with an additional +1 for each tech level researched above 1. For the resource costs required to build our Militia, we'll set the values to the following:

Cost Minerals Formula                           := 10 + (([%Level%] - 1) * 1)
Cost Organics Formula                           := 25 + (([%Level%] - 1) * 5)
Cost Radioactives Formula                       := 10 + (([%Level%] - 1) * 1)

Next we'll change the portraits used to show the unit in game. Modelling is beyond the scope of this tutorial, for now all we need to know is how to get the game to use any new models we may have made. A few lines below where we changed the resource costs, you'll find five groups of three lines each with various names, but all of which contain Primary, Alternate and Default. The first of each of these groups is the Primary. Look at the value, you'll see it has something along the lines of [%EmpireName%]_Portrait_SmallTroop.bmp. Change the SmallTroop to Militia, the entry will now look like [%EmpireName%]_Portrait_Militia.bmp. Go ahead and change all the Primary entries, following the pattern of the existing line. Don't worry that these new bitmaps don't actually exist, if the game can't find the file specified it will fall back to the Alternate and Default portraits.

The lines you've just changed should now look like this:

Vehicle Portrait Primary                        := [%EmpireName%]_Portrait_Militia.bmp
Vehicle Large Portrait Primary                  := [%EmpireName%]_LargePortrait_Militia.jpg
Vehicle Inv Portrait Primary                    := [%EmpireName%]_InvPortrait_Militia.jpg
Vehicle Inv Configuration Layout Primary        := [%EmpireName%] Militia Layout
Vehicle XFile Class Name Primary                := [%EmpireName%] Militia

The last thing we need to change is the requirements which allow us to build Militia hulls. Go down to the end of the Militia entry to where you see a group of lines beginning with the word Requirements. Notice Requirement 2 - the unit must have a troop cockpit. Change this requirement to the following:

Requirement 2 Description                       := This unit must have 1 squad of Militia.
Requirement 2 Formula                           := Get_Design_Specific_Component_Count("Militia") = 1

Later on we'll add this Militia component. But for now we'll have a quick look at the requirements. Requirement 1 is that you must have researched to at least tech level 1 in Troops. Notice the Requirements Evaluation Ability field has a value of 1 - this means it checks Requirement 1 to see if the vehicle is available. Requirement Allows Placement = 2, 3 means that the in-game vehicle design function will check requirements 2 and 3 to see if you have created a valid design. If not - specifically in this case, if you don't have a Militia component and the vehicle has more than 4 movement - the game will give you errors and you won't be able to create your design.

That's it for the moment. Save this file and fire up Space Empires V. Quick Start a new game using the mod we've just created and go straight to the design creation window. Notice this new vehicle type called Militia? Pat yourself on the back, you've just created a new hull type. Of course, you won't be able to create the design because we haven't created any components for it yet. We'll cover this in the next section.

Part Two - Components
=====================

In this part, we'll be playing around with components. Component modding is not the intended focus of this tutorial so we'll only touch briefly on things that are most relevant to our new unit type.

Copy the stock Components.txt file into your mod's Data file and open it up. Find the entry for Troop Cockpit. Remember that we changed one of the requirements in our vehicle hull from "Must have a Troop Cockpit" to "Must have a squad of Militia." Well, the Troop Cockpit is a good place to start. Make a copy of this component.

Change the Name field to Militia and the Description field to something appropriate like A squad of conscripted militia. We'll change the resource costs so that it only costs 20 organics to build (these are people, after all, not machines). Change the Picture Number to 111 (this is the picture used for the Boarding Parties component - you could always add your own component picture but for now this is the most appropriate).

Find the Can Be Placed On Vehicle Types field. This is an important field as it is this one that allows our new component to be placed on our new hull. Change the value to Militia. Next change the Ability 1 Description to something a little more appropriate.

Now we'll add some movement and supply/ordnance storage to this component - otherwise, our Militia units wouldn't be able to move or fight in combat. First change the Number Of Abilities field to 4. Now search for the Small Ion Engine component. Notice some of the abilities this component has - both Ground Movement Standard and Supply Storage. We'll need both of these, so copy both sections and add them to our Militia component. However, we'll need to tweak the values to suit our needs. Change the Movement ability's Amount 1 Formula to 4 (since we only have one of these components per unit, it needs to provide all our movement) and change the Supply ability's Amount 1 Formula to 50. Now copy the entire Ability 3 section and change the following:

- All the Ability 3 lines to Ability 4
- The Type to Ordnance Storage
- Change the word "supply" in the description to "ordnance"

Now we need to be able to arm our militia. Search the components file for "Unit Weapons" - this should take you to the location in the file where all the unit weapons are grouped. There are two lines within each weapon that you'll need to edit - the first is the aforementioned Can Be Placed On Vehicle Types field, which will allow us to place this weapon on our militia. The second is the Weapon Target Type List field, which will allow this weapon to attack our militia. Go through all the small weapons and modify each entry appropriately. For now, only allow the Small Depleted Uranium Cannon and Ground Cannon to be mounted on a Militia hull. Each weapon that can target Troops should be allowed to target Militia as well.

Save the file, we're finished with the components now.

Intermission - Extra Bits
=========================

That's pretty much the easy bit done, what remains is modding the AI to design and use the new Militia hull. But first, we'll clean up a few sundries. Copy the stock Settings.txt and DesignTypes.txt files into your mod's Data folder. In DesignTypes.txt, add a new entry as follows:

Name := Militia

In Settings.txt, search for the line Ground Combat Militia Troop Vehicle Type and change the value from Troop to Militia. Doing this will ensure that our new Militia hull is used as militia troops by a defending population instead of Troop designs. If you want you can also change the number of defending militia units that will be deployed in each battle.

Okay, fire up a game and go into the Design window. Create a new Militia unit. You should be able to place components and successfully create a new design type, although you can't yet use the Auto Complete function. Experiment a bit, put some research into Troops and Troop Weapons and see what you can come up with.

While you're here, design a Troop and fire up the ground combat simulator. On your homeworld, drop a few invading Troop units and let them go at it. If all has gone according to plan, the defending units should be your Militia. Now, do you notice that the invading tanks are running away from the militia? Don't worry, there's a reason for that and it has to do with strategies which is something we'll modify later.

For the rest of this tutorial we'll be modifying the AI scripts. Scripting is a complex and detailed process, and this tutorial will not be going into minute detail of the hows and whys. Interested parties are directed to the scripting pdf in the Docs directory. This tutorial assumes you have some basic knowledge of compiling and installing the AI scripts. As a summary, use the ScriptParser.exe program to compile each script, and then copy the resulting .csf files into the appropriate Empires\[EmpireName] folder.

Copy the entire stock Utilities directory into your mod's folder. You won't actually need everything in this folder but for our purposes it's easier to just copy the whole directory. Also, copy the stock Empires\Default\Default_AI_Strategies.txt file into your mod's Empires\Default directory.

Part Three - Strategies
=======================

Remember in our combat sim the Troops units wouldn't engage the Militia units? Well, that's all to do with the strategies, so in this section we'll set this to rights. Open up the Empires\Default\Default_AI_Strategies.txt file. Notice several long paragraphs, starting with the strategy Name and ending with Target Type 33. In each paragraph you'll have to add the Militia unit so that the game knows how enemy units should react.

Starting with the first strategy - Optimal Firing Range - increase the Number Of Target Type Settings to 34. Now find the Target Type of Troop (number 27) and copy these three lines. Paste them at the end of the paragraph and change each of the Target Type numbers to 34. Set the Target Type Name to Militia. You also can change the engage distance and damage amounts if you want. Now go ahead and do the same for each of the other strategies. Save this file and recompile the scripts. Now if you run the combat simulation your troops will attack, just like they should!

Part Four - Design and Construction
===================================

This is where it gets long and involved. It's not that difficult, just time consuming.

We'll start off by adding a bunch of global constants.

Open Script_AI_GlobalConstants.txt and add:
AI_VEHICLE_SIZE_CLASS_MILITIA: long := 13

Open Script_AI_GlobalConstants_Components.txt and add:
AI_COMPONENT_MILITIA: string := "Militia"
Note that this value is the name of the Militia component we added back in part two.

Open Script_AI_GlobalConstants_DesignTypes.txt and add:

  AI_DESIGN_TYPE_MILITIA:                                   string    := "Militia"
  AI_GEN_DESIGN_TYPE_MILITIA:                               string    := "Militia"
  AI_VEHICLE_TYPE_MILITIA:                                  string    := "Militia"

Open Script_AI_GlobalConstants_VehicleSizes.txt and add:

  AI_VEHICLE_SIZE_CLASS_MILITIA:                            long      := 13
  AI_VEHICLE_SIZE_MILITIA:                                  string    := "Militia"

Now we'll tell the AI that the Militia unit exists. Open Script_AI_GlobalSettings.txt. In the very first function, AI_Set_Vehicle_Sizes, search for the string "troop". You should come to a section with the first line:
if (bool_Race_Uses_Troops) then
At the end of this section, just before the "endif", add the following:

    call lst_AI_Vehicle_Sizes_Name.add(AI_VEHICLE_SIZE_MILITIA)
    call lst_AI_Vehicle_Sizes_AI_Size_Class.add(AI_VEHICLE_SIZE_CLASS_MILITIA)
    call lst_AI_Vehicle_Sizes_Num_Life_Support.add(0)
    call lst_AI_Vehicle_Sizes_Num_Crew_Quarters.add(0)
    call lst_AI_Vehicle_Sizes_Num_Engines.add(0)

Now find the function AI_Set_Race_Design_Types and scroll down to the line "for index := 1 to 39 do"
Change the 39 to 40 and scroll down to the end of the loop. Add the following just before the "endcase":

      40:
        set ai_design_type       := AI_DESIGN_TYPE_MILITIA
        set vehicle_size         := AI_VEHICLE_SIZE_CLASS_MILITIA
        set role                 := TASK_FORCE_ROLE_CORE
        set add_type             := bool_Race_Uses_Troops 
        set min_amt              := total_colony_count * 20
        set max_amt              := 100000
        set pct                  := 0

Save this and open the file Script_AI_DesignCreation.txt and find the function Create_Specific_Design. Scroll down to the line "case (design_gen_type)". Add the following just before the "endcase":

    AI_GEN_DESIGN_TYPE_MILITIA:
      set ai_design_type := AI_DESIGN_TYPE_MILITIA

Now find the function Set_AI_Design_Type_For_Design. Scroll down to the line "case (design_gen_type)". Add the following just before the "endcase":

      AI_GEN_DESIGN_TYPE_MILITIA:
        set new_ai_design_type := AI_DESIGN_TYPE_MILITIA

Scroll down a couple of lines to "case (vehicle_type)". After the entry for AI_VEHICLE_TYPE_TROOP, add the following:

      AI_VEHICLE_TYPE_MILITIA:
        set new_ai_design_type := AI_DESIGN_TYPE_MILITIA

Find the function Can_Create_Design_Type_Of_Type and find the line "case (ai_design_type)". Add the following just before the "endcase":

      AI_DESIGN_TYPE_MILITIA:
        set comp_name := AI_COMPONENT_MILITIA

Now we'll make the AI add components to the design. Find the function Add_Components_To_Design. Scroll down until you find the section that adds the Primary Weapon. Add the following:

  if (continue_design) then
    if (ai_design_type = AI_DESIGN_TYPE_MILITIA) then
      set comp_id := Get_Best_Component_Of_Type(AI_GEN_COMP_TYPE_SMALL_PRIMARY_WEAPON)  
      if (comp_id > 0) then
        set comp_enh_id := Sys_Get_Best_Comp_Enh_For_Component(sys_long_Player_ID, design_id, comp_id)
        set comp_tonnage := Sys_Get_Component_Tonnage_Space(sys_long_Player_ID, comp_id, comp_enh_id)    
        set num_to_add := 1
        call Add_Components_To_Vehicle_Design(design_id, comp_id, comp_enh_id, SHIP_SECTION_OUTER_HULL, num_to_add, FALSE)
      else 
        set continue_design := FALSE
      endif 
    endif
  endif

Find the function Add_Required_Components_To_Design and scroll down to the section "Add required components for Units". Add the following to this section:

    if (vehicle_type = AI_VEHICLE_TYPE_MILITIA) then
      set comp_id := Sys_Get_Component_With_Name(sys_long_Player_ID, AI_COMPONENT_MILITIA)  
      if (comp_id > 0) then
        set comp_enh_id := Sys_Get_Best_Comp_Enh_For_Component(sys_long_Player_ID, design_id, comp_id)
        call Add_Components_To_Vehicle_Design(design_id, comp_id, comp_enh_id, SHIP_SECTION_INNER_HULL, 1, FALSE)
      else
        set bool_continue_design := FALSE
      endif 
    endif

Save and exit this file. Compile and install the scripts and start a new game. Try creating a militia unit using the autocomplete function - your minister should now design a valid Militia unit. End the turn and use the cheat code that allows you to view enemy designs. You should see that all the AI empires are also designing valid Militia units. Use the cheat that gives you all technologies and try to autocomplete a new Militia unit. What's this - no weapon? What happened is that the AI wants to use the same weapons we put on our Troops, but we restricted our Militia to just depleted uranium cannon and ground cannon. There's two things we can do - either allow Militia to mount any weapon, or tell the AI which weapons it is allowed to use on a Militia hull.

Open the file Script_AI_GlobalConstants_Components.txt. About two thirds of the way down, in the section full of AI_GEN_COMP_TYPE lines, add the following:
AI_GEN_COMP_TYPE_MILITIA_WEAPON: long := 19

Save and exit this file. Open up the file Script_AI_GlobalVariables.txt. Look for the three lists that start off with lst_Primary_Weapon_Small. Copy these and change Weapon_Small to Weapon_Militia, thus:

  lst_Primary_Weapon_Militia_Name:                            stringlist     
  lst_Primary_Weapon_Militia_Tech_Area:                       stringlist 
  lst_Primary_Weapon_Militia_Tech_Level:                      longlist

Save and exit this file.

You'll have to add a list to the AI script for each race. In each [EmpireName]_Main_Script.txt file, search for the function Set_Race_Research_Areas and add the following (it's a good idea to add it somewhere near the Primary_Weapon_Small lines in order to keep things nice and neat):

  call lst_Primary_Weapon_Militia_Name.add("Ground Cannon")
  call lst_Primary_Weapon_Militia_Tech_Area.add(AI_TECH_AREA_TROOP_WEAPONS)
  call lst_Primary_Weapon_Militia_Tech_Level.add(1)
  call lst_Primary_Weapon_Militia_Name.add(AI_COMPONENT_SMALL_DEPLETED_URANIUM_CANNON)
  call lst_Primary_Weapon_Militia_Tech_Area.add(AI_TECH_AREA_PROJECTILE_WEAPONS)
  call lst_Primary_Weapon_Militia_Tech_Level.add(1)

Note the order in which these components are listed. The design minister will try to add the item on top of the list first, and will scroll through the items one by one until it finds an available component (ie one which has been researched).

Once you've added the list to all the Main_Script files, go back to the Script_AI_DesignCreation.txt file and go back to the paragraph that adds the Primary Weapon (above, in the function Add_Components_To_Design). Change Get_Best_Component_Of_Type(AI_GEN_COMP_TYPE_SMALL_PRIMARY_WEAPON) to Get_Best_Component_Of_Type(AI_GEN_COMP_TYPE_MILITIA_WEAPON).

Now find the function Get_Best_Component_Of_Type. Add the following just before the "endcase":

    AI_GEN_COMP_TYPE_MILITIA_WEAPON:
      set final_comp_id := Get_Wanted_Component_From_List(lst_Primary_Weapon_Militia_Name)

Save this file and recompile the scripts. Start a new game with all technology and design a Militia unit using the autocomplete function. Now you have a weapon - the Ground Cannon.

And that is that - you've now succesfully created a new unit type and told the AI that it exists and how to design it. Now it's up to you to start experimenting. Try resetting the unit to use the Troop primary weapon and allow all small weapons to be placed on Militia hull. Now each AI will design a different Militia depending on their racial preferences - some will have anti-proton beams or meson blasters, for example. Good luck and keep modding!