gamefic 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6647dc3319080277826fecd19b8466cfbe82a42f4f4c68aeb89fa74bd0de4319
-  data.tar.gz: 0dc0680cb42b981d6e93c12d03e95b4ffcce0a98acb0678595723ab2d5ae7db9
+  metadata.gz: 3900923aaef12a43321ce6f9cc5957953b12bba7d939e0a1666d8c6c75703855
+  data.tar.gz: 6023310c5e26e9632ed4c053a9bea619e1455dbb66966d82fc9e772044d19d3a
 SHA512:
-  metadata.gz: 1ec19185367b63b0ebe352e620af403e0aef00bdd7afac7135801551568ef5c35c923b45092cb4d781cd8458bba71776b042efe9837a0e9d2f144141b6b8d606
-  data.tar.gz: 300d2c30b05993ee4689f14ce8daeeec3585bfdf1cd7636ec6a931bfc568e8227a97771fdf6d20ec859080f3792b914a29ba1fc6a7246c9f9ef9eb563d81920c
+  metadata.gz: aea9a57211541f056c730707227020f2c35376d59cc4e69c3c7463e8a8bafa7b6fcd4585a99bf2ce235fdc4c583393f53e060554e06f6e5912358959305627eb
+  data.tar.gz: 5351ea7cc8b3ff4e01e064eb12a594dc2d928641b19e8593243da00b672780acff0d808d73eca1a80cf2e2139fd657b870fa7a5a5315e0a2a3998bc306db0c05

data/CHANGELOG.md

@@ -1,4 +1,13 @@
-## 3.0.0
+## 3.1.0 - April 8, 2024
+- Dispatcher prioritizes strict token matches
+- Scanner builds commands
+- Tokenize expressions and execute commands
+- Delete concluded subplots last in Plot#ready
+- Fix plot conclusion check after subplots conclude
+- Correct contexts for conclude and output blocks
+- Reinstate Active#last_input
+
+## 3.0.0 - January 27, 2024
 - Instantiate subplots from snapshots
 - Split Action into Response and Action
 - Logging

data/lib/gamefic/action.rb

@@ -13,8 +13,10 @@ module Gamefic
     # action's performance.
     #
     class Hook
+      # @param [Array<Symbol>]
       attr_reader :verbs
 
+      # @param [Proc]
       attr_reader :block
 
       def initialize *verbs, &block
@@ -45,11 +47,13 @@ module Gamefic
       @response = response
     end
 
+    # @return [self]
     def execute
-      return if cancelled?
+      return self if cancelled? || executed?
 
       @executed = true
       response.execute actor, *arguments
+      self
     end
 
     # True if the response has been executed. False typically means that the
@@ -75,6 +79,10 @@ module Gamefic
       response.verb
     end
 
+    def narrative
+      response.narrative
+    end
+
     def meta?
       response.meta?
     end

data/lib/gamefic/active/epic.rb

@@ -47,9 +47,14 @@ module Gamefic
         narratives.one?
       end
 
-      # @param name [Symbol]
-      def conclusion? name
-        select_scene(name).conclusion?
+      def syntaxes
+        rulebooks.flat_map(&:syntaxes)
+      end
+
+      def responses_for(*verbs)
+        rulebooks.to_a
+                 .reverse
+                 .flat_map { |rb| rb.responses_for(*verbs) }
       end
 
       # @param name [Symbol]

data/lib/gamefic/active/take.rb

@@ -16,7 +16,7 @@ module Gamefic
 
       # @param actor [Active]
       # @param cue [Active::Cue]
-      # @param props [Props::Default]
+      # @param props [Props::Default, nil]
       def initialize actor, cue, props = nil
         @actor = actor
         @cue = cue
@@ -31,12 +31,12 @@ module Gamefic
 
       # @return [Props::Default]
       def start
-        actor.output[:scene] = scene.to_hash
+        props.output[:scene] = scene.to_hash
         scene.run_start_blocks actor, props
         scene.start actor, props
         # @todo See if this can be handled better
