Merge pull request #24 from LeXXik/docs

Docs - Constraint Component System

src/index.mjs

@@ -19,8 +19,17 @@ export { CharComponentSystem } from './physics/jolt/front/char/system.mjs';
 export { SoftBodyComponent } from './physics/jolt/front/softbody/component.mjs';
 export { SoftBodyComponentSystem } from './physics/jolt/front/softbody/system.mjs';
 
-export { CommandsBuffer } from './physics/jolt/back/commands-buffer.mjs';
 
+export { ConstraintComponent } from './physics/jolt/front/constraint/component.mjs';
+export { ConstraintComponentSystem } from './physics/jolt/front/constraint/system.mjs';
+
+export { Constraint } from './physics/jolt/front/constraint/types/constraint.mjs';
+export {
+    SpringSettings, MotorSettings, ConstraintSettings, ConeConstraintSettings,
+    DistanceConstraintSettings, FixedConstraintSettings, HingeConstraintSettings,
+    PulleyConstraintSettings, SixDOFConstraintSettings, SwingTwistConstraintSettings,
+    SliderConstraintSettings
+} from './physics/jolt/front/constraint/types/settings.mjs';
 export { ConeConstraint } from './physics/jolt/front/constraint/types/cone.mjs';
 export { DistanceConstraint } from './physics/jolt/front/constraint/types/distance.mjs';
 export { FixedConstraint } from './physics/jolt/front/constraint/types/fixed.mjs';
@@ -31,6 +40,9 @@ export { SixDOFConstraint } from './physics/jolt/front/constraint/types/six-dof.
 export { SliderConstraint } from './physics/jolt/front/constraint/types/slider.mjs';
 export { SwingTwistConstraint } from './physics/jolt/front/constraint/types/swing-twist.mjs';
 
+export { CommandsBuffer } from './physics/jolt/back/commands-buffer.mjs';
+export { IndexedCache } from './physics/indexed-cache.mjs';
+
 export * from './physics/jolt/constants.mjs';
 
 export { init };

src/physics/indexed-cache.mjs

@@ -3,7 +3,7 @@
  * callback function to be called, once we get the result from the physics backend.
  * Indices can be freed and re-used.
  *
