PATTERNS.md

Cougr Patterns

Purpose

This document captures the recommended architectural patterns for new Soroban game contracts built on Cougr.

The goal is to standardize how teams structure worlds, systems, stages, and storage choices instead of relying on ad-hoc example interpretation.

Default Entry Point

Use GameApp as the default runtime entrypoint.

Recommended shape:

1. build the app
2. register plugins and startup systems
3. register tick systems into explicit stages, preferably with named_system(...) / named_context_system(...)
4. run one schedule tick per contract invocation that advances gameplay

This keeps the "contract entrypoint" thin and the gameplay loop explicit.

Stage Layout

Cougr's recommended schedule is:

• Startup: one-time entity/resource setup
• PreUpdate: input decoding, action validation, turn preparation
• Update: core gameplay state transitions
• PostUpdate: scoring, derived-state maintenance, indexing side effects
• Cleanup: despawns, expiry handling, transient marker removal

Do not use cross-stage before / after dependencies. Stage order is already the primary contract between phases.

System Design

Prefer small systems with one responsibility:

• validation systems should reject or mark invalid intent
• update systems should apply game-state transitions
• cleanup systems should remove expired markers or entities

Use context-aware systems when you need deferred structural changes:

• queue spawns during iteration
• queue despawns after collision passes
• queue marker additions that should apply after the current scan

Use plain world/env systems when the system only needs direct mutation and no command buffering.

Query Guidance

Prefer SimpleQueryBuilder for gameplay queries that need:

• multiple required components
• negative filters
• sparse-component inclusion
• "any-of" matching

Guidelines:

• default to table-only queries for tight loops
• opt into sparse inclusion only when marker/tag data must participate
• choose required components carefully so the scheduler can use the narrowest candidate set

Hidden Information Guidance

For hidden-state or commit-reveal contracts:

• keep the contract entrypoints thin and verification-oriented
• use privacy::stable Merkle and commit-reveal primitives instead of example-local crypto formats
• treat proof verification as a boundary concern, not as something every gameplay system needs to understand
• keep public derived state separate from private commitments and Merkle roots

battleship is the canonical reference for this pattern.

Storage Guidance

Use table storage for:

• frequently scanned gameplay state
• canonical state that participates in core loops
• components used by Update systems on most ticks

Use sparse storage for:

• infrequent markers
• administrative tags
• components mostly accessed by targeted lookups instead of broad scans

If a component becomes part of the hot loop, move it to table storage instead of compensating with more complex query logic.

Recommended Separation

Keep modules separated by concern:

• ECS/gameplay core
• account/auth flows
• privacy/ZK
• standards/operational controls

Do not let auth or ZK concerns leak into every system by default. Compose them at the boundaries where they are needed.

When Not To Use ECS

Do not force ECS into contracts that are:

• tiny and single-entity
• mostly configuration/state-machine driven
• dominated by one-off administrative flows

If the problem is closer to a fixed state machine than a world simulation, a direct contract model may be simpler and cheaper.