Catch and stack

The pack

catchStack

function catchStack(): Pack<{ catchStack: typeof api }>

Install the renderer-independent catch-stack (Klax) rules API under game.catchStack.

Helpers

createCatchStack

function createCatchStack(config: CatchStackConfig): CatchStackGame

Create a game from a full configuration (see klaxPreset and tileTumblePreset for ready-made ones).

crossedDiagonals

function crossedDiagonals(lines: readonly BinLine[], minLength: number): boolean

Is there a "Big X" among these lines: two diagonals of opposite slope, each at least minLength long, that cross on a shared cell? (Klax: both 5-long diagonals of the 5 × 5 bin, centre tile placed last.)

findLines

function findLines(columns: BinColours, width: number, height: number, options: FindLinesOptions): BinLine[]

Every maximal run of at least minLine tiles of one colour, along every enabled direction.

Wild tiles (WILD) match any colour, so one wild tile can sit in several lines of different colours at once (the Klax wild-tile combos). A run must contain at least one tile of its own colour; a run made only of wild tiles is reported once with colour WILD. Runs are maximal: a row of five is one line of length 5, never three overlapping threes.

KLAX_BIG_X

const KLAX_BIG_X: StackPatternWarp

The Big X: both 5-tile diagonals on waves 6 and 11 jump 45 waves ahead (to 51 and 56) with a 500,000 bonus.

KLAX_GOAL_ORDER

const KLAX_GOAL_ORDER: readonly StackGoal["kind"][]

The Klax wave-goal order inside each set of five (reconstruction; see the docs).

KLAX_SCORING

const KLAX_SCORING: StackScoring

Klax line scores (arcade, confirmed by the Lynx and NES manuals and the MAME history entry): vertical 50 / 10,000 / 15,000; horizontal 1,000 / 5,000 / 10,000; diagonal 5,000 / 10,000 / 20,000 for 3 / 4 / 5 tiles.

KLAX_WARP

const KLAX_WARP: StackWarp

Klax's warp screen: the next wave with 3 drops, five ahead with 4 drops and 100,000, ten ahead with 5 drops and 200,000.

klaxPreset

function klaxPreset(o: KlaxOptions = {}): CatchStackConfig

Klax (Atari Games, 1989–90): a 5-lane conveyor, a paddle that holds 5 tiles, a 5 × 5 bin, Klaxes of 3+ in any direction scored by type and length with combo multipliers, 100 waves with Klax, horizontal, diagonal, tile and point goals, warp screens every five waves, the Big X, a drop meter of 3–5, and wave-end bonuses.

klaxWave

function klaxWave(n: number): StackWave

Klax wave n (1–100). Anchored on what is documented for the arcade: wave 1 is 3 Klaxes, wave 2 is 5 Klaxes, wave 3 is 3 diagonals, wave 6 is 10 Klaxes, wave 11 is 15 Klaxes, wave 100 is 250,000 points; wild tiles from wave 6; up to 8 colours; more tiles at once and faster tumbles as the waves rise; tiles speed up the longer a wave lasts. The goal amounts between the anchors and the pace numbers are a reconstruction (the ROM tables are not published) and are documented as such.

lineCredit

function lineCredit(line: Pick<BinLine, "length">, minLine: number): number

How many Klaxes a line counts as toward a wave goal: a line of minLine is 1, each extra tile adds 1 (Klax: 3/4/5 tiles = 1/2/3).

linePoints

function linePoints(line: Pick<BinLine, "direction" | "length">, points: LinePoints, minLine: number): number

The points one line scores, before any multiplier.

STACK_STEP

const STACK_STEP: number

The fixed simulation step: 120 Hz.

stackDifficulty

function stackDifficulty(name: StackDifficultyName): StackDifficulty

Difficulty scaling by name: Easy and Normal slow the tiles, space them out and add drops; Arcade changes nothing.

stackPreset

function stackPreset(name: "klax", options?: KlaxOptions): CatchStackConfig

Build a preset by name. Build the Tile Tumble preset; options are those of tileTumblePreset. Implementation of both overloads: builds the named preset with options. Throws for any name but "klax" or "tile-tumble".

tileTumblePreset

