@flayerlabs/gamemode-spec

Define deterministic game rules and share the contracts used by Game Mode servers and browsers.

Requirements

Install the package with Node.js 20 or later:

pnpm add @flayerlabs/gamemode-spec

Choose an entry point

The package exports these public entry points:

| Entry point | Use it to | |---|---| | @flayerlabs/gamemode-spec | define a game module, commands, decisions, awards and views | | @flayerlabs/gamemode-spec/round | run or resume a game round with the shared round driver | | @flayerlabs/gamemode-spec/schedule | turn phase durations into fixed timestamps inside a round window | | @flayerlabs/gamemode-spec/live | share launch, round terms, economy, market, identity, player-ticket and live-room message types | | @flayerlabs/gamemode-spec/embed | parse registry and iframe data, then build canonical spend typed data |

Import only the entry points you need:

import { defineGame } from '@flayerlabs/gamemode-spec'
import { Round } from '@flayerlabs/gamemode-spec/round'
import { scheduleWithin } from '@flayerlabs/gamemode-spec/schedule'

Validate trusted-platform responses

The trusted parent should parse HTTP data before it chooses a gate, deploy or room:

import { parseGameRegistration } from '@flayerlabs/gamemode-spec/embed'
import { isLaunchContext } from '@flayerlabs/gamemode-spec/live'

const registration = parseGameRegistration(await registryResponse.json())
if (!registration) throw new Error('invalid game registration')

const launch: unknown = await adoptionResponse.json()
if (!isLaunchContext(launch)) throw new Error('invalid launch context')

Compare the parsed chain, coin and round with the trusted page selection as well. A valid shape does not prove that the response belongs to the coin the player opened.

gateOrigin is the default network surface for a registered game. A registration needs gameServerOrigins only when a creator gameplay server uses a separate reviewed origin. The parser accepts exact HTTPS origins and rejects wildcards, paths and credentials.

Define game rules

A GameModule owns action parsing, initial state, decisions, state changes, public views, player-specific views, wake times and reward limits.

Your rules must:

• return the same output for the same state and command
• read time from command.at
• derive any random values from the supplied seed
• award points only from decide
• keep secrets out of the publicView return type
• reject malformed and oversized actions in parseAction
• declare the maximum points one player can earn in rewardBounds

Use Round in tests and offline tools. The production gate uses the same driver, so ordering and wake behaviour remain the same.

Follow the authoring contract

Read the game-building guide before writing a rules module.

Use the reference implementations for different game shapes:

• quiz rules with delayed awards
• arrow rules with immediate scoring
• example tests

The /embed entry point also exports GateReadiness, parseGateReadiness, gateReadinessTypedData and READINESS_TTL_SECONDS for non-spend gate identity proofs.

See what changed

This package ships CHANGELOG.md and MIGRATING.md, shared by all four Game Mode packages. Read them on GitHub: changelog and migration guide.