gamefic 1.7.0 → 2.0.0

data/lib/gamefic/scene/conclusion.rb

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

data/lib/gamefic/scene/custom.rb

@@ -1,9 +1,7 @@
 module Gamefic
-  
   # A Custom Scene allows for complete configuration of its behavior upon
   # instantiation. It is suitable for direct instantiation or subclassing.
   #
   class Scene::Custom < Scene::Base
   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.
@@ -8,9 +7,21 @@ module Gamefic
   # instead of a String.
   #
   class Scene::MultipleChoice < Scene::Custom
+    # The zero-based index of the selected option.
+    #
+    # @return [Integer]
     attr_reader :index
+
+    # The one-based index of the selected option.
+    #
+    # @return [Number]
     attr_reader :number
+
+    # The full text of the selected option.
+    #
+    # @return [String]
     attr_reader :selection
+
     attr_writer :invalid_message
 
     def post_initialize
@@ -28,10 +39,16 @@ module Gamefic
       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
@@ -69,7 +86,5 @@ module Gamefic
       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,5 +1,4 @@
 module Gamefic
-
   # Pause for user input.
   #
   class Scene::Pause < Scene::Custom
@@ -7,6 +6,12 @@ module Gamefic
       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
+    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

data/lib/gamefic/scriptable.rb

@@ -0,0 +1,87 @@
+module Gamefic
+  # The Scriptable module provides a clean room (aka "theater") for scripts.
+  #
+  # @!method stage(*args, &block)
+  #   Execute a block of code in a subset of the owner's scope.
+  #
+  #   The provided code is evaluated inside a clean room object that has its
+  #   own instance variables and access to the owner's public methods. The proc
+  #   can accept the method call's arguments.
+  #
+  #   @example Execute a block of code
+  #     stage {
+  #       puts 'Hello'
+  #     }
+  #
+  #   @example Execute a block of code with arguments
+  #     stage 'hello' { |message|
+  #       puts message # <- prints 'hello'
+  #     }
+  #
+  #   @example Use an instance variable
+  #     stage { @message = 'hello'" }
+  #     stage { puts @message } # <- prints 'hello'
+  #
+  #   @yieldpublic [Gamefic::Plot]
+  #   @return [Object] The value returned by the executed code
+  #
+  # @!method theater
+  #   The object that acts as an isolated namespace for staged code.
+  #   @return [Object]
+  #
+  # @!parse alias cleanroom theater
+  module Scriptable
+    module ClassMethods
+      # An array of blocks that were added by the `script` class method.
+      #
+      # @return [Array<Proc>]
+      def blocks
+        @blocks ||= []
+      end
+
+      # Add a block to be executed by the instance's `stage` method.
+      #
+      # Note that `script` does not execute the block instantly, but stores
+      # it in the `blocks` array to be executed later.
+      #
+      # @yieldpublic [Gamefic::Plot]
+      def script &block
+        blocks.push block
+      end
+    end
+
+    def self.included klass
+      klass.extend ClassMethods
+    end
+
+    private
+
+    # Execute all the scripts that were added by the `script` class method.
+    #
+    def run_scripts
+      self.class.blocks.each { |blk| stage &blk }
+    end
+  end
+end
+
+# @note #stage and #theater are implemented this way so the clean room object
+#   defines its classes and modules in the root namespace.
+Gamefic::Scriptable.module_exec do
+  define_method :stage do |*args, &block|
+    theater.instance_exec *args, &block
+  end
+
+  define_method :theater do
+    @theater ||= begin
+      instance = self
+      theater ||= Object.new
+      theater.instance_exec do
+        define_singleton_method :method_missing do |symbol, *args, &block|
+          instance.public_send :public_send, symbol, *args, &block
+        end
+      end
+      theater
+    end
+  end
+  alias cleanroom theater
+end

data/lib/gamefic/serialize.rb

@@ -0,0 +1,68 @@
+module Gamefic
+  module Serialize
+    def to_serial
+      {
+        'class' => self.class.to_s
+      }.merge serialize_instance_variables
+    end
+  end
+end
+
+class Object
+  def to_serial
+    return self if [true, false, nil].include?(self)
+    # @todo This warning is a little too spammy. Set up a logger so it can be
+    # limited to an info or debug level.
+    # STDERR.puts "Unable to convert #{self} to element"
+    "#<UNKNOWN>"
+  end
+
+  def serialize_instance_variables
+    result = {}
+    instance_variables.each do |k|
+      result[k.to_s] = instance_variable_get(k).to_serial
+    end
+    result
+  end
+end
+
+class Symbol
+  def to_serial
+    "#<SYM:#{self}>"
+  end
+end
+
+class String
+  def to_serial
+    self
+  end
+end
+
+class Numeric
+  def to_serial
+    self
+  end
+end
+
+class Array
+  def to_serial
+    map do |e|
+      s = e.to_serial
+      return "#<UNKNOWN>" if s == "#<UNKNOWN>"
+      s
+    end
+  end
+end
+
+class Hash
+  def to_serial
+    result = {}
+    each_pair do |key, value|
+      k2 = key.to_serial
+      v2 = value.to_serial
+      return "#<UNKNOWN>" if k2 == "#<UNKNOWN>" || v2 == "#<UNKNOWN>"
+      result[k2] = v2
+    end
+    result
+  end
+end

data/lib/gamefic/subplot.rb

@@ -1,39 +1,29 @@
 require 'gamefic/plot'
 
 module Gamefic
-
-  class Subplot
-    include Plot::Theater
-    include Plot::Entities
-    include Plot::Commands
-    include Plot::Callbacks
-    include Plot::Scenes
-    include Plot::Articles
+  class Subplot #< Container
+    include World
+    include Scriptable
+    # @!parse extend Scriptable::ClassMethods
 
     # @return [Gamefic::Plot]
     attr_reader :plot
 
-    class << self
-      attr_reader :start_proc
-
-      protected
-
-      def on_start &block
-        @start_proc = block
-      end
-    end
-
-    def initialize plot, introduce: nil, next_cue: nil
+    # @param plot [Gamefic::Plot]
+    # @param introduce [Gamefic::Actor]
+    # @param next_cue [Class<Gamefic::Scene::Base>]
+    def initialize plot, introduce: nil, next_cue: nil, **more
       @plot = plot
       @next_cue = next_cue
       @concluded = false
-      stage &self.class.start_proc unless self.class.start_proc.nil?
+      configure more
+      run_scripts
       playbook.freeze
       self.introduce introduce unless introduce.nil?
     end
 
-    def add_entity e
-      @p_entities.push e
+    def players
+      @players ||= []
     end
 
     def subplot
@@ -58,25 +48,21 @@ module Gamefic
       ent
     end
 
-    # HACK: Always assume subplots are running for the sake of entity destruction
-    def running?
-      true
-    end
-
     def exeunt player
+      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 }
     end
 
     def concluded?
@@ -84,6 +70,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
@@ -95,6 +84,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