gamefic 2.4.0 → 3.0.0

data/lib/gamefic/node.rb

@@ -1,58 +1,45 @@
-# Exception raised when setting a node's parent would cause
-# a circular reference, e.g., A -> A or A -> B -> A
-class CircularNodeReferenceError < RuntimeError; end
+# frozen_string_literal: true
+
+require 'set'
 
 module Gamefic
+  # Exception raised when setting a node's parent to an invalid object.
+  #
+  class NodeError < RuntimeError; end
+
+  # Parent/child relationships for objects.
+  #
   module Node
+    # The object's parent.
+    #
+    # @return [Node, nil]
+    attr_reader :parent
+
     # An array of the object's children.
     #
-    # @return [Array]
+    # @return [Array<Node>]
     def children
-      @children ||= []
-      @children.clone
+      child_set.to_a.freeze
     end
 
     # Get a flat array of all descendants.
     #
-    # @return [Array]
+    # @return [Array<Node>]
     def flatten
-      array = Array.new
-      children.each { |child|
-        array = array + recurse_flatten(child)
-      }
-      array
-    end
-
-    # The object's parent.
-    #
-    # @return [Object]
-    def parent
-      @parent
+      children.flat_map { |child| [child] + child.flatten }
     end
 
     # Set the object's parent.
     #
+    # @param node [Node, nil]
     def parent=(node)
-      return if node == @parent 
-      if node == self
-        raise CircularNodeReferenceError.new("Node cannot be its own parent")
-      end
-      # Do not permit circular references
-      if node != nil and node.parent == self
-        node.parent = nil
-      end
-      if node != nil and flatten.include?(node)
-        raise CircularNodeReferenceError.new("Node cannot be a child of a descendant")
-      end
-      if @parent != node
-        if @parent != nil
-          @parent.send(:rem_child, self)
-        end
-        @parent = node
-        if @parent != nil
-          @parent.send(:add_child, self)
-        end
-      end
+      return if node == parent
+
+      validate_parent node
+
+      parent&.rem_child self
+      @parent = node
+      parent&.add_child self
     end
 
     # Determine if external objects can interact with this object's children.
@@ -64,31 +51,35 @@ module Gamefic
       true
     end
 
+    # True if this node is the other's parent.
+    #
+    # @param other [Node]
+    def has?(other)
+      other.parent == self
+    end
+
     protected
 
     def add_child(node)
-      children
-      @children.push(node)
+      child_set.add node
     end
 
     def rem_child(node)
-      children
-      @children.delete(node)
+      child_set.delete node
     end
 
-    def concat_children(children)
-      children.concat(children)
+    private
+
+    def child_set
+      @child_set ||= Set.new
     end
 
-    private
+    def validate_parent(node)
+      raise NodeError, 'Parent must be a Node' unless node.is_a?(Node) || node.nil?
+
+      raise NodeError, "Node cannot be its own parent" if node == self
 
-    def recurse_flatten(node)
-      array = Array.new
-      array.push(node)
-      node.children.each { |child|
-        array = array + recurse_flatten(child)
-      }
-      return array
+      raise NodeError, 'Node cannot be a child of a descendant' if flatten.include?(node)
     end
   end
 end

data/lib/gamefic/plot.rb

@@ -1,114 +1,81 @@
-require 'gamefic/query'
+# frozen_string_literal: true
 
 module Gamefic
-  # A plot controls the game narrative and manages the world model.
-  # Authors typically build plots through scripts that are executed in a
-  # special container called a stage. All of the elements that compose the
-  # narrative (characters, locations, scenes, etc.) reside in the stage's
-  # scope. Game engines use the plot to receive game data and process user
-  # input.
+  # The plot is the central narrative. It provides a script interface with
+  # methods for creating entities, actions, scenes, and hooks.
   #
-  class Plot
-    autoload :Snapshot,  'gamefic/plot/snapshot'
-    autoload :Darkroom,  'gamefic/plot/darkroom'
-    autoload :Host,      'gamefic/plot/host'
-
-    # @return [Hash]
-    attr_reader :metadata
+  class Plot < Narrative
+    def ready
+      super
+      subplots.each(&:ready)
+      players.each(&:start_take)
+      subplots.delete_if(&:concluding?)
+      players.select(&:concluding?).each { |plyr| rulebook.run_player_conclude_blocks plyr }
+    end
 
-    attr_reader :static
+    def update
+      players.each(&:finish_take)
+      super
+      subplots.each(&:update)
+    end
 