function tileTumblePreset(o: TileTumbleOptions = {}): CatchStackConfig

Tile Tumble: an endless score-attack built on the same API, materially different from Klax. A 7-lane conveyor and a 7 × 6 bin, a 3-tile paddle, lines of 4+ that score only horizontally and vertically (no diagonals), one flat points table by length, a per-set multiplier (no chains), common wild tiles, pulling down speeds up every tile, a long throw-back, and a single endless wave whose pace climbs for five minutes. No warps.

validateConfig

function validateConfig(c: CatchStackConfig): void

Validate a whole configuration. Throws on the first unsupported value, naming the field and the fix.

validateWave

function validateWave(w: StackWave, config: Pick<CatchStackConfig, "lanes" | "depth">, n: number): void

Validate a wave definition for a configuration, throwing a message that names the field.

waveCount

function waveCount(source: StackWaveSource): number

The number of waves in a source.

WILD

const WILD: -1

The colour index of a wild tile. A wild tile matches every colour, and several colours at once.

Classes

CatchStackGame

class CatchStackGame

A running catch-stack game. Drive it with steer/moveTo/drop/throwBack/accelerate and tick(dt); read state; take events with drain. Fixed 120 Hz steps inside; deterministic from the seed and the inputs.

• readonly config: CatchStackConfig — The configuration (validated).
• constructor(config: CatchStackConfig)
• get state(): DeepReadonly<CatchStackState> — The live state, read-only. Copy it (snapshot) to keep it.
• resolveWave(n: number): StackWave — The wave definition for wave n with difficulty applied.
• steer(dir: -1 | 0 | 1): void — Hold a direction (−1 left, 0 none, +1 right). Call every frame with the held state; a tap moves one lane, a hold keeps sliding after paddle.repeatDelay.
• nudge(dir: -1 | 1): void — Move the paddle one lane (a single tap).
• moveTo(lane: number): void — Send the paddle to a lane (pointer or touch).
• drop(): void — Flip the top paddle tile into the bin column under the paddle. Buffered until the paddle reaches its target lane.
• throwBack(): boolean — Throw the top paddle tile back up the conveyor. Returns false when it cannot (disabled, empty paddle, not playing).
• accelerate(held: boolean): void — Hold or release "pull down" (speed up tiles, per accelerate.mode).
• selectMove(dir: -1 | 1): void — Move the warp-screen highlight.
• choose(index = this.s.choice): void — Take a warp-screen choice (default: the highlighted one).
• continueGame(): void — After the game ends, play the same wave again with an empty drop meter (an arcade continue). Score is kept.
• goToWave(n: number): void — Jump to a wave now (debug, practice, a level-select screen). Keeps the score and drop meter.
• tick(dt: number): StackEvent[] — Advance by dt seconds (fixed 120 Hz steps inside). Returns events produced since the last drain.
• drain(): StackEvent[] — Take the events produced since the last drain.
• snapshot(): CatchStackSnapshot — A deep copy of everything, for save/replay.
• restore(snap: CatchStackSnapshot): void — Restore a snapshot taken from a game with the same configuration.

Types

BinCell

interface BinCell

A bin cell: column x (0 = left) and row y (0 = bottom).

• x: number — Column, 0 = left.
• y: number — Row, 0 = bottom of the bin.

BinColours

type BinColours = ReadonlyArray<ReadonlyArray<number | null | undefined>>

A read-only view of a bin: columns[x][y] is the colour of the tile in column x, row y (0 = bottom), or null/undefined for empty. Columns may be ragged (a column array as long as its stack).

BinLine

interface BinLine

One line of same-colour tiles found in the bin.

• direction: LineDirection — Which way it runs.
• slope: 1 | -1 | 0 — For diagonals: +1 rises to the right, -1 rises to the left. 0 for the other directions.
• length: number — The number of tiles in it.
• colour: number — The colour it matched. WILD (-1) when every tile in it is wild.
• cells: BinCell[] — Its cells, in order along the line.

BinTile

interface BinTile

A tile in the bin.

• id: number — Stable id.
• colour: number — Colour index or WILD.
• y: number — Where it is drawn, in rows (it falls to its row index).
• clearing: boolean — True while it flashes in a line about to clear.
• fresh: boolean — True until it lands (it came from the paddle and has not scored its placement yet).

