demiurge 0.2.0

data/lib/demiurge/exception.rb

@@ -0,0 +1,170 @@
+module Demiurge;end
+
+# The Errors module exists to scope errors out of the top-level namespace.
+module Demiurge::Errors
+  # Demiurge::Errors::Exception is the parent class of all Demiurge-specific
+  # Exceptions.
+  #
+  # @since 0.0.1
+  class Exception < ::RuntimeError
+    # @return [Hash] Additional specific data about this exception.
+    # @since 0.0.1
+    attr_reader :info
+
+    # @return [Hash{String=>String}] Context about where and how the error occurred
+    # @since 0.2.0
+    attr_reader :execution_context
+
+    # Optionally add a hash of extra data, called info, to this
+    # exception. You can also add the engine's execution context, if
+    # available.
+    #
+    # @param msg [String] The message for this Exception
+    # @since 0.0.1
+    def initialize(msg, info = {}, execution_context: nil)
+      super(msg)
+      @info = info
+      @execution_context = execution_context ? execution_context.dup : nil
+    end
+
+    def backtrace_chain
+      bt_chain = []
+      cur_cause = self.cause
+      while cur_cause
+        bt_chain.push(self.backtrace)
+        cur_cause = cur_cause.cause
+      end
+      bt_chain
+    end
+
+    # Serialize this exception to a JSON-serializable PORO.
+    #
+    # @return [Hash] The serialized {Demiurge::Errors::Exception} data
+    # @since 0.0.1
+    def jsonable()
+      bt = backtrace_chain.inject { |a, b| a + [ "... Caused by ..." ] + b }
+      {
+        "message" => self.message,
+        "info" => self.info,
+        "execution_context" => self.execution_context,
+        "backtrace" => bt
+      }
+    end
+
+    def formatted
+      bt = backtrace_chain.map { |t| t.join("\n") }.join("\n... Caused by ...\n")
+      <<FORMATTED_BLOCK
+#{self.message}
+Error info: #{info.inspect}
+Context: #{execution_context.inspect}
+#{bt}
+FORMATTED_BLOCK
+    end
+  end
+
+  # A RetryableError or its subclasses normally indicate an error that
+  # is likely to be transient, and where retrying the tick is a
+  # reasonable attempt at a solution.
+  #
+  # @since 0.0.1
+  class RetryableError < ::Demiurge::Errors::Exception; end
+
+  # A BadScriptError will normally not benefit from retrying. Instead,
+  # one or more scripts associated with this error is presumed to be
+  # bad or outdated. The primary thing to do with BadScriptErrors is
+  # to accumulate and count them and possibly to deactivate one or
+  # more bad scripts. Error counting can allow an administrator to
+  # locate (or guess) the bad script in question and disable one or
+  # more scripts to remove the problem. While it's technically
+  # possible to disable bad scripts automatically, that may sometimes
+  # have distressing side effects when a script was intended to run
+  # and didn't. It may also have false positives where a misbehaving
+  # script "frames" a correct script by causing errors downstream.
+  #
+  # @since 0.0.1
+  class BadScriptError < ::Demiurge::Errors::Exception; end
+
+  # An AssetError means that there's a problem in the format of a TMX
+  # file, image, JSON file or other game asset. It is unlikely to be
+  # retryable, but it isn't normally the result of bad admin-written
+  # code.
+  #
+  # @since 0.0.1
+  class AssetError < ::Demiurge::Errors::Exception; end
+
+  # A ReloadError is a result of state that doesn't match perfectly on
+  # reload.  Deleting non-transient objects, renaming objects, giving
+  # objects a new type and changing an object's state format can all
+  # give a ReloadError in certain circumstances.
+  #
+  # @since 0.0.1
+  class ReloadError < ::Demiurge::Errors::Exception; end
+
+
+
+  # This exception occurs when trying to use an action that doesn't
+  # exist, such as from {Demiurge::ActionItem#run_action} or
+  # {Demiurge::Agent#queue_action}.
+  #
+  # @since 0.0.1
+  class NoSuchActionError < BadScriptError; end
+
+  # This exception occurs when trying to use an agent name that
+  # doesn't belong to any registered agent.
+  #
+  # @since 0.0.1
+  class NoSuchAgentError < BadScriptError; end
+
+  # This occurs when trying to use a nonexistent state key in a way
+  # that isn't allowed.  This exception normally refers to object
+  # state, when accessed from a script.
+  #
+  # @since 0.0.1
+  class NoSuchStateKeyError < BadScriptError; end
+
+  # This occurs when trying to modify or cancel an intention when
+  # there isn't one.
+  #
+  # @since 0.0.1
+  class NoCurrentIntentionError < BadScriptError; end
+
+  # This occurs if intentions queue other, new intentions too many
+  # times in the same tick. The exception exists to prevent infinite
+  # loops of queued intentions. If your script wants to queue lots of
+  # intentions, consider queueing them during *later* ticks instead of
+  # immediately.
+  #
+  # @since 0.0.1
+  class TooManyIntentionLoopsError < BadScriptError; end
+
+  # This occurs if notifications queue other, new notifications too
+  # many times in the same tick. The exception exists to prevent
+  # infinite loops of queued notifications. If your script wants to
+  # queue lots of notifications, consider queueing them after the tick
+  # has finished, perhaps on a later tick.
+  #
+  # @since 0.0.1
+  class TooManyNotificationLoopsError < BadScriptError; end
+
+  # This occurs if there's a problem in the TMX file or in some kind
+  # of file convention (such as using "Fringe" for a hardcoded layer)
+  # in a specific subformat like ManaSource.
+  #
+  # @since 0.0.1
+  class TmxFormatError < AssetError; end
+
+  # When loading or reloading, we got an exception when parsing
+  # WorldFile code.
+  #
+  # @since 0.0.1
+  class CannotLoadWorldFiles < ReloadError; end
+
+  # When reloading, this error or a subclass can be raised if the new
+  # state structure or StateItems don't seem to match the old one in
+  # illegal ways.  "Illegal" can vary, depending how conservative the
+  # reloading options are set.
+  #
+  # @since 0.0.1
+  class NonMatchingStateError < ReloadError; end
+
+end

