gamefic 3.6.0 → 4.0.0

data/lib/gamefic/scriptable/scenes.rb

@@ -1,47 +1,52 @@
 # frozen_string_literal: true
 
+require 'set'
+
 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, &blk
-        rulebook.scenes.add klass.new(name, self, on_start: on_start, on_finish: on_finish, &blk)
-        name
+      # @return [Scene::Base]
+      attr_reader :default_scene
+
+      # @return [Scene::Conclusion]
+      attr_reader :default_conclusion
+
+      def select_default_scene(klass)
+        scene_classes.add klass
+        @default_scene = klass
       end
 
-      def preface name, klass = Scene::Activity, &start
-        rulebook.scenes.add klass.new(name, self, on_start: start)
-        name
+      def select_default_conclusion(klass)
+        scene_classes.add klass
+        @default_conclusion = klass
+      end
+
+      def named_scenes
+        @named_scenes ||= {}
+      end
+
+      def scene_classes
+        @scene_classes ||= Set.new
+      end
+
+      def scene_classes_map
+        scene_classes.each_with_object(named_scenes.clone) { |klass, hash| hash[klass] = klass }
+      end
+
+      def scenes
+        scene_classes_map.values.uniq
+      end
+
+      def block(scene, name = nil)
+        named_scenes[name] = scene if name
+        scene_classes.add scene
+        scene
+      end
+      alias scene block
+
+      def introductions
+        @introductions ||= []
       end
-      alias precursor preface
 
       # Add a block to be executed when a player is added to the game.
       # Each Plot should only have one introduction.
@@ -57,10 +62,7 @@ module Gamefic
       # @yieldparam [Props::Default]
       # @return [Symbol]
       def introduction(&start)
-        rulebook.scenes
-                .introduction Scene::Default.new nil,
-                                                 self,
-                                                 on_start: proc { |actor, _props| Stage.run(self, actor, &start) }
+        introductions.push start
       end
 
       # Create a multiple-choice scene.
@@ -68,28 +70,23 @@ module Gamefic
       # 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
+      #   multiple_choice :go_somewhere, do
+      #     on_start do |actor, props|
+      #       props.options.push 'Go to work', 'Go to school'
+      #     end
+      #
+      #     on_finish do |actor, props|
+      #       # Assuming the user selected the first choice:
+      #       props.selection #=> 'Go to work'
+      #       props.index     #=> 0
+      #       props.number    #=> 1
+      #     end
       #   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?', &blk
-        block name,
-              Scene::MultipleChoice,
-              on_start: proc { |_actor, props|
-                props.prompt = prompt
-                props.options.concat choices
-              },
-              on_finish: blk
+      # @param name [Symbol, nil]
+      # @return [Class<Scene::MultipleChoice>]
+      def multiple_choice(name = nil, &block)
+        block Class.new(Scene::MultipleChoice, &block), name
       end
 
       # Create a yes-or-no scene.
@@ -97,48 +94,36 @@ module Gamefic
       # 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."
+      #   yes_or_no :answer_scene do
+      #     on_start do |actor, props|
+      #       actor.tell 'Yes or no?'
+      #     end
+      #
+      #     on_finish do |actor, props|
+      #       if props.yes?
+      #         actor.tell 'You said yes.'
+      #       else
+      #         actor.tell 'You said no.'
+      #       end
       #     end
       #   end
       #
-      # @param name [Symbol]
-      # @param prompt [String, nil]
-      # @yieldparam [Actor]
-      # @yieldparam [Props::YesOrNo]
-      # @return [Symbol]
-      def yes_or_no name, prompt = 'Answer:', &blk
-        block name,
-              Scene::YesOrNo,
-              on_start: proc { |_actor, props|
-                props.prompt = prompt
-              },
-              on_finish: blk
+      # @param name [Symbol, nil]
+      # @return [Class<Scene::YesOrNo>]
+      def yes_or_no(name = nil, &block)
+        block Class.new(Scene::YesOrNo, &block), name
       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)
