gamefic 3.3.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85e6fc4d2b5c4a9abfe20cbbe17affdec1f1badb134e8cad88849a5305fb9bf0
-  data.tar.gz: 97a29823857d93fafa9e8a3bc4872e27a4a6da480f589535da6abf254eb5aa7a
+  metadata.gz: 79309729d2296ceec16e10d3380fba331512f15ca2d303788c1fbcc83c077457
+  data.tar.gz: f4ce7d947730da4e833d895ae3085c4027d80cf89306b3aeff03d1a2a6ecd2aa
 SHA512:
-  metadata.gz: 611c3b366e76a29cd2ffb95f906882a63ac9d73bfb6d1d7aaa505e4470f4526311704c2245285f908247b6248b086914d8a145e1c9b86577e197d8d77c707939
-  data.tar.gz: dc19cf51ab4edbc1b9f9708eb543c977527e3165a949d948782349e545d0a32fde42f8532c9071e0ddc86b521cc0d1cb778e8e88b1d7b0dcc575d547c5db1df1
+  metadata.gz: 01c7c68bdc217447d90bda4c2bdd362e318c644dc3486999f6125d6c124193e0b33782a250272a2455ea98e2f531551f3819611c4139b191d3dccaa61d9e03d8
+  data.tar.gz: '06101965d9a47188f2b5b22e87f4f7b4bbeefd5f102d2405e1457c8a389a732e782cd4eedccec2176f2b237ad3783b1ab0058ce2721e451caa29e4e8a6d52cdc'

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 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
+- Scriptable.no_scripts is deprecated
+- Refactoring/removing unused methods
+
 ## 3.3.0 - September 1, 2024
 - Node#take
 - Node#include?

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/action.rb

@@ -16,12 +16,12 @@ module Gamefic
       # @param [Array<Symbol>]
       attr_reader :verbs
 
-      # @param [Proc]
-      attr_reader :block
+      # @param [Callback]
+      attr_reader :callback
 
-      def initialize *verbs, &block
+      def initialize verbs, callback
         @verbs = verbs
-        @block = block
+        @callback = callback
       end
 
       def match?(input)

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/callback.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Gamefic
+  class Callback
+    # @param narrative [Narrative]
+    # @param code [Proc]
+    def initialize narrative, code
+      @narrative = narrative
+      @code = code
+    end
+
+    def run *args
+      Stage.run @narrative, *args, &@code
+    end
+  end
+end

data/lib/gamefic/chapter.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Gamefic
+  # Chapters are plot extensions that manage their own namespaces. Authors can
+  # use them to encapsulate related content in a separate object instead of
+  # adding the required instance variables, methods, and attributes to 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.
+  # * Chapters share their plot's entities, players, and rulebook.
+  #
+  # @example
+  #   class MyChapter < Gamefic::Chapter
+  #     def thing
+  #       @thing ||= make Gamefic::Entity, name: 'chapter thing'
+  #     end
+  #   end
+  #
+  #   class MyPlot < Gamefic::Plot
+  #     append MyChapter
+  #   end
+  #
+  #   plot = MyPlot.new
+  #   plot.entities             #=> [<#Gamefic::Entity a chapter thing>]
+  #   plot.thing                #   raises NoMethodError
+  #   plot.chapters.first.thing #=> <#Gamefic::Entity a chapter thing>
+  #
+  class Chapter < Narrative
+    extend Scriptable::PlotProxies
+
+    # @return [Plot]
+    attr_reader :plot
+
+    # @param plot [Plot]
+    def initialize(plot)
+      @plot = plot
+      # 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 included_blocks
+      self.class.included_blocks - plot.included_blocks
+    end
+
+    def rulebook
+      plot.rulebook
+    end
+
+    def entity_vault
+      plot.entity_vault
+    end
+
+    def player_vault
+      plot.player_vault
+    end
+
+    def subplots
+      plot.subplots
+    end
+
+    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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module Gamefic
   # A base class for building and managing the resources that compose a story.
   # The Plot and Subplot classes inherit from Narrative and provide additional
@@ -12,19 +14,40 @@ 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
-      self.class.included_blocks.select(&:seed?).each { |blk| Stage.run self, &blk.code }
+    def initialize(hydrate: true)
+      return unless hydrate
+
+      seed
+      script
+      post_script
+    end
+
+    def seed
+      included_blocks.select(&:seed?).each { |blk| Stage.run self, &blk.code }
+    end
+
+    def script
+      @rulebook = Rulebook.new
+      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_script
       entity_vault.lock
-      @rulebook = nil
-      hydrate
+      rulebook.freeze
     end
 
+    # @return [Array<Symbol>]
     def scenes
       rulebook.scenes.names
     end
@@ -91,9 +114,8 @@ module Gamefic
     end
 
     def hydrate
-      @rulebook = Rulebook.new(self)
-      @rulebook.script_with_defaults
-      @rulebook.freeze
+      script
+      post_script
     end
 
     def self.inherited klass

data/lib/gamefic/plot.rb

@@ -5,12 +5,31 @@ module Gamefic
   # methods for creating entities, actions, scenes, and hooks.
   #
   class Plot < Narrative
+    def seed
+      super
+      chapters.each(&:seed)
+    end
+
+    def script
+      super
+      chapters.each(&:script)
+      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
+
     def ready
       super
       subplots.each(&:ready)
       players.each(&:start_take)
       subplots.each(&:conclude) if concluding?
-
       players.select(&:concluding?).each { |plyr| rulebook.run_player_conclude_blocks plyr }
       subplots.delete_if(&:concluding?)
     end
@@ -76,6 +95,14 @@ module Gamefic
       subplots.each(&:hydrate)
     end
 
+    def self.append chapter
+      appended_chapters.add chapter
+    end
+
+    def self.appended_chapters
+      @appended_chapters ||= Set.new
+    end
+
     def self.restore data
       Snapshot.restore data
     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