data/lib/demiurge/inert_state_item.rb

@@ -0,0 +1,21 @@
+module Demiurge
+
+  # Sometimes you just want state that sits and does nothing unless
+  # you mess with it. Player password hashes? Top-level game settings?
+  # Heck, even something sort-of-active like bank inventory can make
+  # sense to model this way since it will never do anything on its
+  # own. This is especially good for things that will never interact
+  # with the engine cycle - something that ignores ticks, intentions,
+  # notifications, etc.
+  #
+  # @since 0.0.1
+  class InertStateItem < StateItem
+    # An InertStateItem doesn't intend anything, ever.
+    #
+    # @return [Array<Intention>] This array will always be empty for an InertStateItem
+    # @since 0.0.1
+    def intentions_for_next_step(*args)
+      []
+    end
+  end
+end

data/lib/demiurge/intention.rb

@@ -0,0 +1,164 @@
+module Demiurge
+
+  # An Intention is an unresolved event. Some part of the simulated
+  # world "wishes" to take an action. This need not be a sentient
+  # being - any change to the world should occur with an Intention
+  # then being resolved into changes in state and events -- or
+  # not. It's also possible for an intention to resolve to nothing at
+  # all. For instance, an intention to move in an impossible direction
+  # could simply resolve with no movement, no state change and no event.
+  #
+  # Intentions go through verification, resolution and eventually
+  # notification.
+  #
+  # Intentions are not, in general, serializable. They normally
+  # persist for only a single tick. To persist an intention for most StateItems,
+  # consider persisting action names instead.
+  #
+  # For more details about Intention, see {file:CONCEPTS.md}.
+  #
+  # @since 0.0.1
+
+  class Intention
+    # Subclasses of intention can require all sorts of constructor arguments to
+    # specify what the intention is. But the engine should always be supplied.
+    #
+    # @param engine [Demiurge::Engine] The engine this Intention is part of.
+    # @since 0.0.1
+    def initialize(engine)
+      @cancelled = false
+      @engine = engine
+      @intention_id = engine.get_intention_id
+    end
+
+    # This cancels the intention, and gives the reason for the
+    # cancellation.
+    #
+    # @param reason [String] A human-readable reason this action was cancelled
+    # @param info [Hash] A String-keyed Hash of additional information about the cancellation
+    # @return [void]
+    # @since 0.0.1
+    def cancel(reason, info = {})
+      @cancelled = true
+      @cancelled_by = caller(1, 1)
+      @cancelled_reason = reason
+      @cancelled_info = info
+      cancel_notification
+      nil
+    end
+
+    # Most intentions will send a cancellation notice when they are
+    # cancelled. By default, this will include who cancelled the
+    # intention and why.
+    #
+    # If the cancellation info Hash includes "silent" with a true
+    # value, by default no notification will be sent out. This is to
+    # avoid an avalache of notifications for common cancelled
+    # intentions that happen nearly every tick. Examples include an
+    # agent's action queue being empty so it cancels its intention.
+    # These are normal operation and nobody is likely to need
+    # notification every tick that they didn't ask to do anything so
+    # they didn't.
+    #
+    # {#cancel_notification} can be overridden by child classes
+    # for more specific cancel notifications.
+    #
+    # @return [void]
+    # @since 0.0.1
+    def cancel_notification
+      return if @cancelled_info && @cancelled_info["silent"]
+      @engine.send_notification({
+                                  :reason => @cancelled_reason,
+                                  :by => @cancelled_by,
+                                  :id => @intention_id,
+                                  :intention_type => self.class.to_s,
+                                  :info => @cancelled_info
+                                },
+                                type: Demiurge::Notifications::IntentionCancelled, zone: "admin", location: nil, actor: nil,
+                                include_context: true)
+      nil
+    end
+
+    # Intentions should send an apply notice when they are
+    # successfully applied. {#apply_notification} can be overridden by
+    # child classes to send more specific information.
+    #
+    # @return [void]
+    # @since 0.2.0
+    def apply_notification
+      @engine.send_notification({
+                                  :id => @intention_id,
+                                  :intention_type => self.class.to_s,
+                                  :info => @cancelled_info
+                                },
+                                type: Demiurge::Notifications::IntentionApplied, zone: "admin", location: nil, actor: nil,
+                                include_context: true)
+      nil
+    end
+
+    # This returns whether this intention has been cancelled.
+    #
+    # @return [Boolean] Whether the notification is cancelled.
+    def cancelled?
+      @cancelled
+    end
+
+    # This method allows child classes of Intention to check whether
+    # they should happen at all. If this method returns false, the
+    # intention will self-cancel without sending a notification and
+    # quietly not occur. The method exists primarily to allow
+    # "illegal" intentions like walking through a wall or drinking
+    # nonexistent water to quietly not happen without the rest of the
+    # simulation responding to them in any way.
+    #
+    # @return [Boolean] If this method returns false, the Intention will quietly self-cancel before the offer phase.
+    # @since 0.0.1
+    def allowed?
+      raise "Unimplemented 'allowed?' for intention: #{self.inspect}!"
+    end
+
+    # This method tells the Intention that it has successfully
+    # occurred and it should modify StateItems accordingly. Normally
+    # this will only be called after {#allowed?} and {#offer} have
+    # completed, and other items have had a chance to modify or cancel
+    # this Intention.
+    #
+    # @return [void]
+    # @since 0.0.1
+    def apply
+      raise "Unimplemented 'apply' for intention: #{self.inspect}!"
+    end
+
+    # When an Intention is "offered", that means appropriate other
+    # entities have a chance to modify or cancel the intention. For
+    # instance, a movement action in a room should be offered to that
+    # room, which may trigger a special action (e.g. trap) or change
+    # the destination of the action (e.g. exits, slippery ice,
+    # spinning spaces.)
+    #
+    # @see file:CONCEPTS.md
+    # @return [void]
+    # @since 0.0.1
+    # @note This method changed signature in 0.2.0 to stop taking an intention ID.
+    def offer
+      raise "Unimplemented 'offer' for intention: #{self.inspect}!"
+    end
+
+    # This is a normally-private part of the Tick cycle. It checks the
+    # {#allowed?} and {#offer} phases for this one specific Intention.
+    #
+    # @return [void]
+    # @since 0.0.1
+    # @api private
+    # @note This method changed signature in 0.2.0 to stop taking an intention ID.
+    def try_apply
+      return unless allowed?
+      offer
+      return if cancelled? # Notification should already have been sent out
+      apply
+      return if cancelled? # Notification should already have been sent out
+      apply_notification
+      nil
+    end
+  end
+end

