https://sungreen.github.io/src/ext/constraints.js

1/**
2 * Copyright (C) 2014-2017 Triumph LLC
3 * 
4 * This program is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation, either version 3 of the License, or
7 * (at your option) any later version.
8 * 
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU General Public License for more details.
13 * 
14 * You should have received a copy of the GNU General Public License
15 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
16 */
17"use strict";
18
19/**
20 * Object constraints API. Please note that these constraints are not the same
21 * as those assigned in Blender.
22 * @module constraints
23 * @local StiffViewportPositioning
24 */
25b4w.module["constraints"] = function(exports, require) {
26
27var m_cam      = require("__camera");
28var m_cons     = require("__constraints");
29var m_phy      = require("__physics");
30var m_print    = require("__print");
31var m_trans    = require("__transform");
32
33/**
34 * An object that defines positioning for the stiff viewport constraint.
35 * @typedef {Object} StiffViewportPositioning
36 * @property {number} [left] Offset from the left edge of the camera's viewport
37 * @property {number} [right] Offset from the right edge of the camera's viewport
38 * @property {number} [top] Offset from the top edge of the camera's viewport
39 * @property {number} [bottom] Offset from the bottom edge of the camera's viewport
40 * @property {number} distance Distance from the camera
41 * @property {Quat} [rotation] Rotation offset
42 * @property {string} [hor_units="widths"] Left/Right offset units: "heights" or "widths"
43 * @property {string} [vert_units="heights"] Top/Bottom offset units: "heights" or "widths"
44 * @cc_externs left right top bottom distance rotation hor_units vert_units
45 */
46
47/**
48 * Attach the object to the other object or to the armature bone using a
49 * stiff constraint. The child object will move, rotate and scale
50 * together with its parent. Examples: a sword is parented to the
51 * character's hand; the character is sitting in a vehicle.
52 *
53 * @method module:constraints.append_stiff
54 * @param {Object3D} obj Constrained object
55 * @param {(Object3D|Array)} target Target object or [Armature object, Bone Name]
56 * @param {Vec3} offset Offset, in the parent's local space.
57 * @param {Quat} [rotation_offset=null] Rotation offset, in the
58 * parent's local space.
59 * @param {number} [scale_offset=1] Scale offset, in the parent's local space.
60 */
61exports.append_stiff = function(obj, target, offset, rotation_offset,
62        scale_offset) {
63
64    scale_offset = scale_offset || 1;
65
66    if (target instanceof Array && target.length == 2)
67        m_cons.append_stiff_bone(obj, target[0], target[1], offset,
68                rotation_offset, scale_offset);
69    else
70        m_cons.append_stiff_obj(obj, target, offset, rotation_offset,
71                scale_offset);
72
73    m_trans.update_transform(obj);
74    m_phy.sync_transform(obj);
75}
76
77/**
78 * Attach the object to the other object using a
79 * semi-stiff constraint. The child object will move and rotate together with
80 * its parent, but it will be still possible to rotate it independently
81 * in the parent's local space. Example: a tank turret.
82 *
83 * @method module:constraints.append_semi_stiff
84 * @param {Object3D} obj Constrained object
85 * @param {Object3D} target Target object
86 * @param {Vec3} offset Offset, in the parent's local space
87 * @param {Quat} [rotation_offset] Initial rotation offset, in the
88 * parent's local space
89 */
90exports.append_semi_stiff = function(obj, target, offset, rotation_offset) {
91    m_cons.append_semi_stiff_obj(obj, target, offset, rotation_offset);
92
93    m_trans.update_transform(obj);
94    m_phy.sync_transform(obj);
95}
96
97/**
98 * Attach the EYE camera to the object using a
99 * semi-stiff constraint. Also apply rotation limits to the camera.
100 * The camera will move and rotate together with
101 * its parent, but it will be still possible to rotate it independently
102 * in the parent's local space. The camera's UP vector will be preserved.
103 * Example: first-person vehicle view.
104 *
105 * @see https://www.blend4web.com/doc/en/camera.html#api
106 * @method module:constraints.append_semi_stiff_cam
107 * @param {Object3D} obj Constrained object
108 * @param {Object3D} target Target object
109 * @param {Vec3} offset Offset, in the parent's local space
110 * @param {Quat} [rotation_offset] Initial rotation offset, in the
111 * parent's local space
112 * @param {number} [clamp_left] Left camera rotation limit, in radians
113 * @param {number} [clamp_right] Right camera rotation limit, in radians
114 * @param {number} [clamp_up] Upward camera rotation limit, in radians
115 * @param {number} [clamp_down] Downward camera rotation limit, in radians
116 */
117exports.append_semi_stiff_cam = function(obj, target, offset, rotation_offset,
118                                            clamp_left, clamp_right,
119                                            clamp_up, clamp_down) {
120    if (!m_cam.is_eye_camera(obj)) {
121        m_print.error("append_semi_stiff_cam(): wrong object type, only EYE" +
122            " camera objects can be parented.");
123        return;
124    }
125
126    clamp_left  = clamp_left  || -Math.PI / 2;
127    clamp_right = clamp_right ||  Math.PI / 2;
128    clamp_up    = clamp_up    ||  Math.PI / 2;
129    clamp_down  = clamp_down  || -Math.PI / 2;
130
131    m_cons.append_semi_stiff_cam_obj(obj, target, offset, rotation_offset,
132                                          clamp_left, clamp_right,
133                                          clamp_up, clamp_down);
134    m_trans.update_transform(obj);
135    m_phy.sync_transform(obj);
136}
137
138/**
139 * Attach the EYE camera to the object using a
140 * semi-soft constraint. The camera will smoothly follow the object's rear.
141 * Example: third-person character or vehicle views.
142 *
143 * @method module:constraints.append_semi_soft_cam
144 * @param {Object3D} obj Constrained object
145 * @param {Object3D} target Target object
146 * @param {Vec3} offset Offset, in the parent's local space
147 * @param {number} [softness=0.25] Camera smoothness ratio
148 */
149exports.append_semi_soft_cam = function(obj, target, offset, softness) {
150
151    if (!m_cam.is_eye_camera(obj)) {
152        m_print.error("append_semi_soft_cam(): wrong object type, only EYE" +
153            " camera objects can be parented.");
154        return;
155    }
156
157    if (!softness || softness < 0)
158        softness = 0.25;
159
160    m_cons.append_semi_soft_cam_obj(obj, target, offset, softness);
161
162    m_trans.update_transform(obj);
163    m_phy.sync_transform(obj);
164}
165
166/**
167 * Attach the object to the other object using a
168 * stiff translation constraint. The child object will move together with
169 * its parent, but will not rotate. It will be still possible to rotate it
170 * independently from the parent.
171 *
172 * Example: attaching the camera to the physics character in order to
173 * implement the first-person character view. Another example: the character
174 * jumps in water and splashes' particle emitter is attached to the
175 * first-person camera using this constraint - the bubbles will follow the
176 * character but will not be rotated with the camera.
177 *
178 * @method module:constraints.append_stiff_trans
179 * @param {Object3D} obj Constrained object
180 * @param {Object3D} target Target object
181 * @param {Vec3} offset Offset, in the parent's local space
182 */
183exports.append_stiff_trans = function(obj, target, offset) {
184    m_cons.append_stiff_trans_obj(obj, target, offset);
185
186    m_trans.update_transform(obj);
187    m_phy.sync_transform(obj);
188}
189
190/**
191 * Attach the object to the other object using a copy translation constraint.
192 * The child object will move together with its parent, but will not rotate.
193 * Note that the offset is specified in the world space.
194 * Example: a light source attached to the character.
195 *
196 * @method module:constraints.append_copy_trans
197 * @param {Object3D} obj Constrained object
198 * @param {Object3D} target Target object
199 * @param {Vec3} offset Offset, in the parent's world space
200 */
201exports.append_copy_trans = function(obj, target, offset) {
202    m_cons.append_copy_trans_obj(obj, target, offset);
203
204    m_trans.update_transform(obj);
205    m_phy.sync_transform(obj);
206}
207
208/**
209 * Attach the object to the other object using a
210 * stiff translation/rotation constraint. The child object will move and rotate
211 * together with its parent, but will not scale. It will be still possible to
212 * scale it independently from the parent.
213 *
214 * Example: smoke emitter attached to the tractor pipe; exhaustion effects
215 * are achieved by scaling the emitter.
216 *
217 * @method module:constraints.append_stiff_trans_rot
218 * @param {Object3D} obj Constrained object
219 * @param {Object3D} target Target object
220 * @param {Vec3} offset Offset, in the parent's local space
221 * @param {Quat} [rotation_offset] Rotation offset, in
222 * the parent's local space
223 */
224exports.append_stiff_trans_rot = function(obj, target, offset, rotation_offset) {
225    m_cons.append_stiff_trans_rot_obj(obj, target, offset, rotation_offset, 1.0);
226
227    m_trans.update_transform(obj);
228    m_phy.sync_transform(obj);
229}
230
231/**
232 * Make the object "looking" at the target object or the position. The object's
233 * facing direction is considered to be the -Z axis that is vertically
234 * downwards.
235 *
236 * Example: a spot light which is tracking the character; both objects can be
237 * moved via API or animated.
238 *
239 * @method module:constraints.append_track
240 * @param {Object3D} obj Constrained object
241 * @param {(Object3D|Vec3)} target Target object or position vector
242 */
243exports.append_track = function(obj, target) {
244    if (target.length == 3)
245        m_cons.append_track_point(obj, target);
246    else
247        m_cons.append_track_obj(obj, target);
248
249    m_trans.update_transform(obj);
250    m_phy.sync_transform(obj);
251}
252
253/**
254 * Attach the object to the other object using a follow constraint. The child
255 * object will track and follow its parent position.
256 *
257 * Example: a follow-style camera view for the character.
258 *
259 * @method module:constraints.append_follow
260 * @param {Object3D} obj Constrained object
261 * @param {(Object3D|Vec3)} target Target object or position vector
262 * @param {number} dist_min Minimum distance
263 * @param {number} dist_max Maximum distance
264 */
265exports.append_follow = function(obj, target, dist_min, dist_max) {
266
267    if (target.length == 3)
268        m_cons.append_follow_point(obj, target, dist_min, dist_max);
269    else
270        m_cons.append_follow_obj(obj, target, dist_min, dist_max);
271
272    m_trans.update_transform(obj);
273    m_phy.sync_transform(obj);
274}
275
276/**
277 * Attach the object to the camera using a stiff viewport constraint, so
278 * the child object will preserve its orientation in the camera viewport.
279 * This constraint is used to create onscreen 2D/3D user interfaces.
280 * @method module:constraints.append_stiff_viewport
281 * @param {Object3D} obj Constrained object
282 * @param {Object3D} camobj Camera object
283 * @param {StiffViewportPositioning} positioning Positioning
284 */
285exports.append_stiff_viewport = function(obj, camobj, positioning) {
286    m_cons.append_stiff_viewport(obj, camobj, positioning);
287
288    m_trans.update_transform(obj);
289    m_phy.sync_transform(obj);
290}
291
292/**
293 * Remove the object's constraint (if any).
294 * @method module:constraints.remove
295 * @param {Object3D} obj Constrained object
296 */
297exports.remove = function(obj) {
298    if (obj.constraint)
299        m_cons.remove(obj);
300}
301
302}