gamefic 3.3.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85e6fc4d2b5c4a9abfe20cbbe17affdec1f1badb134e8cad88849a5305fb9bf0
-  data.tar.gz: 97a29823857d93fafa9e8a3bc4872e27a4a6da480f589535da6abf254eb5aa7a
+  metadata.gz: 79b61813b56cbbabb76ecbef9abb370b2fe77b58ea3e155377f8c4dfd2677684
+  data.tar.gz: 611c108a0c080796c8308bee5f3e361c60fc4ddd316234bf9468c09742b1a52d
 SHA512:
-  metadata.gz: 611c3b366e76a29cd2ffb95f906882a63ac9d73bfb6d1d7aaa505e4470f4526311704c2245285f908247b6248b086914d8a145e1c9b86577e197d8d77c707939
-  data.tar.gz: dc19cf51ab4edbc1b9f9708eb543c977527e3165a949d948782349e545d0a32fde42f8532c9071e0ddc86b521cc0d1cb778e8e88b1d7b0dcc575d547c5db1df1
+  metadata.gz: 85732c76dae467bd5d032462ca23d34b03b7be59c6327202fd9bef307ef3d06bc40af085f32010cfae9dfd93a85b20524785313388964772534632cc95159625
+  data.tar.gz: 5c3db85ff44b268bd7604d33e28b92ca454c82c2a812f023af39a3da816a4252dfea01869d313f1ab6d24a1f062782ac002f5bf8fc40fd435efaa0c1ac14d337

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 3.4.0 - September 10, 2024
+- Chapters
+- Subplots and chapters do not repeat plot scripts
+- Scriptable.no_scripts is deprecated
+- Refactoring/removing unused methods
+
 ## 3.3.0 - September 1, 2024
 - Node#take
 - Node#include?

data/lib/gamefic/action.rb

@@ -16,12 +16,12 @@ module Gamefic
       # @param [Array<Symbol>]
       attr_reader :verbs
 
-      # @param [Proc]
-      attr_reader :block
+      # @param [Callback]
+      attr_reader :callback
 
-      def initialize *verbs, &block
+      def initialize verbs, callback
         @verbs = verbs
-        @block = block
+        @callback = callback
       end
 
       def match?(input)

data/lib/gamefic/callback.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Gamefic
+  class Callback
+    # @param narrative [Narrative]
+    # @param code [Proc]
+    def initialize narrative, code
+      @narrative = narrative
+      @code = code
+    end
+
+    def run *args
+      Stage.run @narrative, *args, &@code
+    end
+  end
+end

data/lib/gamefic/chapter.rb

@@ -0,0 +1,88 @@
+# 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 a few important exceptions:
+  # * Chapters persist for the duration of the plot.
+  # * Players do not need to be introduced to a chapter.
+  # * Scripts in chapters apply to the parent plot's rulebook.
+  # * Using `make` to create an entity in a chapter adds it to the parent
+  #   plot's entity list.
+  #
+  # @example
+  #   class MyChapter < Gamefic::Chapter
+  #     seed do
+  #       @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.instance_exec { @thing } #=> nil
+  #
+  class Chapter
+    extend Scriptable
+
+    include Scriptable::Actions
+    include Scriptable::Events
+    include Scriptable::Proxy
+    include Scriptable::Queries
+    include Scriptable::Scenes
+
+    # @return [Plot]
+    attr_reader :plot
+
+    # @param plot [Plot]
+    def initialize plot
+      @plot = plot
+    end
+
+    def included_blocks
+      self.class.included_blocks - plot.included_blocks
+    end
+
+    def seed
+      included_blocks.select(&:seed?).each { |blk| Stage.run self, &blk.code }
+    end
+
+    def script
+      included_blocks.select(&:script?).each { |blk| Stage.run self, &blk.code }
+    end
+
+    def rulebook
+      plot.rulebook
+    end
+
+    def make klass, **opts
+      plot.make klass, **opts
+    end
+
+    def entities
+      plot.entities
+    end
+
+    def players
+      plot.players
+    end
+
+    def destroy entity
+      plot.destroy entity
+    end
+
+    def pick description
+      plot.pick description
+    end
+
+    def pick! description
+      plot.pick! description
+    end
+  end
+end

