gamefic 2.3.0 → 3.0.0

data/lib/gamefic/describable.rb

@@ -1,19 +1,20 @@
+# frozen_string_literal: true
+
 module Gamefic
-  # Add a variety of text properties for naming, describing, and referencing
+  # A variety of text properties for naming, describing, and referencing
   # objects.
+  #
   module Describable
-    include Keywords
-
-    # Get the name of the object.
-    # The name is usually presented without articles (e.g., "object" instead
-    # of "an object" or "the object" unless the article is part of a proper
+    # The object's name.
+    # Names are usually presented without articles (e.g., "object" instead
+    # of "an object" or "the object") unless the article is part of a proper
     # name (e.g., "The Ohio State University").
     #
     # @return [String]
     attr_reader :name
 
-    # Alternate words that can be used to describe the object. Synonyms are
-    # used in conjunction with the object's name when generating keywords.
+    # Alternate words that can reference the object. Synonyms are used in
+    # conjunction with the object's name when scanning tokens.
     #
     # @return [String]
     attr_reader :synonyms
@@ -21,62 +22,42 @@ module Gamefic
     # The object's indefinite article (usually "a" or "an").
     #
     # @return [String]
-    attr_reader :indefinite_article
+    attr_accessor :indefinite_article
 
     # The object's definite article (usually "the").
     #
     # @return [String]
-    attr_reader :definite_article
+    attr_writer :definite_article
 
-    # Get a set of keywords associated with the object.
-    # Keywords are typically the words in the object's name plus its synonyms.
-    #
-    # @return [Array<String>]
     def keywords
-      @keywords ||= "#{definite_article} #{indefinite_article} #{name} #{synonyms}".downcase.split(Keywords::SPLIT_REGEXP).uniq
+      "#{name} #{synonyms}".keywords
     end
 
-    # Get the name of the object with an indefinite article.
+    # The name of the object with an indefinite article.
     # Note: proper-named objects never append an article, though an article
     # may be included in its proper name.
     #
     # @return [String]
     def indefinitely
-      ((proper_named? or indefinite_article == '') ? '' : "#{indefinite_article} ") + name.to_s
+      (proper_named? || indefinite_article == '' ? '' : "#{indefinite_article} ") + name.to_s
     end
 
-    # Get the name of the object with a definite article.
+    # The name of the object with a definite article.
     # Note: proper-named objects never append an article, though an article
     # may be included in its proper name.
     #
     # @return [String]
     def definitely
-      ((proper_named? or definite_article == '') ? '' : "#{definite_article} ") + name.to_s
+      (proper_named? || definite_article == '' ? '' : "#{definite_article} ") + name.to_s
     end
 
-    # Get the definite article for this object (usually "the").
+    # Tefinite article for this object (usually "the").
     #
     # @return [String]
     def definite_article
       @definite_article || "the"
     end
 
-    # Set the definite article.
-    #
-    # @param [String] article
-    def definite_article= article
-      @keywords = nil
-      @definite_article = article
-    end
-
-    # Set the indefinite article.
-    #
-    # @param [String] article
-    def indefinite_article= article
-      @keywords = nil
-      @indefinite_article = article
-    end
-
     # Is the object proper-named?
     # Proper-named objects typically do not add articles to their names when
     # referenced #definitely or #indefinitely, e.g., "Jane Doe" instead of
@@ -84,18 +65,16 @@ module Gamefic
     #
     # @return [Boolean]
     def proper_named?
-      (@proper_named == true)
+      @proper_named == true
     end
 
     # Set whether the object has a proper name.
     #
     # @param bool [Boolean]
     def proper_named=(bool)
-      if bool == true
-        if @definite_article != nil
-          @name = "#{@definite_article} #{@name}"
-          @definite_article = nil
-        end
+      if bool && @definite_article
+        @name = "#{@definite_article} #{@name}".strip
+        @definite_article = nil
       end
       @proper_named = bool
     end
@@ -106,27 +85,26 @@ module Gamefic
     #
     # @param value [String]
     def name=(value)
-      @keywords = nil
-      words = value.split_words
-      if ['a','an'].include?(words[0].downcase)
+      words = value.split
+      if %w[a an].include?(words[0].downcase)
         @indefinite_article = words[0].downcase
         @definite_article = 'the'
-        value = value[words[0].length+1..-1].strip
+        value = value[words[0].length + 1..].strip
       else
         if words[0].downcase == 'the'
           if proper_named?
             @definite_article = nil
           else
             @definite_article = 'the'