-              }
+      # @param name [Symbol, nil]
+      # @return [Class<Scene::ActiveChoice>]
+      def active_choice(name = nil, &block)
+        block Class.new(Scene::ActiveChoice, &block), name
+      end
+
+      # @param name [Symbol, nil]
+      # @return [Class<Scene::Pause>]
+      def pause(name = nil, &block)
+        block Class.new(Scene::Pause, &block), name
       end
 
       # Create a conclusion.
@@ -150,24 +135,12 @@ module Gamefic
       #     actor.tell 'GAME OVER'
       #   end
       #
-      # @param name [Symbol]
-      # @yieldparam [Actor]
-      # @return [Symbol]
-      def conclusion name, &start
-        block name,
-              Scene::Conclusion,
-              on_start: start
-      end
-
-      # @return [Array<Symbol>]
-      def scenes
-        rulebook.scenes.names
-      end
-
-      # @param name [Symbol]
-      # @return [Scene::Default, nil]
-      def scene(name)
-        rulebook.scenes[name]
+      # @param name [Symbol, nil]
+      # @return [Class<Scene::Conclusion>]
+      def conclusion(name = nil, &block)
+        block(Class.new(Scene::Conclusion) do
+          on_start(&block)
+        end, name)
       end
     end
   end

data/lib/gamefic/scriptable/seeds.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scriptable
+    module Seeds
+      def seeds
+        @seeds ||= []
+      end
+
+      def seed *methods, &block
+        seeds.push(proc { methods.flatten.each { |method| send(method) } }) unless methods.empty?
+        seeds.push block if block
+      end
+
+      # Construct an entity.
+      #
+      # This method adds an instance method for the entity and a class method to
+      # reference it with a proxy.
+      #
+      # @param name [Symbol, String] The method name for the entity
+      # @param klass [Class<Gamefic::Entity>]
+      # @return [void]
+      def construct name, klass, **opts
+        ivname = "@#{name}"
+        define_method(name) do
+          return instance_variable_get(ivname) if instance_variable_defined?(ivname)
+
+          instance_variable_set(ivname, make(klass, **unproxy(opts)))
+        end
+        seed { send(name) }
+        define_singleton_method(name) { Proxy::Attr.new(name) }
+      end
+      alias attr_make construct
+      alias attr_seed construct
+
+      # Add an entity to be seeded when the narrative gets instantiated.
+      #
+      # @param klass [Class<Gamefic::Entity>]
+      # @return [void]
+      def make klass, **opts
+        seed { make(klass, **unproxy(opts)) }
+      end
+      alias make_seed make
+      alias seed_make make
+    end
+
+    # Lazy pick an entity.
+    #
+    # @example
+    #   pick('the red box')
+    #
+    # @param args [Array]
+    # @return [Proxy]
+    def pick *args
+      Proxy::Pick.new(*args)
+    end
+    alias lazy_pick pick
+
+    # Lazy pick an entity or raise an error.
+    #
+    # @note The class method version of `pick!` returns a proxy, so the error
+    #   won't get raised until it gets unproxied in an instance.
+    #
+    def pick! *args
+      Proxy::PickEx.new(*args)
+    end
+    alias lazy_pick! pick!
+  end
+end

data/lib/gamefic/scriptable/syntaxes.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Gamefic
+  module Scriptable
+    module Syntaxes
+      # 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
+        syntaxes.push Syntax.new(command, translation)
+      end
+
+      def syntaxes
+        @syntaxes ||= []
+      end
+    end
+  end
+end

data/lib/gamefic/scriptable.rb

@@ -23,207 +23,22 @@ module Gamefic
   #   end
   #
   module Scriptable
