text_player 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 560e01113ea75b493fc246f2fdc7141fcd20c0d294a877189e823c91503e2c46
+  data.tar.gz: 966be56852cb9ef8561cbca87f34b03e9e51f34d0b89034207cbca187f8accc3
+SHA512:
+  metadata.gz: bffe4f70ce951b792b712185e749b4e90d116f85c03f90a91279eb042159f399a46ed50678922fdca8596d89fbb9ce99fdd438013c85277bde876299151cafdc
+  data.tar.gz: d35806c05c92dbf1516c055a58b439c34f32c20ee243c69f4b352b32c3471df1f66d2c0d1078c963002b612d3f4bdddc7120c73f472e63edd32a69f7dd200959

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-06-08
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Martin Emde
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,171 @@
+# TextPlayer
+
+A Ruby interface for running text-based interactive fiction games using the Frotz Z-Machine interpreter. This gem provides structured access to classic text adventure games with multiple output formatters for different use cases.
+
+Inspired by [@danielricks/textplayer](https://davidgriffith.gitlab.io/frotz/) - the original Python implementation.
+
+I have chosen not to distribute the games in the ruby gem. You'll need to clone this repository to use the games directly without the full pathname. This is out of an abundance of caution and respect to the owners. Offering them for download, as is done regularly, may be interpreted differently than distributing them in a package.
+
+I am grateful for the ability to use these games for learning and building. Zork is the game that got me started on MUDs as a kid, which is the reason I'm a programmer now.
+
+## Requirements
+
+TextPlayer requires Frotz, a Z-Machine interpreter written by Stefan Jokisch in 1995-1997. More information [here](http://frotz.sourceforge.net/).
+
+Use Homebrew to install the `frotz` package:
+
+```bash
+$ brew instal frotz
+```
+
+If you don't have homebrew, download the source code, build and install.
+
+```bash
+$ git clone https://github.com/DavidGriffith/frotz.git
+$ cd frotz
+$ make dumb
+$ make dumb_install # optional, but recommended
+```
+
+The `dfrotz` (dumb frotz) binary must be available in your PATH or you will need to pass the path to the dfrotz executable as an argument to TextPlayer.
+
+## Installation
+
+Add to an application:
+
+```bash
+$ bundle add text_player
+$ bundle install
+```
+
+Or install it:
+
+```bash
+$ gem install text_player
+```
+
+If you'd like to use the games included in the repository, clone it directly from github.com:
+
+```bash
+$ git clone git@github.com:martinemde/text_player.git
+```
+
+## Usage
+
+You can use the command line to check if it's working:
+
+```bash
+$ text_player help
+$ text_player play zork1
+```
+
+### Basic Example
+
+The point of this library is to allow you to run text based adventure games programmatically.
+
+```ruby
+require 'text_player'
+
+# Create a new game session
+game = TextPlayer::Session.new('games/zork1.z5')
+
+# Or specify a custom dfrotz path
+# This must be dfrotz, the DUMB version of frotz, which installs with frotz.
+game = TextPlayer::Session.new('games/zork1.z5', dfrotz: '~/bin/dfrotz')
+
+# Start the game
+start_output = game.start
+puts start_output
+
+# Execute commands
+response = game.call('go north')
+puts response
+
+# Get current score
+if score = game.score
+  current_score, max_score = score.score, score.out_of
+  puts "Score: #{current_score}/#{max_score}"
+end
+
+# Save and restore
+game.save('my_save')
+game.restore('my_save')
+
+# Quit the game
+game.quit
+```
+
+### Save and Restore Operations
+
+```ruby
+# Save to default slot (autosave)
+save_result = game.save
+puts save_result  # Formatted feedback about save operation
+
+# Save to named slot
+game.save('before_dragon')
+
+# Restore from default slot
+game.restore
+
+# Restore from named slot
+game.restore('before_dragon')
+```
+
+### Interactive Shell Example
+
+```ruby
+require 'text_player'
+
+game = TextPlayer::Session.new('zork1.z5')
+formatter = TextPlayer::Formatters::Shell
+game.run do |result|
+  formatter.new(result).write($stdout)
+  command = $stdin.gets
+  break if command.nil?
+  command
+end
+```
+
+### Configuring dfrotz Path
+
+By default, TextPlayer looks for the `dfrotz` executable in the system PATH `dfrotz`. You can specify a custom path:
+
+```ruby
+# Use local path to compiled dfrotz
+game = TextPlayer::Session.new('zork1.z5', dfrotz: './frotz/dfrotz')
+
+# Use absolute path
+game = TextPlayer::Session.new('zork1.z5', dfrotz: '/usr/local/bin/dfrotz')
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/martinemde/text_player.
+
+## Game Files
+
+You'll need Z-Machine game files (`.z3`, `.z5`, `.z8` extensions) to play. Many classic interactive fiction games are available from:
+
+- [The Interactive Fiction Archive](https://www.ifarchive.org/)
+- [Infocom games](http://www.infocom-if.org/downloads/downloads.html)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+I have included the same games from [@danielricks/textplayer](https://github.com/danielricks/textplayer), assuming that in the last ~10 years that it has not been a problem.
+
+The games are copyright and licensed by their respective owners.
+
+**Please open an issue on the repository or contact me directly if there are any concerns.**
+
+## Credits
+
+This Ruby implementation was inspired and influenced by [@danielricks/textplayer](https://github.com/danielricks/textplayer), who wrote a Python interface for Frotz to facilitate training models to automatically play the game.

data/exe/text_player

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/text_player/cli"
+
+TextPlayer::CLI.start(ARGV)

data/lib/text_player/cli.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "../text_player"
+
+module TextPlayer
+  class CLI < Thor
+    default_command :play
+
+    desc "play GAME", "Play a text adventure game"
+    option :formatter, type: :string, default: "shell", desc: "Specify the formatter to use (text, data, json, shell)"
+    def play(game)
+      gamefile = TextPlayer::Gamefile.from_input(game)
+      session = TextPlayer::Session.new(gamefile)
+
+      formatter_type = options[:formatter].downcase.to_sym
+      formatter = TextPlayer::Formatters.by_name(formatter_type)
+
+      session.run do |result|
+        formatter.write(result, $stdout)
+        $stdin.gets
+      end
+    end
+
+    def self.exit_on_failure?
+      true
+    end
+  end
+end

data/lib/text_player/command_result.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module TextPlayer
+  # Encapsulates the result of executing a command
+  CommandResult = Data.define(:input, :raw_output, :operation, :success, :message, :details) do
+    # Common failure patterns in text adventure games
+
+    def initialize(input:, raw_output: "", operation: :action, success: true, message: nil, **details)
+      super(input:, raw_output:, operation:, success:, message:, details:)
+    end
+
+    def action_command? = operation == :action
+
+    def system_command? = !action_command?
+
+    def success? = success
+
+    def failure? = !success
+
+    def to_h
+      super.merge(details)
+    end
+
+    private
+
+    def respond_to_missing?(method, include_private = false)
+      details.key?(method) || super
+    end
+
+    def method_missing(method, *args, &block)
+      if details.key?(method)
+        details[method]
+      else
+        super
+      end
+    end
+  end
+end

data/lib/text_player/commands/action.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "../command_result"
+
+module TextPlayer
+  module Commands
+    # Command for generic game actions (look, go north, take sword, etc.)
+    Action = Data.define(:input) do
+      def execute(game)
+        game.write(input)
+        raw_output = game.read_until(TextPlayer::PROMPT_REGEX)
+
+        CommandResult.new(
+          input: input,
+          raw_output: raw_output,
+          operation: :action,
+          success: !failure_detected?(raw_output)
+        )
+      end
+
+      def failure_detected?(output)
+        TextPlayer::FAILURE_PATTERNS.any? { |pattern| output.match?(pattern) }
+      end
+    end
+  end
+end

data/lib/text_player/commands/quit.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "../command_result"
+
+module TextPlayer
+  module Commands
+    # Command for quitting the game
+    Quit = Data.define do
+      def input
+        "quit"
+      end
+
+      def execute(game)
+        begin
+          game.write(input)
+          sleep(0.2)
+          game.write("y")
+        rescue Errno::EPIPE
+          # Expected when process exits - ignore
+        ensure
+          game.terminate
+        end
+
+        CommandResult.new(
+          input: input,
+          operation: :quit,
+          success: true,
+          message: "Game quit successfully"
+        )
+      end
+    end
+  end
+end

data/lib/text_player/commands/restore.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "../command_result"
+
+module TextPlayer
+  module Commands
+    # Command for restoring game state
+    Restore = Data.define(:savefile) do
+      def input
+        "restore"
+      end
+
+      def execute(game)
+        unless savefile.exist?
+          return CommandResult.new(
+            input: input,
+            operation: :restore,
+            success: false,
+            message: "Restore failed - file not found",
+            slot: savefile.slot,
+            filename: savefile.filename
+          )
+        end
+
+        game.write(input)
+        game.read_until(TextPlayer::FILENAME_PROMPT_REGEX)
+        game.write(savefile.filename)
+
+        result = game.read_until(/Ok\.|Failed\.|not found|>/i)
+
+        success = result.include?("Ok.")
+        message = if success
+          "Game restored successfully"
+        elsif result.include?("Failed") || result.include?("not found")
+          "Restore failed - file not found by dfrotz process even though it existed before running this command"
+        else
+          "Restore operation completed"
+        end
+
+        CommandResult.new(
+          input: input,
+          raw_output: result,
+          operation: :restore,
+          success: success,
+          message: message,
+          slot: savefile.slot,
+          filename: savefile.filename
+        )
+      end
+    end
+  end
+end

data/lib/text_player/commands/save.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../command_result"
+
+module TextPlayer
+  module Commands
+    # Command for saving game state
+    Save = Data.define(:savefile) do
+      def input
+        "save"
+      end
+
+      def execute(game)
+        # Note: we could check if the file exists and delete it here, but
+        # instead we will let dfrotz handle it in case the save fails.
+        game.write(input)
+        game.read_until(TextPlayer::FILENAME_PROMPT_REGEX)
+        game.write(savefile.filename)
+
+        result = game.read_until(/Overwrite existing file\? |Ok\.|Failed\.|>/i)
+
+        if result.include?("Overwrite existing file?")
+          game.write("y")
+          result += game.read_until(/Ok\.|Failed\.|>/i)
+        end
+
+        success = result.include?("Ok.")
+        message = if success
+          "[#{savefile.slot}] Game saved successfully"
+        else
+          "Save operation failed"
+        end
+
+        CommandResult.new(
+          input: input,
+          raw_output: result,
+          operation: :save,
+          success: success,
+          message: message,
+          slot: savefile.slot,
+          filename: savefile.filename
+        )
+      end
+    end
+  end
+end

data/lib/text_player/commands/score.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../command_result"
+
+module TextPlayer
+  module Commands
+    # Command for getting game score
+    Score = Data.define do
+      def input
+        "score"
+      end
+
+      def execute(game)
+        game.write(input)
+        raw_output = game.read_until(TextPlayer::PROMPT_REGEX)
+
+        score, out_of = nil
+        if TextPlayer::SCORE_REGEX =~ raw_output
+          score, out_of = $1, $2
+        end
+
+        # Some games give dialog instead of score
+        # We will return what the game says as a success
+        # whether or not we find a score.
+        CommandResult.new(
+          input:,
+          raw_output:,
+          operation: :score,
+          success: true,
+          score:,
+          out_of:
+        )
+      end
+    end
+  end
+end

data/lib/text_player/commands/start.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../command_result"
+
+module TextPlayer
+  module Commands
+    # Command for starting the game
+    # This is used to start the game and is not accessible by the user.
+    Start = Data.define do
+      def input
+        nil
+      end
+
+      def execute(game)
+        raw_output = game.read_until(TextPlayer::PROMPT_REGEX)
+
+        # Handle "Press any key" prompts - be more specific
+        max_iterations = 5
+        lines = raw_output.lines
+        while /\A\W*(Press|Hit|More)\s+.*\z/i.match?(lines.last) # if last line is a continuation prompt
+          lines.pop
+          game.write(" ")
+          lines.concat game.read_until(TextPlayer::PROMPT_REGEX).lines
+          max_iterations -= 1
+          break if max_iterations.zero?
+        end
+        raw_output = lines.join
+
+        # Skip introduction if offered
+        if raw_output.include?("introduction")
+          game.write("no")
+          raw_output += game.read_until(TextPlayer::PROMPT_REGEX)
+        end
+
+        CommandResult.new(
+          input: input,
+          raw_output: raw_output,
+          operation: :start,
+          success: true
+        )
+      end
+    end
+  end
+end

data/lib/text_player/commands.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "commands/action"
+require_relative "commands/quit"
+require_relative "commands/restore"
+require_relative "commands/save"
+require_relative "commands/score"
+require_relative "commands/start"
+
+module TextPlayer
+  module Commands
+    def self.create(input, game_name: nil)
+      case input.strip.downcase
+      when "score"
+        Commands::Score.new
+      when /^save\s*(\S+)/ # no end anchor to catch all save commands that have args
+        Commands::Save.new(savefile: Savefile.new(game_name:, slot: Regexp.last_match(1)))
+      when "save"
+        Commands::Save.new(savefile: Savefile.new(game_name:))
+      when /^restore\s*(\S+)/ # no end anchor to catch all restore commands that have args
+        Commands::Restore.new(savefile: Savefile.new(game_name:, slot: Regexp.last_match(1)))
+      when "restore"
+        Commands::Restore.new(savefile: Savefile.new(game_name:))
+      when "quit"
+        Commands::Quit.new
+      else
+        Commands::Action.new(input:)
+      end
+    end
+  end
+end

data/lib/text_player/dfrotz.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+require "pathname"
+
+module TextPlayer
+  # Dfrotz - Direct interface to dfrotz interpreter
+  class Dfrotz
+    TIMEOUT = 1
+    IO_SELECT_TIMEOUT = 0.1
+    CHUNK_SIZE = 1024
+    COMMAND_DELAY = 0.1
+    SYSTEM_PATH = "dfrotz"
+
+    def self.path
+      ENV.fetch("DFROTZ_PATH", SYSTEM_PATH)
+    end
+
+    def self.executable?(path = self.path)
+      File.executable?(path) || system("which #{path} > /dev/null 2>&1")
+    end
+
+    def initialize(game_path, dfrotz: nil, timeout: TIMEOUT, command_delay: COMMAND_DELAY)
+      Signal.trap("PIPE", "DEFAULT")
+      @game_path = game_path
+      @dfrotz = dfrotz || self.class.path
+      raise "dfrotz not found: #{@dfrotz.inspect}" unless self.class.executable?(@dfrotz)
+
+      @timeout = timeout
+      @command_delay = command_delay
+      @stdin = @stdout = @wait_thr = nil
+    end
+
+    def start
+      return true if running?
+
+      @stdin, @stdout, @wait_thr = Open3.popen2(@dfrotz, @game_path)
+      true
+    end
+
+    # Send a command to the game.
+    #
+    # Automatically sleeps for COMMAND_DELAY seconds, keeping callers simple.
+    # It takes time for every command to return output. If you don't wait,
+    # you'll get nothing in response, and then follow up commands will
+    # return the last command's output instead of the current command's.
+    def write(cmd)
+      return false unless running?
+
+      @stdin.puts(cmd)
+      @stdin.flush
+      sleep(@command_delay)
+      true
+    rescue Errno::EPIPE
+      # Process has exited - this is expected during quit
+      false
+    end
+
+    def read_all
+      read_until(nil)
+    end
+
+    def read_until(pattern)
+      return "" unless running?
+
+      output = +""
+      begin
+        Timeout.timeout(@timeout) do
+          loop do
+            break unless read_chunk_into(output)
+            break if pattern && output =~ pattern
+          end
+        end
+      rescue Timeout::Error
+        # Return whatever we got
+      end
+      output
+    end
+
+    def running?
+      @stdin && !@stdin.closed? && @wait_thr&.alive?
+    end
+
+    def terminate
+      return true unless running?
+
+      close
+      @wait_thr.kill
+    rescue
+      true
+    end
+
+    private
+
+    def read_chunk_into(output)
+      return false unless IO.select([@stdout], nil, nil, IO_SELECT_TIMEOUT)
+
+      chunk = @stdout.read_nonblock(CHUNK_SIZE)
+      output << chunk
+      true
+    rescue IO::WaitReadable, EOFError
+      false
+    end
+
+    def close
+      @stdin&.close
+      @stdout&.close
+    rescue
+      true
+    end
+  end
+end

data/lib/text_player/formatters/base.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../command_result"
+
+module TextPlayer
+  module Formatters
+    # Base formatter with stream writing and common interface
+    class Base
+      def self.write(command_result, stream)
+        new(command_result).write(stream)
+      end
+
+      attr_reader :command_result
+
+      def initialize(command_result)
+        @command_result = command_result
+      end
+
+      # Write formatted output to stream
+      def write(stream)
+        stream.write(to_s)
+      end
+
+      # String representation for stream output
+      def to_s
+        command_result.to_h.inspect
+      end
+
+      # Hash representation for programmatic access
+      def to_h
+        command_result.to_h
+      end
+    end
+  end
+end

data/lib/text_player/formatters/data.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module TextPlayer
+  module Formatters
+    # Data formatter - parses game-specific data and returns structured output
+    class Data < Base
+      SCORE_PATTERN = /Score:\s*(\d+)/i
+      MOVES_PATTERN = /Moves:\s*(\d+)/i
+      TIME_PATTERN = /(\d{1,2}:\d{2}\s*(?:AM|PM))/i
+
+      def to_h
+        super.merge(parsed_data)
+      end
+
+      private
+
+      def parsed_data
+        @parsed_data ||= begin
+          raw_output = command_result.raw_output
+          cleaned = raw_output.dup
+
+          # Extract from original, remove from cleaned copy
+          location = extract_location(raw_output)
+          score = extract_score(raw_output)
+          moves = extract_moves(raw_output)
+          time = extract_time(raw_output)
+          prompt = extract_prompt(raw_output)
+
+          # Remove what we found from the cleaned copy
+          remove_extracted_data!(cleaned, location, score, moves, time, prompt)
+
+          # Final cleanup of remaining text
+          output = final_cleanup(cleaned)
+
+          {
+            location: location,
+            score: score,
+            moves: moves,
+            time: time,
+            prompt: prompt,
+            output: output,
+            has_prompt: !prompt.nil?
+          }
+        end
+      end
+
+      def extract_location(text)
+        lines = text.split("\n")
+        first_line = lines.first&.strip
+
+        return nil if first_line.nil? || first_line.empty?
+
+        # Try different location extraction strategies
+        location = extract_location_with_stats(first_line) ||
+          extract_standalone_location(first_line)
+
+        return nil unless location && valid_location?(location)
+        location
+      end
+
+      def extract_location_with_stats(line)
+        # Handle formats like: " Canyon Bottom                    Score: 0        Moves: 26"
+        # or " In the enchanted forest                             5:00 AM      Score: 0"
+        parts = line.split(/\s{3,}/)
+        return nil if parts.length < 2
+
+        candidate = parts.first.strip
+        candidate.empty? ? nil : candidate
+      end
+
+      def extract_standalone_location(line)
+        # Handle formats like: " Brig" (location on its own line)
+        candidate = line.strip
+        # Only consider it a location if it doesn't contain stats and isn't an error message
+        if !candidate.match?(/(?:Score|Moves|AM|PM):/i) &&
+            !candidate.match?(/\d+:\d+/) &&
+            !candidate.match?(/[.!?]$/) && # Not a sentence ending with punctuation
+            candidate.length < 50 && # Reasonable location length
+            !candidate.downcase.include?("response") # Not a generic response
+          candidate
+        end
+      end
+
+      def extract_score(text)
+        match = text.match(SCORE_PATTERN)
+        match ? match[1].to_i : nil
+      end
+
+      def extract_moves(text)
+        match = text.match(MOVES_PATTERN)
+        match ? match[1].to_i : nil
+      end
+
+      def extract_time(text)
+        match = text.match(TIME_PATTERN)
+        match ? match[1] : nil
+      end
+
+      def extract_prompt(text)
+        # Extract prompt from end of text (usually ">")
+        lines = text.split("\n")
+        last_line = lines.last&.strip
+        last_line if last_line&.match?(TextPlayer::PROMPT_REGEX)
+      end
+
+      def remove_extracted_data!(text, location, score, moves, time, prompt)
+        # Handle location removal
+        if location
+          lines = text.split("\n")
+          first_line = lines.first&.strip
+
+          if first_line && extract_location_with_stats(first_line)
+            # Replace status line with just the location name
+            lines[0] = location
+            text.replace(lines.join("\n"))
+          end
+        end
+
+        # Remove patterns for extracted data
+        text.gsub!(SCORE_PATTERN, "") if score
+        text.gsub!(MOVES_PATTERN, "") if moves
+        text.gsub!(TIME_PATTERN, "") if time
+
+        # Remove prompt if we extracted it
+        if prompt
+          lines = text.split("\n")
+          if lines.last&.strip == prompt
+            lines.pop
+            text.replace(lines.join("\n"))
+          end
+        end
+      end
+
+      def final_cleanup(text)
+        # Clean up excessive whitespace but preserve paragraph structure
+        # Remove more than 2 consecutive newlines (preserve paragraph breaks)
+        text.gsub!(/\n{3,}/, "\n\n")
+        # Remove lines that are only whitespace
+        text.gsub!(/^\s+$/m, "")
+        # Clean up any trailing/leading whitespace on lines
+        text.gsub!(/[ \t]+$/, "")
+
+        text.strip
+      end
+
+      def valid_location?(location)
+        location.length.positive? &&
+          !location.start_with?("I don't ") &&
+          !location.start_with?("I can't ") &&
+          !location.start_with?("What do you ") &&
+          !location.start_with?("You're ") &&
+          !location.start_with?("You ") &&
+          !location.start_with?("That's not ") &&
+          !location.start_with?("I beg your pardon")
+      end
+    end
+  end
+end

data/lib/text_player/formatters/json.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "data"
+
+module TextPlayer
+  module Formatters
+    # JSON formatter - returns JSON string of structured data
+    class Json < Data
+      def to_s
+        JSON.generate(to_h)
+      end
+    end
+  end
+end

data/lib/text_player/formatters/shell.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module TextPlayer
+  module Formatters
+    # Shell formatter - interactive presentation with prompts and colors
+    class Shell < Base
+      def to_s
+        if command_result.action_command?
+          format_game_output
+        else
+          format_system_feedback
+        end
+      end
+
+      def to_h
+        super.merge(
+          formatted_output: to_s
+        )
+      end
+
+      def write(stream)
+        if command_result.action_command?
+          content, prompt = extract_prompt(display_content)
+          stream.write(content)
+          if prompt
+            color = command_result.success? ? "\e[32m" : "\e[31m"
+            stream.write("#{color}#{prompt}\e[0m")
+          end
+        else
+          stream.write(to_s)
+        end
+      end
+
+      private
+
+      def format_system_feedback
+        return command_result.raw_output if %i[start score].include?(command_result.operation)
+
+        prefix = command_result.success? ? "\e[32m✓\e[0m" : "\e[31m✗\e[0m"
+        feedback = "#{prefix} #{command_result.operation.upcase}: #{command_result.message}"
+
+        # Add details if present
+        if command_result.details.any?
+          detail_lines = command_result.details.map { |k, v| "  #{k}: #{v}" }
+          feedback += "\n#{detail_lines.join("\n")}"
+        end
+
+        feedback
+      end
+
+      def format_game_output
+        display_content
+      end
+
+      def display_content
+        command_result.message || command_result.raw_output
+      end
+
+      def extract_prompt(content)
+        # Look for prompt at the end (> or similar)
+        # Match: content + optional newlines + > + optional spaces
+        if TextPlayer::PROMPT_REGEX.match?(content)
+          content = content.gsub(TextPlayer::PROMPT_REGEX, "").rstrip
+          [content + "\n\n", "> "]
+        else
+          [content, nil]
+        end
+      end
+    end
+  end
+end

data/lib/text_player/formatters/text.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module TextPlayer
+  module Formatters
+    # Plain text formatter - returns raw output
+    class Text < Base
+      def to_s
+        content = command_result.message || command_result.raw_output
+        content = remove_prompt(content)
+        "#{content}\n\n"
+      end
+
+      private
+
+      def remove_prompt(content)
+        content.gsub(TextPlayer::PROMPT_REGEX, "").rstrip
+      end
+    end
+  end
+end

data/lib/text_player/formatters.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "formatters/base"
+require_relative "formatters/text"
+require_relative "formatters/data"
+require_relative "formatters/json"
+require_relative "formatters/shell"
+
+module TextPlayer
+  # UI Formatters - Stream-based output handling for different interfaces
+  module Formatters
+    def self.by_name(name)
+      case name
+      when :data then Data
+      when :json then Json
+      when :shell then Shell
+      else Text
+      end
+    end
+
+    def self.create(name, command_result)
+      by_name(name).new(command_result)
+    end
+  end
+end

data/lib/text_player/gamefile.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module TextPlayer
+  # Gamefile - A game file and its name
+  Gamefile = Data.define(:name, :path) do
+    def self.from_input(input)
+      if input.include?("/")
+        path = Pathname.new(input)
+        new(name: path.basename.to_s, path:)
+      else # must be a simple game name
+        matches = TextPlayer::GAME_DIR.glob("#{input}.*")
+
+        if matches.size == 1
+          path = matches.first
+          new(name: path.basename.to_s, path:)
+        else
+          names = matches.map { |m| m.basename }
+          raise ArgumentError, "Multiple games found for '#{input}':\n#{names.join("\n")}"
+        end
+      end
+    end
+
+    def initialize(name:, path:)
+      super(name: name.to_s, path: Pathname.new(path))
+    end
+
+    def exist? = path.exist?
+
+    def full_path = path.expand_path.to_s
+  end
+end

data/lib/text_player/savefile.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TextPlayer
+  # Utilities for saving and restoring game state
+  Savefile = Data.define(:game_name, :slot) do
+    def initialize(game_name: nil, slot: nil)
+      slot = slot.to_s.strip
+      slot = TextPlayer::AUTO_SAVE_SLOT if slot.empty?
+      super
+    end
+
+    def filename
+      basename = [game_name, slot].compact.join("_")
+      "saves/#{basename}.qzl"
+    end
+
+    def exist?
+      File.exist?(filename)
+    end
+
+    def delete
+      File.delete(filename)
+    end
+  end
+end

data/lib/text_player/session.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module TextPlayer
+  # Mid-level: Manages game session lifecycle and output formatting
+  class Session
+    def initialize(gamefile, dfrotz: nil)
+      @gamefile = gamefile
+      @game = Dfrotz.new(gamefile.full_path, dfrotz:)
+      @started = false
+      @interrupt_count = 0
+    end
+
+    def run(&)
+      result = start
+      while running?
+        command = yield result
+        break if command.nil?
+
+        result = call(command)
+      end
+    end
+
+    def start
+      return @start_result if @started
+
+      setup_interrupt_handling
+      @game.start
+      @started = true
+
+      start_command = Commands::Start.new
+      @start_result = execute_command(start_command)
+    end
+
+    def running?
+      @started && @game.running?
+    end
+
+    # We intentionally intercept certain commands.
+    # Because the intention of this library is automated play, allowing an agent
+    # to save to any file path on the system is a security risk at worst, and
+    # a nuisance at best.
+    #
+    # We automatically save to "autosave" when the game is quit.
+    #
+    # Quit is also intercepted to make sure we shut down the game cleanly.
+    def call(cmd)
+      command = Commands.create(cmd, game_name: @gamefile.name)
+      execute_command(command)
+    end
+
+    def score
+      command = Commands::Score.new
+      execute_command(command)
+    end
+
+    def save(slot = nil)
+      command = Commands::Save.new(save: Save.new(game_name: @gamefile.name, slot:))
+      execute_command(command)
+    end
+
+    def restore(slot = nil)
+      command = Commands::Restore.new(save: Save.new(game_name: @gamefile.name, slot:))
+      execute_command(command)
+    end
+
+    def quit
+      command = Commands::Quit.new
+      execute_command(command)
+    end
+
+    private
+
+    def execute_command(command)
+      if running?
+        command.execute(@game)
+      else
+        CommandResult.new(
+          input: command.input,
+          operation: :error,
+          success: false,
+          message: "Game not running"
+        )
+      end
+    end
+
+    def setup_interrupt_handling
+      Signal.trap("INT") do
+        @interrupt_count += 1
+        if @interrupt_count == 1
+          warn "\n\nInterrupt received - quitting game gracefully..."
+          quit if running?
+
+          exit(0)
+        else
+          @game.terminate
+          exit(1)
+        end
+      end
+    end
+  end
+end

data/lib/text_player/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TextPlayer
+  VERSION = "0.1.0"
+end

data/lib/text_player.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require_relative "text_player/version"
+require_relative "text_player/gamefile"
+require_relative "text_player/dfrotz"
+require_relative "text_player/formatters"
+require_relative "text_player/commands"
+require_relative "text_player/savefile"
+require_relative "text_player/session"
+
+module TextPlayer
+  class Error < StandardError; end
+
+  AUTO_SAVE_SLOT = "autosave"
+  FILENAME_PROMPT_REGEX = /Please enter a filename \[.*\]: /
+  PROMPT_REGEX = /^>\s*$/
+  SCORE_REGEX = /([0-9]+) ?(?:\(total [points ]*[out ]*of [a mxiuof]*[a posible]*([0-9]+)\))?/i
+  GAME_DIR = Pathname.new(__dir__).join("../games")
+  FAILURE_PATTERNS = [
+    /I don't understand/i,
+    /I don't know/i,
+    /You can't/i,
+    /You're not/i,
+    /I can't see/i,
+    /That doesn't make sense/i,
+    /That's not a verb I recognize/i,
+    /What do you want to/i,
+    /You don't see/i,
+    /There is no/i,
+    /I don't see/i,
+    /I beg your pardon/i
+  ].freeze
+end

data/sig/text_player.rbs

@@ -0,0 +1,4 @@
+module TextPlayer
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: text_player
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Cardiff Emde
+- Martin Emde
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ruby gem for playing Zork and other text-based adventure games that provides
+  a programmatic interface for interacting with the game.
+email:
+- cardiff.emde@gmail.com
+- me@martinemde.com
+executables:
+- text_player
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/text_player
+- lib/text_player.rb
+- lib/text_player/cli.rb
+- lib/text_player/command_result.rb
+- lib/text_player/commands.rb
+- lib/text_player/commands/action.rb
+- lib/text_player/commands/quit.rb
+- lib/text_player/commands/restore.rb
+- lib/text_player/commands/save.rb
+- lib/text_player/commands/score.rb
+- lib/text_player/commands/start.rb
+- lib/text_player/dfrotz.rb
+- lib/text_player/formatters.rb
+- lib/text_player/formatters/base.rb
+- lib/text_player/formatters/data.rb
+- lib/text_player/formatters/json.rb
+- lib/text_player/formatters/shell.rb
+- lib/text_player/formatters/text.rb
+- lib/text_player/gamefile.rb
+- lib/text_player/savefile.rb
+- lib/text_player/session.rb
+- lib/text_player/version.rb
+- sig/text_player.rbs
+homepage: https://github.com/martinemde/text_player
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/martinemde/text_player
+  source_code_uri: https://github.com/martinemde/text_player
+  changelog_uri: https://github.com/martinemde/text_player/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Ruby gem for playing Zork and other text-based adventure games
+test_files: []