gamefic 1.7.0 → 2.0.0

data/lib/gamefic/syntax.rb

@@ -1,11 +1,9 @@
 require 'gamefic/command'
 
 module Gamefic
-
   class Syntax
     attr_reader :token_count, :first_word, :verb, :template, :command
-    @@phrase = '([\w\W\s\S]*?)'
-    
+
     def initialize template, command
       words = template.split_words
       @token_count = words.length
@@ -15,8 +13,8 @@ module Gamefic
         @token_count -= 1
         @first_word = ''
       else
-        @verb = command_words[0].to_sym if !command_words[0].nil?
         @first_word = words[0].to_s
+        @verb = command_words[0].to_sym
       end
       @command = command_words.join(' ')
       @template = words.join(' ')
@@ -29,7 +27,7 @@ module Gamefic
           if last_token_is_reg
             next
           else
-            tokens.push @@phrase
+            tokens.push '([\w\W\s\S]*?)'
             last_token_is_reg = true
           end
         else
@@ -50,11 +48,11 @@ module Gamefic
       @replace = subs.join(' ')
       @regexp = Regexp.new("^#{tokens.join(' ')}$", Regexp::IGNORECASE)
     end
-    
+
     # Convert a String into a Command.
     #
     # @param text [String]
-    # @return [Command]
+    # @return [Gamefic::Command]
     def tokenize text
       m = text.match(@regexp)
       return nil if m.nil?
@@ -71,7 +69,11 @@ module Gamefic
       }
       Command.new @verb, arguments
     end
-    
+
+    # Determine if the specified text matches the syntax's expected pattern.
+    #
+    # @param text [String]
+    # @return [Boolean]
     def accept? text
       !text.match(@regexp).nil?
     end
@@ -82,16 +84,16 @@ module Gamefic
     def signature
       [@regexp, @replace]
     end
-    
+
     def ==(other)
       signature == other.signature
     end
-    
+
     # Tokenize an Array of Commands from the specified text.
     #
     # @param text [String] The text to tokenize.
