gamefic 2.4.0 → 3.0.0

data/lib/gamefic/rulebook.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'gamefic/rulebook/calls'
+require 'gamefic/rulebook/events'
+require 'gamefic/rulebook/hooks'
+require 'gamefic/rulebook/scenes'
+
+module Gamefic
+  # A collection of rules that define the behavior of a narrative.
+  #
+  # Rulebooks provide a way to separate narrative data from code. This
+  # separation is necessary to ensure that the game state can be serialized in
+  # snapshots.
+  #
+  class Rulebook
+    # @return [Calls]
+    attr_reader :calls
+
+    # @return [Events]
+    attr_reader :events
+
+    # @return [Hooks]
+    attr_reader :hooks
+
+    # @return [Scenes]
+    attr_reader :scenes
+
+    # @return [Narrative]
+    attr_reader :narrative
+
+    # @param narrative [Narrative]
+    def initialize(narrative)
+      @narrative = narrative
+      @calls = Calls.new
+      @events = Events.new
+      @hooks = Hooks.new
+      @scenes = Scenes.new
+    end
+
+    def freeze
+      super
+      [@calls, @events, @hooks, @scenes].each(&:freeze)
+      self
+    end
+
+    # @return [Array<Response>]
+    def responses
+      @calls.responses
+    end
+
+    # @return [Array<Syntax>]
+    def syntaxes
+      @calls.syntaxes
+    end
+
+    # An array of all the verbs available in the rulebook. This list only
+    # includes verbs that are explicitly defined in reponses. It excludes
+    # synonyms that might be defined in syntaxes (see #synonyms).
+    #
+    # @example
+    #   rulebook.respond :verb { |_| nil }
+    #   rulebook.interpret 'synonym', 'verb'
+    #   rulebook.verbs #=> [:verb]
+    #
+    # @return [Array<Symbol>]
+    def verbs
+      @calls.verbs
+    end
+
+    # An array of all the verbs defined in responses and any synonyms defined
+    # in syntaxes.
+    #
+    # @example
+    #   rulebook.respond :verb { |_| nil }
+    #   rulebook.interpret 'synonym', 'verb'
+    #   rulebook.synonyms #=> [:synonym, :verb]
+    #
+    def synonyms
+      @calls.synonyms
+    end
+
+    # Get an array of all the responses that match a list of verbs.
+    #
+    # @param verbs [Array<Symbol>]
+    # @return [Array<Response>]
+    def responses_for *verbs
+      @calls.responses_for *verbs
+    end
+
+    # Get an array of all the syntaxes that match a lit of verbs.
+    #
+    # @param words [Array<Symbol>]
+    # @return [Array<Syntax>]
+    def syntaxes_for *synonyms
+      @calls.syntaxes_for *synonyms
+    end
+
+    def run_ready_blocks
+      events.ready_blocks.each { |blk| Stage.run narrative, &blk }
+    end
+
+    def run_update_blocks
+      events.update_blocks.each { |blk| Stage.run narrative, &blk }
+    end
+
+    def run_before_actions action
+      hooks.run_before action, narrative
+    end
+
+    def run_after_actions action
+      hooks.run_after action, narrative
+    end
+
+    def run_conclude_blocks
+      events.conclude_blocks.each { |blk| Stage.run narrative, &blk }
+    end
+
+    def run_player_conclude_blocks player
+      events.player_conclude_blocks.each { |blk| Stage.run(narrative) { blk.call(player) } }
+    end
+
+    def run_player_output_blocks player, output
+      events.player_output_blocks.each { |blk| Stage.run(narrative) { blk.call(player, output) } }
+    end
+
+    def empty?
+      calls.empty? && hooks.empty? && scenes.empty? && events.empty?
+    end
+
+    def script
+      narrative.class.included_blocks.select(&:script?).each { |blk| Stage.run(narrative, &blk.code) }
+    end
+
+    def script_with_defaults
+      script
+      scenes.with_defaults narrative
+    end
+  end
+end

data/lib/gamefic/scanner.rb

