Sub entity is a sub set of animation properties that “spawn” or “summon” another entity into play. The model brought into play is determined by the sub_entity_model_index animation property.

Script Access

Sub entity is a sub property of Animation Properties. To access sub entity properties, you must first get the sub entity pointer. Once you have the sub entity pointer, you may get and set sub entity properties at will.

Use Cases

Read/write

Get a parent pointer, in this case sub_entity_spawn. If the parent pointer is NULL, there is no sub entity property in place and you will need to allocate one first.

void sub_entity = get_animation_property(void <animation pointer>, "sub_entity_spawn");

Get a sub entity property value.

mixed x = get_sub_entity_property(void <sub_entity>, char <property>);

Modify a sub entity property value:

mixed x = <value>;

set_sub_entity_property(void <sub_entity>, char <property>, x);

Allocate/Free

In many cases, the parent properties will have a NULL value. This is because there is no sub entity property allocated. There is no reason to waste memory on an unused command, so if a model’s text file does not call for a sub entity, OpenBOR will not allocate the properties for it. The parent property retains a NULL value indicating it points at nothing.

If you want to add a new sub entity property, you first need to tell OpenBOR to allocate the memory space and get the pointer. Once you have the pointer value, you can then place it into the target parent property to use. Of course you can also modify the newly created sub entity property values before or after you place the pointer into a parent property. In the example below, we allocate a sub entity property, set one of its values, and then place it into an animation’s sub_entity_spawn property.

void sub_entity = allocate_sub_entity();

set_sub_entity_property(sub_entity, "position_x", 10.0);

set_animation_property(void <animation pointer>, "sub_entity_spawn", sub_entity);

You may also delete any set of sub entity properties as a quick means of disabling them, or to free up memory when you don’t need them any more. First, you will need the sub entity property pointer. Then, apply the free(<target pointer>) function to delete the memory space. The properties no longer exist. Now (VERY important), you need to make sure no parent properties or script variables are pointing to the memory you just deleted. Otherwise you’ll get undefined behavior – usually an instant shutdown. In the example below, we get the pointer from an animation’s sub_entity_spawn property, free the allocated memory, and then set the sub_entity_spawn to NULL.

void sub_entity = get_animation_property(void <animation pointer>, "sub_entity_spawn");

free(sub_entity);

set_animation_property(void <animation pointer>, "sub_entity_spawn", NULL());

Property List

• Name: The identifier used to access property through script.
• Type: The property value’s variable type.
• Read Only: If the property is a read only attribute.
• Description: A short description of what the property is and does.