gruesome 0.0.1

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in grue.gemspec
+gemspec

data/README.md

@@ -0,0 +1,35 @@
+<pre>
+        ▄▄▄▄▄                                              ▄▄▄▄▄                    
+         ▀████▄                                          ▄████▀                     
+           ▀████▄                                      ▄████▀                       
+  ▄▄▄▄▄▄    ██████▄   ▄▄▄   ▄▄▄   ▄▄▄▄▄▄   ▄▄▄▄▄     ▄████▀  ▄▄▄   ▄▄▄   ▄▄▄▄▄▄
+▄████████▄  ██▓▀████▄ ██▓   ███ ▄███████ ▄███████▄ ▄████▀██▄ ████▄████ ▄███████
+██▓    ███  ██▓  ▀███ ██▓   ███ ██▓      ██▓   ███ ███▀  ███ █████████ ██▓
+██▓         ██▓   ███ ██▓   ███ ██▓      ██▓       ██▓   ███ ███▀█▀███ ██▓
+██▓  █████ ████████   ███   ███ ████████ ▀██████▄  ██▓   ███ ██▓   ███ ████████
+██▓  ▀▀███ ▀██▓▀▀▀█▄▄ ███   ███ ███▀▀▀▀▀   ▀▀▀▀███ ██▓   ███ ██▓   ███ ███▀▀▀▀▀
+██▓    ███  ██▓   ███ ██▓   ███ ██▓      ██▓   ███ ██▓   ███ ███   ███ ██▓
+▀████████▀  ██▓   ███ ▀███████▀ ▀███████ ▀███████▀ ▀███████▀ ██▓   ███ ▀███████
+  ▀▀▀▀▀▀    ▀▀▀   ▀▀▀   ▀▀▀▀▀     ▀▀▀▀▀▀   ▀▀▀▀▀     ▀▀▀▀▀   ▀▀▀   ▀▀▀   ▀▀▀▀▀▀
+</pre>
+
+# Gruesome
+
+The Ruby Z-Code Emulator and IF Manager (Currently in progress). It current can
+play version 3 games such as the ZORK trilogy.
+
+## Currently implemented
+
+* Majority of version 3 Z-Machine (Enough to play most games)
+
+## Next
+
+* Versions 4+ (Goal: Run Photopia)
+
+## Overall Goals
+
+There are several goals:
+
+* Emulate the Z-Machine accurately for all versions (text-only first)
+* Provide detailed information to IF designers and programmers
+* Make it easy to pull down and play new and old IF and text adventure games

data/Rakefile

@@ -0,0 +1,15 @@
+require 'rspec/core/rake_task'
+
+# rake spec
+RSpec::Core::RakeTask.new(:spec) do |spec|
+	spec.pattern = 'spec/*/*_spec.rb'
+end
+
+# rake doc
+RSpec::Core::RakeTask.new(:doc) do |spec|
+	spec.pattern = 'spec/*/*_spec.rb'
+	spec.rspec_opts = ['--format documentation']
+end
+
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/bin/gruesome

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+$: << File.dirname(__FILE__) + '/../lib'
+
+require 'gruesome'
+require 'gruesome/cli'
+
+Gruesome::CLI.run
+

data/gruesome.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "gruesome/version"
+
+Gem::Specification.new do |s|
+  s.name        = "gruesome"
+  s.version     = Grue::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Dave Wilkinson"]
+  s.email       = ["wilkie05@gmail.com"]
+  s.homepage    = "http://github.com/wilkie/gruesome"
+  s.summary     = %q{An Interactive Fiction client that can play/read interactive stories}
+  s.description = %q{Reads and executes various interactive fiction technologies and helps easily download new stories from other sources on the Internet.}
+
+  s.rubyforge_project = "gruesome"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rspec"
+
+  s.add_dependency "bit-struct"
+end

data/lib/gruesome/cli.rb

