Map Editor Documentation

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.

Start here · Page 1 of 49

A map in Shards of Stone is a single JSON document. It carries the terrain, the elevation, every placed unit and building, the player roster, the triggers, any balance changes the map makes, and the cutscenes it plays. The game loads that document and nothing else, which is the property everything in these pages depends on: if the editor can write it, the game can play it, and if the file is self-contained then a multiplayer match cannot end up with two clients running different content.

The editor is the tool that writes that document. It is not a level viewer with a save button. It runs the same terrain renderer the game runs, the same placement rules the build system uses, and the same validator the publish endpoint runs, so that what you see while authoring is what loads at match start.

What you can author

A map, from an empty grid to a published file

  1. Human

    New map

    Pick a size, a biome and a seat count, or generate a random layout to edit.

  2. Human

    Terrain and height

    Paint ground, water and trees; raise terraces and carve ramps.

  3. Human

    Place entities

    Units, buildings, resources, neutral camps and items, each with its own properties.

  4. Human

    Players and teams

    Per-seat race, controller, team, starting resources and AI behaviour.

  5. Human

    Triggers

    Events, conditions and actions. Waves, objectives, lives, dialogs, victory.

  6. Human

    Test

    Launch the map in the real engine from inside the editor.

  7. Agent

    Validate

    Every rule that catches a silent failure runs before you can publish.

    The same check runs server-side on the publish request.

  8. Human

    Publish

    The map becomes a self-contained file others can download and play.

  • Humana person writes it or decides it
  • Agentthe coding agent does it, in the repository

The modules are reachable from the top-right of the editor and by function key: Terrain on F5, Triggers on F6, Data on F7, Players on F8, Cutscene on F9, Validation on F10, and Test Map on Ctrl+F9. The layout follows classic RTS editors on purpose, including the number keys setting entity ownership while you place, because a lot of people already have those in their fingers.

Maps and mods

Two words are used precisely throughout these pages.

A map is a playable scenario: terrain, placed units and buildings, the player roster, triggers, balance changes and cutscenes, all in one file.

A mod is a portable package of changes with no terrain and nothing placed: data overrides, triggers, custom sounds and model references, in a .sosmod file. A mod is applied on top of a map when a match starts, so one balance mod can be played on any custom map. See Mods.

The Forge is the product name of the map editor. The two terms mean the same tool.

What it deliberately cannot do

Triggers and scripts are complementary. Triggers are typed JSON nodes for events, conditions and actions. For custom code, the Forge also supports sandboxed JavaScript and TypeScript with a generated game API, fixed memory and instruction budgets. Start with Your first sandboxed script.

Sprites and portraits must be the game's own. Custom units, buildings, items and spells may use any art key the game ships, but not uploaded images.

3D models and sounds can come from outside. A custom unit or building can point at a .glb model on any web host that allows it, or embedded in a mod, within limits (40,000 triangles, 2048 px textures), and a map or mod can register its own sounds. Both are presentation only: if a model fails to load, or a player has turned off third-party models in their settings, the unit falls back to its shipped sprite and the match plays identically. See Custom Units & Models.

Two things that will save you an afternoon

Elevation is a terrace system, not a heightmap. Ground sits at integer levels, a step of one level is a cliff, and a cliff is impassable to ground units unless a ramp crosses it. The editor refuses to save a map with a two-level step, because the movement rule that reads it (heightStep) refuses to cross one even with ramps on both sides, and the minimap would draw the map as if it were fine. Terrain and Height covers the rules and the repair tools.

Publishing is gated on a validator that only reports failures you would not otherwise see. It does not have opinions about your map's design. It catches a mercenary camp that will spawn as scenery, a spawner that will tick forever producing nothing, two entities sharing an authored id so a trigger can only find one of them, and a one-seat map that declares victory on tick one. Publishing lists every rule and what each one prevents.

Where to go next

If you have never made a custom map, start with Your First Map, a step-by-step walkthrough that ends with a map you can play. Then read Interface and Creating a Map. If you are porting a map from another game or another editor, start with Terrain and Height, because terraces are the part most likely to differ from what you are used to. If you already have a layout and want it to do something, go to Triggers. If you are using an AI assistant, read Working with AI Assistants and Validation & Tooling.