Halo Wars: Definitive Edition

Create a Leader

Connect the leader, technology, starting army and artwork.

A leader belongs to a civilization. The civilization supplies its shared technology and UI. The leader supplies its starting army, resources, powers and leader-specific technology.

For a custom faction using UNSC or Covenant mechanics, start with a new leader under that existing civilization. A separate civilization needs additional setup.

Files You Need

First follow Getting Started to extract files, convert XMB to XML and configure ModManifest.txt.

File inside your mod	What to edit
root/data/leaders.xml	Leader entry, starting army, resources and artwork references.
root/data/techs.xml	Leader bonuses, unlocks and research.
root/data/stringtable-en.xml	English names and descriptions. Update other languages you support too.
root/data/objects.xml	Building commands and custom objects, when needed.
root/data/squads.xml	Custom squads, when needed.
pregameUI/art/ui/flash/pregame/leaderpicker/leaderpicker.gfx	Picker layout, if adding more slots than the current movie supports.

Copy the complete XML files from the version of the game or mod you are extending. Add entries inside their existing root elements. These files replace tables; a file containing only your new entry would remove the other entries.

Keep edited XML in your mod folder, not the extracted reference folder. Avoid stale XMB copies of the same edited files in the mod.

1. Copy A Playable Leader

In leaders.xml, duplicate the complete Cutter entry for a UNSC leader, or a playable Covenant leader for a Covenant leader. Do not copy Gaia, a test leader or a random selection entry.

For this guide, use the internal leader name mod_Commander and technology name mod_LeaderCommander.

Change these fields in the copied entry:

<Leader Name="mod_Commander"
        Icon="ui\game\icon\unsc\leader\Captain Cutter"
        LeaderPickerOrder="9"
        StatsID="-1"
        DefaultPlayerSlotFlags="0x0">

<Civ>UNSC</Civ>
<Tech>mod_LeaderCommander</Tech>
<NameID>900000</NameID>
<DescriptionID>900001</DescriptionID>
<FlashCivID>0</FlashCivID>

These are replacements inside the copied leader, not a complete leader definition. Keep its other fields and closing tag.

• Use an unused internal name and picker order. Order 9 is an example for an otherwise stock list.
• Remove Test="true" if present. Test leaders are excluded from the normal picker.
• Do not set Random="true" on a playable leader.
• Use 0 for the stock UNSC picker style or 1 for Covenant. 2 is the stock random style.
• DefaultPlayerSlotFlags chooses lobby defaults. It does not unlock technology or make the leader visible.

StatsID="-1" skips leader-specific profile records. If you need those records, assign a unique StatsID and keep the total number of leaders with a StatsID within the stock ten-record capacity. Keep existing StatsIDs stable across mod updates.

LeaderPickerOrder is stored as a signed byte. Use nonnegative values up to 127. A missing or negative order excludes the entry from the normal DE picker.

2. Give The Leader Its Technology

In techs.xml, duplicate the complete unsc_LeaderCutter technology. Rename the copy to mod_LeaderCommander and give the copy an unused DBID.

Keep these initialization settings:

<ResearchPoints>0</ResearchPoints>
<Status>UNOBTAINABLE</Status>
<Flag>Shadow</Flag>

Keep the copied effects initially. This gives the new leader a known starting setup. Replace the bonuses and unlocks after the first version works.

At the start of a new match, the game activates:

1. The selected civilization's CivTech, such as unsc_basic.
2. The selected leader's Tech, such as mod_LeaderCommander.

UNOBTAINABLE does not prevent that starting activation. It prevents the initialization technology from becoming ordinary research. Do not make a Shadow initialization technology generally obtainable without prerequisites, or it can apply to unintended players.

A leader's name, portrait or starting squad does not activate a technology. The <Tech> reference must resolve to the intended definition.

Unlock A Unit Or Building

A trainable unit needs all of these:

