v0 state

emit

Events emitted by the realm (type, attribute keys): GameCreated id creator char seats maxTurns timeoutMinutes hex facing stake PlayerJoined id player seat char hex facing PlanCommitted id turn player seat AllCommitted id turn (every character in the fight committed: the reveals start) PlanRevealed id turn seat by (by: who sent the reveal, the player or the opener of its timelocked plan) PlanUnopened id turn seat reason (a RevealMany skips a seat whose salt and plan do not match its commit or whose plan is not valid) PlanPassed id turn seat (a player with no time points to play is passed automatically) PlanMissed id turn seat missed (a claimed timeout passes the turn of a player whose plan is not in, no commit or never revealed; Out at the MaxMissed-th in a row) PlayerSurrendered id turn player seat TurnResolved id turn rev seed VictoryPoints id seat player reason points (one per award at the end of a turn or of the showdown, rule 15; points < 0 for a loss) GameEnded id reason winner PotPaid id seat player amount (ugnot; one per winner, a draw splitting the pot, stakes.gno) StakeRefunded id seat player amount (a showdown cancelled, or ended with everyone out of time, gives the stakes back) HouseWithdrawn to amount AdminChanged admin PlanDue id turn turns to char vs left (a turn started: one per player with a plan to send; char its character, vs the others', left the time the turn gives; notify.gno) RevealDue id turn turns to char vs (the reveals started: one per player whose committed plan is not revealed) ShowdownOver id to char vs outcome (the game ended: one per player, "you won", "you lost", "a draw"; a cancelled game, to the players who had joined) They land in transaction results; clients still poll Game.Rev to sync. PlanDue, RevealDue and ShowdownOver name their recipient, for the browser notifications (notify.gno).

realmPath

DefaultTimeout

MinTimeout

MaxTimeout

MinMaxTurns

MaxMaxTurns

MaxMissed

RevealGrace

LockDelay

MaxLocked

MaxSalt

DrandGenesis

DrandPeriod

Phase

Phase is where a game stands.

PhaseWaiting

PhasePlanning

PhaseFinished

PhaseRevealing

Player

Player is a seat: the address that controls it (empty while nobody took it) and its character token.

TurnResult

TurnResult is the outcome of one resolved turn, kept so the client can replay it: the state the turn started from, the plans (one per seat), and what happened. Seed lets anyone re-run the resolution; Cards is the trace of the result cards drawn from the deck it shuffles, in order. The start snapshot, the weapons on the ground at the start, the cards and the events are kept in the engine's compact text encodings: as structs they cost a hundred times more storage (see engine/encode.gno). With the ground, a turn is shown from its own record, without the turns before it.

newTurnResult

Sealed

Sealed is a seat's sealed plan for the turn in progress, cleared by its reveal.

Game

Game is one showdown. Players, Commits, Plans, Salts, Revealed, Missed and VP have one entry per seat, the seats filling up in the order the players join.

games

// id -> \*Game

gameSeq

byPlayer

// address -> \[]string game ids, newest first

openGames

// id -> \*Game while a seat is free

getGame

PlanHash

PlanHash is what a seat commits: the sha256, in hex, of its salt and plan for that game, turn and seat ("gnoslinger|id|turn|seat|salt|plan").

save

save records a change: bumps the revision and the activity clock.

index

unindex

unindex removes id from addr's games, and addr from byPlayer once it has none left.

listLimit

liveScan

liveScan is how many of the newest games GamesJSON looks through for the ones being played: what the view costs stays bounded however many games there are.

endedLimit

endedLimit is how many of the last finished games GamesJSON lists.

GameJSON

GameJSON is the full view of a game: {"id","rev","phase","turn","maxTurns","timeout" (seconds),"board", "players":[{"addr" ("" for a seat nobody took yet),"name","char","hex" ("" until the seat set up),"facing","down","delay","status","committed","revealed","locked" (its timelocked plan, "" once revealed),"missed" (turns in a row it let time out),"playedFoot","playedRun","ranLastTurn", "aim","aimAt" (the seat the AIM markers follow, -1 when they sit on a hex or there is no aim),"aimHex" (the hex they sit on, "" when they follow a seat),"endurance","serious","gunArm","otherArm","leg", "guns":[{"id","type","name","location","cocked","shells","capacity","jammed","exploded"}]}] (one entry per seat, 2 to 4), "ground":[{"id" (ground id, "g<id>" in a plan),"hex","guns":[{..}]}], "winner","vp":[victory points per seat],"awards":[{"p","reason","points"}] (rule 15, once a played game ends), "stake" (ugnot each player puts in, 0 for a free showdown),"pot" (the stakes paid so far),"payouts":[ugnot each seat got, [] until paid],"houseCut" (stakes.gno),"endReason", "createdAt","updatedAt","timeoutAt" (when the turn in progress can be claimed, 0 unless planning or revealing), "commitUntil" (the turn's deadline),"revealUntil" (when unrevealed seats can be claimed out),"lockRound" (the drand round the plans are timelocked to) (0 unless planning or revealing), "lastTurn":null|{"turn","seed","cards":[result card numbers drawn, in order],"plans":[..], "events":[{"seg","p","kind","action","from","to","facing","down","n","delay","reason","card","result","endurance","target","hit","range","gun","gunId","step","chart","status"}], "start":[{"hex","facing","down","delay","status","aim","aimAt","aimHex","endurance","serious","gunArm","otherArm","leg","guns":[..]},..], "ground":[the weapons on the ground at the turn's start, as "ground" above]}} Times are unix seconds; winner, events\[].p and events\[].target are seat indexes, -1 for none. The plans of the turn in progress are hidden until revealed: only their commits show, as flags and timelocked plans.

