class Demiurge::Engine

The Engine class encapsulates one “world” of simulation. This includes state and code for all items, subscriptions to various events and the ability to reload state or code at a later point. It is entirely possible to have multiple Engine objects containing different objects and subscriptions which are unrelated to each other. If Engines share references in common, that sharing is ordinarily a bug. Currently only registered {Demiurge::DSL} Object Types should be shared.

@since 0.0.1

Attributes

execution_context[R]

@return [Hash{String=>String}] The current execution context for notifications and logging. @since 0.3.0

ticks[R]

@return [Integer] The number of ticks that have occurred since the beginning of this Engine's history.

Public Class Methods

new(types: {}, state: []) click to toggle source

This is the constructor for a new Engine object. Most frequently this will be called by {Demiurge::DSL} or another external source which will also supply item types and initial state.

@param types [Hash] A name/value hash of item types supported by this engine's serialization. @param state [Array] An array of serialized Demiurge items in {Demiurge::StateItem} structured array format. @return [void] @since 0.0.1

# File lib/demiurge.rb, line 58
def initialize(types: {}, state: [])
  @klasses = {}
  if types
    types.each do |tname, tval|
      register_type(tname, tval)
    end
  end

  @finished_init = false
  @state_items = {}
  @zones = []
  state_from_structured_array(state || [])

  @item_actions = {}

  @subscriptions_by_tracker = {}

  @queued_notifications = []
  @queued_intentions = []

  @execution_context = []

  nil
end

Public Instance Methods

action_for_item(item_name, action_name) click to toggle source

Fetch an action for an ActionItem that's stored in the engine.

@api private @since 0.0.1

# File lib/demiurge.rb, line 324
def action_for_item(item_name, action_name)
  @item_actions[item_name] ? @item_actions[item_name][action_name] : nil
end
actions_for_item(item_name) click to toggle source

Fetch actions for an ActionItem that's stored in the engine.

@api private @since 0.0.1

# File lib/demiurge.rb, line 332
def actions_for_item(item_name)
  @item_actions[item_name]
end
admin_warning(message, info = {}) click to toggle source

Send a warning that something unfortunate but not continuity-threatening has occurred. The problem isn't bad enough to warrant raising an exception, but it's bad enough that we should collect data about the problem. The warning normally indicates a problem in user-supplied code, current state, or the Demiurge gem itself. These warnings can be subscribed to with the notification type {Demiurge::Notifications::AdminWarning}.

@param message [String] A user-readable log message indicating the problem that occurred @param info [Hash] A hash of additional fields that indicate the nature of the problem being reported @option info [String] “name” The name of the item causing the problem @option info [String] “zone” The name of the zone where the problem is located, if known @return [void] @since 0.0.1

# File lib/demiurge.rb, line 210
def admin_warning(message, info = {})
  send_notification({"message" => message, "info" => info},
                    type: ::Demiurge::Notifications::AdminWarning, zone: "admin", location: nil, actor: nil, include_context: true)
end
advance_one_tick() click to toggle source

Perform all necessary operations and phases for one “tick” of virtual time to pass in the Engine.

@return [void] @since 0.0.1

# File lib/demiurge.rb, line 257
def advance_one_tick()
  queue_item_intentions
  flush_intentions
  send_notification({}, type: Demiurge::Notifications::TickFinished, location: "", zone: "", actor: nil)
  flush_notifications
  nil
end
all_actions_for_all_items() click to toggle source

Fetch all actions for all items in an internal format.

@api private @since 0.0.1

# File lib/demiurge.rb, line 340
def all_actions_for_all_items
  @item_actions
end
all_item_names() click to toggle source

Get an array of all registered names for all items.

@return [Array<String>] All registered item names for this {Demiurge::Engine} @since 0.0.1

# File lib/demiurge.rb, line 143
def all_item_names
  @state_items.keys
end
finished_init() click to toggle source

