gamefic 3.5.0 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79309729d2296ceec16e10d3380fba331512f15ca2d303788c1fbcc83c077457
-  data.tar.gz: f4ce7d947730da4e833d895ae3085c4027d80cf89306b3aeff03d1a2a6ecd2aa
+  metadata.gz: d5c61efc096ecbacdd43431dd3f0b755120650258a4a3e5d724692957ee45f53
+  data.tar.gz: 499d740594a35e767c86fae7610a51dafa9ba647658af7b3ab46c61de4335501
 SHA512:
-  metadata.gz: 01c7c68bdc217447d90bda4c2bdd362e318c644dc3486999f6125d6c124193e0b33782a250272a2455ea98e2f531551f3819611c4139b191d3dccaa61d9e03d8
-  data.tar.gz: '06101965d9a47188f2b5b22e87f4f7b4bbeefd5f102d2405e1457c8a389a732e782cd4eedccec2176f2b237ad3783b1ab0058ce2721e451caa29e4e8a6d52cdc'
+  metadata.gz: dd430f5dfa970cacfe12915ff09284ef286b1116aa701ce5484472fdf880b68a5de91953182189c647e90c527653bde92db26016045ac5ea5304e660082979fe
+  data.tar.gz: 1726fc542b40c55443bc9b452df85d94fe0831fa19bc73e40076cd6768e92bc71e504fd2da7998ef65b913c21f8b3ccb7bd4f04329186b88e71eb9dc675b0b69

data/CHANGELOG.md

@@ -1,4 +1,12 @@
-## 3.5.0
+## 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

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

@@ -30,6 +30,14 @@ module Gamefic
       @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.
       #
@@ -48,11 +56,12 @@ module Gamefic
       # @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.precision, -result.strictness, idx] }
+             .sort_by.with_index { |result, idx| [-result.substantiality, -result.strictness, -result.precision, idx] }
       end
     end
   end

data/lib/gamefic/dispatcher.rb

@@ -4,12 +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
+      Gamefic.logger.info "Dispatching #{command.inspect}"
     end
 
     # Run the dispatcher.

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/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/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

@@ -1,7 +1,16 @@
 # 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
 
@@ -9,11 +18,12 @@ module Gamefic
     attr_reader :key
 
     # @param type [Symbol]
-    # @param key [Symbol, String]
+    # @param key [Symbol, String, Array]
     def initialize type, key
+      Gamefic.logger.debug "Using deprecated #{type} proxy"
       @type = type
-      @key = key
       validate_type
+      @key = type == :config ? [key].compact : key
     end
 
     def fetch narrative
@@ -21,6 +31,13 @@ module Gamefic
         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
@@ -34,13 +51,29 @@ module Gamefic
     end
 
     def pick narrative
-      narrative.pick! key
+      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 [:attr, :ivar, :pick].include?(type)
+      return if TYPES.include?(type)
 
-      raise ArgumentError, "Invalid proxy type `#{type}` (must be :attr, :ivar, or :pick)"
+      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

data/lib/gamefic/query/base.rb

@@ -19,11 +19,13 @@ module Gamefic
       #
       # @param arguments [Array<Object>]
       # @param ambiguous [Boolean]
-      def initialize *arguments, ambiguous: false
+      # @param name [String]
+      def initialize *arguments, ambiguous: false, name: self.class.to_s
         raise ArgumentError, "nil argument in query" if arguments.any?(&:nil?)
 
         @arguments = arguments
         @ambiguous = ambiguous
+        @name = name
       end
 
       # Get a query result for a given subject and token.
@@ -38,19 +40,35 @@ module Gamefic
       # @param token [String]
       # @return [Result]
       def query(subject, token)
-        scan = Scanner.scan(select(subject), token)
-        ambiguous? ? ambiguous_result(scan) : unambiguous_result(scan)
+        first_pass = Scanner.scan(span(subject), token)
+        if ambiguous?
+          ambiguous_result(first_pass.filter(*normalized_arguments))
+        elsif first_pass.match.one?
+          unambiguous_result(first_pass.filter(*normalized_arguments))
+        else
+          unambiguous_result(first_pass)
+        end
       end
       alias filter query
 
