gamefic 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79b61813b56cbbabb76ecbef9abb370b2fe77b58ea3e155377f8c4dfd2677684
-  data.tar.gz: 611c108a0c080796c8308bee5f3e361c60fc4ddd316234bf9468c09742b1a52d
+  metadata.gz: 79309729d2296ceec16e10d3380fba331512f15ca2d303788c1fbcc83c077457
+  data.tar.gz: f4ce7d947730da4e833d895ae3085c4027d80cf89306b3aeff03d1a2a6ecd2aa
 SHA512:
-  metadata.gz: 85732c76dae467bd5d032462ca23d34b03b7be59c6327202fd9bef307ef3d06bc40af085f32010cfae9dfd93a85b20524785313388964772534632cc95159625
-  data.tar.gz: 5c3db85ff44b268bd7604d33e28b92ca454c82c2a812f023af39a3da816a4252dfea01869d313f1ab6d24a1f062782ac002f5bf8fc40fd435efaa0c1ac14d337
+  metadata.gz: 01c7c68bdc217447d90bda4c2bdd362e318c644dc3486999f6125d6c124193e0b33782a250272a2455ea98e2f531551f3819611c4139b191d3dccaa61d9e03d8
+  data.tar.gz: '06101965d9a47188f2b5b22e87f4f7b4bbeefd5f102d2405e1457c8a389a732e782cd4eedccec2176f2b237ad3783b1ab0058ce2721e451caa29e4e8a6d52cdc'

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 3.5.0
+- Configurable scanners
+- Refactored scanners and queries
+- Allow assignment to nil instance variables in stage
+- Lazy proxies
+- Remove buggy index proxies
+- Chapter inherits Narrative
+- Plot attribute proxy for chapters and subplots
+- Entity#leave
+- Descendants query
+- Persistent subplots
+- Entity#broadcast
+- Ascendants in family query
+
 ## 3.4.0 - September 10, 2024
 - Chapters
 - Subplots and chapters do not repeat plot scripts

data/README.md

@@ -16,7 +16,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/castwide/gamefic-sdk.
+Bug reports and pull requests are welcome on GitHub at https://github.com/castwide/gamefic.
 
 ## License
 

data/lib/gamefic/active/epic.rb

@@ -51,6 +51,7 @@ module Gamefic
         rulebooks.flat_map(&:syntaxes)
       end
 
+      # @return [Array<Response>]
       def responses_for(*verbs)
         rulebooks.to_a
                  .reverse

data/lib/gamefic/active.rb

@@ -212,6 +212,10 @@ module Gamefic
       false
     end
 
+    def acting?
+      !epic.empty?
+    end
+
     private
 
     # @return [Array<Dispatcher>]

data/lib/gamefic/chapter.rb

@@ -6,17 +6,15 @@ module Gamefic
   # adding the required instance variables, methods, and attributes to the
   # plot.
   #
-  # Chapters are similar to subplots with a few important exceptions:
-  # * Chapters persist for the duration of the plot.
+  # Chapters are similar to subplots with three important exceptions:
+  # * Chapters normally persist for the duration of a plot.
   # * Players do not need to be introduced to a chapter.
-  # * Scripts in chapters apply to the parent plot's rulebook.
-  # * Using `make` to create an entity in a chapter adds it to the parent
-  #   plot's entity list.
+  # * Chapters share their plot's entities, players, and rulebook.
   #
   # @example
   #   class MyChapter < Gamefic::Chapter
-  #     seed do
-  #       @thing = make Gamefic::Entity, name: 'chapter thing'
+  #     def thing
+  #       @thing ||= make Gamefic::Entity, name: 'chapter thing'
   #     end
   #   end
   #
@@ -25,64 +23,49 @@ module Gamefic
   #   end
   #
   #   plot = MyPlot.new
-  #   plot.entities                 #=> [<#Gamefic::Entity a chapter thing>]
-  #   plot.instance_exec { @thing } #=> nil
+  #   plot.entities             #=> [<#Gamefic::Entity a chapter thing>]
+  #   plot.thing                #   raises NoMethodError
+  #   plot.chapters.first.thing #=> <#Gamefic::Entity a chapter thing>
   #
-  class Chapter
-    extend Scriptable
-
-    include Scriptable::Actions
-    include Scriptable::Events
-    include Scriptable::Proxy
-    include Scriptable::Queries
-    include Scriptable::Scenes
+  class Chapter < Narrative
+    extend Scriptable::PlotProxies
 
     # @return [Plot]
     attr_reader :plot
 
     # @param plot [Plot]
