Module: constraints

Object constraints API.

Summary

Methods

Type Definitions

Detailed Description

Methods

append_copy_trans(obj, target, offset)

Attach the object to the other object using a copy translation constraint. The child object will move together with its parent, but will not rotate. Note that the offset is specified in the world space. Example: a light source attached to the character.
Parameters:
Name Type Description
obj Object3D Constrained object
target Object3D Target object
offset Vec3 Offset, in the parent's world space
Source:

append_follow(obj, target, dist_min, dist_max)

Attach the object to the other object using a follow constraint. The child object will track and follow its parent position. Example: a follow-style camera view for the character.
Parameters:
Name Type Description
obj Object3D Constrained object
target Object3D | Vec3 Target object or position vector
dist_min Number Minimum distance
dist_max Number Maximum distance
Source:

append_semi_soft_cam(obj, target, offset, softnessopt)

Attach the EYE camera to the object using a semi-soft constraint. The camera will smoothly follow the object's rear. Example: third-person character or vehicle views.
Parameters:
Name Type Attributes Default Description
obj Object3D Constrained object
target Object3D Target object
offset Vec3 Offset, in the parent's local space
softness Number <optional>
0.25 Camera smoothness ratio
Source:

append_semi_stiff(obj, target, offset, rotation_offsetopt)

Attach the object to the other object using a semi-stiff constraint. The child object will move and rotate together with its parent, but it will be still possible to rotate it independently in the parent's local space. Example: a tank turret.
Parameters:
Name Type Attributes Description
obj Object3D Constrained object
target Object3D Target object
offset Vec3 Offset, in the parent's local space
rotation_offset Quat <optional>
Initial rotation offset, in the parent's local space
Source:

append_semi_stiff_cam(obj, target, offset, rotation_offsetopt, clamp_leftopt, clamp_rightopt, clamp_upopt, clamp_downopt)

Attach the EYE camera to the object using a semi-stiff constraint. Also apply rotation limits to the camera. The camera will move and rotate together with its parent, but it will be still possible to rotate it independently in the parent's local space. The camera's UP vector will be preserved. Example: first-person vehicle view.
Parameters:
Name Type Attributes Description
obj Object3D Constrained object
target Object3D Target object
offset Vec3 Offset, in the parent's local space
rotation_offset Quat <optional>
Initial rotation offset, in the parent's local space
clamp_left Number <optional>
Left camera rotation limit, in radians
clamp_right Number <optional>
Right camera rotation limit, in radians
clamp_up Number <optional>
Upward camera rotation limit, in radians
clamp_down Number <optional>
Downward camera rotation limit, in radians
Source:
See:

append_stiff(obj, target, offset, rotation_offsetopt, scale_offsetopt)

Attach the object to the other object or to the armature bone using a stiff constraint. The child object will move, rotate and scale together with its parent. Examples: a sword is parented to the character's hand; the character is sitting in a vehicle.
Parameters:
Name Type Attributes Default Description
obj Object3D Constrained object
target Object3D | Array Target object or [Armature object, Bone Name]
offset Vec3 Offset, in the parent's local space.
rotation_offset Quat <optional>
null Rotation offset, in the parent's local space.
scale_offset Number <optional>
1 Scale offset, in the parent's local space.
Source:

append_stiff_trans(obj, target, offset)

Attach the object to the other object using a stiff translation constraint. The child object will move together with its parent, but will not rotate. It will be still possible to rotate it independently from the parent. Example: attaching the camera to the physics character in order to implement the first-person character view. Another example: the character jumps in water and splashes' particle emitter is attached to the first-person camera using this constraint - the bubbles will follow the character but will not be rotated with the camera.
Parameters:
Name Type Description
obj Object3D Constrained object
target Object3D Target object
offset Vec3 Offset, in the parent's local space
Source:

append_stiff_trans_rot(obj, target, offset, rotation_offsetopt)

Attach the object to the other object using a stiff translation/rotation constraint. The child object will move and rotate together with its parent, but will not scale. It will be still possible to scale it independently from the parent. Example: smoke emitter attached to the tractor pipe; exhaustion effects are achieved by scaling the emitter.
Parameters:
Name Type Attributes Description
obj Object3D Constrained object
target Object3D Target object
offset Vec3 Offset, in the parent's local space
rotation_offset Quat <optional>
Rotation offset, in the parent's local space
Source:

append_stiff_viewport(obj, camobj, positioning)

Attach the object to the camera using a stiff vieport constraint, so the child object will preserve its orientation in the camera viewport. This constraint is used to create onscreen 2D/3D user interfaces.
Parameters:
Name Type Description
obj Object3D Constrained object
camobj Object3D Camera object
positioning StiffViewportPositioning Positioning
Source:

append_track(obj, target)

Make the object "looking" at the target object or the position. The object's facing direction is considered to be the -Z axis that is vertically downwards. Example: a spot light which is tracking the character; both objects can be moved via API or animated.
Parameters:
Name Type Description
obj Object3D Constrained object
target Object3D | Vec3 Target object or position vector
Source:

get_parent(obj) → (nullable) {Object3D}

Get object's parent object.
Parameters:
Name Type Description
obj Object3D Object
Returns:
Parent object
Type
Object3D
Deprecated:
Source:

remove(obj)

Remove the object's constraint (if any).
Parameters:
Name Type Description
obj Object3D Constrained object
Source:

Type Definitions

StiffViewportPositioning

An object that defines positioning for the stiff viewport constraint.
Type:
  • Object
Properties:
Name Type Attributes Default Description
left Number <optional>
Offset from the left edge of the camera's viewport
right Number <optional>
Offset from the right edge of the camera's viewport
top Number <optional>
Offset from the top edge of the camera's viewport
bottom Number <optional>
Offset from the bottom edge of the camera's viewport
distance Number Distance from the camera
rotation Quat <optional>
Rotation offset
hor_units String <optional>
"widths" Left/Right offset units: "heights" or "widths"
vert_units String <optional>
"heights" Top/Bottom offset units: "heights" or "widths"
Source: