smoke

Documentation

Overview

Package smoke runs a game's smoke.yaml: a small deterministic script (seed, seats, steps) that drives the game on a virtual clock and dumps named 80×24 screens. The same script powers three surfaces:

• `go run . -smoke smoke.yaml` — the native inner loop (kit.Main dispatches here; no TinyGo, no terminal needed)
• `shellcade-kit smoke <gamedir>` — the canonical path: the same script against the built wasm artifact, rendered through this package's encoder, so a deterministic game produces byte-identical shots
• the games catalog CI, which renders the shots as PR previews

A smoke.yaml looks like:

seed: 42        # required — room RNG seed (deterministic)
seats: 2        # required, 1..8 — seats joined before the first step
heartbeat: 50ms # optional — wake cadence during `advance`
config:         # optional — per-game config values
  variant: classic
steps:
  - shot: lobby       # dump the current screen(s), named "lobby"
  - rune: "5"         # printable rune → current seat
  - key: enter        # named key: enter/backspace/esc/tab/arrows/space
  - text: "hello"     # sugar: one rune step per character
  - seat: 1           # switch the current input seat (sticky)
  - advance: 1.5s     # sweep the clock, waking once per heartbeat
  - wake:             # a single wake without moving the clock
  - shot: reveal
    seats: [0, 1]     # optional filter; default = all seats

Shots default to every seat and collapse to one file when all captured frames are identical (broadcast games). Two runs of the same script against the same game produce byte-identical output — `advance` is the only clock, the RNG is seeded, and all seats are joined up-front (seat i is AccountID "seat-<i>", Handle "seat<i>"). See GUIDE.md "Smoke scripts" for authoring guidance, including picking quiescent or exact-tick moments in animated games.

Index

• Constants
• func RenderANSI(f *kit.Frame) []byte
• func RenderText(f *kit.Frame) []byte
• func SeedEpoch(seed int64) time.Time
• func WriteShots(dir string, shots []Shot) ([]string, error)
• type Script
  • func Parse(b []byte) (*Script, error)
• type Shot
  • func Run(g kit.Game, s *Script) ([]Shot, error)
• type Step
• type StepKind

Constants

const (
	StepRune    = internal.StepRune
	StepKey     = internal.StepKey
	StepSeat    = internal.StepSeat
	StepAdvance = internal.StepAdvance
	StepWake    = internal.StepWake
	StepShot    = internal.StepShot
)

const DefaultHeartbeat = internal.DefaultHeartbeat

DefaultHeartbeat is the wake cadence when smoke.yaml omits heartbeat.

Functions

func RenderANSI

func RenderANSI(f *kit.Frame) []byte

RenderANSI renders a frame to the canonical shot byte form: 24 truecolor ANSI lines, LF separators, trailing newline.

func RenderText

func RenderText(f *kit.Frame) []byte

RenderText renders a frame as plain text (full grapheme clusters, no escape sequences, trailing blanks trimmed) — the greppable twin of RenderANSI.

func SeedEpoch

func SeedEpoch(seed int64) time.Time

SeedEpoch is the virtual-clock start for a seed — the same fixed, seed-derived instant the dev runner's -seed mode uses. Any harness running a smoke script (the devkit CLI's wasm path included) must start its clock here for runs to agree byte-for-byte.

func WriteShots

func WriteShots(dir string, shots []Shot) ([]string, error)

WriteShots writes each shot's .ansi and .txt files into dir: NN-<name>.{ansi,txt} when the shot collapses (single seat or identical frames), NN-<name>.seat<K>.{ansi,txt} otherwise. Returns the file names.

Types

type Script

type Script = internal.Script

Script is a parsed smoke.yaml.

func Parse

func Parse(b []byte) (*Script, error)

Parse decodes and validates a smoke.yaml; errors name the offending line.

type Shot

type Shot = internal.Shot

Shot is one captured screen dump: the frames of every captured seat.

func Run

func Run(g kit.Game, s *Script) ([]Shot, error)

Run executes a parsed script against the game natively on a virtual-clock, seeded room, returning the captured shots in script order.

type Step

type Step = internal.Step

Step is one parsed script step (text: steps are pre-expanded to runes).

type StepKind

type StepKind = internal.StepKind

StepKind enumerates the script step vocabulary.