@@ -0,0 +1,70 @@
+require 'optparse'
+
+require_relative '../gruesome'
+require_relative 'machine'
+require_relative 'logo'
+
+module Gruesome
+	class CLI
+		BANNER = <<-USAGE
+		Usage:
+		  gruesome play STORY_FILE
+
+		Description:
+		  The 'play' command will start a session of the story given as STORY_FILE
+
+		Example:
+		  gruesome play zork1.z3
+
+		USAGE
+
+		class << self
+			def parse_options
+				@opts = OptionParser.new do |opts|
+					opts.banner = BANNER.gsub(/^\t{2}/, '')
+
+					opts.separator ''
+					opts.separator 'Options:'
+
+					opts.on('-h', '--help', 'Display this help') do
+						puts opts
+						exit
+					end
+				end
+
+				@opts.parse!
+			end
+
+			def CLI.run
+				begin
+					parse_options
+				rescue OptionParser::InvalidOption => e
+					warn e
+					exit -1
+				end
+
+				def fail
+					puts @opts
+					exit -1
+				end
+
+				if ARGV.empty?
+					fail
+				end
+
+				case ARGV.first
+				when 'play'
+					fail unless ARGV[1]
+
+					Gruesome::Logo.print
+
+					puts
+					puts "--------------------------------------------------------------------------------"
+					puts
+
+					Gruesome::Machine.new(ARGV[1]).execute
+				end
+			end
+		end
+	end
+end

data/lib/gruesome/logo.rb

@@ -0,0 +1,28 @@
+# encoding: utf-8
+#
+# DO NOT REMOVE ABOVE COMMENT! IT IS MAGIC!
+
+module Gruesome
+	module Logo
+		# I'm just making sure this works regardless of the unicode format this
+		# source file is saved as...
+		LOGO = <<ENDLOGO
+        ▄▄▄▄▄                                               ▄▄▄▄▄                       
+         ▀████▄                                           ▄████▀                     
+           ▀████▄                                       ▄████▀                       
+  ▄▄▄▄▄▄    ██████▄   ▄▄▄   ▄▄▄   ▄▄▄▄▄▄   ▄▄▄▄▄▄     ▄████▀  ▄▄▄   ▄▄▄   ▄▄▄▄▄▄
+▄████████▄  ██▓▀████▄ ██▓   ███ ▄███████ ▄████████▄ ▄████▀██▄ ████▄████ ▄███████
+██▓    ███  ██▓  ▀███ ██▓   ███ ██▓      ██▓    ███ ███▀  ███ █████████ ██▓
+██▓         ██▓   ███ ██▓   ███ ██▓      ██▓        ██▓   ███ ███▀█▀███ ██▓
+██▓  █████ ████████   ███   ███ ████████ ▀███████▄  ██▓   ███ ██▓   ███ ████████
+██▓  ▀▀███ ▀██▓▀▀▀█▄▄ ███   ███ ███▀▀▀▀▀   ▀▀▀▀▀███ ██▓   ███ ██▓   ███ ███▀▀▀▀▀
+██▓    ███  ██▓   ███ ██▓   ███ ██▓      ██▓    ███ ██▓   ███ ███   ███ ██▓
+▀████████▀  ██▓   ███ ▀███████▀ ▀███████ ▀████████▀ ▀███████▀ ██▓   ███ ▀███████
+  ▀▀▀▀▀▀    ▀▀▀   ▀▀▀   ▀▀▀▀▀     ▀▀▀▀▀▀   ▀▀▀▀▀▀     ▀▀▀▀▀   ▀▀▀   ▀▀▀   ▀▀▀▀▀▀
+ENDLOGO
+
+		def Logo.print
+			puts LOGO
+		end
+	end
+end

data/lib/gruesome/machine.rb

@@ -0,0 +1,17 @@
+require_relative 'z/machine'
+
+module Gruesome
+	class Machine
+		def initialize(story_file)
+			# Later, detect the type
+			#
+			# For now, assume Z-Machine
+
+			@machine = Z::Machine.new(story_file)
+		end
+
+		def execute
+			@machine.execute
+		end
+	end
+end

data/lib/gruesome/version.rb

@@ -0,0 +1,3 @@
+module Grue
+  VERSION = "0.0.1"
+end

data/lib/gruesome/z/abbreviation_table.rb

@@ -0,0 +1,30 @@
+# The Z-Machine, in order to conserve precious space, often encoded in various
+# strings a codeword that would inject the word given at a particular place in
+# the abbreviation table.
+
+require_relative 'memory'
+require_relative 'header'
+require_relative 'zscii'
+
+module Gruesome
+	module Z
+		class AbbreviationTable
+			def initialize(memory)
+				@memory = memory
+				@header = Header.new(@memory.contents)
+			end
+
+			def lookup(alphabet, index, translation_alphabet)
+				abbrev_index = (32 * (alphabet)) + index
+				addr = @header.abbrev_tbl_addr + abbrev_index*2
+
+				# this will yield a word address, which we multiply by 2
+				# to get into a byte address
+				str_addr = @memory.force_readw(addr)
+				str_addr *= 2
+
+				ZSCII.translate(translation_alphabet, @header.version, @memory.force_readzstr(str_addr)[1], nil)
+			end
+		end
+	end
+end