-    include World
-    include Scriptable
-    # @!parse extend Scriptable::ClassMethods
-    include Snapshot
-    include Host
-    include Serialize
+    # Remove an actor from the game.
+    #
+    # Calling `uncast` on the plot will also remove the actor from its
+    # subplots.
+    #
+    # @param actor [Actor]
+    # @return [Actor]
+    def uncast actor
+      subplots.each { |sp| sp.uncast actor }
+      super
+    end
 
-    exclude_from_serial [:@static]
+    # Get an array of all the current subplots.
+    #
+    # @return [Array<Subplot>]
+    def subplots
+      @subplots ||= []
+    end
 
-    # @param metadata [Hash]
-    def initialize metadata: {}
-      @metadata = metadata
-      run_scripts
-      @static = [self] + scene_classes + entities
+    # Start a new subplot based on the provided class.
+    #
+    # @param subplot_class [Class<Gamefic::Subplot>] The Subplot class
+    # @param introduce [Gamefic::Actor, Array<Gamefic::Actor>] Players to introduce
+    # @param config [Hash] Subplot configuration
+    # @return [Gamefic::Subplot]
+    def branch subplot_class = Gamefic::Subplot, introduce: [], **config
+      subplot_class.new(self, introduce: introduce, **config)
+                   .tap { |sub| subplots.push sub }
     end
 
-    def plot
-      self
+    def save
+      Snapshot.save self
     end
 
-    # Get an Array of the Plot's current Syntaxes.
-    #
-    # @return [Array<Syntax>]
-    def syntaxes
-      playbook.syntaxes
+    def inspect
+      "#<#{self.class}>"
     end
 
-    # Prepare the Plot for the next turn of gameplay.
-    # This method is typically called by the Engine that manages game
-    # execution.
-    #
-    def ready
-      playbook.freeze
-      call_ready
-      call_player_ready
-      subplots.each { |s| s.ready }
-      players.each do |p|
-        p.state.replace(
-          p.scene.state
-          .merge({
-            messages: p.messages,
-            last_prompt: p.last_prompt,
-            last_input: p.last_input,
-            queue: p.queue
-          })
-          .merge(p.state)
-        )
-        p.output.replace(p.state)
-        p.state.clear
-      end
+    def detach
+      cache = [@rulebook]
+      @rulebook = nil
+      cache.concat subplots.map(&:detach)
+      cache
     end
 
-    # Update the Plot's current turn of gameplay.
-    # This method is typically called by the Engine that manages game
-    # execution.
-    #
-    def update
-      entities.each { |e| e.flush }
-      call_before_player_update
-      players.each do |p|
-        next unless p.scene
-        p.last_input = p.queue.last
-        p.last_prompt = p.scene.prompt
-        p.scene.update
-        if p.scene.is_a?(Scene::Conclusion)
-          player_conclude_procs.each do |proc|
-            proc.call p
-          end
-        end
-      end
-      call_player_update
-      call_update
-      subplots.delete_if(&:concluded?)
-      subplots.each(&:update)
+    def attach(cache)
+      super(cache.shift)
+      subplots.each { |subplot| subplot.attach cache.shift }
     end
 
-    # Send a message to a group of entities.
-    #
-    # @param entities [Array<Entity>]
-    # @param message [String]
-    def tell entities, message
-      entities.each { |entity|
-        entity.tell message
-      }
+    def hydrate
+      super
+      subplots.each(&:hydrate)
     end
-  end
-end
 
-module Gamefic
-  # @yieldself [Gamefic::Plot]
-  def self.script &block
-    Gamefic::Plot.script &block
+    def self.restore data
+      Snapshot.restore data
+    end
   end
 end

data/lib/gamefic/props/default.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Props
+    # A collection of data related to a scene. Scenes define which Props class
+    # they use. Props can be accessed in a scene's on_start and on_finish
+    # callbacks.
+    #
+    # Props::Default includes the most common attributes that a scene requires.
+    # Scenes are able but not required to subclass it. Some scenes, like
+    # MultipleChoice, use specialized Props subclasses, but in many cases,
+    # Props::Default is sufficient.
+    #
+    class Default
+      # @return [String]
+      attr_writer :prompt
+
+      # @return [String]
+      attr_accessor :input
+
+      # A freeform dictionary of objects related to the scene. Plots can pass
+      # opts to be included in the context when they cue scenes.
+      #
+      # @return [Hash]
+      attr_reader :context
+      alias data context
+
+      # @param scene [Scene, nil]
+      # @param context [Hash]
+      def initialize name, type, **context
+        @scene_name = name
+        @scene_type = type
+        @context = context
+      end
+
+      def prompt
+        @prompt ||= '>'
+      end
+    end
+  end
+end

data/lib/gamefic/props/multiple_choice.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Props
+    # Props for MultipleChoice scenes.
+    #
+    class MultipleChoice < Default
+      # A message to send the player for an invalid choice. A formatting
+      # token named %<input>s can be used to inject the user input.
+      #
+      # @return [String]
+      attr_writer :invalid_message
+
+      # The array of available options.
+      #
+      # @return [Array<String>]
+      def options
+        @options ||= []
+      end
+
+      def invalid_message
+        @invalid_message ||= '"%<input>s" is not a valid choice.'
+      end
+
+      # The zero-based index of the selected option.
+      #
+      # @return [Integer, nil]
+      def index
+        return nil unless input
+
+        @index ||= index_by_number || index_by_text
+      end
+
+      # The one-based index of the selected option.
+      #
+      # @return [Integer, nil]
+      def number
+        return nil unless index
+
+        index + 1
+      end
+
+      # The full text of the selected option.
+      #
+      # @return [String, nil]
+      def selection
+        return nil unless index
+
+        options[index]
+      end
+
+      private
+
+      def index_by_number
+        return input.to_i - 1 if input.match(/^\d+$/) && options[input.to_i - 1]
+
+        nil
+      end
+
+      def index_by_text
+        options.find_index { |text| input.downcase == text.downcase }
+      end
+    end
+  end
+end

data/lib/gamefic/props/pause.rb

@@ -0,0 +1,11 @@
+module Gamefic
+  module Props
+    # Props for Pause scenes.
+    #
+    class Pause < Default
+      def prompt
+        @prompt ||= 'Press enter to continue...'
+      end
+    end
+  end
+end

data/lib/gamefic/props/yes_or_no.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Props
+    # A MultipleChoice variant that only allows Yes or No.
+    #
+    class YesOrNo < MultipleChoice
+      def yes?
+        selection == 'Yes'
+      end
+
+      def no?
+        selection == 'No'
+      end
+
+      def options
+        @options ||= %w[Yes No].freeze
+      end
+    end
+  end
+end

data/lib/gamefic/props.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Props
+    require 'gamefic/props/default'
+    require 'gamefic/props/multiple_choice'
+    require 'gamefic/props/pause'
+    require 'gamefic/props/yes_or_no'
+  end
+end

data/lib/gamefic/query/base.rb

@@ -1,160 +1,79 @@
+# frozen_string_literal: true
+
 module Gamefic
   module Query
+    # A base class for entity-based queries that can be applied to responses.
+    # Each query represents an attempt to match an argument in a command to a
+    # game entity.
+    #
     class Base
-      NEST_REGEXP = / in | on | of | from | inside | from inside /
-
+      # @return [Array<Object>]
       attr_reader :arguments
 
-      def initialize *args
-        @arguments = args
-      end
-
-      # Determine whether the query allows ambiguous entity references.
-      # If false, actions that use this query will only be valid if the token
-      # passed into it resolves to a single entity. If true, actions will
-      # accept an array of matching entities instead.
-      # Queries are not ambiguous by default (ambiguous? == false).
-      #
       # @return [Boolean]
-      def ambiguous?
-        false
-      end
+      attr_reader :ambiguous
 
-      # Subclasses should override this method with the logic required to collect
-      # all entities that exist in the query's context.
+      # @raise [ArgumentError] if any of the arguments are nil
       #
-      # @return [Array<Object>]
-      def context_from(subject)
-        []
-      end
+      # @param arguments [Array<Object>]
+      # @param ambiguous [Boolean]
+      def initialize *arguments, ambiguous: false
+        raise ArgumentError, "nil argument in query" if arguments.any?(&:nil?)
 
