# Shards of Stone: Ash and Iron

> Web-based lockstep RTS engine (Next.js, Canvas 2D/Three.js 3D, deterministic ECS) with 8+ distinct factions, a comprehensive Map Editor ("The Forge"), zero-eval data overrides, and a pure JSON Abstract Syntax Tree (AST) trigger system for custom maps and game modes.

This document serves as the machine-readable developer and AI context index for Shards of Stone, formatted according to the [llmstxt.org](https://llmstxt.org) standard.

For the single-file, exhaustive context document containing all TypeScript interfaces, faction rosters, unit IDs, and complete JSON recipes for LLM system prompts, see [/llms-full.txt](https://shardsofstone.com/llms-full.txt).

## Core Documentation & Guides

- [Docs Portal](https://shardsofstone.com/docs): Central developer and creator hub for level design, modding, and engine references.
- [Modding Platform](https://shardsofstone.com/modding): Technical showcase comparing Warcraft III JASS with our modern web AST, plus the 'Vibe Code on Shards of Stone' tech stack breakdown.
- [Map Editor Guide](https://shardsofstone.com/docs/map-editor): 17-chapter comprehensive guide to The Forge (terrain elevation, lava biomes, rosters, camera cutscenes, publishing, 3D Meshy custom units, engine hooks, REST APIs, and asset catalog).
- [Asset Catalog & Key Registry Guide](https://shardsofstone.com/docs/map-editor/asset-catalog): Complete catalog of 626 built-in 3D model IDs across 10 factions, sound effect keys, and defOverrides registry.
- [Custom Units & 3D Meshy Models Guide](https://shardsofstone.com/docs/map-editor/custom-units-and-models): How to generate, rig, animate, and wire custom 3D models with Meshy.ai, Blender, multi-clip animation pools, and defOverrides.
- [Engine Hooks & Event Bus Guide](https://shardsofstone.com/docs/map-editor/engine-hooks): 30+ canonical simulation lifecycle, combat, and VFX event hooks for 3rd-party developers and custom ECS systems.
- [Web APIs & Headless SDK Guide](https://shardsofstone.com/docs/map-editor/api-reference): Complete REST API reference (maps, lobbies, ratings) and HeadlessGame Node.js runner for 1000x automated simulation.
- [AI Creators & LLM Modding Guide](https://shardsofstone.com/docs/map-editor/ai-creators): How to prompt Claude 5 (Fable 5.1 / Sonnet 5), OpenAI GPT-6 Astra / GPT-5.6, Google Gemini 3.8, Cursor, Windsurf, and other frontier models to design custom RTS maps, triggers, and balance overrides.
- [Trigger Scripting Guide](https://shardsofstone.com/docs/map-editor/triggers): Explanation of the deterministic event-condition-action AST, total evaluation, and multiplayer lockstep guarantees.
- [Data Overrides & Object Editor](https://shardsofstone.com/docs/map-editor/data-overrides): Per-match unit stat patches, archetype cloning, custom costs, and zero-eval balance registries.
- [Testing & Playtesting Guide](https://shardsofstone.com/docs/map-editor/testing): 1-click test launches via `Ctrl + Enter` / `Ctrl + F9`, multiplayer desync detection, and verification habits.
- [Map Publishing Guide](https://shardsofstone.com/docs/map-editor/publishing): Format packaging, content hashing, and sharing custom scenarios.

## Deterministic RTS Architecture

- **Deterministic Simulation**: Fixed 20 ticks/sec (50ms) timestep. All peers in a multiplayer match simulate the entire state independently and compare state hashes.
- **Zero JS Eval**: Triggers are authored as a closed, typed JSON AST (`TriggerScript`). No `eval()`, no dynamic code, and no sandboxed VMs.
- **Total Evaluation**: All expressions degrade to safe zero-values instead of throwing exceptions. Division by zero yields `0`; dead or missing entities return `0`, `false`, or `""`. Loops are strictly capped (`LOOP_CAP = 10000`, `CASCADE_CAP = 64`).
- **Data Isolation**: Unit balance overrides (`DefOverrideSet`) install into an isolated per-match registry and never mutate core prototype tables.

## Playable Factions

- **Dwarves of Greyhelm**: Fortified holds, steam tanks, gyrocopters, runesmiths, and heavy defensive masonry.
- **Goblin Ashland Clans**: Swarm tactics, bomb lobbers, warg riders, scrap demolishers, and shamanic magic.
- **Ratmen Under-Empire**: Swarm infantry, clanrats (2 per spawn), jezzail snipers, spark cannons, and doom wheels.
- **Lizardmen of the Sun**: Tough saurus warriors, skink skirmishers, bastiladon war beasts, and ancient carnosaurs.
- **Wood Elves**: Forest mastery, stealth waywatchers, treemen ancients, spirit trees, and mobile archers.
- **High Elves**: Crystal walkers, silver helms, phoenix aviators, and disciplined elemental casters.
- **Dark Elves**: Corsairs, cold one cavalry, repeater crossbows, shadow engines, and offensive sorcery.
- **The Undead**: Necromancy, skeletal swarms, corpse wagons, abominations, bone dragons, and unit raising.

## Level Design & AST Reference

- [Full LLM Reference (`/llms-full.txt`)](https://shardsofstone.com/llms-full.txt): Complete concatenated reference featuring system prompts, TypeScript interfaces (`TriggerScript`, `TriggerEvent`, `Action`, `Expr`, `UnitFilter`, `DefOverrideSet`), unit and building IDs, and tested game mode JSON recipes.

## Interactive Tools & Play

- [Play Online](https://shardsofstone.com/play): Launch the full RTS in your browser with zero install.
- [The Forge Map Editor](https://shardsofstone.com/docs/map-editor/interface): In-browser 2D/3D map editor with real-time terrain sculpting and visual trigger builder.
- [Developer Blog](https://shardsofstone.com/blog): Technical deep dives into the engine's renderer, audio synthesis, pathfinding, and AI bots.