-    # @param syntaxes [Array<Syntax>] The Syntaxes to use.
-    # @return [Array<Command>] The tokenized commands.
+    # @param syntaxes [Array<Gamefic::Syntax>] The Syntaxes to use.
+    # @return [Array<Gamefic::Command>] The tokenized commands.
     def self.tokenize text, syntaxes
       matches = []
       syntaxes.each { |syntax|
@@ -108,5 +110,4 @@ module Gamefic
       matches
     end
   end
-
 end

data/lib/gamefic/version.rb

@@ -1,3 +1,3 @@
-module Gamefic
-  VERSION = '1.7.0'
-end
+module Gamefic
+  VERSION = '2.0.0'
+end

data/lib/gamefic/world.rb

@@ -0,0 +1,16 @@
+module Gamefic
+  module World
+    autoload :Playbook,  'gamefic/world/playbook'
+    autoload :Entities,  'gamefic/world/entities'
+    autoload :Commands,  'gamefic/world/commands'
+    autoload :Callbacks, 'gamefic/world/callbacks'
+    autoload :Scenes,    'gamefic/world/scenes'
+    autoload :Players,   'gamefic/world/players'
+
+    include Entities
+    include Commands
+    include Callbacks
+    include Scenes
+    include Players
+  end
+end

data/lib/gamefic/world/callbacks.rb

@@ -0,0 +1,135 @@
+module Gamefic
+  module World
+    module Callbacks
+      # Add a block to be executed on preparation of every turn.
+      #
+      # @example Increment a turn counter
+      #   turn = 0
+      #   on_ready do
+      #     turn += 1
+      #   end
+      #
+      def on_ready &block
+        ready_procs.push block
+      end
+
+      # Add a block to be executed after the Plot is finished updating a turn.
+      #
+      def on_update &block
+        update_procs.push block
+      end
+
+      # Add a block to be executed for each player at the beginning of a turn.
+      #
+      # @example Tell the player how many turns they've played.
+      #   on_player_ready do |player|
+      #     player[:turns] ||= 0
+      #     if player[:turns] > 0
+      #       player.tell "Turn #{player[:turns]}"
+      #     end
+      #     player[:turns] += 1
+      #   end
+      #
+      # @yieldparam [Gamefic::Actor]
+      def on_player_ready &block
+        player_ready_procs.push block
+      end
+
+      # Add a block to be executed for each player before an update.
+      #
+      # @yieldparam[Gamefic::Actor]
+      def before_player_update &block
+        before_player_update_procs.push block
+      end
+
+      # Add a block to be executed for each player at the end of a turn.
+      #
+      # @yieldparam [Gamefic::Actor]
+      def on_player_update &block
+        player_update_procs.push block
+      end
+
+      # Add a block to be executed at the conclusion of the plot.
+      #
+      # @yieldparam [Gamefic::Actor]
+      def on_player_conclude &block
+        player_conclude_procs.push block
+      end
+
+      def player_conclude_procs
+        @player_conclude_procs ||= []
+      end
+
+      def ready_procs
+        @ready_procs ||= []
+      end
+
+      def update_procs
+        @update_procs ||= []
+      end
+
+      def player_ready_procs
+        @player_ready_procs ||= []
+      end
+
+      def before_player_update_procs
+        @before_player_update_procs ||= []
+      end
+
+      def player_update_procs
+        @player_update_procs ||= []
+      end
+
+      private
+
+      # Execute the on_ready blocks. This method is typically called by the
+      # Plot while beginning a turn.
+      #
+      def call_ready
+        ready_procs.each { |p| p.call }
+      end
+
+      # Execute the on_update blocks. This method is typically called by the
+      # Plot while ending a turn.
+      #
+      def call_update
+        update_procs.each { |p| p.call }
+      end
+
+      # Execute the before_player_update blocks for each player. This method is
+      # typically called by the Plot while updating a turn, immediately before
+      # processing player input.
+      #
+      def call_before_player_update
+        players.each { |player|
+          player.flush
+          before_player_update_procs.each { |block| block.call player }
+        }
+      end
+
+      # Execute the on_player_ready blocks for each player. This method is
+      # typically called by the Plot while beginning a turn, immediately after
+      # the on_ready blocks.
+      #
+      def call_player_ready
+        players.each { |player|
+          unless player.next_scene.nil? || !player.scene.finished?
+            player.cue player.next_scene, **player.next_options
+          end
+          player.cue default_scene if player.scene.nil?
+          player_ready_procs.each { |block| block.call player }
+        }
+      end
+
+      # Execute the on_player_update blocks for each player. This method is
+      # typically called by the Plot while ending a turn, immediately before the
+      # on_ready blocks.
+      #
+      def call_player_update
+        players.each { |player|
+          player_update_procs.each { |block| block.call player }
+        }
+      end
+    end
+  end
+end

data/lib/gamefic/world/commands.rb

@@ -0,0 +1,184 @@
+require 'gamefic/action'
+
+module Gamefic
+  module World
+    module Commands
+      include Gamefic::World::Entities
+
+      # @return [Gamefic::World::Playbook]
+      def playbook
+        @playbook ||= Gamefic::World::Playbook.new
+      end
+
+      # Create an Action that responds to a command.
+      # An Action uses the command argument to identify the imperative verb that
+      # triggers the action.
+      # It can also accept queries to tokenize the remainder of the input and
+      # filter for particular entities or properties.
+      # The block argument contains the code to be executed when the input
+      # matches all of the Action's criteria (i.e., verb and queries).
+      #
+      # @example A simple Action.
+      #   respond :salute do |actor|
+      #     actor.tell "Hello, sir!"
+      #   end
+      #   # The command "salute" will respond "Hello, sir!"
+      #
+      # @example An Action that accepts a Character
+      #   respond :salute, Use.visible(Character) do |actor, character|
+      #     actor.tell "#{The character} returns your salute."
+      #   end
+      #
+      # @param command [Symbol] An imperative verb for the command
+      # @param queries [Array<Query::Base>] Filters for the command's tokens
+      # @yieldparam [Gamefic::Actor]
+      # @return [Class] The resulting Action subclass
+      def respond(command, *queries, &proc)
+        playbook.respond(command, *map_response_args(queries), &proc)
+      end
+      alias action respond
+
+      # Parse a verb and a list of arguments into an action.
+      # This method serves as a shortcut to creating an action with one or more
+      # arguments that identify specific entities.
+      #
+      # @example
+      #   @thing = make Entity, name: 'a thing'
+      #   parse "use", "the thing" do |actor, thing|
+      #     actor.tell "You use it."
+      #   end
+      #
+      # @raise [ArgumentError] if tokens are unrecognized or ambiguous
+      #
+      # @param verb [String, Symbol] The command's verb
+      # @param tokens [Array<String>] The arguments passed to the action
+      # @return [Class] The resulting Action subclass
+      def parse verb, *tokens, &proc
+        query = Query::External.new(entities)
+        params = []
+        tokens.each do |arg|
+          matches = query.resolve(nil, arg)
+          raise ArgumentError, "Unable to resolve token '#{arg}'" if matches.objects.empty?
+          raise ArgumentError, "Ambiguous results for '#{arg}'" if matches.objects.length > 1
+          params.push Query::Family.new(matches.objects[0])
+        end
+        respond(verb.to_sym, *params, &proc)
+      end
+
+      # Tokenize and parse a command to create a new Action subclass.
+      #
+      # @param command [String] The command
+      # @yieldparam [Gamefic::Actor]
+      # @return [Class] the resulting Action subclass
+      def override(command, &proc)
+        cmd = Syntax.tokenize(command, playbook.syntaxes).first
+        raise "Unable to tokenize command '#{command}'" if cmd.nil?
+        parse cmd.verb, *cmd.arguments, &proc
+      end
+
+      # Create a Meta Action that responds to a command.
+      # Meta Actions are very similar to standard Actions, except the Plot
+      # understands them to be commands that operate above and/or outside of the
+      # actual game world. Examples of Meta Actions are commands that report the
+      # player's current score, save and restore saved games, or list the game's
+      # credits.
+      #
+      # @example A simple Meta Action
+      #   meta :credits do |actor|
+      #     actor.tell "This game was written by John Smith."
+      #   end
+      #
+      # @param command [Symbol] An imperative verb for the command
+      # @param queries [Array<Query::Base>] Filters for the command's tokens
+      # @yieldparam [Gamefic::Actor]
+      def meta(command, *queries, &proc)
+        playbook.meta command, *queries, &proc
+      end
+
+      # Declare a dismabiguation response for actions.
+      # The disambigurator is executed when an action expects an argument to
+      # reference a specific entity but its query matched more than one. For
+      # example, "red" might refer to either a red key or a red book.
+      #
+      # If a disambiguator is not defined, the playbook will use its default
+      # implementation.
+      #
+      # @example Tell the player the list of ambiguous entities.
+      #   disambiguate do |actor, entities|
+      #     actor.tell "I don't know which you mean: #{entities.join_or}."
+      #   end
+      #
+      # @yieldparam [Gamefic::Actor]
+      # @yieldparam [Array<Gamefic::Entity>]
+      def disambiguate &block
+        playbook.disambiguate &block
+      end
+
+      # Validate an order before a character can execute its command.
+      #
+      # @yieldparam [Gamefic::Director::Order]
+      def validate &block
+        playbook.validate &block
+      end
+
+      # Create an alternate Syntax for an Action.
+      # The command and its translation can be parameterized.
+      #
+      # @example Create a synonym for the Inventory Action.
+      #   interpret "catalogue", "inventory"
+      #   # The command "catalogue" will be translated to "inventory"
+      #
+      # @example Create a parameterized synonym for the Look Action.
+      #   interpret "scrutinize :entity", "look :entity"
+      #   # The command "scrutinize chair" will be translated to "look chair"
+      #
+      # @param command [String] The format of the original command
+      # @param translation [String] The format of the translated command
+      # @return [Syntax] the Syntax object
+      def interpret command, translation
+        playbook.interpret command, translation
+      end
+      alias xlate interpret
+
+      # Get an Array of available verbs.
+      #
+      # @return [Array<String>]
+      def verbs
+        playbook.verbs.map { |v| v.to_s }.reject{ |v| v.start_with?('_') }
+      end
+
+      # Get an Array of all Actions defined in the Plot.
+      #
+      # @return [Array<Action>]
+      def actions
+        playbook.actions
+      end
+
+      def get_default_query
+        @default_query_class ||= Gamefic::Query::Family
+      end
+
+      def set_default_query cls
+        @default_query_class = cls
+      end
+
+      private
+
+      def map_response_args queries
+        result = []
+        queries.each do |q|
+          if q.is_a?(Regexp)
+            result.push Gamefic::Query::Text.new(q)
+          elsif q.is_a?(Gamefic::Query::Base)
+            result.push q
+          elsif q.is_a?(Gamefic::Element) || (q.is_a?(Class) && q <= Gamefic::Element)
+            result.push get_default_query.new(q)
+          else
+            raise ArgumentError.new("Invalid argument for response: #{q}")
+          end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/gamefic/{plot → world}/entities.rb

@@ -1,6 +1,5 @@
 module Gamefic
-
-  class Plot
+  module World
     module Entities
       # Make a new Entity with the provided properties.
       #
@@ -8,16 +7,16 @@ module Gamefic
       #   chair = make Entity, name: 'red chair'
       #   chair.name #=> 'red chair'
       #
+      # @raise [ArgumentError] if class is not an Entity
+      #
       # @param cls [Class] The Class of the Entity to be created.
       # @param args [Hash] The entity's properties.
-      # @return [Gamefic::Entity]
+      # @!macro [attach] make_entity
+      #   @return [$1]
       def make cls, args = {}, &block
+        raise ArgumentError, "Invalid Entity class" unless cls.is_a?(Class) && cls <= Entity
         ent = cls.new args, &block
-        if ent.kind_of?(Entity) == false
-          raise "Invalid entity class"
-        end
-        p_entities.push ent
-        p_dynamic.push ent if running?
+        entities.push ent
         ent
       end
 
@@ -34,13 +33,21 @@ module Gamefic
         ent
       end
 
+      # Safely remove an entity from a plot.
+      #
+      # If the entity is dynamic (e.g., created after a plot is already
+      # running), it is safe to delete it completely. Otherwise the entity
+      # will still be referenced in the entities array, but its parent will be
+      # set to nil.
+      #
+      # @param [Gamefic::Entity] The entity to remove
       def destroy entity
-        if p_dynamic.include?(entity)
-          p_entities.delete entity
-          p_dynamic.delete entity
-          p_players.delete entity
-        end
         entity.parent = nil
+        index = entities.index(entity)
+        return if index.nil? || index < static_entity_length - 1
+        entities.delete_at index
+        players.delete entity
+        entity.destroy
       end
 
       # Pick an entity based on its description.
@@ -49,7 +56,7 @@ module Gamefic
       #
       # @example Select the Entity that matches the description
       #   red_chair = make Entity, :name => 'red chair'
-      #   blue_chair make Entity, :name => 'blue chair'
+      #   blue_chair = make Entity, :name => 'blue chair'
       #   pick "red chair" #=> red_chair
       #   pick "blue chair" #=> blue_chair
       #   pick "chair" #=> IndexError: description is ambiguous
@@ -57,8 +64,7 @@ module Gamefic
       # @param  description [String] The description of the entity
       # @return [Gamefic::Entity] The entity that matches the description
       def pick(description)
-        query = Gamefic::Query::Base.new
-        result = query.match(description, entities)
+        result = Query::Matches.execute(entities, description)
         if result.objects.length == 0
           raise IndexError.new("Unable to find entity from '#{description}'")
         elsif result.objects.length > 1
@@ -69,32 +75,27 @@ module Gamefic
 
       # Get an array of entities associated with this plot.
       #
-      # @return [Array<Entity>]
+      # @return [Array<Gamefic::Entity>]
       def entities
-        p_entities.clone
+        @entities ||= []
       end
 
       # Get an array of players associated with this plot.
       #
-      # @return [Array<Character>]
+      # @return [Array<Gamefic::Actor>]
       def players
-        p_players.clone
+        @players ||= []
       end
 
       private
 
-      def p_entities
-        @p_entities ||= []
-      end
-
-      def p_players
-        @p_players ||= []
+      def mark_static_entities
+        @static_entity_length ||= entities.length
       end
 
-      def p_dynamic
-        @p_dynamic ||= []
+      def static_entity_length
+        @static_entity_length || 0
       end
     end
   end
-
 end