@@ -0,0 +1,103 @@
+module Gamefic
+  # A module for matching objects to tokens.
+  #
+  module Scanner
+    NEST_REGEXP = / in | on | of | from | inside | from inside /
+
+    # The result of an attempt to scan objects against a token in a Scanner. It
+    # provides an array of matching objects, the text that matched them, and the
+    # text that remains unmatched.
+    #
+    class Result
+      # The scanned objects
+      #
+      # @return [Array<Object>]
+      attr_reader :scanned
+
+      # The scanned token
+      #
+      # @return [String]
+      attr_reader :token
+
+      # The matched objects
+      #
+      # @return [Array<Object>]
+      attr_reader :matched
+
+      # The remaining (unmatched) portion of the token
+      #
+      # @return [String]
+      attr_reader :remainder
+
+      def initialize scanned, token, matched, remainder
+        @scanned = scanned
+        @token = token
+        @matched = matched
+        @remainder = remainder
+      end
+    end
+
+    # Scan entities against a token.
+    #
+    # @param objects [Array<Gamefic::Entity>]
+    # @param token [String]
+    # @return [Result]
+    def self.scan objects, token
+      # @note Theoretically, scanned objects only have to implement two
+      #   methods:
+      #     *  #keywords => [Array<String>]
+      #     *  #children => [Array<#keywords, #children>]
+
+      words = token.keywords
+      available = objects.clone
+      filtered = []
+      if nested?(token) && objects.all?(&:children)
+        denest(objects, token)
+      else
+        words.each_with_index do |word, idx|
+          tested = select_strict(available, word)
+          tested = select_fuzzy(available, word) if tested.empty?
+          return Result.new(objects, token, filtered, words[idx..].join(' ')) if tested.empty?
+
+          filtered = tested
+          available = filtered
+        end
+        Result.new(objects, token, filtered, '')
+      end
+    end
+
+    class << self
+      private
+
+      def select_strict available, word
+        available.select { |obj| obj.keywords.include?(word) }
+      end
+
+      def select_fuzzy available, word
+        available.select { |obj| obj.keywords.any? { |wrd| wrd.start_with?(word) } }
+      end
+
+      def nested?(token)
+        token.match(NEST_REGEXP)
+      end
+
+      def denest(objects, token)
+        parts = token.split(NEST_REGEXP)
+        current = parts.pop
+        last_result = scan(objects, current)
+        until parts.empty?
+          current = "#{parts.last} #{current}"
+          result = scan(last_result.matched, current)
+          break if result.matched.empty?
+
+          parts.pop
+          last_result = result
+        end
+        return Result.new(objects, token, [], '') if last_result.matched.empty? || last_result.matched.length > 1
+        return last_result if parts.empty?
+
+        denest(last_result.matched.first.children, parts.join(' '))
+      end
+    end
+  end
+end

data/lib/gamefic/scene/activity.rb

@@ -1,21 +1,13 @@
-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
+# frozen_string_literal: true
 
-    def finish
-      super
-      actor.perform input.strip unless input.to_s.strip.empty?
-    end
-
-    class << self
-      def type
-        'Activity'
+module Gamefic
+  module Scene
+    # A scene that accepts player commands for actors to perform.
+    #
+    class Activity < Default
+      def finish actor, props
+        super
+        actor.perform props.input
       end
     end
   end

data/lib/gamefic/scene/conclusion.rb

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
 module Gamefic
-  # A Conclusion ends the Plot (or the character's participation in it).
-  #
-  class Scene::Conclusion < Scene::Base
-    def type
-      @type ||= 'Conclusion'
+  module Scene
+    # A scene that ends an actor's participation in a narrative.
+    #
+    class Conclusion < Default
     end
   end
 end

