gamefic 2.4.0 → 3.0.0

data/lib/gamefic/scriptable.rb

@@ -1,94 +1,188 @@
+# frozen_string_literal: true
+
+require 'set'
+
 module Gamefic
-  # The Scriptable module provides a clean room (aka "theater") for scripts.
-  #
-  # @!method stage(*args, &block)
-  #   Execute a block of code in a subset of the owner's scope.
+  # A class module that enables scripting.
   #
-  #   The provided code is evaluated inside a clean room object that has its
-  #   own instance variables and access to the owner's public methods. The proc
-  #   can accept the method call's arguments.
+  # Narratives extend Scriptable to enable definition of scripts and seeds.
+  # Modules can also be extended with Scriptable to make them includable to
+  # other Scriptables.
   #
-  #   @example Execute a block of code
-  #     stage {
-  #       puts 'Hello'
-  #     }
+  # @example Include a scriptable module in a plot
+  #   module MyScript
+  #     extend Gamefic::Scriptable
   #
-  #   @example Execute a block of code with arguments
-  #     stage 'hello' { |message|
-  #       puts message # <- prints 'hello'
-  #     }
+  #     respond :myscript do |actor|
+  #       actor.tell "This command was added by MyScript"
+  #     end
+  #   end
   #
-  #   @example Use an instance variable
-  #     stage { @message = 'hello'" }
-  #     stage { puts @message } # <- prints 'hello'
+  #   class MyPlot < Gamefic::Plot
+  #     include MyScript
+  #   end
   #
-  #   @yieldpublic [Gamefic::Plot]
-  #   @return [Object] The value returned by the executed code
-  #
-  # @!method theater
-  #   The object that acts as an isolated namespace for staged code.
-  #   @return [Object]
-  #
-  # @!parse alias cleanroom theater
   module Scriptable
-    module ClassMethods
-      # An array of blocks that were added by the `script` class method.
-      #
-      # @return [Array<Proc>]
-      def blocks
-        @blocks ||= []
-      end
+    autoload :Actions,   'gamefic/scriptable/actions'
+    autoload :Entities,  'gamefic/scriptable/entities'
+    autoload :Events,    'gamefic/scriptable/events'
+    autoload :Queries,   'gamefic/scriptable/queries'
+    autoload :Proxy,     'gamefic/scriptable/proxy'
+    autoload :Scenes,    'gamefic/scriptable/scenes'
 
-      # Add a block to be executed by the instance's `stage` method.
-      #
-      # Note that `script` does not execute the block instantly, but stores
-      # it in the `blocks` array to be executed later.
-      #
-      # @yieldpublic [Gamefic::Plot]
-      def script &block
-        blocks.push block
-      end
+    include Proxy
+    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
 
-    def self.included klass
-      klass.extend ClassMethods
+    # 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
 
-    private
+    # @return [Array<Block>]
+    def included_blocks
+      included_modules.that_are(Scriptable)
+                      .uniq
+                      .reverse
+                      .flat_map(&:blocks)
+                      .concat(blocks)
+    end
 
-    # Execute all the scripts that were added by the `script` class method.
+    # Seed an entity.
+    #
+    # @example
+    #   make_seed Gamefic::Entity, name: 'thing'
     #
-    def run_scripts
-      self.class.blocks.each { |blk| stage &blk }
+    # @param klass [Class<Gamefic::Entity>]
+    def make_seed klass, **opts
+      @count ||= 0
+      seed { make(klass, **opts) }
+      @count.tap { @count += 1 }
     end
-  end
-end
 
-# @note #stage and #theater are implemented this way so the clean room object
-#   defines its classes and modules in the root namespace.
-Gamefic::Scriptable.module_exec do
-  define_method :stage do |*args, &block|
-    theater.instance_exec *args, &block
-  end
+    # 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 klass [Class<Gamefic::Entity>]
+    def attr_seed name, klass, **opts
+      @count ||= 0
+      seed do
+        instance_variable_set("@#{name}", make(klass, **opts))
+        self.class.define_method(name) { instance_variable_get("@#{name}") }
+      end
+      @count.tap { @count += 1 }
+    end
+
+    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
 
-  define_method :theater do
-    @theater ||= begin
-      instance = self
-      theater ||= Object.new
-      theater.instance_exec do
-        if RUBY_ENGINE == 'opal' || RUBY_VERSION =~ /^2\.[456]\./
-          define_singleton_method :method_missing do |symbol, *args, &block|
-            instance.public_send :public_send, symbol, *args, &block
-          end
-        else
-          define_singleton_method :method_missing do |symbol, *args, **splat, &block|
-            instance.public_send :public_send, symbol, *args, **splat, &block
-          end
-        end
+    # 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.
+    #
+    # @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
+    #
+    #   class Plot < Gamefic::Plot
+    #     include Shared
+    #   end
+    #
+    #   class Subplot < Gamefic::Subplot
+    #     include Shared.no_scripts
+    #   end
+    #
+    # @return [Module]
+    def no_scripts
+      Module.new.tap do |mod|
+        append_features(mod)
       end
-      theater.extend Gamefic::Serialize
-      theater
     end
   end
-  alias cleanroom theater
 end

data/lib/gamefic/snapshot.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'corelib/marshal' if RUBY_ENGINE == 'opal' # Required in browser
+require 'base64'
+
+module Gamefic
+  # Save and restore plots.
+  #
+  module Snapshot
+    # Save a base64-encoded snapshot of a plot.
+    #
+    # @param plot [Plot]
+    # @return [String]
+    def self.save plot
+      cache = plot.detach
+      binary = Marshal.dump(plot)
+      plot.attach cache
+      Base64.encode64(binary)
+    end
+
+    # Restore a plot from a base64-encoded string.
+    #
+    # @param snapshot [String]
+    # @return [Plot]
+    def self.restore snapshot
+      binary = Base64.decode64(snapshot)
+      Marshal.load(binary).tap do |plot|
+        plot.hydrate
+        # @todo Opal marshal dumps are not idempotent
+        next if RUBY_ENGINE == 'opal' || Snapshot.save(plot) == snapshot
+
+        Logging.logger.warn "Scripts modified #{plot.class} data. Snapshot may not have restored properly"
+      end
+    end
+  end
+end

data/lib/gamefic/stage.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Gamefic
+  # A safe execution environment for narrative code.
+  #
+  module Stage
+    module_function
+
+    # @param narrative [Narrative]
+    def run(narrative, *args, &code)
+      container = narrative.clone
+      narrative.instance_exec(*args, &code).tap { validate_changes narrative, container, code }
+    end
+
+    OVERWRITEABLE_CLASSES = [String, Numeric, Symbol].freeze
+
+    SWAPPABLE_VALUES = [true, false, nil].freeze
+
+    class << self
+      private
+
+      def validate_changes narrative, container, code
+        container.instance_variables.each do |var|
+          next unless narrative.instance_variables.include?(var)
+
+          cval = container.instance_variable_get(var)
+
+          nval = narrative.instance_variable_get(var)
+          next if cval == nval
+
+          validate_overwriteable(cval, nval, "Unsafe reassignment of #{var} in #{code}")
+        end
+      end
+
+      def validate_overwriteable cval, nval, error
+        raise error unless overwriteable?(cval, nval)
+      end
+
+      def overwriteable? cval, nval
+        return true if swappable?(cval, nval)
+
+        allowed = OVERWRITEABLE_CLASSES.find { |klass| cval.is_a?(klass) }
+        allowed && cval.is_a?(allowed)
+      end
+
+      def swappable? *values
+        values.all? { |val| SWAPPABLE_VALUES.include?(val) }
+      end
+    end
+  end
+end

data/lib/gamefic/subplot.rb

@@ -1,106 +1,78 @@
+# frozen_string_literal: true
+
 require 'gamefic/plot'
 
 module Gamefic
   # Subplots are disposable plots that run inside a parent plot. They can be
-  # started and concluded at any time during the parent plot's execution.
+  # started and concluded at any time during the parent plot's runtime.
   #
-  class Subplot
-    include World
-    include Scriptable
-    include Gamefic::Serialize
-    # @!parse extend Scriptable::ClassMethods
+  class Subplot < Narrative
+    # @return [Hash]
+    attr_reader :config
 
-    # @return [Gamefic::Plot]
+    # @return [Plot]
     attr_reader :plot
 
     # @param plot [Gamefic::Plot]
-    # @param introduce [Gamefic::Actor, nil]
-    # @param next_cue [Class<Gamefic::Scene::Base>, nil]
-    # @param more [Hash]
-    def initialize plot, introduce: nil, next_cue: nil, **more
+    # @param introduce [Gamefic::Actor, Array<Gamefic::Actor>, nil]
+    # @param config [Hash]
+    def initialize plot, introduce: [], **config
       @plot = plot
