gamefic 2.4.0 → 3.1.0

data/lib/gamefic/rulebook/events.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Gamefic
+  class Rulebook
+    # Blocks of code to be executed for various narrative events, such as
+    # on_ready and on_update.
+    #
+    class Events
+      attr_reader :player_output_blocks
+
+      attr_reader :player_conclude_blocks
+
+      attr_reader :ready_blocks
+
+      attr_reader :update_blocks
+
+      attr_reader :conclude_blocks
+
+      def initialize
+        @ready_blocks = []
+        @update_blocks = []
+        @conclude_blocks = []
+        @player_conclude_blocks = []
+        @player_output_blocks = []
+      end
+
+      def empty?
+        [player_output_blocks, player_conclude_blocks, ready_blocks, update_blocks, conclude_blocks].all?(&:empty?)
+      end
+
+      def freeze
+        super
+        instance_variables.each { |k| instance_variable_get(k).freeze }
+        self
+      end
+
+      # @return [void]
+      def on_ready &block
+        @ready_blocks.push block
+      end
+
+      # @yieldparam [Actor]
+      # @return [void]
+      def on_player_ready &block
+        @ready_blocks.push(proc do
+          players.each { |plyr| instance_exec plyr, &block }
+        end)
+      end
+
+      def on_update &block
+        @update_blocks.push block
+      end
+
+      def on_player_update &block
+        @update_blocks.push(proc do
+          players.each { |plyr| instance_exec plyr, &block }
+        end)
+      end
+
+      # @return [void]
+      def on_conclude &block
+        @conclude_blocks.push block
+      end
+
+      # @yieldparam [Actor]
+      # @return [void]
+      def on_player_conclude &block
+        @player_conclude_blocks.push block
+      end
+
+      # @yieldparam [Actor]
+      # @yieldparam [Hash]
+      # @return [void]
+      def on_player_output &block
+        @player_output_blocks.push block
+      end
+    end
+  end
+end

data/lib/gamefic/rulebook/hooks.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Gamefic
+  class Rulebook
+    # A collection of hooks that can be executed before and after an action.
+    #
+    class Hooks
+      attr_reader :before_actions
+
+      attr_reader :after_actions
+
+      def initialize
+        @before_actions = []
+        @after_actions = []
+      end
+
+      def freeze
+        super
+        @before_actions.freeze
+        @after_actions.freeze
+        self
+      end
+
+      def before_action *verbs, &block
+        before_actions.push Action::Hook.new(*verbs, &block)
+      end
+
+      def after_action *verbs, &block
+        after_actions.push Action::Hook.new(*verbs, &block)
+      end
+
+      def empty?
+        before_actions.empty? && after_actions.empty?
+      end
+
+      def run_before action, narrative
+        run_action_hooks action, narrative, before_actions
+      end
+
+      def run_after action, narrative
+        run_action_hooks action, narrative, after_actions
+      end
+
+      private
+
+      def run_action_hooks action, narrative, hooks
+        hooks.each do |hook|
+          break if action.cancelled?
+
+          next unless hook.match?(action.verb)
+
+          Stage.run(narrative) { instance_exec(action, &hook.block) }
+        end
+      end
+    end
+  end
+end

data/lib/gamefic/rulebook/scenes.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Gamefic
+  class Rulebook
+    # The scene manager for rulebooks.
+    #
+    class Scenes
+      attr_reader :introductions
+
+      def initialize
+        @scene_map = {}
+        @introductions = []
+      end
+
+      def freeze
+        super
+        @scene_map.freeze
+        @introductions.freeze
+        self
+      end
+
+      # Add a scene to the scenebook.
+      #
+      # @param [Scene]
+      def add scene
+        raise ArgumentError, "A scene named `#{scene.name} already exists" if @scene_map.key?(scene.name)
+
+        @scene_map[scene.name] = scene
+      end
+
+      def scene? name
+        @scene_map.key? name
+      end
+
+      # @return [Scene, nil]
+      def [](name)
+        @scene_map[name]
+      end
+
+      # @return [Array<Symbol>]
+      def names
+        @scene_map.keys
+      end
+
+      # @return [Array<Scene>]
+      def all
+        @scene_map.values
+      end
+
+      def introduction scene
+        introductions.push scene
+      end
+
+      def with_defaults narrative
+        maybe_add :default_scene, Scene::Activity, narrative
+        maybe_add :default_conclusion, Scene::Conclusion, narrative
+      end
+
+      def maybe_add name, klass, narrative
+        add klass.new(name, narrative) unless names.include?(name)
+      end
+
+      def empty?
+        @scene_map.empty? && introductions.empty?
+      end
+    end
+  end
+end

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, player, &blk) }
+    end
+
+    def run_player_output_blocks player, output
+      events.player_output_blocks.each { |blk| Stage.run(narrative, player, output, &blk) }
+    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,130 @@
+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<Entity>, String, Regexp]
+      attr_reader :scanned
+
+      # The scanned token
+      #
+      # @return [String]
+      attr_reader :token
+
+      # The matched objects
+      #
+      # @return [Array<Entity>, String]
+      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 selection [Array<Entity>, String, Regexp]
+    # @param token [String]
+    # @return [Result]
+    def self.scan selection, token
+      strict_result = strict(selection, token)
+      strict_result.matched.empty? ? fuzzy(selection, token) : strict_result
+    end
+
+    # @param selection [Array<Entity>, String, Regexp]
+    # @param token [String]
+    # @return [Result]
+    def self.strict selection, token
+      return Result.new(selection, token, '', token) unless selection.is_a?(Array)
+
+      scan_strict_or_fuzzy(selection, token, :select_strict)
+    end
+
+    # @param selection [Array<Entity>, String, Regexp]
+    # @param token [String]
+    # @return [Result]
+    def self.fuzzy selection, token
+      return scan_text(selection, token) unless selection.is_a?(Array)
+
+      scan_strict_or_fuzzy(selection, token, :select_fuzzy)
+    end
+
+    class << self
+      private
+
+      def scan_strict_or_fuzzy objects, token, method
+        if nested?(token) && objects.all?(&:children)
+          denest(objects, token)
+        else
+          words = token.keywords
+          available = objects.clone
+          filtered = []
+          words.each_with_index do |word, idx|
+            tested = send(method, available, word)
+            return Result.new(objects, token, filtered, words[idx..].join(' ')) if tested.empty?
+
+            filtered = tested
+            available = filtered
+          end
+          Result.new(objects, token, filtered, '')
+        end
+      end
+
+      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 scan_text selection, token
+        case selection
+        when Regexp
+          return Result.new(selection, token, token, '') if token =~ selection
+        else
+          return Result.new(selection, token, selection, token[selection.length..]) if token.start_with?(selection)
+        end
+        Result.new(selection, token, '', token)
+      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(self, **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
+        props.output[:scene] = to_hash
+        props.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
+        props.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