-      # Get an array of entities that match the query from the context of the
-      # subject.
+      # Get an array of entities that match the arguments from the context of
+      # the subject.
+      #
+      # @param subject [Entity]
+      # @return [Array<Entity>]
+      def select subject
+        span(subject).that_are(*normalized_arguments)
+      end
+
+      # Get an array of entities that are candidates for selection from the
+      # context of the subject. These are the entities that #select will
+      # filter through query's arguments.
       #
       # Subclasses should override this method.
       #
       # @param subject [Entity]
       # @return [Array<Entity>]
-      def select _subject
+      def span _subject
         []
       end
 
@@ -77,12 +95,20 @@ module Gamefic
         @ambiguous
       end
 
+      def name
+        @name || self.class.to_s
+      end
+
+      def inspect
+        "##{ambiguous? ? '*' : ''}#{name}(#{normalized_arguments.map(&:inspect).join(', ')})"
+      end
+
       private
 
       def calculate_precision
-        unproxied_arguments.sum(@ambiguous ? -1000 : 0) do |arg|
+        normalized_arguments.sum(@ambiguous ? -1000 : 0) do |arg|
           case arg
-          when Entity, Proxy
+          when Entity, Proxy, Proxy::Base
             1000
           when Class, Module
             class_depth(arg) * 100
@@ -115,11 +141,15 @@ module Gamefic
         Result.new(scan.matched.first, scan.remainder, scan.strictness)
       end
 
-      def unproxied_arguments
-        @unproxied_arguments ||= arguments.map do |arg|
+      def normalized_arguments
+        @normalized_arguments ||= arguments.map do |arg|
           case arg
-          when Proxy
+          when Proxy, Proxy::Base
             arg.fetch(narrative)
+          when String
+            proc do |entity|
+              arg.keywords.all? { |word| entity.keywords.include?(word) }
+            end
           else
             arg
           end

data/lib/gamefic/query/general.rb

@@ -14,13 +14,13 @@ module Gamefic
       # @param entities [Array, Proc]
       # @param arguments [Array<Object>]
       # @param ambiguous [Boolean]
-      def initialize entities, *arguments, ambiguous: false
-        super(*arguments, ambiguous: ambiguous)
+      def initialize entities, *arguments, ambiguous: false, name: nil
+        super(*arguments, ambiguous: ambiguous, name: name)
         @entities = entities
       end
 
-      def select subject
-        available_entities(subject).that_are(*unproxied_arguments)
+      def span subject
+        available_entities(subject)
       end
 
       private

data/lib/gamefic/query/scoped.rb

@@ -10,14 +10,13 @@ module Gamefic
       attr_reader :scope
 
       # @param scope [Class<Gamefic::Scope::Base>]
-      def initialize scope, *arguments, ambiguous: false
-        super(*arguments, ambiguous: ambiguous)
+      def initialize scope, *arguments, ambiguous: false, name: nil
+        super(*arguments, ambiguous: ambiguous, name: name)
         @scope = scope
       end
 
-      def select(subject)
+      def span(subject)
         @scope.matches(subject)
-              .that_are(*unproxied_arguments)
       end
 
       def precision

data/lib/gamefic/query/text.rb

@@ -6,9 +6,10 @@ module Gamefic
     #
     class Text < Base
       # @param argument [String, Regexp]
-      def initialize argument = /.*/
-        super
-        validate
+      # @param name [String, nil]
+      def initialize argument = /.*/, name: self.class.name
+        super(argument, name: name)
+        validate_argument
       end
 
       def argument
@@ -50,7 +51,7 @@ module Gamefic
         end
       end
 
-      def validate
+      def validate_argument
         return if argument.is_a?(String) || argument.is_a?(Regexp)
 
         raise ArgumentError, 'Invalid text query argument'

data/lib/gamefic/query.rb

@@ -2,6 +2,7 @@
 
 require 'gamefic/query/base'
 require 'gamefic/query/general'
+require 'gamefic/query/abstract'
 require 'gamefic/query/scoped'
 require 'gamefic/query/text'
 require 'gamefic/query/result'

data/lib/gamefic/response.rb

@@ -77,11 +77,12 @@ module Gamefic
     # @param expression [Expression]
     # @return [Command, nil]
     def to_command actor, expression
-      return nil unless expression.verb == verb && expression.tokens.length <= queries.length
+      return log_and_discard unless expression.verb == verb && expression.tokens.length <= queries.length
 
       results = filter(actor, expression)
-      return nil unless results
+      return log_and_discard unless results
 
