gamefic 3.6.0 → 4.0.0

data/lib/gamefic/scene/multiple_choice.rb

@@ -2,29 +2,32 @@
 
 module Gamefic
   module Scene
-    # A scene that presents a list of choices and processes the player's input.
-    # If the input is not a valid choice, the scene gets recued.
+    # A scene that presents a list of choices. If the input does not match any
+    # of the choices, the scene gets recued.
     #
-    class MultipleChoice < Default
+    class MultipleChoice < Base
       use_props_class Props::MultipleChoice
 
-      def start actor, props
+      def initialize(...)
         super
-        props.output[:options] = props.options
+        props.options.concat(context[:options] || [])
       end
 
-      def finish actor, props
+      def start
         super
-        return if props.index
+        props.output[:options] = props.options
+        props
+      end
+
+      def finish
+        return super if props.selected?
 
         actor.tell format(props.invalid_message, input: props.input)
         actor.recue
       end
 
-      def run_finish_blocks actor, props
-        return unless props.index
-
-        super
+      def self.type
+        'MultipleChoice'
       end
     end
   end

data/lib/gamefic/scene/pause.rb

@@ -6,8 +6,12 @@ module Gamefic
     # before proceeding to on_finish. The user input itself is ignored by
     # default.
     #
-    class Pause < Default
+    class Pause < Base
       use_props_class Props::Pause
+
+      def self.type
+        'Pause'
+      end
     end
   end
 end

data/lib/gamefic/scene/yes_or_no.rb

@@ -6,6 +6,15 @@ module Gamefic
     #
     class YesOrNo < MultipleChoice
       use_props_class Props::YesOrNo
+
+      def initialize(...)
+        super
+        props.options
+      end
+
+      def self.type
+        'YesOrNo'
+      end
     end
   end
 end

data/lib/gamefic/scene.rb

@@ -5,9 +5,10 @@ module Gamefic
   # the output to be sent to the player. The finish processes player input.
   #
   module Scene
-    require 'gamefic/scene/default'
+    require 'gamefic/scene/base'
     require 'gamefic/scene/activity'
     require 'gamefic/scene/multiple_choice'
+    require 'gamefic/scene/active_choice'
     require 'gamefic/scene/pause'
     require 'gamefic/scene/yes_or_no'
     require 'gamefic/scene/conclusion'