CatchStackConfig

interface CatchStackConfig

Everything that defines a catch-stack game. Presets build these; every field is public configuration.

• lanes: number — Conveyor lanes, which are also the bin's columns (the paddle drops into the column under it). Klax: 5.
• depth: number — Bin rows (Klax: 5).
• rampSteps: number — Ramp steps from the top of the conveyor to the paddle: one tumble per step.
• minLine: number — The shortest scoring line (Klax: 3).
• directions: LineDirections — Which line directions score.
• scoring: StackScoring — Scoring tables.
• waves: StackWaveSource — The waves.
• drops: number — Drop meter size when no warp screen sets it (and before the first warp when warp.atStart is false).
• warp: StackWarp | null — Warp screens; null for none.
• patternWarps: ReadonlyArray<StackPatternWarp> — Secret pattern warps (Klax's Big X).
• tileGoal: "caught" | "any" — For tiles goals: count tiles caught only, or every tile that reaches the end of the ramp (caught or missed).
• binFullEnds: boolean — The bin filling up completely ends the game (Klax: yes).
• accelerate: StackAccelerate — Pulling down.
• throwBack: StackThrowBack | null — Pushing up; null disables it.
• paddle: StackPaddle — The paddle.
• timing: StackTiming — Timings.
• difficulty: StackDifficulty — Difficulty scaling.
• startWave: number — The first wave (used directly when there is no start warp screen, and as the base of the start choices).
• seed: number — Seed for tile colours, lanes and wild tiles.

CatchStackSnapshot

interface CatchStackSnapshot

A saved game: restore it with restore.

• state: CatchStackState — The state.
• internal: { rng: RngState; nextId: number; spawnTimer: number; sequenceAt: number; steer: number; heldFor: number; dropQueued: boolean; accel: boolean; acc: number } — Internal counters; rng is where the seeded stream stands (a kernel Rng snapshot).

CatchStackState

interface CatchStackState

The whole game state. Read it every frame; change it only through the methods.

• status: StackStatus — Where the game is.
• statusTime: number — Seconds in this status.
• wave: number — The current wave number.
• waveCount: number — The number of waves.
• waveDef: StackWave — The current wave's definition (difficulty applied).
• score: number — Total score.
• waveScore: number — Points scored in this wave.
• drops: number — Tiles dropped since the meter was last reset.
• dropLimit: number — Drops that end the game.
• goal: StackGoalState — Goal progress.
• tilesSeen: number — Tiles that reached the paddle end this wave (caught, plus missed when tileGoal is any).
• waveTime: number — Seconds of play in this wave (drives the pace ramp).
• pace: { step: number; interval: number } — The current step time and spawn interval.
• ramp: RampTile[] — Tiles on the conveyor.
• paddle: PaddleState — The paddle.
• bin: BinTile[][] — The bin, by column; each column bottom first.
• missed: MissedTile[] — Missed tiles falling into the pit.
• clearing: { cells: BinCell[]; t: number; total: number } | null — Lines flashing before they clear.
• cascade: number — Lines made so far in the current cascade (the multiplier under cascade scoring).
• lastKlax: StackKlax | null — The last lines scored (cleared when the wave changes).
• klaxCount: number — Number of line sets scored this wave.
• rampPaused: boolean — True while the conveyor is stopped for a clear.
• choices: StackChoice[] — Warp screen choices (status select).
• choice: number — The highlighted choice.
• tally: StackTally | null — Wave-complete breakdown (status complete).
• pendingBonus: number — A warp bonus waiting on this wave's completion.
• patternWarp: number — Where a pattern warp will take the game when this wave ends (0 = none).
• overReason: "drops" | "bin-full" | null — Why the game ended (status over).
• continues: number — Continues used.
• columnFull: boolean[] — For each column: true when it is full (the arcade's red light under the bin).

DeepReadonly

type DeepReadonly<T> = T extends (infer U)[] ? ReadonlyArray<DeepReadonly<U>> : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> } : T

A deep read-only view.

FindLinesOptions

interface FindLinesOptions

Options for findLines.

• minLine: number — The shortest run that counts (Klax: 3).
• directions?: LineDirections — Which directions count. Default: all three.

KlaxOptions

interface KlaxOptions

Options for klaxPreset. Every geometry and rule field can also be changed on the returned config.

• difficulty?: StackDifficultyName — Easy, Normal (default) or Arcade.
• seed?: number — Seed. Default 1.
• startWave?: number — Start wave when the start warp screen is off. Default 1.
• startWarp?: boolean — Offer the warp screen at the start (wave 1, 6 or 11). Default true.
• lanes?: number — Lanes and bin columns. Default 5.
• depth?: number — Bin rows. Default 5.
• paddleCapacity?: number — Paddle capacity. Default 5.
• minLine?: number — The shortest line. Default 3.
• directions?: Partial<LineDirections> — Which directions score. Default all three.
• colours?: number — Override the colours dealt in every wave.
• wild?: number — Override the wild-tile chance in every wave.
• bigX?: boolean — The Big X secret warp. Default true.

LineDirection

type LineDirection = "vertical" | "horizontal" | "diagonal"

Which way a line runs. vertical is up a column, horizontal is along a row, diagonal is either slope.

LineDirections

interface LineDirections

Which line directions score.

• vertical: boolean — Up a single column (Klax: the cheapest).
• horizontal: boolean — Along a row, across columns.
• diagonal: boolean — Either diagonal.

LinePoints

interface LinePoints

Points per line direction, indexed by length − minLine (index 0 = the shortest line). Longer lines use the last entry.

• vertical: readonly number[] — Vertical lines by length (Klax: 50, 10,000, 15,000).
• horizontal: readonly number[] — Horizontal lines by length (Klax: 1,000, 5,000, 10,000).
• diagonal: readonly number[] — Diagonal lines by length (Klax: 5,000, 10,000, 20,000).

MissedTile

interface MissedTile

A missed tile falling into the pit.

• id: number — Stable id.
• colour: number — Colour index or WILD.
• lane: number — The lane it fell from.
• t: number — Seconds since it fell.
• reason: "missed" | "paddle-full" — Why: no paddle under it, or the paddle was full.

PaddleState

interface PaddleState

The paddle.

• x: number — Position in lanes (fractional while sliding).
• target: number — The lane it is in or heading to.
• lane: number — The lane it catches in: the nearest lane to x.
• stack: PaddleTile[] — The tiles it holds, bottom first; the last is the top tile.
• full: boolean — True when it can take no more tiles (the arcade's red light).

PaddleTile

interface PaddleTile

A tile held on the paddle (index 0 is the bottom).

• id: number — Stable id.
• colour: number — Colour index or WILD.

RampTile

interface RampTile

A tile on the conveyor. depth runs 0 (top of the ramp) to 1 (the paddle end).

• id: number — Stable id for the tile's whole life (ramp, paddle, bin).
• colour: number — Colour index or WILD.
• lane: number — Lane, 0 = left.
• step: number — Whole ramp steps completed.
• phase: number — Progress through the current tumble, 0–1.
• mode: "down" | "thrown" — Tumbling down, or thrown back up.
• air: number — For thrown tiles: seconds in the air so far.
• landStep: number — For thrown tiles: the step it will land on.
• depth: number — Where it is, 0 (top) to 1 (paddle end), for drawing.
• angle: number — Its tumble angle in radians (0 = lying flat; π/2 = standing on end). Negative while thrown back.
• fast: boolean — True while sped up by pulling down.

ScoredLine

interface ScoredLine extends BinLine

A scored line, with its points and goal credit.

• points: number — Points before the multiplier.
• credit: number — Goal credit (Klax: 3/4/5 tiles count 1/2/3).

StackAccelerate

interface StackAccelerate

What pulling down does: speed up the nearest tile (arcade), the nearest tile in the paddle's lane, or all tiles (home ports).

• mode: "nearest" | "lane" | "all" — Which tiles speed up while down is held.
• factor: number — Speed multiplier while held.

StackChoice

interface StackChoice

A warp screen choice.

• wave: number — The wave it starts.
• drops: number — The drop meter size it gives (difficulty extra drops included).
• bonus: number — Bonus when that wave is completed.

StackDifficulty

interface StackDifficulty

Difficulty scaling applied to every wave (Arcade is 1, 1, 0).

• speed: number — Tile speed multiplier (0.8 = 20% slower tumbles).
• interval: number — Spawn interval multiplier (1.2 = 20% more time between tiles).
• extraDrops: number — Drops added to every drop meter.

StackDifficultyName

type StackDifficultyName = "easy" | "normal" | "arcade"

The three difficulty settings every arcade rules pack offers. Arcade is the original tables.

StackEvent

type StackEvent = | { kind: "spawn"; id: number; lane: number; colour: number } | { kind: "catch"; id: number; lane: number; colour: number; held: number } | { kind: "miss"; id: number; lane: number; colour: number; reason: "missed" | "paddle-full"; drops: number; dropLimit: number } | { kind: "throw"; id: number; lane: number; colour: number } | { kind: "flip"; id: number; column: number; colour: number } | { kind: "blocked"; column: number; reason: "column-full" | "empty-paddle" } | { kind: "land"; id: number; column: number; row: number; colour: number; points: number } | { kind: "klax"; klax: StackKlax; cascade: number } | { kind: "cleared"; cells: BinCell[] } | { kind: "pattern-warp"; from: number; to: number; bonus: number } | { kind: "wave-start"; wave: number; goal: StackGoal } | { kind: "playing"; wave: number } | { kind: "wave-complete"; wave: number; tally: StackTally } | { kind: "select"; choices: StackChoice[] } | { kind: "warp"; to: number; drops: number; bonus: number } | { kind: "over"; reason: "drops" | "bin-full"; wave: number } | { kind: "finished"; score: number } | { kind: "continue"; wave: number; continues: number }

Ordered events from tick and drain.

StackGoal

interface StackGoal

A wave goal. endless never completes (score attack until the drop meter or bin fills).

• kind: StackGoalKind — The kind of goal.
• count: number — How many: lines (credit), points scored in the wave, or tiles. Ignored for endless.

StackGoalKind

type StackGoalKind = "klaxes" | "horizontals" | "diagonals" | "verticals" | "points" | "tiles" | "endless"

What a wave asks for. Line goals count Klax credit (a line of minLine is 1, each extra tile 1 more).

StackGoalState

interface StackGoalState

Goal progress.

• kind: StackGoalKind — The kind.
• count: number — The target.
• done: number — Progress so far (lines credit, wave points, or tiles).
• remaining: number — What the "to go" meter shows.

StackKlax

interface StackKlax

The last set of lines scored.

• lines: ScoredLine[] — The lines.
• points: number — Sum of their points.
• multiplier: number — The multiplier applied.
• total: number — points × multiplier.

StackPaddle

interface StackPaddle

The paddle's movement.

• speed: number — Lanes per second it slides.
• repeatDelay: number — Seconds a direction must be held before the paddle keeps sliding lane after lane. A tap moves one lane.
• capacity: number — How many tiles it holds (Klax: 5). A tile that reaches a full paddle is dropped.

StackPatternWarp

interface StackPatternWarp

A secret warp: build two crossing diagonals of at least minLength on one of waves to jump skip waves ahead.

• waves: ReadonlyArray<number> — The waves where the pattern warps.
• minLength: number — The shortest diagonal that counts (Klax's Big X: 5).
• skip: number — How far ahead it jumps (Klax: 45).
• bonus: number — Bonus paid at the end of the wave that made it.

StackScoring

interface StackScoring

Scoring tables.

• lines: LinePoints — Points per line, by direction and length.
• place: number — Points for each tile that lands in the bin (Klax: 5).
• multiplier: "cascade" | "set" | "none" — How simultaneous and chained lines multiply: cascade multiplies each set's points by the number of lines made so far in the cascade (Klax: two lines at once score ×2; a chained third line scores ×3); set by the lines in that set only; none adds plain points.
• emptyCell: number — Wave-end bonus for each empty bin cell (Klax: 200).
• unplacedTile: number — Wave-end bonus for each tile still on the ramp or paddle (Klax: 25).
• pointsOverflow: number — Wave-end bonus per point scored beyond a points goal (Klax: 1).

StackSequenceTile

interface StackSequenceTile

One authored tile in a wave's opening sequence.

• lane: number — The lane it comes down, 0 = left.
• colour: number — Its colour index, or WILD (-1).

StackStatus

type StackStatus = "select" | "intro" | "playing" | "complete" | "over" | "finished"

Where a game is.

StackTally

interface StackTally

The wave-complete bonus breakdown.

• emptyCells: number — Empty bin cells.
• emptyPoints: number — Their bonus.
• unplaced: number — Tiles left on the ramp and paddle.
• unplacedPoints: number — Their bonus.
• overflow: number — Points beyond a points goal.
• overflowPoints: number — Their bonus.
• warpBonus: number — Warp bonus (from a warp choice or a pattern warp).
• total: number — Everything added.

StackThrowBack

interface StackThrowBack

Throwing the top tile back up the ramp.

• steps: number — How many ramp steps it flies back up.
• time: number — Seconds in the air.

StackTiming

interface StackTiming

Pace and animation-relevant timings, in seconds unless noted.

• clear: number — How long a line flashes before it clears.
• pauseRampOnClear: boolean — Stop the conveyor while lines clear (Klax: tiles pause about a second when a Klax is made).
• binFall: number — Rows per second a tile falls inside the bin (from the paddle, or after a clear).
• intro: number — The wave banner before play.
• complete: number — The wave-complete bonus screen.
• missFall: number — How long a missed tile takes to fall into the pit (presentation; it is already counted).

StackWarp

interface StackWarp

Warp screens: at the start and after every everyth wave, choose where to go next. The drop meter resets there.

• every: number — A warp screen follows every wave that is a multiple of this (Klax: 5).
• choices: ReadonlyArray<StackWarpChoice> — The choices offered (Klax: next wave with 3 drops; +5 with 4 drops and 100,000; +10 with 5 drops and 200,000).
• atStart: boolean — Offer the choice before the first wave too (Klax: start at wave 1, 6 or 11).

StackWarpChoice

interface StackWarpChoice

One choice on a warp screen: skip ahead and play with a drop meter of drops; bonus is paid when that wave is completed.

• skip: number — Waves to skip beyond the next one (0 = the next wave, 5 = five further on).
• drops: number — The drop meter size for the waves that follow (misses allowed before the game ends).
• bonus: number — Bonus paid when the chosen wave is completed.

StackWave

interface StackWave

One wave: goal, tile mix and pace. Times are seconds.

• goal: StackGoal — What completes the wave.
• colours: number — How many colours are dealt (indices 0 … colours − 1).
• wild: number — Chance (0–1) that a new tile is wild.
• step: readonly [number, number] — Seconds per ramp step (one end-over-end tumble) at the wave's start and after rampSeconds.
• interval: readonly [number, number] — Seconds between new tiles at the start and after rampSeconds.
• rampSeconds: number — Seconds of play over which step and interval move from the first value to the second.
• maxOnRamp: number — The most tiles on the ramp at once (new tiles wait).
• preload: number — Tiles already tumbling down the ramp when play starts, one spawn interval apart (as many as fit).
• bin?: ReadonlyArray<ReadonlyArray<number>> — A starting bin, per column bottom → top (colour indices). Default empty.
• sequence?: ReadonlyArray<StackSequenceTile> — Authored tiles dealt first, in order.
• afterSequence?: "random" | "stop" | "repeat" — After the sequence: random tiles (default), no more tiles, or the sequence again.

StackWaveSource

type StackWaveSource = ReadonlyArray<StackWave> | { readonly count: number; wave(n: number): StackWave }

A wave table, or a generator for count waves (wave numbers start at 1).

TileTumbleOptions

interface TileTumbleOptions

Options for tileTumblePreset.

• difficulty?: StackDifficultyName — Easy, Normal (default) or Arcade (the full pace).
• seed?: number — Seed. Default 1.
• lanes?: number — Lanes and bin columns. Default 7.
• depth?: number — Bin rows. Default 6.
• paddleCapacity?: number — Paddle capacity. Default 3.
• minLine?: number — The shortest line. Default 4.
• colours?: number — Colours dealt. Default 5.
• wild?: number — Wild-tile chance. Default 1/12.
• drops?: number — Drop meter. Default 5.