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
@return [Hash{String=>String}] The current execution context for notifications and logging. @since 0.3.0
@return [Integer] The number of ticks that have occurred since the beginning of this Engine's history.
Public Class Methods
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
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
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
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
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
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
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
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
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
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 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 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
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
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
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
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
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
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 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
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 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 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
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
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 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
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
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
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
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
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
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
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
# 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
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
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