gamefic 2.4.0 → 3.0.0

data/lib/gamefic/scope/siblings.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scope
+    # A query scope that matches the entity's siblings, i.e., the other
+    # entities that share its parent.
+    #
+    class Siblings < Base
+      def matches
+        context.parent.children - [context]
+      end
+    end
+  end
+end

data/lib/gamefic/scope.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'gamefic/scope/base'
+require 'gamefic/scope/children'
+require 'gamefic/scope/family'
+require 'gamefic/scope/parent'
+require 'gamefic/scope/siblings'
+require 'gamefic/scope/myself'

data/lib/gamefic/scriptable/actions.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scriptable
+    # Scriptable methods related to creating actions.
+    #
+    module Actions
+      include Queries
+
+      # 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] An imperative verb for the command
+      # @param queries [Array<Query::Base, Query::Text>] Filters for the command's tokens
+      # @yieldparam [Gamefic::Actor]
+      # @return [Symbol]
+      def respond(verb, *queries, &proc)
+        args = map_response_args(queries)
+        rulebook.calls.add_response Response.new(verb, rulebook.narrative, *args, &proc)
+        verb
+      end
+
+      # Create a meta response for a command.
+      # Meta responses are very similar to standard responses, except they're
+      # flagged as meta (`Response#meta?`) to indicate that they provide a
+      # feature that is not considered an in-game action, such as displaying
+      # help documentation or a scoreboard.
+      #
+      # @example A simple meta Response
+      #   meta :credits do |actor|
+      #     actor.tell "This game was written by John Smith."
+      #   end
+      #
+      # @param verb [Symbol] An imperative verb for the command
+      # @param queries [Array<Query::Base, Query::Text>] Filters for the command's tokens
+      # @yieldparam [Gamefic::Actor]
+      # @return [Symbol]
+      def meta(verb, *queries, &proc)
+        args = map_response_args(queries)
+        rulebook.calls.add_response Response.new(verb, rulebook.narrative, *args, meta: true, &proc)
+        verb
+      end
+
+      # Add a proc to be evaluated before a character executes an action.
+      # When verbs are specified, the proc will only be evaluated if the
+      # action's verb matches them.
+      #
+      # @param verbs [Array<Symbol>]
+      # @yieldparam [Gamefic::Action]
+      # @return [Action::Hook]
+      def before_action *verbs, &block
+        rulebook.hooks.before_action *verbs, &block
+      end
+
+      # Add a proc to be evaluated after a character executes an action.
+      # When a verbs are specified, the proc will only be evaluated if the
+      # action's verb matches them.
+      #
+      # @param verbs [Array<Symbol>]
+      # @yieldparam [Gamefic::Action]
+      # @return [Action::Hook]
+      def after_action *verbs, &block
+        rulebook.hooks.after_action *verbs, &block
+      end
+
+      # Create an alternate Syntax for a response.
+      # The command and its translation can be parameterized.
+      #
+      # @example Create a synonym for an `inventory` response.
+      #   interpret "catalogue", "inventory"
+      #   # The command "catalogue" will be translated to "inventory"
+      #
+      # @example Create a parameterized synonym for a `look` response.
+      #   interpret "scrutinize :entity", "look :entity"
+      #   # The command "scrutinize chair" will be translated to "look chair"
+      #
+      # @param command [String] The format of the original command
+      # @param translation [String] The format of the translated command
+      # @return [Syntax] the Syntax object
+      def interpret command, translation
+        rulebook.calls.add_syntax Syntax.new(command, translation)
+      end
+
+      # Verbs are the symbols that have responses defined in the rulebook.
+      #
+      # @example
+      #   class MyPlot < Gamefic::Plot
+      #     script do
+      #       respond :think { |actor| actor.tell 'You think.' }
+      #
+      #       verbs #=> [:think]
+      #     end
+      #   end
+      #
+      # @return [Array<Symbol>]
+      def verbs
+        rulebook.verbs
+      end
+
+      # Synonyms are a combination of the rulebook's concrete verbs plus the
+      # alternative variants defined in syntaxes.
+      #
+      # @example
+      #   class MyPlot < Gamefic::Plot
+      #       respond :think { |actor| actor.tell 'You think.' }
+      #       interpret 'ponder', 'think'
+      #
+      #       verbs #=> [:think]
+      #       synonyms #=> [:think, :ponder]
+      #     end
+      #   end
+      #
+      # @return [Array<Symbol>]
+      def synonyms
+        rulebook.synonyms
+      end
+
+      # @return [Array<Syntax>]
+      def syntaxes
+        rulebook.syntaxes
+      end
+
+      private
+
+      def map_response_args args
+        args.map do |arg|
+          case arg
+          when Entity, Class, Module, Proc, Proxy::Agent
+            available(arg)
+          when String, Regexp
+            plaintext(arg)
+          when Gamefic::Query::Base, Gamefic::Query::Text
+            arg
+          else
+            raise ArgumentError, "invalid argument in response: #{arg.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gamefic/scriptable/entities.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scriptable
+    # Scriptable methods related to managing entities.
+    #
+    # @note The public versions of the entity and player arrays are frozen.
+    #   Authors need access to them but shouldn't modify them directly. Use
+    #   #make and #destroy instead.
+    #
+    module Entities
+      include Proxy
+
+      def entity_vault
+        @entity_vault ||= Vault.new
+      end
+
+      def player_vault
+        @player_vault ||= Vault.new
+      end
+
+      # @return [Array<Gamefic::Entity>]
+      def entities
+        entity_vault.array
+      end
+
+      # @return [Array<Gamefic::Actor, Gamefic::Active>]
+      def players
+        player_vault.array
+      end
+
+      # Create an entity.
+      #
+      # @example
+      #   class MyPlot < Gamefic::Plot
+      #     seed { make Gamefic::Entity, name: 'thing' }
+      #   end
+      #
+      # @param [Class<Gamefic::Entity>]
+      # @param args [Hash]
+      # @return [Gamefic::Entity]
+      def make klass, **opts
+        entity_vault.add klass.new(**unproxy(opts))
+      end
+
+      def destroy entity
+        entity.children.each { |child| destroy child }
+        entity.parent = nil
+        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.
+      #
+      # @param description [String]
+      # @return [Gamefic::Entity, nil]
+      def pick description
+        Gamefic::Query::General.new(entities).query(nil, description).match
+      end
+
+      # Same as #pick, but raise an error if a unique match could not be found.
+      #
+      # @param description [String]
+      # @return [Gamefic::Entity, nil]
+      def pick! description
+        ary = Gamefic::Query::General.new(entities, ambiguous: true).query(nil, description).match
+
+        raise "no entity matching '#{description}'" if ary.nil?
+
+        raise "multiple entities matching '#{description}': #{ary.join_and}" unless ary.one?
+
+        ary.first
+      end
+    end
+  end
+end

data/lib/gamefic/scriptable/events.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scriptable
+    # Scriptable methods related to creating event callbacks.
+    #
+    module Events
+      # Add a block to be executed on preparation of every turn.
+      #
+      # @example Increment a turn counter
+      #   turn = 0
+      #   on_ready do
+      #     turn += 1
+      #   end
+      #
+      def on_ready &block
+        rulebook.events.on_ready(&block)
+      end
+
+      # Add a block to be executed for each player at the beginning of a turn.
+      #
+      # @example Tell the player how many turns they've played.
+      #   on_player_ready do |player|
+      #     player[:turns] ||= 1
+      #     player.tell "Turn #{player[:turns]}"
+      #     player[:turns] += 1
+      #   end
+      #
+      # @yieldparam [Gamefic::Actor]
+      def on_player_ready &block
+        rulebook.events.on_player_ready(&block)
+      end
+
+      # Add a block to be executed after the Plot is finished updating a turn.
+      #
+      def on_update &block
+        rulebook.events.on_update(&block)
+      end
+
+      # Add a block to be executed for each player at the end of a turn.
+      #
+      # @yieldparam [Gamefic::Actor]
+      def on_player_update &block
+        rulebook.events.on_player_update(&block)
+      end
+
+      def on_conclude &block
+        rulebook.events.on_conclude(&block)
+      end
+
+      # @yieldparam [Actor]
+      # @return [Proc]
+      def on_player_conclude &block
+        rulebook.events.on_player_conclude(&block)
+      end
+
+      # @yieldparam [Actor]
+      # @yieldparam [Hash]
+      # @return [Proc]
+      def on_player_output &block
+        rulebook.events.on_player_output(&block)
+      end
+    end
+  end
+end