+      Gamefic.logger.info "Accepted #{inspect}"
       Command.new(
         verb,
         results.map(&:match),
@@ -90,8 +91,17 @@ module Gamefic
       )
     end
 
+    def inspect
+      "#<#{self.class} #{([verb] + queries).map(&:inspect).join(', ')}>"
+    end
+
     private
 
+    def log_and_discard
+      Gamefic.logger.info "Discarded #{inspect}"
+      nil
+    end
+
     def filter actor, expression
       remainder = ''
       result = queries.zip(expression.tokens)
@@ -126,7 +136,7 @@ module Gamefic
 
     def select_query arg, narrative
       case arg
-      when Entity, Class, Module, Proc, Proxy
+      when Entity, Class, Module, Proc, Proxy, Proxy::Base
         narrative.available(arg)
       when String, Regexp
         narrative.plaintext(arg)

data/lib/gamefic/scanner/nesting.rb

@@ -12,7 +12,7 @@ module Gamefic
       end
 
       def scan
-        return Result.unmatched(selection, token, self.class) unless token =~ NEST_REGEXP
+        return unmatched_result unless token =~ NEST_REGEXP
 
         denest selection, token
       end
@@ -27,7 +27,7 @@ module Gamefic
           current = parts.pop
           last_result = subprocessor.scan(near, current)
           last_result = subprocessor.scan(far, current) if last_result.matched.empty? && near != far
-          return Result.unmatched(selection, token, self.class) if last_result.matched.empty? || last_result.matched.length > 1
+          return unmatched_result if last_result.matched.empty? || last_result.matched.length > 1
 
           near = last_result.matched.first.children & objects
           far = last_result.matched.first.flatten & objects

data/lib/gamefic/scanner/result.rb

@@ -42,6 +42,16 @@ module Gamefic
         @strictness ||= Scanner.strictness(processor)
       end
 
+      def filter *args
+        Scanner::Result.new(
+          scanned,
+          token,
+          match.that_are(*args),
+          remainder,
+          processor
+        )
+      end
+
       def self.unmatched scanned, token, processor
         new(scanned, token, [], token, processor)
       end

data/lib/gamefic/scope/descendants.rb

@@ -1,16 +1,16 @@
-# frozen_string_literal: true
-
-module Gamefic
-  module Scope
-    # The Descendants scope returns an entity's children and accessible
-    # descendants.
-    #
-    class Descendants < Base
-      def matches
-        context.children.flat_map do |child|
-          [child] + subquery_accessible(child)
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+module Gamefic
+  module Scope
+    # The Descendants scope returns an entity's children and accessible
+    # descendants.
+    #
+    class Descendants < Base
+      def matches
+        context.children.flat_map do |child|
+          [child] + subquery_accessible(child)
+        end
+      end
+    end
+  end
+end

data/lib/gamefic/scriptable/entities.rb

@@ -49,16 +49,30 @@ module Gamefic
         entity_vault.delete entity
       end
 
-      # Pick an entity based on a unique name or description. Return nil if an
-      # entity could not be found or there is more than one possible match.
+      def find *args
+        args.inject(entities) do |entities, arg|
+          case arg
+          when String
+            result = Scanner.scan(entities, arg)
+            result.remainder.empty? ? result.match : []
+          else
+            entities.that_are(arg)
+          end
+        end
+      end
+
+      # Pick a unique entity based on the given arguments. String arguments are
+      # used to scan the entities for matching names and synonyms. Return nil
+      # if an entity could not be found or there is more than one possible
+      # match.
       #
-      # @param description [String]
+      # @param description [Array]
       # @return [Gamefic::Entity, nil]
-      def pick description
-        result = Scanner.scan(entities, description)
-        return nil unless result.matched.one?
+      def pick *args
+        matches = find(*args)
+        return nil unless matches.one?
 
-        result.matched.first
+        matches.first
       end
 
       # Same as #pick, but raise an error if a unique match could not be found.
@@ -66,16 +80,14 @@ module Gamefic
       #
       # @raise [RuntimeError] if a unique match was not found.
       #
