plai_testr 0.1.1

data/templates/examples/gin_rummy/lib/gin_rummy/bot.rb

@@ -0,0 +1,34 @@
+module GinRummy
+  module Bot
+    def bot_choice(player, moves, pick: nil)
+      params = moves.map { |m| m[:action].values.first }
+      step == 'draw' ? draw_policy(params) : discard_policy(player, params)
+    end
+
+    private
+
+    def draw_policy(params)
+      params[1][:deadwood] < params[0][:deadwood] ? choose(1, 'take_useful_discard') : choose(0, 'draw_stock')
+    end
+
+    def discard_policy(player, params)
+      options = params.each_index
+      gin     = options.find { |i| params[i][:knock] && params[i][:deadwood].zero? }
+      knock   = options.select { |i| params[i][:knock] }.min_by { |i| params[i][:deadwood] }
+      shed    = options.reject { |i| params[i][:knock] }.min_by do |i|
+        [params[i][:deadwood], -Melds.value(hand(player).find { |c| c['uid'] == params[i][:value] })]
+      end
+
+      if gin then choose(gin, 'gin', obvious: true)
+      elsif knock && knock_now?(player, params[knock][:deadwood]) then choose(knock, 'knock')
+      else choose(shed, 'shed_deadwood')
+      end
+    end
+
+    def knock_now?(player, deadwood)
+      deadwood <= bot_strategy_for(player)['knock_at'] || stock.length <= LATE_STOCK
+    end
+
+    def choose(index, rule, obvious: false) = { 'choice' => index + 1, 'rule' => rule, 'obvious' => obvious }
+  end
+end

data/templates/examples/gin_rummy/lib/gin_rummy/game.rb

@@ -0,0 +1,8 @@
+module GinRummy
+  SUITS      = %w[clubs diamonds spades hearts].freeze
+  HAND_SIZE  = 10
+  DEAD_STOCK = 2
+  MAX_HANDS  = 50
+  MAX_TURNS  = 120
+  LATE_STOCK = 10
+end

data/templates/examples/gin_rummy/lib/gin_rummy/melds.rb

@@ -0,0 +1,51 @@
+module GinRummy
+  module Melds
+    Arrangement = Data.define(:melds, :deadwood) do
+      def points = Melds.points(deadwood)
+    end
+
+    def self.value(card)   = [card['rank'], 10].min
+    def self.points(cards) = cards.sum { |c| value(c) }
+
+    def self.best(cards) = search(cards, candidates(cards))
+
+    def self.lay_off(cards, melds)
+      melds = melds.map(&:dup)
+      cards = cards.dup
+
+      while (card = cards.find { |c| melds.any? { |m| fits?(c, m) } })
+        melds.find { |m| fits?(card, m) } << card
+        cards.delete(card)
+      end
+      cards
+    end
+
+    def self.candidates(cards)
+      sets = cards.group_by { |c| c['rank'] }.values.select { |g| g.length >= 3 }
+                  .flat_map { |g| g.length == 4 ? [g, *g.combination(3)] : [g] }
+      runs = cards.group_by { |c| c['suit'] }.values.flat_map do |suited|
+        suited.sort_by { |c| c['rank'] }.slice_when { |a, b| b['rank'] != a['rank'] + 1 }.flat_map do |streak|
+          (3..streak.length).flat_map { |size| streak.each_cons(size).to_a }
+        end
+      end
+      sets + runs
+    end
+
+    def self.search(cards, candidates)
+      candidates.each_with_index.reduce(Arrangement.new(melds: [], deadwood: cards)) do |best, (meld, i)|
+        next best unless (meld - cards).empty?
+
+        rest = search(cards - meld, candidates.drop(i + 1))
+        rest.points < best.points ? Arrangement.new(melds: [meld, *rest.melds], deadwood: rest.deadwood) : best
+      end
+    end
+
+    def self.fits?(card, meld)
+      ranks = meld.map { |c| c['rank'] }
+
+      if ranks.uniq.one? then card['rank'] == ranks.first && meld.length < 4
+      else card['suit'] == meld.first['suit'] && [ranks.min - 1, ranks.max + 1].include?(card['rank'])
+      end
+    end
+  end
+end

data/templates/examples/gin_rummy/lib/gin_rummy/session/runner.rb