data/lib/gamefic/narrative.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module Gamefic
   # A base class for building and managing the resources that compose a story.
   # The Plot and Subplot classes inherit from Narrative and provide additional
@@ -19,10 +21,27 @@ module Gamefic
     attr_reader :rulebook
 
     def initialize
-      self.class.included_blocks.select(&:seed?).each { |blk| Stage.run self, &blk.code }
+      seed
+      script
+      post_initialize
+    end
+
+    def seed
+      included_blocks.select(&:seed?).each { |blk| Stage.run self, &blk.code }
+    end
+
+    def script
+      @rulebook = Rulebook.new
+      included_blocks.select(&:script?).each { |blk| Stage.run self, &blk.code }
+    end
+
+    def included_blocks
+      self.class.included_blocks
+    end
+
+    def post_initialize
       entity_vault.lock
-      @rulebook = nil
-      hydrate
+      rulebook.freeze
     end
 
     def scenes
@@ -91,9 +110,8 @@ module Gamefic
     end
 
     def hydrate
-      @rulebook = Rulebook.new(self)
-      @rulebook.script_with_defaults
-      @rulebook.freeze
+      script
+      post_initialize
     end
 
     def self.inherited klass

data/lib/gamefic/plot.rb

@@ -5,12 +5,26 @@ module Gamefic
   # methods for creating entities, actions, scenes, and hooks.
   #
   class Plot < Narrative
+    def seed
+      super
+      chapters.each(&:seed)
+    end
+
+    def script
+      super
+      chapters.each(&:script)
+      rulebook.scenes.with_defaults self
+    end
+
+    def chapters
+      @chapters ||= self.class.appended_chapters.map { |klass| klass.new(self) }
+    end
+
     def ready
       super
       subplots.each(&:ready)
       players.each(&:start_take)
       subplots.each(&:conclude) if concluding?
-
       players.select(&:concluding?).each { |plyr| rulebook.run_player_conclude_blocks plyr }
       subplots.delete_if(&:concluding?)
     end
@@ -76,6 +90,14 @@ module Gamefic
       subplots.each(&:hydrate)
     end
 
+    def self.append chapter
+      appended_chapters.add chapter
+    end
+
+    def self.appended_chapters
+      @appended_chapters ||= Set.new
+    end
+
     def self.restore data
       Snapshot.restore data
     end

data/lib/gamefic/response.rb

@@ -11,9 +11,6 @@ module Gamefic
     # @return [Array<Query::Base>]
     attr_reader :queries
 
-    # @return [Narrative]
-    attr_reader :narrative
-
     # @param verb [Symbol]
     # @param narrative [Narrative]
     # @param queries [Array<Query::Base>]
@@ -21,10 +18,10 @@ module Gamefic
     # @param block [Proc]
     def initialize verb, narrative, *queries, meta: false, &block
       @verb = verb
-      @narrative = narrative
       @queries = map_queryable_objects(queries)
       @meta = meta
       @block = block
+      @callback = Callback.new(narrative, block)
     end
 
     # The `meta?` flag is just a way for authors to identify responses that
@@ -70,7 +67,7 @@ module Gamefic
     end
 
     def execute *args
-      Stage.run(narrative, *args, &@block)
+      @callback.run *args
     end
 
     def precision

data/lib/gamefic/rulebook/calls.rb

@@ -67,10 +67,6 @@ module Gamefic
         verb_response_map.empty? && synonym_syntax_map.empty?
       end
 
-      def self.new_array_map
-        Hash.new { |hash, key| hash[key] = [] }
-      end
-
       private
 
       attr_reader :verb_response_map

data/lib/gamefic/rulebook/events.rb

@@ -35,44 +35,30 @@ module Gamefic
       end
 
       # @return [void]
