CIG2 for agents: start here

CIG2 is a Go framework for real-time multiplayer card games. You write the rules; the framework owns:

  • concurrency
  • hidden information
  • networking
  • persistence
  • testing harnesses

This guide is version-matched: cig context prints the guidance of the CIG2 version your game’s go.mod requires. Trust it over anything you remember from another version.

The model in one screen

  • A game implements cig2.Game: Setup, HandleAction, CheckEnd. It is registered once, cig2.RegisterGame(name, &Game{}) in init(), and shared by every table. So it holds no fields; all per-table state lives in s.SetState / s.SetPlayerState.

  • A session is one table. Exactly one goroutine (the actor) runs every game callback. Never start goroutines in game code, and never lock: there is nothing to race with.

  • The board is a tree of zones (s.NewDeck, NewHand, NewPile, NewDisplay, NewGroup). Every zone has a visibility mode, which decides what each seat sees. Card.Reveal() is sticky and one-way. See cig context hidden-info.

  • Every step is atomic. Validate everything, then mutate. Return an error only before the first change (strict rejection checking enforces this).

  • Snapshots are full, never diffs. After every step each seat gets its whole filtered view.

  • Deterministic by construction:

    • read time with s.Now()
    • randomness from s.Rand()
    • delay with s.Schedule / s.Rearm
    • ask a seat with s.Ask

    That is what lets tables be journaled, replayed and restored after a restart.

Decide in this order when writing a game

  1. Zones and their modes. Who may see what? Pick Hidden (count only) for draw piles, Concealed or OwnerOnly for hands, and Public for tables. Never leave a mode unset: an unknown mode shows nothing.

  2. State. One struct in SetState. Per-seat secrets in SetPlayerState, published per viewer through GameState(s, viewer).

  3. Actions. One HandleAction switch. Validate first.

  4. Hints. Implement ActionHinter (LegalActions). Agents, bots and Explore all act from hints, and they must agree with HandleAction (E503).

  5. The end. CheckEnd must notice every way the game ends (E504, E505).

  6. Describe it. Implement GameDescriber with schema.For[T]() schemas, so agent players can learn the game from GET /describe.

  7. Test it.

    • cig2test.Explore (one line)
    • a scripted cig2test.Start game
    • golden snapshots

    See cig context testing.

Never write these yourself

cig context patterns maps each helper you might be about to write to the framework tool that already does it. The common ones:

  • an SSE adapter (use host)
  • a payload type assertion (use deck52.PayloadOf or a typed helper)
  • a clock (use s.Now, Clock)
  • a timer (use Schedule, Rearm)
  • a decision protocol (use s.Ask)
  • a test harness (use cig2test)

Commands

go run github.com/PipGrylls/CIG2/tools/cmd/cig context            # this guide
go run github.com/PipGrylls/CIG2/tools/cmd/cig context <topic>    # one topic; "list" lists them
go run github.com/PipGrylls/CIG2/tools/cmd/cig context errors E101
go run github.com/PipGrylls/CIG2/tools/cmd/cig check ./...        # analyzers for the rules above
go run github.com/PipGrylls/CIG2/tools/cmd/cig new example.com/mygame
go run github.com/PipGrylls/CIG2/tools/cmd/cig new -package-only example.com/repo/games/mygame games/mygame  # into an existing module
go run github.com/PipGrylls/CIG2/tools/cmd/cig inspect tables     # a running server's inspector