Core Documentation
Essential Guides & References
Your First Map
Never made a custom map? A step-by-step walkthrough of The Forge, the map editor: paint terrain, place gold and start positions, add one trigger, test it, publish it and share the link.
- ✓No account needed until you publish
- ✓Terrain, gold mines, start positions and a region
- ✓One working trigger, tested in the real game
- ✓Publish to Custom Games and copy a share link
Map Editor Guide
The full guide to The Forge: terrain and height, placing units, players and teams, triggers, data overrides, cutscenes, testing and publishing.
- ✓Terrain painting, elevation terraces and ramps
- ✓Triggers with functions, locals, hashtables and camera control
- ✓Data overrides for units, buildings, items, spells, upgrades and heroes
- ✓Testing with the Trigger Debug panel, and publishing
Mods (.sosmod)
A map is a scenario; a mod is a package of data overrides, triggers, sounds and models applied on top of any custom map, in single player or multiplayer.
- ✓The two sample mods, explained line by line
- ✓Dependencies with version ranges and minEngineVersion
- ✓Applying a mod from the map browser, the lobby or a link
- ✓Exporting a mod from The Forge
Validation & Tooling
One validator behind the editor, /tools/validator, POST /api/validate and a command-line tool, with JSON Schemas and a write, validate, fix loop for people and AI agents.
- ✓Errors with JSON paths and "did you mean" suggestions
- ✓POST /api/validate: no key, CORS open, 30 requests a minute
- ✓npx tsx tools/validate.ts with --json and CI-friendly exit codes
- ✓Compatibility and versioning policy
Working with AI Assistants
Using a chat assistant or coding agent to draft triggers, data overrides and mods, and checking the result before you play it.
- ✓Copy Map as AI Context: the full node reference, generated from the game
- ✓Validating and importing what the assistant returns
- ✓The mistakes assistants make most often
- ✓Test the result with Test Map (Ctrl+F9)
Custom Units & Models
Giving a custom unit a 3D model hosted anywhere or embedded in a mod: the limits it must fit, animation clip naming, effect sockets and the sprite fallback.
- ✓modelUrl, animationsUrl and mod: references
- ✓40,000 triangles and 2048px textures, or the sprite is shown
- ✓The nine animation states and the names that select them
- ✓The in-browser model merger
Web APIs & Embedding
HTTP endpoints for community maps, validation and the asset catalogue; embedding the game with postMessage; and headless runs from a checkout of the repository.
- ✓Community map list, publish, rate and report endpoints
- ✓Embed messages: sos:load-map, sos:trigger-event, sos:match-end
- ✓Guest share links with ?customMap=
- ✓Engine internals and the event bus, for forks
Machine-Readable Context (llms.txt)
A plain-text index of these docs following the llmstxt.org convention, for AI tools and assistants. /llms-full.txt is the long form.
- ✓/llms.txt: links to every chapter, schema and tool
- ✓/llms-full.txt: the long form, including the trigger node reference
- ✓Unit and building ids and the file formats
- ✓Pointers to the validator for checking generated content
Design Principles
Deterministic Lockstep RTS Architecture
Custom content runs inside a lockstep multiplayer simulation, where every player's game must compute exactly the same result. These rules are how the engine is built to keep it that way:
Triggers are a closed set of JSON nodes, never JavaScript. A map cannot run arbitrary code, in the simulation or in your browser.
Nodes are designed not to throw. A dead unit or a division by zero yields a zero value, and loops and trigger cascades are capped.
A fixed 50ms simulation tick, with rendering interpolated between ticks for smooth movement.
Press Ctrl + F9 (Test Map) in The Forge to launch your map in the game with its triggers and data changes applied.
The Forge Manual
Map Editor Chapters
Introduction
What The Forge map editor can author, maps versus mods, what it deliberately cannot do, and the shape of the work from an empty grid to a published map.
Your First Map
A step-by-step walkthrough for someone who has never made a custom map: open The Forge, paint terrain, place gold and start positions, add one trigger, test it, save it, publish it and share the link.
Interface
The module bar, the tool palettes, the outliner, the viewports and every keyboard shortcut that matters.
Creating a Map
Sizes, biomes, generated starting layouts, spawn points, the environment block and what a saved map actually contains.
Terrain & Height
Painting ground and water, the terrace elevation model, ramps, and the six ways a hand-edited height field goes wrong.
Lava & Biomes
Lava as a terrain type, the one rule it imposes on a map, and how the eleven biomes differ from each other.
Units & Properties
Placing units and buildings, the inspector, authored ids and tags, hero instances, spawners and ground items.
Players & Teams
The per-seat roster, controllers, teams, starting resources, AI settings, map rules, and how to make a one-player map boot.
Triggers
Events, conditions and actions; variables, functions and hashtables; camera and interface actions; and combining JSON triggers with sandboxed JavaScript or TypeScript.
Trigger reference
Every trigger event, expression and action: its JSON kind, editor sentence, fields and a minimal valid example.
Data Overrides
Per-map changes to units, buildings, items, spells, upgrades and heroes: patching, cloning, merge rules and array operators, and what gets checked.
Cutscenes
Building an in-game scene from camera keyframes and timed lines, and the one rule that keeps a skipped cutscene from breaking a match.
Testing
Launching the map in the real engine, what to check before you call it done, and how to test a map that only misbehaves in multiplayer.
Validation & Tooling
One validator, four front ends: the Validation module, the web validator, POST /api/validate and the command line. Plus the JSON Schemas, the Trigger Debug panel and a write, validate, fix loop for people and AI agents.
Publishing
Publishing to Custom Games from The Forge, what blocks it and why, share links, updating a published map, and what happens after: ratings, reports and moderation.
Mods
What a .sosmod package is, the two sample mods line by line, applying a mod in single player, multiplayer and by link, dependencies, and exporting one from The Forge.
Compatibility & Versioning
Every version number a map or mod carries, what the game enforces about each today, and the policy for how formats change without breaking published content.
Working with AI Assistants
Using a chat assistant or a coding agent to draft triggers, data overrides and mods: what to give it, how to bring its output into The Forge, and how to check the result before you play.
Custom Units & Models
Giving a custom unit or building a 3D model: modelUrl and mod: references, the limits a model must fit, animation clip naming, effect sockets, and what happens when a model fails.
Asset Catalog
Finding the ids a map or mod can reference: unit and building ids to clone, model ids, sprite keys and sound ids, and how each one is checked.
Web APIs, Embedding & Headless Runs
The HTTP endpoints for community maps, validation and the asset catalogue; embedding the game in an iframe with postMessage; and running matches headlessly from a checkout of the repository.
Engine Internals & Events
What you can hook from a map, what you can hook from a page embedding the game, and what needs a fork of the engine: the event bus, adding systems, and the determinism rules a fork must follow.
Capability map
What you want a map to do and the node that does it, every entry checked against the live catalogue, plus an honest list of what is not possible yet.
Glossary
Every term these docs use that does not mean what you would guess, in one place.
Frequently asked questions
The questions people actually ask first, answered in one place, with a pointer to the page that goes deeper.
Troubleshooting by error code
Every code the validator can report, what it means and how to fix it, plus which ones stop a map loading at all.
Determinism for authors
Why the same map must produce the same result on every machine, what the engine does to guarantee it, and the handful of habits that still matter when you author triggers.
Performance and limits
The real per-tick budgets a map may spend, every hard cap with its live value, what happens when you cross one, and how to see it happen.
Security model
What a custom map may and may not do to the machine that loads it, why each boundary exists, and what is checked where.
The AI Agent Toolkit
The agent-facing half of AI authoring: the validate → play → assert loop, the starter templates, the four engine facts no schema will tell you, and what an agent gets wrong on its first attempt.
Your First Win Condition
Turning a map into a game: the built-in victory presets, when you need a trigger instead, the counter-and-outcome pattern every genre uses, and the seat rule that decides whether your victory actually ends the match.
Your First Custom Unit
Cloning a shipped unit into one of your own in the Data module, making it trainable, finding real ids instead of guessing them, and the did-you-mean suggestion that validates cleanly while giving you the wrong unit.
Your First Mod
Turning changes you made on one map into a .sosmod that plays on any map: exporting from The Forge, what a package may contain, validating it, applying it by file or by link, and the multiplayer rule that keeps everyone in the same match.
Publish and Iterate
Shipping the first version early, what the gallery tells you back, updating a published map in place without losing the old one, and building a repeatable check so a balance change cannot quietly break the map.
The Genre Cookbook
Eight custom-game shapes as recipes: the rules to set, the triggers to add, a trigger fragment checked against a real map, and one command per recipe that plays the map and asserts the result.
Walkthrough: Tower Defense
A read-through of the shipped tower defence showcase: its waves, its lives counter, the two triggers that can end it, and why a headless run of it loses.
Walkthrough: Castle Fight
A read-through of the shipped Castle Fight showcase: buildings that spawn their own army, income on a timer, and a castle poll that pairs victory and defeat across four seats.
Walkthrough: Hero Arena
A read-through of the shipped champion arena: a custom event between scoring and winning, chat-driven save codes, and a bot loop written entirely in triggers.
Walkthrough: Survival
A read-through of the shipped survival showcase: a day and night cycle run on two named timers, a horde spawned at dusk and deleted at dawn, and a match decided on the sixth sunrise.
Walkthrough: Deep Delve
A read-through of the hand-authored horde showcase: four spawn regions, waves that scale by arithmetic, and a win condition that is one atTick node with no condition attached.
Walkthrough: Tanks of Stone
A read-through of the hand-authored tank arena: five rounds counted by one death trigger, enemy movement written entirely in triggers, and a barricade field you shoot holes in.
Walkthrough: Escape Maze
A read-through of the Vault of Ash escape map: three routes that charge three different currencies, trigger-authored chase AI kept in a hashtable, and a clock tuned against measured route lengths.
Walkthrough: Hero Siege
A read-through of Siege of Ember Gate: five waves that each send a swarm and a ram at opposite targets, bounty paid to the killer, and a repair that buys back the past and nothing of the future.
Walkthrough: Lane Race
A read-through of Ironvale Legion: ten rounds against both lanes at once, where the only decision is what each round's gold buys, and income that pays back on round 7 of 10.
Your first sandboxed script
Write JavaScript or TypeScript in the Forge, test it in QuickJS, and remix Aces of Stone or Drop of Stone.
Build a custom game
Combine map JSON, visual triggers and sandboxed JavaScript or TypeScript; reuse public arcade controllers, validate the result and understand the current engine boundaries.