gamefic 3.4.0 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79b61813b56cbbabb76ecbef9abb370b2fe77b58ea3e155377f8c4dfd2677684
-  data.tar.gz: 611c108a0c080796c8308bee5f3e361c60fc4ddd316234bf9468c09742b1a52d
+  metadata.gz: d5c61efc096ecbacdd43431dd3f0b755120650258a4a3e5d724692957ee45f53
+  data.tar.gz: 499d740594a35e767c86fae7610a51dafa9ba647658af7b3ab46c61de4335501
 SHA512:
-  metadata.gz: 85732c76dae467bd5d032462ca23d34b03b7be59c6327202fd9bef307ef3d06bc40af085f32010cfae9dfd93a85b20524785313388964772534632cc95159625
-  data.tar.gz: 5c3db85ff44b268bd7604d33e28b92ca454c82c2a812f023af39a3da816a4252dfea01869d313f1ab6d24a1f062782ac002f5bf8fc40fd435efaa0c1ac14d337
+  metadata.gz: dd430f5dfa970cacfe12915ff09284ef286b1116aa701ce5484472fdf880b68a5de91953182189c647e90c527653bde92db26016045ac5ea5304e660082979fe
+  data.tar.gz: 1726fc542b40c55443bc9b452df85d94fe0831fa19bc73e40076cd6768e92bc71e504fd2da7998ef65b913c21f8b3ccb7bd4f04329186b88e71eb9dc675b0b69

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 3.6.0 - October 6, 2024
+- Normalized arguments accept strings
+- Smarter picks and proxies
+- Commands prefer strictness over precision
+- Queries scan for ambiguity before filtering through arguments
+- Abstract queries
+- Command logging
+
+## 3.5.0 - October 5, 2024
+- 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/action.rb

@@ -51,6 +51,7 @@ module Gamefic
     def execute
       return self if cancelled? || executed?
 
+      Gamefic.logger.info "Executing #{([verb] + [arguments]).flatten.map(&:inspect).join(', ')}"
       @executed = true
       response.execute actor, *arguments
       self

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,59 @@ 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
+
+    def substantiality
+      @substantiality ||= arguments.that_are(Entity).length + (verb ? 1 : 0)
+    end
+
+    def inspect
+      "#<#{self.class} #{([verb] + arguments).map(&:inspect).join(', ')}>"
+    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
+        Gamefic.logger.info "Evaluating #{expression.inspect}"
+        actor.epic
+             .responses_for(expression.verb)
+             .map { |response| response.to_command(actor, expression) }
+             .compact
+             .sort_by.with_index { |result, idx| [-result.substantiality, -result.strictness, -result.precision, idx] }
+      end
     end
   end
 end

data/lib/gamefic/dispatcher.rb

@@ -4,13 +4,15 @@ module Gamefic
   # The action executor for character commands.
   #
   class Dispatcher
+    include Logging
+
     # @param actor [Actor]
     # @param command [Command]
     def initialize actor, command
       @actor = actor
       @command = command
       @executed = false
-      @finalized = false
+      Gamefic.logger.info "Dispatching #{command.inspect}"
     end
 
     # Run the dispatcher.
@@ -23,11 +25,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 +48,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 +84,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/expression.rb

@@ -17,6 +17,9 @@ module Gamefic
       @tokens = tokens
     end
 
+    def inspect
+      "#<#{self.class} #{([verb] + tokens).map(&:inspect).join(', ')}>"
+    end
     # Compare two syntaxes for the purpose of ordering them by relevance while
     # dispatching.
     #

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

@@ -88,11 +88,9 @@ module Gamefic
     end
 
     def validate_parent(node)
-      raise NodeError, 'Parent must be a Node' unless node.is_a?(Node) || node.nil?
-
-      raise NodeError, "Node cannot be its own parent" if node == self
-
-      raise NodeError, 'Node cannot be a child of a descendant' if flatten.include?(node)
+      raise NodeError, "Parent of #{inspect} must be a Node, received #{node.inspect}" unless node.is_a?(Node) || node.nil?
+      raise NodeError, "#{inspect} cannot be its own parent" if node == self
+      raise NodeError, "#{inspect} cannot be a child of descendant #{node.inspect}" if flatten.include?(node)
     end
   end
 end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Gamefic
+  class Proxy
+    class Base
+      attr_reader :args
+
+      def initialize *args, raise: false
+        @args = args
+        @raise = raise
+      end
+
+      def raise?
+        @raise
+      end
+
+      def fetch narrative
+        result = select(narrative)
+        return result if result
+        raise "#{self.class} failed for #{args.inspect}" if raise?
+      end
+
+      def select narrative
+      end
+    end
+  end
+end

data/lib/gamefic/proxy/config.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Gamefic
+  class Proxy
+    class Config < Base
+      def select narrative
+        args.inject(narrative.config) { |hash, key| hash[key] }
+      end
+
+      def [](key)
+        args.push key
+        self
+      end
+    end
+  end
+end

data/lib/gamefic/proxy/pick.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Gamefic
+  class Proxy
+    class Pick < Base
+      def select narrative
+        raise? ? narrative.pick!(*args) : narrative.pick(*args)
+      end
+    end
+  end
+end

data/lib/gamefic/proxy/plot_pick.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Gamefic
+  class Proxy
+    class PlotPick < Base
+      def select narrative
+        raise? ? narrative.plot.pick!(*args) : narrative.plot.pick(*args)
+      end
+    end
+  end
+end

data/lib/gamefic/proxy.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Gamefic
+  # @todo Turn this into a module after the old proxies are completely deprecated
+  #
+  class Proxy
+    require 'gamefic/proxy/base'
+    require 'gamefic/proxy/config'
+    require 'gamefic/proxy/pick'
+    require 'gamefic/proxy/plot_pick'
+
+    TYPES = %i[attr ivar pick pick! plot_pick plot_pick! config].freeze
+
+    # @return [Symbol]
+    attr_reader :type
+
+    # @return [Symbol, Array<Symbol>, String, Integer]
+    attr_reader :key
+
+    # @param type [Symbol]
+    # @param key [Symbol, String, Array]
+    def initialize type, key
+      Gamefic.logger.debug "Using deprecated #{type} proxy"
+      @type = type
+      validate_type
+      @key = type == :config ? [key].compact : key
+    end
+
+    def fetch narrative
+      send(type, narrative) ||
+        raise(ArgumentError, "Unable to fetch entity from proxy agent symbol `#{key}`")
+    end
+
+    def [](key)
+      raise ArgumentError, 'Invalid []' unless type == :config
+
+      @key.push key
+      self
+    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 pick! narrative
+      narrative.pick! *key
+    end
+
+    def plot_pick narrative
+      narrative.plot.pick *key
+    end
+
+    def plot_pick! narrative
+      narrative.plot.pick! *key
+    end
+
+    def config narrative
+      key.inject(narrative.config) { |hash, key| hash[key] }
+    end
+
+    def validate_type
+      return if TYPES.include?(type)
+
+      raise ArgumentError, "Invalid proxy type `#{type}` (must be #{TYPES.join_or})"
+    end
+  end
+end

data/lib/gamefic/query/abstract.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Query
+    class Abstract < General
+      def span subject
+        available_entities(subject).that_are(Describable)
+                                   .that_are_not(Entity)
+      end
+    end
+  end
+end