Capability map

Most people who build a custom game arrive with a design already in their head. This page maps the things a map usually needs onto the nodes that do them, points out what this engine does that you might not expect, and lists what genuinely is not here yet.

Every node id on this page is checked against the live node catalogue by a test in the engine repository, capabilityMap.test.ts. If a node named here stopped existing, that test would fail rather than this page quietly lying to you. The "Not possible yet" list is checked the other way round: the test fails when a capability listed there appears, so the list cannot silently go stale either.

The short version#

If you have used a trigger editor before, three things will be familiar: the event / condition / action shape of a trigger, an object editor (here: data overrides), and regions. You can also write sandboxed JavaScript or TypeScript, combine it with JSON triggers, and reuse the public arcade controllers. Build a custom game explains which layer to use. Some native engine capabilities remain unavailable to downloaded maps.

In ordinary RTS lockstep, a tick is one twentieth of a second. An "every 2 seconds" event is everyTicks: 40. Explicit local profiles can change that rate; see Timing and multiplayer.

Events#

The event list is thinner than a mature editor's in the unit and ability areas, and broader everywhere else.

About damage detection. Custom-map authors reach for "a unit takes damage" as a matter of reflex, because half the custom-spell tradition is built on it, and both halves of that idiom now work here.

unitDamaged fires after damage lands, from every source: melee, projectile, spell, burn, thorns, cleave and the rest. unitDamaging fires before it lands, and inside it setEventDamage changes the number — so custom armour types, damage reduction auras and reflect are all expressible. Read the amount with eventDamage, the element with eventDamageType, and which door it came through with eventDamageKind.

Two rules worth knowing before you build on it. wait is illegal inside unitDamaging, because the damage has to resolve in the same tick. And damage caused by a damage hook stops firing hooks after two levels, so a reflect that reflects a reflect terminates instead of looping.

unitAttacked still exists and still fires for attacks specifically, which is the cheaper event when an attack is all you care about.

Conditions#

Most trigger editors split conditions into a small set of comparisons and a large set of boolean queries. Here, a condition is just an expression that evaluates to a boolean, so comparisons and queries are the same thing.

Actions#

Time of day works, with one catch. setTimeOfDay takes a progress from 0 to 1 across the day and a speed multiplier, where speed: 0 holds that time of day instead of pausing nothing. It works from a trigger and from the editor's Environment panel, which now reaches a running match: set the time and a cycle speed of frozen, save, and the map plays at that hour. The panel does not preview it in the editor viewport, and the Tileset panel still does not reach a match at all.

Values, maths and text#

Values, the parts of a trigger line you fill in, are expressions here. This is the area that grew most recently.

Things you might not expect to be here#

Worth knowing they are here, because they change how you would solve a problem you previously solved the long way round.

• Physics. applyImpulse and setUnitKinematics give a unit a real velocity, and unitVelocity reads it back. Knockbacks, launches and bouncing projectiles are a single action rather than a periodic timer that moves a unit by hand.
• Declarative HUD frames. createUIFrame, updateUIFrame, destroyUIFrame and clearUIFrames build custom interface out of described frames, and setCounter / removeCounter put a labelled number on screen. uiFrameClicked reports a click on one of your own frames, arriving through lockstep like a dialog button.
• Restricting where a seat may build. setBuildableRegion takes a list of regions, an empty list for nowhere, or null to restore the default.
• Group algebra. Union, difference, sorting and "pick N" are nodes, not loops you write.
• Save codes that cannot be forged. generateSaveCode binds the code to your map, and verifySaveCode reads a field back out or rejects it.
• Headless testing. You can run your map against the AI a thousand times and assert the outcome. Testing.
• A city builder. rules.city runs the city Cities of Stone plays (roads, zones, services, peoples, seasons), rules.city.tuning gives it your own numbers, and scripts and triggers read and drive it. Overlays (your own map layers) and runtime terrain work on any map. Build a city builder.

Not possible yet#

This is the honest list. Everything in it is something an experienced map author would reach for and not find today. Several are being built right now, so check the date on this page against the Trigger Reference, which is generated and always current: if a capability below has landed, it will be in the reference and this row will have been deleted.

Scripts can combine the exposed operations into new mechanics: shields, custom damage rules, wave logic, scoring and scripted encounters. The boundary is the public API. There is no arbitrary native system or new native spell-effect registration, direct renderer access or general rigid-body API. Existing spell visuals and trigger actions are available through sos.triggers.run; see Current boundaries.

A worked example#

The classic "every 30 seconds, spawn a wave at a region and announce it, until wave 20" as a whole trigger script:

{
  "version": 1,
  "vars": [{ "name": "wave", "type": "int" }],
  "regions": [{ "id": "spawn_north", "x": 2, "y": 2, "w": 4, "h": 4 }],
  "triggers": [
    {
      "id": "waves",
      "events": [{ "k": "periodic", "everyTicks": 600 }],
      "conditions": [{ "k": "lt", "a": { "k": "var", "name": "wave" }, "b": 20 }],
      "actions": [
        { "k": "addVar", "name": "wave", "delta": 1 },
        {
          "k": "createUnits",
          "unitTypeId": "goblin_brawler",
          "count": 8,
          "player": 5,
          "at": { "k": "regionCenter", "region": "spawn_north" }
        },
        {
          "k": "order",
          "units": { "k": "unitsInRegion", "region": "spawn_north" },
          "order": "attack_move",
          "to": { "k": "regionCenter", "region": "spawn_north" }
        },
        { "k": "showText", "players": null, "text": "A wave is coming." }
      ]
    }
  ]
}

Four things worth naming if you have written this in another editor:

1. No registering events at runtime. A trigger's events are declared, not registered, so the initialisation trigger other editors need is unnecessary.
2. No cleanup. There is no location to destroy and no group to release. unitsInRegion returns a value, not a handle.
3. players: null means every seat. A list means those seats. Seat ids are not 0 and 1: a lobby seats up to eight, and creeps sit above the playable range. Never hardcode a seat you did not place. Players and teams.
4. Every duration is in ticks. In this ordinary 20 Hz RTS example, 600 ticks is thirty seconds.

Where to go next#

• Triggers for how the system fits together.
• Trigger reference for every node, field by field. Generated from the catalogue, so it is never out of date.
• Determinism for authors for why the maths nodes exist instead of you doing your own.
• Performance and limits for what a map may spend per tick.
• Troubleshooting by error code when the validator refuses something.