Bind is a set of script accessible entity sub properties that “attach” one entity to another. In addition to position, it is also possible to bind an entity to another entity’s animations and animation frames. Binding is essential for most particle effects, grappling animations, multi-piece boss battles, or any other effect where one entity must overlay another in real time. It is important to note that entities do not bind other entities to themselves, they bind themselves to other entities.
It is logically impossible for an entity to bind itself to more than one target at a time, but there is nothing at all preventing an entity from being the target of multiple binds. This means that one entity might have several other entities binding themselves to it, while that entity may in turn be binding itself to another entity, and so on. Binding is accessible through the get_bind_property() and set_bind_property() functions.
Whenever active binds are present, the engine will execute the following event scripts on the bound entity and the binding target. You may use these to further refine binding control or perform other actions as necessary:
- On bind update other to self script – Executed by the target of bind. Returns following local variables:
self– Pointer to entity executing script.other– Pointer to entity binding itself to self.bind– Pointer to bind property in use by other.
- On bind update self to other script – Executed by entity currently binding itself. Returns following local variables:
self– Pointer to entity executing script.other– Pointer to entity that self is binding to.bind– Pointer to bind property in use by self.
Script Access
Bind is a sub-property of Entity Properties. To access bind, you must first get the entity’s bind pointer. Once you have the bind property pointer, you may get and set bind properties at will.
Get a bind property value.
mixed x = get_bind_property(void <bind pointer>, int <property>);
Modify a bind property value.
mixed new_value = <value>
set_bind_property(void <bind pointer>, int <property>, new_value);
Property List
- Constant: The
openborconstant()used to access property. - Type: The property value’s variable type.
- Description: A short description of what the property is and does.
| Name | Type | Description |
|---|---|---|
| BIND_PROPERTY_ANIMATION_FRAME | Integer | Frame to match. Provide a frame for entity to bind itself to here. This property has no effect unless the config property is set to use it. |
| BIND_PROPERTY_ANIMATION_ID | Integer | Animation to match. Provide an animation constant for entity to bind itself to here. This property has no effect unless the config property is set to use it. |
| BIND_PROPERTY_CONFIG | Integer | Primary binding behaviors. Uses following bitmask constants: * openborconstant("BIND_CONFIG_ANIMATION_DEFINED") – Attempt to match the animation id provided in animation_id property. * openborconstant(" – Attempt to match the animation_frame property.* openborconstant(" – Attempt to match target’s current animation frame.* openborconstant(" – Entity is kills self if it is unable to match frames.* openborconstant(" – Entity is killed if it is unable to match animations (i.e. doesn’t have the requested animation available). * openborconstant(" – Bind X axis position to arbitrary location in level with offset.* openborconstant(" – Bind X axis position to target (if any) with offset.* openborconstant(" – Bind Y axis position to arbitrary location in level with offset.* openborconstant(" – Bind Y axis position to target (if any) with offset.* openborconstant(" – Bind Z axis position to arbitrary location in level with offset.* openborconstant(" – No flags. Assign this directly (not as a bitmask) to reset all flags to 0.* openborconstant(" – When in a falling state, disable ground detection.* openborconstant(" – Disable dropframe.* openborconstant(" – Disable landframe.* openborconstant(" – Disable specials (when controlled by AI).* openborconstant(" – Disable specials (when controlled by player).Tip: Use override flags to resolve behavior conflicts when making custom slams or similar systems. One example is falling behavior during scripted slams when bound entities touch the ground. Native fall landing behaviors activate and ruin the grappling sequence. By using openborconstant(" flag to disable falling behavior, the problem is eliminated without the need for tedious and potentially buggy workarounds. |
| BIND_PROPERTY_DIRECTION_ADJUST | Integer | Directional binding behavior. * openborconstant("DIRECTION_ADJUST_LEFT") – Always face left. * openborconstant("DIRECTION_ADJUST_NONE") – No directional binding. * openborconstant("DIRECTION_ADJUST_OPPOSITE") – Always opposite direction as target.* openborconstant("DIRECTION_ADJUST_RIGHT") – Always face right. * openborconstant("DIRECTION_ADJUST_SAME") – Always face same direction as target. |
| BIND_PROPERTY_META_TAG | Integer | Tags are attributes not used in any way by engine logic. Employ this to store your own custom information about a bind. |
| BIND_PROPERTY_OFFSET_X | Integer | Adjust the final horizontal position. Positive values adjust toward direction target is facing, negative values adjust away. If not bound to an entity, higher values adjust rightward and vise versa. |
| BIND_PROPERTY_OFFSET_Y | Integer | Adjusts the final vertical position. Positive values adjust upward from target, negative values adjust downward. |
| BIND_PROPERTY_OFFSET_Z | Integer | Adjusts the bind position in relation to target’s lateral position. Positive values adjust toward the camera from target, negative values adjust toward the background. |
| BIND_PROPERTY_SORT_ID | Integer | Drawing sort adjustment in relation to target. Drawing order is determined by a combination of sort ID and position on the Z axis. Lower numbered items are drawn first, meaning that higher numbered items will appear over top of them. For example, if the target and entity are on the same Z axis, a value of -1 will place the entity one lower in drawing order compared to the target. The entity would therefore appear to be behind the target. If Z position and sorting ID are both identical, then drawing order will be whichever is updated first on each engine cycle, resulting in possible flicker back and forth. |
| BIND_PROPERTY_TARGET | Pointer | The target entity to bind to. If this attribute is empty or null, there is effectively no bind at all. The other attributes will continue to exist, but the engine will not conduct any binding logic. |
| Name | Type | Description |
Legacy
Prior to OpenBOR 4.0, bind properties were not exposed. Binding control was accomplished with the bindentity() function. This function is still available and may be used in conjunction with bind property exposure, but is considered depreciated and will not receive further updates.
bindentity(bound entity, target, offset_x , offset_z, offset_y, direction, animation_match); – Sets up a bind. Unlisted properties receive the following values:
- animation_frame: 0
- animation_id: 0
- config (flags enabled):
openborconstant("BIND_CONFIG_AXIS_X_TARGET")openborconstant("BIND_CONFIG_AXIS_Y_TARGET")openborconstant("BIND_CONFIG_AXIS_Z_TARGET")
- sort_id: -1
- tag: 0
bindentity(bound entity, NULL()); – Cancel a bind.
