# actor


A set of utilities for iterating over a hierarchy of actor-like objects, as well
as managing tag-based lookups. Objects are assumed to have a "objects" property,
pointing to children or sub-objects, forming a tree.


### all_objects(fn, startobj) <sub>function</sub>


Iterate over each object (and its sub-objects) in the hierarchy, calling fn for each one.


**fn**: A callback function that receives each object. If it returns a truthy value, iteration stops and that value is returned.

**startobj**: The root object at which iteration begins, default is the global "world".


**Returns**: The first truthy value returned by fn, or undefined if none.


### find_object(fn, startobj) <sub>function</sub>


Intended to find a matching object within the hierarchy.


**fn**: A callback or criteria to locate a particular object.

**startobj**: The root object at which search begins, default "world".


**Returns**: Not yet implemented.


### tag_add(tag, obj) <sub>function</sub>


Associate the given object with the specified tag. Creates a new tag set if it does not exist.


**tag**: A string tag to associate with the object.

**obj**: The object to add under this tag.


**Returns**: None


### tag_rm(tag, obj) <sub>function</sub>


Remove the given object from the specified tag’s set, if it exists.


**tag**: The tag to remove the object from.

**obj**: The object to remove from the tag set.


**Returns**: None


### tag_clear_guid(obj) <sub>function</sub>


Remove the object from all tag sets.


**obj**: The object whose tags should be cleared.


**Returns**: None


### objects_with_tag(tag) <sub>function</sub>


Retrieve all objects currently tagged with the specified tag.


**tag**: A string tag to look up.


**Returns**: An array of objects associated with the given tag.