-      # Get a collection of objects that exist in the subject's context and
-      # match the provided token. The result is provided as a Matches object.
-      #
-      # @param subject [Entity]
-      # @param token [String]
-      # @param continued [Boolean]
-      # @return [Gamefic::Query::Matches]
-      def resolve(subject, token, continued: false)
-        available = context_from(subject)
-        return Matches.new([], '', token) if available.empty?
-        if continued
-          return Matches.execute(available, token, continued: continued)
-        elsif nested?(token)
-          drill = denest(available, token).select { |e| accept?(e) }
-          return Matches.new(drill, token, '') unless drill.length != 1
-          return Matches.new([], '', token)
-        end
-        result = available.select { |e| e.specified?(token) }
-        result = available.select { |e| e.specified?(token, fuzzy: true) } if result.empty?
-        result.keep_if { |e| accept? e }
-        Matches.new(result, (result.empty? ? '' : token), (result.empty? ? token : ''))
+        @arguments = arguments
+        @ambiguous = ambiguous
       end
 
-      def include?(subject, object)
-        return false unless accept?(object)
-        result = context_from(subject)
-        result.include?(object)
+      # @param subject [Gamefic::Entity]
+      # @param token [String]
+      # @return [Result]
+      def query(subject, token)
+        raise "#query not implemented for #{self.class}"
       end
 
-      # A ranking of how precise the query's arguments are.
-      #
-      # Query precision is a factor in calculating Action#rank.
-      #
       # @return [Integer]
       def precision
-        if @precision.nil?
-          @precision = 1
-          arguments.each { |a|
-            if a.is_a?(Class)
-              @precision += 100
-            elsif a.is_a?(Gamefic::Entity)
-              @precision += 1000
-            end
-          }
-          @precision
-        end
-        @precision
+        @precision ||= calculate_precision
       end
-      alias rank precision
 
-      def signature
-        "#{self.class.to_s.split('::').last.downcase}(#{simplify_arguments.join(', ')})"
+      def ambiguous?
+        @ambiguous
       end
 
-      # Determine whether the specified entity passes the query's arguments.
-      #
-      # @param [Entity]
-      # @return [Boolean]
-      def accept?(entity)
-        result = true
-        arguments.each do |a|
-          result = if a.is_a?(Symbol)
-            (entity.send(a) != false)
-          elsif a.is_a?(Regexp)
-            !entity.to_s.match(a).nil?
-          elsif a.is_a?(Module) || a.is_a?(Class)
-            entity.is_a?(a)
+      private
+
+      def calculate_precision
+        @arguments.sum(@ambiguous ? -1000 : 0) do |arg|
+          case arg
+          when Entity, Scriptable::Proxy::Agent
+            1000
+          when Class, Module
+            class_depth(arg) * 100
           else
-            (entity == a)
+            1
           end
-          break if result == false
         end
-        result
       end
 
-      protected
+      def class_depth klass
+        return 1 unless klass.is_a?(Class)
 
-      # Return an array of the entity's children. If the child is accessible,
-      # recursively append its children.
-      # The result will NOT include the original entity itself.
-      #
-      # @param [Entity]
-      # @return [Array<Object>]
-      def subquery_accessible entity
-        return [] if entity.nil?
-        result = []
-        if entity.accessible?
-          entity.children.each do |c|
-            result.push c
-            result.concat subquery_accessible(c)
-          end
-        end
-        result
+        depth = 1
+        sup = klass
+        depth += 1 while (sup = sup.superclass)
+        depth
       end
 
-      private
+      def ambiguous_result scan
+        return Result.new(nil, scan.token) if scan.matched.empty?
 
-      def simplify_arguments
-        arguments.map do |a|
-          if a.is_a?(Class) || a.is_a?(Object)
-            a.to_s.split('::').last.downcase
-          else
-            a.to_s.downcase
-          end
-        end
+        Result.new(scan.matched, scan.remainder)
       end
 
-      def nested?(token)
-        !token.match(NEST_REGEXP).nil?
-      end
+      def unambiguous_result scan
+        return Result.new(nil, scan.token) unless scan.matched.one?
 
-      def denest(objects, token)
-        parts = token.split(NEST_REGEXP)
-        current = parts.pop
-        last_result = objects.select { |e| e.specified?(current) }
-        last_result = objects.select { |e| e.specified?(current, fuzzy: true) } if last_result.empty?
-        until parts.empty?
-          current = "#{parts.last} #{current}"
-          result = last_result.select { |e| e.specified?(current) }
-          result = last_result.select { |e| e.specified?(current, fuzzy: true) } if result.empty?
-          break if result.empty?
-          parts.pop
-          last_result = result
-        end
-        return [] if last_result.empty? or last_result.length > 1
-        return last_result if parts.empty?
-        denest(last_result[0].children, parts.join(' '))
+        Result.new(scan.matched.first, scan.remainder)
       end
     end
   end