data/lib/gamefic/scriptable/proxy.rb

@@ -0,0 +1,55 @@
+module Gamefic
+  module Scriptable
+    # Functions that provide proxies for referencing a narrative's entities
+    # from class-level scripts.
+    #
+    module Proxy
+      # The object that fetches a proxied entity.
+      #
+      class Agent
+        attr_reader :symbol
+
+        # @param symbol [Symbol, Integer]
+        def initialize symbol
+          @symbol = symbol
+        end
+
+        def fetch container
+          if symbol.to_s =~ /^\d+$/
+            Stage.run(container, symbol) { |sym| entities[sym] }
+          elsif symbol.to_s.start_with?('@')
+            Stage.run(container, symbol) { |sym| instance_variable_get(sym) }
+          else
+            Stage.run(container, symbol) { |sym| send(sym) }
+          end
+        end
+      end
+
+      # Proxy a method or instance variable.
+      #
+      # @example
+      #   proxy(:method_name)
+      #   proxy(:@instance_variable_name)
+      #
+      # @param symbol [Symbol]
+      def proxy symbol
+        Agent.new(symbol)
+      end
+
+      # @param object [Object]
+      # @return [Object]
+      def unproxy object
+        case object
+        when Agent
+          object.fetch self
+        when Array
+          object.map { |obj| unproxy obj }
+        when Hash
+          object.transform_values { |val| unproxy val }
+        else
+          object
+        end
+      end
+    end
+  end
+end

data/lib/gamefic/scriptable/queries.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scriptable
+    # Scriptable methods related to creating action queries.
+    #
+    module Queries
+      include Proxy
+
+      # Define a query that searches the entire plot's entities.
+      #
+      # @param args [Array<Object>] Query arguments
+      # @return [Query::General]
+      def anywhere *args, ambiguous: false
+        Query::General.new -> { entities }, *unproxy(args), ambiguous: ambiguous
+      end
+
+      # Define a query that searches an actor's family of entities. The
+      # results include the parent, siblings, children, and accessible
+      # descendants of siblings and children.
+      #
+      # @param args [Array<Object>] Query arguments
+      # @return [Query::Scoped]
+      def available *args, ambiguous: false
+        Query::Scoped.new Scope::Family, *unproxy(args), ambiguous: ambiguous
+      end
+      alias family 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, *unproxy(args), ambiguous: ambiguous
+      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, *unproxy(args), ambiguous: ambiguous
+      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, *unproxy(args), ambiguous: ambiguous
+      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, *unproxy(args), ambiguous: ambiguous
+      end
+
+      # Define a query that performs a plaintext search. It can take a String
+      # or a RegExp as an argument. If no argument is provided, it will match
+      # any text it finds in the command. A successful query returns the
+      # corresponding text instead of an entity.
+      #
+      # @param arg [String, Regrxp] The string or regular expression to match
+      # @return [Query::Text]
+      def plaintext arg = nil
+        Query::Text.new arg
+      end
+    end
+  end
+end