data/lib/gamefic/scene/default.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scene
+    # The base class for scenes. Authors can instantiate this class directly
+    # and customize it with on_start and on_finish blocks.
+    #
+    class Default
+      # @return [Symbol]
+      attr_reader :name
+
+      # @param name [Symbol]
+      # @param narrative [Narrative]
+      # @param on_start [Proc, nil]
+      # @param on_finish [Proc, nil]
+      # @yieldparam [self]
+      def initialize name, narrative, on_start: nil, on_finish: nil
+        @name = name
+        @narrative = narrative
+        @start_blocks = []
+        @finish_blocks = []
+        @start_blocks.push on_start if on_start
+        @finish_blocks.push on_finish if on_finish
+        yield(self) if block_given?
+      end
+
+      # @return [String]
+      def type
+        @type ||= self.class.to_s.sub(/^Gamefic::Scene::/, '')
+      end
+
+      def new_props(**context)
+        self.class.props_class.new(name, type, **context)
+      end
+
+      def on_start &block
+        @start_blocks.push block
+      end
+
+      def on_finish &block
+        @finish_blocks.push block
+      end
+
+      # @param actor [Gamefic::Actor]
+      # @param props [Props::Default]
+      # @return [void]
+      def start actor, props
+        actor.output[:scene] = to_hash
+        actor.output[:prompt] = props.prompt
+      end
+
+      # @param actor [Gamefic::Actor]
+      # @param props [Props::Default]
+      # @return [void]
+      def finish actor, props
+        props.input = actor.queue.shift
+      end
+
+      def run_start_blocks actor, props
+        @start_blocks.each { |blk| Stage.run(@narrative, actor, props, &blk) }
+      end
+
+      def run_finish_blocks actor, props
+        @finish_blocks.each { |blk| Stage.run(@narrative, actor, props, &blk) }
+      end
+
+      def self.props_class
+        @props_class ||= Props::Default
+      end
+
+      def conclusion?
+        is_a?(Conclusion)
+      end
+
+      def to_hash
+        { name: name, type: type }
+      end
+
+      class << self
+        protected
+
+        def use_props_class klass
+          @props_class = klass
+        end
+      end
+    end
+  end
+end

data/lib/gamefic/scene/multiple_choice.rb

@@ -1,79 +1,24 @@
-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.
-  #
-  # The finish block's input parameter receives a MultipleChoice::Input object
-  # instead of a String.
-  #
-  class Scene::MultipleChoice < Scene::Base
-    # The zero-based index of the selected option.
-    #
-    # @return [Integer]
-    attr_reader :index
+# frozen_string_literal: true
 
-    # The one-based index of the selected option.
-    #
-    # @return [Integer]
-    attr_reader :number
-
-    # The full text of the selected option.
+module Gamefic
+  module Scene
+    # A scene that presents a list of choices and processes the player's input.
+    # If the input is not a valid choice, the scene gets recued.
     #
-    # @return [String]
-    attr_reader :selection
+    class MultipleChoice < Default
+      use_props_class Props::MultipleChoice
 
-    attr_writer :invalid_message
-
-    def post_initialize
-      self.type = 'MultipleChoice'
-      self.prompt = 'Enter a choice:'
-    end
-
-    def finish
-      get_choice
-      if selection.nil?
-        actor.tell invalid_message
-      else
+      def start actor, props
         super
+        actor.output[:options] = props.options
       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
-
-    def state
-      super.merge options: options
-    end
-
-    private
+      def finish actor, props
+        super
+        return if props.index
 
-    def get_choice
-      if input.strip =~ /^[0-9]+$/ and input.to_i > 0
-        @number = input.to_i
-        @index = number - 1
-        @selection = options[index]
-      else
-        i = 0
-        options.each { |o|
-          if o.casecmp(input).zero?
-            @selection = o
-            @index = i
-            @number = index + 1
-            break
-          end
-          i += 1
-        }
+        actor.tell format(props.invalid_message, input: props.input)
+        actor.recue
       end
     end
   end

data/lib/gamefic/scene/pause.rb

@@ -1,17 +1,13 @@
-module Gamefic
-  # Pause for user input.
-  #
-  class Scene::Pause < Scene::Base
-    def post_initialize
-      self.type = 'Pause'
-      self.prompt = 'Press enter to continue...'
-    end
+# frozen_string_literal: true
 
-    class << self
-      def tracked?
-        @tracked = true if @tracked.nil?
-        @tracked
-      end
+module Gamefic
+  module Scene
+    # Pause a scene. This rig simply runs on_start and waits for user input
+    # before proceeding to on_finish. The user input itself is ignored by
+    # default.
+    #
+    class Pause < Default
+      use_props_class Props::Pause
     end
   end
 end