-      # @param description [String]
-      # @return [Gamefic::Entity, nil]
-      def pick! description
-        result = Scanner.scan(entities, description)
-
-        raise "no entity matching '#{description}'" if result.matched.empty?
-
-        raise "multiple entities matching '#{description}': #{result.matched.join_and}" unless result.matched.one?
+      # @param args [Array]
+      # @return [Gamefic::Entity]
+      def pick! *args
+        matches = find(*args)
+        raise "no entity matching '#{args.inspect}'" if matches.empty?
+        raise "multiple entities matching '#{args.inspect}': #{matches.join_and}" unless matches.one?
 
-        result.matched.first
+        matches.first
       end
     end
   end

data/lib/gamefic/scriptable/plot_proxies.rb

@@ -4,6 +4,7 @@ module Gamefic
   module Scriptable
     module PlotProxies
       def lazy_plot key
+        Logging.logger.warn "#{caller.first ? "#{caller.first}: " : ''}`lazy_plot` is deprecated. Use `plot_pick`, `plot_pick!, or pass the entity from the plot in a `config` option instead."
         Proxy.new(:attr, [:plot, key])
       end
       alias _plot lazy_plot
@@ -11,6 +12,18 @@ module Gamefic
       def attr_plot attr
         define_method(attr) { plot.send(attr) }
       end
+
+      def plot_pick *args
+        Proxy::PlotPick.new(*args)
+      end
+      alias lazy_plot_pick plot_pick
+      alias _plot_pick plot_pick
+
+      def plot_pick! *args
+        Proxy::PlotPick.new(*args)
+      end
+      alias lazy_plot_pick! plot_pick!
+      alias _plot_pick! plot_pick!
     end
   end
 end

data/lib/gamefic/scriptable/proxies.rb

@@ -16,7 +16,7 @@ module Gamefic
       # @return [Object]
       def unproxy object
         case object
-        when Proxy
+        when Proxy, Proxy::Base
           object.fetch self
         when Array
           object.map { |obj| unproxy obj }

data/lib/gamefic/scriptable/queries.rb

@@ -12,7 +12,18 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::General]
       def anywhere *args, ambiguous: false
-        Query::General.new -> { entities }, *args, ambiguous: ambiguous
+        Query::General.new -> { entities }, *args, ambiguous: ambiguous, name: 'anywhere'
+      end
+
+      # Define a query that searches for abstract entities.
+      #
+      # An abstract entity is a pseudo-entity that is describable but does
+      # not have a parent or children.
+      #
+      # @param args [Array<Object>] Query arguments
+      # @return [Query::Abstract]
+      def abstract *args, ambiguous: false
+        Query::Abstract.new -> { entities }, *args, ambiguous: ambiguous
       end
 
       # Define a query that searches an actor's family of entities. The
@@ -22,7 +33,7 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def available *args, ambiguous: false
-        Query::Scoped.new Scope::Family, *args, ambiguous: ambiguous
+        Query::Scoped.new Scope::Family, *args, ambiguous: ambiguous, name: 'available'
       end
       alias family available
 
@@ -31,7 +42,7 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def parent *args, ambiguous: false
-        Query::Scoped.new Scope::Parent, *args, ambiguous: ambiguous
+        Query::Scoped.new Scope::Parent, *args, ambiguous: ambiguous, name: 'parent'
       end
 
       # Define a query that searches an actor's children.
@@ -39,7 +50,7 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def children *args, ambiguous: false
-        Query::Scoped.new Scope::Children, *args, ambiguous: ambiguous
+        Query::Scoped.new Scope::Children, *args, ambiguous: ambiguous, name: 'children'
       end
 
       # Define a query that searches an actor's descendants.
@@ -55,7 +66,7 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def siblings *args, ambiguous: false
-        Query::Scoped.new Scope::Siblings, *args, ambiguous: ambiguous
+        Query::Scoped.new Scope::Siblings, *args, ambiguous: ambiguous, name: 'siblings'
       end
 
       # Define a query that returns the actor itself.
@@ -63,7 +74,7 @@ module Gamefic
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
       def myself *args, ambiguous: false
-        Query::Scoped.new Scope::Myself, *args, ambiguous: ambiguous
+        Query::Scoped.new Scope::Myself, *args, ambiguous: ambiguous, name: 'myself'
       end
 
       # Define a query that performs a plaintext search. It can take a String
@@ -74,7 +85,7 @@ module Gamefic
       # @param arg [String, Regexp] The string or regular expression to match
       # @return [Query::Text]
       def plaintext arg = /.*/
-        Query::Text.new arg
+        Query::Text.new arg, name: 'plaintext'
       end
     end
   end