-    def initialize plot
+    def initialize(plot)
       @plot = plot
-    end
-
-    def included_blocks
-      self.class.included_blocks - plot.included_blocks
-    end
-
-    def seed
-      included_blocks.select(&:seed?).each { |blk| Stage.run self, &blk.code }
+      # The plot is responsible for hydrating chapters
+      super(hydrate: false)
     end
 
     def script
       included_blocks.select(&:script?).each { |blk| Stage.run self, &blk.code }
     end
 
-    def rulebook
-      plot.rulebook
-    end
-
-    def make klass, **opts
-      plot.make klass, **opts
+    def included_blocks
+      self.class.included_blocks - plot.included_blocks
     end
 
-    def entities
-      plot.entities
+    def rulebook
+      plot.rulebook
     end
 
-    def players
-      plot.players
+    def entity_vault
+      plot.entity_vault
     end
 
-    def destroy entity
-      plot.destroy entity
+    def player_vault
+      plot.player_vault
     end
 
-    def pick description
-      plot.pick description
+    def subplots
+      plot.subplots
     end
 
-    def pick! description
-      plot.pick! description
+    def branch(...)
+      plot.branch(...)
     end
   end
 end

data/lib/gamefic/command.rb

@@ -10,11 +10,50 @@ module Gamefic
     # @return [Array<Array<Entity>, Entity, String>]
     attr_reader :arguments
 
+    # @return [Integer]
+    attr_reader :strictness
+
+    # @return [Integer]
+    attr_reader :precision
+
     # @param verb [Symbol]
     # @param arguments [Array<Array<Entity>, Entity, String>]
-    def initialize verb, arguments
+    # @param strictness [Integer]
+    # @param precision [Integer]
+    #
+    # @todo Consider making strictness and precision required or providing
+    #   another generator
+    def initialize verb, arguments, strictness = 0, precision = 0
       @verb = verb
       @arguments = arguments
+      @strictness = strictness
+      @precision = precision
+    end
+
+    class << self
+      # Compose a command from input.
+      #
+      # @param actor [Actor]
+      # @param input [String]
+      # @return [Command]
+      def compose actor, input
+        expressions = Syntax.tokenize(input, actor.epic.syntaxes)
+        expressions.flat_map { |expression| expression_to_commands(actor, expression) }
+                   .first || Command.new(nil, [])
+      end
+
+      private
+
+      # @param actor [Actor]
+      # @param expression [Expression]
+      # @return [Array<Command>]
+      def expression_to_commands actor, expression
+        actor.epic
+             .responses_for(expression.verb)
+             .map { |response| response.to_command(actor, expression) }
+             .compact
+             .sort_by.with_index { |result, idx| [-result.precision, -result.strictness, idx] }
+      end
     end
   end
 end

data/lib/gamefic/dispatcher.rb

@@ -10,7 +10,6 @@ module Gamefic
       @actor = actor
       @command = command
       @executed = false
-      @finalized = false
     end
 
     # Run the dispatcher.
@@ -23,11 +22,11 @@ module Gamefic
       action = next_action
       return unless action
 
-      run_before_action_hooks action
+      actor.epic.rulebooks.flat_map { |rlbk| rlbk.run_before_actions action }
       return if action.cancelled?
 
       action.execute
-      run_after_action_hooks action
+      actor.epic.rulebooks.flat_map { |rlbk| rlbk.run_after_actions action }
       action
     end
 
@@ -46,9 +45,9 @@ module Gamefic
     # @param input [String]
     # @return [Dispatcher]
     def self.dispatch actor, input
-      expressions = Syntax.tokenize(input, actor.epic.syntaxes)
-      command = Composer.compose(actor, expressions)
-      new(actor, command)
+      # expressions = Syntax.tokenize(input, actor.epic.syntaxes)
+      # new(actor, Command.compose(actor, expressions))
+      new(actor, Command.compose(actor, input))
     end
 
     # @param actor [Active]
@@ -82,31 +81,6 @@ module Gamefic
 
         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

@@ -55,6 +55,32 @@ module Gamefic
       "#<#{self.class} #{name}>"
     end
 
