Glossary

Quick definitions of the vocabulary used throughout these docs. Each term links to where it’s covered in depth.

Action

The effect half of a rule (do). Changes state, sends events, moves items, or ends the game. Reference

Annotation

A purely decorative map marking (line, arrow, text, circle). No gameplay effect. Reference

Behavior tree

The nested selector/sequence/chase/flee/wander structure that drives a bot each tick. Reference

Binding

The players a condition match attaches to actions — the primary as same, the partner as other. Reference

Bot / bot class

An engine-controlled player; a class is a declared type of bot with its own speed, state, and behavior. Reference

Catalog metadata

The catalog block (abstract, players, thumbnail) describing a game in listings. Reference

Condition

The trigger half of a rule (when). Reference

Countdown

A fixed game duration (countdownSeconds); the engine ends the game when it expires. Reference

Edge-triggered

Fires on a transition, not continuously. entered_zone, left_zone, and proximity are edge-triggered. Reference

Exclusion

A shape that subtracts from its zone — a cutout. Players inside it count as outside the zone. Reference

First-match-wins

Top-down evaluation where the first matching entry is used and the rest ignored. Applies to theme, objectives, and visibility. Reference

Gamemaster (GM)

The person who hosts a session: picks the game, places the map, starts and manages it. Uses the web console. Guide

Initializer

A one-shot setup step in onStart, run once when the GM starts the game. Reference

Interaction

A player-initiated, range-checked action (a verb like tag). The bridge between GPS proximity and a real-world action. Reference

Item / item kind

A thing with identity, in the world or an inventory. Its kind (defined in itemTypes) gives it a label and icon. Reference

Join code

The four-letter pronounceable code players enter to join a session (e.g. SHON). How it works

Objective

Short goal text shown on a player’s phone, derived from their state each tick. Reference

Placeable zone

A top-level zone the GM positions on the real map at session time. Children move with it. Reference

Point

A single named map coordinate (a flag spawn, a goal). Reference

Proximity

A condition that fires when two players come within N meters. Edge-triggered; binds same and other. Reference

Required

A zone or point the game refuses to start without (must be placed and have geometry). Reference

Ruleset

The complete definition of one game as data (YAML/JSON). The recipe. Reference

Selector

Which players a condition or action applies to: same, other, any, or a team/id selector. Reference

Session

One live playthrough of a ruleset, with a join code and live world state. Lifecycle

same / other

The two bound players in a match: same is the primary, other is the partner (or the item, for item interactions). Reference

Server-authoritative

The server holds the real state and decides outcomes; phones are thin clients. Architecture

State

A player’s bag of arbitrary key/value pairs that rules read and write. Concepts

Theme

Presentation rules — chiefly per-state marker colors. Reference

Tick

One iteration of the engine’s loop (~1 Hz): move bots, run rules, broadcast. Concepts

Tunable

A numeric knob (e.g. bot speed) the GM can adjust at runtime. Reference

Value / ref

A literal or a { ref: "same.state.X" } path used in comparisons and set_state. Reference

Visibility

Rules controlling which players’ positions a given viewer can see. Reference

World

The full live snapshot the engine broadcasts: players, zones, items, status, timers. Protocol

Zone

A region of the map built from shapes; the basic spatial building block. Reference