Guide:Modding

From Wargroove Wiki
Jump to navigation Jump to search

'


Modding is a beta feature. Please ask questions and report bugs on our Discord.

This documentation details what's involved with setting up and implementing mods for Wargroove and Wargroove 2. Credit for the original guide about Wargroove 1 goes to former 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, make sure to back up your save files! For Wargroove, they're likely located at %APPDATA%\Chucklefish\Wargroove\save. For Wargroove 2, they can be found at %APPDATA%\Chucklefish\Wargroove2\save

Mod File Location[edit]

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

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

The EXE to create mods and the examples are located at C:\Program Files (x86)\Steam\steamapps\common\Wargroove\modpacker_bin and C:\Program Files (x86)\Steam\steamapps\common\Wargroove2\modpacker_bin. This folder also contains subfolders with the sample mod(s) and many of the game's original assets.

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 configuration (YAML), script (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 (https://www.aseprite.org/) along with itch.io, Humble Bundle, and Steam.

Mod Creation: Configuration[edit]

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, LUA, image 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:

mod
- 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

Most of this documentation applies to both Wargroove and Wargroove 2. Some configuration formats have been changed for Wargroove 2 though. Please try to not mix tools and configuration files between both titles, as this will very likely lead to bugs.

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!
remove:                             
  commander:
    - mercia
  unitClass:
    - soldier
  faction:
    - felheim

...

Maps[edit]

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[edit]

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.

unitClasses:
 - id: soldier
   name: unit_class_name_soldier
   cost: 100
   movement: walking
   moveRange: 4
   damageMultiplier: 1
   aiPriority: 1.0
   weapons:
     - id: sword
   verbs:
     - capture
     - load
   tags:
     - soldier
     - type.ground.light
   battleUnitCount: 4
   passiveMultiplier: 1.5
   sightRange: 2                   # Wargroove 2

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 Wargroove
archer
ballista
balloon
barracks
city
commander_caesar
commander_darkmercia
commander_elodie
commander_emeric
commander_greenfinger
commander_koji
commander_mercia
commander_mercival
commander_nuru
commander_ragna
commander_ryota
commander_sedge
commander_sigrid
commander_tenri
commander_valder
crystal
dog
dragon
drone
garrison
gate
ghost_mercival
giant
harpoonship
harpy
hq
knight
mage
merman
port
soldier
spearman
tower
travelboat
trebuchet
turtle
villager
vine
wagon
warship
water_city
witch
Expand for a complete list of unit ids implemented in Wargroove 2
archer
area_combined
area_combined_hidden
area_damage
area_damage_hidden
area_heal
area_heal_hidden
ballista
balloon
band_aid
buff
burn
caravel
commander_caesar
commander_darkmercia
commander_death_gauntlet
commander_elodie
commander_emeric
commander_greenfinger
commander_koji
commander_lytra
commander_lytra_no_harp
commander_mercia
commander_mercival
commander_nadia
commander_nuru
commander_pistil
commander_ragna
commander_ragna_boss
commander_rhomb
commander_rhomb_angry
commander_ryota
commander_sedge
commander_sigrid
commander_tenri
commander_twins
commander_valder
commander_valder_no_glove
commander_vesper
commander_wulfar
commander_wulfar_pirate
crystal
crystal_tier_two
dog
dragon
drone
drone_strong
elder_strength
errol
fortified_garrison
frog
garrison
ghost_mercival
giant
golem_unit
griffin_walking
growth
harpoonship
harpy
healing_sparrow
knight
kraken
low_resonance_music
mage
merman
mine
minicommader_oaracle
minicommander_donut
minicommander_fenris
minicommander_floran_captain
minicommander_hans
minicommander_kraken
minicommander_oddvar
minicommander_oddvar_undead
minicommander_sourcheeks
minicommander_sweetcheeks
minicommander_warship
organ
organ_bomb
organ_up
orla
pistil_ball
pistil_ball_strong
rifleman
roots
shadow_vesper
smoke_producer
soldier
spearman
splinter_fire
stock_trade
tentacle
thief
thief_with_gold
thorny_vine
travelboat
trebuchet
turtle
vesper_boss
villager
vine
vine_boss
wagon
warship
weak_vine
witch

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.]
units:
 - 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]
   sounds:
     attack: soldierAttackRed
     attackShout: soldierPreAttackRed
     attackMap: unitAttack
     captureShout: soldierPreAttackRed
     death: soldierDieRed
     deathMap: unitDie
     run: infantryHeavyEntry
     runMap: infantryHeavyMapEntry
     hit: hitOrganic
     hitMap: hitOrganic
   attacks:
     - id: primary
       hitSpark: fx/bs_stab_attack
       hitDelay: [0.45, 0.8]
   shouts:
     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
   emotes:
     idle: idle
     idle_crownbearer: idle_crownbearer
     idle_crown: emote_idle_crown
     idle_crown_ragged: emote_idle_crown_ragged
     cushion: emote_cushion
     [...]
   alternativeRuns:
     - id: run_crown
     [...]

Wargroove 2 adds a few sections, namely mapLightSource and battleLightSource which defines attributes to be used for rendering light sources on map and in battle scenes.

Weapon Configuration[edit]

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

weapons:
 - id: sword
   rangeMin: 1
   rangeMax: 1
   canMoveAndAttack: true
   baseDamage:
     land: 1
   tagDamage:
     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
     [...]

Wargroove 2 retires the tagDamage section and adds two important properties:

weapons:
 - id: sword
   baseDamage:
     buildings: 1 # base damage against buildings
   tagDamageOverwrite: soldier

In Wargroove 2, the damage values are fetched from a damage matrix (spreadsheet) in config/gameplay/units.csv, using the unit class id. The tagDamageOverwrite property can be used to point to a different unit id instead.

The damage matrix in use by the game can be found at at modpacker_bin/original_assets/config/gameplay/units.csv.

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.

modifyingUnitClasses:
 - id: soldier
   # replace:  # This replaces the sections, so the soldier can only pet
   #   verbs:
   #     - pet
   add:
     verbs:
       - 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)

Wargroove 2 introduces a new unit category called "mini commanders". Mini commanders are strong(er) units that behave like “commanders without a groove”.

Adding a Faction[edit]

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

Example: tolstoy_mod/assets_src/config/gameplay/factions.yaml
factions:
 - 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 in Wargroove 1[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 in Wargroove 1[edit]

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

Biomes and Terrain in Wargroove 2[edit]

There have been major changes in Wargroove 2 about how biomes, terrain and tile sets work. Wargroove 2 uses a system called "Wang tilesets" which allows for a high number of variations in connecting tiles with each other, by using a relatively small number of base tiles and an equally small but non-trivial number of rules to automate those connections.

In another big change, some of those tilesets are now layered on top of each other to blend ground tiles with beaches, rivers and ocean, and other types of terrain.

Unfortunatly, this system makes it anything but straightforward for modding. Configuration and tilesets are assembled from a few different places:

  1. original_assets/config/gameplay/biomes.yaml stores a list of biomes with their main properties
  2. original_assets/config/gameplay/tilesets/ contains a list of configurations, one YAML file per type of terrain. Each of them lists which tilesets are used, per biome, for this terrain type.
  3. The tilesets themselves can be found at original_assets/image/terrain/tilesets/. Just open any of them in Aseprite.
  4. Tilesets usually contain one frame with the actual colours, one for storing masks used for water rendering, and one which is used for rendering the "paper border" area around maps.
  5. Some terrain types, like mountains and forest, still use the old system from Wargroove 1.
  6. Tip: most tileset sprite sheets contain a disabled layer showing the basic layout the (Wang) tiles use.

Each biome uses a number of those tileset sprite sheets. They all follow a naming convention, e.g. wang_[biome]_[terrain]{_[blend]}_tileset.ase.

  1. wang_[biome]_plains_sea_tileset is the "main" tileset, containing the base tiles for combining plain and water terrain.
  2. wang_[biome]_plains_beach_tileset is layered on top, and is used to blend beach tiles with plains and water tiles around them.
  3. All other sheets are used to render other types of terrain - reefs in ocean, bridges atop of rivers or ocean, roads atop of plains and so on.

A fair bit of warning: while it may be possible to alter the layout and/or variations inside those Wang tilesets, we highly recommend to *not* try that. The whole system is a bit fragile - especially the auto-tiler used by the map editor does some assumptions about them. It's better to stick with their layout as-is, and use them as a paint-over template.

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.
Examples:
tolstoy_mod/assets_src/config/gameplay/triggers/actions.yaml
tolstoy_mod/assets_src/config/gameplay/triggers/conditions.yaml
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.
Examples:
tolstoy_mod/assets_src/lua/initialized/actions.lua
tolstoy_mod/assets_src/lua/initialized/conditions.lua


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’.”
Examples:
tolstoy_mod/assets_src/config/strings/en-GB.yaml

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[edit]

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.
tolstoy_mod/assets_src/config/gameplay/verbs.yaml
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.
tolstoy_mod/assets_src/lua/lua_mod/verbs/pet.lua
3. String: A verb has a name associated with it.
tolstoy_mod/assets_src/config/strings/en-GB.yaml

Grooves[edit]

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.
tolstoy_mod/assets_src/config/gameplay/grooves.yaml
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.
tolstoy_mod/assets_src/config/gameplay/verbs.yaml
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.
tolstoy_mod/assets_src/lua/lua_mod/verbs/groove_tolstoy.lua
4. String: A verb has a name associated with it.
tolstoy_mod/assets_src/config/strings/en-GB.yaml

Cutscenes[edit]

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.
units:                                                                      
  - class: commander_tolstoy
    alternativeRuns:
      - 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.
units:                                                                      
  - 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).
