gamefic 1.6.0 → 2.0.3

data/lib/gamefic/subplot.rb

@@ -1,36 +1,37 @@
 require 'gamefic/plot'
 
 module Gamefic
+  class Subplot #< Container
+    include World
+    include Scriptable
+    include Gamefic::Serialize
+    # @!parse extend Scriptable::ClassMethods
 
-  class Subplot
+    # @return [Gamefic::Plot]
     attr_reader :plot
-    attr_writer :denied_message
 
-    include Plot::Theater
-    include Plot::Entities
-    include Plot::Commands
-    include Plot::Callbacks
-    include Plot::Scenes
-    include Plot::Articles
-
-    class << self
-      attr_reader :start_proc
-
-      protected
-
-      def on_start &block
-        @start_proc = block
-      end
-    end
-
-    def initialize plot, introduce: nil, next_cue: nil, busy_cue: nil
+    # @param plot [Gamefic::Plot]
+    # @param introduce [Gamefic::Actor, nil]
+    # @param next_cue [Class<Gamefic::Scene::Base>, nil]
+    # @param more [Hash]
+    def initialize plot, introduce: nil, next_cue: nil, **more
       @plot = plot
       @next_cue = next_cue
-      @busy_cue = busy_cue
       @concluded = false
-      stage &self.class.start_proc unless self.class.start_proc.nil?
+      @more = more
+      configure more
+      run_scripts
       playbook.freeze
       self.introduce introduce unless introduce.nil?
+      @static = [self] + scene_classes + entities
+    end
+
+    def static
+      plot.static
+    end
+
+    def players
+      @players ||= []
     end
 
     def subplot
@@ -46,44 +47,31 @@ module Gamefic
     end
 
     def playbook
-      @playbook ||= plot.playbook.dup
-    end
-
-    # HACK: Always assume subplots are running for the sake of entity destruction
-    def running?
-      true
-    end
-
-    def denied_message
-      @denied_message ||= 'You are already involved in another subplot.'
+      @playbook ||= Gamefic::Plot::Playbook.new
     end
 
-    def introduce player
-      if plot.in_subplot?(player)
-        if @busy_cue.nil?
-          player.tell denied_message
-        else
-          player.cue @busy_cue
-        end
-      else
-        super
-      end
+    def cast cls, args = {}, &block
+      ent = super
+      ent.playbooks.push plot.playbook unless ent.playbooks.include?(plot.playbook)
+      ent
     end
 
     def exeunt player
-      player.playbook = plot.playbook
+      player_conclude_procs.each { |block| block.call player }
+      player.playbooks.delete playbook
       player.cue (@next_cue || default_scene)
-      p_players.delete player
+      players.delete player
     end
 
     def conclude
       @concluded = true
-      entities.each { |e|
-        destroy e
-      }
-      players.each { |p|
-        exeunt p
-      }
+      # Players needed to exit first in case any player_conclude procs need to
+      # interact with the subplot's entities.
+      players.each { |p| exeunt p }
+      # @todo I'm not sure why rejecting nils is necessary here. It's only an
+      #   issue in Opal.
+      entities.reject(&:nil?).each { |e| destroy e }
+      # plot.static.remove(scene_classes + entities)
     end
 
     def concluded?
@@ -91,6 +79,9 @@ module Gamefic
     end
 
     def ready
+      # @todo We might not want to conclude subplots without players. There
+      #   might be cases where a subplot gets created with the intention of
+      #   introducing players in a later turn.
       conclude if players.empty?
       return if concluded?
       playbook.freeze
@@ -102,6 +93,11 @@ module Gamefic
       call_player_update
       call_update
     end
-  end
 
+    # Subclasses can override this method to handle additional configuration
+    # options.
+    #
+    def configure more
+    end
+  end
 end

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,17 @@ module Gamefic
     def signature
       [@regexp, @replace]
     end
-    
+
     def ==(other)
+      return false unless other.is_a?(Syntax)
       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 +111,4 @@ module Gamefic
       matches
     end
   end
-
 end

data/lib/gamefic/version.rb

@@ -1,3 +1,3 @@
-module Gamefic
-  VERSION = '1.6.0'
-end
+module Gamefic
+  VERSION = '2.0.3'
+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