data/lib/gamefic/scriptable/hooks.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scriptable
+    # Scriptable hook methods are class methods that define procs to be
+    # executed in response to various game events.
+    #
+    module Hooks
+      # Define a callback to be executed before a command is processed. The
+      # callback accepts two parameters, the Actor and the Command.
+      #
+      # The optional verbs parameter can be used to restrict the callback to
+      # commands that use one of the specified verbs. If no verbs are provided,
+      # the callback will be executed before every command.
+      #
+      # Calling Command#cancel will prevent the command from being performed.
+      #
+      # @example Cancel non-meta commands when the actor does not have a parent
+      #   before_command do |actor, command|
+      #     next if actor.parent || command.meta?
+      #
+      #     actor.tell "You can't do anything while you're in limbo."
+      #     command.cancel
+      #   end
+      #
+      # @param verbs [Array<Symbol>]
+      # @yieldparam [Actor]
+      # @yieldparam [Command]
+      # @yieldself [Object<self>]
+      def before_command(*verbs, &block)
+        before_commands.push(proc do |actor, command|
+          instance_exec(actor, command, &block) if verbs.empty? || verbs.include?(command.verb)
+        end)
+      end
+
+      # Define a callback to be executed after a command is processed. The
+      # callback accepts two parameters, the Actor and the Command.
+      #
+      # The optional verbs parameter can be used to restrict the callback to
+      # commands that use one of the specified verbs. If no verbs are provided,
+      # the callback will be executed after every command.
+      #
+      # @param verbs [Array<Symbol>]
+      # @yieldparam [Actor]
+      # @yieldparam [Command]
+      # @yieldself [Object<self>]
+      def after_command(*verbs, &block)
+        after_commands.push(proc do |actor, command|
+          instance_exec(actor, command, &block) if verbs.empty? || verbs.include?(command.verb)
+        end)
+      end
+
+      # Define a callback to be executed after a scene starts.
+      #
+      # @yieldself [Object<self>]
+      def on_ready(&block)
+        ready_blocks.push block
+      end
+
+      # Define a callback to be executed for each participating player after
+      # a scene starts.
+      #
+      # @yieldparam [Actor]
+      # @yieldself [Object<self>]
+      def on_player_ready(&block)
+        ready_blocks.push(proc { players.each { |player| instance_exec(player, &block) } })
+      end
+
+      # Define a callback to be executed after a scene finishes.
+      #
+      # @yieldself [Object<self>]
+      def on_update(&block)
+        update_blocks.push block
+      end
+
+      # Define a callback to be executed for each participating player after
+      # a scene finishes.
+      #
+      # @yieldparam [Actor]
+      # @yieldself [Object<self>]
+      def on_player_update(&block)
+        update_blocks.push(proc { players.each { |player| instance_exec(player, &block) } })
+      end
+
+      # Define a callback that modifies the output sent to the player at the
+      # beginning of a game turn. The callback accepts two parameters, the
+      # Actor and the Props::Output.
+      #
+      # Narrators execute player_output blocks after starting a scene and
+      # executing ready blocks. The output gets sent to players' game clients
+      # as JSON objects to be rendered before prompting the player for input.
+      #
+      # @example Add a player's parent to the output as a custom hash value.
+      #   on_player_output do |actor, output|
+      #     output[:parent_name] = actor.parent&.name
+      #   end
+      #
+      # @yieldparam [Actor]
+      # @yieldparam [Props::Output]
+      # @yieldself [Object<self>]
+      def on_player_output(&block)
+        player_output_blocks.push(block)
+      end
+
+      # Define a callback that gets executed when a narrative reaches a
+      # conclusion.
+      #
+      # @yieldself [Object<self>]
+      def on_conclude(&block)
+        conclude_blocks.push(block)
+      end
+
+      # Define a callback that gets executed when a player reaches a 
+      # conclusion.
+      #
+      # @note A player can conclude participation in a narrative without the
+      #   narrative itself concluding.
+      #
+      # @yieldparam [Actor]
+      # @yieldself [Object<self>]
+      def on_player_conclude(&block)
+        player_conclude_blocks.push(block)
+      end
+
+      # @return [Array<Proc>]
+      def before_commands
+        @before_commands ||= []
+      end
+
+      # @return [Array<Proc>]
+      def after_commands
+        @after_commands ||= []
+      end
+
+      # @return [Array<Proc>]
+      def ready_blocks
+        @ready_blocks ||= []
+      end
+
+      # @return [Array<Proc>]
+      def update_blocks
+        @update_blocks ||= []
+      end
+
+      # @return [Array<Proc>]
+      def player_output_blocks
+        @player_output_blocks ||= []
+      end
+
+      # @return [Array<Proc>]
+      def conclude_blocks
+        @conclude_blocks ||= []
+      end
+
+      # @return [Array<Proc>]
+      def player_conclude_blocks
+        @player_conclude_blocks ||= []
+      end
+    end
+  end
+end

data/lib/gamefic/scriptable/queries.rb

@@ -5,26 +5,16 @@ module Gamefic
     # Scriptable methods related to creating action queries.
     #
     module Queries
-      include Proxies
-
-      # Define a query that searches the entire plot's entities.
+      # Define a query that searches all entities in the subject's epic.
       #
-      # @param args [Array<Object>] Query arguments
-      # @return [Query::General]
-      def anywhere *args, ambiguous: false
-        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.
+      # If the subject is not an actor, the result will always be empty.
       #
       # @param args [Array<Object>] Query arguments
-      # @return [Query::Abstract]
-      def abstract *args, ambiguous: false
-        Query::Abstract.new -> { entities }, *args, ambiguous: ambiguous
+      # @return [Query::Global]
+      def global *args
+        Query::Global.new(*args, name: 'global')
       end
+      alias anywhere global
 
       # Define a query that searches an actor's family of entities. The
       # results include the parent, siblings, children, and accessible
@@ -32,49 +22,58 @@ module Gamefic
       #
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
-      def available *args, ambiguous: false
-        Query::Scoped.new Scope::Family, *args, ambiguous: ambiguous, name: 'available'
+      def available *args
+        Query::Family.new(*args, name: 'available')
       end
       alias family available
