gamefic 3.6.0 → 4.0.0

data/lib/gamefic/active.rb

@@ -2,9 +2,8 @@
 
 require 'set'
 require 'gamefic/active/cue'
-require 'gamefic/active/epic'
 require 'gamefic/active/messaging'
-require 'gamefic/active/take'
+require 'gamefic/active/narratives'
 
 module Gamefic
   # The Active module gives entities the ability to perform actions and
@@ -15,33 +14,21 @@ module Gamefic
     include Logging
     include Messaging
 
-    # The cue that will be used to create a scene at the beginning of the next
-    # turn.
+    # The most recently started cue.
     #
-    # @return [Active::Cue, nil]
-    attr_reader :next_cue
-
-    # @return [String, nil]
-    attr_reader :last_input
-
-    # @return [Symbol, nil]
-    def next_scene
-      next_cue&.scene
-    end
+    # @return [Cue, nil]
+    attr_reader :last_cue
 
-    # The rulebooks that will be used to perform commands. Every plot and
-    # subplot has its own rulebook.
+    # The cue that will be started on the next turn.
     #
-    # @return [Set<Gamefic::World::Rulebook>]
-    # def rulebooks
-    #   @rulebooks ||= Set.new
-    # end
+    # @return [Cue, nil]
+    attr_reader :next_cue
 
     # The narratives in which the entity is participating.
     #
-    # @return [Epic]
-    def epic
-      @epic ||= Epic.new
+    # @return [Narratives]
+    def narratives
+      @narratives ||= Narratives.new
     end
 
     # An array of commands waiting to be executed.
@@ -59,14 +46,7 @@ module Gamefic
     #
     # @return [Props::Output]
     def output
-      @output ||= Props::Output.new.freeze
-    end
-
-    # The output from the previous turn.
-    #
-    # @return [Props::Output]
-    def last_output
-      @last_output ||= output
+      last_cue&.output || Props::Output::EMPTY
     end
 
     # Perform a command.
@@ -77,21 +57,24 @@ module Gamefic
     # @example Send a command as a string
     #   character.perform "take the key"
     #
-    # @param command [String]
-    # @return [Action, nil]
-    def perform(command)
-      dispatchers.push Dispatcher.dispatch(self, command)
-      dispatchers.last.execute.tap { dispatchers.pop }
+    # @param input [String]
+    # @return [Command, nil]
+    def perform(input)
+      dispatchers.push Dispatcher.new(Request.new(self, input))
+      dispatchers.last.execute.tap do |command|
+        dispatchers.pop
+        @acting = true if command&.active?
+      end
     end
 
     # Quietly perform a command.
     # This method executes the command exactly as #perform does, except it
     # buffers the resulting output instead of sending it to messages.
     #
-    # @param command [String]
+    # @param input [String]
     # @return [String] The output that resulted from performing the command.
-    def quietly(command)
-      messenger.buffer { perform command }
+    def quietly(input)
+      messenger.buffer { perform input }
     end
 
     # Perform an action.
@@ -107,10 +90,13 @@ module Gamefic
     #
     # @param verb [Symbol]
     # @param params [Array]
-    # @return [Action, nil]
+    # @return [Command, nil]
     def execute(verb, *params)
-      dispatchers.push Dispatcher.dispatch_from_params(self, verb, params)
-      dispatchers.last.execute.tap { dispatchers.pop }
+      dispatchers.push Dispatcher.new(Order.new(self, verb, params))
+      dispatchers.last.execute.tap do |command|
+        dispatchers.pop
+        @acting = true if command&.active?
+      end
     end
 
     # Proceed to the next Action in the current stack.
@@ -145,89 +131,91 @@ module Gamefic
     #
     # @raise [ArgumentError] if the scene is not valid
     #
-    # @param scene [Symbol]
+    # @param scene [Class<Scene::Base>, Symbol]
     # @param context [Hash] Extra data to pass to the scene's props
     # @return [Cue]
     def cue scene, **context
-      return @next_cue if @next_cue&.scene == scene && @next_cue&.context == context
+      return @next_cue if @next_cue&.key == scene && @next_cue&.context == context
 
