A map refers to things by id: goblin_brawler to spawn, dwarf_crossbowman to
clone, explosion to play. This page is about finding the right id, and
knowing which ids the validator will accept where.
Rather than a hand-written list that goes stale, use one of the sources below. They are generated from the game's own data.
Where the ids are
| Source | Best for |
|---|---|
| The Forge's palette and Data module | Browsing units, buildings, items, spells, research upgrades and heroes with their art |
| File → Copy Map as AI Context | Every unit and building id, by race, in one paste |
| Trigger Reference | Trigger node names and fields |
GET /api/assets/catalog | Programmatic lookup: models, sounds, units, buildings, spells, items |
| The validator | The final word: an id it rejects will not work |
The catalogue endpoint
curl 'https://www.shardsofstone.com/api/assets/catalog?category=sounds&search=explosion'| Parameter | Meaning |
|---|---|
category | models, sounds, units, buildings, spells or items. Absent: all six. Anything else: 400. |
race | Filters models, units and buildings, e.g. dwarf, goblin, ratmen, lizardmen, wood_elf, high_elf, dark_elf, human, undead, creep, neutral |
search | Case-insensitive substring of id, name or path |
The response is an object with one array per category requested. The same
data is public/assets/catalog.json in the game's repository, generated by
tools/generate_asset_catalog.ts. At the time of writing it lists 626 models,
3,686 sounds, 247 units, 452 buildings, 645 spells and 136 items.
Entries look like this (one each from units, models and sounds):
{
"units": [
{ "id": "dwarf_ironguard", "name": "Ironguard", "race": "dwarf", "hp": 60, "attackDamage": 8, "speed": 2.5, "cost": { "gold": 80, "lumber": 0, "stone": 0 }, "modelId": "dwarf_ironguard", "spriteKey": "dwarf_ironguard" }
],
"models": [
{ "id": "dwarf_archery_range", "race": "dwarf", "polycountTier": "building", "hasAnimations": false, "footprint": "3x3" }
],
"sounds": [
{ "id": "arrow_hit", "category": "combat", "path": "/assets/sfx/arrow_hit.mp3" }
]
}Two cautions:
- The catalogue is a summary, not the definition. Its unit entries use
attackDamage, but a unit override patchesdamage. Use the catalogue to find ids; use the Data module (or the validator's suggestions) for field names. - It is a generated file, refreshed when the team regenerates it. If it disagrees with the validator, the validator is right.
What each kind of id is checked against
| Where the id appears | Accepted | Checked by |
|---|---|---|
unitTypeId in triggers, unit filters | Any unit, hero, creep or building type id, plus clones the map or mod declares | Validator: unknown id is an error with a suggestion |
baseId, produces, requires, researches, researchedAt, spells in overrides | The matching kind's ids, plus clones in the same set | Validator: error with a suggestion |
itemId, upgradeId in triggers | Shipped items and upgrades, plus clones | Validator |
soundId in playSound | A shipped sound directly in /assets/sfx/, or a custom sound the map or mod registers | Validator |
spriteKey, iconKey, portraitKey | Art the game ships | Validator: unknown key is an error |
modelId | Not checked | Nothing; see Custom Units & Models |
modelUrl, animationsUrl | A .glb/.gltf URL, /assets/…, a data: URI, or mod:<key> | Validator checks the form; the model is measured when it loads |
Sounds
A sound id is the file name without .mp3, for files directly in
/assets/sfx/. In the catalogue, that is any entry whose path has no folder
after sfx/, about 640 of them:
- Combat:
arrow_hit,axe_hit,battering_ram_impact,bolt_hit,explosion - Spells:
buff_cast,heal_cast,lightning_strike,plague_cloud,shadow_bolt,spell_frost_cast - Interface:
click,coins,error_buzz,under_attack - Ambient:
chopping,dawn_rooster_crow,night_wolf_howl,ship_sinking
Sounds in subfolders, which includes most unit voice lines under
/assets/sfx/voice/, are not accepted by playSound. A path like
voice/dwarf_under_attack is rejected.
For anything else, register a custom sound (an https:// URL or a data: URI)
in the map's or mod's sounds and play it by the id you gave it. See
Mods.
Patch or clone?
When you have found the id, the next question is whether to change it or copy it. Patch when the change is a number, so the unit still reads as itself to a player and the AI and tech tree keep working. Clone when it is a new identity: a boss, an elite wave unit, a tower with its own role. The details are in Data Overrides.