Module: constraints

Object constraints API. Please note that these constraints are not the same as those assigned in Blender.
Source:

Summary

Methods

Type Definitions

Detailed Description

Methods

append_copy_loc(obj, target, axesopt, use_offsetopt, influenceopt)

Attach the object to the other object using a copy location constraint. The child object will move together with its parent, but will not rotate. Note that the offset is the object's location in the world space.

This method works similarly to the Copy Location constraint in Blender.

Parameters:
Name Type Attributes Default Description
obj Object3D Constrained object
target Object3D Target object
axes string <optional>
 'XYZ' Copy the target's location
use_offset boolean <optional>
 false Add original location into copied location
influence number <optional>
 1 Amount of influence constraint will have on the final solution
Source:
Example
var m_scene = require("scenes");
var m_const = require("constraints");

var my_cube = m_scene.get_object_by_name("cube");
var my_sphere = m_scene.get_object_by_name("Icosphere");

m_const.append_copy_loc(my_sphere, my_cube, 'XYZ', false, 0.5);

append_copy_rot(obj, target, axesopt, use_offsetopt, influenceopt)

Attach the object to the other object using a copy rotation constraint. The child object will rotate together with its parent, but will not move. Note that the offset is the object's rotation in the world space.

This method works similarly to the Copy Rotation constraint in Blender.

Parameters:
Name Type Attributes Default Description
obj Object3D Constrained object
target Object3D Target object
axes string <optional>
 'XYZ' Copy the target's location
use_offset boolean <optional>
 false Add original location into copied location
influence number <optional>
 1 Amount of influence constraint will have on the final solution
Source:
Example
var m_scene = require("scenes");
var m_const = require("constraints");

var my_cube = m_scene.get_object_by_name("cube");
var my_sphere = m_scene.get_object_by_name("Icosphere");

m_const.append_copy_rot(my_sphere, my_cube, 'XYZ', 0.5);

append_copy_trans(obj, target, influenceopt)

Attach the object to the other object using a copy transforms constraint. The child object will move and rotate together with its parent.

This method works similarly to the Copy Transforms constraint in Blender.

Parameters:
Name Type Attributes Default Description
obj Object3D Constrained object
target Object3D Target object
influence number <optional>
 1 Amount of influence constraint will have on the final solution
Source:
Example
var m_scene = require("scenes");
var m_const = require("constraints");

var my_cube = m_scene.get_object_by_name("cube");
var my_sphere = m_scene.get_object_by_name("Icosphere");

m_const.append_copy_trans(my_sphere, my_cube, 0.5);

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.

This method works similarly to the Limit Distance constraint in Blender, but, unlike it, does not set a precise distance.

Example: a follow-style camera view for the character.
Parameters:
Name Type Description
obj Object3D Constrained object
target Object3D Target object
dist_min number Minimum distance
dist_max number Maximum distance
Source:
Example
var m_scene = require("scenes");
var m_const = require("constraints");

var my_cube = m_scene.get_object_by_name("cube");
var my_camera = m_scene.get_object_by_name("Camera");

m_const.append_follow(my_camera, my_cube, 2.0, 4.0);

append_semi_soft(obj, target, offsetopt, softnessopt)

Attach one object to another one using a semi-soft constraint. The object 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 <optional>
 Offset, in the parent's local space
softness number <optional>
 0.25 Object smoothness ratio
Source:
Example
var m_scene = require("scenes");
var m_const = require("constraints");

var my_offset_vector = new Float32Array([2.0, 2.0, 2.0]);

var my_cube = m_scene.get_object_by_name("cube");
var my_sphere = m_scene.get_object_by_name("Icosphere");

m_const.append_semi_soft(my_sphere, my_cube, my_offset_vector, 0.5);