-      logger.debug "Overwriting existing cue `#{@next_cue.scene}` with `#{scene}`" if @next_cue
+      logger.debug "Overwriting existing cue `#{@next_cue.key}` with `#{scene}`" if @next_cue
 
-      @next_cue = Cue.new(scene, **context)
+      @next_cue = Cue.new(self, scene, current, **context)
     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
-      @props.output[:last_prompt] = @last_output.prompt
-      @props.output[:last_input] = @last_input
-      @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.
     #
     # @return [Cue, nil]
     def recue
-      logger.warn "No scene to recue" unless @last_cue
-
-      @next_cue = @last_cue
+      (@next_cue = @last_cue&.restart) || warn_nil('No scene to recue')
     end
 
-    # Cue a conclusion. This method works like #cue, except it will raise an
-    # error if the scene is not a conclusion.
-    #
-    # @raise [ArgumentError] if the requested scene is not a conclusion
+    # True if the actor is ready to leave the game.
     #
-    # @param new_scene [Symbol]
-    # @oaram context [Hash] Additional scene data
-    # @return [Cue]
-    def conclude scene, **context
-      cue scene, **context
-      available = epic.select_scene(scene)
-      raise ArgumentError, "`#{scene}` is not a conclusion" unless available.conclusion?
+    def concluding?
+      narratives.empty? || last_cue&.type == 'Conclusion'
+    end
 
-      @next_cue
+    def accessible
+      []
     end
 
-    # True if the actor is ready to leave the game.
+    # True if the actor is participating in any narratives.
     #
-    def concluding?
-      epic.empty? || @props&.scene&.fetch(:type) == 'Conclusion'
+    def participating?
+      !narratives.empty?
     end
 
-    def accessible?
-      false
+    # True if the actor can perform the verb (i.e., an active narrative
+    # understands it).
+    #
+    # @param verb [String, Symbol]
+    def can?(verb)
+      narratives.understand?(verb)
     end
 
+    # Move next_cue into last_cue. This method is typically called by the
+    # narrator at the start of a turn. It returns the last cue.
+    #
+    # @return [Cue, nil]
+    def rotate_cue
+      @acting = false
+      @last_cue = @next_cue
+      @next_cue = nil
+      @last_cue
+    end
+
+    # True if the actor performed a command this turn. False if the actor has
+    # not performed a command yet or has only performed meta commands.
+    #
     def acting?
-      !epic.empty?
+      @acting ||= false
+    end
+
+    # The input from the last finished cue.
+    #
+    # @return [String, nil]
+    def last_input
+      output.last_input
     end
 
     private
 
+    # Get the currently bound or primary narrative.
+    #
+    # @return [Narrative, nil]
+    def current
+      Binding.for(self) || narratives.first
+    end
+
     # @return [Array<Dispatcher>]
     def dispatchers
       @dispatchers ||= []
     end
 
-    def ensure_cue
-      return if next_cue
-
-      logger.debug "Using default scene for actor without cue"
-      cue :default_scene
+    def warn_nil(message)
+      logger.warn message
+      nil
     end
   end
 end

data/lib/gamefic/binding.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Gamefic
+  class Binding
+    class << self
+      def registry
+        @registry ||= {}
+      end
+
+      def push(object, narrative)
+        registry[object] ||= []
+        registry[object].push narrative
+      end
+
+      def pop(object)
+        registry[object].pop
+        registry.delete(object) if registry[object].empty?
+      end
+
+      def for(object)
+        registry.fetch(object, []).last
+      end
+    end
+
+    attr_reader :narrative
+
+    attr_reader :code
+
+    # @param narrative [Narrative]
+    # @param code [Proc]
+    def initialize(narrative, code)
+      @narrative = narrative
+      @code = code
+    end
+
+    def call(*args)
+      args.each { |arg| Binding.push arg, @narrative }
+      @narrative.instance_exec(*args, &@code)
+    ensure
+      args.each { |arg| Binding.pop arg }
+    end
+    alias [] call
+  end
+end

data/lib/gamefic/chapter.rb

@@ -1,71 +1,55 @@
 # 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
 
+    # @return [Hash]
+    attr_reader :config
+
     # @param plot [Plot]