-      def on_ready &block
-        @ready_blocks.push block
+      def on_ready callback
+        @ready_blocks.push callback
       end
 
-      # @yieldparam [Actor]
-      # @return [void]
-      def on_player_ready &block
-        @ready_blocks.push(proc do
-          players.each { |plyr| instance_exec plyr, &block }
-        end)
-      end
-
-      def on_update &block
-        @update_blocks.push block
-      end
-
-      def on_player_update &block
-        @update_blocks.push(proc do
-          players.each { |plyr| instance_exec plyr, &block }
-        end)
+      def on_update callback
+        @update_blocks.push callback
       end
 
       # @return [void]
-      def on_conclude &block
-        @conclude_blocks.push block
+      def on_conclude callback
+        @conclude_blocks.push callback
       end
 
       # @yieldparam [Actor]
       # @return [void]
-      def on_player_conclude &block
-        @player_conclude_blocks.push block
+      def on_player_conclude callback
+        @player_conclude_blocks.push callback
       end
 
       # @yieldparam [Actor]
       # @yieldparam [Hash]
       # @return [void]
-      def on_player_output &block
-        @player_output_blocks.push block
+      def on_player_output callback
+        @player_output_blocks.push callback
       end
     end
   end

data/lib/gamefic/rulebook/hooks.rb

@@ -21,35 +21,35 @@ module Gamefic
         self
       end
 
-      def before_action *verbs, &block
-        before_actions.push Action::Hook.new(*verbs, &block)
+      def before_action narrative, *verbs, &block
+        before_actions.push Action::Hook.new(verbs, Callback.new(narrative, block))
       end
 
-      def after_action *verbs, &block
-        after_actions.push Action::Hook.new(*verbs, &block)
+      def after_action narrative, *verbs, &block
+        after_actions.push Action::Hook.new(verbs, Callback.new(narrative, block))
       end
 
       def empty?
         before_actions.empty? && after_actions.empty?
       end
 
-      def run_before action, narrative
-        run_action_hooks action, narrative, before_actions
+      def run_before action
+        run_action_hooks action, before_actions
       end
 
-      def run_after action, narrative
-        run_action_hooks action, narrative, after_actions
+      def run_after action
+        run_action_hooks action, after_actions
       end
 
       private
 
-      def run_action_hooks action, narrative, hooks
+      def run_action_hooks action, hooks
         hooks.each do |hook|
           break if action.cancelled?
 
           next unless hook.match?(action.verb)
 
-          Stage.run(narrative) { instance_exec(action, &hook.block) }
+          hook.callback.run action
         end
       end
     end

data/lib/gamefic/rulebook.rb

@@ -25,12 +25,7 @@ module Gamefic
     # @return [Scenes]
     attr_reader :scenes
 
-    # @return [Narrative]
-    attr_reader :narrative
-
-    # @param narrative [Narrative]
-    def initialize(narrative)
-      @narrative = narrative
+    def initialize
       @calls = Calls.new
       @events = Events.new
       @hooks = Hooks.new
@@ -96,44 +91,35 @@ module Gamefic
     end
 
     def run_ready_blocks
-      events.ready_blocks.each { |blk| Stage.run narrative, &blk }
+      events.ready_blocks.each(&:run)
     end
 
     def run_update_blocks
-      events.update_blocks.each { |blk| Stage.run narrative, &blk }
+      events.update_blocks.each(&:run)
     end
 
     def run_before_actions action
-      hooks.run_before action, narrative
+      hooks.run_before action
     end
 
     def run_after_actions action
-      hooks.run_after action, narrative
+      hooks.run_after action
     end
 
     def run_conclude_blocks
-      events.conclude_blocks.each { |blk| Stage.run narrative, &blk }
+      events.conclude_blocks.each(&:run)
     end
 
     def run_player_conclude_blocks player
-      events.player_conclude_blocks.each { |blk| Stage.run(narrative, player, &blk) }
+      events.player_conclude_blocks.each { |blk| blk.run(player) }
     end
 
     def run_player_output_blocks player, output