• An enabled object or squad definition.
• A building that the player can reach and construct.
• The appropriate TrainSquad, TrainUnit or Build command on that building.
• An available command and satisfied technology requirements.

For example, replace Cutter's Elephant with the existing Cyclops. First remove the copied leader technology's three CommandEnable effects for unsc_veh_elephant_01. Cyclops, Gremlin and Elephant share headquarters wheel position 2, so enabling two together creates a slot conflict.

Then put these effects inside your leader technology's <Effects>:

<Effect type="Data" amount="1" subtype="Enable" relativity="Absolute">
  <Target type="ProtoSquad">unsc_inf_cyclops_01</Target>
</Effect>
<Effect type="Data" amount="1" subtype="CommandEnable"
        commandType="TrainSquad" CommandData="unsc_inf_cyclops_01"
        relativity="Absolute">
  <Target type="ProtoUnit">unsc_bldg_command_01</Target>
  <Target type="ProtoUnit">unsc_bldg_command_02</Target>
  <Target type="ProtoUnit">unsc_bldg_command_03</Target>
</Effect>

ProtoSquad refers to squads.xml. ProtoUnit refers to an object in objects.xml. Match the command type to what the building actually trains.

CommandEnable changes an existing command. It does not add one. For a custom unit, add the command to the producing building too, and cover its upgraded or replacement versions.

If you want both Elephant and Cyclops, move one command to a free position on each headquarters definition instead. Remove inherited Elephant research unlocks too if the leader no longer uses that unit.

Unlock Leader-Specific Research

1. Duplicate an existing research technology with the behavior you want.

2. Give it an unused name and DBID. Update its text and icon.

3. Keep its normal research costs, duration and OBTAINABLE status.

4. Add your leader initialization technology to its prerequisites:

   <Prereqs>
     <TechStatus status="Active">mod_LeaderCommander</TechStatus>
   </Prereqs>

5. Preserve any earlier upgrade prerequisites inside that same <Prereqs> element.

6. Add a Research command referencing the new technology to the intended building. Choose a free command-wheel position.

7. If another technology disables that command, enable it in your leader technology with CommandEnable, commandType="Research" and the matching CommandData.

Prerequisites normally require every listed technology. A copied OrPrereqs flag changes that to any listed prerequisite. Remove that flag when the leader technology must always be required.

An active prerequisite makes research eligible. It does not research the upgrade for free. Conversely, an effect with type="TechStatus" makes its target technology obtainable; it does not directly finish that research.

Leader Powers

Keep the copied power setup for the first version. To replace it, update the leader technology's GodPower effects and the matching definitions in root/data/powers.xml and their referenced power files.

Covenant hero powers also depend on the hero object, its abilities, tactics and the civilization's PowerFromHero setting. A portrait change or a <Power> entry alone does not create that setup.

3. Add Names And Descriptions

Add these entries inside the existing <Language> element in stringtable-en.xml:

<String _locID="900000" category="Leaders" subtitle="false">My Commander</String>
<String _locID="900001" category="Leaders" subtitle="false">Describe the leader's units, power and bonuses.</String>

The numbers are examples. Check that they are unused in your complete mod. Set NameID and DescriptionID to the chosen numbers. Research technologies use DisplayNameID, RolloverTextID and, when needed, PrereqTextID.

4. Set The Starting Army

Edit the copied leader's existing fields:

Field	Meaning
Resource Type="Supplies"	Starting supplies.
Resource Type="Power"	Starting power value.
StartingSquad	A squad from squads.xml, with an optional offset and fly-in setting.
StartingUnit	An object from objects.xml.
BuildOther on StartingUnit	The object built on the starting socket. Keep the socket and headquarters compatible.
Pop	Starting population cap and maximum for that population type.
RepairRate, RepairDelay, RepairCost, RepairTime	Repair settings.

Adding a starting squad only spawns it. It does not make that squad trainable later.

5. Change The Images

The leader uses separate images for separate screens:

XML field	Where it appears	Stock Cutter image
FlashPortrait	Leader picker portrait.	art/ui/flash/shared/textures/pregame/leaderimages/cutter.ddx
UIControlBackground	Leader banner in the player lobby.	art/ui/flash/shared/textures/leaders/leaderpict_cutter.ddx
Icon attribute	Legacy leader icon reference.	Keep the copied reference until you replace that asset too.
FlashImg	Legacy Flash label.	Does not replace the portrait path.

The stock picker portrait is 512 × 512. The Cutter lobby banner is 768 × 192. Keep the copied image's dimensions and alpha layout for the first replacement.

1. Copy the stock image to a new filename.

2. Edit it with a DDS-capable image tool. Export valid texture data, not a PNG renamed to .ddx.

3. Put the new file in your mod at the matching resource path.

4. Change the relevant leader field, keeping img://:

   <FlashPortrait>img://art\ui\flash\shared\textures\pregame\leaderimages\my_commander.ddx</FlashPortrait>
   <UIControlBackground>img://art\ui\flash\shared\textures\leaders\leaderpict_my_commander.ddx</UIControlBackground>

The stock portrait is in pregameUI.era; the stock lobby banner is in inGameUI.era. Mirror those archive folders in your mod and add each used folder to ModManifest.txt. The XML resource paths do not include pregameUI or inGameUI.

Changing these texture references does not require editing the picker GFX.

6. Make Room In The Picker

The shipped picker contains nine placed leader slots, including random choices. Adding XML entries does not create extra movie slots.

DE passes the configured leader list to the movie. Nine is the shipped layout's slot count, not a general nine-leader limit on the XML table.

Use the Scrubb Edition Dev 2.0 dynamic leader picker to add leaders without rebuilding the GFX for each roster change:

Download the dynamic leader picker

The package contains the development build's picker and matching input file, hosted on Cloudflare R2. It creates portrait slots from the configured leader list, scrolls and wraps selection, and keeps the Scrubb description-panel layout. It is dynamic, not literally unlimited; DE's native limits still apply.

1. Back up your existing picker and input file.
2. Extract the ZIP into your mod folder, preserving these paths:

pregameUI/art/ui/flash/pregame/leaderpicker/leaderpicker.gfx
root/art/ui/flash/pregame/leaderpicker/leaderpickerinput.xml

3. Include both the mod's root and pregameUI folders in ModManifest.txt.
4. Keep the installed game's leaderpickerdata.xml and shared UI resources available.
5. Add or remove entries in leaders.xml, then restart the game.

The package does not replace your leader roster, technology or civilization tables. The input file supplies keyboard, controller and mouse-wheel navigation. Check those controls after installation, especially if your mod changes input bindings.

For custom layouts, the companion leaderpickerdata.xml exposes the movie's functions; it is not another leader roster. Preserve functions such as initLeaders and loadLeader, the matching slot instance names and navigation behavior.

Check The Result

Restart the game after changing these tables. Start a new skirmish; loading an old save does not repeat starting technology activation.

• Select the leader with mouse and controller. Check its name, description, portrait and lobby banner.
• Confirm the starting headquarters, squads, supplies and population.
• Train the unlocked unit at each headquarters level.
• Confirm the unique research is available only to this leader and applies its effect after research.
• Check powers, then repeat with an unchanged leader to catch shared unlocks.
• Check AI behavior separately. Custom names and new units do not automatically receive an AI build plan.

Problem	Check
Leader missing	Test, Random, picker order, loaded XML and available GFX slots.
Leader appears but has no bonuses	<Tech> name and the initialization technology's effects.
Unit spawns but cannot be trained	Producing building, command, command enable state and unit/squad enable state.
Research missing	Prerequisites, command, command enable state and the correct building version.
Wrong or blank image	Correct portrait versus banner field, texture format, resource path and archive folder.
AI does nothing useful	data/triggerscripts/skirmishai.triggerscript and referenced data/aidata/*.ai tables.