+    # Move this entity to its parent entity.
+    #
+    # @example
+    #   room =   Gamefic::Entity.new(name: 'room')
+    #   person = Gamefic::Entity.new(name: 'person', parent: room)
+    #   thing =  Gamefic::Entity.new(name: 'thing', parent: person)
+    #
+    #   thing.parent #=> person
+    #   thing.leave
+    #   thing.parent #=> room
+    #
+    # @return [void]
+    def leave
+      self.parent = parent&.parent
+    end
+
+    # Tell a message to all of this entity's accessible descendants.
+    #
+    # @param message [String]
+    # @return [void]
+    def broadcast message
+      Query::Scoped.new(Scope::Descendants).select(self)
+                                           .that_are(Active, proc(&:acting?))
+                                           .each { |actor| actor.tell message }
+    end
+
     class << self
       # Set or update the default attributes for new instances.
       #

data/lib/gamefic/narrative.rb

@@ -14,16 +14,18 @@ module Gamefic
     include Scriptable::Actions
     include Scriptable::Entities
     include Scriptable::Events
-    include Scriptable::Proxy
+    include Scriptable::Proxies
     include Scriptable::Queries
     include Scriptable::Scenes
 
     attr_reader :rulebook
 
-    def initialize
+    def initialize(hydrate: true)
+      return unless hydrate
+
       seed
       script
-      post_initialize
+      post_script
     end
 
     def seed
@@ -35,15 +37,17 @@ module Gamefic
       included_blocks.select(&:script?).each { |blk| Stage.run self, &blk.code }
     end
 
+    # @return [Array<Module>]
     def included_blocks
       self.class.included_blocks
     end
 
-    def post_initialize
+    def post_script
       entity_vault.lock
       rulebook.freeze
     end
 
+    # @return [Array<Symbol>]
     def scenes
       rulebook.scenes.names
     end
@@ -111,7 +115,7 @@ module Gamefic
 
     def hydrate
       script
-      post_initialize
+      post_script
     end
 
     def self.inherited klass

data/lib/gamefic/plot.rb

@@ -16,6 +16,11 @@ module Gamefic
       rulebook.scenes.with_defaults self
     end
 
+    def post_script
+      super
+      chapters.freeze
+    end
+
     def chapters
       @chapters ||= self.class.appended_chapters.map { |klass| klass.new(self) }
     end

data/lib/gamefic/proxy.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Gamefic
+  class Proxy
+    # @return [Symbol]
+    attr_reader :type
+
+    # @return [Symbol, Array<Symbol>, String, Integer]
+    attr_reader :key
+
+    # @param type [Symbol]
+    # @param key [Symbol, String]
+    def initialize type, key
+      @type = type
+      @key = key
+      validate_type
+    end
+
+    def fetch narrative
+      send(type, narrative) ||
+        raise(ArgumentError, "Unable to fetch entity from proxy agent symbol `#{key}`")
+    end
+
+    private
+
+    def attr narrative
+      Stage.run(narrative, [key].flatten) { |keys| keys.inject(self) { |obj, key| obj.send key } }
+    rescue NoMethodError
+      nil
+    end
+
+    def ivar narrative
+      narrative.instance_variable_get key
+    end
+
+    def pick narrative
+      narrative.pick! key
+    end
+
+    def validate_type
+      return if [:attr, :ivar, :pick].include?(type)
+
+      raise ArgumentError, "Invalid proxy type `#{type}` (must be :attr, :ivar, or :pick)"
+    end
+  end
+end

data/lib/gamefic/query/base.rb

@@ -13,6 +13,8 @@ module Gamefic
       # @return [Boolean]
       attr_reader :ambiguous
 
+      attr_accessor :narrative
+
       # @raise [ArgumentError] if any of the arguments are nil
       #
       # @param arguments [Array<Object>]
@@ -26,12 +28,6 @@ module Gamefic
 
       # Get a query result for a given subject and token.
       #
-      # @note This method is retained as a convenience for authors. Narratives
-      #   should use Composer to build commands, as it provides more precise
-      #   matching of tokens to valid response arguments. Authors can use
-      #   #query to find entities that match a token regardless of whether the
-      #   result matches an available response.
-      #
       # @example
       #   respond :reds do |actor|
       #     reds = available(ambiguous: true).query(actor, 'red').match
@@ -41,19 +37,28 @@ module Gamefic
       # @param subject [Gamefic::Entity]
       # @param token [String]
       # @return [Result]
-      def query(_subject, _token)
-        raise "#query not implemented for #{self.class}"
+      def query(subject, token)
+        scan = Scanner.scan(select(subject), token)
+        ambiguous? ? ambiguous_result(scan) : unambiguous_result(scan)
       end