-      events.player_output_blocks.each { |blk| Stage.run(narrative, player, output, &blk) }
+      events.player_output_blocks.each { |blk| blk.run(player, output) }
     end
 
     def empty?
       calls.empty? && hooks.empty? && scenes.empty? && events.empty?
     end
-
-    def script
-      narrative.class.included_blocks.select(&:script?).each { |blk| Stage.run(narrative, &blk.code) }
-    end
-
-    def script_with_defaults
-      script
-      scenes.with_defaults narrative
-    end
   end
 end

data/lib/gamefic/scriptable/actions.rb

@@ -31,7 +31,7 @@ module Gamefic
       # @return [Symbol]
       def respond(verb, *queries, &proc)
         args = map_response_args(queries)
-        rulebook.calls.add_response Response.new(verb, rulebook.narrative, *args, &proc)
+        rulebook.calls.add_response Response.new(verb, self, *args, &proc)
         verb
       end
 
@@ -52,7 +52,7 @@ module Gamefic
       # @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)
+        rulebook.calls.add_response Response.new(verb, self, *args, meta: true, &proc)
         verb
       end
 
@@ -64,7 +64,7 @@ module Gamefic
       # @yieldparam [Gamefic::Action]
       # @return [Action::Hook]
       def before_action *verbs, &block
-        rulebook.hooks.before_action *verbs, &block
+        rulebook.hooks.before_action self, *verbs, &block
       end
 
       # Add a proc to be evaluated after a character executes an action.
@@ -75,7 +75,7 @@ module Gamefic
       # @yieldparam [Gamefic::Action]
       # @return [Action::Hook]
       def after_action *verbs, &block
-        rulebook.hooks.after_action *verbs, &block
+        rulebook.hooks.after_action self, *verbs, &block
       end
 
       # Create an alternate Syntax for a response.

data/lib/gamefic/scriptable/events.rb

@@ -14,7 +14,7 @@ module Gamefic
       #   end
       #
       def on_ready &block
-        rulebook.events.on_ready(&block)
+        rulebook.events.on_ready(Callback.new(self, block))
       end
 
       # Add a block to be executed for each player at the beginning of a turn.
@@ -28,37 +28,43 @@ module Gamefic
       #
       # @yieldparam [Gamefic::Actor]
       def on_player_ready &block
-        rulebook.events.on_player_ready(&block)
+        wrapper = proc do
+          players.each { |player| Stage.run(self, player, &block) }
+        end
+        on_ready &wrapper
       end
 
       # Add a block to be executed after the Plot is finished updating a turn.
       #
       def on_update &block