@@ -0,0 +1,197 @@
+module GinRummy
+  module Session
+    class Runner < PlaiTestr::Session::Runner
+      include Bot
+
+      RULES_PATH = File.expand_path('../../../data/rules.md', __dir__)
+      RECENT_LOG = 10
+
+      DEBRIEF_QUESTIONS = [
+        'Which decision in this game mattered most, and why?',
+        'When did you choose to knock (or not), and was it the right call?',
+        'Which choices felt automatic (the choice did not matter)?'
+      ].freeze
+
+      def setup
+        data.merge!('hand' => 0, 'log' => [])
+        deal(players.last)
+        out.puts "  Setup (seed #{@seed}): first to #{points_to_win} points; #{players.map { |p| display_name(p) }.join(' vs ')}."
+      end
+
+      def next_player = @game_state.active
+
+      def legal_moves(player)
+        case step
+        when 'draw'    then draw_moves(player)
+        when 'discard' then discard_moves(player)
+        end
+      end
+
+      def apply_action_effects(player, action)
+        case action
+        in { draw: { source: } }              then draw(player, source)
+        in { discard: { value:, knock: true } } then discard(player, value, knock: true)
+        in { discard: { value: } }            then discard(player, value, knock: false)
+        end
+      end
+
+      def rules_text_for(_player) = @rules_text ||= File.read(RULES_PATH)
+
+      def view_text_for(player)
+        best = Melds.best(hand(player))
+
+        [
+          "Hand #{data['hand']}. Scores (first to #{points_to_win}): #{players.map { |p| "#{whose(p, player)} #{pstate(p).score}" }.join(', ')}",
+          "Your hand: #{list(hand(player))}",
+          "Your best melds: #{melds_text(best)}; deadwood #{best.points}",
+          "Discard pile: #{top ? "#{top['name']} on top (#{discard_pile.length} cards)" : 'empty'}. Stock: #{stock.length} cards. #{opponent(player)} holds #{hand(opponent(player)).length} cards.",
+          '',
+          instruction
+        ].join("\n")
+      end
+
+      def turn_phase(_player) = "hand #{data['hand']} · #{step}"
+
+      def recent_events_for(player) = event_log.recent_for(player, RECENT_LOG)
+
+      def debrief_questions(_player) = DEBRIEF_QUESTIONS
+
+      private
+
+      def draw_moves(player)
+        now  = Melds.best(hand(player)).points
+        with = hand(player).map { |c| Melds.best(hand(player) + [top] - [c]).points }.min
+
+        [
+          option('Draw the top card of the stock (face-down)', public: 'drew from the stock', draw: { source: 'stock', deadwood: now }),
+          option("Take the #{top['name']} from the discard pile (best deadwood after your discard: #{with}; now: #{now})",
+                 public: "took the #{top['name']} from the discard pile", draw: { source: 'discard', deadwood: with })
+        ]
+      end
+
+      def discard_moves(player)
+        hand(player).reject { |c| c['uid'] == data['taken'] }.flat_map do |card|
+          deadwood = Melds.best(hand(player) - [card]).points
+          params   = { value: card['uid'], deadwood: deadwood }
+
+          [
+            option("Discard #{card['name']} (deadwood after: #{deadwood})", public: "discarded #{card['name']}", discard: params),
+            (knock_option(card, params) if deadwood <= knock_limit)
+          ].compact
+        end
+      end
+
+      def knock_option(card, params)
+        gin = params[:deadwood].zero?
+        option(gin ? "Discard #{card['name']} and go gin" : "Discard #{card['name']} and knock with #{params[:deadwood]} deadwood",
+               public: "discarded #{card['name']} and #{gin ? 'went gin' : 'knocked'}", discard: params.merge(knock: true))
+      end
+
+      def deal(dealer)
+        deck = PlaiTestr::Deck.build(@rules).shuffle(random: @rng)
+
+        players.each { |p| hand(p).replace(sorted(deck.shift(HAND_SIZE))) }
+        data.merge!('hand' => data['hand'] + 1, 'dealer' => dealer, 'discard' => [deck.shift], 'stock' => deck,
+                    'step' => 'draw', 'active' => opponent(dealer), 'taken' => nil, 'turns' => 0)
+        log("Hand #{data['hand']}: #{dealer} dealt; the upcard is #{top['name']}")
+      end
+
+      def draw(player, source)
+        card = source == 'stock' ? stock.shift : discard_pile.pop
+
+        hand(player).replace(sorted(hand(player) + [card]))
+        data.merge!('step' => 'discard', 'taken' => (card['uid'] if source == 'discard'))
+
+        if source == 'stock'
+          log("#{player} drew from the stock")
+          log("You drew the #{card['name']}", to: player)
+        else
+          log("#{player} took the #{card['name']} from the discard pile")
+        end
+      end
+
+      def discard(player, uid, knock:)
+        card = take(player, uid)
+        discard_pile << card
+        log("#{player} discarded #{card['name']}")
+
+        data['turns'] += 1
+
+        if knock then score_hand(player)
+        elsif stock.length <= DEAD_STOCK then dead_hand('draw', "The stock is down to #{DEAD_STOCK} cards: hand #{data['hand']} is a draw")
+        elsif data['turns'] >= MAX_TURNS then dead_hand('turn_cap', "Hand #{data['hand']} is a draw")
+        else data.merge!('step' => 'draw', 'active' => opponent(player), 'taken' => nil)
+        end
+      end
+
+      def score_hand(knocker)
+        defender = opponent(knocker)
+        knock    = Melds.best(hand(knocker))
+        defense  = Melds.best(hand(defender))
+        gin      = knock.deadwood.empty?
+        left     = gin ? defense.deadwood : Melds.lay_off(defense.deadwood, knock.melds)
+        margin   = Melds.points(left) - knock.points
+
+        winner, points, result =
+          if gin then [knocker, margin + @rules.fetch('gin_bonus'), 'gin']
+          elsif margin.positive? then [knocker, margin, 'knock']
+          else [defender, @rules.fetch('undercut_bonus') - margin, 'undercut']
+          end
+
+        pstate(winner).apply_changes('score' => pstate(winner).score + points)
+        data['results'] = data.fetch('results', {}).merge(result => data.dig('results', result).to_i + 1)
+        log("#{knocker} #{gin ? 'went gin' : "knocked with #{knock.points}"} (#{melds_text(knock)}); " \
+            "#{defender} had #{Melds.points(left)} deadwood (#{melds_text(defense)}#{", laid off #{list(defense.deadwood - left)}" unless gin || left == defense.deadwood}). " \
+            "#{winner} scores #{points}#{' for the undercut' if result == 'undercut'}.")
+
+        if pstate(winner).score >= points_to_win then end_game(winner, "reached_#{points_to_win}")
+        elsif data['hand'] >= MAX_HANDS then end_game(players.max_by { |p| pstate(p).score }, 'hand_limit')
+        else deal(winner)
+        end
+      end
+
+      def dead_hand(result, text)
+        log(text)
+        data['results'] = data.fetch('results', {}).merge(result => data.dig('results', result).to_i + 1)
+        data['hand'] >= MAX_HANDS ? end_game(players.max_by { |p| pstate(p).score }, 'hand_limit') : deal(data['dealer'])
+      end
+
+      def end_game(winner, reason)
+        @game_state.apply_changes('status' => { 'game_over' => true, 'winner' => winner, 'end_reason' => reason })
+      end
+
+      def instruction
+        case step
+        when 'draw' then 'Draw the top card of the stock, or take the top card of the discard pile.'
+        when 'discard'
+          "Discard one card. If your deadwood after discarding is #{knock_limit} or less you may knock; with 0 deadwood you go gin." \
+            "#{" You cannot discard the #{hand(@game_state.active).find { |c| c['uid'] == data['taken'] }['name']} you just took." if data['taken']}"
+        end
+      end
+
+      def melds_text(arrangement)
+        melds = arrangement.melds.map { |m| "[#{list(m)}]" }.join(' ')
+        "#{melds.empty? ? 'no melds' : melds}#{"; unmatched #{list(arrangement.deadwood)}" if arrangement.deadwood.any?}"
+      end
+
+      def take(player, uid) = hand(player).delete_at(hand(player).index { |c| c['uid'] == uid })
+
+      def sorted(cards) = cards.sort_by { |c| [SUITS.index(c['suit']), c['rank']] }
+
+      def opponent(player) = (players - [player]).first
+
+      def whose(player, viewer) = player == viewer ? 'You' : player
+
+      def list(cards)      = cards.map { |c| c['name'] }.join(', ')
+      def top              = discard_pile.last
+      def points_to_win    = @rules.fetch('points_to_win')
+      def knock_limit      = @rules.fetch('knock_limit')
+      def step             = @game_state.step
+      def stock            = @game_state.stock
+      def discard_pile     = @game_state.discard_pile
+      def players          = @game_state.players
+      def pstate(player)   = @game_state.player_state(player)
+      def hand(player)     = pstate(player).hand
+    end
+  end
+end

