game.gm.v2 — ai.intergraph/game-master 0.1.30

Runs a game on gm-lib runtime v2 (GM_RUNTIME=v2): the GM owns its state in its own Postgres schema and serves events itself on POST /v2/events, instead of MoM routing them in. Default off; with the flag off nothing here is reachable except as a 404.

This is the app-integration layer over game.gm.runtime-v2. A game adds it with:

1. (v2/with-runtime cfg {:dispatch-fn .. :initial-state .. ...}) on its start-gm! config
2. (v2/wrap-v2 handler) inside its JSON body middleware
3. v2/service-event! / v2/read-game-state where it used MoM for its own events/state
4. v2/ui-event! for the UI's /events route See docs/runtime-v2-wiring.md.

ONE WRITER. With the flag on the GM's store is the only writer, so the legacy webhook (/v1/gm/handle) answers 410.

build-store clj

(build-store env game-name)

The game's Postgres store from GM_PG_URL / GM_PG_USER / GM_PG_PASSWORD / GM_PG_SCHEMA / GM_PG_POOL (schema defaults from the game name). A missing URL is a startup error: a GM that was asked for v2 must not quietly fall back to anything else.

enabled? clj

(enabled?)

True only for GM_RUNTIME=v2 (case and surrounding space ignored).

env-runtime clj

(env-runtime)

handle clj

(handle request)

POST /v2/events.

handle-state clj

(handle-state request)

GET /v2/state: the current state for an authenticated seat.

init! clj

(init! {:keys [gm-id game-id game-name]}
       {:keys [dispatch-fn initial-state store mom-url memory-fn
               memory-protocols avatar-provider-fn http-post now-fn env
               protected-protocols]})

The start-gm! :on-ready body. info is {:gm-id :game-id :game-name}; opts: :dispatch-fn, :initial-state, :mom-url, :memory-protocols (default #{:attention}), :memory-fn (caller -> private memory; default reads MoM's KV), :avatar-provider-fn (-> the configured AvatarProvider or nil; wires avatar effects through the outbox), :protected-protocols (protocols GET /v2/state does not serve), and for tests :store, :http-post, :now-fn, :env.

mom-memory-fn clj

(mom-memory-fn mom-url game-name)

caller -> the seat's private memory from MoM's per-player KV, read with the GM's service credential. nil when there is no player, or MoM does not answer 200.

on-ready clj

(on-ready opts)

The start-gm! :on-ready hook for opts (see init!). A store that cannot open throws, so start-gm! stops instead of serving half-configured.

outbox-lease-ms clj

How long a worker holds an effect it is running. It must outlast the slowest provider call (Yvatar's socket timeout is 60 s): an effect whose lease lapses mid-call would be taken for abandoned.

read-game-state clj

(read-game-state)

The whole state in MoM's reload shape, or nil while the runtime is not ready.

runtime clj

schema-for clj

(schema-for game-name)

The Postgres schema a game gets by default: gm_<game name as a plain identifier>.

seat-event! clj

(seat-event! caller body)

An event from a seat this GM has ALREADY authenticated (the UI's /events route verified the browser's user and seat with MoM on this request). caller is {:game-id :membership-id :player-name :roles}. Returns {:status :body}.

seed-if-empty! clj

(seed-if-empty! s initial-state)

A brand-new store starts from the game's initial state. A store that already has state is never touched.

service-event! clj

(service-event! m)

The GM's own event, run locally (see game.gm.runtime-v2/service-event!).

ui-event! clj

(ui-event! {:keys [game-id seat body]})

The UI's POST /events on v2: {:game-id :seat :body} where :seat is the verified seat. Runs as that seat, with the caller protections applied.

ui-event-body clj

(ui-event-body body seat)

The browser's event body rewritten to speak as seat: the seat's :player-name and :roles go into :event/data, and everything the browser claims about who is acting is dropped.

with-runtime clj

(with-runtime cfg opts)

cfg for start-gm!, with the v2 :on-ready hook added only when the flag is on. :mom-url defaults to the config's.

wrap-v2 clj

(wrap-v2 handler)

Serves POST /v2/events and GET /v2/state, and (flag on) answers 410 on the legacy POST /v1/gm/handle. Every other request passes through. Put it inside the JSON body middleware.