-    def initialize(plot)
+    def initialize(plot, **config)
       @plot = plot
-      # The plot is responsible for hydrating chapters
-      super(hydrate: false)
+      @concluding = false
+      @config = config
+      configure
+      @config.freeze
+      super()
     end
 
-    def script
-      included_blocks.select(&:script?).each { |blk| Stage.run self, &blk.code }
+    def players
+      plot.players
     end
 
-    def included_blocks
-      self.class.included_blocks - plot.included_blocks
+    def conclude
+      # @todo Void entities?
+      @concluding = true
     end
 
-    def rulebook
-      plot.rulebook
+    def concluding?
+      @concluding
     end
 
-    def entity_vault
-      plot.entity_vault
+    def self.bind_from_plot *methods
+      methods.flatten.each do |method|
+        define_method(method) { plot.send(method) }
+        define_singleton_method(method) { Proxy::Attr.new(method) }
+      end
     end
 
-    def player_vault
-      plot.player_vault
+    def included_scripts
+      super - plot.included_scripts
     end
 
-    def subplots
-      plot.subplots
-    end
+    # Subclasses can override this method to handle additional configuration.
+    #
+    def configure; end
 
-    def branch(...)
-      plot.branch(...)
+    class << self
+      def config
+        Proxy::Config.new
+      end
     end
   end
 end

data/lib/gamefic/command.rb

@@ -10,59 +10,41 @@ module Gamefic
     # @return [Array<Array<Entity>, Entity, String>]
     attr_reader :arguments
 
-    # @return [Integer]
-    attr_reader :strictness
-
-    # @return [Integer]
-    attr_reader :precision
+    # @return [String, nil]
+    attr_reader :input
 
     # @param verb [Symbol]
     # @param arguments [Array<Array<Entity>, Entity, String>]
-    # @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
+    # @param meta [Boolean]
+    # @param input [String, nil]
+    def initialize(verb, arguments, meta = false, input = nil)
       @verb = verb
       @arguments = arguments
-      @strictness = strictness
-      @precision = precision
+      @meta = meta
+      @input = input
+      @cancelled = false
     end
 
-    def substantiality
-      @substantiality ||= arguments.that_are(Entity).length + (verb ? 1 : 0)
+    def cancel
+      @cancelled = true
     end
+    alias stop cancel
 
-    def inspect
-      "#<#{self.class} #{([verb] + arguments).map(&:inspect).join(', ')}>"
+    def cancelled?
+      @cancelled
     end
+    alias stopped? cancelled?
 
-    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
+    def meta?
+      @meta
+    end
 
-      private
+    def active?
+      !meta?
+    end
 
-      # @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
+    def inspect
+      "#<#{self.class} #{([verb] + arguments).map(&:inspect).join(', ')}>"
     end
   end
 end

data/lib/gamefic/core_ext/array.rb

@@ -46,24 +46,24 @@ class Array
   #   animals = ['a dog', 'a cat', 'a mouse']
   #   animals.join_and #=> 'a dog, a cat, and a mouse'
   #
-  # @param sep [String] The separator for all but the last element
-  # @param andSep [String] The separator for the last element
+  # @param separator [String] The separator for all but the last element
+  # @param and_separator [String] The separator for the last element
   # @param serial [Boolean] Use serial separators (e.g., serial commas)
   # @return [String]
-  def join_and(sep = ', ', and_sep = ' and ', serial = true)
+  def join_and(separator: ', ', and_separator: ' and ', serial: true)
     if length < 3
-      join(and_sep)
+      join(and_separator)
     else
       start = self[0..-2]
-      start.join(sep) + "#{serial ? sep.strip : ''}#{and_sep}#{last}"
+      start.join(separator) + "#{serial ? separator.strip : ''}#{and_separator}#{last}"
     end
   end
 
   # @see Array#join_and
   #
   # @return [String]
-  def join_or(sep = ', ', or_sep = ' or ', serial = true)
-    join_and(sep, or_sep, serial)
+  def join_or(separator: ', ', or_separator: ' or ', serial: true)
+    join_and(separator: separator, and_separator: or_separator, serial: serial)
   end
 
   private

data/lib/gamefic/core_ext/string.rb