-            value = value[4..-1].strip
+            value = value[4..].strip
           end
         end
         # Try to guess the indefinite article
-        if ['a','e','i','o','u'].include?(value[0,1].downcase)
-          @indefinite_article = 'an'
-        else
-          @indefinite_article = 'a'
-        end
+        @indefinite_article = if %w[a e i o u].include?(value[0, 1].downcase)
+                                'an'
+                              else
+                                'a'
+                              end
       end
       @name = value
     end
@@ -134,30 +112,26 @@ module Gamefic
     # Does the object have a description?
     #
     # @return [Boolean]
-    def has_description?
-      (@description.to_s != '')
+    def description?
+      @description.to_s != ''
     end
+    alias has_description? description?
 
     # Get the object's description.
     #
     # @return [String]
     def description
-      @description || (Describable.default_description % { :name => self.definitely, :Name => self.definitely.capitalize_first })
+      @description || format(Describable.default_description, name: definitely, Name: definitely.capitalize_first)
     end
 
     # Set the object's description.
     #
     # @param text [String]
     def description=(text)
-      if text != (Describable.default_description % { :name => self.definitely, :Name => self.definitely.capitalize_first })
-        @description = text
-      else
-        @description = nil
-      end
+      @description = (text if text != (format(Describable.default_description, name: definitely, Name: definitely.capitalize_first)))
     end
 
     def synonyms= text
-      @keywords = nil
       @synonyms = text
     end
 
@@ -175,12 +149,12 @@ module Gamefic
     #
     # @return [String]
     def self.default_description
-      @default_description || "There's nothing special about %{name}."
+      @default_description || "There's nothing special about %<name>s."
     end
 
-    # Get a String representation of the object. By default, this is the
-    # object's name with an indefinite article, e.g., "a person" or "a red
-    # dog."
+    # Get a String representation of the object. By default, this is either
+    # the object's name with an indefinite article, e.g., "a person" or "a red
+    # dog"; or its proper name, e.g., "Mr. Smith".
     #
     # @return [String]
     def to_s

data/lib/gamefic/dispatcher.rb

@@ -1,45 +1,63 @@
+# frozen_string_literal: true
+
 module Gamefic
   # The action selector for character commands.
   #
   class Dispatcher
     # @param actor [Actor]
     # @param commands [Array<Command>]
-    # @param actions [Array<Action>]
-    def initialize actor, commands = [], actions = []
+    # @param responses [Array<Response>]
+    def initialize actor, commands = [], responses = []
       @actor = actor
       @commands = commands
-      @actions = actions
-      @started = false
+      @responses = responses
+      @executed = false
     end
 
-    def merge dispatcher
-      commands.concat dispatcher.commands
-      actions.concat dispatcher.actions
+    # Run the dispatcher.
+    #
+    def execute
+      return if @executed
+
+      action = proceed
+      return unless action
+
+      @executed = action.arguments
+      run_before_action_hooks action
+      return if action.cancelled?
+
+      action.execute
+      run_after_action_hooks action
     end
 
-    def next
-      instance = nil
-      while instance.nil? && !@actions.empty?
-        action = actions.shift
+    # Get the next executable action.
+    #
+    # @return [Action, nil]
+    def proceed
+      while (response = responses.shift)
         commands.each do |cmd|
-          instance = action.attempt(actor, cmd, !@started)
-          if instance
-            @started = true
-            break
-          end
+          action = response.attempt(actor, cmd)
+          next unless action && arguments_match?(action.arguments)
+
+          return action
         end
       end
-      instance
+      nil # Without this, return value in Opal is undefined
     end
 
     # @param actor [Active]
-    # @param command [String]
+    # @param input [String]
     # @return [Dispatcher]
-    def self.dispatch actor, command
-      group = actor.playbooks.reverse.map { |p| p.dispatch(actor, command) }
-      dispatcher = Dispatcher.new(actor)
-      group.each { |d| dispatcher.merge d }
-      dispatcher
+    def self.dispatch actor, input
+      commands = Syntax.tokenize(input, actor.epic.rulebooks.flat_map(&:syntaxes))
+      verbs = commands.map(&:verb).uniq
+      responses = actor.epic
+                       .rulebooks
+                       .to_a
+                       .reverse
+                       .flat_map { |pb| pb.responses_for(*verbs) }
+                       .reject(&:hidden?)
+      new(actor, commands, responses)
     end
 
     # @param actor [Active]