data/templates/examples/gin_rummy/lib/gin_rummy/state/game_state.rb

@@ -0,0 +1,19 @@
+module GinRummy
+  module State
+    class GameState < PlaiTestr::State::GameState
+      def step         = @data['step']
+      def active       = @data['active']
+      def stock        = @data['stock'] ||= []
+      def discard_pile = @data['discard'] ||= []
+
+      private
+
+      def data_for(observer)
+        @data.except('stock', 'log').merge(
+          'stock_size' => stock.length,
+          'log'        => PlaiTestr::EventLog.new(@data.fetch('log', [])).visible_to(observer)
+        )
+      end
+    end
+  end
+end

data/templates/examples/gin_rummy/lib/gin_rummy.rb

@@ -0,0 +1,9 @@
+require_relative 'gin_rummy/game'
+require_relative 'gin_rummy/melds'
+require_relative 'gin_rummy/state/game_state'
+require_relative 'gin_rummy/bot'
+require_relative 'gin_rummy/session/runner'
+
+PlaiTestr.register('gin_rummy',
+                   runner_class:     GinRummy::Session::Runner,
+                   game_state_class: GinRummy::State::GameState)

data/templates/examples/gin_rummy/spec/melds_spec.rb

@@ -0,0 +1,26 @@
+require 'spec_helper'
+
+RSpec.describe GinRummy::Melds do
+  let(:deck) { PlaiTestr::Deck.build(PlaiTestr.load('gin_rummy').rules) }
+
+  def cards(*names) = names.map { |name| deck.find { |c| c['name'] == name } }
+  def names(cards)  = cards.map { |c| c['name'] }
+
+  it 'finds the arrangement with the least deadwood' do
+    best = described_class.best(cards('7♣', '7♦', '7♥', '8♥', '9♥', 'K♠', 'A♣'))
+
+    expect(best.melds.map { |m| names(m) }).to eq([%w[7♥ 8♥ 9♥]])
+    expect(best.points).to eq(25)
+  end
+
+  it 'plays aces low only' do
+    expect(described_class.best(cards('A♠', '2♠', '3♠')).points).to eq(0)
+    expect(described_class.best(cards('Q♠', 'K♠', 'A♠')).points).to eq(21)
+  end
+
+  it 'lays off deadwood onto runs and sets' do
+    melds = [cards('4♠', '5♠', '6♠'), cards('9♣', '9♦', '9♥')]
+
+    expect(names(described_class.lay_off(cards('3♠', '7♠', '9♠', 'K♦'), melds))).to eq(['K♦'])
+  end
+end

