From Wargroove Wiki
Jump to: navigation, search
Wargroove header modding.png

Modding is in beta, so please ask questions on Discord and report bugs to the support forums.

This documentation details what's involved with setting up and implementing mods for Wargroove. Guide credit goes to Chucklefish programmer Caryn Krakauer

A lot of documentation refers to the “Tolstoy” mod. Tolstoy is a dog, not the famous Russian author.

Mod Usage[edit]

Before using any mods, especially during the modding beta, make sure to back up your save files! They're likely located at %APPDATA%\Chucklefish\Wargroove\save\

Mod File Location[edit]

Mods are stored in your application folder, which is probably at %appdata%\Roaming\Chucklefish\Wargroove\mods. My folder with the example mods looks like this:

Modding Guide 2.png

Each folder contains the .dat files for the individual mod.

The EXE and example mods are located at C:\Program Files (x86)\Steam\steamapps\common\Wargroove\modpacker_bin

Using Mods in Maps[edit]

Mods are per map/campaign and can be selected on map creation and on map selection. In addition, maps can be packaged along with mods or used separately.

Adding Mods to a Map[edit]

Create a map as normal. In the map editor menu, select the “mods” option. This will bring up the list of currently available mods. When selecting “save and reload map” this will also remove any broken units and tiles, such as if a unit type no longer exists that was placed on the map.

Using a Mod on an Unmodded Map[edit]

Mods can be used on any skirmish map. In the ‘Match Settings” view when setting up the map, select the “mods” option and you will be given the list of mods. The user can turn on new mods and also turn off currently active mods. If any changes would break the map (such as a unit type being removed that is placed on the map) the changes to mods will revert.

Updating a Modded Map[edit]

If a mod that a map relies on is updated, the map also needs to be updated. If the map is part of the mod this happens automatically on packing the mod. If not, the next time the map is opened for edit the game will ask which mods should be updated. If a mod is not updated, it will remove all units and events that rely on the mod. It’s a good idea to back up a map before updating a mod.

Using Mods Online[edit]

Maps that are packaged within mods can be used for online play. These maps can be used online if and only if all players have the same version of the mod installed.

Mod Creation: Requirements[edit]

Mods use a combination of Yaml, Lua, art, and sound files. It's definitely advisable to be familiar with the Yaml format, and Lua if there's any scripting. In addition, animations are done using Aseprite which is paid software (but very much worth it!).