@@ -47,10 +65,13 @@ module Gamefic
     # @param params [Array<Object>]
     # @return [Dispatcher]
     def self.dispatch_from_params actor, verb, params
-      group = actor.playbooks.reverse.map { |p| p.dispatch_from_params(actor, verb, params) }
-      dispatcher = Dispatcher.new(actor)
-      group.each { |d| dispatcher.merge d }
-      dispatcher
+      command = Command.new(verb, params)
+      responses = actor.epic
+                       .rulebooks
+                       .to_a
+                       .reverse
+                       .flat_map { |pb| pb.responses_for(verb) }
+      new(actor, [command], responses)
     end
 
     protected
@@ -61,7 +82,24 @@ module Gamefic
     # @return [Array<Command>]
     attr_reader :commands
 
-    # @return [Array<Action>]
-    attr_reader :actions
+    # @return [Array<Response>]
+    attr_reader :responses
+
+    private
+
+    # After the first action gets selected, subsequent actions need to use the
+    # same arguments.
+    #
+    def arguments_match? arguments
+      !@executed || arguments == @executed
+    end
+
+    def run_before_action_hooks action
+      actor.epic.rulebooks.flat_map { |rlbk| rlbk.run_before_actions action }
+    end
+
+    def run_after_action_hooks action
+      actor.epic.rulebooks.flat_map { |rlbk| rlbk.run_after_actions action }
+    end
   end
 end

data/lib/gamefic/entity.rb

@@ -1,26 +1,35 @@
-require "gamefic/node"
-require "gamefic/describable"
-require 'gamefic/messaging'
+# frozen_string_literal: true
 
 module Gamefic
-  # A physical object that can exist in a plot. Most objects with which
-  # players interact are entities. Player characters themselves typically
-  # derive from entities, e.g., the Gamefic::Actor class.
+  # Entities are the people, places, and things that exist in a Gamefic
+  # narrative. Authors are encouraged to define Entity subclasses to create
+  # entity types that have additional features or need special handling in
+  # actions.
   #
-  class Entity < Element
+  class Entity
+    include Describable
     include Node
-    include Messaging
+    # include Messaging
 
-    # Set the Entity's parent.
-    #
-    # @param node [Gamefic::Entity, nil] The new parent.
-    def parent=(node)
-      if node && node.is_a?(Entity) == false
-        raise ArgumentError, "Entity's parent must be an Entity"
+    def initialize **args
+      klass = self.class
+      defaults = {}
+      while klass <= Entity
+        defaults = klass.default_attributes.merge(defaults)
+        klass = klass.superclass
       end
-      super
+      defaults.merge(args).each_pair { |k, v| send "#{k}=", v }
+
+      yield(self) if block_given?
+
+      post_initialize
     end
 
+    # This method can be overridden for additional processing after the entity
+    # has been created.
+    #
+    def post_initialize; end
+
     # A freeform property dictionary.
     # Authors can use the session hash to assign custom properties to the
     # entity. It can also be referenced directly using [] without the method
@@ -31,20 +40,36 @@ module Gamefic
       @session ||= {}
     end
 
-    # Get a custom property.
-    #
     # @param key [Symbol] The property's name
     # @return The value of the property
     def [](key)
       session[key]
     end
 
-    # Set a custom property.
-    #
     # @param key [Symbol] The property's name
     # @param value The value to set
     def []=(key, value)
       session[key] = value
     end
+
+    def inspect
+      "#<#{self.class} #{name}>"
+    end
+
+    class << self
+      # Set or update the default values for new instances.
+      #
+      # @param attrs [Hash] The attributes to be merged into the defaults.
+      def set_default attrs = {}
+        default_attributes.merge! attrs
+      end
+
+      # A hash of default values for attributes when creating an instance.
+      #
+      # @return [Hash]
+      def default_attributes
+        @default_attributes ||= {}
+      end
+    end
   end
 end

data/lib/gamefic/logging.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Gamefic
+  # A simple logger.
+  #
+  module Logging
+    module_function
+
+    # @return [Logger]
+    def logger
+      Gamefic.logger
+    end
+  end
+
+  class << self
+    def logger
+      @logger ||= select_logger.tap do |l|
+        l.formatter = proc { |sev, _dt, _prog, msg| "[#{sev}] #{msg}\n" }
+      end
+    end
+
+    private
+
+    def select_logger
+      # We use #tap here because `Logger.new(STDERR, level: Logger::WARN)`
+      # fails in Opal
+      Logger.new($stderr).tap { |log| log.level = Logger::WARN }
+    end
+  end
+end

