Asset Catalog & Key Registry

Shards of Stone provides a machine-readable asset catalog and query endpoint for third-party modders, map authors, and external automation tools. Because custom scenarios, maps, and mod packages run deterministically inside a client-side lockstep engine, custom definitions must reference canonical assets or valid external URLs.

This registry details how to query the catalog, how to reference 3D meshes and sound effects, and includes canonical registries for every faction in the game.

flowchart TD
    A["Asset Catalog\n(/api/assets/catalog & catalog.json)"] --> B["3D Models (620+ GLBs)\n(modelId / modelUrl)"]
    A --> C["Sound Effects (3,600+ SFX)\n(soundId in triggers)"]
    A --> D["Unit & Building Defs\n(baseId for cloning & patches)"]
    A --> E["Spells & Items\n(spellId, iconKey, itemId)"]
 
    B --> F["Three.js 3D Viewport\n(ModelManager)"]
    C --> G["SoundManager / Web Audio\n(Spatial playback)"]
    D --> H["Data Overrides\n(defOverrides)"]
    E --> H

1. Querying the Machine-Readable Catalog#

The game serves a pre-indexed asset catalog directly from static disk and via a filtered REST API endpoint.

Static JSON Endpoint#

For offline tooling, build pipelines, and CI/CD map validators, load public/assets/catalog.json directly:

# In local development or standalone tools
cat public/assets/catalog.json | jq '.units[] | select(.race=="dwarf")'

REST API (/api/assets/catalog)#

When building web map editors, spectator overlays, or external AI agents, query the live Next.js API endpoint:

GET /api/assets/catalog HTTP/1.1
Host: localhost:3050

Query Parameters#

All responses return HTTP 200 with Cache-Control: public, max-age=3600.

Client Example#

// Fetch only Dwarf 3D model definitions
const response = await fetch('/api/assets/catalog?category=models&race=dwarf');
const { models } = await response.json();
 
console.log(`Found ${models.length} dwarf 3D models`);
// models[0] -> { id: "dwarf_cannon_tower", race: "dwarf", polycountTier: "building", hasAnimations: false, footprint: "2x2" }

// Search for all siege weapons across all factions
const res = await fetch('/api/assets/catalog?category=units&search=ram');
const { units } = await res.json();

2. Referencing Assets in Map & Mod Files#

In defOverrides (Data Overrides)#

In defOverrides, you can patch existing units or clone new variants that borrow shipped 3D models, portraits, and sprites:

{
  "units": [
    {
      "id": "td_boss_dwarf_juggernaut",
      "baseId": "dwarf_steam_tank",
      "patch": {
        "name": "Siege Juggernaut",
        "hp": 2500,
        "damage": 120,
        "speed": 1.2,
        "modelId": "dwarf_steam_tank",
        "spriteKey": "dwarf_steam_tank",
        "renderScale": 1.4
      }
    }
  ]
}

[!TIP] Custom External Models: You can supply direct URLs to externally hosted .glb files via modelUrl and animationsUrl in the patch:

{
  "id": "custom_dragon",
  "baseId": "dark_elf_dragon",
  "patch": {
    "modelUrl": "https://cdn.example.com/models/elder_dragon.glb",
    "animationsUrl": "https://cdn.example.com/models/elder_dragon_anims.glb"
  }
}

In TriggerScript (Sound Effects)#

The trigger action { "k": "playSound", "soundId": string, "players": number[] | null } plays audio across local clients:

{
  "k": "playSound",
  "soundId": "battering_ram_impact",
  "players": null
}

To play unit voice lines or faction alarms:

{
  "k": "playSound",
  "soundId": "voice/dwarf_king_ack_1",
  "players": [0]
}

3. Canonical 3D Models Reference#

Shards of Stone includes over 620 production-ready 3D models (.glb) stored in public/assets/models/<faction>/. All units are normalized to UNIT_MODEL_HEIGHT_PIXELS, and building footprints align with the simulation grid.

Dwarf Faction Models#

Goblin Faction Models#

Ratmen Faction Models#

Lizardmen Faction Models#

High Elf, Wood Elf, & Dark Elf Models#

Human & Undead Models#

Neutral, Creep, & Boss Models#

4. Audio Keys Reference#

The game engine provides more than 3,600 sound effects (public/assets/sfx/). In TriggerScript, reference the sound ID (filename without .mp3 extension, or prefixed with voice/ for unit voice lines).

Combat Impacts & Hits#

Spell Invocations & Magic Schools#

Alarms, Economy, & UI#

5. Overriding vs Cloning Best Practices#

When designing custom game modes or rebalancing factions, choosing between patching and cloning preserves compatibility with the AI and HUD:

flowchart TD
    Q{"Is the change purely\na balance tweak or stat buff?"}
    Q -- "Yes (Numbers only)" --> P["Patch Existing ID\n(e.g. id: 'dwarf_crossbowman')"]
    Q -- "No (New role, new identity)" --> C["Clone with baseId\n(e.g. id: 'dwarf_marksman', baseId: 'dwarf_crossbowman')"]
 
    P --> R1["✓ AI build orders keep working\n✓ Tooltips & tech tree intact\n✓ Preloads existing textures"]
    C --> R2["✓ Safe from breaking vanilla balance\n✓ Placeable in editor unit palette\n✓ Unique trigger targeting"]

When to Patch#

• Adjusting cost, training time, speed, or health of existing units.
• Giving a building extra armor or attack damage in a defense scenario.
• Replacing the 3D model of a unit faction-wide with an alternate skin.
• Rule of Thumb: If the unit still behaves like a Crossbowman, patch it.

When to Clone#

• Creating a specialized mini-boss, hero bodyguard, or elite wave creep.
• Introducing a unit that has a distinct identity, custom ability, or unique weapon.
• Introducing custom towers with distinct targeting rules.
• Rule of Thumb: If a player needs to tell the unit apart from standard forces at a glance, clone it with baseId.

Previous: API & Headless Runner Reference. Back to: Map Editor Overview.