Sample Unit Definition

This guide depicts the definition of a unit, to help with modding. This guide assumes you are putting your code in a main.lua file, as in the Dwarven Tunnel and Railroad Gold Mine mod examples. The file can be modified with a text editor, and ideally an advanced one such as Notepad++ should be used.

Unit Definition

When adding a new unit, the most important part is the unit definition itself, which is done with the DefineUnitType function. In our example, we will define a dwarven berserker.

DefineUnitType("unit-dwarven-berserker", {
	Name = "Berserker",
	Parent = "unit-template-infantry", -- this makes it inherit data from the infantry template, you can set it to any unit; the only element that won't be inherited is the unit's civilization (because it would mess up the civilization units table)
	Civilization = "dwarf",
	Class = "berserker", -- it has a different class from "infantry" here (which it otherwise would inherit from the template), so that it doesn't replace the dwarven axefighter in the civilization units table
	Description = "Dwarven berserkers know no match in their battle rage, crushing foes indistinctly in their frenzy. Unarmored, these deadly warriors have protective runes inscribed on their skin." -- the unit's description (this is necessary to make it show up in the encyclopedia)
	Image = {"file", "dwarf/units/dwarven_axefighter.png", "size", {72, 72}}, -- set the graphics here to those you want; keep in mind unit graphics need to be indexed to a palette, so that the player color works correctly
	Animations = "animations-dwarven-axefighter", -- the unit's animation code
	Icon = "icon-dwarven-axefighter", -- the unit's icon
	BasicDamage = 12, -- +3 damage compared to the infantry template, we want the berserker to be more deadly
	Armor = 0, -- -2 armor compared to the infantry template, to compensate for the berserker's damage increase
	Evasion = 9, -- -1 evasion compared to the template, also to compensate for the higher damage
	DefaultEquipment = {
		{"weapon", "unit-battle-axe"},
		{"shield", "unit-round-shield"},
		{"boots", "unit-boots"}
	},
	Corpse = "unit-dwarven-dead-body",
	WeaponClasses = {"axe", "mace"}, -- the weapon classes heroes of this unit type can use
	HackDamage = true,
	AiDrops = {"unit-battle-axe", "unit-broad-axe", "unit-great-axe", "unit-round-shield", "unit-brising-round-shield", "unit-heater-shield", "unit-thrymgjol-shield", "unit-boots", "unit-cheese", "unit-potion-of-healing"}, -- the items you want AI heroes of this unit type to be able to drop
	Sounds = {
		"selected", "basic-dwarf-voices-selected-group", -- sound when the unit is selected
		"acknowledge", "basic-dwarf-voices-acknowledge", -- sound when the unit receives an order
		"attack", "basic-dwarf-voices-attack", -- sound when the unit receives an order to attack
		"ready", "dwarven-axefighter-ready", -- sound when the unit is trained
		"help", "basic-dwarf-voices-help", -- sound when the unit is attacked
		"dead", "basic-dwarf-voices-dead", -- sound when the unit dies
		"hit", "axe-attack", -- sound when the unit hits an enemy
		"miss", "attack-miss" -- sound when the unit misses an enemy
	}
} )

The game's unit definitions are stored in its /scripts/units.lua file, along with the units.lua file for each civilization (in their respective folders in /scripts/civilizations/).

Units Array

Next, it is necessary to add the unit to the "Units" array, which is used for a variety of things, such as the encyclopedia. This is done with the following code:

table.insert(Units, "unit-dwarven-berserker")

Unit Training Button

Finally, a button is needed for the unit to be trained at the dwarven War Hall.

DefineButton( { Pos = 7, Level = 0, Icon = "icon-dwarven-axefighter",
	Action = "train-unit", Value = "unit-dwarven-berserker",
	Key = "k", Hint = _("Train Berser~!ker"), Popup = "popup-unit",
	ForUnit = {"unit-dwarven-barracks"}
} )

Congratulations! You have added a new unit to the game!