-    autoload :Actions,     'gamefic/scriptable/actions'
-    autoload :Entities,    'gamefic/scriptable/entities'
-    autoload :Events,      'gamefic/scriptable/events'
-    autoload :Queries,     'gamefic/scriptable/queries'
-    autoload :Proxies,     'gamefic/scriptable/proxies'
-    autoload :Scenes,      'gamefic/scriptable/scenes'
-    autoload :PlotProxies, 'gamefic/scriptable/plot_proxies'
-
+    require 'gamefic/scriptable/hooks'
+    require 'gamefic/scriptable/queries'
+    require 'gamefic/scriptable/syntaxes'
+    require 'gamefic/scriptable/responses'
+    require 'gamefic/scriptable/scenes'
+    require 'gamefic/scriptable/seeds'
+
+    include Hooks
     include Queries
-    # @!parse
-    #   include Scriptable::Actions
-    #   include Scriptable::Events
-    #   include Scriptable::Scenes
-
-    # @return [Array<Block>]
-    def blocks
-      @blocks ||= []
-    end
-    alias scripts blocks
-
-    # Add a block of code to be executed during initialization.
-    #
-    # These blocks are primarily used to define actions, scenes, and hooks in
-    # the narrative's rulebook. Entities and game data should be initialized
-    # with `seed`.
-    #
-    # @example
-    #   class MyPlot < Gamefic::Plot
-    #     script do
-    #       introduction do |actor|
-    #         actor.tell 'Hello, world!'
-    #       end
-    #
-    #       respond :wait do |actor|
-    #         actor.tell 'Time passes.'
-    #       end
-    #     end
-    #   end
-    #
-    def script &block
-      blocks.push Block.new(:script, block)
-    end
-
-    # Add a block of code to generate content after initialization.
-    #
-    # Seeds run after the initial scripts have been executed. Their primary
-    # use is to add entities and other data components, especially randomized
-    # or procedurally generated content that can vary between instances.
-    #
-    # @note Seeds do not get executed when a narrative is restored from a
-    #   snapshot.
-    #
-    # @example
-    #   class MyPlot < Gamefic::Plot
-    #     seed do
-    #       @thing = make Gamefic::Entity, name: 'a thing'
-    #     end
-    #   end
-    #
-    def seed &block
-      blocks.push Block.new(:seed, block)
-    end
-
-    # @return [Array<Block>]
-    def included_blocks
-      included_modules.that_are(Scriptable)
-                      .uniq
-                      .reverse
-                      .flat_map(&:blocks)
-                      .concat(blocks)
-    end
-
-    # Seed an entity.
-    #
-    # @example
-    #   make_seed Gamefic::Entity, name: 'thing'
-    #
-    # @param klass [Class<Gamefic::Entity>]
-    # @return [Proxy]
-    def make_seed klass, **opts
-      seed { make(klass, **opts) }
-      Proxy::Pick.new(klass, opts[:name], raise: true)
-    end
-    alias make make_seed
-
-    # Seed an entity with an attribute method.
-    #
-    # @example
-    #   class Plot < Gamefic::Plot
-    #     attr_seed :thing, Gamefic::Entity, name: 'thing'
-    #   end
-    #
-    #   plot = Plot.new
-    #   plot.thing #=> #<Gamefic::Entity a thing>
-    #
-    # @param name [Symbol] The attribute name
-    # @param klass [Class<Gamefic::Entity>]
-    # @return [Proxy]
-    def attr_seed name, klass, **opts
-      ivname = "@#{name}"
-      define_method(name) do
-        return instance_variable_get(ivname) if instance_variable_defined?(ivname)
-
-        instance_variable_set(ivname, make(klass, **opts))
-      end
-      seed { send name }
-      Proxy.new(:attr, name)
-    end
-
-    # @param symbol [Symbol]
-    # @return [Proxy]
-    def proxy symbol
-      Logging.logger.warn "#{caller.first ? "#{caller.first}: " : ''}`proxy` is deprecated. Use `pick` or `pick!` instead."
-      if symbol.to_s.start_with?('@')
-        Proxy.new(:ivar, symbol)
-      else
-        Proxy.new(:attr, symbol)
-      end
-    end
-
-    # Lazy reference an entity by its instance variable.
-    #
-    # @example
-    #   lazy_ivar(:@variable)
-    #
-    # @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
-
-    # Lazy reference an entity by its attribute or method.
-    #
-    # @example
-    #   lazy_attr(:method)
-    #
-    # @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 pick an entity.
-    #
-    # @example
-    #   pick('the red box')
-    #
-    # @param args [Array]
-    # @return [Proxy]
-    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 lazy_pick! pick
-    alias _pick! pick
-
-    if RUBY_ENGINE == 'opal'
-      # :nocov:
-      def method_missing method, *args, &block
-        return super unless respond_to_missing?(method)
-
-        script { send(method, *args, &block) }
-      end
-      # :nocov:
-    else
-      def method_missing method, *args, **kwargs, &block
-        return super unless respond_to_missing?(method)
-
-        script { send(method, *args, **kwargs, &block) }
-      end
-    end
-
-    def respond_to_missing?(method, _with_private = false)
-      [Scriptable::Actions, Scriptable::Events, Scriptable::Scenes].flat_map(&:public_instance_methods)
-                                                                   .include?(method)
-    end
+    include Responses
+    include Scenes
+    include Seeds
+    include Syntaxes
 
