gamefic 1.7.0 → 2.1.0

data/lib/gamefic/version.rb

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

data/lib/gamefic/world.rb

@@ -0,0 +1,18 @@
+module Gamefic
+  # A collection of classes and modules related to generating a world model.
+  #
+  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 disambiguator 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(&: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
+
+      # @param queries [Array]
+      # @return [Array<Query::Base>]
+      def map_response_args queries
+        queries.map do |q|
+          if q.is_a?(Regexp)
+            Gamefic::Query::Text.new(q)
+          elsif q.is_a?(Gamefic::Query::Base)
+            q
+          elsif q.is_a?(Gamefic::Element) || (q.is_a?(Class) && q <= Gamefic::Element)
+            get_default_query.new(q)
+          else
+            raise ArgumentError.new("Invalid argument for response: #{q}")
+          end
+        end
+      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,28 @@ 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
+
+        # @todo It might make sense to destroy the entity completely now. It
+        #   will still have a reference in the index, but that shouldn't impact
+        #   the current state of the plot.
+        return if static.include?(entity)
+        entities.delete entity
+        players.delete entity
       end
 
       # Pick an entity based on its description.
@@ -49,7 +63,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 +71,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 +82,17 @@ 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
-      end
-
-      private
-
-      def p_entities
-        @p_entities ||= []
-      end
-
-      def p_players
-        @p_players ||= []
-      end
-
-      def p_dynamic
-        @p_dynamic ||= []
+        @players ||= []
       end
     end
   end
-
 end