data/templates/examples/gin_rummy/spec/session/runner_spec.rb

@@ -0,0 +1,105 @@
+require 'spec_helper'
+
+RSpec.describe GinRummy::Session::Runner do
+  let(:game)   { PlaiTestr.load('gin_rummy') }
+  let(:runner) { runner_with(nil) }
+  let(:state)  { runner.game_state }
+  let(:deck)   { PlaiTestr::Deck.build(game.rules) }
+
+  def runner_with(personas, seed: 1)
+    described_class.new(game: game, players: game.players, seed: seed, personas: personas, mode: 'bot', persist: false, out: StringIO.new)
+  end
+
+  def cards(*names) = names.map { |name| deck.find { |c| c['name'] == name } }
+
+  def give(player, *names) = state.player_state(player).hand.replace(cards(*names))
+
+  def labels(player) = runner.legal_moves(player).map { |m| m[:label] }
+
+  before { runner.setup }
+
+  it 'deals 10 cards each and turns up one card; the non-dealer starts' do
+    expect(game.players.map { |p| state.player_state(p).hand.length }).to eq([10, 10])
+    expect(state.discard_pile.length).to eq(1)
+    expect(state.stock.length).to eq(31)
+    expect(state.active).to eq('Player 1')
+  end
+
+  it 'does not let a player discard the card they just took from the discard pile' do
+    taken = state.discard_pile.last['name']
+    runner.apply_action_effects('Player 1', { draw: { source: 'discard' } })
+
+    expect(labels('Player 1').grep(/#{taken}/)).to be_empty
+  end
+
+  it 'offers a knock only when the deadwood after discarding is 10 or less' do
+    give('Player 1', 'A♣', '2♣', '3♣', '7♦', '7♥', '7♠', 'J♠', 'Q♠', 'K♠', '4♦', '9♥')
+    state.data['step'] = 'discard'
+
+    expect(labels('Player 1')).to include('Discard 9♥ and knock with 4 deadwood')
+    expect(labels('Player 1').grep(/Discard A♣ and knock/)).to be_empty
+  end
+
+  it 'shows what taking the top discard would do to the deadwood' do
+    expect(labels('Player 1').last).to match(/\ATake the .+ from the discard pile \(best deadwood after your discard: \d+; now: \d+\)\z/)
+  end
+
+  it 'declares a hand that runs too long a draw and deals the next' do
+    state.data.merge!('turns' => GinRummy::MAX_TURNS - 1, 'step' => 'discard')
+    runner.apply_action_effects('Player 1', { discard: { value: state.player_state('Player 1').hand.first['uid'] } })
+
+    expect(state.data['hand']).to eq(2)
+    expect(state.data.dig('results', 'turn_cap')).to eq(1)
+  end
+
+  it 'scores an undercut to the defender' do
+    give('Player 1', 'A♣', '2♣', '3♣', '7♦', '7♥', '7♠', 'J♠', 'Q♠', 'K♠', '5♦')
+    give('Player 2', '4♣', '5♣', '6♣', '8♦', '8♥', '8♠', '9♦', '10♦', 'J♦', '2♥')
+    runner.send(:score_hand, 'Player 1')
+
+    expect(state.scores).to eq('Player 1' => 0, 'Player 2' => 28)
+  end
+
+  describe 'personas' do
+    it 'gives each player a different persona when none are requested' do
+      expect(state.data['personas'].values).to contain_exactly('quick_knocker', 'gin_hunter')
+    end
+
+    it 'refuses an unknown persona' do
+      expect { runner_with(%w[gambler *]) }.to raise_error(PlaiTestr::PersonaError, /Unknown persona "gambler"/)
+    end
+
+    def bot_rule(persona)
+      state.data['personas']['Player 1'] = persona
+      runner.bot_choice('Player 1', runner.legal_moves('Player 1'))['rule']
+    end
+
+    it 'has the gin hunter hold a knock that the quick knocker takes' do
+      give('Player 1', 'A♣', '2♣', '3♣', '7♦', '7♥', '7♠', 'J♠', 'Q♠', 'K♠', '4♦', '9♥')
+      state.data['step'] = 'discard'
+
+      expect(bot_rule('quick_knocker')).to eq('knock')
+      expect(bot_rule('gin_hunter')).to eq('shed_deadwood')
+    end
+  end
+
+  it 'builds every prompt a model player would see' do
+    (1..3).each do |seed|
+      session = runner_with(nil, seed: seed)
+      session.setup
+      until session.game_over?
+        player = session.next_player
+        %i[rules_text_for view_text_for recent_events_for persona_for turn_phase].each { |hook| session.public_send(hook, player) }
+        session.play_turn
+      end
+      game.players.each { |p| session.debrief_view_for(p) }
+    end
+  end
+
+  it 'plays whole games with its bot rules' do
+    results = PlaiTestr::Botrun.new(game: game, players: game.players, seeds: (1..10).to_a, personas: ['all']).run
+
+    expect(results.map { |r| r['error'] }.compact).to be_empty
+    expect(results.map { |r| r['winner'] }).to all(start_with('Player'))
+  end
+end

data/templates/examples/hearts/data/bots.yml

@@ -0,0 +1,22 @@
+# bot_strategy: parameters your bot (lib/<game>/bot.rb) reads (never shown to the model).
+#   Read them in bot_choice with bot_strategy_for(player).
+#   knock_at: 10
+#   lead_low: true
+#
+# bots: per-persona overrides, keyed by the persona's key in personas.yml.
+#   A key with no matching persona is an error.
+#   gin_hunter:
+#     <<: *bot_defaults
+#     knock_at: 3
+
+bot_strategy: &bot_defaults
+  pass_dangerous: true
+  win_clean_tricks: true
+
+bots:
+  safe_player:
+    <<: *bot_defaults
+    win_clean_tricks: false
+  moon_shooter:
+    <<: *bot_defaults
+    pass_dangerous: false

data/templates/examples/hearts/data/personas.yml

@@ -0,0 +1,27 @@
+# basic_strategy: shared strategy, injected into each persona with <<: *basics.
+#   complete_tricks: Points come only from tricks you win; count them before you lead.
+#   avoid_penalties: Discard high cards early, while they're hard to punish.
+#
+# personas: play styles, picked with --personas a,b (or at random). The key is
+#   the persona's name; every field under it is shown to the model. To override
+#   a basic_strategy item, reuse its key exactly; a new key adds an item.
+#   moon_shooter:
+#     <<: *basics
+#     avoid_penalties: Keep hearts and the Q♠ if you can take every trick.
+#   safe_player:
+#     <<: *basics
+#     goal: Finish every hand with as few points as you can.
+
+basic_strategy: &basics
+  pass_dangerous: Pass away the Q♠, high spades (A♠, K♠) and high hearts unless you have many low spades to protect them.
+  duck: Play just under the winning card to avoid taking tricks that carry points.
+  dump_when_void: When you cannot follow suit, drop the Q♠ or high hearts on someone else.
+
+personas:
+  safe_player:
+    <<: *basics
+    goal: Take as few points as you can in every hand. Never win a trick you could lose.
+  moon_shooter:
+    <<: *basics
+    goal: Watch for a hand strong enough to take every heart and the Q♠ (26 points to everyone else). Go for it when you can; otherwise play safe.
+    pass_dangerous: Keep high hearts and the Q♠ when your hand is strong enough to take every trick; pass low cards instead.

data/templates/examples/hearts/data/rules.json

@@ -0,0 +1,73 @@
+{
+  "game": {
+    "name": "Hearts",
+    "version": "1.0.0",
+    "description": "A 4-player trick-taking card game. Avoid taking hearts (1 point each) and the Queen of Spades (13 points). When a player reaches 100 points, the player with the fewest points wins.",
+    "player_count": { "min": 4, "max": 4, "default": 4 }
+  },
+
+  "points_to_end": 100,
+
+  "components": [
+    {
+      "name": "Deck",
+      "type": "card_deck",
+      "count": 52,
+      "description": "Standard 52-card deck. Aces are high (rank 14).",
+      "values": [
+        { "name": "2♣", "rank": 2, "suit": "clubs" },
+        { "name": "3♣", "rank": 3, "suit": "clubs" },
+        { "name": "4♣", "rank": 4, "suit": "clubs" },
+        { "name": "5♣", "rank": 5, "suit": "clubs" },
+        { "name": "6♣", "rank": 6, "suit": "clubs" },
+        { "name": "7♣", "rank": 7, "suit": "clubs" },
+        { "name": "8♣", "rank": 8, "suit": "clubs" },
+        { "name": "9♣", "rank": 9, "suit": "clubs" },
+        { "name": "10♣", "rank": 10, "suit": "clubs" },
+        { "name": "J♣", "rank": 11, "suit": "clubs" },
+        { "name": "Q♣", "rank": 12, "suit": "clubs" },
+        { "name": "K♣", "rank": 13, "suit": "clubs" },
+        { "name": "A♣", "rank": 14, "suit": "clubs" },
+        { "name": "2♦", "rank": 2, "suit": "diamonds" },
+        { "name": "3♦", "rank": 3, "suit": "diamonds" },
+        { "name": "4♦", "rank": 4, "suit": "diamonds" },
+        { "name": "5♦", "rank": 5, "suit": "diamonds" },
+        { "name": "6♦", "rank": 6, "suit": "diamonds" },
+        { "name": "7♦", "rank": 7, "suit": "diamonds" },
+        { "name": "8♦", "rank": 8, "suit": "diamonds" },
+        { "name": "9♦", "rank": 9, "suit": "diamonds" },
+        { "name": "10♦", "rank": 10, "suit": "diamonds" },
+        { "name": "J♦", "rank": 11, "suit": "diamonds" },
+        { "name": "Q♦", "rank": 12, "suit": "diamonds" },
+        { "name": "K♦", "rank": 13, "suit": "diamonds" },
+        { "name": "A♦", "rank": 14, "suit": "diamonds" },
+        { "name": "2♠", "rank": 2, "suit": "spades" },
+        { "name": "3♠", "rank": 3, "suit": "spades" },
+        { "name": "4♠", "rank": 4, "suit": "spades" },
+        { "name": "5♠", "rank": 5, "suit": "spades" },
+        { "name": "6♠", "rank": 6, "suit": "spades" },
+        { "name": "7♠", "rank": 7, "suit": "spades" },
+        { "name": "8♠", "rank": 8, "suit": "spades" },
+        { "name": "9♠", "rank": 9, "suit": "spades" },
+        { "name": "10♠", "rank": 10, "suit": "spades" },
+        { "name": "J♠", "rank": 11, "suit": "spades" },
+        { "name": "Q♠", "rank": 12, "suit": "spades" },
+        { "name": "K♠", "rank": 13, "suit": "spades" },
+        { "name": "A♠", "rank": 14, "suit": "spades" },
+        { "name": "2♥", "rank": 2, "suit": "hearts" },
+        { "name": "3♥", "rank": 3, "suit": "hearts" },
+        { "name": "4♥", "rank": 4, "suit": "hearts" },
+        { "name": "5♥", "rank": 5, "suit": "hearts" },
+        { "name": "6♥", "rank": 6, "suit": "hearts" },
+        { "name": "7♥", "rank": 7, "suit": "hearts" },
+        { "name": "8♥", "rank": 8, "suit": "hearts" },
+        { "name": "9♥", "rank": 9, "suit": "hearts" },
+        { "name": "10♥", "rank": 10, "suit": "hearts" },
+        { "name": "J♥", "rank": 11, "suit": "hearts" },
+        { "name": "Q♥", "rank": 12, "suit": "hearts" },
+        { "name": "K♥", "rank": 13, "suit": "hearts" },
+        { "name": "A♥", "rank": 14, "suit": "hearts" }
+      ]
+    }
+  ]
+}

data/templates/examples/hearts/data/rules.md

@@ -0,0 +1,30 @@
+# Hearts
+
+v1.0.0
+
+A trick-taking game for 4 players. Points are bad: the player with the **fewest** points when the game ends wins.
+
+## Cards
+
+A standard 52-card deck. Aces are high. Each heart (♥) is worth 1 point; the Queen of Spades (Q♠) is worth 13. All other cards are worth nothing.
+
+## Each hand
+
+1. **Deal.** Every player gets 13 cards.
+2. **Pass.** Each player chooses 3 cards to pass, without seeing what they receive. The direction rotates every hand: left, right, across, then no passing (hold), and repeats.
+3. **Tricks.** The player holding the 2♣ leads it to start the first trick. Going clockwise, each player plays one card. You must follow the suit that was led if you can; if you cannot, you may play any card. The highest card of the suit led wins the trick, and its winner leads the next trick.
+4. **Restrictions.**
+   - On the first trick, you may not play a heart or the Q♠ unless you have nothing else.
+   - You may not lead a heart until hearts are broken (a heart has been played on an earlier trick), unless your hand has only hearts.
+5. **Scoring.** After all 13 tricks, each player adds the points in the tricks they took.
+   - **Shooting the moon:** a player who takes all 13 hearts and the Q♠ scores 0, and every other player scores 26.
+
+## End of the game
+
+When any player has 100 or more points at the end of a hand, the game ends. The player with the fewest points wins; tied low scores share the win.
+
+## Strategy notes
+
+- Pass away the Q♠, high spades (A♠, K♠) and high hearts unless you have many low spades to protect them.
+- Play just under the winning card to avoid taking tricks that carry points.
+- When you cannot follow suit, it is a chance to drop the Q♠ or high hearts on someone else.