units:                                                                      
  - 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).
units:                                                                      
  - 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."
remove:
 commander:
   - mercia
 unitClass:
   - soldier
 faction:
   - 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/assets_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 (Wargroove 1 only)
  • ja-JP: Japanese
  • ko-KR: Korean (Wargroove 1 only)
  • pt-BR: Portuguese
  • ru-RU: Russian
  • zh-Hans: Chinese Simplified
  • zh-Hant: Chinese Traditional

Colours[edit]

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]

Art[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.

The sample palette used in the Tolstoy mod is shuffling around some army colours to demonstrate the feature.

The mod packing tool will tell you if any assets use a colour not present in your palette. The error message contains a colour code and location to help you find the offending pixels.

Aseprite Files[edit]

In order to create an aseprite file, you have to buy Aseprite. Animations work with Aseprite tags.

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.

Sound[edit]

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[edit]

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.

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

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

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

SFX[edit]

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.

---
actions:
  - 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.

---
actions:
  - 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]

Packaging[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 application folder which is probably at %APPDATA%\Roaming\Chucklefish\Wargroove\mods or %APPDATA%\Roaming\Chucklefish\Wargroove2\mods.

It is recommended to keep a close eye on the tool's output for any warnings or error messages. If there are errors, the files in your %APPDATA% folder won't be updated.

Any output is also written to a log file, which can be found at %APPDATA%\Roaming\Chucklefish\Wargroove\mod_packer_mod.txt or %APPDATA%\Roaming\Chucklefish\Wargroove2\mod_packer_mod.txt.

Distribution[edit]

At the moment, distribution is a manual process. Once you have packaged your mod, it will be moved to your application folder. The folder that’s created will have the same id as your mod, and can be copied and placed in any user’s mods folder for usage.'