-      @next_cue = next_cue
-      @concluded = false
-      @more = more
-      configure **more
-      run_scripts
-      playbook.freeze
-      self.introduce introduce unless introduce.nil?
-      @static = [self] + scene_classes + entities
-    end
-
-    def static
-      plot.static
-    end
-
-    def players
-      @players ||= []
-    end
-
-    def subplot
-      self
-    end
-
-    def default_scene
-      plot.default_scene
-    end
-
-    def default_conclusion
-      plot.default_conclusion
-    end
-
-    def playbook
-      @playbook ||= Gamefic::Plot::Playbook.new
+      @config = config
+      configure
+      @config.freeze
+      super()
+      [introduce].flatten.each { |pl| self.introduce pl }
     end
 
-    def cast cls, args = {}, &block
-      ent = super
-      ent.playbooks.push plot.playbook unless ent.playbooks.include?(plot.playbook)
-      ent
-    end
-
-    def exeunt player
-      player_conclude_procs.each { |block| block.call player }
-      player.playbooks.delete playbook
-      player.cue (@next_cue || default_scene)
-      players.delete player
+    def ready
+      super
+      conclude if concluding?
     end
 
     def conclude
-      @concluded = true
-      # Players needed to exit first in case any player_conclude procs need to
-      # interact with the subplot's entities.
-      players.each { |p| exeunt p }
-      # @todo I'm not sure why rejecting nils is necessary here. It's only an
-      #   issue in Opal.
-      entities.reject(&:nil?).each { |e| destroy e }
-      # plot.static.remove(scene_classes + entities)
+      rulebook.run_conclude_blocks
+      players.each do |plyr|
+        rulebook.run_player_conclude_blocks plyr
+        uncast plyr
+      end
+      entities.each { |ent| destroy ent }
     end
 
-    def concluded?
-      @concluded
-    end
-
-    def ready
-      # @todo We might not want to conclude subplots without players. There
-      #   might be cases where a subplot gets created with the intention of
-      #   introducing players in a later turn.
-      conclude if players.empty?
-      return if concluded?
-      playbook.freeze
-      call_ready
-      call_player_ready
+    # Make an entity that persists in the subplot's parent plot.
+    #
+    # @see Plot#make
+    #
+    def persist klass, **args
+      plot.make klass, *args
     end
 
-    def update
-      call_player_update
-      call_update
+    # Start a new subplot based on the provided class.
+    #
+    # @note A subplot's host is always the base plot, regardless of whether
+    #   it was branched from another subplot.
+    #
+    # @param subplot_class [Class<Gamefic::Subplot>] The Subplot class
+    # @param introduce [Gamefic::Actor, Array<Gamefic::Actor>, nil] Players to introduce
+    # @param config [Hash] Subplot configuration
+    # @return [Gamefic::Subplot]
+    def branch subplot_class = Gamefic::Subplot, introduce: [], **config
+      plot.branch subplot_class, introduce: introduce, **config
     end
 
     # Subclasses can override this method to handle additional configuration
     # options.
     #
-    def configure **more
+    def configure; end
+
+    def inspect
+      "#<#{self.class}>"
+    end
+
+    def hydrate
+      @rulebook = Rulebook.new(self)
+      @rulebook.script
+      @rulebook.freeze
     end
   end
 end

data/lib/gamefic/syntax/template.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Gamefic
+  class Syntax
+    # Template data for syntaxes.
+    #
+    class Template
+      PARAM_REGEXP = /^:[a-z0-9_]+$/i.freeze
+
+      # @return [String]
+      attr_reader :text
+
+      # @return [Array<String>]
+      attr_reader :params
+
+      def initialize text
+        @text = text.normalize
+        @params = @text.keywords.select { |word| word.start_with?(':') }
+      end
+
+      def keywords
+        text.keywords
+      end
+
+      def to_s
+        text
+      end
+
+      def regexp
+        @regexp ||= Regexp.new("^#{make_tokens.join(' ')}$", Regexp::IGNORECASE)
+      end
+
+      def verb
+        @verb ||= Syntax.literal_or_nil(keywords.first)
+      end
+
+      def compare other
+        if keywords.length == other.keywords.length
+          other.verb <=> verb
+        else
+          other.keywords.length <=> keywords.length
+        end
+      end
+
+      # @param tmpl_or_str [Template, String]
+      # @return [Template]
+      def self.to_template tmpl_or_str
+        return tmpl_or_str if tmpl_or_str.is_a?(Template)
+
+        Template.new(tmpl_or_str)
+      end
+
+      private
+
+      # @return [Array<String>]
+      def make_tokens
+        keywords.map.with_index do |word, idx|
+          next word unless word.match?(PARAM_REGEXP)
+
+          next nil if idx.positive? && keywords[idx - 1].match?(PARAM_REGEXP)
+
+          '([\w\W\s\S]*?)'
+        end.compact
+      end
+    end
+  end
+end