data/lib/gamefic/scene/yes_or_no.rb

@@ -1,51 +1,11 @@
-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::Base
-    attr_writer :invalid_message
-
-    def post_initialize
-      self.type = 'YesOrNo'
-      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' 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' or input.to_i == 2
-    end
+# frozen_string_literal: true
 
-    # The message sent to the user for an invalid answer, i.e., the input
-    # could not be resolved to either Yes or No.
+module Gamefic
+  module Scene
+    # A specialized MultipleChoice scene that only accepts Yes or No.
     #
-    # @return [String]
-    def invalid_message
-      @invalid_message ||= 'Please enter Yes or No.'
-    end
-
-    def finish
-      if yes? or no?
-        super
-      else
-        actor.tell invalid_message
-      end
-    end
-
-    def state
-      super.merge options: ['Yes', 'No']
+    class YesOrNo < MultipleChoice
+      use_props_class Props::YesOrNo
     end
   end
 end

data/lib/gamefic/scene.rb

@@ -1,11 +1,15 @@
+# frozen_string_literal: true
+
 module Gamefic
+  # Narratives use scenes to process game turns. The start of a scene defines
+  # the output to be sent to the player. The finish processes player input.
+  #
   module Scene
-    autoload :Base, 'gamefic/scene/base'
-    autoload :Activity, 'gamefic/scene/activity'
-    autoload :Pause, 'gamefic/scene/pause'
-    autoload :Conclusion, 'gamefic/scene/conclusion'
-    autoload :MultipleChoice, 'gamefic/scene/multiple_choice'
-    autoload :MultipleScene, 'gamefic/scene/multiple_scene'
-    autoload :YesOrNo, 'gamefic/scene/yes_or_no'
+    require 'gamefic/scene/default'
+    require 'gamefic/scene/activity'
+    require 'gamefic/scene/multiple_choice'
+    require 'gamefic/scene/pause'
+    require 'gamefic/scene/yes_or_no'
+    require 'gamefic/scene/conclusion'
   end
 end

data/lib/gamefic/scope/base.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scope
+    # The base class for a Scoped query's scope.
+    #
+    class Base
+      attr_reader :context
+
+      # @param [Gamefic::Entity]
+      def initialize context
+        @context = context
+      end
+
+      # @param [Array<Gamefic::Entity>]
+      def matches
+        []
+      end
+
+      # @param [Gamefic::Entity]
+      def self.matches context
+        new(context).matches
+      end
+
+      def self.precision
+        0
+      end
+
+      private
+
+      # Return an array of the entity's accessible descendants.
+      #
+      # @param [Entity]
+      # @return [Array<Entity>]
+      def subquery_accessible entity
+        return [] unless entity&.accessible?
+
+        entity.children.flat_map do |c|
+          [c] + subquery_accessible(c)
+        end
+      end
+    end
+  end
+end

data/lib/gamefic/scope/children.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scope
+    # The Children scope returns an entity's children and all accessible
+    # descendants.
+    #
+    class Children < Base
+      def matches
+        context.children.flat_map do |c|
+          [c] + subquery_accessible(c)
+        end
+      end
+    end
+  end
+end

data/lib/gamefic/scope/family.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scope
+    # The Family scope returns an entity's parent, siblings, and descendants.
+    #
+    class Family < Base
+      def matches
+        result = context.parent ? [context.parent] : []
+        result.concat subquery_accessible(context.parent)
+        result.delete context
+        context.children.each do |c|
+          result.push c
+          result.concat subquery_accessible(c)
+        end
+        result.uniq
+      end
+    end
+  end
+end

data/lib/gamefic/scope/myself.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scope
+    # The Myself scope returns the entity itself.
+    #
+    class Myself < Base
+      def matches
+        [context]
+      end
+    end
+  end
+end

data/lib/gamefic/scope/parent.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scope
+    # A query scope that can only match the entity's parent.
+    #
+    class Parent < Base
+      def matches
+        [context.parent].compact
+      end
+    end
+  end
+end