Troubleshooting

Symptoms and fixes, grouped by who hits them.

Players

”The join code doesn’t work.”

• Typo. Codes are letters only and case-insensitive — re-enter carefully.
• Expired session. Idle sessions are reaped after ~an hour. Ask the GM to create a fresh session.
• Not started / wrong session. Confirm with the GM you’ve got the current code.

”My marker is stuck or in the wrong place.”

• Location permission. Make sure the app is allowed to use location “while using the app.”
• GPS settling. Right after joining, your position can take a few seconds to lock; it’ll snap in.
• Poor sky view. Indoors, under heavy tree cover, or beside tall buildings, GPS wanders. Move into the open.
• App backgrounded. Keep the app in the foreground during play for reliable updates.

”The action button won’t light up.”

An interaction button is gated server-side. Usually one of:

• you’re out of range (move closer — tags are typically 3–5 m),
• you’re not eligible (wrong team, wrong state — check your objective), or
• the target isn’t valid (e.g. already frozen, on your team, an item you can’t carry a second of).

”I got disconnected.”

Reopen the app and rejoin with the same code and name. The game is on the server, so you’ll resync to its current state.

Gamemasters

”Start is greyed out / blocked.”

The pre-flight checklist failed. The console names the reason; common ones:

• a required zone isn’t placed (or has no shapes),
• a required point is missing,
• the player count is outside the game’s min/max,
• a placed zone is too small (minArea), or
• a bot-class minimum isn’t met.

Fix the named item and try again. See Run a session.

”I can’t reshape a zone.”

Editing is locked once a game is started so the field doesn’t move under players. Pause (stop) first, adjust, then resume.

”I refreshed the console and lost the game.”

You shouldn’t — the console reconnects to the active session on reload. If it didn’t, the session may have ended or expired; check the library and recreate if needed.

Builders

”My game won’t load.”

The engine validates rulesets at load and fails loudly. The most common cause is an undeclared item kind: every kind used in items, interactions.itemKinds, or a spawn_item action must be in itemTypes. The error names the kind — add it and reload. Also check your YAML/JSON is well-formed.

”A rule never fires.”

In rough order of likelihood:

1. Edge-triggering. entered_zone/left_zone/proximity fire once on the transition. For a repeat, use a tick or convert the edge to a state flag.
2. same/other reversed. The rule fires but acts on the wrong player. Add a log with {player}/{other} to confirm the binding.
3. First-match shadowing. A broader earlier entry in theme/objectives/visibility is catching the case first. Order most-specific-first.
4. Filters too strict. An interaction’s initiatorFilters/targetFilters or rangeMeters excludes your test case.
5. and order. Put the player-binding condition first and tick last.

”A rule fires too many times.”

Level conditions (count_state, compare, state_equals) re-check every tick. Gate one-shot effects with an announced/done flag you set in the same do and add to the when. See Win conditions.

”Units look wrong.”

Author in canonical units: meters, milliseconds (everyMs/delayMs), meters/second. Only countdownSeconds is in seconds. A timer that’s 1000× too fast or slow is usually seconds-vs-milliseconds.

Still stuck? Read the matching built-in game’s source under apps/wage-engine/src/games/ — it’s the most reliable reference there is.