Core concepts

This page is the conceptual foundation for everything else in the docs. Whether you play, host, or build, these are the words WAGE uses and what they mean.

Ruleset vs. session

A ruleset is a game definition — a single data file (YAML or JSON) describing one game’s zones, rules, items, and bots. It’s static; it’s the recipe. Tag is a ruleset. Capture the Flag is a ruleset.

A session is one live playthrough of a ruleset. When a gamemaster picks a game and starts hosting, the engine creates a session: it gets a four-letter join code, holds the live world state, and ticks until the game ends. Many sessions of the same ruleset can run at once, each independent.

Note

The engine is game-agnostic. It has no code that knows what “tag” or “a flag” is — it only knows how to evaluate the generic ruleset vocabulary below. All the game-specific meaning lives in the data. This is the single most important idea in WAGE.

Players, teams, and state

A player is a participant — usually a human with a phone, sometimes a bot. Every player has:

• a position (latitude/longitude, updated from GPS),
• an optional team,
• and a bag of state: arbitrary key/value pairs the ruleset defines, like it: true, score: 5, carrying: false, or targetId: "abc".

State is the heart of WAGE gameplay. Rules read state to decide what’s true and write state to make things happen. The engine never hardcodes “the it player” — it just knows some player has it: true because the ruleset said so.

Teams are named groups (red, blue). Some games are free-for-all (no teams); others are team-based. New players are auto-balanced onto the smallest team unless the ruleset pins humans to a specific team.

Zones, points, and the map

A zone is a region of the map — a play area, a base, a hill, a ship. Zones are authored in a local meters coordinate frame (x = east, y = north), so a game’s geometry is described abstractly and the gamemaster drops it onto the real world at session time. Zones can:

• be built from shapes (rectangles, circles, polygons),
• nest — child zones move rigidly with their parent when placed,
• have exclusions (cutout shapes that punch holes), and
• be marked placeable (the GM positions it) and required (the game won’t start until it’s placed).

A point is a single named coordinate (a flag spawn, a goal). Annotations are purely decorative map markings (lines, arrows, labels) with no gameplay effect.

Full map & zone reference →

Rules: when → do

A rule is the unit of game logic:

- id: tag
  when: <condition>
  do:
    - <action>
    - <action>

When the rule’s condition is satisfied, its actions run in order.

• Conditions watch the world: a player entered/left a zone, two players are within N meters (proximity), a timer ticked, a piece of state equals a value, a count of players matches, a comparison holds, or a player performed an interaction. They combine with and / or / not.
• Actions change the world: set or increment state, send a player an event (a toast or countdown), spawn/move/destroy items, pick a random player, branch randomly, write a log line, or end the game.

Two semantics you must internalize early:

• Edge-triggered conditions. entered_zone, left_zone, and proximity fire on the transition, not continuously. Walking into a zone fires entered_zone once; standing in it does not keep re-firing.
• Bindings: same and other. Many conditions bind the players involved. A proximity or interaction match binds the primary player as same and the partner as other. Actions and nested conditions then refer to same and other to act on the right player. (For item interactions, the item is bound as other.)

Conditions reference → · Actions reference → · Selectors & values →

Items

An item is a thing with an identity that lives either in the world (it has a position) or in a player’s inventory (it has a holder). A flag, a treasure chest, a coin. Items have a kind (defined once in the ruleset’s itemTypes, with a label and icon) and are placed by an items spawn spec at game start or by the spawn_item action mid-game. Picking something up is just a custody transfer that keeps the same item id.

Items & interactions reference →

Interactions

GPS can tell the engine that two players are near each other — but not that a real-world tag happened. An interaction bridges that gap: it’s a player-initiated, range-checked, optionally-confirmed action with a verb (like tag, capture, grab_chest). The player taps a button (or, for walk-over pickups, it fires automatically); the server validates range and eligibility; then any rule with a matching interaction condition runs.

Interactions can target another player, an item lying in the world, or an item the player is holding. They can be honor-system (confirm: none) or require the target to confirm (confirm: mutual).

Items & interactions reference →

Bots

A bot is an engine-controlled player. Rulesets declare bot classes with a movement speed, initial state, and a behavior tree — a small nested structure of selector / sequence / chase_nearest / flee_nearest / wander nodes re-evaluated every tick. Bots let a game run with too few humans, or be the opposition entirely (as in Bots vs Humans). The GM can spawn bots and tune their numbers and speed.

Bots & behavior trees reference →

The tick loop

The engine advances the game in ticks — roughly once per second. On each tick it:

1. moves bots according to their behavior trees,
2. processes automatic item pickups,
3. evaluates every rule’s condition and runs the actions of those that match,
4. recomputes each player’s objective text,
5. checks the countdown timer and win conditions, and
6. broadcasts the new world snapshot to all phones and the GM.

Between ticks, players’ phones stream GPS updates (about every two seconds) and the actions they take. Everything visible to a player — their marker, the map, their objective, toasts — is a render of the latest snapshot.

How the engine works →

Where to go next

• Brand-new to the vocabulary? Keep the Glossary open in a tab.
• Want to host? Gamemaster guide.
• Want to build? Start with reading Tag line by line.