data/lib/gamefic/scriptable/scenes.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scriptable
+    # Scriptable methods related to creating scenes.
+    #
+    module Scenes
+      # Block a new scene.
+      #
+      # @example Prompt the player for a name
+      #   block :name_of_scene do |scene|
+      #     # The scene's start occurs before the user gets prompted for input
+      #     scene.on_start do |actor, props|
+      #       props.prompt = 'What's your name?'
+      #     end
+      #
+      #     # The scene's finish is where you can process the user's input
+      #     scene.on_finish do |actor, props|
+      #       if props.input.empty?
+      #         # You can use recue to start the scene again
+      #         actor.recue
+      #       else
+      #         actor.tell "Hello, #{props.input}!"
+      #       end
+      #     end
+      #   end
+      #
+      # @param name [Symbol]
+      # @param klass [Class<Scene::Default>]
+      # @param on_start [Proc, nil]
+      # @param on_finish [Proc, nil]
+      # @param block [Proc]
+      # @yieldparam [Scene]
+      # @return [Symbol]
+      def block name, klass = Scene::Default, on_start: nil, on_finish: nil, &block
+        rulebook.scenes.add klass.new(name, rulebook.narrative, on_start: on_start, on_finish: on_finish, &block)
+        name
+      end
+      alias scene block
+
+      # Add a block to be executed when a player is added to the game.
+      # Each Plot should only have one introduction.
+      #
+      # @example Welcome the player to the game
+      #   introduction do |actor|
+      #     actor.tell "Welcome to the game!"
+      #   end
+      #
+      # @raise [ArgumentError] if an introduction already exists
+      #
+      # @yieldparam [Gamefic::Actor]
+      # @yieldparam [Props::Default]
+      # @return [Symbol]
+      def introduction(&start)
+        rulebook.scenes
+                .introduction Scene::Default.new nil,
+                                                 rulebook.narrative,
+                                                 on_start: proc { |actor, _props| instance_exec(actor, &start) }
+      end
+
+      # Create a multiple-choice scene.
+      # The user will be required to make a choice to continue. The scene
+      # will restart if the user input is not a valid choice.
+      #
+      # @example
+      #   multiple_choice :go_somewhere, ['Go to work', 'Go to school'] do |actor, props|
+      #     # Assuming the user selected the first choice:
+      #     props.selection #=> 'Go to work'
+      #     props.index     #=> 0
+      #     props.number    #=> 1
+      #   end
+      #
+      # @param name [Symbol]
+      # @param choices [Array<String>]
+      # @param prompt [String, nil]
+      # @param proc [Proc]
+      # @yieldparam [Actor]
+      # @yieldparam [Props::MultipleChoice]
+      # @return [Symbol]
+      def multiple_choice name, choices = [], prompt = 'What is your choice?', &block
+        block name,
+              Scene::MultipleChoice,
+              on_start: proc { |_actor, props|
+                props.prompt = prompt
+                props.options.concat choices
+              },
+              on_finish: block
+      end
+
+      # Create a yes-or-no scene.
+      # The user will be required to answer Yes or No to continue. The scene
+      # will restart if the user input is not a valid choice.
+      #
+      # @example
+      #   yes_or_no :answer_scene, 'What is your answer?' do |actor, props|
+      #     if props.yes?
+      #       actor.tell "You said yes."
+      #     else
+      #       actor.tell "You said no."
+      #     end
+      #   end
+      #
+      # @param name [Symbol]
+      # @param prompt [String, nil]
+      # @yieldparam [Actor]
+      # @yieldparam [Props::YesOrNo]
+      # @return [Symbol]
+      def yes_or_no name, prompt = 'Answer:', &block
+        block name,
+              Scene::YesOrNo,
+              on_start: proc { |_actor, props|
+                props.prompt = prompt
+              },
+              on_finish: block
+      end
+
+      # Create a scene that pauses the game.
+      # This scene will execute the specified block and wait for input from the
+      # the user (e.g., pressing Enter) to continue.
+      #
+      # @example
+      #   pause :wait do |actor|
+      #     actor.tell "After you continue, you will be prompted for a command."
+      #   end
+      #
+      # @param name [Symbol]
+      # @param prompt [String, nil] The text to display when prompting the user to continue
+      # @yieldparam [Actor]
+      # @return [Symbol]
+      def pause name, prompt: 'Press enter to continue...', &start
+        block name,
+              Scene::Pause,
+              on_start: proc { |actor, props|
+                props.prompt = prompt if prompt
+                instance_exec(actor, props, &start)
+              }
+      end
+
+      # Create a conclusion.
+      # The game (or the character's participation in it) will end after this
+      # scene is complete.
+      #
+      # @example
+      #   conclusion :ending do |actor|
+      #     actor.tell 'GAME OVER'
+      #   end
+      #
+      # @param name [Symbol]
+      # @yieldparam [Actor]
+      # @return [Symbol]
+      def conclusion name, &start
+        block name,
+              Scene::Conclusion,
+              on_start: start
+      end
+
+      def scenes
+        rulebook.scenes.names
+      end
+    end
+  end
+end