plai_testr 0.1.1

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

@@ -0,0 +1,53 @@
+module Hearts
+  module Bot
+    def bot_choice(player, moves, pick: nil)
+      cards = moves.map { |m| hand(player).find { |c| c['uid'] == m[:action].values.first[:value] } }
+      pick ? pass_policy(player, cards, pick.first) : play_policy(player, cards)
+    end
+
+    private
+
+    def pass_policy(player, cards, count)
+      ranked = cards.each_index.sort_by { |i| -danger(cards[i]) }
+      return { 'choices' => ranked.first(count).map { |i| i + 1 }, 'rule' => 'pass_dangerous' } if bot_strategy_for(player)['pass_dangerous']
+
+      { 'choices' => ranked.last(count).map { |i| i + 1 }, 'rule' => 'keep_dangerous' }
+    end
+
+    def play_policy(player, cards)
+      if trick.empty? then choose(cards, cards.min_by { |c| [Hearts.points(c), c['rank']] }, 'lead_low')
+      elsif cards.first['suit'] == led_suit then follow_policy(player, cards)
+      else dump_policy(cards)
+      end
+    end
+
+    def follow_policy(player, cards)
+      high  = trick.select { |t| t['card']['suit'] == led_suit }.map { |t| t['card']['rank'] }.max
+      under = cards.select { |c| c['rank'] < high }
+
+      if under.any? then choose(cards, under.max_by { |c| c['rank'] }, 'duck')
+      elsif last_to_play? && points_in(trick.map { |t| t['card'] }).zero? && bot_strategy_for(player)['win_clean_tricks']
+        choose(cards, cards.reject { |c| c['name'] == QUEEN }.max_by { |c| c['rank'] } || cards.first, 'win_clean_trick')
+      else choose(cards, cards.min_by { |c| c['rank'] }, 'play_low')
+      end
+    end
+
+    def dump_policy(cards)
+      worst = cards.max_by { |c| danger(c) }
+      queen = worst['name'] == QUEEN
+      choose(cards, worst, queen ? 'dump_queen' : 'dump_high', obvious: queen)
+    end
+
+    def danger(card)
+      if card['name'] == QUEEN then 100
+      elsif card['suit'] == 'spades' && card['rank'] > 12 then 50 + card['rank']
+      elsif card['suit'] == 'hearts' then 20 + card['rank']
+      else card['rank']
+      end
+    end
+
+    def last_to_play? = trick.length == players.length - 1
+
+    def choose(cards, card, rule, obvious: false) = { 'choice' => cards.index(card) + 1, 'rule' => rule, 'obvious' => obvious }
+  end
+end

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

@@ -0,0 +1,16 @@
+module Hearts
+  SUITS      = %w[clubs diamonds spades hearts].freeze
+  HAND_SIZE  = 13
+  PASS_COUNT = 3
+  PASSES     = %w[left right across hold].freeze
+  SEAT_SHIFT = { 'left' => 1, 'right' => -1, 'across' => 2 }.freeze
+  QUEEN      = 'Q♠'
+  OPENER     = '2♣'
+  MOON       = 26
+
+  def self.points(card)
+    return 13 if card['name'] == QUEEN
+
+    card['suit'] == 'hearts' ? 1 : 0
+  end
+end

data/templates/examples/hearts/lib/hearts/reporter/botrun_report.rb

@@ -0,0 +1,29 @@
+module Hearts
+  module Reporter
+    class BotrunReport < PlaiTestr::Reporter::BotrunReport
+      private
+
+      def extra_sections
+        games = @played.select { |r| r['stats'] }
+        return [] if games.empty?
+
+        [hands(games), penalties(games)]
+      end
+
+      def hands(games)
+        counts = games.map { |r| r.dig('stats', 'hands') }.sort
+        table('## Hands per game', %w[Mean Median 90th Max], ["| #{counts.sum.fdiv(counts.length).round(1)} | #{percentile(counts, 50)} | #{percentile(counts, 90)} | #{counts.max} |"])
+      end
+
+      def penalties(games)
+        rows = games.first['names'].keys.map do |seat|
+          "| #{seat} | #{average(games, 'hearts', seat).round(1)} | #{average(games, 'queen', seat).round(2)} | #{games.sum { |r| r.dig('stats', 'taken', 'moons', seat) }} |"
+        end
+        table('## Penalties by seat', ['Seat', 'Hearts per game', 'Q♠ per game', 'Moons shot'], rows,
+              "Player 2 sits on Player 1's left, and so on around the table.")
+      end
+
+      def average(games, key, seat) = games.sum { |r| r.dig('stats', 'taken', key, seat) }.fdiv(games.length)
+    end
+  end
+end

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