+      alias avail available
 
       # Define a query that returns the actor's parent.
       #
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
-      def parent *args, ambiguous: false
-        Query::Scoped.new Scope::Parent, *args, ambiguous: ambiguous, name: 'parent'
+      def parent *args
+        Query::Parent.new(*args, name: 'parent')
       end
 
       # Define a query that searches an actor's children.
       #
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
-      def children *args, ambiguous: false
-        Query::Scoped.new Scope::Children, *args, ambiguous: ambiguous, name: 'children'
+      def children *args
+        Query::Children.new(*args, name: 'children')
       end
 
       # Define a query that searches an actor's descendants.
       #
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
-      def descendants *args, ambiguous: false
-        Query::Scoped.new Scope::Descendants, *args, ambiguous: ambiguous
+      def descendants *args
+        Query::Descendants.new(*args)
       end
 
       # Define a query that searches an actor's siblings.
       #
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
-      def siblings *args, ambiguous: false
-        Query::Scoped.new Scope::Siblings, *args, ambiguous: ambiguous, name: 'siblings'
+      def siblings *args
+        Query::Siblings.new(*args, name: 'siblings')
+      end
+
+      # Define a query that searches an actor's siblings and their descendants.
+      #
+      # @param args [Array<Object>] Query arguments
+      # @return [Query::Scoped]
+      def extended *args
+        Query::Extended.new(*args, name: 'extended')
       end
 
       # Define a query that returns the actor itself.
       #
       # @param args [Array<Object>] Query arguments
       # @return [Query::Scoped]
-      def myself *args, ambiguous: false
-        Query::Scoped.new Scope::Myself, *args, ambiguous: ambiguous, name: 'myself'
+      def myself *args
+        Query::Myself.new(*args, name: 'myself')
       end
 
       # Define a query that performs a plaintext search. It can take a String
@@ -84,9 +83,19 @@ module Gamefic
       #
       # @param arg [String, Regexp] The string or regular expression to match
       # @return [Query::Text]
-      def plaintext arg = /.*/
+      def plaintext(arg = /.*/)
         Query::Text.new arg, name: 'plaintext'
       end
+
+      # Define a query that matches integers. Unlike other queries, #integer
+      # does not take arguments. It will match and return an integer if the
+      # corresponding command token is an integer or the corresponding input is
+      # a string representation of an integer. A successful query returns the
+      # integer instead of an entity.
+      #
+      def integer
+        Query::Integer.new name: 'integer'
+      end
     end
   end
 end

data/lib/gamefic/scriptable/responses.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scriptable
+    module Responses
+      include Queries
+      include Syntaxes
+
+      # Create a response to a command.
+      # A Response uses the `verb` argument to identify the imperative verb
+      # that triggers the action. It can also accept queries to tokenize the
+      # remainder of the input and filter for particular entities or
+      # properties. The `block`` argument is the proc to execute when the input
+      # matches all of the Response's criteria (i.e., verb and queries).
+      #
+      # @example A simple Response.
+      #   respond :wave do |actor|
+      #     actor.tell "Hello!"
+      #   end
+      #   # The command "wave" will respond "Hello!"
+      #
+      # @example A Response that accepts a Character
+      #   respond :salute, available(Character) do |actor, character|
+      #     actor.tell "#{The character} returns your salute."
+      #   end
+      #
+      # @param verb [Symbol, String, nil] An imperative verb for the command
+      # @param args [Array<Object>] Filters for the command's tokens
+      # @yieldparam [Gamefic::Actor]
+      # @yieldself [Object<self>]
+      # @return [Response]
+      def respond verb, *args, &proc
+        response = Response.new(verb&.to_sym, *args, &proc)
+        responses.push response
+        syntaxes.push response.syntax
+        response
+      end
+
+      # Create a meta response to a command.
+      #
+      # @param verb [Symbol, String, nil] An imperative verb for the command
+      # @param args [Array<Object>] Filters for the command's tokens
+      # @yieldparam [Gamefic::Actor]
+      # @yieldself [Object<self>]
+      # @return [Response]
+      def meta verb, *args, &proc
+        response = Response.new(verb&.to_sym, *args, meta: true, &proc)
+        responses.push response
+        syntaxes.push response.syntax
+        response
+      end
+
+      # @return [Array<Response>]
+      def responses
+        @responses ||= []
+      end
+
+      # @return [Array<Response>]
+      def responses_for(*verbs)
+        symbols = verbs.map { |verb| verb&.to_sym }
+        responses.select { |response| symbols.include? response.verb }
+      end
+
+      # @return [Array<Symbol>]
+      def verbs
+        responses.select(&:verb).uniq(&:verb)
+      end
+    end
+  end
+end