data/lib/gamefic/messenger.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Gamefic
+  # Message formatting and buffering.
+  #
+  class Messenger
+    def initialize
+      @buffers = ['']
+    end
+
+    # Create a temporary buffer while yielding the given block and return the
+    # buffered text.
+    #
+    # @return [String]
+    def buffer
+      @buffers.push('')
+      yield if block_given?
+      @buffers.pop
+    end
+
+    # Add a formatted message to the current buffer.
+    #
+    # This method will automatically wrap the message in HTML paragraphs.
+    # To send a message without formatting, use #stream instead.
+    #
+    # @param message [String, #to_s]
+    # @return [String] The messages in the current buffer
+    def tell(message)
+      @buffers.push(@buffers.pop + format(message.to_s))
+              .last
+    end
+
+    # Add a raw text message to the current buffer.
+    #
+    # Unlike #tell, this method will not wrap the message in HTML paragraphs.
+    #
+    # @param message [String, #to_s]
+    # @return [String] The messages in the current buffer
+    def stream(message)
+      @buffers.push(@buffers.pop + message.to_s)
+              .last
+    end
+
+    # Get the currently buffered messages.
+    #
+    # @return [String]
+    def messages
+      @buffers.last
+    end
+
+    # Clear the buffered messages.
+    #
+    # @return [String] The flushed message
+    def flush
+      @buffers.pop.tap { @buffers.push '' }
+    end
+
+    def format(message)
+      "<p>#{message.strip}</p>"
+        .gsub(/[ \t\r]*\n[ \t\r]*\n[ \t\r]*/, "</p><p>")
+        .gsub(/[ \t]*\n[ \t]*/, ' ')
+        .gsub(/<p>\s*<p>/, '<p>')
+        .gsub(%r{</p>\s*</p>}, '</p>')
+    end
+  end
+end

data/lib/gamefic/narrative.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+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
+  # functionality.
+  #
+  class Narrative
+    extend Scriptable
+
+    include Logging
+    include Scriptable::Actions
+    include Scriptable::Entities
+    include Scriptable::Events
+    include Scriptable::Proxy
+    include Scriptable::Queries
+    include Scriptable::Scenes
+
+    attr_reader :rulebook
+
+    def initialize
+      self.class.included_blocks.select(&:seed?).each { |blk| Stage.run self, &blk.code }
+      entity_vault.lock
+      @rulebook = nil
+      hydrate
+    end
+
+    def scenes
+      rulebook.scenes.names
+    end
+
+    # Introduce an actor to the story.
+    #
+    # @param player [Gamefic::Actor]
+    # @return [Gamefic::Actor]
+    def introduce(player = Gamefic::Actor.new)
+      cast player
+      rulebook.scenes.introductions.each do |scene|
+        scene.run_start_blocks player, nil
+      end
+      player
+    end
+
+    # A narrative is considered to be concluding when all of its players are in
+    # a conclusion scene. Engines can use this method to determine whether the
+    # game is ready to end.
+    #
+    def concluding?
+      players.empty? || players.all?(&:concluding?)
+    end
+
+    # Add an active entity to the narrative.
+    #
+    # @param [Gamefic::Active]
+    # @return [Gamefic::Active]
+    def cast active
+      active.epic.add self
+      player_vault.add active
+      entity_vault.add active
+      active
+    end
+
+    # Remove an active entity from the narrative.
+    #
+    # @param [Gamefic::Active]
+    # @return [Gamefic::Active]
+    def uncast active
+      active.epic.delete self
+      player_vault.delete active
+      entity_vault.delete active
+      active
+    end
+
+    def ready
+      rulebook.run_ready_blocks
+    end
+
+    def update
+      rulebook.run_update_blocks
+    end
+
+    # @return [Object]
+    def detach
+      cache = @rulebook
+      @rulebook = nil
+      cache
+    end
+
+    def attach cache
+      @rulebook = cache
+    end
+
+    def hydrate
+      @rulebook = Rulebook.new(self)
+      @rulebook.script_with_defaults
+      @rulebook.freeze
+    end
+
+    def self.inherited klass
+      super
+      klass.blocks.concat blocks
+    end
+  end
+end