Constraints
SixDOF Constraint
Nastaví každou relativní translaci a rotaci jako fixed, free nebo limited včetně per-axis friction a motorů.
SixDOF je nejflexibilnější managed joint. Použijte jej, když Fixed, Hinge, Slider, Cone ani SwingTwist nedokážou vyjádřit zamýšlený mechanismus. Jeho flexibilita vyžaduje přesně definovaný frame, osy a jednotky.
Syntaxe#
jolt_sixdof(body_a, body_b, anchor_x, anchor_y, anchor_z, options=undefined)Frame a obecné options#
| Pole | Výchozí | Popis |
|---|---|---|
| axis_x | {x:1,y:0,z:0} | Konečná nenulová world-space frame X axis. |
| axis_y | {x:0,y:1,z:0} | Konečná nenulová world-space frame Y axis, která není rovnoběžná s X. |
| swing_type | JOLT_SIXDOF_SWING_CONE | CONE pro eliptický symetrický swing nebo PYRAMID pro asymetrický Y/Z swing. |
| collision | false | Zda připojená tělesa mohou kolidovat. |
| enabled | true | Počáteční stav solveru. |
| friction | nenastaveno | Pole až šesti nezáporných per-axis force/torque limitů. |
Options os#
| Pole | Osa | Přijímaná hodnota |
|---|---|---|
| linear_x / linear_y / linear_z | Translation X/Y/Z | JOLT_SIXDOF_FIXED, JOLT_SIXDOF_FREE, 'fixed', 'locked', 'free' nebo {min,max} ve world units. |
| angular_x | Rotation X / twist | Fixed, free nebo {min,max} ve stupních uvnitř -180..180. |
| angular_y / angular_z | Coupled swing | Fixed, free nebo {min,max} ve stupních uvnitř -180..180. |
Konstanty#
| Konstanty | Hodnoty / význam |
|---|---|
| JOLT_SIXDOF_TRANSLATION_X / Y / Z | 0 / 1 / 2 |
| JOLT_SIXDOF_ROTATION_X / Y / Z | 3 / 4 / 5 |
| JOLT_SIXDOF_FIXED / FREE / LIMITED | 0 / 1 / 2 |
| JOLT_SIXDOF_SWING_CONE / PYRAMID | Symetrický eliptický swing / asymetrický pyramid swing |
Metody os#
| Skupina | Metody |
|---|---|
| Režim | set_axis_free(), set_axis_fixed(), set_axis_limit(), get_axis_mode(), is_axis_free(), is_axis_fixed() |
| Limity | get_axis_min(), get_axis_max(), get_axis_limit() |
| Translation shortcuts | set_translation_limits(), get_translation_limits_min(), get_translation_limits_max() |
| Rotation shortcuts | set_rotation_limits(), get_rotation_limits_min(), get_rotation_limits_max() |
| Friction | set_friction(axis,value), get_friction(axis) |
Význam rotací#
- Rotation X je Jolt twist. Rotation Y a Z jsou coupled swing rozměry, nikoli samostatné Euler clamps.
- CONE swing vyžaduje limited Y/Z ranges symetrické kolem nuly a tvoří eliptický kužel.
- PYRAMID dovoluje asymetrické Y/Z ranges.
- Lineární hodnoty používají world units; high-level angular limits a angular velocities používají stupně.
Metody motoru#
| Metoda | Účel |
|---|---|
| set_axis_motor_state(axis,state) / get_axis_motor_state(axis) | Vybere Off, Velocity, Position nebo PositionAndVelocity pro jednu osu. |
| set_target_position(x,y,z) / get_target_position() | Translation position target v body-1 constraint space. |
| set_target_velocity(x,y,z) / get_target_velocity() | Translation velocity target v body-1 constraint space. |
| set_target_angular_velocity(x,y,z) / get_target_angular_velocity() | Angular velocity target ve stupních/s; v Jolt 5.6 používá body-2 constraint space. |
| set_target_orientation(x,y,z,w) | Autoritativní normalized quaternion orientation target. |
| set_target_orientation_euler(x,y,z) | Convenience převod stupňů na target quaternion. |
| get_target_orientation() / get_current_orientation() | Target a aktuální constraint-space quaterniony. |
| get_target_orientation_euler() / get_current_orientation_euler() | Convenience Euler reprezentace. |
| set_axis_motor_limit(axis,value) / get_axis_motor_limit(axis) | Force limit pro translaci nebo torque limit pro rotaci. |
| set_axis_motor_spring(axis,frequency,damping) | Per-axis native pružina position motoru. |
| get_axis_motor_spring(axis) | Vrací {frequency,damping} pro zvolenou SixDOF osu. Použijte živý SixDOF constraint a osu JOLT_SIXDOF_*; při chybě čtení ihned ověřte native chybový kanál. |
Soft limits a solver state#
| Metoda | Výsledek |
|---|---|
| set_limit_spring(axis, frequency, damping) | Změkčí pouze Translation X/Y/Z limity. |
| get_limit_spring(axis) | Vrátí {frequency,damping}. |
| get_impulses() | Vrátí translation, rotation, motor_translation a motor_rotation vektory. |
| get_sixdof_debug_frame() | Vrátí live constraint frame používaný diagnostikou. |
Příklad: Slider-like pohyb Z#
var joint = jolt_sixdof(body_a, body_b, 0, 0, 2, {
linear_z: { min:0, max:3 },
collision: false
});Příklad: poháněná translation axis#
joint.set_axis_free(JOLT_SIXDOF_TRANSLATION_X);
joint.set_axis_motor_limit(JOLT_SIXDOF_TRANSLATION_X, 120);
joint.set_axis_motor_spring(JOLT_SIXDOF_TRANSLATION_X, 3, 0.8);
joint.set_target_position(2, 0, 0);
joint.set_axis_motor_state(JOLT_SIXDOF_TRANSLATION_X, JOLT_MOTOR_POSITION);Validace a životní cyklus#
- Creator vyžaduje dvě různá živá tělesa, konečný anchor a dvě konečné, nenulové a nerovnoběžné frame axes.
- Každá limited axis potřebuje konečné seřazené min/max; angular hodnoty musí zůstat uvnitř -180..180 stupňů.
- Per-axis friction je force pro translace a torque pro rotace.
- Runtime změny probouzejí připojená tělesa; getters nikoli.
- Zničení tělesa zneplatní constraint. destroy() i jolt_stop() jsou bezpečné a správně seřazené.
- jolt_sixdof_world() convenience creator zatím neexistuje.
Ověřené kontrakty operací#
Následující kontrakty rozlišují jednotky, návratové hodnoty, chyby a životnost podle aktuální implementace. Nevynechávej kontrolu výsledku: false, 0 a undefined mohou mít u různých metod odlišný význam.
| Symbol / vlastník | Signatura | Kontrakt operace |
|---|---|---|
| jolt_sixdof | jolt_sixdof(body_a,body_b,anchor_x,anchor_y,anchor_z,options=undefined) | Dvě tělesa, světová kotva, axis_x/y default+X/+Y. Všech6 os default FIXED; linear_x/y/z m, angular_x/y/z°: FIXED/FREE nebo {min, max}. CONE default vyžaduje symetrii swing Y/Z, PYRAMID dovolí asymetrii. Collisionfalse, enabledtrue; Constraint/undefined. |
| JoltConstraint.get_axis_limit | JoltConstraint.get_axis_limit(axis) | SixDOF axis 0..5; min/max v m pro posuv, ° pro rotaci. get_axis_limit vrací {mode, minimum, maximum}. Chybové náhrady jsou FIXED/0/0; ověř platnost a chybový stav. |
| JoltConstraint.get_axis_max | JoltConstraint.get_axis_max(axis) | SixDOF axis 0..5; min/max v m pro posuv, ° pro rotaci. get_axis_limit vrací {mode, minimum, maximum}. Chybové náhrady jsou FIXED/0/0; ověř platnost a chybový stav. |
| JoltConstraint.get_axis_min | JoltConstraint.get_axis_min(axis) | SixDOF axis 0..5; min/max v m pro posuv, ° pro rotaci. get_axis_limit vrací {mode, minimum, maximum}. Chybové náhrady jsou FIXED/0/0; ověř platnost a chybový stav. |
| JoltConstraint.get_axis_mode | JoltConstraint.get_axis_mode(axis) | SixDOF axis 0..5. Režim FREE/FIXED/LIMITED nebo Boolean porovnání; při chybě get_axis_mode vrací FIXED, takže is_axis_fixed může být true i při chybě. |
| JoltConstraint.get_axis_motor_limit | JoltConstraint.get_axis_motor_limit(axis) | SixDOF axis 0..5; N pro posuv, N·m pro rotaci; 0 při neplatném wrapperu/typu, nativní chybu čti zvlášť. |
| JoltConstraint.get_axis_motor_spring | JoltConstraint.get_axis_motor_spring(axis) | SixDOF: {frequency, damping}, Hz a poměr. Motor osy 0..5, limit pouze 0..2; při chybě mohou složky obsahovat nativní náhradní 0. |
| JoltConstraint.get_axis_motor_state | JoltConstraint.get_axis_motor_state(axis) | SixDOF axis 0..5, stav JOLT_MOTOR_*. Setter Boolean; getter číselný režim nebo OFF při neplatném wrapperu/typu. |
| JoltConstraint.is_axis_fixed | JoltConstraint.is_axis_fixed(axis) | SixDOF axis 0..5. Režim FREE/FIXED/LIMITED nebo Boolean porovnání; při chybě get_axis_mode vrací FIXED, takže is_axis_fixed může být true i při chybě. |
| JoltConstraint.is_axis_free | JoltConstraint.is_axis_free(axis) | SixDOF axis 0..5. Režim FREE/FIXED/LIMITED nebo Boolean porovnání; při chybě get_axis_mode vrací FIXED, takže is_axis_fixed může být true i při chybě. |
| JoltConstraint.set_axis_fixed | JoltConstraint.set_axis_fixed(axis) | Pouze SixDOF, celé axis 0..5 (posuv X/Y/Z, rotace X/Y/Z). Boolean; fixed uzamkne na 0, free odstraní limit. |
| JoltConstraint.set_axis_free | JoltConstraint.set_axis_free(axis) | Pouze SixDOF, celé axis 0..5 (posuv X/Y/Z, rotace X/Y/Z). Boolean; fixed uzamkne na 0, free odstraní limit. |
| JoltConstraint.set_axis_limit | JoltConstraint.set_axis_limit(axis,minimum,maximum) | SixDOF, celé axis 0..5; konečné min≤max. Posuv v m, rotace v -180..180°. Cone swing typ vyžaduje symetrické Y/Z rotační meze kolem 0. Boolean. |
| JoltConstraint.set_axis_motor_limit | JoltConstraint.set_axis_motor_limit(axis,value) | SixDOF axis 0..5; konečný nezáporný limit síly (osy 0..2, N) nebo momentu (3..5, N·m). Boolean. Nastavení limitu samo motor nezapne. |
| JoltConstraint.set_axis_motor_spring | JoltConstraint.set_axis_motor_spring(axis,frequency,damping) | SixDOF axis 0..5; konečné frequency ≥0 Hz a damping ≥0 jako poměr tlumení. Boolean. |
| JoltConstraint.set_axis_motor_state | JoltConstraint.set_axis_motor_state(axis,state) | SixDOF axis 0..5, stav JOLT_MOTOR_*. Setter Boolean; getter číselný režim nebo OFF při neplatném wrapperu/typu. |