lecodes-cli 0.17.1 → 0.18.0

package/runtime/sdk/gl/Physics.ts

@@ -12,6 +12,7 @@
 // are driven with moveTo.
 
 import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
 import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
 import { nodeRegistry, type Node } from "./Node"
 import { Shape } from "./Shape"
@@ -48,6 +49,29 @@ export class Physics extends Aspect<"physics", Node> {
   motion: MotionType = "dynamic"
   /** Mass in kg for dynamic bodies (default 1). Ignored for static/kinematic. */
   mass = 1
+  /**
+   * Surface friction: 0 = ice, ~1 = grippy asphalt, and values above 1 are allowed (rubber on
+   * tarmac).
+   *
+   * The engine COMBINES the two touching bodies as `sqrt(a * b)`, so the LOWER value dominates and
+   * the floor caps everything standing on it. The default **0.6** is a neutral solid surface (the
+   * raw Jolt default of 0.2 is ice by game standards); dry tarmac a car should corner on wants a
+   * `1`, ice `0.02`. A Vehicle's tires read the GROUND body's value, so this is the single number
+   * that decides how well a car corners.
+   *
+   * Change it at runtime by re-configuring — `floor.aspect(Physics, { friction: 0.02 })` (an ice
+   * patch). It is a PLAIN FIELD on purpose: an accessor pair would be tree-shaken out of the
+   * bundle, because passing `{ friction }` in a config object is not a member reference the
+   * bundler can see, and the write would then silently land on a dead property.
+   */
+  friction = 0.6
+
+  /** Scene-editor inspector: `motion` as a dropdown (a string default alone infers a text box). */
+  static fields: FieldMeta<Physics> = {
+    motion: { options: [ "static", "kinematic", "dynamic" ] },
+    mass: { min: 0, step: 0.1 },
+    friction: { min: 0, max: 2, step: 0.05 },
+  }
 
   private _bodyId = 0
 
@@ -57,14 +81,29 @@ export class Physics extends Aspect<"physics", Node> {
     if (!shape) {
       throw new Error("Physics requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Physics, {…})")
     }
+    if (this.motion === "dynamic" && shape._isTriangleMesh) {
+      throw new Error("Physics: a dynamic body cannot use Shape { mesh: true } (triangle meshes are static/kinematic only) — use { mesh: 'convex' } or a primitive shape")
+    }
     const shapeId = shape._claim() // drop the pick-only body; reuse its shape
     this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, MOTION[this.motion], this.mass, false, false)
+    this._applyFriction()
     shape._ownBody(this._bodyId)
   }
 
   onDetach(): void {
     if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
-    this.node.get(Shape)?._recreatePickBody() // keep the node pickable if the Shape stays
+    const shape = this.node.get(Shape)
+    if (shape) {
+      shape._ownBody(0)          // the Shape held OUR body id — forget it, or its own detach removes it twice (native crash)
+      shape._recreatePickBody()  // keep the node pickable if the Shape stays
+    }
+  }
+
+  /** Re-configuring (`node.aspect(Physics, { friction })`) pushes the new surface to the live body. */
+  onReconfigure(): void { this._applyFriction() }
+
+  private _applyFriction(): void {
+    if (this._bodyId) _creator.physicsSetFriction?.(this._bodyId, this.friction)
   }
 
   /** Native Jolt body id. 0 until attached, or if the build has no physics support. */
@@ -86,6 +125,19 @@ export class Physics extends Aspect<"physics", Node> {
     return this
   }
 
+  /** The same impulse applied at a WORLD-SPACE point instead of the centre of mass: the lever arm
+   *  becomes angular impulse, so the body spins as well as moves (a bullet hitting a crate off
+   *  centre, a blast lifting it by its base). Falls back to the central impulse on an older host. */
+  applyImpulseAt(v: Vec3Like, point: Vec3Like): this {
+    if (!this._bodyId) return this
+    if (_creator.physicsApplyImpulseAt) {
+      _creator.physicsApplyImpulseAt(this._bodyId, cx(v), cy(v), cz(v), cx(point), cy(point), cz(point))
+    } else {
+      _creator.physicsApplyImpulse(this._bodyId, cx(v), cy(v), cz(v))
+    }
+    return this
+  }
+
   /** Teleport / drive a kinematic (or dynamic) body to a world position. */
   moveTo(p: Vec3Like): this {
     if (this._bodyId) _creator.physicsSetBodyPosition(this._bodyId, cx(p), cy(p), cz(p))