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{})ininit(), and shared by every table. So it holds no fields; all per-table state lives ins.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. Seecig 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.
- read time with
Decide in this order when writing a game
Zones and their modes. Who may see what? Pick
Hidden(count only) for draw piles,ConcealedorOwnerOnlyfor hands, andPublicfor tables. Never leave a mode unset: an unknown mode shows nothing.State. One struct in
SetState. Per-seat secrets inSetPlayerState, published per viewer throughGameState(s, viewer).Actions. One
HandleActionswitch. Validate first.Hints. Implement
ActionHinter(LegalActions). Agents, bots andExploreall act from hints, and they must agree withHandleAction(E503).The end.
CheckEndmust notice every way the game ends (E504, E505).Describe it. Implement
GameDescriberwithschema.For[T]()schemas, so agent players can learn the game fromGET /describe.Test it.
cig2test.Explore(one line)- a scripted
cig2test.Startgame - 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.PayloadOfor 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