data/lib/gruesome/z/decoder.rb

@@ -0,0 +1,292 @@
+# The Z-Machine has a RISC-like instruction set with 1 byte opcodes with
+# the exception of several extension opcodes of 2 bytes.
+#
+# The operands are variable length, however, mostly for size constraint reasons.
+#
+# The format:
+#
+# OPCODE :: 1 or 2 bytes 
+# OPCODE_TYPE (opt) :: 1 to 2 bytes, divided into 2-bit fields
+# OPERANDS :: 0 to 8 given, each 1 or 2 bytes, or an unlimited length string
+
+require_relative 'opcode'
+require_relative 'operand_type'
+require_relative 'opcode_class'
+require_relative 'instruction'
+require_relative 'zscii'
+
+module Gruesome
+	module Z
+		
+		# This is the instruction decoder
+		class Decoder
+			def initialize(memory)
+				@memory = memory
+				@instruction_cache = {}
+				@header = Header.new(@memory.contents)
+				@abbreviation_table = AbbreviationTable.new(@memory)
+
+				# For versions 1 and 2, there is a permanent alphabet
+				@alphabet = 0
+			end
+
+			def fetch
+				pc = @memory.program_counter
+				orig_pc = pc
+
+				# Determine type and form of the operand
+				# along with the number of operands
+
+				# read first byte to get opcode
+				opcode = @memory.force_readb(pc)
+				pc = pc + 1
+
+				# opcode form is top 2 bits
+				opcode_form = (opcode >> 6) & 3
+				operand_count = 0
+				operand_types = Array.new(8) { OperandType::OMITTED }
+				operand_values = []
+
+				# SHORT
+				if opcode_form == 2
+					# operand count is determined by bits 4 and 5
+					if ((opcode >> 4) & 3) == 3
+						operand_count = 0
+						opcode_class = OpcodeClass::OP0
+					else
+						operand_count = 1
+						opcode_class = OpcodeClass::OP1
+					end
+
+					operand_types[0] = (opcode >> 4) & 3
+
+					# opcode is given as bottom 4 bits
+					opcode = opcode & 0b1111
+
+				# VARIABLE
+				elsif opcode_form == 3
+					if (opcode & 0b100000) == 0
+						# when bit 5 is clear, there are two operands
+						operand_count = 2
+						opcode_class = OpcodeClass::OP2
+					else
+						# otherwise, there are VAR number
+						operand_count = 8
+						opcode_class = OpcodeClass::VAR
+					end
+
+					# opcode is given as bottom 5 bits
+					opcode = opcode & 0b11111
+
+				# EXTENDED
+				elsif opcode == 190 # extended form
+					opcode_class = OpcodeClass::EXT
+
+					# VAR number
+					operand_count = 8
+
+					# opcode is given as the next byte
+					opcode = @memory.force_readb(pc)
+					pc = pc + 1
+
+				# LONG
+				else 
+
+					# there are always 2 operands
+					operand_count = 2
+					opcode_class = OpcodeClass::OP2
+
+					# bit 6 of opcode is type of operand 1
+					type = opcode & 0b1000000
+					if type == 0 # 0 means small constant
+						type = OperandType::SMALL
+					else # 1 means variable
+						type = OperandType::VARIABLE 
+					end
+					operand_types[0] = type
+
+					# bit 5 of opcode is type of operand 2
+					type = opcode & 0b100000
+					if type == 0 # 0 means small constant
+						type = OperandType::SMALL
+					else # 1 means variable
+						type = OperandType::VARIABLE 
+					end
+					operand_types[1] = type
+
+					# opcode is given as bottom 5 bits
+					opcode = opcode & 0b11111
+				end
+
+				# We need the opcode and opcode_class to be combined
+				opcode = (opcode << 3) | opcode_class
+
+				# convert some moved opcodes
+				if (@header.version <= 4)
+					if opcode == Opcode::CALL_1N
+						opcode = Opcode::NOT
+					end
+				end
+
+				# handle VAR operands
+				if opcode_form == 3 or opcode_class == OpcodeClass::VAR or opcode_class == OpcodeClass::EXT
+					# each type for the operands is given by reading
+					# the next 1 or 2 bytes.
+					#
+					# This byte contains 4 type descriptions where
+					# the most significant 2 bits are the 0th type
+					# and the least 2 are the 3rd type
+					#
+					# If a type is deemed omitted, every subsequent
+					# type must also be omitted
+
+					byte = @memory.force_readb(pc)
+					pc = pc + 1
+
+					operand_types[0] = (byte >> 6) & 3
+					operand_types[1] = (byte >> 4) & 3
+					operand_types[2] = (byte >> 2) & 3
+					operand_types[3] = byte & 3
+
+					# Get the number of operands
+					idx = -1
+					first_omitted = -1
+					operand_count = operand_types.inject(0) do |result, element|
+						idx = idx + 1
+						if element == OperandType::OMITTED
+							first_omitted = idx
+							result
+						elsif first_omitted == -1
+							result + 1
+						else
+							# Error, OMITTED was found, but another type
+							# was defined as not omitted
+							# We will ignore
+							result
+						end
+					end
+
+					if opcode == Opcode::CALL_VS2 or opcode == Opcode::CALL_VN2
+						# Certain opcodes can have up to 8 operands!
+						# These are given by a second byte
+						byte = @memory.force_readb(pc)
+						pc = pc + 1
+
+						operand_types[4] = (byte >> 6) & 3
+						operand_types[5] = (byte >> 4) & 3
+						operand_types[6] = (byte >> 2) & 3
+						operand_types[7] = byte & 3
+
+						# update operand_count once more
+						operand_count = operand_types.inject(operand_count) do |result, element|
+							idx = idx + 1
+							if element == OperandType::OMITTED
+								first_omitted = idx
+								result
+							elsif first_omitted == -1
+								result + 1
+							else
+								# Error, OMITTED was found, but another type
+								# was defined as not omitted
+								# We will ignore
+								result
+							end
+						end
+					end
+				end
+
+				# Retrieve the operand values
+				operand_types = operand_types.slice(0, operand_count)
+				operand_types.each do |i|
+					if i == OperandType::SMALL or i == OperandType::VARIABLE
+						operand_values << @memory.force_readb(pc)
+						pc = pc + 1
+					elsif i == OperandType::LARGE 
+						operand_values << @memory.force_readw(pc)
+						pc = pc + 2
+					end
+				end
+
+				# If the opcode stores, we need to pull the next byte to get the
+				# destination of the result
+				destination = nil
+				if Opcode.is_store?(opcode, @header.version)
+					destination = @memory.force_readb(pc)
+					pc = pc + 1
+				end
+
+				# The opcode may indicate that it's argument is a string literal
+				if Opcode.has_string?(opcode, @header.version)
+					str = ""
+					# Now we read in 2-byte words until the most significant bit is set
+					# We unencode them from the ZSCII encoding
+
+					continue = true
+
+					alphabet = 0
+					if (@header.version < 3)
+						alphabet = @alphabet
+					end
+
+					result = @memory.force_readzstr(pc)
+					pc = pc + result[0]
+					chrs = result[1]
+
+					# convert the string from ZSCII to UTF8
+					operand_types << OperandType::STRING
+					operand_values << ZSCII.translate(@alphabet, @header.version, chrs, @abbreviation_table)
+
+					# determine shift locks
+					if (@header.version < 3)
+						@alphabet = ZSCII.eval_alphabet(@alphabet, @header.version, chrs, @abbreviation_table)
+					end
+				end
+
+				# If the opcode is a branch, we need to pull the offset info
+				branch_destination = nil
+				branch_condition = false
+				if Opcode.is_branch?(opcode, @header.version)
+					branch_offset = @memory.force_readb(pc)
+					pc = pc + 1
+
+					# if bit 7 is set, the branch occurs on a true condition
+					# false otherwise
+					if (branch_offset & 0b10000000) != 0
+						branch_condition = true
+					end
+
+					# if bit 6 is clear, the branch offset is 14 bits (6 from first byte 
+					# and the 8 from the next byte) This is _signed_
+					if (branch_offset & 0b01000000) == 0
+						branch_offset = branch_offset & 0b111111
+						negative = (branch_offset & 0b100000) > 0
+						branch_offset = branch_offset << 8
+						branch_offset = branch_offset | @memory.force_readb(pc)
+						if (negative)
+							branch_offset = -(16384 - branch_offset)
+						end
+						pc = pc + 1
+					else # otherwise, the offset is simply the remaining 6 bits _unsigned_
+						branch_offset = branch_offset & 0b111111
+					end
+
+					# calculate actual destination from the offset
+					if branch_offset == 0 or branch_offset == 1
+						# a return
+						branch_destination = branch_offset
+					else
+						branch_destination = pc + branch_offset - 2
+					end
+				end
+
+				# Create an Instruction class to hold this metadata
+				inst = Instruction.new(opcode, operand_types, operand_values, destination, branch_destination, branch_condition, pc - orig_pc)
+
+				# Store in the instruction cache
+				@instruction_cache[orig_pc] = inst
+
+				inst
+			end
+		end
+	end
+end