@@ -0,0 +1,255 @@
+module Hearts
+  module Session
+    class Runner < PlaiTestr::Session::Runner
+      include Bot
+
+      RULES_PATH = File.expand_path('../../../data/rules.md', __dir__)
+      RECENT_LOG = 12
+
+      DEBRIEF_QUESTIONS = [
+        'Which decision in this game mattered most, and why?',
+        'Which rule or restriction was unclear or confusing?',
+        'Which choices felt automatic (the choice did not matter)?'
+      ].freeze
+
+      def setup
+        data.merge!('hand' => 0, 'log' => [], 'taken_total' => %w[hearts queen moons].to_h { |key| [key, players.to_h { |p| [p, 0] }] })
+        deal
+        out.puts "  Setup (seed #{@seed}): #{players.length} players; the game ends at #{limit} points."
+      end
+
+      def next_player = @game_state.active
+
+      def legal_moves(player)
+        case step
+        when 'pass'
+          hand(player).map { |card| option("Pass #{card['name']}#{" (#{pts(Hearts.points(card))})" if Hearts.points(card).positive?}", pass: { value: card['uid'] }) }
+        when 'play'
+          playable(player).map do |card|
+            facts = [(pts(Hearts.points(card)) if Hearts.points(card).positive?), (outcome(card) unless trick.empty?)].compact
+            option("Play #{card['name']}#{" (#{facts.join('; ')})" if facts.any?}", public: "played #{card['name']}", play: { value: card['uid'] })
+          end
+        end
+      end
+
+      def pick_range(_player) = step == 'pass' ? [PASS_COUNT, PASS_COUNT] : nil
+
+      def apply_action_effects(player, action)
+        case action
+        in { pass: { value: uids } } then pass(player, uids)
+        in { play: { value: uid } }  then play(player, uid)
+        end
+      end
+
+      def rules_text_for(_player) = @rules_text ||= File.read(RULES_PATH)
+
+      def view_text_for(player)
+        [
+          "Hand #{data['hand']}. Scores (lower is better; the game ends at #{limit}): #{per_player(player) { |p| pstate(p).score }}",
+          ("Points taken this hand: #{per_player(player) { |p| points_in(taken[p]) }}. Hearts broken: #{data['hearts_broken'] ? 'yes' : 'no'}." if step == 'play'),
+          ("Current trick: #{trick_text(player)}" if step == 'play'),
+          "Your hand: #{list(hand(player))}",
+          '',
+          instruction(player)
+        ].compact.join("\n")
+      end
+
+      def turn_phase(_player)
+        step == 'pass' ? "hand #{data['hand']} · pass #{data['pass']}" : "hand #{data['hand']} · trick #{data['tricks'] + 1}"
+      end
+
+      def report_sections
+        rows = players.map { |p| "| #{p} | #{pstate(p).score} | #{totals['hearts'][p]} | #{totals['queen'][p]} | #{totals['moons'][p]} |" }
+
+        [<<~MD.strip]
+          ## Hearts
+
+          #{data['hand']} hands played.
+
+          | Player | Score | Hearts taken | Q♠ taken | Moons shot |
+          |---|---|---|---|---|
+          #{rows.join("\n")}
+        MD
+      end
+
+      def botrun_stats = { 'hands' => data['hand'], 'taken' => totals }
+
+      def recent_events_for(player) = event_log.recent_for(player, RECENT_LOG)
+
+      def debrief_questions(_player) = DEBRIEF_QUESTIONS
+
+      private
+
+      def deal
+        deck   = PlaiTestr::Deck.build(@rules).shuffle(random: @rng)
+        number = data['hand'] + 1
+
+        players.each { |p| hand(p).replace(sorted(deck.shift(HAND_SIZE))) }
+        data.merge!('hand' => number, 'pass' => PASSES[(number - 1) % PASSES.length], 'passes' => {},
+                    'taken' => players.to_h { |p| [p, []] }, 'trick' => [], 'tricks' => 0, 'hearts_broken' => false)
+        log("Hand #{number} dealt: pass #{data['pass']}")
+
+        if data['pass'] == 'hold'
+          start_tricks
+        else
+          data.merge!('step' => 'pass', 'active' => players.first)
+        end
+      end
+
+      def pass(player, uids)
+        data['passes'][player] = uids
+
+        if data['passes'].length == players.length
+          exchange
+        else
+          data['active'] = seat(player, 1)
+        end
+      end
+
+      def exchange
+        given = data['passes'].to_h { |giver, uids| [giver, uids.map { |uid| take(giver, uid) }] }
+
+        given.each do |giver, cards|
+          receiver = seat(giver, SEAT_SHIFT.fetch(data['pass']))
+          hand(receiver).replace(sorted(hand(receiver) + cards))
+          log("You passed #{list(cards)} to #{receiver}", to: giver)
+          log("#{giver} passed you #{list(cards)}", to: receiver)
+        end
+        start_tricks
+      end
+
+      def start_tricks
+        data.merge!('step' => 'play', 'active' => players.find { |p| hand(p).any? { |c| c['name'] == OPENER } })
+      end
+
+      def play(player, uid)
+        card = take(player, uid)
+        trick << { 'player' => player, 'card' => card }
+        data['hearts_broken'] ||= card['suit'] == 'hearts'
+        log("#{player} played #{card['name']}")
+
+        if trick.length == players.length
+          finish_trick
+        else
+          data['active'] = seat(player, 1)
+        end
+      end
+
+      def finish_trick
+        winner = trick.select { |t| t['card']['suit'] == led_suit }.max_by { |t| t['card']['rank'] }['player']
+        cards  = trick.map { |t| t['card'] }
+
+        taken[winner].concat(cards)
+        log("#{winner} took the trick (#{list(cards)})#{" for #{pts(points_in(cards))}" if points_in(cards).positive?}")
+        data.merge!('trick' => [], 'tricks' => data['tricks'] + 1, 'active' => winner)
+        score_hand if data['tricks'] == HAND_SIZE
+      end
+
+      def score_hand
+        points  = players.to_h { |p| [p, points_in(taken[p])] }
+        shooter = points.key(MOON)
+        points  = players.to_h { |p| [p, p == shooter ? 0 : MOON] } if shooter
+
+        players.each do |p|
+          pstate(p).apply_changes('score' => pstate(p).score + points[p])
+          totals['hearts'][p] += taken[p].count { |c| c['suit'] == 'hearts' }
+          totals['queen'][p]  += 1 if taken[p].any? { |c| c['name'] == QUEEN }
+        end
+        totals['moons'][shooter] += 1 if shooter
+        log("Hand #{data['hand']} scored: #{players.map { |p| "#{p} +#{points[p]}" }.join(', ')}#{" (#{shooter} shot the moon)" if shooter}")
+
+        players.any? { |p| pstate(p).score >= limit } ? end_game : deal
+      end
+
+      def end_game
+        low     = players.map { |p| pstate(p).score }.min
+        winners = players.select { |p| pstate(p).score == low }
+
+        @game_state.apply_changes('status' => { 'game_over' => true, 'winner' => winners.join(' & '),
+                                                'end_reason' => winners.one? ? 'fewest_points' : 'tied_for_fewest_points' })
+      end
+
+      def playable(player)
+        cards = hand(player)
+
+        if trick.empty?
+          data['tricks'].zero? ? cards.select { |c| c['name'] == OPENER } : leads(cards)
+        else
+          follows(cards)
+        end
+      end
+
+      def leads(cards)
+        safe = cards.reject { |c| c['suit'] == 'hearts' }
+        data['hearts_broken'] || safe.empty? ? cards : safe
+      end
+
+      def follows(cards)
+        suited = cards.select { |c| c['suit'] == led_suit }
+        clean  = cards.select { |c| Hearts.points(c).zero? }
+
+        if suited.any? then suited
+        elsif data['tricks'].zero? && clean.any? then clean
+        else cards
+        end
+      end
+
+      def trick_text(player)
+        return 'none yet (you lead)' if trick.empty?
+
+        points = points_in(trick.map { |t| t['card'] })
+        "#{trick.map { |t| "#{whose(t['player'], player)}: #{t['card']['name']}" }.join(', ')} (#{led_suit} led; #{points.zero? ? 'no points' : pts(points)} in it so far)"
+      end
+
+      def outcome(card)
+        best = trick.map { |t| t['card'] }.select { |c| c['suit'] == led_suit }.max_by { |c| c['rank'] }
+
+        if card['suit'] != led_suit then 'cannot win this trick'
+        elsif card['rank'] < best['rank'] then "stays under the #{best['name']}"
+        elsif last_to_play? then 'wins the trick'
+        else 'wins the trick so far'
+        end
+      end
+
+      def instruction(player)
+        case step
+        when 'pass' then "Choose #{PASS_COUNT} cards to pass #{data['pass']} to #{seat(player, SEAT_SHIFT.fetch(data['pass']))}."
+        when 'play' then play_instruction(player)
+        end
+      end
+
+      def play_instruction(player)
+        if trick.empty?
+          "You lead this trick.#{' Hearts are not broken, so you may not lead a heart unless you have only hearts.' unless data['hearts_broken']}"
+        elsif hand(player).any? { |c| c['suit'] == led_suit }
+          "You are following, not leading: you must play one of your #{led_suit}."
+        else
+          "You are following, not leading. You have no #{led_suit}, so you may play any card#{', but not a heart or the Q♠ unless you have nothing else' if data['tricks'].zero?}."
+        end
+      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 seat(player, shift) = players[(players.index(player) + shift) % players.length]
+
+      def per_player(viewer) = players.map { |p| "#{whose(p, viewer)} #{yield p}" }.join(', ')
+
+      def whose(player, viewer) = player == viewer ? 'You' : player
+
+      def points_in(cards) = cards.sum { |c| Hearts.points(c) }
+      def list(cards)      = cards.map { |c| c['name'] }.join(', ')
+      def pts(points)      = points == 1 ? '1 pt' : "#{points} pts"
+      def led_suit         = trick.first['card']['suit']
+      def limit            = @rules.fetch('points_to_end')
+      def step             = @game_state.step
+      def trick            = @game_state.trick
+      def taken            = @game_state.taken
+      def totals           = data['taken_total']
+      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/hearts/lib/hearts/state/game_state.rb

@@ -0,0 +1,19 @@
+module Hearts
+  module State
+    class GameState < PlaiTestr::State::GameState
+      def step   = @data['step']
+      def active = @data['active']
+      def trick  = @data['trick'] ||= []
+      def taken  = @data['taken'] ||= {}
+
+      private
+
+      def data_for(observer)
+        @data.except('passes', 'log').merge(
+          'passed' => @data.fetch('passes', {}).keys,
+          'log'    => PlaiTestr::EventLog.new(@data.fetch('log', [])).visible_to(observer)
+        )
+      end
+    end
+  end
+end

data/templates/examples/hearts/lib/hearts.rb

@@ -0,0 +1,11 @@
+require_relative 'hearts/game'
+require_relative 'hearts/state/game_state'
+require_relative 'hearts/bot'
+require_relative 'hearts/session/runner'
+require_relative 'hearts/reporter/botrun_report'
+
+PlaiTestr.register('hearts',
+                    runner_class:        Hearts::Session::Runner,
+                    game_state_class:    Hearts::State::GameState,
+                    botrun_report_class: Hearts::Reporter::BotrunReport,
+                    players:             ['Player 1', 'Player 2', 'Player 3', 'Player 4'])

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

@@ -0,0 +1,122 @@
+require 'spec_helper'
+
+RSpec.describe Hearts::Session::Runner do
+  let(:game)   { PlaiTestr.load('hearts') }
+  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 the whole deck, 13 cards each' do
+    hands = game.players.map { |p| state.player_state(p).hand }
+
+    expect(hands.map(&:length)).to all(eq(13))
+    expect(hands.flatten.map { |c| c['uid'] }.uniq.length).to eq(52)
+  end
+
+  it 'passes 3 cards to the left on the first hand, then starts with the 2♣' do
+    passed = game.players.to_h { |p| [p, state.player_state(p).hand.first(3)] }
+    game.players.each { |p| runner.apply_action_effects(p, { pass: { value: passed[p].map { |c| c['uid'] } } }) }
+
+    expect(state.player_state('Player 2').hand).to include(*passed['Player 1'])
+    expect(state.player_state(state.active).hand.map { |c| c['name'] }).to include('2♣')
+    expect(labels(state.active)).to eq(['Play 2♣'])
+  end
+
+  context 'during tricks' do
+    before { state.data.merge!('step' => 'play', 'tricks' => 1, 'trick' => [], 'active' => 'Player 1') }
+
+    it 'does not lead hearts until they are broken' do
+      give('Player 1', '5♥', '9♣')
+
+      expect(labels('Player 1')).to eq(['Play 9♣'])
+    end
+
+    it 'follows the suit led when it can, and says whether each card wins the trick' do
+      give('Player 2', '5♥', '7♣', 'K♣')
+      state.data['trick'] = [{ 'player' => 'Player 1', 'card' => cards('9♣').first }]
+
+      expect(labels('Player 2')).to eq(['Play 7♣ (stays under the 9♣)', 'Play K♣ (wins the trick so far)'])
+    end
+
+    it 'tells a player who cannot follow suit that any card is allowed' do
+      give('Player 2', 'Q♠', '5♥')
+      state.data.merge!('trick' => [{ 'player' => 'Player 1', 'card' => cards('2♣').first }], 'active' => 'Player 2')
+
+      expect(runner.view_text_for('Player 2')).to end_with('You are following, not leading. You have no clubs, so you may play any card.')
+      expect(labels('Player 2')).to eq(['Play Q♠ (13 pts; cannot win this trick)', 'Play 5♥ (1 pt; cannot win this trick)'])
+    end
+
+    it 'keeps points off the first trick unless there is nothing else' do
+      state.data.merge!('tricks' => 0, 'trick' => [{ 'player' => 'Player 1', 'card' => cards('2♣').first }])
+      give('Player 2', 'Q♠', '5♥', '9♦')
+
+      expect(labels('Player 2')).to eq(['Play 9♦ (cannot win this trick)'])
+    end
+  end
+
+  it 'scores 26 to everyone else when a player shoots the moon' do
+    state.data['taken'] = { 'Player 1' => deck.select { |c| Hearts.points(c).positive? }, 'Player 2' => [], 'Player 3' => [], 'Player 4' => [] }
+    runner.send(:score_hand)
+
+    expect(state.scores).to eq('Player 1' => 0, 'Player 2' => 26, 'Player 3' => 26, 'Player 4' => 26)
+  end
+
+  it 'counts hearts, the Q♠ and moons in the session report' do
+    state.data['taken'] = { 'Player 1' => cards('Q♠', '5♥'), 'Player 2' => cards('2♥'), 'Player 3' => [], 'Player 4' => [] }
+    runner.send(:score_hand)
+
+    expect(runner.report_sections.first).to include('| Player 1 | 14 | 1 | 1 | 0 |', '| Player 2 | 1 | 1 | 0 | 0 |')
+  end
+
+  describe 'personas' do
+    it 'seats four players with two personas, each used twice' do
+      expect(state.data['personas'].values.tally).to eq('safe_player' => 2, 'moon_shooter' => 2)
+    end
+
+    it 'has the moon shooter keep the dangerous cards the safe player passes' do
+      state.player_state('Player 1').hand.replace(cards('Q♠', 'A♥', '2♣', '3♦'))
+      moves = runner.legal_moves('Player 1')
+      state.data['personas']['Player 1'] = 'safe_player'
+      safe  = runner.bot_choice('Player 1', moves, pick: [2, 2])
+      state.data['personas']['Player 1'] = 'moon_shooter'
+      moon  = runner.bot_choice('Player 1', moves, pick: [2, 2])
+
+      expect(safe['choices'].map { |i| moves[i - 1][:label] }).to contain_exactly('Pass Q♠ (13 pts)', 'Pass A♥ (1 pt)')
+      expect(moon['choices'].map { |i| moves[i - 1][:label] }).to contain_exactly('Pass 2♣', 'Pass 3♦')
+    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 and reports penalties by seat' do
+    results = PlaiTestr::Botrun.new(game: game, players: game.players, seeds: (1..20).to_a).run
+    report  = game.botrun_report_class.new(results, game: 'Hearts', version: '1.0.0', seconds: 1.0).to_markdown
+
+    expect(results.map { |r| r['error'] }.compact).to be_empty
+    expect(results.map { |r| r['winner'] }).to all(start_with('Player'))
+    expect(report).to include('## Hands per game', '## Penalties by seat')
+  end
+end

data/templates/game/data/bots.yml

@@ -0,0 +1,13 @@
+# 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 {}
+bots: {}

data/templates/game/data/personas.yml

@@ -0,0 +1,16 @@
+# 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 {}
+personas: {}

data/templates/game/data/rules.json.erb

@@ -0,0 +1,16 @@
+{
+  "game": {
+    "name": "<%= title %>",
+    "version": "0.1.0",
+    "description": "One or two sentences the model players read first: what the game is and how to win.",
+    "player_count": { "min": 2, "max": 4, "default": 2 }
+  },
+
+  "components": [
+    {
+      "name": "Deck",
+      "type": "card_deck",
+      "values": []
+    }
+  ]
+}

data/templates/game/data/rules.md.erb

@@ -0,0 +1,11 @@
+# <%= title %>
+
+v0.1.0
+
+## Components
+
+## Setup
+
+## Turn
+
+## End of the game

data/templates/game/lib/__name__/bot.rb.erb

@@ -0,0 +1,7 @@
+module <%= module_name %>
+  module Bot
+    def bot_choice(_player, _moves, pick: nil)
+      nil
+    end
+  end
+end

data/templates/game/lib/__name__/session/runner.rb.erb

@@ -0,0 +1,36 @@
+module <%= module_name %>
+  module Session
+    class Runner < PlaiTestr::Session::Runner
+      include Bot
+
+      RULES_PATH = File.expand_path('../../../data/rules.md', __dir__)
+
+      DEBRIEF_QUESTIONS = [
+        'Which decision in this game mattered most, and why?',
+        'Which rule was unclear or confusing?',
+        'Which choices felt automatic (the choice did not matter)?'
+      ].freeze
+
+      def setup
+        raise NotImplementedError, "#{self.class}#setup: build the starting state; PlaiTestr::Deck.build(@rules).shuffle(random: @rng) gives a shuffled deck"
+      end
+
+      def legal_moves(_player)
+        raise NotImplementedError, "#{self.class}#legal_moves: return [option('Play 3♣', public: 'played 3♣', play: { value: uid }), ...]"
+      end
+
+      def apply_action_effects(_player, _action)
+        raise NotImplementedError, "#{self.class}#apply_action_effects: case action in { play: { value: uid } } then ...; apply it to @game_state; set status 'game_over', 'winner' and 'end_reason' when the game ends"
+      end
+
+      def rules_text_for(_player) = @rules_text ||= File.read(RULES_PATH)
+
+      def debrief_questions(_player) = DEBRIEF_QUESTIONS
+
+      private
+
+      def players        = @game_state.players
+      def pstate(player) = @game_state.player_state(player)
+    end
+  end
+end

data/templates/game/lib/__name__/state/game_state.rb.erb

@@ -0,0 +1,11 @@
+module <%= module_name %>
+  module State
+    class GameState < PlaiTestr::State::GameState
+      private
+
+      def data_for(observer)
+        @data.except('log').merge('log' => PlaiTestr::EventLog.new(@data.fetch('log', [])).visible_to(observer))
+      end
+    end
+  end
+end

data/templates/game/lib/__name__.rb.erb

@@ -0,0 +1,10 @@
+require_relative '<%= name %>/state/game_state'
+require_relative '<%= name %>/bot'
+require_relative '<%= name %>/session/runner'
+
+PlaiTestr.register('<%= name %>',
+                   runner_class:     <%= module_name %>::Session::Runner,
+                   game_state_class: <%= module_name %>::State::GameState,
+                   # max_decisions:  5_000,
+                   # model_settings: { context_size: 16_384 },
+                  )

data/templates/game/spec/session/runner_spec.rb.erb

@@ -0,0 +1,29 @@
+require 'spec_helper'
+
+RSpec.describe <%= module_name %>::Session::Runner do
+  let(:game) { PlaiTestr.load('<%= name %>') }
+
+  def runner(seed) = described_class.new(game: game, players: game.players, seed: seed, mode: 'bot', persist: false, out: StringIO.new)
+
+  it 'plays whole games with its bot rules' do
+    pending 'implement setup, legal_moves and apply_action_effects'
+
+    results = PlaiTestr::Botrun.new(game: game, players: game.players, seeds: (1..10).to_a).run
+
+    expect(results.map { |r| r['error'] }.compact).to be_empty
+  end
+
+  it 'builds every prompt a model player would see' do
+    pending 'implement the game, its bot rules and view_text_for'
+
+    (1..3).each do |seed|
+      session = runner(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
+    end
+  end
+end