@umicat/three-sdk 0.3.0 → 0.4.0

package/dist/CharacterController3D.d.ts

@@ -14,6 +14,9 @@ export interface CharacterOptions {
     stepHeight?: number;
     /** Steeper than this and they slide instead of climbing. Degrees. */
     maxSlopeDegrees?: number;
+    /** Fall acceleration, in world units. Defaults to the world's own gravity;
+     *  set it only to make this character deliberately heavier or floatier than
+     *  its surroundings. */
     gravity?: number;
     /** Start position. */
     position?: {
@@ -83,6 +86,21 @@ export declare class CharacterController3D {
     get state(): CharacterState;
     /** Rising under its own power, as opposed to merely off the ground. */
     get airborne(): boolean;
+    /** How high a HELD jump rises, in world units.
+     *
+     *  Level geometry is authored against these two numbers, so they are exposed
+     *  rather than left to be re-derived. Getting the algebra wrong is not
+     *  hypothetical: a course laid out against a mis-computed apex produced a
+     *  first step the character could not clear, which reads to a player as
+     *  "that platform is unreachable" rather than as a bug. */
+    get maxJumpRise(): number;
+    /** How high a TAPPED jump rises — the button released as early as the
+     *  variable-height cut can see it.
+     *
+     *  **Author rises against this one, not `maxJumpRise`.** A jump is a range,
+     *  not a number: releasing early cuts it deliberately, so a gap only the
+     *  held jump clears is a gap half your players will believe is closed. */
+    get minJumpRise(): number;
     /** Put the character somewhere, cancelling any fall. The respawn primitive:
      *  without clearing the velocity, a character teleported out of a long drop
      *  arrives still travelling at the speed it fell. */

package/dist/CharacterController3D.js

@@ -29,7 +29,14 @@ export class CharacterController3D {
             speed: options.speed ?? 4,
             stepHeight: options.stepHeight ?? 0.4,
             maxSlopeDegrees: options.maxSlopeDegrees ?? 50,
-            gravity: options.gravity ?? 9.81,
+            // Default to the WORLD's gravity, not to Earth's. A kinematic character
+            // integrates its own fall, so a hard-coded 9.81 put a second gravity in
+            // the scene: in a world authored in Kenney's unit (gravity -4.17) the
+            // character fell 2.35x faster than everything around it, and every jump
+            // came out less than half the height the docs promised. One world, one
+            // gravity — pass the option only to give this character a deliberately
+            // different feel.
+            gravity: options.gravity ?? (Math.abs(world.gravity.y) || 9.81),
             jumpSpeed: options.jumpSpeed ?? 0,
             coyoteTime: options.coyoteTime ?? 0.12,
             jumpBuffer: options.jumpBuffer ?? 0.12,
@@ -53,6 +60,30 @@ export class CharacterController3D {
     get state() { return this._state; }
     /** Rising under its own power, as opposed to merely off the ground. */
     get airborne() { return !this.grounded; }
+    /** How high a HELD jump rises, in world units.
+     *
+     *  Level geometry is authored against these two numbers, so they are exposed
+     *  rather than left to be re-derived. Getting the algebra wrong is not
+     *  hypothetical: a course laid out against a mis-computed apex produced a
+     *  first step the character could not clear, which reads to a player as
+     *  "that platform is unreachable" rather than as a bug. */
+    get maxJumpRise() {
+        if (this.opts.jumpSpeed <= 0)
+            return 0;
+        return (this.opts.jumpSpeed * this.opts.jumpSpeed) / (2 * this.opts.gravity);
+    }
+    /** How high a TAPPED jump rises — the button released as early as the
+     *  variable-height cut can see it.
+     *
+     *  **Author rises against this one, not `maxJumpRise`.** A jump is a range,
+     *  not a number: releasing early cuts it deliberately, so a gap only the
+     *  held jump clears is a gap half your players will believe is closed. */
+    get minJumpRise() {
+        if (this.opts.jumpSpeed <= 0)
+            return 0;
+        const cut = this.opts.jumpSpeed * this.opts.jumpCut;
+        return (cut * cut) / (2 * this.opts.gravity);
+    }
     /** Put the character somewhere, cancelling any fall. The respawn primitive:
      *  without clearing the velocity, a character teleported out of a long drop
      *  arrives still travelling at the speed it fell. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umicat/three-sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Three.js runtime for Umicat games: the scene3d design format, its loader with physics, a kinematic character controller, and the Umicat platform via @umicat/platform-sdk.",
   "type": "module",
   "main": "dist/index.js",