-        actor.epic.rulebooks.each { |rlbk| rlbk.run_player_output_blocks actor, actor.output }
-        actor.output.merge!({
+        actor.epic.rulebooks.each { |rlbk| rlbk.run_player_output_blocks actor, props.output }
+        props.output.merge!({
                               messages: actor.messages,
                               queue: actor.queue
                             })
@@ -47,7 +47,7 @@ module Gamefic
       def finish
         actor.flush
         scene.finish(actor, props)
-        actor.output.replace(last_prompt: props.prompt, last_input: props.input)
+        props.output.replace(last_prompt: props.prompt, last_input: props.input)
         scene.run_finish_blocks actor, props
       end
 

data/lib/gamefic/active.rb

@@ -21,6 +21,9 @@ module Gamefic
     # @return [Active::Cue, nil]
     attr_reader :next_cue
 
+    # @return [String, nil]
+    attr_reader :last_input
+
     # @return [Symbol, nil]
     def next_scene
       next_cue&.scene
@@ -48,12 +51,22 @@ module Gamefic
       @queue ||= []
     end
 
-    # A hash of data that will be sent to the user. The output is typically
-    # sent after a scene has started and before the user is prompted for input.
+    # Data that will be sent to the user. The output is typically sent after a
+    # scene has started and before the user is prompted for input.
+    #
+    # The output object attached to the actor is always frozen. Authors should
+    # use on_player_output blocks to modify output to be sent to the user.
     #
-    # @return [Hash]
+    # @return [Props::Output]
     def output
-      @output ||= {}
+      @output ||= Props::Output.new.freeze
+    end
+
+    # The output from the previous turn.
+    #
+    # @return [Props::Output]
+    def last_output
+      @last_output ||= output
     end
 
     # Perform a command.
@@ -65,11 +78,10 @@ module Gamefic
     #   character.perform "take the key"
     #
     # @param command [String]
-    # @return [void]
+    # @return [Action, nil]
     def perform(command)
       dispatchers.push Dispatcher.dispatch(self, command)
-      dispatchers.last.execute
-      dispatchers.pop
+      dispatchers.last.execute.tap { dispatchers.pop }
     end
 
     # Quietly perform a command.
@@ -95,11 +107,10 @@ module Gamefic
     #
     # @param verb [Symbol]
     # @param params [Array]
-    # @return [Gamefic::Action]
+    # @return [Action, nil]
     def execute(verb, *params)
       dispatchers.push Dispatcher.dispatch_from_params(self, verb, params)
-      dispatchers.last.execute
-      dispatchers.pop
+      dispatchers.last.execute.tap { dispatchers.pop }
     end
 
     # Proceed to the next Action in the current stack.
@@ -125,9 +136,9 @@ module Gamefic
     #     end
     #   end
     #
-    # @return [void]
+    # @return [Action, nil]
     def proceed
-      dispatchers.last&.proceed&.execute
+      dispatchers.last&.proceed
     end
 
     # Cue a scene to start in the next turn.
@@ -146,17 +157,22 @@ module Gamefic
     end
     alias prepare cue
 
+    # @return [void]
     def start_take
       ensure_cue
       @last_cue = @next_cue
       cue :default_scene
       @props = Take.start(self, @last_cue)
+      @last_output = self.output
+      @output = @props.output.dup.freeze
     end
 
+    # @return [void]
     def finish_take
       return unless @last_cue
 
       Take.finish(self, @last_cue, @props)
+      @last_input = @props.input
     end
 
     # Restart the scene from the most recent cue.
@@ -175,6 +191,7 @@ module Gamefic
     #
     # @param new_scene [Symbol]
     # @oaram context [Hash] Additional scene data
+    # @return [Cue]
     def conclude scene, **context
       cue scene, **context
       available = epic.select_scene(scene)
@@ -186,7 +203,7 @@ module Gamefic
     # True if the actor is ready to leave the game.
     #
     def concluding?
-      epic.empty? || (@last_cue && epic.conclusion?(@last_cue.scene))
+      epic.empty? || @props&.scene&.type == 'Conclusion'
     end
 
     def accessible?

data/lib/gamefic/command.rb

@@ -1,31 +1,20 @@
 # frozen_string_literal: true
 
 module Gamefic
-  # A decomposition of a text-based command into its verb and arguments.
-  #
-  # Commands are typically derived from tokenization against syntaxes.
+  # A concrete representation of an input as a verb and an array of arguments.
   #
   class Command
     # @return [Symbol]
     attr_reader :verb
 
-    # @return [Array<String>]
+    # @return [Array<Array<Entity>, Entity, String>]
     attr_reader :arguments
 
+    # @param verb [Symbol]
+    # @param arguments [Array<Array<Entity>, Entity, String>]
     def initialize verb, arguments
       @verb = verb
       @arguments = arguments
     end
-
-    # Compare two syntaxes for the purpose of ordering them by relevance while
-    # dispatching.
-    #
-    def compare other
-      if verb == other.verb
-        other.arguments.compact.length <=> arguments.compact.length
-      else
-        (other.verb ? 1 : 0) <=> (verb ? 1 : 0)
-      end
-    end
   end
 end

data/lib/gamefic/composer.rb

@@ -0,0 +1,68 @@
+module Gamefic
+  # A function module for creating commands from expressions.
+  #
+  module Composer
+    # Create a command from the first expression that matches a response.
+    #
+    # @param actor [Actor]
+    # @param expressions [Array<Expression>]
+    # @return [Command]
+    def self.compose actor, expressions
+      %i[strict fuzzy].each do |method|
+        result = match_expressions_to_response actor, expressions, method
+        return result if result
+      end
+      Command.new(nil, [])
+    end
+
+    class << self
+      private
+
+      def match_expressions_to_response actor, expressions, method
+        expressions.each do |expression|
+          result = match_response_arguments actor, expression, method
+          return result if result
+        end
+        nil
+      end
+
+      def match_response_arguments actor, expression, method
+        actor.epic.responses_for(expression.verb).each do |response|
+          next unless response.queries.length >= expression.tokens.length
+
+          result = match_query_arguments(actor, expression, response, method)
+          return result if result
+        end
+        nil
+      end
+
+      def match_query_arguments actor, expression, response, method
+        remainder = response.verb ? '' : expression.verb.to_s
+        arguments = []
+        response.queries.each_with_index do |query, idx|
+          result = Scanner.send(method, query.select(actor), "#{remainder} #{expression.tokens[idx]}".strip)
+          break unless validate_result_from_query(result, query)
+
+          if query.ambiguous?
+            arguments.push result.matched
+          else
+            arguments.push result.matched.first
+          end
+          remainder = result.remainder
+        end
+
+        return nil if arguments.length != response.queries.length || remainder != ''
+
+        Command.new(response.verb, arguments)
+      end
+
+      # @param result [Scanner::Result]
+      # @param query [Query::Base]
+      def validate_result_from_query result, query
+        return false if result.matched.empty?
+
+        result.matched.length == 1 || query.ambiguous?
+      end
+    end
+  end
+end

data/lib/gamefic/dispatcher.rb

@@ -1,63 +1,54 @@
 # frozen_string_literal: true
 
 module Gamefic
-  # The action selector for character commands.
+  # The action executor for character commands.
   #
   class Dispatcher
     # @param actor [Actor]
-    # @param commands [Array<Command>]
-    # @param responses [Array<Response>]
-    def initialize actor, commands = [], responses = []
+    # @param command [Command]
+    def initialize actor, command
       @actor = actor
-      @commands = commands
-      @responses = responses
+      @command = command
       @executed = false
+      @finalized = false
     end
 
     # Run the dispatcher.
     #
+    # @return [Action, nil]
     def execute
       return if @executed
 
-      action = proceed
+      @executed = true
+      action = next_action
       return unless action
 
-      @executed = action.arguments
       run_before_action_hooks action
       return if action.cancelled?
 
       action.execute
       run_after_action_hooks action
+      action
     end
 
-    # Get the next executable action.
+    # Execute the next available action.
+    #
+    # Actors should run #execute first.
     #
     # @return [Action, nil]
     def proceed
-      while (response = responses.shift)
-        commands.each do |cmd|
-          action = response.attempt(actor, cmd)
-          next unless action && arguments_match?(action.arguments)
+      return unless @executed
 
-          return action
-        end
-      end
-      nil # Without this, return value in Opal is undefined
+      next_action&.execute
     end
 
     # @param actor [Active]
     # @param input [String]
     # @return [Dispatcher]
     def self.dispatch actor, input
-      commands = Syntax.tokenize(input, actor.epic.rulebooks.flat_map(&:syntaxes))
-      verbs = commands.map(&:verb).uniq
-      responses = actor.epic
-                       .rulebooks
-                       .to_a
-                       .reverse
-                       .flat_map { |pb| pb.responses_for(*verbs) }
-                       .reject(&:hidden?)
-      new(actor, commands, responses)
+      expressions = Syntax.tokenize(input, actor.epic.syntaxes)
+      command = Composer.compose(actor, expressions)
+      new(actor, command)
     end
 
     # @param actor [Active]
@@ -66,12 +57,7 @@ module Gamefic
     # @return [Dispatcher]
     def self.dispatch_from_params actor, verb, params
       command = Command.new(verb, params)
-      responses = actor.epic
-                       .rulebooks
-                       .to_a
-                       .reverse
-                       .flat_map { |pb| pb.responses_for(verb) }
-      new(actor, [command], responses)
+      new(actor, command)
     end
 
     protected
@@ -79,27 +65,48 @@ module Gamefic
     # @return [Actor]
     attr_reader :actor
 
-    # @return [Array<Command>]
-    attr_reader :commands
+    # @return [Command]
+    attr_reader :command
 
     # @return [Array<Response>]
-    attr_reader :responses
+    def responses
+      @responses ||= actor.epic.responses_for(command.verb)
+    end
 
     private
 
-    # After the first action gets selected, subsequent actions need to use the
-    # same arguments.
-    #
-    def arguments_match? arguments
-      !@executed || arguments == @executed
+    # @return [Action, nil]
+    def next_action
+      while (response = responses.shift)
+        next if response.queries.length < @command.arguments.length
+
+        return Action.new(actor, @command.arguments, response) if response.accept?(actor, @command)
+      end
+      finalize
     end
 
+    # @return [void]
     def run_before_action_hooks action
       actor.epic.rulebooks.flat_map { |rlbk| rlbk.run_before_actions action }
     end
 
+    # @return [void]
     def run_after_action_hooks action
       actor.epic.rulebooks.flat_map { |rlbk| rlbk.run_after_actions action }
     end
+
+    # If the dispatcher proceeds through all possible responses, it can fall
+    # back to a nil response as a catchall for commands that could not be
+    # completed.
+    #
+    # @return [Action, nil]
+    def finalize
+      return nil if @finalized
+
+      @finalized = true
+      @command = Command.new(nil, ["#{command.verb} #{command.arguments.join(' ').strip}"])
+      @responses = actor.epic.responses_for(nil)
+      next_action
+    end
   end
 end

data/lib/gamefic/entity.rb

@@ -9,7 +9,6 @@ module Gamefic
   class Entity
     include Describable
     include Node
-    # include Messaging
 
     def initialize **args
       klass = self.class
@@ -57,14 +56,13 @@ module Gamefic
     end
 
     class << self
-      # Set or update the default values for new instances.
+      # Set or update the default attributes for new instances.
       #
-      # @param attrs [Hash] The attributes to be merged into the defaults.
-      def set_default attrs = {}
+      def set_default **attrs
         default_attributes.merge! attrs
       end
 
-      # A hash of default values for attributes when creating an instance.
+      # A hash of default attributes when creating an instance.
       #
       # @return [Hash]
       def default_attributes

data/lib/gamefic/expression.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Gamefic
+  # A tokenization of an input from available syntaxes.
+  #
+  class Expression
+    # @return [Symbol]
+    attr_reader :verb
+
+    # @return [Array<String>]
+    attr_reader :tokens
+
+    # @param verb [Symbol, nil]
+    # @param tokens [Array<String>]
+    def initialize verb, tokens
+      @verb = verb
+      @tokens = tokens
+    end
+
+    # Compare two syntaxes for the purpose of ordering them by relevance while
+    # dispatching.
+    #
+    def compare other
+      if verb == other.verb
+        other.tokens.compact.length <=> tokens.compact.length
+      else
+        (other.verb ? 1 : 0) <=> (verb ? 1 : 0)
+      end
+    end
+  end
+end

data/lib/gamefic/plot.rb

@@ -9,8 +9,8 @@ module Gamefic
       super
       subplots.each(&:ready)
       players.each(&:start_take)
-      subplots.delete_if(&:concluding?)
       players.select(&:concluding?).each { |plyr| rulebook.run_player_conclude_blocks plyr }
+      subplots.delete_if(&:concluding?)
     end
 
     def update

data/lib/gamefic/props/default.rb

@@ -2,6 +2,8 @@
 
 module Gamefic
   module Props
+    SceneData = Struct.new(:name, :type)
+
     # 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.
@@ -25,17 +27,23 @@ module Gamefic
       attr_reader :context
       alias data context
 
-      # @param scene [Scene, nil]
+      # @return [SceneData]
+      attr_reader :scene
+
+      # @param scene [Scene]
       # @param context [Hash]
-      def initialize name, type, **context
-        @scene_name = name
-        @scene_type = type
+      def initialize scene, **context
+        @scene = SceneData.new(scene.name, scene.type)
         @context = context
       end
 
       def prompt
         @prompt ||= '>'
       end
+
+      def output
+        @output ||= Props::Output.new
+      end
     end
   end
 end

data/lib/gamefic/props/output.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Props
+    # A container for output sent to players with a hash interface for custom
+    # data.
+    #
+    class Output
+      # @return [String, nil]
+      attr_reader :last_input
+
+      # @return [String, nil]
+      attr_reader :last_prompt
+
+      def initialize **data
+        @raw_data = {
+          messages: '',
+          options: [],
+          queue: [],
+          scene: {},
+          prompt: ''
+        }
+        merge! data
+      end
+
+      # @return [String]
+      def messages
+        raw_data[:messages]
+      end
+
+      # @return [Array<String>]
+      def options
+        raw_data[:options]
+      end
+
+      # @return [Array<String>]
+      def queue
+        raw_data[:queue]
+      end
+
+      # @todo Should this be a concrete class?
+      # @return [Hash]
+      def scene
+        raw_data[:scene]
+      end
+
+      # @return [String]
+      def prompt
+        raw_data[:prompt]
+      end
+
+      def [] key
+        raw_data[key]
+      end
+
+      def []= key, value
+        raw_data[key] = value
+      end
+
+      # @return [Hash]
+      def to_hash
+        raw_data.dup
+      end
+
+      def to_json _ = nil
+        raw_data.to_json
+      end
+
+      def merge! data
+        data.each { |key, val| self[key] = val }
+      end
+
+      def replace data
+        raw_data.replace data
+      end
+
+      private
+
+      attr_reader :raw_data
+    end
+  end
+end

data/lib/gamefic/props.rb

@@ -6,5 +6,6 @@ module Gamefic
     require 'gamefic/props/multiple_choice'
     require 'gamefic/props/pause'
     require 'gamefic/props/yes_or_no'
+    require 'gamefic/props/output'
   end
 end

data/lib/gamefic/query/base.rb

@@ -24,6 +24,12 @@ module Gamefic
         @ambiguous = ambiguous
       end
 
+      # @deprecated Queries should only be used to select entities that are
+      #   eligible to be response arguments. After a text command is tokenized
+      #   into an array of expressions, the composer builds the command that
+      #   the dispatcher uses to execute actions. The #accept? method verifies
+      #   that the command's arguments match the response's queries.
+      #
       # @param subject [Gamefic::Entity]
       # @param token [String]
       # @return [Result]
@@ -31,6 +37,24 @@ module Gamefic
         raise "#query not implemented for #{self.class}"
       end
 
+      # Get an array of entities that match the query from the context of the
+      # subject.
+      #
+      # @param subject [Entity]
+      # @return [Array<Entity>]
+      def select subject
+        raise "#select not implemented for #{self.class}"
+      end
+
+      def accept?(subject, object)
+        available = select(subject)
+        if ambiguous?
+          object & available == object
+        else
+          available.include?(object)
+        end
+      end
+
       # @return [Integer]
       def precision
         @precision ||= calculate_precision

data/lib/gamefic/query/general.rb

@@ -19,6 +19,10 @@ module Gamefic
         @entities = entities
       end
 
+      def select subject
+        available_entities(subject).that_are(*@arguments)
+      end
+
       def query subject, token
         filtered = available_entities(subject).that_are(*@arguments)
         return Result.new(token, nil) if filtered.include?(token)

data/lib/gamefic/query/scoped.rb

@@ -16,6 +16,11 @@ module Gamefic
         @scope = scope
       end
 
+      def select(subject)
+        @scope.matches(subject)
+              .that_are(*@arguments)
+      end
+
       # @return [Result]
       def query(subject, token)
         available = @scope.matches(subject)

data/lib/gamefic/query/text.rb

@@ -5,12 +5,17 @@ module Gamefic
     # A special query that handles text instead of entities.
     #
     class Text
-      # @param argument [String, Regexp, nil]
-      def initialize argument = nil
+      # @param argument [String, Regexp]
+      def initialize argument = /.*/
         @argument = argument
         validate
       end
 
+      # @return [String, Regexp]
+      def select(_subject)
+        @argument
+      end
+
       def query _subject, token
         if match? token
           Result.new(token, '')
@@ -23,11 +28,17 @@ module Gamefic
         0
       end
 
+      def accept? _subject, argument
+        match? argument
+      end
+
+      def ambiguous?
+        true
+      end
+
       private
 
       def match? token
-        return true if @argument.nil?
-
         case @argument
         when Regexp
           token =~ @argument
@@ -37,7 +48,7 @@ module Gamefic
       end
 
       def validate
-        return if @argument.nil? || @argument.is_a?(String) || @argument.is_a?(Regexp)
+        return if @argument.is_a?(String) || @argument.is_a?(Regexp)
 
         raise ArgumentError, 'Invalid text query argument'
       end

data/lib/gamefic/response.rb

@@ -1,4 +1,4 @@
-# frozen_literal_string: true
+# frozen_string_literal: true
 
 module Gamefic
   # A proc to be executed in response to a command that matches its verb and
@@ -11,17 +11,17 @@ module Gamefic
     # @return [Array<Query::Base>]
     attr_reader :queries
 
-    # @return [Proc]
-    # attr_reader :block
+    # @return [Narrative]
+    attr_reader :narrative
 
     # @param verb [Symbol]
-    # @param stage [Object]
+    # @param narrative [Narrative]
     # @param queries [Array<Query::Base>]
     # @param meta [Boolean]
     # @param block [Proc]
-    def initialize verb, stage, *queries, meta: false, &block
+    def initialize verb, narrative, *queries, meta: false, &block
       @verb = verb
-      @stage = stage
+      @narrative = narrative
       @queries = map_queryable_objects(queries)
       @meta = meta
       @block = block
@@ -48,35 +48,29 @@ module Gamefic
     #
     # @param actor [Entity]
     # @param command [Command]
-    # @param with_hooks [Boolean]
     # @return [Action, nil]
     def attempt actor, command
-      return nil if command.verb != verb
+      return nil unless accept?(actor, command)
 
-      tokens = command.arguments.clone
-      result = []
-      remainder = ''
-
-      queries.each do |qd|
-        token = tokens.shift
-        txt = "#{remainder} #{token}".strip
-        return nil if txt.empty?
-
-        response = qd.query(actor, txt)
-        return nil if response.match.nil?
+      Action.new(actor, command.arguments, self)
+    end
 
-        result.push response.match
+    # True if the Response can be executed for the given actor and command.
+    #
+    # @param actor [Active]
+    # @param command [Command]
+    def accept? actor, command
+      return false if command.verb != verb || command.arguments.length != queries.length
 
-        remainder = response.remainder
+      queries.each_with_index do |query, idx|
+        return false unless query.accept?(actor, command.arguments[idx])
       end
 
-      return nil unless tokens.empty? && remainder.empty?
-
-      Action.new(actor, result, self)
+      true
     end
 
     def execute *args
-      Stage.run(@stage, *args, &@block)
+      Stage.run(narrative, *args, &@block)
     end
 
     def precision

data/lib/gamefic/rulebook/events.rb

@@ -34,16 +34,16 @@ module Gamefic
         self
       end
 
-      # @return [Proc]
+      # @return [void]
       def on_ready &block
         @ready_blocks.push block
       end
 
       # @yieldparam [Actor]
-      # @return [Proc]
+      # @return [void]
       def on_player_ready &block
         @ready_blocks.push(proc do
-          players.each { |plyr| block.call plyr }
+          players.each { |plyr| instance_exec plyr, &block }
         end)
       end
 
@@ -53,24 +53,24 @@ module Gamefic
 
       def on_player_update &block
         @update_blocks.push(proc do
-          players.each { |plyr| block.call plyr }
+          players.each { |plyr| instance_exec plyr, &block }
         end)
       end
 
-      # @return [Proc]
+      # @return [void]
       def on_conclude &block
         @conclude_blocks.push block
       end
 
       # @yieldparam [Actor]
-      # @return [Proc]
+      # @return [void]
       def on_player_conclude &block
         @player_conclude_blocks.push block
       end
 
       # @yieldparam [Actor]
       # @yieldparam [Hash]
-      # @return [Proc]
+      # @return [void]
       def on_player_output &block
         @player_output_blocks.push block
       end

data/lib/gamefic/rulebook.rb

@@ -116,11 +116,11 @@ module Gamefic
     end
 
     def run_player_conclude_blocks player
-      events.player_conclude_blocks.each { |blk| Stage.run(narrative) { blk.call(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) { blk.call(player, output) } }
+      events.player_output_blocks.each { |blk| Stage.run(narrative, player, output, &blk) }
     end
 
     def empty?

data/lib/gamefic/scanner.rb

@@ -11,7 +11,7 @@ module Gamefic
     class Result
       # The scanned objects
       #
-      # @return [Array<Object>]
+      # @return [Array<Entity>, String, Regexp]
       attr_reader :scanned
 
       # The scanned token
@@ -21,7 +21,7 @@ module Gamefic
 
       # The matched objects
       #
-      # @return [Array<Object>]
+      # @return [Array<Entity>, String]
       attr_reader :matched
 
       # The remaining (unmatched) portion of the token
@@ -39,36 +39,53 @@ module Gamefic
 
     # Scan entities against a token.
     #
-    # @param objects [Array<Gamefic::Entity>]
+    # @param selection [Array<Entity>, String, Regexp]
     # @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
+    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
@@ -81,6 +98,16 @@ module Gamefic
         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

data/lib/gamefic/scene/default.rb

@@ -30,7 +30,7 @@ module Gamefic
       end
 
       def new_props(**context)
-        self.class.props_class.new(name, type, **context)
+        self.class.props_class.new(self, **context)
       end
 
       def on_start &block
@@ -45,8 +45,8 @@ module Gamefic
       # @param props [Props::Default]
       # @return [void]
       def start actor, props
-        actor.output[:scene] = to_hash
-        actor.output[:prompt] = props.prompt
+        props.output[:scene] = to_hash
+        props.output[:prompt] = props.prompt
       end
 
       # @param actor [Gamefic::Actor]

data/lib/gamefic/scene/multiple_choice.rb

@@ -10,7 +10,7 @@ module Gamefic
 
       def start actor, props
         super
-        actor.output[:options] = props.options
+        props.output[:options] = props.options
       end
 
       def finish actor, props

data/lib/gamefic/scriptable/entities.rb

@@ -55,7 +55,10 @@ module Gamefic
       # @param description [String]
       # @return [Gamefic::Entity, nil]
       def pick description
-        Gamefic::Query::General.new(entities).query(nil, description).match
+        result = Scanner.scan(entities, description)
+        return nil unless result.matched.one?
+
+        result.matched.first
       end
 
       # Same as #pick, but raise an error if a unique match could not be found.
@@ -63,13 +66,13 @@ module Gamefic
       # @param description [String]
       # @return [Gamefic::Entity, nil]
       def pick! description
-        ary = Gamefic::Query::General.new(entities, ambiguous: true).query(nil, description).match
+        result = Scanner.scan(entities, description)
 
-        raise "no entity matching '#{description}'" if ary.nil?
+        raise "no entity matching '#{description}'" if result.matched.empty?
 
-        raise "multiple entities matching '#{description}': #{ary.join_and}" unless ary.one?
+        raise "multiple entities matching '#{description}': #{result.matched.join_and}" unless result.matched.one?
 
-        ary.first
+        result.matched.first
       end
     end
   end

data/lib/gamefic/scriptable/proxy.rb

@@ -15,6 +15,15 @@ module Gamefic
         end
 
         def fetch container
+          result = safe_fetch(container)
+          raise ArgumentError, "Unable to fetch entity from proxy agent symbol `#{symbol}`" unless result
+
+          result
+        end
+
+        private
+
+        def safe_fetch container
           if symbol.to_s =~ /^\d+$/
             Stage.run(container, symbol) { |sym| entities[sym] }
           elsif symbol.to_s.start_with?('@')
@@ -22,6 +31,8 @@ module Gamefic
           else
             Stage.run(container, symbol) { |sym| send(sym) }
           end
+        rescue NoMethodError
+          nil
         end
       end
 

data/lib/gamefic/scriptable/queries.rb

@@ -63,9 +63,9 @@ module Gamefic
       # any text it finds in the command. A successful query returns the
       # corresponding text instead of an entity.
       #
-      # @param arg [String, Regrxp] The string or regular expression to match
+      # @param arg [String, Regexp] The string or regular expression to match
       # @return [Query::Text]
-      def plaintext arg = nil
+      def plaintext arg = /.*/
         Query::Text.new arg
       end
     end

data/lib/gamefic/scriptable/scenes.rb

@@ -32,8 +32,8 @@ module Gamefic
       # @param block [Proc]
       # @yieldparam [Scene]
       # @return [Symbol]
-      def block name, klass = Scene::Default, on_start: nil, on_finish: nil, &block
-        rulebook.scenes.add klass.new(name, rulebook.narrative, on_start: on_start, on_finish: on_finish, &block)
+      def block name, klass = Scene::Default, on_start: nil, on_finish: nil, &blk
+        rulebook.scenes.add klass.new(name, rulebook.narrative, on_start: on_start, on_finish: on_finish, &blk)
         name
       end
       alias scene block
@@ -77,14 +77,14 @@ module Gamefic
       # @yieldparam [Actor]
       # @yieldparam [Props::MultipleChoice]
       # @return [Symbol]
-      def multiple_choice name, choices = [], prompt = 'What is your choice?', &block
+      def multiple_choice name, choices = [], prompt = 'What is your choice?', &blk
         block name,
               Scene::MultipleChoice,
               on_start: proc { |_actor, props|
                 props.prompt = prompt
                 props.options.concat choices
               },
-              on_finish: block
+              on_finish: blk
       end
 
       # Create a yes-or-no scene.
@@ -105,13 +105,13 @@ module Gamefic
       # @yieldparam [Actor]
       # @yieldparam [Props::YesOrNo]
       # @return [Symbol]
-      def yes_or_no name, prompt = 'Answer:', &block
+      def yes_or_no name, prompt = 'Answer:', &blk
         block name,
               Scene::YesOrNo,
               on_start: proc { |_actor, props|
                 props.prompt = prompt
               },
-              on_finish: block
+              on_finish: blk
       end
 
       # Create a scene that pauses the game.

data/lib/gamefic/snapshot.rb

@@ -27,10 +27,18 @@ module Gamefic
       Marshal.load(binary).tap do |plot|
         plot.hydrate
         # @todo Opal marshal dumps are not idempotent
-        next if RUBY_ENGINE == 'opal' || Snapshot.save(plot) == snapshot
+        next if RUBY_ENGINE == 'opal' || match?(plot, snapshot)
 
         Logging.logger.warn "Scripts modified #{plot.class} data. Snapshot may not have restored properly"
       end
     end
+
+    # True if the plot's state matches the snapshot.
+    #
+    # @param plot [Plot]
+    # @param snapshot [String]
+    def self.match?(plot, snapshot)
+      save(plot) == snapshot
+    end
   end
 end

data/lib/gamefic/syntax.rb

@@ -61,12 +61,12 @@ module Gamefic
     # Convert a String into a Command.
     #
     # @param text [String]
-    # @return [Command, nil]
+    # @return [Expression, nil]
     def tokenize text
       match = text&.match(template.regexp)
       return nil unless match
 
-      Command.new(verb, match_to_args(match))
+      Expression.new(verb, match_to_args(match))
     end
 
     # Determine if the specified text matches the syntax's expected pattern.
@@ -94,7 +94,7 @@ module Gamefic
     #
     # @param text [String] The text to tokenize.
     # @param syntaxes [Array<Syntax>] The syntaxes to use.
-    # @return [Array<Command>] The tokenized commands.
+    # @return [Array<Expression>] The tokenized expressions.
     def self.tokenize text, syntaxes
       syntaxes
         .map { |syn| syn.tokenize(text) }
@@ -109,7 +109,7 @@ module Gamefic
     end
 
     # @param string [String]
-    # @return [String, nil]
+    # @return [Symbol, nil]
     def self.literal_or_nil string
       string.start_with?(':') ? nil : string.to_sym
     end

data/lib/gamefic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Gamefic
-  VERSION = '3.0.0'
+  VERSION = '3.1.0'
 end

data/lib/gamefic.rb

@@ -11,6 +11,7 @@ require 'gamefic/rulebook'
 require 'gamefic/query'
 require 'gamefic/scanner'
 require 'gamefic/scope'
+require 'gamefic/expression'
 require 'gamefic/command'
 require 'gamefic/action'
 require 'gamefic/props'
@@ -27,6 +28,7 @@ require 'gamefic/node'
 require 'gamefic/describable'
 require 'gamefic/messenger'
 require 'gamefic/entity'
+require 'gamefic/composer'
 require 'gamefic/dispatcher'
 require 'gamefic/active'
 require 'gamefic/active/cue'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gamefic
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Fred Snyder
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-27 00:00:00.000000000 Z
+date: 2024-04-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opal
@@ -136,11 +136,13 @@ files:
 - lib/gamefic/actor.rb
 - lib/gamefic/block.rb
 - lib/gamefic/command.rb
+- lib/gamefic/composer.rb
 - lib/gamefic/core_ext/array.rb
 - lib/gamefic/core_ext/string.rb
 - lib/gamefic/describable.rb
 - lib/gamefic/dispatcher.rb
 - lib/gamefic/entity.rb
+- lib/gamefic/expression.rb
 - lib/gamefic/logging.rb
 - lib/gamefic/messenger.rb
 - lib/gamefic/narrative.rb
@@ -149,6 +151,7 @@ files:
 - lib/gamefic/props.rb
 - lib/gamefic/props/default.rb
 - lib/gamefic/props/multiple_choice.rb
+- lib/gamefic/props/output.rb
 - lib/gamefic/props/pause.rb
 - lib/gamefic/props/yes_or_no.rb
 - lib/gamefic/query.rb