PlanJSON

PlanJSON is where an address's plan for the turn in progress stands; the plan itself shows once revealed: {"id","turn","seat" (-1 when addr is not a player),"committed","revealed","plan" ("" until revealed)}

TurnJSON

TurnJSON is one resolved turn of a game (from 1), the turn result as json/game writes its last one: what replays read, a turn per query (the "json/history/{id}/{turn}" view), so that what a query costs does not grow with the game. Each turn is self-contained (its start and ground).

HistoryJSON

HistoryJSON is every resolved turn of a game, oldest first, for tests and tools (the tutorial's showdown, make gen-tutorial); no view serves it: a long game's history may cost more than a query can. {"id","turn","phase","players":[{"addr","char"}],"turns":[turn result...]}

writePlayer

writeWounds

writeWounds writes the aim and wound members of a character.

writeTimeoutAt

writeTimeoutAt writes the ,"timeoutAt" member: when the turn in progress can be claimed, 0 unless the game is planning or revealing.

writeGround

writeGround writes the ,"ground":\[...] member: the weapons lying in hexes.

writeGuns

writeGuns writes the ,"guns":\[...] member of a character.

writeTurnResult

writeEvent

GamesJSON

GamesJSON lists, for an address, the games with a free seat, the games being played (live: planning or revealing, for anyone to watch), the last endedLimit games finished (ended, for anyone to replay) and the games it plays or played, newest first (at most 50 each), with the address's registered name ("" if none). live and ended are found among the liveScan newest games, a running game being recent: a turn times out within days. {"name","open":[summary...],"live":[summary...],"ended":[summary...],"mine":[summary...]} summary = {"id","rev","phase","turn","maxTurns","timeout","winner","endReason","vp","stake","pot","payouts","houseCut","createdAt","updatedAt","timeoutAt","lockRound","players":[{"addr","name","char","status","committed","revealed"}]} lockRound (0 unless planning or revealing) tells the lobby when the timelocked plans of a seat committed and not revealed can be opened. players has one entry per seat, "addr" "" for a seat nobody took yet.

writeSummary

writeVP

writeVP writes the victory points of each seat.

writeStakes

writeStakes writes the stake, the pot and, once paid, what each seat got.

quote

quote encodes s as a JSON string.

GameRev

GameRev is the cheapest way to poll a game for changes.

CreateGame

CreateGame opens a showdown of seats players (engine.MinPlayers to engine.MaxPlayers) with the caller in seat 0, playing the showdown's first character (engine.Setups: the marshal), standing in startHex, one of the hexes assigned to that character, facing f (0=N 1=NE 2=SE 3=S 4=SW 5=NW); it returns the game id. The other seats take the next characters in the order the players join. maxTurns is the game length, from MinMaxTurns to MaxMaxTurns; timeoutMinutes is the time each turn gives the players, past which anyone may claim it with ClaimTimeout, 0 meaning DefaultTimeout (2 days). The game stays open until its seats fill up or its creator cancels it: the turn clock starts with the last join. The ugnot sent with the call are the showdown's stake, which every joiner must send too; none, a free showdown (stakes.gno).

JoinGame

JoinGame seats the caller in the first free seat of a waiting game, playing that seat's character (the kid, then the reb, then the yankee), standing in startHex, one of that character's hexes, facing f; the game starts collecting the commits of turn 1 once its last seat is taken. The call must send the showdown's stake, no more, no less.

assertSetUp

assertSetUp refuses a character that is not in the showdown, a hex it may not set up in, or no such facing.

CancelGame

CancelGame withdraws a game whose seats are not all taken yet. Creator only. The game is deleted, not kept as finished, so the creator gets back the storage deposit CreateGame paid; the players who had joined are unindexed with it, and every stake paid goes back.

notifTriggers

notifTriggers are the realm's triggers, by name. Title and body are templates, {key} standing for the event's attribute: every event names the player's character (char) and the others' (vs), and the game; the link opens the game in the client (game/route.ts).

notif

notif is the realm's handle on its triggers in the registry, kept so that DeclareTriggers can set them again: a changed title, body or link keeps the trigger's id, and so the browsers opted in.

DeclareTriggers

DeclareTriggers sets the realm's triggers in the gnotif registry. Admin only, and the first call has what the registry's Open requires: the namespace owner's own key (not a session), in a call sent straight to the realm; so the deployer sends it once the realm is deployed (on gnodev, the make notif script sends it as test1). The triggers keep their ids from one call to the next. Every call makes the registry emit each trigger again (TriggerDeclared), which is what a gnotif server reads them from: the registry emits nothing for a trigger set as it already is, so each is first set with a nudged body, then as it should be. That is for gnodev, whose reload puts the earlier call in the genesis, where no indexer serves its events: the script calls again after each reload and the triggers reach gnotifd anew.

charName

charName spells a character key as the client does: "the\_kid" is "The Kid".

formatTimeout

formatTimeout spells the time a turn gives: whole days, else whole hours, else minutes.

Commit

Commit seals the caller's plan for the given turn, the one in progress, and returns the game revision (a commit meant for another turn, say one still on its way when time was called, is refused: its hash, which covers the turn, could never be revealed in this one, and it would take the seat's commit). hash is PlanHash of a salt and the plan, which a Reveal shows once every character still in the fight committed; locked is the salt and plan timelocked to the turn's LockRound (at most MaxLocked bytes, required: encrypting needs no drand node), which anyone can open and reveal from then if the player does not. When this commit is the last one the turn waits for, the game moves on to the reveals.