The “finished_init” callback on Demiurge items exists to allow items to finalize their structure relative to other items. For instance, containers can ensure that their list of contents is identical to the set of items that list the container as their location. This cannot be done until the container is certain that all items have been added to the engine. The finished_init engine method calls {Demiurge::StateItem#finished_init} on any items that respond to that callback. Normally {Demiurge::Engine#finished_init} should be called when a new Engine is created, but not when restoring one from a state dump. This method should not be called multiple times, and the Engine will try not to allow multiple calls.

@return [void] @since 0.0.1

# File lib/demiurge.rb, line 98
def finished_init
  raise("Duplicate finished_init call to engine!") if @finished_init
  @state_items.values.each { |obj| obj.finished_init() if obj.respond_to?(:finished_init) }
  @finished_init = true
end
flush_intentions() click to toggle source

Send out all pending {Demiurge::Intention}s in the {Demiurge::Intention} queue. This will ordinarily happen at least once per tick in any case. Calling this method outside the Engine's Intention phase of a tick may cause unexpected results.

@return [void] @since 0.0.1

# File lib/demiurge.rb, line 222
def flush_intentions
  state_backup = structured_state("copy" => true)

  infinite_loop_detector = 0
  until @queued_intentions.empty?
    infinite_loop_detector += 1
    if infinite_loop_detector > 20
      raise ::Demiurge::Errors::TooManyIntentionLoopsError.new("Over 20 batches of intentions were dispatched in the same call! Error and die!", "final_batch" => @queued_intentions.map { |i| i.class.to_s })
    end

    intentions = @queued_intentions
    @queued_intentions = []
    begin
      intentions.each do |a|
        if a.cancelled?
          admin_warning("Trying to apply a cancelled intention of type #{a.class}!", "inspect" => a.inspect)
        else
          a.try_apply
        end
      end
    rescue ::Demiurge::Errors::RetryableError
      admin_warning("Exception when updating! Throwing away speculative state!", "exception" => $_.jsonable)
      load_state_from_dump(state_backup)
    end
  end

  @state_items["admin"].state["ticks"] += 1
  nil
end
flush_notifications() click to toggle source

Send out any pending notifications that have been queued. This will normally happen at least once per tick in any case, but may happen more often. If this occurs during the Engine's tick, certain ordering issues may occur. Normally it's best to let the Engine call this method during the tick, and to only call it manually when no tick is occurring.

@return [void] @since 0.0.1

# File lib/demiurge.rb, line 655
def flush_notifications
  infinite_loop_detector = 0
  # Dispatch the queued notifications. Then, dispatch any
  # notifications that resulted from them.  Then, keep doing that
  # until the queue is empty.
  until @queued_notifications.empty?
    infinite_loop_detector += 1
    if infinite_loop_detector > 20
      raise ::Demiurge::Errors::TooManyNotificationLoopsError.new("Over 20 batches of notifications were dispatched in the same call! Error and die!", "last batch" => @queued_notifications.map { |n| n.class.to_s })
    end

    current_notifications = @queued_notifications
    @queued_notifications = []
    current_notifications.each do |cleaned_data|
      @subscriptions_by_tracker.each do |tracker, sub_structures|
        sub_structures.each do |sub_structure|
          next unless sub_structure[:type] == :all || sub_structure[:type].include?(cleaned_data["type"])
          next unless sub_structure[:zone] == :all || sub_structure[:zone].include?(cleaned_data["zone"])
          next unless sub_structure[:location] == :all || sub_structure[:location].include?(cleaned_data["location"])
          next unless sub_structure[:actor] == :all || sub_structure[:actor].include?(cleaned_data["actor"])
          next unless sub_structure[:predicate] == nil || sub_structure[:predicate] == :all || sub_structure[:predicate].call(cleaned_data)

          sub_structure[:block].call(cleaned_data)
        end
      end
    end
  end
end
get_intention_id() click to toggle source

Get an intention ID which is guaranteed to never be returned by this method again. It's not important that it be consecutive or otherwise special, just that it be unique.

@return [Integer] The new intention ID @api private @since 0.2.0

# File lib/demiurge.rb, line 154
def get_intention_id
  @state_items["admin"].state["intention_id"] += 1
  return @state_items["admin"].state["intention_id"]
end
get_type(t) click to toggle source

Get a StateItem type that is registered with this Engine, using the registered name for that type.

@param t [String] The registered type name for this class object @return [Class] A StateItem Class object @since 0.0.1

# File lib/demiurge.rb, line 270
def get_type(t)
  raise("Not a valid type: #{t.inspect}!") unless @klasses[t]
  @klasses[t]
end
instantiate_new_item(name, parent, extra_state = {}) click to toggle source

This method creates a new StateItem based on an existing parent StateItem, and will retain some level of linkage to that parent StateItem afterward as well. This provides a simple form of action inheritance and data inheritance.

The new child item will begin with a copy of the parent's state which can then be overridden. There will not be a longer-term link to the parent's state, and any later state changes in the parent or child will not affect each other.

There will be a longer-term link to the parent's actions, and any action not overridden in the child item will fall back to the parent's action of the same name.

@param name [String] The new item name to register with the engine @param parent [Demiurge::StateItem] The parent StateItem @param extra_state [Hash] Additional state data for the child @return [Demiurge::StateItem] The newly-created StateItem which has been registered with the engine @since 0.0.1

# File lib/demiurge.rb, line 393
def instantiate_new_item(name, parent, extra_state = {})
  parent = item_by_name(parent) unless parent.is_a?(StateItem)
  ss = parent.get_structure

  # The new instantiated item is different from the parent because
  # it has its own name, and because it can get named actions from
  # the parent as well as itself. The latter is important because
  # we can't easily make new action procs without an associated
  # World File of some kind.
  ss[1] = name
  ss[2] = deepcopy(ss[2])
  ss[2].merge!(extra_state)
  ss[2]["parent"] = parent.name

  child = register_state_item(StateItem.from_name_type(self, *ss))
  if @finished_init && child.respond_to?(:finished_init)
    child.finished_init
  end
  child
end
item_by_name(name) click to toggle source

Get a StateItem by its registered unique name.

@param name [String] The name registered with the {Demiurge::Engine} for this item @return [StateItem, nil] The StateItem corresponding to this name or nil @since 0.0.1

# File lib/demiurge.rb, line 127
def item_by_name(name)
  @state_items[name]
end
load_state_from_dump(arr) click to toggle source

This loads the Engine's state from structured {Demiurge::StateItem} state that has been serialized. This method handles reinitializing, signaling and whatnot. Use this method to restore state from a JSON dump or a hypothetical scenario that didn't work out.

Note that this does not update code from Ruby files or otherwise handle any changes in the World Files. For that, use {#reload_from_dsl_files} or {#reload_from_dsl_text}.

You can only reload state or World Files for a running engine, never both. If you want to reload both, make a new engine and use it, or reload the two in an order of your choice. Keep in mind that some World File changes can rename state items.

@see Demiurge::DSL.engine_from_dsl_files @see Demiurge::DSL.engine_from_dsl_text @see Demiurge::Engine#reload_from_dsl_files @see Demiurge::Engine#reload_from_dsl_text @param arr [Array] {Demiurge::StateItem} structured state in the form of Ruby objects @return [void] @since 0.0.1

# File lib/demiurge.rb, line 506
def load_state_from_dump(arr)
  send_notification(type: Demiurge::Notifications::LoadStateStart, actor: nil, location: nil, zone: "admin", include_context: true)
  state_from_structured_array(arr)
  finished_init
  send_notification(type: Demiurge::Notifications::LoadStateEnd, actor: nil, location: nil, zone: "admin", include_context: true)
  flush_notifications
end
next_step_intentions() click to toggle source

Calculate the intentions for the next round of the Intention phase of a tick. This is not necessarily the same as all Intentions for the next tick - sometimes an executed {Demiurge::Intention} will queue more {Demiurge::Intention}s to run during the same phase of the same tick.

@return [void] @since 0.0.1

# File lib/demiurge.rb, line 192
def next_step_intentions()
  @zones.flat_map { |item| item.intentions_for_next_step || [] }
end
push_context(context) { || ... } click to toggle source

Certain context can be important to notifications, errors, logging and other admin-available information. For instance: the current zone-in-tick (if any), a current item taking an action and so on. This context can be attached to notifications, admin warnings, system logging and similar.

@param context [Hash{String=>String}] @yield Evaluate the following block with the given context set @api private @return [void] @since 0.3.0

# File lib/demiurge.rb, line 367
def push_context(context)
  @execution_context.push(context)
  yield
ensure
  @execution_context.pop
end
queue_intention(intention) click to toggle source

Add an intention to the Engine's Intention queue. If this method is called during the Intention phase of a tick, the intention should be excecuted during this tick in standard order. If the method is called outside the Intention phase of a tick, the Intention will normally be executed during the soonest upcoming Intention phase. Queued intentions are subject to approval, cancellation and other normal operations that Intentions undergo before being executed.

@param intention [Demiurge::Intention] The intention to be queued @return [void] @since 0.0.1

# File lib/demiurge.rb, line 171
def queue_intention(intention)
  @queued_intentions.push intention
  nil
end
queue_item_intentions() click to toggle source

Queue all Intentions for all registered items for the current tick.

@return [void] @since 0.0.1

# File lib/demiurge.rb, line 180
def queue_item_intentions()
  next_step_intentions.each { |i| queue_intention(i) }
end
register_actions_by_item_and_action_name(item_actions) click to toggle source

StateItems are transient and can be created, recreated or destroyed without warning. They need to be hooked up to the various Ruby code for their actions. The code for actions isn't serialized. Instead, each action is referred to by name, and the engine loads up all the item-name/action-name combinations when it reads the Ruby World Files. This means an action can be referred to by its name when serialized, but the actual code changes any time the world files are reloaded.

# File lib/demiurge.rb, line 298
def register_actions_by_item_and_action_name(item_actions)
  item_actions.each do |item_name, act_hash|
    if @item_actions[item_name]
      act_hash.each do |action_name, opts|
        existing = @item_actions[item_name][action_name]
        if existing
          ActionItem::ACTION_LEGAL_KEYS.each do |key|
            if existing[key] && opts[key] && existing[key] != opts[key]
              raise "Can't register action #{action_name.inspect} for item #{item_name.inspect}, conflict for key #{key.inspect}!"
            end
          end
          existing.merge!(opts)
        else
          @item_actions[item_name][action_name] = opts
        end
      end
    else
      @item_actions[item_name] = act_hash
    end
  end
end
register_state_item(item) click to toggle source

Register a new StateItem

@param item [Demiurge::StateItem] @return [Demiurge::StateItem] The same item @since 0.0.1

# File lib/demiurge.rb, line 428
def register_state_item(item)
  name = item.name
  if @state_items[name]
    raise "Duplicate item name: #{name}! Failing!"
  end
  @state_items[name] = item
  if item.zone?
    @zones.push(item)
  end
  if @finished_init
    send_notification(type: ::Demiurge::Notifications::NewItem, zone: item.zone_name, location: item.location_name, actor: name)
  end
  item
end
register_type(name, klass) click to toggle source

Register a new StateItem type with a name that will be used in structured {Demiurge::StateItem} dumps.

@param name [String] The name to use when registering this type @param klass [Class] The StateItem class to register with this name @return [void] @since 0.0.1

# File lib/demiurge.rb, line 281
def register_type(name, klass)
  if @klasses[name] && @klasses[name] != klass
    raise "Re-registering name with different type! Name: #{name.inspect} Class: #{klass.inspect} OldClass: #{@klasses[name].inspect}!"
  end
  @klasses[name] ||= klass
  nil
end
reload_from_dsl_files(*filenames, options: {}) click to toggle source

This method loads new World File code into an existing engine. It should be passed a list of filenames, normally roughly the same list that was passed to Demiurge::DSL.engine_from_dsl_files to create the engine initially.

See {#reload_from_dsl_text} for more details and allowed options. It is identical in operation except for taking code as parameters instead of filenames.

@see file:RELOADING.md @see Demiurge::DSL.engine_from_dsl_files @see reload_from_dsl_text @see load_state_from_dump @param filenames [Array<String>] An array of filenames, suitable for calling File.read on @param options [Hash] An optional hash of options for modifying the behavior of the reload @option options [Boolean] verify_only Only see if the new engine code would load, don't replace any code. @option options [Boolean] guessing_okay Attempt to guess about renamed objects @option options [Boolean] no_addition Don't allow adding new StateItems, raise an error instead @option options [Boolean] no_addition Don't allow removing StateItems, raise an error instead @return [void] A configured Engine @since 0.0.1

# File lib/demiurge/dsl.rb, line 23
def reload_from_dsl_files(*filenames, options: {})
  filename_string_pairs = filenames.map { |fn| [fn, File.read(fn)] }
  engine_from_dsl_text(*filename_string_pairs)
end
reload_from_dsl_text(*specs, options: { "verify_only" => false, "guessing_okay" => false, "no_addition" => false, "no_removal" => false }) click to toggle source

This method loads new World File code into an existing engine. It should be passed a list of “specs”, normally roughly the same list that was passed to Demiurge::DSL.engine_from_dsl_files to create the engine initially. A “spec” is either a single string of World File DSL code, or a two-element array of the form: [“label”, “code”]. Each is a string. “Code” is World File DSL Ruby code, while “label” is the name that will be used in stack traces.

Options:

  • verify_only - only check for errors, don't load the new code into the engine, aka “dry run mode”

  • guessing_okay - attempt to notice renames and modify old state to new state accordingly

  • no_addition - if any new StateItem would be created, raise a NonMatchingStateError

  • no_removal - if any StateItem would be removed, raise a NonMatchingStateError

Note that if “guessing_okay” is turned on, certain cases where same-type or (in the future) similar-type items are added and removed may be “guessed” as renames rather than treated as addition or removal.

Where the files and world objects are essentially the same, this should reload any code changes into the engine. Where they are different, the method will try to determine the best match between the new and old state, but may fail at doing so.

Ordinarily, this method should be called on a fully-configured, fully-initialized engine with its full state loaded, in between ticks.

When in doubt, it's better to save state and reload the engine from nothing. This gives far better opportunities for a human to determine what changes have occurred and manually fix any errors. A game's current state is a complex thing and a computer simply cannot correctly determine all possible changes to it in a useful way.

@see file:RELOADING.md @see Demiurge::DSL.engine_from_dsl_files @see Demiurge::DSL.engine_from_dsl_text @see load_state_from_dump @param specs [Array<String>,Array<Array<String>>] An array of specs, see above @param options [Hash] An optional hash of options for modifying the behavior of the reload @option options [Boolean] verify_only Only see if the new engine code would load, don't replace any code. @option options [Boolean] guessing_okay Attempt to guess about renamed objects @option options [Boolean] no_addition Don't allow adding new StateItems, raise an error instead @option options [Boolean] no_addition Don't allow removing StateItems, raise an error instead @return [void] A configured Engine @since 0.0.1

# File lib/demiurge/dsl.rb, line 77
def reload_from_dsl_text(*specs, options: { "verify_only" => false, "guessing_okay" => false, "no_addition" => false, "no_removal" => false })
  old_engine = self
  new_engine = nil

  send_notification type: Demiurge::Notifications::LoadWorldVerify, zone: "admin", location: nil, actor: nil, include_context: true

  begin
    new_engine = Demiurge::DSL.engine_from_dsl_text(*specs)
  rescue
    # Didn't work? Leave the existing engine intact, but raise.
    raise Demiurge::Errors::CannotLoadWorldFiles.new("Error reloading World File text")
  end

  # Match up old and new state items, but the "admin" InertStateItem doesn't get messed with
  old_item_names = old_engine.all_item_names - ["admin"]
  new_item_names = new_engine.all_item_names - ["admin"]

  shared_item_names = old_item_names & new_item_names
  added_item_names = new_item_names - shared_item_names
  removed_item_names = old_item_names - shared_item_names
  renamed_pairs = {}

  if options["guessing_okay"]
    # For right this second, don't guess. When guessing happens,
    # this will populate the renamed_pairs hash.
  end

  if options["no_addition"] && !added_item_names.empty?
    raise NonMatchingStateError.new "StateItems added when they weren't allowed: #{added_item_names.inspect}!"
  end

  if options["no_removal"] && !removed_item_names.empty?
    raise NonMatchingStateError.new "StateItems removed when they weren't allowed: #{removed_item_names.inspect}!"
  end

  # Okay, finished with error checking - the dry-run is over
  return if options["verify_only"]

  # Now, replace the engine code

  send_notification type: Demiurge::Notifications::LoadWorldStart, zone: "admin", location: nil, actor: nil, include_context: true

  # Replace all actions performed by ActionItems
  old_engine.replace_all_actions_for_all_items(new_engine.all_actions_for_all_items)

  # For removed items, delete the StateItem from the old engine
  removed_item_names.each do |removed_item_name|
    old_engine.unregister_state_item(old_engine.item_by_name removed_item_name)
  end

  # For added items, use the state data from the new engine and add the item to the old engine
  added_item_names.each do |added_item_name|
    new_item = new_engine.item_by_name(added_item_name)
    ss = new_item.structured_state
    old_engine.register_state_item(StateItem.from_name_type(old_engine, *ss))
  end

  # A rename is basically an add and a remove... But not necessarily
  # with the same name. And the newly-created item uses the state
  # from the older item. A rename is also permitted to choose a new
  # type, so create the new item in the old engine with the new name
  # and type, but the old state.
  renamed_pairs.each do |old_name, new_name|
    old_item = old_engine.item_by_name(old_name)
    new_item = new_engine.item_by_name(new_name)

    old_type, _, old_state = *old_item.structured_state
    new_type, _, new_state = *new_item.structured_state

    old_engine.unregister_state_item(old_item)
    old_engine.register_state_item(StateItem.from_name_type(old_engine, new_type, new_name, old_state))
  end

  send_notification type: Demiurge::Notifications::LoadWorldEnd, zone: "admin", location: nil, actor: nil, include_context: true
  nil
end
replace_all_actions_for_all_items(item_action_hash) click to toggle source

Replace actions for an item with other, potentially quite different, actions. This is normally done to reload engine state from World Files.

@api private @return [void] @since 0.0.1

# File lib/demiurge.rb, line 351
def replace_all_actions_for_all_items(item_action_hash)
  @item_actions = item_action_hash
  nil
end
send_notification(data = {}, type:, zone:, location:, actor:, include_context:false) click to toggle source

Queue a notification to be sent later by the engine. The notification must include at least type, zone, location and actor and may include a hash of additional data, which should be serializable to JSON (i.e. use only basic data types.)

@param type [String] The notification type of this notification @param zone [String, nil] The zone name for this notification. The special “admin” zone name is used for engine-wide events @param location [String, nil] The location name for this notification, or nil if no location @param actor [String, nil] The name of the acting item for this notification, or nil if no item is acting @param data [Hash] Additional data about this notification; please use String keys for the Hash @return [void] @since 0.0.1

# File lib/demiurge.rb, line 626
def send_notification(data = {}, type:, zone:, location:, actor:, include_context:false)
  raise "Notification type must be a String, not #{type.class}!" unless type.is_a?(String)
  raise "Location must be a String, not #{location.class}!" unless location.is_a?(String) || location.nil?
  raise "Zone must be a String, not #{zone.class}!" unless zone.is_a?(String)
  raise "Acting item must be a String or nil, not #{actor.class}!" unless actor.is_a?(String) || actor.nil?

  @state_items["admin"].state["notification_id"] += 1

  cleaned_data = {}
  cleaned_data["context"] = @execution_context if include_context
  data.each do |key, val|
    # TODO: verify somehow that this is JSON-serializable?
    cleaned_data[key.to_s] = val
  end
  cleaned_data.merge!("type" => type, "zone" => zone, "location" => location, "actor" => actor,
    "notification_id" => @state_items["admin"].state["notification_id"])

  @queued_notifications.push(cleaned_data)
end
structured_state(options = { "copy" => false }) click to toggle source

This method dumps the Engine's state in {Demiurge::StateItem} structured array format. This method is how one would normally collect a full state dump of the engine suitable for later restoration.

@param [Hash] options Options for dumping state @option options [Boolean] copy If true, copy the serialized state rather than allowing any links into StateItem objects. This reduces performance but increases security. @return [Array] The engine's state in {Demiurge::StateItem} structured array format @since 0.0.1 @see load_state_from_dump

# File lib/demiurge.rb, line 114
def structured_state(options = { "copy" => false })
  dump = @state_items.values.map { |item| item.get_structure }
  if options["copy"]
    dump = deepcopy(dump)  # Make sure it doesn't share state...
  end
  dump
end
subscribe_to_notifications(type: :all, zone: :all, location: :all, predicate: nil, actor: :all, tracker: nil, &block) click to toggle source

This method 'subscribes' a block to various types of notifications. The block will be called with the notifications when they occur. A “specifier” for this method means either the special symbol :all or an Array of Symbols or Strings to show what values a notification may have for the given field. For fields that might indicate Demiurge items such as “zone” or “actor” the value should be the Demiurge item name, not the item itself.

When a notification occurs that matches the subscription, the given block will be called with a hash of data about that notification.

The tracker is supplied to allow later unsubscribes. Pass a unique tracker object (usually a String or Symbol) when subscribing, then pass in the same one when unsubscribing.

At a minimum, subscriptions should include a zone to avoid subscribing to all such notifications everywhere in the engine. Engine-wide subscriptions become very inefficient very quickly.

Notifications only have a few mandatory fields - type, actor, zone and location. The location and/or actor can be nil in some cases, and the zone can be “admin” for engine-wide events. If you wish to subscribe based on other properties of the notification then you'll need to pass a custom predicate to check each notification. A “predicate” just means it's a proc that returns true or false, depending whether a notification matches.

@example Subscribe to all notification types at a particular location subscribe_to_notifications(zone: “my zone name”, location: “my location”) { |h| puts “Got #{h.inspect}!” }

@example Subscribe to all “say” notifications in my same zone subscribe_to_notifications(zone: “my zone”, type: “say”) { |h| puts “Somebody said something!” }

@example Subscribe to all move_to notifications for a specific actor, with a tracker for future unsubscription subscribe_to_notifications(zone: [“one”, “two”, “three”], type: “move_to”, actor: “bozo the clown”, tracker: “bozo move tracker”) { |h| bozo_move(h) }

@example Subscribe to notifications matching a custom predicate subscribe_to_notifications(zone: “green field”, type: “joyous dance”, predicate: proc { |h| h[“subtype”] == “butterfly wiggle” }) { |h| process(h) }

@param type [:all, String, Array<Symbol>, Array<String>] A specifier for what Demiurge notification names to subscribe to @param zone [:all, String, Array<Symbol>, Array<String>] A specifier for what Zone names match this subscription @param location [:all, String, Array<Symbol>, Array<String>] A specifier for what location names match this subscription @param predicate [Proc, nil] Call this proc on each notification to see if it matches this subscription @param actor [:all, String, Array<Symbol>, Array<String>] A specifier for what Demiurge item name(s) must be the actor in a notification to match this subscription @param tracker [Object, nil] To unsubscribe from this notification later, pass in the same tracker to {#unsubscribe_from_notifications}, or another object that is +==+ to this tracker. A tracker is most often a String or Symbol. If the tracker is nil, you can't ever unsubscribe. @return [void] @since 0.0.1

# File lib/demiurge.rb, line 582
def subscribe_to_notifications(type: :all, zone: :all, location: :all, predicate: nil, actor: :all, tracker: nil, &block)
  sub_structure = {
    type: notification_spec(type),
    zone: notification_spec(zone),
    location: notification_spec(location),
    actor: notification_spec(actor),
    predicate: predicate,
    tracker: tracker,
    block: block,
  }
  @subscriptions_by_tracker[tracker] ||= []
  @subscriptions_by_tracker[tracker].push(sub_structure)
  nil
end
unregister_state_item(item) click to toggle source

This method unregisters a StateItem from the engine. The method assumes other items don't refer to the item being unregistered. {#unregister_state_item} will try to perform basic cleanup, but calling it can leave dangling references.

@param [Demiurge::StateItem] item The item to unregister @return [void] @since 0.0.1

# File lib/demiurge.rb, line 451
def unregister_state_item(item)
  loc = item.location
  loc.ensure_does_not_contain(item.name)
  zone = item.zone
  zone.ensure_does_not_contain(item.name)
  @state_items.delete(item.name)
  @zones -= [item]
  nil
end
unsubscribe_from_notifications(tracker) click to toggle source

When you subscribe to a notification with {#subscribe_to_notifications}, you may optionally pass a non-nil tracker with the subscription. If you pass that tracker to this method, it will unsubscribe you from that notification. Multiple subscriptions can use the same tracker and they will all be unsubscribed at once. For that reason, you should use a unique tracker if you do not want other code to be able to unsubscribe you from notifications.

@param tracker [Object] The tracker from which to unsubscribe @return [void] @since 0.0.1

# File lib/demiurge.rb, line 609
def unsubscribe_from_notifications(tracker)
  raise "Tracker must be non-nil!" if tracker.nil?
  @subscriptions_by_tracker.delete(tracker)
end
valid_item_name?(name) click to toggle source

Determine whether the item name is basically allowable.

@param name String The item name to check @return [Boolean] Whether the item name is valid, just in terms of its characters. @since 0.0.1

# File lib/demiurge.rb, line 419
def valid_item_name?(name)
  !!(name =~ /\A[-_ 0-9a-zA-Z]+\Z/)
end
zones() click to toggle source

Get an Array of StateItems that are top-level {Demiurge::Zone} items.

@since 0.0.1 @return [Array<Demiurge::StateItem>] All registered StateItems that are treated as {Demiurge::Zone} items

# File lib/demiurge.rb, line 135
def zones
  @zones
end

Private Instance Methods

notification_entity(s) click to toggle source
# File lib/demiurge.rb, line 524
def notification_entity(s)
  s = s.to_s if s.is_a?(Symbol)
  s = s.name if s.respond_to?(:name) # Demiurge Entities should be replaced by their names
  raise "Unrecognized notification entity: #{s.inspect}!" unless s.is_a?(String)
  s
end
notification_spec(s) click to toggle source

Internal methods used by subscribe_to_notifications for notification matching.

# File lib/demiurge.rb, line 516
def notification_spec(s)
  return s if s == :all
  if s.respond_to?(:each)
    return s.map { |s| notification_entity(s) }
  end
  return [notification_entity(s)]
end
state_from_structured_array(arr) click to toggle source

This sets the Engine's internal state from a structured array of items. It is normally used via load_state_from_dump.

# File lib/demiurge.rb, line 464
def state_from_structured_array(arr)
  @finished_init = false
  @state_items = {}
  @zones = []

  unless arr.any? { |type, name, state| name == "admin" }
    register_state_item(StateItem.from_name_type(self, "InertStateItem", "admin", {}))
    @state_items["admin"].state["ticks"] ||= 0
    @state_items["admin"].state["notification_id"] ||= 0
    @state_items["admin"].state["intention_id"] ||= 0
  end

  arr.each do |type, name, state|
    register_state_item(StateItem.from_name_type(self, type.freeze, name.to_s.freeze, state))
  end

  nil
end