@@ -12,9 +12,9 @@ class String
 
   # Get an array of words split by any whitespace.
   #
-  # @return [Array]
+  # @return [Array<String>]
   def keywords
-    gsub(/[\s-]+/, ' ').strip.downcase.split - %w[a an the]
+    gsub(/[\s-]+/, ' ').strip.downcase.split
   end
 
   # @return [String]

data/lib/gamefic/describable.rb

@@ -19,6 +19,9 @@ module Gamefic
     # @return [String]
     attr_reader :synonyms
 
+    # @return [String]
+    attr_writer :nuance
+
     # The object's indefinite article (usually "a" or "an").
     #
     # @return [String]
@@ -33,6 +36,16 @@ module Gamefic
       "#{name} #{synonyms}".keywords
     end
 
+    # Optional words that shouldn't match an object on their own but might be
+    # used in a larger phrase. For example, if you have an entity named "dog"
+    # and its description calls it "sleepy," you might add "sleepy" to nuance
+    # so the phrase "sleepy dog" matches but the word "sleepy" alone does not.
+    #
+    # @return [String]
+    def nuance
+      @nuance ||= ''
+    end
+
     # The name of the object with an indefinite article.
     # Note: proper-named objects never append an article, though an article
     # may be included in its proper name.

data/lib/gamefic/dispatcher.rb

@@ -4,33 +4,21 @@ 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}"
+    # @param actionable [#to_actions]
+    def initialize(actionable)
+      @actions = actionable.to_actions
     end
 
-    # Run the dispatcher.
+    # Start executing actions in the dispatcher.
     #
-    # @return [Action, nil]
+    # @return [Command, nil]
     def execute
-      return if @executed
-
-      @executed = true
-      action = next_action
-      return unless action
+      return if action || actions.empty?
 
-      actor.epic.rulebooks.flat_map { |rlbk| rlbk.run_before_actions action }
-      return if action.cancelled?
-
-      action.execute
-      actor.epic.rulebooks.flat_map { |rlbk| rlbk.run_after_actions action }
-      action
+      @action = actions.shift
+      Gamefic.logger.info "Dispatching #{actor.inspect} #{command.inspect}"
+      run_hooks_and_response
+      command
     end
 
     # Execute the next available action.
@@ -39,51 +27,43 @@ module Gamefic
     #
     # @return [Action, nil]
     def proceed
-      return unless @executed
+      return if !action || command.cancelled?
 
-      next_action&.execute
+      actions.shift&.execute
     end
 
-    # @param actor [Active]
-    # @param input [String]
-    # @return [Dispatcher]
-    def self.dispatch actor, input
-      # expressions = Syntax.tokenize(input, actor.epic.syntaxes)
-      # new(actor, Command.compose(actor, expressions))
-      new(actor, Command.compose(actor, input))
-    end
+    private
 
-    # @param actor [Active]
-    # @param verb [Symbol]
-    # @param params [Array<Object>]
-    # @return [Dispatcher]
-    def self.dispatch_from_params actor, verb, params
-      command = Command.new(verb, params)
-      new(actor, command)
-    end
+    # @return [Array<Action>]
+    attr_reader :actions
 
-    protected
+    # @return [Action, nil]
+    attr_reader :action
 
-    # @return [Actor]
-    attr_reader :actor
+    # @return [Actor, nil]
+    def actor
+      action.actor
+    end
 
     # @return [Command]
-    attr_reader :command
-
-    # @return [Array<Response>]
-    def responses
-      @responses ||= actor.epic.responses_for(command.verb)
+    def command
+      action.command
     end
 
-    private
+    def run_hooks(list)
+      list.each do |blk|
+        blk[actor, command]
+        break if command.cancelled?
+      end
+    end
 
-    # @return [Action, nil]
-    def next_action
-      while (response = responses.shift)
-        next if response.queries.length < @command.arguments.length
+    def run_hooks_and_response
+      run_hooks actor.narratives.before_commands
+      command.freeze
+      return if command.cancelled?
 
-        return Action.new(actor, @command.arguments, response) if response.accept?(actor, @command)
-      end
+      action.execute
+      run_hooks actor.narratives.after_commands
     end
   end
 end