Reveal

Reveal puts a seat's salt and plan for the given turn on chain and returns the game revision. Anyone may send it while the game collects the reveals: the salt and plan must match the seat's commit (PlanHash). The last seat to commit may also reveal straight away, without committing: the others' plans are already fixed by their hashes, so its plan in clear helps nobody; that is only accepted from the seat itself, before the deadline, once every other character still in the fight committed (a refused transaction still shows its plan). The plan is a comma-separated list of "\<card>\<f|b>\[:\<choice>]" entries, e.g. "1f:ahead\_left,2f:ahead,3f"; an empty string passes. The reveal that completes the turn resolves it in this same transaction and the next turn starts.

RevealMany

RevealMany reveals several seats of the given turn in one transaction, as Reveal does each, in the order given: what an opener of the timelocked plans sends. seats, salts and plans are lists separated by ";", of the same length (a plan string never holds a ";", an empty plan is an empty field). A seat already revealed is skipped (its player's own reveal landed first), and so is one whose salt and plan do not match its commit or whose plan is not valid (event PlanUnopened): the opener cannot check that before opening, and one bad timelocked plan must not keep the others back; that seat stays unrevealed, for the claim.

revealSeat

revealSeat checks a committed seat's salt and plan against its hash and stores them, clearing the commit.

checkReveal

checkReveal tells why a committed seat's salt and plan cannot be revealed, "" if they can.

checkPlan

checkPlan parses and validates a seat's salt and plan; why is "" when they are fine.

storePlan

storePlan validates a seat's plan and records it as revealed, clearing its commit (whose storage deposit goes back to the caller).

isHex

isHex reports whether s is min to max lowercase hex characters.

progress

progress moves the turn on as far as it can: it passes the players who cannot play anything (a carried delay of 5 or more leaves no time points, rule 7.3: there is nothing to wait for from them), goes on to the reveals once every character in the fight committed, and resolves the turn once every plan is in; when nobody is left to wait for in the next turn either, that turn resolves at once, and so on.

resolveTurn

resolveTurn plays the seats' plans with the result deck shuffled from this turn's seed, stores the result and advances the game. It returns the seed in hex.

groundExists

groundExists reports whether a gun with that ground id lies somewhere on the board; whether it is in the character's hex is checked when the action executes, since the character may walk to it first.

Surrender

Surrender gives up the showdown (rule 15.4: at the start of a turn, that is while the plans are committed; once they are revealed, surrendering after reading the others' would be the abort the hidden plans remove). The character is Out: nobody can shoot it and it plays no more. With one character left in the fight the game ends and is scored, the surrendered losing the "Surrender" points and, an enemy holding the field, being captured; with more, the showdown goes on without it (its commit is dropped), and goes on to the reveals if the others' plans are committed.

ClaimTimeout

ClaimTimeout ends the wait of a turn past its deadline. Anyone may call it. A game waiting for players has no timeout (its creator may cancel it). While the plans are committed, past the deadline: each player who did not commit misses the turn: it is passed for them, unless that makes MaxMissed in a row, which puts the character out of the fight (out of time counts as surrendering); the game then goes on to the reveals, and with nobody's plan in, the turn resolves empty. A showdown nobody plays any more so ends after MaxMissed claims, everyone out of the fight (its stakes given back, stakes.gno). While they are revealed, RevealGrace past the deadline (the timelocked plans had time to be opened, which is how a vanished player's plan normally comes in): every character whose plan is still not in misses the turn the same way. The realm cannot tell a copy nobody could open from one nobody tried to open, so it does not punish more than a missed turn. With one character left the game ends and is scored, with more the turn resolves with the plans in and the showdown goes on.

missTurn

missTurn passes the turn for a seat whose plan is not in at the claim (its commit, if any, dropped), or puts the character out of the fight at its MaxMissed-th miss in a row; only a revealed plan resets the count.

recentLimit

router

init.78

Render

Render serves the gnoweb pages ("", "help", "game/{id}") and the raw JSON views the web client reads ("json/game/{id}", "json/games/{addr}", "json/history/{id}/{turn}", "json/plan/{id}/{addr}"); the players' profiles and ranking are the profiles realm's (gno.land/r/g1th0masp67zfs9lg6d34qhghldhg6kjcqjuv7c2/gnoslinger/profiles/v0).

link

link is a gnoweb link to a sub-path of this realm.

renderHome

renderGame

renderHelp

cancelReason

cancelReason is the reason of a cancel event as the log shows it: the reason code, except a target out of sight, spelled out with the obstacle in the way.

noSight

noSight words a no\_los reason: the event's To names the obstacle in the way.

sideLabel

describeEvent

seatLabel

seatLabels

seatLabels names every seat, "marshal vs the\_kid vs ?".

createLink

createLink is a transaction link to call a showdown of seats players, standing in the middle of the marshal's hexes, facing its way.

joinLink

joinLink is a transaction link to take the next free seat of a waiting game, standing in the middle of its character's hexes.

gnot

gnot words an amount of ugnot in GNOT: "5 GNOT", "9.5 GNOT".

stakeLabel

stakeLabel words a showdown's stake: "free", or "5 GNOT each".

setupList

setupList words where each character sets up: "the marshal in A-G5 to A-G9, ...".

phaseLabel

addr

addr shows an address by its registered name when it has one.

when

yesNo

orPass

Denom

HouseCutPercent

house

admin

sentStake

sentStake returns the ugnot sent with the call, 0 for none. Coins can only come straight from a user's call: a realm in between could have spent the send it reports (unsafe.OriginSend is the whole message's).

assertNoSend

assertNoSend refuses coins sent with a call that takes none: they would sit in the realm's balance with no showdown to pay them out.

pay

pay sends amount ugnot from the realm to addr.

WithdrawHouse

WithdrawHouse sends amount ugnot of the house's funds to an address. Admin only.

SetAdmin

SetAdmin hands the house's funds over to another admin. Admin only.

assertAdmin

House

House is the ugnot the house holds for events.

Admin