-        rulebook.events.on_update(&block)
+        rulebook.events.on_update(Callback.new(self, 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)
+        wrapper = proc do
+          players.each { |player| Stage.run(self, player, &block) }
+        end
+        on_update &wrapper
       end
 
       def on_conclude &block
-        rulebook.events.on_conclude(&block)
+        rulebook.events.on_conclude(Callback.new(self, block))
       end
 
       # @yieldparam [Actor]
       # @return [Proc]
       def on_player_conclude &block
-        rulebook.events.on_player_conclude(&block)
+        rulebook.events.on_player_conclude(Callback.new(self, block))
       end
 
       # @yieldparam [Actor]
       # @yieldparam [Hash]
       # @return [Proc]
       def on_player_output &block
-        rulebook.events.on_player_output(&block)
+        rulebook.events.on_player_output Callback.new(self, block)
       end
     end
   end

data/lib/gamefic/scriptable/scenes.rb

@@ -33,13 +33,13 @@ module Gamefic
       # @yieldparam [Scene]
       # @return [Symbol]
       def block name, klass = Scene::Default, on_start: nil, on_finish: nil, &blk
-        rulebook.scenes.add klass.new(name, rulebook.narrative, on_start: on_start, on_finish: on_finish, &blk)
+        rulebook.scenes.add klass.new(name, self, on_start: on_start, on_finish: on_finish, &blk)
         name
       end
       alias scene block
 
       def preface name, klass = Scene::Activity, &start
-        rulebook.scenes.add klass.new(name, rulebook.narrative, on_start: start)
+        rulebook.scenes.add klass.new(name, self, on_start: start)
         name
       end
       alias precursor preface
@@ -60,7 +60,7 @@ module Gamefic
       def introduction(&start)
         rulebook.scenes
                 .introduction Scene::Default.new nil,
-                                                 rulebook.narrative,
+                                                 self,
                                                  on_start: proc { |actor, _props| Stage.run(self, actor, &start) }
       end
 

data/lib/gamefic/scriptable.rb

@@ -117,6 +117,7 @@ module Gamefic
     #   plot = Plot.new
     #   plot.thing #=> #<Gamefic::Entity a thing>
     #
+    # @param name [Symbol] The attribute name
     # @param klass [Class<Gamefic::Entity>]
     def attr_seed name, klass, **opts
       @count ||= 0
@@ -154,35 +155,13 @@ module Gamefic
     # 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.
     #
-    # @example
-    #   # Plot and Subplot will both include the `info` method, but
-    #   # only Plot will implement the `think` action.
-    #
-    #   module Shared
-    #     extend Gamefic::Scriptable
-    #
-    #     def info
-    #       "This method was added by the Shared module."
-    #     end
-    #
-    #     respond :think do |actor|
-    #       actor.tell 'You ponder your predicament.'
-    #     end
-    #   end
+    # @deprecated Removing script blocks is no longer necessary. This method
+    #   will simply return self until it's removed.
     #
-    #   class Plot < Gamefic::Plot
-    #     include Shared
-    #   end
-    #
-    #   class Subplot < Gamefic::Subplot
-    #     include Shared.no_scripts
-    #   end
-    #
-    # @return [Module]
+    # @return [Module<self>]
     def no_scripts
-      Module.new.tap do |mod|
-        append_features(mod)
-      end
+      Logging.logger.warn 'Calling `no_scripts` on Scriptable modules is no longer necessary.'
+      self
     end
   end
 end

data/lib/gamefic/subplot.rb

@@ -25,6 +25,10 @@ module Gamefic
       [introduce].flatten.each { |pl| self.introduce pl }
     end
 
+    def included_blocks
+      super - plot.included_blocks
+    end
+
     def ready
       super
       conclude if concluding?
@@ -68,11 +72,5 @@ module Gamefic
     def inspect
       "#<#{self.class}>"
     end
-
-    def hydrate
-      @rulebook = Rulebook.new(self)
-      @rulebook.script
-      @rulebook.freeze
-    end
   end
 end

data/lib/gamefic/version.rb

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

data/lib/gamefic.rb

@@ -8,6 +8,7 @@ require 'gamefic/core_ext/string'
 require 'gamefic/syntax'
 require 'gamefic/response'
 require 'gamefic/rulebook'
+require 'gamefic/callback'
 require 'gamefic/query'
 require 'gamefic/scanner'
 require 'gamefic/scope'
@@ -22,6 +23,7 @@ require 'gamefic/stage'
 require 'gamefic/vault'
 require 'gamefic/narrative'
 require 'gamefic/plot'
+require 'gamefic/chapter'
 require 'gamefic/subplot'
 require 'gamefic/snapshot'
 require 'gamefic/node'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gamefic
 version: !ruby/object:Gem::Version
-  version: 3.3.0
+  version: 3.4.0
 platform: ruby
 authors:
 - Fred Snyder
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-01 00:00:00.000000000 Z
+date: 2024-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: opal
@@ -135,6 +135,8 @@ files:
 - lib/gamefic/active/take.rb
 - lib/gamefic/actor.rb
 - lib/gamefic/block.rb
+- lib/gamefic/callback.rb
+- lib/gamefic/chapter.rb
 - lib/gamefic/command.rb
 - lib/gamefic/composer.rb
 - lib/gamefic/core_ext/array.rb