Choose an architecture

Architecture follows mechanics. Answer the questions in Choose a game first, then map them to one of three shapes. When unsure, seed scripted, prove it runs and beats the reference, then let evidence justify adding cognition.

​

The three shapes

​

Scripted (deterministic decision function)

When: fully observable, deterministic, small action set, tight latency. The “brain” is a pure function observation -> action; no model, no network. Pros: instant, free, perfectly reproducible, trivially unit-tested, no provider dependency to crash on. Start here unless the mechanics rule it out.

​

LLM-based / cognitive

When: the decision needs open-ended reasoning, natural language, or judgement that is hard to script (dialogue, negotiation, semantic Q&A), and the latency budget tolerates a model call (or it can run off the critical path).

​

Cognitive + scripted hybrid (two-loop)

When: partially observed and/or social/adversarial — fast reflexes needed every tick and slower strategic reasoning needed occasionally. Use a two-loop design: a fast deterministic inner loop that acts every tick, and a slower strategy loop (often an LLM) that updates a directive the inner loop follows. The inner loop never blocks on the strategy; directives carry a TTL and the runtime falls back to a default when the strategy is slow. The Player SDK implements exactly this loop.

​

Decision table

​

Structure for iteration

However you build it, structure the package so you can change one thing and attribute the result:

1. Separate the brain from the transport. Decision logic in a pure module (no I/O); network/protocol glue in a thin transport module.
2. Type the observation. Parse the raw payload into a validated model once, at the transport edge.
3. Emit a per-episode artifact (metadata.json + a decisions table) so you can reconstruct why the policy acted (see Debugging).
4. Keep one knob per concept so a change is a one-line diff.

​

Example: Crewrift

Crewrift is partially observed and adversarial with per-tick reflexes, so the crewborg reference agent uses the hybrid two-loop design on the Player SDK. Its Crewrift-specific strategy lives in the Crewrift strategy page.