Pitfalls: gameplay logic & readiness gates

Silent readiness signals, retry flags, stable keys and shared placement paths.

Generalized pitfalls harvested from shipped and active projects. Each entry: rule, what broke, why, check. Index: the pitfalls page. All rules here are LOCKED evidence (the customizable rules page LOCKED-VS-CUSTOMIZABLE). Status: locked (empirical, seen in shipped/active projects).

• SILENT-SIGNAL-COUNTS-AS-SATISFIED — a readiness input that is never produced in this build must count as satisfied, not pending. Why: "not reported" was treated as "not ready". Check: for every gate input, name which builds/worlds write it; inputs with no writer in a configuration are excluded or pre-satisfied there. Status: locked (empirical, seen in shipped/active projects).

• FIRST-TIME-FLAG-IS-NOT-A-RETRY-FLAG — never key a "first time" test off a flag that also means "retry next tick". Why: two states shared one bit. Check: one-shot init and retry have separate fields; a failure path cannot reset the "initialised" field. Status: locked (empirical, seen in shipped/active projects).

• CATALOG-ORDER-IS-NOT-PRIORITY-ORDER — fixed-order iteration over a category-sorted list streams the world in category order, not distance order. Why: catalog order encodes authoring categories, not relevance. Check: streaming/LOD work queues sort by distance or importance each pass, never by source-list order. Status: locked (empirical, seen in shipped/active projects).

• TIMEOUT-ADVANCE-HIDES-THE-SCREEN — an auto-advancing timeout makes the screen it leaves impossible to inspect or test. Why: the timeout doubled as navigation. Check: timeouts surface a visible state (error/retry) rather than silently navigating; tests can disable the timer. Status: locked (empirical, seen in shipped/active projects).

Related rules

Additional incident rules now sit with System design, Networking, Save data, UI design and Performance.