gamefic 1.7.0 → 2.1.0

data/lib/gamefic/query/tree.rb

@@ -0,0 +1,17 @@
+module Gamefic
+  module Query
+    # Query to retrieve all of the subject's ancestors, siblings, and descendants.
+    #
+    class Tree < Family
+      def context_from(subject)
+        result = super
+        parent = subject.parent
+        until parent.nil?
+          result.unshift parent
+          parent = parent.parent
+        end
+        result
+      end
+    end
+  end
+end

data/lib/gamefic/scene.rb

@@ -1,5 +1,4 @@
 module Gamefic
-
   module Scene
     autoload :Base, 'gamefic/scene/base'
     autoload :Custom, 'gamefic/scene/custom'
@@ -10,5 +9,4 @@ module Gamefic
     autoload :MultipleScene, 'gamefic/scene/multiple_scene'
     autoload :YesOrNo, 'gamefic/scene/yes_or_no'
   end
-
 end

data/lib/gamefic/scene/activity.rb

@@ -1,26 +1,24 @@
-module Gamefic
-
-  # Active Scenes handle the default command prompt, where input is parsed
-  # into an Action performed by the Character. This is the default scene in
-  # a Plot.
-  #
-  class Scene::Activity < Scene::Base
-    def post_initialize
-      self.type = 'Activity'
-    end
-
-    def finish
-      super
-      o = nil
-      o = actor.perform input.strip unless input.to_s.strip.empty?
-      actor.performed o
-    end
-
-    class << self
-      def type
-        'Activity'
-      end
-    end
-  end
-  
-end
+module Gamefic
+  # Active Scenes handle the default command prompt, where input is parsed
+  # into an Action performed by the Character. This is the default scene in
+  # a Plot.
+  #
+  class Scene::Activity < Scene::Base
+    def post_initialize
+      self.type = 'Activity'
+    end
+
+    def finish
+      super
+      o = nil
+      o = actor.perform input.strip unless input.to_s.strip.empty?
+      actor.performed o
+    end
+
+    class << self
+      def type
+        'Activity'
+      end
+    end
+  end
+end

data/lib/gamefic/scene/base.rb

@@ -1,61 +1,105 @@
 module Gamefic
-  
-  # The Base Scene is not intended for instantiation. Other Scene classes
-  # should inherit from it.
+  # An abstract class for building different types of scenes. It can be
+  # extended either through concrete subclasses or by creating anonymous
+  # subclasses through a scene helper method like
+  # `Gamefic::World::Scenes#custom`.
   #
   class Scene::Base
+    include Gamefic::Serialize
+    extend Gamefic::Serialize
+
+    # The scene's primary actor.
+    #
+    # @return [Gamefic::Actor]
     attr_reader :actor
+
+    # A human-readable string identifying the type of scene.
+    #
+    # @return [String]
     attr_writer :type
+
+    # The text to display when requesting input.
+    #
+    # @return [String]
     attr_writer :prompt
+
+    # The input received from the actor.
+    #
+    # @return [String]
     attr_reader :input
 
-    def initialize actor
+    # @return [Hash{Symbol => Object}]
+    attr_reader :data
+
+    def initialize actor, **data
       @actor = actor
+      @data = data
       post_initialize
     end
 
+    # A shortcut for the #data hash.
+    #
+    # @param key [Symbol]
+    # @return [Object]
+    def [] key
+      data[key]
+    end
+
     def post_initialize
     end
 
+    # Set a proc to be executed at the end of the scene.
+    #
     def on_finish &block
       @finish_block = block
     end
 
+    # Update the scene.
+    #
     def update
       @input = actor.queue.shift
       finish
     end
 
+    # Start the scene.
+    #
     def start
       self.class.start_block.call @actor, self unless self.class.start_block.nil?
+      @actor.entered self if tracked?
     end
 
+    # Finish the scene.
+    #
     def finish
       @finish_block.call @actor, self unless @finish_block.nil?
       @finished = true
     end
 
+    # Determine whether the scene's execution is finished.
+    #
+    # @return [Boolean]
     def finished?
       @finished ||= false
     end
 
-    def flush
-      @state.clear
-    end
-
+    # Get a hash that describes the current state of the scene.
+    #
+    # @return [Hash]
     def state
       {
         scene: type, prompt: prompt
       }
     end
 
+    # @yieldparam [Class<Gamefic::Actor>]
+    # @return [Class<Gamefic::Scene::Base>]
     def self.subclass &block
       c = Class.new(self) do
         on_start &block
       end
       c
     end
-    
+
     # Get the prompt to be displayed to the user when accepting input.
     #
     # @return [String] The text to be displayed.
@@ -63,19 +107,36 @@ module Gamefic
       @prompt ||= '>'
     end
 
+    # Get a String that describes the type of scene.
+    #
+    # @return [String]
     def type
       @type ||= 'Scene'
     end
 
+    # @yieldparam [Class<Gamefic::Scene::Base>]
     def self.on_start &block
       @start_block = block
     end
 
+    def tracked?
+      self.class.tracked?
+    end
+
+    def tracked= bool
+      self.class.tracked = bool
+    end
+
     class << self
+      attr_writer :tracked
+
       def start_block
         @start_block
       end
+
+      def tracked?
+        @tracked ||= false
+      end
     end
   end
-
 end

data/lib/gamefic/scene/conclusion.rb

@@ -1,11 +1,9 @@
 module Gamefic
-
   # A Conclusion ends the Plot (or the character's participation in it).
   #
-  class Scene::Conclusion < Scene::Custom
+  class Scene::Conclusion < Scene::Base
     def type
       @type ||= 'Conclusion'
     end
   end
-  
 end

data/lib/gamefic/scene/multiple_choice.rb

@@ -1,5 +1,4 @@
 module Gamefic
-
   # Provide a list of options and process the selection in the scene's finish
   # block. After the scene is finished, the :active scene will be cued unless
   # some other scene has already been prepared or cued.
@@ -7,10 +6,22 @@ module Gamefic
   # The finish block's input parameter receives a MultipleChoice::Input object
   # instead of a String.
   #
-  class Scene::MultipleChoice < Scene::Custom
+  class Scene::MultipleChoice < Scene::Base
+    # The zero-based index of the selected option.
+    #
+    # @return [Integer]
     attr_reader :index
+
+    # The one-based index of the selected option.
+    #
+    # @return [Integer]
     attr_reader :number
+
+    # The full text of the selected option.
+    #
+    # @return [String]
     attr_reader :selection
+
     attr_writer :invalid_message
 
     def post_initialize
@@ -22,16 +33,21 @@ module Gamefic
       get_choice
       if selection.nil?
         actor.tell invalid_message
-        tell_options
       else
         super
       end
     end
 
+    # The array of available options.
+    #
+    # @return [Array<String>]
     def options
       @options ||= []
     end
 
+    # The text to display when an invalid selection is received.
+    #
+    # @return [String]
     def invalid_message
       @invalid_message ||= 'That is not a valid choice.'
     end
@@ -60,16 +76,5 @@ module Gamefic
         }
       end
     end
-
-    def tell_options
-      list = '<ol class="multiple_choice">'
-      options.each { |o|
-        list += "<li><a href=\"#\" rel=\"gamefic\" data-command=\"#{o}\">#{o}</a></li>"
-      }
-      list += "</ol>"
-      actor.tell list
-    end
-    
   end
-
 end

data/lib/gamefic/scene/multiple_scene.rb

@@ -1,20 +1,29 @@
-module Gamefic
-
-  class Scene::MultipleScene < Scene::MultipleChoice
-    def option_map
-      @option_map ||= {}
-    end
-
-    def map option, scene
-      options.push option
-      option_map[option] = scene
-    end
-
-    def finish
-      get_choice
-      unless selection.nil?
-        actor.prepare option_map[selection]
-      end
-    end
-  end
-end
+module Gamefic
+  class Scene::MultipleScene < Scene::MultipleChoice
+    def option_map
+      @option_map ||= {}
+    end
+
+    # @param option [String]
+    # @param scene [Class<Gamefic::Scene::Base>]
+    def map option, scene
+      options.push option
+      option_map[option] = scene
+    end
+
+    def finish
+      get_choice
+      unless selection.nil?
+        actor.prepare option_map[selection]
+      end
+    end
+
+    def state
+      entered = {}
+      option_map.each_pair do |k, v|
+        entered[k] = actor.entered?(v)
+      end
+      super.merge entered: entered
+    end
+  end
+end

data/lib/gamefic/scene/pause.rb

@@ -1,12 +1,17 @@
 module Gamefic
-
   # Pause for user input.
   #
-  class Scene::Pause < Scene::Custom
+  class Scene::Pause < Scene::Base
     def post_initialize
       self.type = 'Pause'
       self.prompt = 'Press enter to continue...'
     end
+
+    class << self
+      def tracked?
+        @tracked = true if @tracked.nil?
+        @tracked
+      end
+    end
   end
-  
 end

data/lib/gamefic/scene/yes_or_no.rb

@@ -1,32 +1,41 @@
 module Gamefic
-
   # Prompt the user to answer "yes" or "no". The scene will accept variations
   # like "YES" or "n" and normalize the answer to "yes" or "no" in the finish
   # block. After the scene is finished, the :active scene will be cued if no
   # other scene has been prepared or cued.
   #
-  class Scene::YesOrNo < Scene::Custom
+  class Scene::YesOrNo < Scene::Base
+    attr_writer :invalid_message
+
     def post_initialize
       self.type = 'YesOrNo'
-      self.prompt = 'Yes or No?'
+      self.prompt = 'Yes or No:'
     end
 
+    # True if the actor's answer is Yes.
+    # Any answer beginning with letter Y is considered Yes.
+    #
+    # @return [Boolean]
     def yes?
-      input.to_s[0,1].downcase == 'y'
+      input.to_s[0,1].downcase == 'y' or input.to_i == 1
     end
 
+    # True if the actor's answer is No.
+    # Any answer beginning with letter N is considered No.
+    #
+    # @return [Boolean]
     def no?
-      input.to_s[0,1].downcase == 'n'
+      input.to_s[0,1].downcase == 'n' or input.to_i == 2
     end
 
+    # The message sent to the user for an invalid answer, i.e., the input
+    # could not be resolved to either Yes or No.
+    #
+    # @return [String]
     def invalid_message
       @invalid_message ||= 'Please enter Yes or No.'
     end
 
-    def prompt
-      @prompt ||= 'Yes or No?'
-    end
-
     def finish
       if yes? or no?
         super
@@ -34,6 +43,9 @@ module Gamefic
         actor.tell invalid_message
       end
     end
-  end
 
+    def state
+      super.merge options: ['Yes', 'No']
+    end
+  end
 end