append_semi_soft_cam(obj, target, offsetopt, 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 <optional>
 Offset, in the parent's local space
softness number <optional>
 0.25 Camera smoothness ratio
Deprecated since 17.06:
Source:

append_semi_stiff(obj, target, offsetopt, rotation_offsetopt, clamp_leftopt, clamp_rightopt, clamp_upopt, clamp_downopt)

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 <optional>
 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 object rotation limit, in radians
clamp_right number <optional>
 Right object rotation limit, in radians
clamp_up number <optional>
 Upward object rotation limit, in radians
clamp_down number <optional>
 Downward object rotation limit, in radians
Source:
Example
var m_scene = require("scenes");
var m_const = require("constraints");

var my_offset_vector = new Float32Array([2.0, 2.0, 2.0]);

var my_cube = m_scene.get_object_by_name("cube");
var my_sphere = m_scene.get_object_by_name("Icosphere");

m_const.append_semi_stiff(my_sphere, my_cube, my_offset_vector);

append_semi_stiff_cam(obj, target, offsetopt, 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 <optional>
 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
Deprecated since 17.06:
Source:
See:

append_stiff(obj, target, offsetopt, 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 <optional>
 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:
Example
var m_scene = require("scenes");
var m_const = require("constraints");

var my_offset_vector = new Float32Array([2.0, 2.0, 2.0]);

var my_cube = m_scene.get_object_by_name("cube");
var my_sphere = m_scene.get_object_by_name("Icosphere");

m_const.append_stiff(my_sphere, my_cube, my_offset_vector);

append_stiff_trans(obj, target, offsetopt)

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 Attributes Description
obj Object3D Constrained object
target Object3D Target object
offset Vec3 <optional>
 Offset, in the parent's local space
Source:
Example
var m_scene = require("scenes");
var m_const = require("constraints");

var my_offset_vector = new Float32Array([-2.0, 2.0, 2.0]);

var my_cube = m_scene.get_object_by_name("cube");
var my_sphere_4 = m_scene.get_object_by_name("Icosphere");

m_const.append_stiff_trans(my_sphere, my_cube, my_offset_vector);

append_stiff_trans_rot(obj, target, offsetopt, 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 <optional>
 Offset, in the parent's local space
rotation_offset Quat <optional>
 Rotation offset, in the parent's local space
Source:
Example
var m_scene = require("scenes");
var m_const = require("constraints");

var my_sphere = m_scene.get_object_by_name("Icosphere");
var my_cube = m_scene.get_object_by_name("cube");

var my_offset_vector = new Float32Array([-2.0, 2.0, 2.0]);
m_const.append_stiff_trans_rot(my_sphere, my_cube, my_offset_vector);

append_stiff_viewport(obj, camobj, positioningopt)

Attach the object to the camera using a stiff viewport 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 Attributes Description
obj Object3D Constrained object
camobj Object3D Camera object
positioning StiffViewportPositioning <optional>
 Positioning
Source:
Example
var m_scene = require("scenes");
var m_const = require("constraints");

var sphere_1 = m_scene.get_object_by_name("Icosphere");
var my_camera = m_scene.get_object_by_name("Camera");

m_const.append_stiff_viewport(sphere_1, my_camera, { 
     left: 150,
     top: 100,
     distance: 1
 });

append_track(obj, target, track_axisopt, up_axisopt, use_target_zopt, influenceopt)

Make the object "looking" at the target object. Example: a spot light which is tracking the character; both objects can be moved via API or animated.

This method works in a similar way to the Track To constraint in Blender.

Parameters:
Name Type Attributes Default Description
obj Object3D Constrained object
target Object3D Target object
track_axis string <optional>
 'Y' Axis that points to the target object
up_axis string <optional>
 'Z' Axis that points upward
use_target_z boolean <optional>
 false Target's Z axis, not World Z axis, will constraint the Up direction
influence number <optional>
 1 Amount of influence constraint will have on the final solution
Source:
Example
var m_scene = require("scenes");
var m_const = require("constraints");

var my_cube = m_scene.get_object_by_name("cube");  
var my_camera = m_scene.get_object_by_name("Camera");

m_const.append_track(my_camera, my_cube, "-X", "Z");

remove(obj, restore_transformopt)

Remove the object's constraint (if any).
Parameters:
Name Type Attributes Default Description
obj Object3D Constrained object
restore_transform boolean <optional>
 false Restore default transform
Source:
Example
var m_scene = require("scenes");
var m_const = require("constraints");

var my_sphere = m_scene.get_object_by_name("Icosphere");

m_const.remove(my_sphere);

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 <optional>
 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: