Class: Demiurge::Engine

Inherits:
Object
  • Object
show all
Includes:
Util
Defined in:
lib/demiurge.rb,
lib/demiurge/dsl.rb

Overview

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 DSL Object Types should be shared.

Since:

  • 0.0.1

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Util

#copyfreeze, #deepcopy

Constructor Details

#initialize(types: {}, state: []) ⇒ void

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

Parameters:

  • types (Hash) —

    A name/value hash of item types supported by this engine's serialization.

  • state (Array) —

    An array of serialized Demiurge items in StateItem structured array format.

Since:

  • 0.0.1



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/demiurge.rb', line 63

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

Instance Attribute Details

#execution_context ⇒ Hash{String=>String} (readonly)

Returns The current execution context for notifications and logging.

Returns:

  • (Hash{String=>String}) —

    The current execution context for notifications and logging.

Since:

  • 0.3.0



53
54
55
 
# File 'lib/demiurge.rb', line 53

def execution_context
  @execution_context
end

#ticks ⇒ Integer (readonly)

Returns The number of ticks that have occurred since the beginning of this Engine's history.

Returns:

  • (Integer) —

    The number of ticks that have occurred since the beginning of this Engine's history.

Since:

  • 0.0.1



49
50
51
 
# File 'lib/demiurge.rb', line 49

def ticks
  @ticks
end

Instance Method Details

#action_for_item(item_name, action_name) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Since:

  • 0.0.1



329
330
331
 
# File 'lib/demiurge.rb', line 329

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) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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

Since:

  • 0.0.1



337
338
339
 
# File 'lib/demiurge.rb', line 337

def actions_for_item(item_name)
  @item_actions[item_name]
end

#admin_warning(message, info = {}) ⇒ void

This method returns an undefined value.

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 Notifications::AdminWarning.

Parameters:

  • message (String) —

    A user-readable log message indicating the problem that occurred

  • info (Hash) (defaults to: {}) —

    A hash of additional fields that indicate the nature of the problem being reported

Options Hash (info):

  • "name" (String) —

    The name of the item causing the problem

  • "zone" (String) —

    The name of the zone where the problem is located, if known

Since:

  • 0.0.1



215
216
217
218
 
# File 'lib/demiurge.rb', line 215

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 ⇒ void

This method returns an undefined value.

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

Since:

  • 0.0.1



262
263
264
265
266
267
268
 
# File 'lib/demiurge.rb', line 262

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 ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Fetch all actions for all items in an internal format.

Since:

  • 0.0.1



345
346
347
 
# File 'lib/demiurge.rb', line 345

def all_actions_for_all_items
  @item_actions
end

#all_item_names ⇒ Array<String>

Get an array of all registered names for all items.

Returns:

Since:

  • 0.0.1



148
149
150
 
# File 'lib/demiurge.rb', line 148

def all_item_names
  @state_items.keys
end

#finished_init ⇒ void

This method returns an undefined value.

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 StateItem#finished_init on any items that respond to that callback. Normally #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.

Since:

  • 0.0.1



103
104
105
106
107
 
# File 'lib/demiurge.rb', line 103

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 ⇒ void

This method returns an undefined value.

Send out all pending Intentions in the 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.

Since:

  • 0.0.1



227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/demiurge.rb', line 227

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 ⇒ void

This method returns an undefined value.

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.

Since:

  • 0.0.1



660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
 
# File 'lib/demiurge.rb', line 660

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 ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

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.

Returns:

  • (Integer) —

    The new intention ID

Since:

  • 0.2.0



159
160
161
162
 
# File 'lib/demiurge.rb', line 159

def get_intention_id
  @state_items["admin"].state["intention_id"] += 1
  return @state_items["admin"].state["intention_id"]
end

#get_type(t) ⇒ Class

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

Parameters:

  • t (String) —

    The registered type name for this class object

Returns:

  • (Class) —

    A StateItem Class object

Since:

  • 0.0.1



275
276
277
278
 
# File 'lib/demiurge.rb', line 275

def get_type(t)
  raise("Not a valid type: #{t.inspect}!") unless @klasses[t]
  @klasses[t]
end

#instantiate_new_item(name, parent, extra_state = {}) ⇒ Demiurge::StateItem

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.

Parameters:

  • name (String) —

    The new item name to register with the engine

  • parent (Demiurge::StateItem) —

    The parent StateItem

  • extra_state (Hash) (defaults to: {}) —

    Additional state data for the child

Returns:

  • (Demiurge::StateItem) —

    The newly-created StateItem which has been registered with the engine

Since:

  • 0.0.1



398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
 
# File 'lib/demiurge.rb', line 398

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) ⇒ StateItem?

Get a StateItem by its registered unique name.

Parameters:

Returns:

  • (StateItem, nil) —

    The StateItem corresponding to this name or nil

Since:

  • 0.0.1



132
133
134
 
# File 'lib/demiurge.rb', line 132

def item_by_name(name)
  @state_items[name]
end

#load_state_from_dump(arr) ⇒ void

This method returns an undefined value.

This loads the Engine's state from structured 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.

Parameters:

  • arr (Array) —

    StateItem structured state in the form of Ruby objects

See Also:

Since:

  • 0.0.1



511
512
513
514
515
516
517
 
# File 'lib/demiurge.rb', line 511

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 ⇒ void

This method returns an undefined value.

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 Intention will queue more Intentions to run during the same phase of the same tick.

Since:

  • 0.0.1



197
198
199
 
# File 'lib/demiurge.rb', line 197

def next_step_intentions()
  @zones.flat_map { |item| item.intentions_for_next_step || [] }
end

#push_context(context) { ... } ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

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.

Parameters:

  • context (Hash{String=>String})

Yields:

  • Evaluate the following block with the given context set

Since:

  • 0.3.0



372
373
374
375
376
377
 
# File 'lib/demiurge.rb', line 372

def push_context(context)
  @execution_context.push(context)
  yield
ensure
  @execution_context.pop
end

#queue_intention(intention) ⇒ void

This method returns an undefined value.

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.

Parameters:

Since:

  • 0.0.1



176
177
178
179
 
# File 'lib/demiurge.rb', line 176

def queue_intention(intention)
  @queued_intentions.push intention
  nil
end

#queue_item_intentions ⇒ void

This method returns an undefined value.

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

Since:

  • 0.0.1



185
186
187
 
# File 'lib/demiurge.rb', line 185

def queue_item_intentions()
  next_step_intentions.each { |i| queue_intention(i) }
end

#register_actions_by_item_and_action_name(item_actions) ⇒ Object

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.

Since:

  • 0.0.1



303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/demiurge.rb', line 303

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) ⇒ Demiurge::StateItem

Register a new StateItem

Parameters:

Returns:

Since:

  • 0.0.1



433
434
435
436
437
438
439
440
441
442
443
444
445
446
 
# File 'lib/demiurge.rb', line 433

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) ⇒ void

This method returns an undefined value.

Register a new StateItem type with a name that will be used in structured StateItem dumps.

Parameters:

  • name (String) —

    The name to use when registering this type

  • klass (Class) —

    The StateItem class to register with this name

Since:

  • 0.0.1



286
287
288
289
290
291
292
 
# File 'lib/demiurge.rb', line 286

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: {}) ⇒ void

This method returns an undefined value.

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.

Parameters:

  • filenames (Array<String>) —

    An array of filenames, suitable for calling File.read on

  • options (Hash) —

    An optional hash of options for modifying the behavior of the reload

Options Hash (options:):

  • verify_only (Boolean) —

    Only see if the new engine code would load, don't replace any code.

  • guessing_okay (Boolean) —

    Attempt to guess about renamed objects

  • no_addition (Boolean) —

    Don't allow adding new StateItems, raise an error instead

  • no_addition (Boolean) —

    Don't allow removing StateItems, raise an error instead

See Also:

Since:

  • 0.0.1



23
24
25
26
 
# 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 }) ⇒ void

This method returns an undefined value.

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.

Parameters:

  • specs (Array<String>, Array<Array<String>>) —

    An array of specs, see above

  • options (Hash) —

    An optional hash of options for modifying the behavior of the reload

Options Hash (options:):

  • verify_only (Boolean) —

    Only see if the new engine code would load, don't replace any code.

  • guessing_okay (Boolean) —

    Attempt to guess about renamed objects

  • no_addition (Boolean) —

    Don't allow adding new StateItems, raise an error instead

  • no_addition (Boolean) —

    Don't allow removing StateItems, raise an error instead

See Also:

Since:

  • 0.0.1



77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
 
# 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_state = *old_item.structured_state
    new_type, _, _ = *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) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

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

Since:

  • 0.0.1



356
357
358
359
 
# File 'lib/demiurge.rb', line 356

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) ⇒ void

This method returns an undefined value.

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.)

Parameters:

  • type (String) —

    The notification type of this notification

  • zone (String, nil) —

    The zone name for this notification. The special "admin" zone name is used for engine-wide events

  • location (String, nil) —

    The location name for this notification, or nil if no location

  • actor (String, nil) —

    The name of the acting item for this notification, or nil if no item is acting

  • data (Hash) (defaults to: {}) —

    Additional data about this notification; please use String keys for the Hash

Since:

  • 0.0.1



631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
 
# File 'lib/demiurge.rb', line 631

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 }) ⇒ Array

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

Parameters:

  • options (Hash) (defaults to: { "copy" => false }) —

    Options for dumping state

Options Hash (options):

  • copy (Boolean) —

    If true, copy the serialized state rather than allowing any links into StateItem objects. This reduces performance but increases security.

Returns:

  • (Array) —

    The engine's state in StateItem structured array format

See Also:

Since:

  • 0.0.1



119
120
121
122
123
124
125
 
# File 'lib/demiurge.rb', line 119

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) ⇒ void

This method returns an undefined value.

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.

subscribe_to_notifications(zone: "my zone name", location: "my location") { |h| puts "Got #Demiurge::Engine.hh.inspect!" }

subscribe_to_notifications(zone: "my zone", type: "say") { |h| puts "Somebody said something!" }

subscribe_to_notifications(zone: ["one", "two", "three"], type: "move_to", actor: "bozo the clown", tracker: "bozo move tracker") { |h| bozo_move(h) }

subscribe_to_notifications(zone: "green field", type: "joyous dance", predicate: proc { |h| h["info"]["subtype"] == "butterfly wiggle" }) { |h| process(h) }

Examples:

Subscribe to all notification types at a particular location

Subscribe to all "say" notifications in my same zone

Subscribe to all move_to notifications for a specific actor, with a tracker for future unsubscription

Subscribe to notifications matching a custom predicate

Parameters:

  • type (:all, String, Array<Symbol>, Array<String>) —

    A specifier for what Demiurge notification names to subscribe to

  • zone (:all, String, Array<Symbol>, Array<String>) —

    A specifier for what Zone names match this subscription

  • location (:all, String, Array<Symbol>, Array<String>) —

    A specifier for what location names match this subscription

  • predicate (Proc, nil) —

    Call this proc on each notification to see if it matches this subscription

  • 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

  • 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.

Since:

  • 0.0.1



587
588
589
590
591
592
593
594
595
596
597
598
599
600
 
# File 'lib/demiurge.rb', line 587

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) ⇒ void

This method returns an undefined value.

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.

Parameters:

Since:

  • 0.0.1



456
457
458
459
460
461
462
463
464
 
# File 'lib/demiurge.rb', line 456

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) ⇒ void

This method returns an undefined value.

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.

Parameters:

  • tracker (Object) —

    The tracker from which to unsubscribe

Since:

  • 0.0.1



614
615
616
617
 
# File 'lib/demiurge.rb', line 614

def unsubscribe_from_notifications(tracker)
  raise "Tracker must be non-nil!" if tracker.nil?
  @subscriptions_by_tracker.delete(tracker)
end

#valid_item_name?(name) ⇒ Boolean

Determine whether the item name is basically allowable.

Parameters:

  • name —

    String The item name to check

Returns:

  • (Boolean) —

    Whether the item name is valid, just in terms of its characters.

Since:

  • 0.0.1



424
425
426
 
# File 'lib/demiurge.rb', line 424

def valid_item_name?(name)
  !!(name =~ /\A[-_ 0-9a-zA-Z]+\Z/)
end

#zones ⇒ Array<Demiurge::StateItem>

Get an Array of StateItems that are top-level Zone items.

Returns:

Since:

  • 0.0.1



140
141
142
 
# File 'lib/demiurge.rb', line 140

def zones
  @zones
end