Map Editor Documentation

Frequently asked questions

The questions people actually ask first, answered in one place, with a pointer to the page that goes deeper.

Start here · Page 25 of 49

The questions that come up first, with a link to the page that answers each one properly.

Getting started

Do I need to install anything?

No. The editor runs in the browser, and so does the game. A map you publish plays from a URL. There is also a desktop build if you prefer one.

Where do I start?

Your first map. It is short, and it ends with a map you can actually play.

Is there a scripting language?

Yes. Scripts (F11) in the Forge accepts JavaScript and TypeScript. Code runs in the pinned QuickJS sandbox through the public sos API. JSON triggers remain available, and scripts can execute their actions with sos.triggers.run. Start with Your first sandboxed script or Build a custom game.

Can I combine JSON triggers and my own code?

Yes. They can live in the same map. Scripts call supported JSON actions through sos.triggers.run, and both use the shared engine operations and budgets. Keep JS state in sos.storage; direct JavaScript access to trigger variables and calling a JS function from a trigger are not exposed today.

Can I make something other than an RTS?

Yes: defence, survival, arenas, escape and puzzle games, scripted encounters, and shooter or pegboard variants are supported starting points. You can write new logic within the public API. That is not an unlimited native-engine plugin system: new physics systems, arbitrary renderer code and unexposed engine features require extensions. Build a custom game explains the supported layers and boundaries.

I have made maps in another RTS editor. What transfers?

Almost all of it, and there is a page that maps it line by line: the Capability map. It also carries an honest list of what is not possible here yet, so you find out before you build around it.

Building

How big can a map be?

Between 8 and 1,024 tiles on a side, and up to 4,194,304 bytes of map data, including script source, compiled code and embedded assets. Hosted assets are fetched separately; an embedded GLB or data URI counts towards the map limit. See Custom units and models.

Can I change what a unit does?

You can change every number and most behaviour flags on any shipped unit, building, hero, item, spell or upgrade, and you can clone one and change the copy. Data overrides. For custom behaviour, combine triggers and scripts to alter stats, respond to damage, spawn units, apply buffs and play existing effects. Registering a new native spell-effect implementation is not exposed to map scripts.

Can I use my own models and sounds?

Yes. Custom units and models for the art route, and you can name any of the 3,857 shipped sound effects, voice lines and critter calls without shipping anything at all.

How many players?

Up to eight seats, humans and AI mixed. Seat ids are not 0 and 1, and you should never hardcode one. Players and teams.

Can two maps share logic?

A mod can carry data overrides and assets and be merged into any map at launch. Trigger scripts are per map. Mods.

Triggers

What is a tick?

In ordinary RTS lockstep, there are 20 ticks per second, so a tick is 50 ms and thirty seconds is 600 ticks. Local maps may explicitly choose a different supported rate; timer durations must use that declared rate. Timing and multiplayer explains the warning and tradeoffs.

Why is my trigger not firing?

In rough order of likelihood:

  1. The trigger is disabled. A trigger that crosses a per-tick budget on three separate ticks is switched off for the rest of the match, and the console says so. Performance and limits.
  2. unitEntersRegion only fires on movement. A unit standing in the region when the match starts never entered it.
  3. A condition is false in a way you did not expect. Every expression is total, so a missing unit or an undeclared variable gives you a zero rather than an error. A condition comparing against that zero quietly fails.
  4. Run once is ticked. It is easy to leave on.

The Trigger Debug panel shows fire counts per trigger and appears when you launch from Test Map (Ctrl+F9).

Why did my map stop working halfway through a match?

Almost always a disabled trigger. See above.

Can I make my map do something random?

Yes, with rand and randReal, which draw from the match's shared generator so every client agrees. Be aware that they consume a draw even when the range is a single value, so adding or removing a random node changes every later random result. Determinism for authors.

Where do I write custom scripts?

Open Scripts (F11), add a script, choose JavaScript or TypeScript, then use Test Map. The generated API reference is beside the source editor, and the Scripts tab in Trigger Debug shows runtime faults. Scripts receive validated engine operations and plain snapshots. Security model.

Why are angles in radians?

Because the maths nodes are, and converting at the boundary is one more place for the two to disagree. angleBetween and atan2 return -pi..pi, and due west is +pi.

Testing and publishing

How do I test a map?

Test Map (Ctrl+F9) in The Forge launches it with the debug panel attached. For something stronger, you can run a map headlessly against the AI many times over and assert the outcome. Testing.

What does the validator check?

Structure, references, security, resource budgets and quality. It runs in the editor while you work, on the validator page, at POST /api/validate, at publish, and again every time a match loads the map. Validation and tooling.

The validator gave me a code I do not understand

Every code has an entry with a fix: Troubleshooting by error code. That page is generated from the validator's own registry, so a code you can see always has an entry.

Someone else's map will not load for me

Either your build is older than the map's format, in which case update, or the map has a problem serious enough that the load gate refuses it. The message names the code, and Troubleshooting says what it means. The gate deliberately never tries to repair a map, because two clients repairing it differently would be worse than a refusal.

Will my map keep working when the game updates?

Maps are versioned by format, and a build refuses a map it cannot fully run rather than loading it and skipping the parts it does not understand. Compatibility and versioning.

Rights and distribution

Who owns a map I make?

You do. We claim no ownership of custom maps.

Can someone steal my map?

Map content is hashed, so authorship and fork lineage are recorded rather than argued about. Deliberately there is no obfuscation or "map protection": it breaks the learning path for new authors and never stops determined theft. Source-available maps plus real attribution is the better trade.

Can I make money from a map?

Not today. Creator monetisation brings tax, payouts, fraud and moderation obligations much larger than the feature, so it is a later question rather than a no.

For AI agents

Is there one document I can be pointed at?

Yes: llms-full.txt at the site root is generated from the same manifest that feeds the JSON schemas, and it carries the map format, the complete node catalogue, every issue code and the validate endpoint's contract. The JSON schemas themselves are under /schemas/v1/. AI creators.

How do I check a map without running the game?

POST /api/validate with the map as the body. It is open and rate limited, and it returns the same codes the editor does. A map that fails validation is a 200 with valid: false; a 4xx means the request was malformed. API reference.

Which nodes exist?

Read the Trigger reference or the catalogue in llms-full.txt. Both are generated from the validator's own tables, so anything else, including any list in a blog post or a forum reply, is a guess.