+      alias filter query
 
       # Get an array of entities that match the query from the context of the
       # subject.
       #
+      # Subclasses should override this method.
+      #
       # @param subject [Entity]
       # @return [Array<Entity>]
       def select _subject
-        raise "#select not implemented for #{self.class}"
+        []
       end
 
+      # True if the object is selectable by the subject.
+      #
+      # @param subject [Entity]
+      # @param object [Array<Entity>, Entity]
+      # @return [Boolean]
       def accept?(subject, object)
         available = select(subject)
         if ambiguous?
@@ -75,9 +80,9 @@ module Gamefic
       private
 
       def calculate_precision
-        @arguments.sum(@ambiguous ? -1000 : 0) do |arg|
+        unproxied_arguments.sum(@ambiguous ? -1000 : 0) do |arg|
           case arg
-          when Entity, Scriptable::Proxy::Agent
+          when Entity, Proxy
             1000
           when Class, Module
             class_depth(arg) * 100
@@ -107,7 +112,18 @@ module Gamefic
       def unambiguous_result scan
         return Result.new(nil, scan.token) unless scan.matched.one?
 
-        Result.new(scan.matched.first, scan.remainder)
+        Result.new(scan.matched.first, scan.remainder, scan.strictness)
+      end
+
+      def unproxied_arguments
+        @unproxied_arguments ||= arguments.map do |arg|
+          case arg
+          when Proxy
+            arg.fetch(narrative)
+          else
+            arg
+          end
+        end
       end
     end
   end

data/lib/gamefic/query/general.rb

@@ -20,16 +20,7 @@ module Gamefic
       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)
-
-        scan = Scanner.scan(filtered, token)
-
-        ambiguous? ? ambiguous_result(scan) : unambiguous_result(scan)
+        available_entities(subject).that_are(*unproxied_arguments)
       end
 
       private
@@ -37,9 +28,9 @@ module Gamefic
       def available_entities(subject)
         if @entities.is_a?(Proc)
           if @entities.arity.zero?
-            @entities.call
+            Stage.run narrative, &@entities
           else
-            @entities.call(subject)
+            Stage.run narrative, subject, &@entities
           end
         else
           @entities

data/lib/gamefic/query/result.rb

@@ -11,9 +11,12 @@ module Gamefic
       # @return [String]
       attr_reader :remainder
 
-      def initialize match, remainder
+      attr_reader :strictness
+
+      def initialize match, remainder, strictness = 0
         @match = match
         @remainder = remainder
+        @strictness = strictness
       end
     end
   end

data/lib/gamefic/query/scoped.rb

@@ -17,29 +17,12 @@ module Gamefic
 
       def select(subject)
         @scope.matches(subject)
-              .that_are(*@arguments)
-      end
-
-      # @return [Result]
-      def query(subject, token)
-        available = @scope.matches(subject)
-                          .that_are(*@arguments)
-        return Result.new(token, nil) if available.include?(token)
-
-        scan = Scanner.scan(available, token)
-
-        return ambiguous_result(scan) if ambiguous?
-
-        unambiguous_result(scan)
+              .that_are(*unproxied_arguments)
       end
 
       def precision
         @precision ||= @scope.precision + calculate_precision
       end
-
-      def ambiguous?
-        @ambiguous
-      end
     end
   end
 end

data/lib/gamefic/query/text.rb

@@ -4,16 +4,20 @@ module Gamefic
   module Query
     # A special query that handles text instead of entities.
     #
-    class Text
+    class Text < Base
       # @param argument [String, Regexp]
       def initialize argument = /.*/
-        @argument = argument
+        super
         validate
       end
 
+      def argument
+        arguments.first
+      end
+
       # @return [String, Regexp]
       def select(_subject)
-        @argument
+        argument
       end
 
       def query _subject, token
@@ -23,6 +27,7 @@ module Gamefic
           Result.new(nil, token)
         end
       end
+      alias filter query
 
       def precision
         0
@@ -32,25 +37,21 @@ module Gamefic
         match? argument
       end
 
-      def ambiguous?
-        true
-      end
-
       private
 
       def match? token
-        return false unless token.is_a?(String)
+        return false unless token.is_a?(String) && !token.empty?
 
-        case @argument
+        case argument
         when Regexp
-          token =~ @argument
+          token =~ argument
         else
-          token == @argument
+          token == argument
         end
       end
 
       def validate
-        return if @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