data/lib/demiurge/location.rb

@@ -0,0 +1,85 @@
+module Demiurge
+  # A Location is generally found inside a Zone.  It may contain items
+  # and agents.
+  class Location < Container
+    # Constructor - set up exits
+    #
+    # @param name [String] The Engine-unique item name
+    # @param engine [Demiurge::Engine] The Engine this item is part of
+    # @param state [Hash] State data to initialize from
+    # @return [void]
+    # @since 0.0.1
+    def initialize(name, engine, state)
+      super
+      state["exits"] ||= []
+    end
+
+    def finished_init
+      super
+      # Make sure we're in our zone.
+      zone.ensure_contains(@name)
+    end
+
+    # A Location isn't located "inside" somewhere else. It is located in/at itself.
+    def location_name
+      @name
+    end
+
+    # A Location isn't located "inside" somewhere else. It is located in/at itself.
+    def location
+      self
+    end
+
+    def zone_name
+      @state["zone"]
+    end
+
+    def zone
+      @engine.item_by_name(@state["zone"])
+    end
+
+    # By default, the location can accomodate any agent number, size
+    # or shape, as long as it's in this location itself.  Subclasses
+    # of location may have different abilities to accomodate different
+    # sizes or shapes of agent, and at different positions.
+    def can_accomodate_agent?(agent, position)
+      position == @name
+    end
+
+    # Return a legal position of some kind within this Location.  By
+    # default there is only one position, which is just the Location's
+    # name. More complicated locations (e.g. tilemaps or procedural
+    # areas) may have more interesting positions inside them.
+    def any_legal_position
+      @name
+    end
+
+    # Is this position valid in this location?
+    def valid_position?(pos)
+      pos == @name
+    end
+
+    def add_exit(from:any_legal_position, to:, to_location: nil, properties:{})
+      to_loc, to_coords = to.split("#",2)
+      if to_location == nil
+        to_location = @engine.item_by_name(to_loc)
+      end
+      raise("'From' position #{from.inspect} is invalid when adding exit to #{@name.inspect}!") unless valid_position?(from)
+      raise("'To' position #{to.inspect} is invalid when adding exit to #{@name.inspect}!") unless to_location.valid_position?(to)
+      exit_obj = { "from" => from, "to" => to, "properties" => properties }
+      @state["exits"] ||= []
+      @state["exits"].push(exit_obj)
+      exit_obj
+    end
+
+    # This isn't guaranteed to be in a particular format for all
+    # Locations everywhere. Sometimes exits in this form don't even
+    # make sense. So: this is best-effort when queried from a random
+    # Location, and a known format only if you know the specific
+    # subclass of Location you're dealing with.
+    def exits
+      @state["exits"]
+    end
+
+  end
+end

data/lib/demiurge/notification_names.rb

@@ -0,0 +1,93 @@
+module Demiurge
+  # Notifications use string identifiers as names. It's legal to use
+  # strings directly, but then typos can go undetected.  This also
+  # serves as a list of what notifications are normally
+  # available. Application-specific notifications should define their
+  # own notification constants, either in this module or another one.
+  #
+  # @since 0.2.0
+  module Notifications
+
+    # This notification is sent when something is misconfigured, but
+    # not in a continuity-threatening way.
+    #
+    # @since 0.2.0
+    AdminWarning = "admin_warning"
+
+    # This notification indicates that a tick has completed.
+    #
+    # @since 0.2.0
+    TickFinished = "tick_finished"
+
+    # This notification indicates that a new item has been registered
+    # by the engine.
+    #
+    # @since 0.2.0
+    NewItem = "new_item"
+
+    # This notification means that state loading has begun into an
+    # initialized engine.
+    #
+    # @since 0.2.0
+    LoadStateStart = "load_state_start"
+
+    # This notification means that state loading has finished in an
+    # initialized engine.
+    #
+    # @since 0.2.0
+    LoadStateEnd = "load_state_end"
+
+    # This notification is sent when a World File reload is preparing
+    # to start.  This will be sent on verify-only reloads as well as
+    # normal reloads.
+    #
+    # @since 0.2.0
+    LoadWorldVerify = "load_world_verify"
+
+    # This notification is sent when a World File reload has
+    # successfully verified and has begun loading. Verify-only reloads
+    # do not send this signal.
+    #
+    # @since 0.2.0
+    LoadWorldStart = "load_world_start"
+
+    # This notification is sent when a World File reload has
+    # successfully completed. Verify-only reloads do not send this
+    # signal.
+    #
+    # @since 0.2.0
+    LoadWorldEnd = "load_world_end"
+
+    # This notification is sent when an agent moves between positions,
+    # locations and/or zones. This notification goes out at the old
+    # location and zone, which may be the same as the new.
+    #
+    # Fields: new_position (String), old_position (String), new_location (String), old_location (String), zone (String)
+    #
+    # @since 0.2.0
+    MoveFrom = "move_from"
+
+    # This notification is sent when an agent moves between positions,
+    # locations and/or zones. This notification goes out at the new
+    # location and zone, which may be the same as the old.
+    #
+    # Fields: new_position (String), old_position (String), new_location (String), old_location (String), zone (String)
+    #
+    # @since 0.2.0
+    MoveTo = "move_to"
+
+    # This notification is sent when an intention has been cancelled.
+    #
+    # Fields: reason (String), by (Array<String>), id (Integer), intention_type (String), info (Hash)
+    #
+    # @since 0.2.0
+    IntentionCancelled = "intention_cancelled"
+
+    # This notification is sent when an intention is successfully applied.
+    #
+    # Fields: id (Integer), intention_type (String), info (Hash)
+    #
+    # @since 0.2.0
+    IntentionApplied = "intention_applied"
+  end
+end