Aseprite is available from their website ( along with, Humble Bundle, Steam, and Gumroad. Mod Creation: Configuration The basic steps are:

  1. Create a mod manifest file with basic information
  2. Create configuration, art, and sound files
  3. Package the mod
  4. Create maps that use the mod
  5. Package the mod to include the maps
  6. Give the mod to internet friends!

Mods are created from a collection of yaml files, lua files, image files, and sound files. Once a mod is created and added to a user’s game, they can create new maps/campaigns using the mod and apply the mod to existing maps/campaigns.

We have included a few example mods as well as a lot of example config files, lua files, and some image assets. The easiest way to get started is to take a look at these examples while going through this document.

The basic structure of a mod looks like this:

- assets_src
  - audio
    - music
    - sfx
  - audio_event
  - config 
    - gameplay
      - triggers
        - actions.yaml
        - conditions.yaml
      - units
    - strings
  - image
    - palettes
    - portraits
      - _dir.meta
    - ui	
    - units
      - _dir.meta
  - lua
    - initialized
- manifest.yaml
# The top level folder
# Contains all assets
# Audio files

# Audio configuration files
# General Configuration files
# Gameplay Configuration files
# Yaml files for the event system

# Yaml files for units
# Yaml files for translated strings
# Art
# The Wargroove palette
# Unit/commander portraits
# Sets portraits to use the Wargroove palette

# Art for units map/battle animations
# Sets units to use the Wargroove palette
# Lua scripts folder
# Special Lua files that are initialized
# Information about the mod

Creating the Mod Manifest File[edit]

The manifest.yaml file at the root of the mod folder determines the mod’s general settings. The fields are:

  • id: The id of the mod. This should be unchanging for all versions of your mod as the id is what the game uses to determine if two mods are the same mod but with different versions. This should also be relatively unique, as two mods with the same id will clash.
  • name: This is the name that players will see when they load the mod into their game. This does not have to stay the same throughout versions of the mod and does not have to be unique (although it probably should be to avoid confusion).
  • description: This is the description that players will see when they load the mod into their game. This does not have to stay the same throughout versions of the mod and does not have to be unique (although it probably should be to avoid confusion).
  • remove: A group of assets to remove from the map when using this mod. The three types of assets that can be removed are commanders, units, and factions.

Example from tolstoy_mod’s manifest.yaml:


id: TolstoyMod
name: "Tolstoy's Mod"
author: "TolstoyFan1"
description: "Adds My Tolstoy to the game which is the feature we've all been waiting for!
    - mercia
    - soldier
    - felheim



Maps can be packaged along with mods for distribution. In order to do this, the map must use no other mods. If a map uses multiple mods, it needs to be distributed separately from the mod.

While editing the map, go to the mods settings. Next to the mod you want to add the map to press “add to mod”. This will remove other active mods. Note, this means that you have to create the mod first (or at least an initial skeletal framework). Once a map is part of a mod it will be updated automatically with the mod.

The next time wargroove_mod_packer.exe is run, the map will be automatically packaged along with the mod. You should see them in the assets_src/maps folder after packaging.


Units are made up of multiple parts:

  1. Unit Class Configuration
  2. Unit Configuration
  3. Weapons Configuration
  4. (optional) Commander Configuration
  5. Art and sound effects

For example, the soldier unit has a unit class config of “soldier” and individual unit configurations for each faction (Cherrystone, Floran, Heavensong, Felheim). It also has the weapon “sword”. Various art and sounds are referred to in the configuration file.

Typically, we store the weapons, unit class, and unit configuration in a single file.

Unit Class Configuration[edit]

The unit class defines the information that all soldiers share, such as their cost, movement, and weapons.

 - id: soldier
   name: unit_class_name_soldier
   cost: 100
   movement: walking
   moveRange: 4
   damageMultiplier: 1
   aiPriority: 1.0
     - id: sword
     - capture
     - load
     - soldier
     - type.ground.light
   battleUnitCount: 4
   passiveMultiplier: 1.5

To use a new unit icon, the unit class must define the classIconSpritesheet. The value is ui_<ModId> where ModName is the id of the mod. For example, in the Tolstoy mod, the line is: classIconSpritesheet: ui_TolstoyMod.

Expand for a complete list of unit ids implemented in game

Unit Configuration[edit]

The unit defines information that is faction specific, such as the name, animations, and sounds.

[This example has been shortened slightly where there are ellipses.]
 - class: soldier
   faction: cherrystone
   name: unit_name_soldier_cherrystone
   mapAnimation: units/soldier/cherrystone/map_soldier_cherrystone
   battleAnimation: units/soldier/cherrystone/battle_soldier_cherrystone
   battleAnimationRiver: fx/river_overlay/battle_soldier_cherrystone_river
   smallPortrait: units/soldier/cherrystone/portrait_soldier_cherrystone_small.png
   mediumPortrait: units/soldier/cherrystone/portrait_soldier_cherrystone_medium.png
   mapSpeed: 4.0
   grabPos: [13, 14]
     attack: soldierAttackRed
     attackShout: soldierPreAttackRed
     attackMap: unitAttack
     captureShout: soldierPreAttackRed
     death: soldierDieRed
     deathMap: unitDie
     run: infantryHeavyEntry
     runMap: infantryHeavyMapEntry
     hit: hitOrganic
     hitMap: hitOrganic
     - id: primary
       hitSpark: fx/bs_stab_attack
       hitDelay: [0.45, 0.8]
     soldier_shout1: soldierShoutRed1
     soldier_shout2: soldierShoutRed2
     soldier_shout3: soldierShoutRed3
     soldier_hit1: soldierHitRed1
     soldier_hit2: soldierHitRed2
     soldier_hit3: soldierHitRed3
     crownbearer_panting: cutscene/crownbearerPanting
     crownbearer_yell: cutscene/crownbearerYell
     idle: idle
     idle_crownbearer: idle_crownbearer
     idle_crown: emote_idle_crown
     idle_crown_ragged: emote_idle_crown_ragged
     cushion: emote_cushion
     - id: run_crown

Weapon Configuration[edit]

The weapon defines information relevant to combat, such as damage, range, and restrictions.

 - id: sword
   rangeMin: 1
   rangeMax: 1
   canMoveAndAttack: true
     land: 1
     archer: 0.65
     soldier: 0.55
     villager: 0.55
     spearman: 0.35
     dog: 0.45
     wagon: 0.35
     knight: 0.15
     trebuchet: 0.3
     merman: 0.55
     mage: 0.55
     structure: 0.35
     commander: 0.10
     ballista: 0.35
     giant: 0.05

Adding/Modifying a Unit Class[edit]

Units can be added, modified, or completely overwritten.

Adding a Unit[edit]

A unit can be added by creating a unit with a new id. An example in the Tolstoy mod is assets/art/config/units/commander_tolstoy.yaml. A unit needs the four basic components of a unit class configuration, unit configurations, and any weapons. In addition, new art and sounds can be used.

Modifying a Unit Class[edit]

To only change part of a unit (for example, to add the “pet” verb to soldiers”), instead of creating a new entry in “unitClasses”, a new entry in the “modifyingUnitClasses” is created with the id of the modified class.

 - id: soldier
   # replace:  # This replaces the sections, so the soldier can only pet
   #   verbs:
   #     - pet
       - pet   # This adds “pet” to the soldier verbs
   # remove:
   #   verbs:
   #     - capture # This removes

Sections in “modifyingUnitClasses” are replace, add, and remove. Under these, the categories refer to the categories in the unit class table.

Overwriting a Unit[edit]

To completely overwrite a unit, it’s the same process as adding a new unit. If the id is set to an existing unit (such as “soldier”), then it will overwrite the existing configuration.

Adding/Modifying a Commander[edit]

Commanders are units with additional configuration files and art/sound assets. The additional configuration files that need to be created are:

  1. A commander configuration under config/gameplay (see example: tolstoy_mod/assets_src/config/gameplay/commanders.yaml)
  2. A groove configuration under config/gameplay (see example: tolstoy_mod/assets_src/config/gameplay/grooves.yaml)
  3. A verb configuration for the commander’s groove under config/gameplay (see example: tolstoy_mod/assets_src/config/gameplay/verbs.yaml)

Adding a Faction[edit]

Factions are defined in assets_src/config/gameplay/factions.yaml.

Example: tolstoy_mod/assets_src/config/gameplay/factions.yaml
 - id: tolstoy                    # The faction id
   name: faction_name_tolstoy     # The visible name of the faction
   stdColour: blue                # The default colour of the faction
   altColour: yellow              
   # The colour of the faction is the default is not available
   skinColours: [ "typeII", "typeIII", "typeIV", "typeV", "typeVI" ]
   # The skin colours of units in the faction

Once a new faction is added, units can have their faction set to the new faction in the configuration files.

Biomes and Terrain[edit]

Adding a Biome[edit]

A biome has two components.

  1. Biome config: This has the basic information of a biome (see biome_mod/assets_src/config/gameplay/tilesets/grass2.yaml)
  2. Tilesets: Tilesets can be added to a biome in two different ways. Either a new tile needs to be created, or an appending tileset configuration can be created.
  1. New tileset: see “Adding a Terrain Tile” below
  2. Appending tileset: For a new biome, it’s possible to add existing tile types. See biome_mod/assets_src/config/gameplay/tilesets/grass2.yaml. In this, the grass2 biome is being added to all existing tile types. In the example it uses the default grass images but these can be changed.

Adding a Terrain Tile[edit]

See example terrain_mod/assets_src/config/gameplay/tilesets/flowers.yaml.

Lua Scripts[edit]

All Lua files must exist under assets_src/lua/. Lua files under assets_src/lua/initialized will have init() called on them. This can be used for setting up conditions and actions as well as replacing game functions.

Custom Events (Conditions and Actions)[edit]

Events are made up of conditions and actions. Conditions and actions have three components:

1. Yaml Configuration: This specifies the name of the event and parameter types.
2. Lua File: This specifies the actual actions and rules of the event. This file must have an init() function and be in the folder assets_src/lua/initialized.

3. Strings: Each event has three strings. A name, a description, and a “readable” description. The readable description has places for user chosen values.
Example readable strings:
“Add set state {3} to {4} for unit type(s) {0} at location {1} owned by player {2}.” becomes “Add set state cute to ‘true’ for unit type(s) ‘dog’ at location ‘any’ owned by player ‘1’.”

Modifying Existing Lua[edit]

Existing lua systems (such as the combat system) can be modified with initialized lua files. See example tolstoy_mod/assets_src/lua/initialized/combat.lua.

Critical Hit Conditions[edit]

In Wargroove, critical hit conditions are called “passive conditions”. Each unit type has one; for example, the soldier does a critical hit when they are standing next to their commander. Adding a new condition works the same as modifying existing lua. See tolstoy_mod/assets_src/lua/initialized/passive_conditions.lua.


Verbs are actions that units can take, such as attack, capture, and reinforce. Verbs have three components:

1. Yaml Configuration: This specifies the name of the verb, the lua file associated with it, and various parameters such as splash radius, the icon, and colours.
2. Lua File: This is what is actually run when a verb is used. This is also where AI rules for using the verb are specified.
3. String: A verb has a name associated with it.


Grooves are essential special verbs used by commanders. The only difference is an additional groove configuration. Grooves have four components:

1. Groove yaml configuration: this has information such as groove charge time and the associated verb.
2. Verb yaml Configuration: This specifies the name of the groove’s verb, the lua file associated with it, and various parameters such as splash radius, the icon, and colours.
3. Lua File: This is what is actually run when a verb is used. This is also where AI rules for using the verb are specified.
4. String: A verb has a name associated with it.


The Tolstoy mod has examples of these.

  • Sound Effects: defined in config/gameplay/cutscene/cutscene_sfx.yaml
  • Visual Effects: defined in config/gameplay/cutscene/cutscene_vfx.yaml
  • Props: defined in config/gameplay/cutscene/cutscene_props.yaml
  • Backgrounds: defined in config/gameplay/cutscene/cutscene_backgrounds.yaml
  • Shouts: defined in the unit class configuration file for the unit with the shout.
  • Emotes: defined in the unit class configuration file for the unit with the emote.
  • Alternative run: defined in the unit class file for the unit with the run. This is for characters who might have different versions of their runs, for example Sigrid has a regular run and a float.
  - class: commander_tolstoy
      - id: run_sniff  # Refers to a tag in the battle .ase file
        sound: sniff   # Can set an alternative run sound
  • Cutscene idle: If your character has an alternative idle that you want to use in cutscenes. For example, in cutscenes Caesar does not have his crossbow soldiers.
  - class: commander_tolstoy
    cutsceneIdle: capture_idle  # Tag in the battle ase file
  • Cutscene pre-idle: If your character has a pre-idle animation that you want to include in the cutscene (or want to not use the regular combat pre-idle animation). This can be set to nothing. For example, Caesar doesn’t do his battle pre-idle in cutscenes (as it has crossbow soldiers).
  - class: commander_tolstoy
    cutscenePreIdle: "" # None (or a tag in the battle .ase file)
  • Cutscene hit: If your character has a hit animation you want to use in the cutscene. For example, Caesar doesn’t do his battle hit in cutscenes (as it has crossbow soldiers).
  - class: commander_tolstoy
    cutsceneHit: hit_foot  # A tag in the battle .ase file

Removing Units, Commanders, and Factions[edit]

In order to remove units, commanders, and factions they must be specified in the mod’s manifest.yaml file.

id: TolstoyMod
name: "Tolstoy's Mod"
description: "Adds Tolstoy to the game which is the feature we've all been waiting for."
   - mercia
   - soldier
   - felheim

This mod removes Mercia as a commander, the Soldier unit, and the Felhem faction. The remove id matches the id field of the asset being removed.

Game Strings[edit]

In many configuration files, there are references to strings. These strings are keys that refer to a language file, so that translation is easier. For example, in the faction configuration the entry name: faction_name_tolstoy refers to the key “faction_name_tolstoy” that can be found in tolstoy_mod/ssets_src/config/gameplay/strings/en-GB.yaml.

There are a number of supported languages. To add another one to your mod, you just add the corresponding language yaml file in the same folder as the en-GB file. The language files are:

  • de-DE: German
  • en-GB: English
  • es-ES: Spanish
  • fr-FR: French
  • it-IT: Italian
  • ja-JP: Japanese
  • ko-KR: Korean
  • pt-BR: Portuguese
  • ru-RU: Russian
  • zh-Hans: Chinese Simplified
  • zh-Hant: Chinese Traditional


Colours are defined in config/art/colours.yaml. These are referred to by various configuration files, such as tolstoy_mod/assets_src/config/gameplay/verbs.yaml when it refers to target and outline colours.

Mod Creation: Art and Sound[edit]


There are two basic types of art assets in Wargroove, animated Aseprite files and static png files. In addition, an art asset can support palette swapping, which is what happens when commanders change faction colours.

Wargroove Palette[edit]

All art assets that has army or skin colours (such as battle and map unit animations) must use the colours found in the wargroove palette.


The palette has three sections: army colour, skin colour, and other. Colours from the army colour section will be changed depending on the player's chosen army colour. Skin colour will be changed depending on the unit's skin colour. The other colours will never be changed. New colours cannot be added to the palette, as it is full.

Aseprite Files[edit]

In order to create an aseprite file, you have to buy Aseprite (sorry!). It’s really awesome though so you won’t regret it. Animations work with Aseprite tags.

Modding Guide 3.png

The tags are referred to by the game, and can also be referred to in new Lua scripts.

Png Files[edit]

Assets such as portraits and UI are not animated, and thus do not have to be Aseprite files.

Meta Files[edit]

Art files can have a corresponding meta file. The metafile is the same name as the art asset with “.meta” at the end. So for the battle_tolstoy.ase file its meta is battle_tolstoy.ase.meta. The most important purpose of a meta file is to set the pivot of the art asset.

pivotX: 150
pivotY: 86

Palette Swapping[edit]

Some art assets change colours depending on the faction they are assigned to.

For palette swapped images, they must use the colours found in the wargroove palette. Otherwise the packaging step will fail.

Portraits Required
Units Required
Attack Special FX Optional, can be set in a meta file

In the mod, files are set to palette swap by using meta files. For portraits and units, in their folders contain a file named _dir.meta which is generated by the mod packaging tool.

- data:
    palette: image/palettes/wargroove_palette.png
    material: Wargroove/PaletteSwap
    atlas: portraits

This files applies the settings to all files in the directory tree.

The wargroove palette must be in the mod at image/palettes/wargroove_palette.png.

Ranged Attack Special FX[edit]

Optionally, ranged attack effects can be palette swapped. For example, the harpy attack changes colour depending on faction. To support this, the meta file contains instructions to use the palette and the pallete swap material.

pivotX: 145
pivotY: -4
palette: image/palettes/wargroove_palette.png
material: Wargroove/PaletteSwap

Overwriting the Wargroove Palette[edit]

The Wargroove palette can be overwritten, but this will also change the colours used in the rest of the game. To do this, in the manifest.yaml file, add: overwritesPalette: true. This will cause the version of the wargroove palette in image/palettes/ to overwrite the game's default. New palettes must have colours placed in the same location as the old palette.


All sound assets in Wargroove are .ogg format. The game uses them files in 48khz frequency, and it’s recommended to save them at 50% quality VBR to save space. Also save them without any metatag info. For sound effects and voice lines, they should be saved in mono. For music and environmental soundscapes, they should be saved in stereo.


Music .ogg files have a corresponding meta file, which is contained in the same folder is the same name but with a “.meta” on the end. So for campaign.ogg, its meta file is campaign.ogg.meta and specifies that it is streaming and its loop point.

streaming: true
loopPoint: 498462

Music also has two configuration files. One is music.yaml which is under assets_src/config/gameplay/yaml.

  - id: main_theme
    name: music_name_main_theme
    audioEvent: music/main_theme

Another is an audio event configuration under assets_src/audio_event/music.

  - type: play
    clips: [ music/maintheme.ogg ]
    group: music
    loop: true


Sound effects have additional configuration files. Sound effects can be defined in the assets_src/audio_event folder. Configuration files can combine sounds into larger effects. For example, the metaAttack.yaml sound event actually contains three sounds.

  - type: play
    clips: [ sfx/mercia/merciaAttackFoley.ogg ]
    group: sfx
    delay: 0.08
  - type: play
    clips: [ sfx/mercia/merciaAttackVoice1.ogg, sfx/mercia/merciaAttackVoice2.ogg, sfx/mercia/merciaAttackVoice3.ogg ]
    group: voice
    delay: 0.2
  - type: play
    clips: [ sfx/mercia/merciaAttackVoice4.ogg, sfx/mercia/merciaAttackVoice5.ogg ]
    group: voice
    delay: 1.1

Each sound specifies:

  • That it should be played
  • What clips it should use. If more than one is specifies it chooses one at random.
  • What type of effect it is (sfx or voice)
  • When it should play after the audio event starts.

In addition, sounds can have a volume and pitch specified. These are specified by a single value or a range which they can vary between.

  - type: play
    clips: [ sfx/soldierPreAttack1.ogg, sfx/soldierPreAttack2.ogg, sfx/soldierPreAttack3.ogg, sfx/soldierPreAttack4.ogg, sfx/soldierPreAttack5.ogg, sfx/soldierPreAttack6.ogg, sfx/soldierPreAttack7.ogg, sfx/soldierPreAttack8.ogg, sfx/soldierPreAttack9.ogg ]
    group: voice
    pitch: [ 0.9, 1.1 ]
    volume: [ 0.63, 0.7 ]

Mod Packaging and Distribution[edit]


To package a mod, run the executable from your command line.

wargroove_mod_packer.exe <path_to_mod>

The packaged mod will automatically be put into the mods folder of your Wargroove app data which is probably at %appdata%\Roaming\Chucklefish\Wargroove\mods.


At the moment, we have not integrated Steam Workshop so it’s a manual process. Once you have packaged your mod, it will be moved to your application folder, which is probably at %appdata%\Roaming\Chucklefish\Wargroove\mods. The folder that’s created will have the same id as your mod, and can be placed in any user’s mods folder for usage.