Object Sets

An object set is a structure used to keep track of zero or more objects. An "object" is an object in the game, so a character, a tree, an effect, etc... Anything that you can physically place in your stage. Sets are unordered, so you can't guarantee the order that the objects will be retrieved. Sets also only allow one copy of an object, so if you try to add an object to a set that already contains that object, the set won't change. By default an object set is empty, which isn't terribly useful, so let's see some examples of how to use it.

=Manipulating An Object Set=

Assigning to an object set
You can either assign an object set using the [equals] tile. You can assign an object set to another existing object set, which will make it track all the same objects, you can assign an object set to an object, which will make your set contain exactly one object, or you can assign your object set to be nothing, which will have it contain no objects.

Please note that, like with any variable, assigning to an object set will overwrite whatever information was previously stored.

Adding or removing from an object set
Object sets support the [increment by] and [decrement by] tiles. These will allow you to add/remove items from your set while keeping the existing objects in there. You can increment or decrement by either single objects, or object sets.

=Common Functionality=

Count
The [count] property of an object set will tell you how many objects the set is currently keeping track of.

Contains
The [contains] tile checks to see if an object set contains something. When used with an object, it returns true if the object is in the set. When used with another object set, you are checking if one object set contains every item in the other, and only if so does it return true.

Intersect
Intersect is used with object sets to get the objects that are shared between sets. For example if we had two object sets, [object set 1] that contains objects (a, b, c) and [object set 2] that contains objects (b, c, d), then if we were to ask for [object set 1] [intersect] [object set 2] you should get (b, c) because those objects are in both of your sets.

Note: Usually, having an [intersect] tile might suggest that you should have a union tile as well. The union operation can be accomplished by simply adding two sets together with the [plus] tile.

=Tiles That Produces Sets=

There are actually several tiles that produce object sets that you may just not think of. Each of the sensors for example. Let's look at [in trigger zone].

The [in trigger zone] tile is actually returning an object set that contains every object in the trigger zone.

=Filtering=

Filtering is way to get just the objects you need, and is visible even in the default character brain. Let's dissect this line:

First, it gets all objects that are detected with the [detect] tile. Then the results of the [detect] tile are filtered through the [interactable] tile, leaving you with objects that are both detected and interactable. Finally, those objects are filtered futher, but the [objects in front] tile, until you are left with objects that meet all three of your conditions.

So how does this work?

This "filtering" is really just an application of intersecting sets. Each of those tiles, [detect], [interactable] and [objects in front] return a set of objects. Placing two object set tiles next to each other returns an object set with the intersection of the two sets. So the line above could also be written as

Something worth mentioning is how templates work here. If you select a template with the in world picker you can use it as an object set that contains all objects created from that template. Because of this, you can filter with templates to get just objects that were made from that template. The objects from the prop gallery are also templates. So if you were to say When [Goblin] by selecting the goblin from the gallery, you would get the the set of all goblins in the game.

=Increased, decreased, and changed=

You can use the increased/decreased and changed tiles to track what has changed in an object set. These tiles will return just the objects that have been added or removed from the set this frame.

=Destroying objects in a set=

When an object is destroyed, it should get automatically removed from your set. However, there was a recent bug where certain objects when destroyed were not removed from your set, so it may be a good idea to remove items from the set directly rather than relying on them getting removed when they are destroyed. The specific issue was around the Destroy After Death property I believe.