Understanding the Engine

Before writing your first line of game code, it helps to understand why the engine is built the way it is and how the key objects fit together. This page is the mental model you need before working through the rest of the tutorial.

The Core Invariant: Only Actions Are Persisted

The 18xx.games engine never saves the game state — the board layout, cash totals, stock prices — to the database. It saves only the sequence of Actions that produced that state. Every time a page loads, the engine replays all actions from scratch to reconstruct the state.

This means:

• There is no migration risk from state format changes.
• A fixture test is just "replay these actions and check the final scores."
• Adding a new game title requires only defining the starting conditions and how each action type changes them.

The trade-off is that load time grows with game length. Caching and the PIN mechanism (locking old games to a JS bundle snapshot) address this.

The Object Map

The Four Runtime Layers

When you implement a game title, you are working in exactly one of these layers per change:

Work at the lowest layer that solves the problem. Constants first, then event hooks, then step overrides, then new Steps. Adding a new Step is significant; most title-specific rules only need a constant or a method override.

g_1830 is the gold standard for L1: 95% of its mechanics live in constants.

L1 — What each constant captures

TRAINS entries:

• Train roster: name:, distance:, price:, num:
• Rust triggers: rusts_on:, obsolete_on:
• Availability gate: available_on: (train only appears after another is bought)
• Purchase discounts: discount: {'2' => 30} hash
• Variants: variants: array (sub-types selectable at buy time; each can have own rusts_on:)
• Revenue multipliers on variants: multiplier: int
• Phase-transition events: events: [{'type' => 'xxx'}] — dispatched to event_xxx!
• Multi-node distance specs: distance: as array of {'nodes'=>[...], 'pay'=>N, 'visit'=>N}

PHASES entries:

• Train limit per phase (scalar or {minor: N, major: N, national: N} hash)
• Available tile colours: tiles:
• Operating rounds per phase: operating_rounds:
• Status flags: string array mapping to STATUS_TEXT
• Phase-trigger events: same events: key as trains

CORPORATIONS / MINORS entries:

• Type field: :minor / :major / :national
• Token stack and costs: tokens:
• Home coordinates + city index: coordinates:, city:
• Float percent: float_percent:

Scalar game constants (selection):

• CAPITALIZATION — :full, :incremental, :none
• SELL_BUY_ORDER, SELL_AFTER, SELL_MOVEMENT, POOL_SHARE_DROP
• MUST_BUY_TRAIN, MUST_SELL_IN_BLOCKS, EBUY_FROM_OTHERS, EBUY_PRES_SWAP
• HOME_TOKEN_TIMING, TILE_RESERVATION_BLOCKS_OTHERS, TRACK_RESTRICTION
• BANK_CASH, STARTING_CASH, CERT_LIMIT, CURRENCY_FORMAT_STR
• GAME_END_CHECK hash of reason → timing
• TILE_LAYS array of lay-slot hashes for default entity type
• STATUS_TEXT, EVENTS_TEXT, MARKET_TEXT, GAME_END_REASONS_TEXT

L2 — Key hook methods

L3 — Common custom Step and Round categories

Game, Round, and Step

A Game (Game::Base) is the top-level container. It holds all objects and knows which Round is active. Each of the 100+ game titles is a subclass with its own constant definitions.

A Round is a turn segment — Stock Round, Operating Round, Auction Round. It holds an ordered list of Steps and an ordered queue of entities (players or corporations) that act in sequence.

A Step is an atomic decision unit. It declares ACTIONS — the action types it handles — and implements process_<type>(action) for each. The Round asks Steps in order: "can you handle this?" The first blocking Step that claims the action type handles it.

The UI reads the union of all active Steps' ACTIONS lists to decide which buttons to enable. If a button is greyed out, no active Step is claiming that action type for the current entity.

How an Action Travels

The same engine code runs on both sides. The browser validates optimistically; the server validates authoritatively. Your game code only needs to be correct once.

How Phases Advance

Buying the first copy of a train advances the game phase. This is the engine's primary mechanism for progressing the development arc:

The on: field in each PHASES entry names the train whose first purchase triggers that phase. A single purchase can advance the phase and fire multiple events simultaneously.

Event Handler Library

Event handlers are dispatched from TRAINS or PHASES events: arrays via @game.send("event_#{type}!"). They must exist in game.rb or base.rb.

Define your own by adding events: [{'type' => 'my_event'}] to a TRAINS or PHASES entry and implementing event_my_event! in game.rb.

Key Terms

Where to Look Things Up

What's Next

Work through the tutorial in order:

1. Development Setup — get Docker running and the test suite green
2. Game Structure — create the four files every title needs
3. Map Configuration — define hexes, location names, and tile supply
4. Corporations & Companies — define the entities players interact with
5. Trains, Phases & Market — configure the economic arc
6. Rounds & Steps — customise the decision sequence

Version: 2026-05-08 — derived from lib/engine/game/base.rb, lib/engine/round/base.rb, lib/engine/step/base.rb, lib/engine/phase.rb.