data/lib/gamefic/scriptable.rb

@@ -101,11 +101,12 @@ module Gamefic
     #   make_seed Gamefic::Entity, name: 'thing'
     #
     # @param klass [Class<Gamefic::Entity>]
-    # @return [void]
+    # @return [Proxy]
     def make_seed klass, **opts
       seed { make(klass, **opts) }
-      nil
+      Proxy::Pick.new(klass, opts[:name], raise: true)
     end
+    alias make make_seed
 
     # Seed an entity with an attribute method.
     #
@@ -134,11 +135,11 @@ module Gamefic
     # @param symbol [Symbol]
     # @return [Proxy]
     def proxy symbol
-      Logging.logger.warn "#proxy is deprecated. Use lazy_attr, lazy_ivar, or lazy_pick instead"
+      Logging.logger.warn "#{caller.first ? "#{caller.first}: " : ''}`proxy` is deprecated. Use `pick` or `pick!` instead."
       if symbol.to_s.start_with?('@')
-        lazy_ivar(symbol)
+        Proxy.new(:ivar, symbol)
       else
-        lazy_attr(symbol)
+        Proxy.new(:attr, symbol)
       end
     end
 
@@ -150,6 +151,7 @@ module Gamefic
     # @param key [Symbol]
     # @return [Proxy]
     def lazy_ivar key
+      Gamefic.logger.warn "#{caller.first ? "#{caller.first}: " : ''}`lazy_ivar` is deprecated. Use `pick` or `pick!` instead."
       Proxy.new(:ivar, key)
     end
     alias _ivar lazy_ivar
@@ -162,23 +164,31 @@ module Gamefic
     # @param key [Symbol]
     # @return [Proxy]
     def lazy_attr key
+      Gamefic.logger.warn "#{caller.first ? "#{caller.first}: " : ''}`lazy_attr` is deprecated. Use `pick` or `pick!` instead."
       Proxy.new(:attr, key)
     end
     alias _attr lazy_attr
 
-    # Lazy reference an entity by its description.
+    # Lazy pick an entity.
     #
     # @example
-    #   lazy_pick('the red box')
-    #
-    # @raise [RuntimeError] if a unique match could not be found.
+    #   pick('the red box')
     #
-    # @param description [String]
+    # @param args [Array]
     # @return [Proxy]
-    def lazy_pick description
-      Proxy.new(:pick, description)
+    def pick *args
+      Proxy::Pick.new(*args)
+    end
+    alias lazy_pick pick
+    alias _pick pick
+
+    # Lazy pick an entity or raise
+    #
+    def pick! *args
+      Proxy::Pick.new(*args)
     end
-    alias _pick lazy_pick
+    alias lazy_pick! pick
+    alias _pick! pick
 
     if RUBY_ENGINE == 'opal'
       # :nocov:
@@ -212,7 +222,7 @@ module Gamefic
     #
     # @return [Module<self>]
     def no_scripts
-      Logging.logger.warn 'Calling `no_scripts` on Scriptable modules is no longer necessary.'
+      Logging.logger.warn "#{caller.first ? "#{caller.first}: " : ''}Calling `no_scripts` on Scriptable modules is no longer necessary."
       self
     end
   end

data/lib/gamefic/subplot.rb

@@ -98,5 +98,11 @@ module Gamefic
     def inspect
       "#<#{self.class}>"
     end
+
+    class << self
+      def config
+        Proxy::Config.new
+      end
+    end
   end
 end

data/lib/gamefic/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gamefic
 version: !ruby/object:Gem::Version
-  version: 3.5.0
+  version: 3.6.0
 platform: ruby
 authors:
 - Fred Snyder
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-05 00:00:00.000000000 Z
+date: 2024-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opal
@@ -156,7 +156,12 @@ files:
 - lib/gamefic/props/pause.rb
 - lib/gamefic/props/yes_or_no.rb
 - lib/gamefic/proxy.rb
+- lib/gamefic/proxy/base.rb
+- lib/gamefic/proxy/config.rb
+- lib/gamefic/proxy/pick.rb
+- lib/gamefic/proxy/plot_pick.rb
 - lib/gamefic/query.rb
+- lib/gamefic/query/abstract.rb
 - lib/gamefic/query/base.rb
 - lib/gamefic/query/general.rb
 - lib/gamefic/query/result.rb