- * @hidden
+ * @group Utilities
  */
 class IndexedCache {
     constructor() {

src/physics/jolt/back/operators/helpers/constraint-modifier.mjs

@@ -8,12 +8,11 @@ import {
     CMD_JNT_SDF_SET_R_LIMITS, CMD_JNT_SDF_SET_SPRING_S, CMD_JNT_SDF_SET_T_ANG_VEL_CS,
     CMD_JNT_SDF_SET_T_LIMITS, CMD_JNT_SDF_SET_T_POS_CS, CMD_JNT_SDF_SET_T_ROT_BS,
     CMD_JNT_SDF_SET_T_ROT_CS, CMD_JNT_SDF_SET_T_VEL_CS, CMD_JNT_SET_ENABLED,
-    CMD_JNT_ST_SET_M_F_TORQUE,
-    CMD_JNT_ST_SET_N_H_C_ANGLE, CMD_JNT_ST_SET_P_H_C_ANGLE, CMD_JNT_ST_SET_SWING_M_S,
-    CMD_JNT_ST_SET_TWIST_M_S, CMD_JNT_ST_SET_T_ANG_VEL_CS, CMD_JNT_ST_SET_T_MAX_ANGLE,
-    CMD_JNT_ST_SET_T_MIN_ANGLE, CMD_JNT_ST_SET_T_O_BS, CMD_JNT_ST_SET_T_O_CS, CMD_JNT_S_SET_LIMITS,
-    CMD_JNT_S_SET_M_F_FORCE, CMD_JNT_S_SET_M_STATE, CMD_JNT_S_SET_SPRING_S, CMD_JNT_S_SET_T_POS,
-    CMD_JNT_S_SET_T_VEL
+    CMD_JNT_ST_SET_M_F_TORQUE, CMD_JNT_ST_SET_N_H_C_ANGLE, CMD_JNT_ST_SET_P_H_C_ANGLE,
+    CMD_JNT_ST_SET_SWING_M_S, CMD_JNT_ST_SET_TWIST_M_S, CMD_JNT_ST_SET_T_ANG_VEL_CS,
+    CMD_JNT_ST_SET_T_MAX_ANGLE, CMD_JNT_ST_SET_T_MIN_ANGLE, CMD_JNT_ST_SET_T_O_BS,
+    CMD_JNT_ST_SET_T_O_CS, CMD_JNT_S_SET_LIMITS, CMD_JNT_S_SET_M_F_FORCE, CMD_JNT_S_SET_M_STATE,
+    CMD_JNT_S_SET_SPRING_S, CMD_JNT_S_SET_T_POS, CMD_JNT_S_SET_T_VEL
 } from '../../../constants.mjs';
 
 class ConstraintModifier {

src/physics/jolt/back/utils.mjs

@@ -42,6 +42,8 @@ function setSixDOFAxes(cb, settings, type, Jolt, isLimited) {
         const min = isLimited ? cb.read(BUFFER_READ_FLOAT32) : null;
         const max = isLimited ? cb.read(BUFFER_READ_FLOAT32) : null;
 
+        // TODO
+        // Fix this. Fixed and Free methods don't need scalars for value. Only axis.
         switch (axis) {
             case CONSTRAINT_SIX_DOF_TRANSLATION_X:
                 settings[type](Jolt.SixDOFConstraintSettings_EAxis_TranslationX, min, max);

src/physics/jolt/front/constraint/component.mjs

@@ -15,9 +15,61 @@ import {
     CONSTRAINT_TYPE_SIX_DOF, CONSTRAINT_TYPE_SLIDER, CONSTRAINT_TYPE_SWING_TWIST
 } from '../../constants.mjs';
 
+/**
+ * Constraint Component. Allows to add one or multiple constraints to an entity with a
+ * {@link BodyComponent | Body Component}.
+ *
+ * @category Constraint Component
+ */
 class ConstraintComponent extends Component {
     _list = new Set();
 
+    /**
+     * Adds a joint to this entity. Following enum aliases available:
+     * ```
+     * CONSTRAINT_TYPE_FIXED
+     * ```
+     * ```
+     * CONSTRAINT_TYPE_POINT
+     * ```
+     * ```
+     * CONSTRAINT_TYPE_DISTANCE
+     * ```
+     * ```
+     * CONSTRAINT_TYPE_HINGE
+     * ```
+     * ```
+     * CONSTRAINT_TYPE_SLIDER
+     * ```
+     * ```
+     * CONSTRAINT_TYPE_CONE
+     * ```
+     * ```
+     * CONSTRAINT_TYPE_SIX_DOF
+     * ```
+     * ```
+     * CONSTRAINT_TYPE_SWING_TWIST
+     * ```
+     * ```
+     * CONSTRAINT_TYPE_PULLEY
+     * ```
+     *
+     * @param {number} type - Enum alias, representing joint type.
+     * @param {import('playcanvas').Entity} otherEntity - The other entity that this entity will be
+     * connected to with this joint.
+     * @param {import('./types/settings.mjs').ConstraintSettings |
+     * import('./types/settings.mjs').ConeConstraintSettings |
+     * import('./types/settings.mjs').DistanceConstraintSettings |
+     * import('./types/settings.mjs').FixedConstraintSettings |
+     * import('./types/settings.mjs').HingeConstraintSettings |
+     * import('./types/settings.mjs').PulleyConstraintSettings |
+     * import('./types/settings.mjs').SixDOFConstraintSettings |
+     * import('./types/settings.mjs').SliderConstraintSettings |
+     * import('./types/settings.mjs').SwingTwistConstraintSettings} [opts] - Optional joint options object.
+     * @returns {FixedConstraint | PointConstraint | DistanceConstraint | HingeConstraint |
+     * SliderConstraint | ConeConstraint | SixDOFConstraint | SwingTwistConstraint |
+     * PulleyConstraint | null} - A joint interface or `null`, if unable to create a joint.
+     */
     addJoint(type, otherEntity, opts = {}) {
         let JointConstructor;
         switch (type) {
@@ -52,7 +104,7 @@ class ConstraintComponent extends Component {
                 if ($_DEBUG) {
                     Debug.warn(`Trying to add unrecognized constraint type: ${type}`);
                 }
-                return;
+                return null;
         }
 
         const joint = new JointConstructor(this.entity, otherEntity, opts);

src/physics/jolt/front/constraint/system.mjs

@@ -8,6 +8,12 @@ import {
 
 const schema = ['list'];
 
+/**
+ * Constraint Component System. Creates and destroys constraints from
+ * {@link ConstraintComponent | Constraint Components} on the backend.
+ *
+ * @category Constraint Component
+ */
 class ConstraintComponentSystem extends JoltComponentSystem {
     _constraintMap = new IndexedCache();
 

src/physics/jolt/front/constraint/types/cone.mjs

@@ -30,6 +30,11 @@ class ConeConstraint extends Constraint {
         this._halfConeAngle = opts.halfConeAngle ?? this._halfConeAngle;
     }
 
+    /**
+     * Changes the half cone angle of the constraint.
+     *
+     * @param {number} angle - Angle in radians.
+     */
     set halfConeAngle(angle) {
         if ($_DEBUG) {
             const ok = Debug.checkFloat(angle, `Invalid half cone angle scalar: ${angle}`);
@@ -50,18 +55,38 @@ class ConeConstraint extends Constraint {
         );
     }
 
+    /**
+     * @returns {number} - Half cone angle in radians.
+     * @defaultValue 0
+     */
     get halfConeAngle() {
         return this._halfConeAngle;
     }
 
+    /**
+     * @returns {Vec3} - Twist axis 1.
+     * @defaultValue Vec3(1, 0, 0)
+     */
     get twistAxis1() {
         return this._twistAxis1;
     }
 
+    /**
+     * @returns {Vec3} - Twist axis 2.
+     * @defaultValue Vec3(1, 0, 0)
+     */
     get twistAxis2() {
         return this._twistAxis2;
     }
 
+    /**
+     * @returns {number} - Constraint type alias number.
+     * @defaultValue CONSTRAINT_TYPE_CONE
+     */
+    get type() {
+        return this._type;
+    }
+
     write(cb) {
         super.write(cb);
 

src/physics/jolt/front/constraint/types/constraint.mjs

@@ -6,7 +6,7 @@ import {
     CONSTRAINT_TYPE_UNDEFINED, OPERATOR_MODIFIER, SPRING_MODE_FREQUENCY
 } from '../../../constants.mjs';
 
-class SpringSettings {
+class Spring {
     springMode = SPRING_MODE_FREQUENCY;
 
     frequency = 0;
@@ -23,7 +23,7 @@ class SpringSettings {
     }
 }
 
-class MotorSettings {
+class Motor {
     minForceLimit = -Number.MAX_VALUE;
 
     maxForceLimit = Number.MAX_VALUE;
@@ -34,20 +34,32 @@ class MotorSettings {
 
     springSettings = null;
 
+    /**
+     * Creates a motor.
+     *
+     * @param {import('./settings.mjs').MotorSettings} [opts] - Optional object, describing motor
+     * settings.
+     */
     constructor(opts = {}) {
         this.minForceLimit = opts.minForceLimit ?? this.minForceLimit;
         this.maxForceLimit = opts.maxForceLimit ?? this.maxForceLimit;
         this.minTorqueLimit = opts.minTorqueLimit ?? this.minTorqueLimit;
         this.maxTorqueLimit = opts.maxTorqueLimit ?? this.maxTorqueLimit;
 
         if (opts.springSettings) {
-            this.springSettings = new SpringSettings(opts.springSettings);
+            this.springSettings = new Spring(opts.springSettings);
         }
     }
 }
 
+/**
+ * Base class for different types of constraint interfaces.
+ *
+ * @group Utilities
+ * @category Constraints
+ */
 class Constraint {
-    static defaultMotor = new MotorSettings();
+    static defaultMotor = new Motor();
 
     static writeAxes(cb, axes, limits) {
         cb.write(!!axes, BUFFER_WRITE_BOOL, false);
@@ -135,50 +147,115 @@ class Constraint {
         this._space = opts.space ?? this._space;
     }
 
+    /**
+     * Unique constraint index to link to physics object. Index can be re-used by another constraint, when this one is
+     * destroyed.
+     *
+     * @hidden
+     */
     set index(idx) {
         this._index = idx;
     }
 
+    /**
+     * @hidden
+     * @returns {number} - Constraint unique integer index.
+     */
     get index() {
         return this._index;
     }
 
+    /**
+     * First body position in constraint reference frame. Space is determined by {@link space}
+     * property.
+     *
+     * @type {import('playcanvas').Vec3}
+     * @defaultValue Vec3(0, 0, 0)
+     */
     get point1() {
         return this._point1;
     }
 
+    /**
+     * Second body position in constraint reference frame. Space is determined by {@link space}
+     * property.
+     *
+     * @type {import('playcanvas').Vec3}
+     * @defaultValue Vec3(0, 0, 0)
+     */
     get point2() {
         return this._point2;
     }
 
+    /**
+     * First entity this joint is connected to.
+     *
+     * @returns {import('playcanvas').Entity} - First entity the joint is connected to.
+     */
     get entity1() {
         return this._entity1;
     }
 
+    /**
+     * Second entity this joint is connected to.
+     *
+     * @returns {import('playcanvas').Entity} - Second entity the joint is connected to.
+     */
     get entity2() {
         return this._entity2;
     }
 
+    /**
+     * Override for the number of solver velocity iterations to run. If set to `0`, the constraint
+     * will use global default set by Physics initialization setting (TODO add link).
+     *
+     * @returns {number} - Velocity steps override.
+     * @defaultValue 0
+     */
     get numVelocityStepsOverride() {
         return this._numVelocityStepsOverride;
     }
 
+    /**
+     * Override for the number of solver position iterations to run. If set to `0`, the constraint
+     * will use global default set by Physics initialization setting (TODO add link).
+     *
+     * @returns {number} - Positions steps override.
+     * @defaultValue 0
+     */
     get numPositionStepsOverride() {
-        return this._numVelocityStepsOverride;
+        return this._numPositionStepsOverride;
     }
 
+    /**
+     * Reference frame space that `point1` and `point2` use.
+     *
+     * @returns {number} - Number, representing reference space.
+     * @defaultValue CONSTRAINT_SPACE_WORLD
+     */
     get space() {
         return this._space;
     }
 
+    /**
+     * @hidden
+     * @returns {import('../system.mjs').ConstraintComponentSystem} - Constraint component system.
+     */
     get system() {
         return this._entity1.constraint.system;
     }
 
+    /**
+     * @hidden
+     * @returns {number} - Constraint type.
+     */
     get type() {
         return this._type;
     }
 
+    /**
+     * Destroy this joint. The connected bodies will be activated.
+     */
     destroy() {
         this.system.destroyConstraint(this._index);
     }
@@ -193,6 +270,12 @@ class Constraint {
         cb.write(this._space, BUFFER_WRITE_UINT8, false);
     }
 
+    /**
+     * Allows to enable/disable a constraint without destroying it.
+     *
+     * @param {boolean} enabled - `true` - enable constraint, `false` - disable.
+     * @param {boolean} [activate] - If `true`, activate connected bodies after changing the state.
+     */
     setEnabled(enabled, activate = true) {
         if ($_DEBUG) {
             let ok = Debug.checkBool(enabled, `Invalid constraint enable bool: ${enabled}`);
@@ -210,4 +293,4 @@ class Constraint {
     }
 }
 
-export { Constraint, MotorSettings, SpringSettings };
+export { Constraint, Motor, Spring };