Ability Types Reference

Company and corporation abilities are defined as hashes in entities.rb files. The engine processes them via lib/engine/ability/ and evaluates their legality through Game::Base#ability_right_time?. This page is an exhaustive reference for ability types, their fields, and the when: vocabulary.

Ability Type Frequency

Frequencies extracted from analysis of 112 entities.rb files (1,111 COMPANIES, 1,241 CORPORATIONS) across the engine.

Ability Structure

Standard ability hash in entities.rb:

{
  type: 'tile_lay',           # required
  owner_type: 'player',       # 'player' | 'corporation'
  when: 'track',              # string or array; see When: Field section
  count: 2,                   # number of uses; omit = unlimited
  hexes: %w[A1 B2],           # hex restriction
  tiles: %w[57 58],           # tile number restriction
  free: true,                 # waives tile cost
  closed_when_used_up: true,  # close company when count reaches 0
  reachable: true,            # must be reachable from home token
  consume_tile_lay: true,     # consumes one of the corporation's normal lay slots
  terrain: 'mountain',        # (on tile_discount) terrain type
  discount: 20,               # (on tile_discount / train_discount) amount
  trains: %w[2+2 3+3],        # (on train_discount) train types
  corporations: %w[GWR LNWR], # (on exchange / token / assign_corporation)
  from: 'par',                # (on exchange) source
  description: 'text',        # (on base / description / generic)
  price: 0,                   # (on token) placement cost
  corporation: 'GWR',         # (on token / close) specific corporation
  on_phase: 'Phase 4',        # (on close / revenue_change) phase trigger
  revenue: 20,                # (on revenue_change) new value
  amount: 30,                 # (on hex_bonus) bonus amount
}

count: enforcement

ability.use! decrements @count [lib/engine/ability/base.rb:1]. When count reaches zero and @remove_when_used_up is true (the default), the ability is removed from the entity. TileLay#use! tracks lay_count and upgrade_count separately.

consume_tile_lay: on tile_lay abilities

• consume_tile_lay: true — routes through lay_tile_action; increments @round.num_laid_track. The ability consumes one of the corporation's normal lay slots.
• Without consume_tile_lay — routes through lay_tile directly. The ability is extra on top of the normal budget.

blocks_hexes vs blocks_hexes_consent

• blocks_hexes — unconditional; blocked until the company is purchased or closed.
• blocks_hexes_consent — blocking released when the owning player consents. Used for concession cards (released when the concession is transferred or the major is parred). Reference: 1822 family.

when: Field Complete Vocabulary

649 occurrences across 75 games; 27 distinct values. Source: Game::Base#ability_right_time? [lib/engine/game/base.rb].

OR Step-Scoped

Active only during the named Step class:

OR Turn-Scoped

Active at any point during the owning entity's OR turn:

SR Turn-Scoped

Event-Triggered (on close abilities only)

Meta / Any-Round

Always-valid values (no step prerequisite): any, owning_corp_or_turn, owning_player_or_turn, owning_player_track, owning_player_token, owning_player_sr_turn, stock_round, or_between_turns, or_start.

exchange Ability — from: Values

Concessions use from: 'par' per the 1822/1866 concession pattern.

description Ability

Used to associate a minor with a major and to hold the human-readable rulebook ability text:

# In CORPORATIONS for a minor:
abilities: [{ type: 'description', description: 'Associated minor for GWR' }]

The par_via_exchange field handles the mechanical association; the description ability is UI display only.

18OE Ability Mapping

Minor special abilities

Private special abilities

Implementation notes — BBBT, BBE, and SML

Barclay, Bevan, Barclay & Tritton (BBBT)

Option 3 only implemented for alpha. During the player's own SR turn, can_use_bbbt_option3? gates a choose action in BuySellParShares. Choice keys are prefixed bbbt_<corp_id> to avoid collisions with the SML choose keys. bbbt_protect!(corp, player) stores @bbbt_protected_corp and logs the protection. sell_shares_and_change_price is overridden in game.rb to pass movement: :none when the protected corp is being sold, suppressing all DOWN movement for that sale. next_round! calls finish_bbbt_sr! when leaving an SR — this clears @bbbt_protected_corp and closes BBBT. Options 1 (re-set par) and 2 (custodianship) are deferred to beta.

Brandt & Brandau, Engineers (BBE)

owner_type: 'corporation' on the tile_lay ability means the ability only activates after a corporation has purchased BBE from the player. Once corp-owned, during the Track step on a terrain hex, upgrade_cost returns 0 (terrain free). After the lay, the Track step calls ability.use! and mark_bbe_hex!(hex, corp), storing the hex in @bbe_hexes. check_bbe_exclusion! (called from check_route_token) raises GameError if a non-owning corp routes through a marked hex. The removal mechanic (opponent pays terrain + tile point to remove token) is not yet implemented.

Swift Metropolitan Line (SML)

Implemented entirely in game.rb via can_claim_sml? / claim_sml_train! and an SR choose action on BuySellParShares. The rusted 2+2 is assigned with buyable = false and tracked in @sml_trains. num_corp_trains and must_buy_train? both exclude SML trains from their counts.

What's next

• How abilities are evaluated at runtime: Game Engine
• OR step order in which ability when: values become active: Round/Step System
• Tile lay mechanics: Tile Reference

Version: 2026-05-19 — derived from lib/engine/ability/base.rb, lib/engine/ability/tile_lay.rb, lib/engine/game/base.rb.