data/lib/gruesome/z/dictionary.rb

@@ -0,0 +1,156 @@
+# The Z-Machine has a dictionary which it uses to parse input and
+# perform lexical analysis.
+
+# The header is located at the address given in the Header at
+# address 0x08
+
+require_relative 'memory'
+require_relative 'header'
+require_relative 'zscii'
+
+module Gruesome
+	module Z
+		class Dictionary
+			def initialize(memory)
+				@memory = memory
+				@header = Header.new(@memory.contents)
+
+				@abbreviation_table = AbbreviationTable.new(@memory)
+
+				@lookup_cache = {}
+			end
+
+			def address
+				@header.dictionary_addr
+			end
+
+			def address_of_entries
+				addr = self.address
+				num_input_codes = @memory.force_readb(addr)
+				addr += 1
+				addr += num_input_codes
+				addr += 3
+
+				addr
+			end
+
+			def entry_length
+				addr = self.address_of_entries - 3
+				return @memory.force_readb(addr)
+			end
+
+			def number_of_words
+				addr = self.address_of_entries - 2
+				return @memory.force_readw(addr)
+			end
+
+			def word_address(index)
+				addr = address_of_entries
+				addr += entry_length * index
+
+				return addr
+			end
+
+			def word(index)
+				addr = word_address(index)
+
+				codes = nil
+
+				if @header.version <= 3
+					codes = @memory.force_readzstr(addr, 4)[1]
+				else
+					codes = @memory.force_readzstr(addr, 6)[1]
+				end
+
+				str = ZSCII.translate(0, @header.version, codes, @abbreviation_table)
+				@lookup_cache[str] = index
+				return str
+			end
+
+			def lookup_word(token)
+				if token.length > 6 and @header.version <= 3
+					token = token[0..5]
+				elsif token.length > 9
+					token = token[0..8]
+				end
+				cached_index = @lookup_cache[token]
+				if cached_index != nil
+					if self.word(cached_index) == token
+						return cached_index
+					end
+				end
+
+				number_of_words.times do |i|
+					if word(i) == token
+						cached_index = i
+						break
+					end
+				end
+				
+				cached_index
+			end
+
+			def word_separators
+				addr = self.address
+
+				# the number of word separators
+				num_input_codes = @memory.force_readb(addr)
+				addr += 1
+
+				codes = []
+				num_input_codes.times do
+					codes << @memory.force_readb(addr)
+					addr += 1
+				end
+
+				codes = codes.map do |i|
+					ZSCII.translate_Zchar(i)
+				end
+
+				return codes
+			end
+
+			def tokenize(line)
+				orig_line = line
+
+				# I. ensure that word separators are surrounded by spaces
+				self.word_separators.each do |sep|
+					line = line.gsub(sep, " " + sep + " ")
+				end
+
+				# II. break up the line into words delimited by spaces
+				tokens = line.split(' ')
+
+				line = orig_line
+				last_pos = 0
+				ret = tokens.map do |token|
+					index = line.index(token)
+					line = line[index+token.size..-1]
+
+					index = index + last_pos
+					last_pos = index + token.size
+
+					index
+					{ :position => index, :string => token }
+				end
+				
+				ret
+			end
+
+			def parse(tokens)
+				ret = []
+				tokens.each do |token|
+					index = lookup_word(token[:string])
+					if index != nil
+						addr = word_address(index)
+					else
+						addr = 0
+					end
+					ret << { :size => token[:string].size, :address => addr, :position => token[:position] }
+				end
+
+				ret
+			end
+		end
+	end
+end