-    # Create an anonymous module that includes the features of a Scriptable
-    # module but does not include its scripts.
-    #
-    # This can be useful when you need access to the Scriptable's constants and
-    # instance methods, but you don't want to duplicate its rules.
-    #
-    # @deprecated Removing script blocks is no longer necessary. This method
-    #   will simply return self until it's removed.
-    #
-    # @return [Module<self>]
-    def no_scripts
-      Logging.logger.warn "#{caller.first ? "#{caller.first}: " : ''}Calling `no_scripts` on Scriptable modules is no longer necessary."
-      self
+    def included_scripts
+      ancestors.that_are(Scriptable).uniq
     end
   end
 end

data/lib/gamefic/{scriptable → scripting}/entities.rb

@@ -1,32 +1,23 @@
 # frozen_string_literal: true
 
+require 'set'
+
 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 Scripting
+    # Methods related to managing entities.
     #
     module Entities
+      # extend Scriptable
       include Proxies
 
-      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
+        entity_set.to_a
       end
 
       # @return [Array<Gamefic::Actor, Gamefic::Active>]
       def players
-        player_vault.array
+        player_set.to_a
       end
 
       # Create an entity.
@@ -36,17 +27,17 @@ module Gamefic
       #     seed { make Gamefic::Entity, name: 'thing' }
       #   end
       #
-      # @param [Class<Gamefic::Entity>]
-      # @param args [Hash]
+      # @param klass [Class<Gamefic::Entity>]
       # @return [Gamefic::Entity]
       def make klass, **opts
-        entity_vault.add klass.new(**unproxy(opts))
+        klass.new(**unproxy(opts)).tap { |entity| entity_set.add entity }
       end
 
-      def destroy entity
+      def destroy(entity)
         entity.children.each { |child| destroy child }
         entity.parent = nil
-        entity_vault.delete entity
+        entity_set.delete entity
+        entity
       end
 
       def find *args
@@ -66,7 +57,6 @@ module Gamefic
       # if an entity could not be found or there is more than one possible
       # match.
       #
-      # @param description [Array]
       # @return [Gamefic::Entity, nil]
       def pick *args
         matches = find(*args)
@@ -89,6 +79,16 @@ module Gamefic
 
         matches.first
       end
+
+      private
+
+      def entity_set
+        @entity_set ||= Set.new
+      end
+
+      def player_set
+        @player_set ||= Set.new
+      end
     end
   end
 end