lecodes-sdk 0.20.0 → 1.0.0

package/src/gl/vehicle/Wheel.ts

@@ -0,0 +1,290 @@
+// One wheel of a `Vehicle`, as an aspect on the wheel's own node — a wheel COLLIDER, the way Unity's
+// WheelCollider is one. The node's position IS the wheel's resting position (where its centre sits
+// on flat ground), and everything physical about it lives here: size, suspension, tire, its role.
+//
+//   const car = new Node('car')
+//     .add(body, hubFL.aspect(Wheel), hubFR.aspect(Wheel), hubRL.aspect(Wheel), hubRR.aspect(Wheel))
+//     .aspect(Shape, { box: [0.9, 0.4, 2.1] })
+//     .aspect(Vehicle, { mass: 1200 })
+//
+// That is the whole minimum: `Vehicle` collects every `Wheel` under itself, groups them into axles by
+// Z (front first), and the defaults fall out — the front axle steers, the rear one is driven.
+// Override any of it per wheel.
+//
+// The aspect never touches a transform. The hub node stays where the author put it; where the
+// wheel IS right now is a readout — `position` (down the suspension), `steerAngle`, `spin` — and
+// posing a wheel model from them is the game's, a few lines in a late-phase system:
+//
+//   angle = (angle + wheel.spin * dt) % (2 * Math.PI)
+//   mesh.position = wheel.position
+//   mesh.quaternion = Quat.fromAxisAngle([0, 1, 0], -wheel.steerAngle * DEG2RAD)
+//                         .mul(Quat.fromAxisAngle([1, 0, 0], -angle))
+//
+// (both minus signs: the engine reports the driver's terms — steer right-positive, spin forward-
+// positive — in a right-handed scene whose forward is −Z; a caliper is the same without the spin).
+//
+// The TIRE is numbers too, all the way down: its friction curves go to the engine as points, the way
+// the engine's torque curve does. `Tire.road()` / `arcade()` / `drift()` are point lists of this
+// file, not the engine's — the engine has no presets at all.
+//
+// The brake is an INPUT here (`brake`, N·m this frame), like `throttle` on the car: a foot brake, a
+// handbrake, an ABS decide what each wheel gets, and that is the game's.
+//
+// Chassis space is forward −Z / up +Y, the SDK's own convention (`node.forward`).
+
+import { Aspect } from "../../core/Aspect"
+import type { FieldMeta } from "../../core/fields"
+import { Mat4 } from "../../math/mat4"
+import { Vec3, cx, cy, cz } from "../../math/vec"
+import { Gizmos } from "../../scene/gizmos"
+import { Node } from "../Node"
+import { Shape } from "../physics/Shape"
+import type { Vehicle } from "./Vehicle"
+
+/** Floats `vehicleGetState` writes before the per-wheel block: speed, rpm, contacts, vx, vy, vz, wx, wy, wz,
+ *  steerDeg, steerTorque. */
+export const STATE_HEADER = 11
+/** Floats per wheel: contact, slip, slipAngle, suspensionLength, steerDeg, spin, fLat, fLong, vLat, vSlip, load. */
+export const WHEEL_STATE = 11
+/** Fully compressed = this fraction of `travel` (the engine's one suspension constant, mirrored here
+ *  so `compression` and the resting-height maths read the same number). */
+export const SUSPENSION_MIN_FRACTION = 0.4
+
+/** A point on a curve — a tire's friction over slip, an engine's torque over rpm. */
+export type Point = { x: number, y: number }
+
+export interface WheelSuspension {
+  /** Total travel in metres, full droop to fully compressed (default 0.4). */
+  travel?: number
+  /** Spring frequency in Hz — bigger is stiffer (default 1.4; a race car ~2.5, a truck ~1). It also
+   *  sets the ride-height sag, and the sag is how far the wheel can still extend DOWN. */
+  stiffness?: number
+  /** Damping ratio 0..1 (default 0.5). Low values pogo. */
+  damping?: number
+}
+
+/**
+ * A tire, as the engine takes it: two friction curves and two numbers. `Tire.road()` and the other
+ * presets are starting points — copy one and edit, or `Tire.scale()` it.
+ */
+export interface Tire {
+  /** Lateral friction over slip ANGLE: `{ x: degrees, y: friction }`, x ascending. Friction is the
+   *  coefficient the tire's load is multiplied by; the last value holds to 90°. The grip a wheel
+   *  actually gets is combined with the ground it stands on as `sqrt(tire × groundFriction)`, and a
+   *  body's friction defaults to 0.6 — a road a car should really corner on wants `Physics { friction: 1 }`. */
+  side: Point[]
+  /** Longitudinal friction over slip RATIO: `{ x: ratio, y: friction }` (0 = rolling in sync, 1 =
+   *  locked or spinning freely). */
+  forward: Point[]
+  /** The longitudinal impulse clamp as a multiple of `friction × load` — for DRIVE only; a braking
+   *  wheel is always clamped at the physical limit (or a locked rear would stop the car at a full g
+   *  and kill every handbrake turn). `1` is the physical tire; `road`'s 10 is Jolt's own sample
+   *  value (it keeps a driven wheel from ever spinning up). Anything a friction circle should bite
+   *  on wants this near 1. */
+  traction?: number
+  /** Friction circle, 0..1: how much of the lateral capacity the longitudinal impulse in use takes
+   *  away. `0` = the two axes independent (a spinning wheel corners as well as a rolling one);
+   *  `1` = the full circle — wheelspin or a locked wheel lets go sideways. */
+  circle?: number
+}
+
+const pts = (flat: number[]): Point[] => {
+  const out: Point[] = []
+  for (let i = 0; i + 1 < flat.length; i += 2) out.push({ x: flat[i]!, y: flat[i + 1]! })
+  return out
+}
+
+/**
+ * Tire presets — fresh point lists every call (editing one never touches another), and `scale`.
+ *
+ *  - `road` — Jolt's stock tire: lateral peak 1.2 at 3° falling to 1.0 by 20° and flat after, the
+ *    two axes independent, and the longitudinal clamp ×10 (Jolt's own sample runs this; it means a
+ *    driven wheel practically never spins up). Grippy, glued, hard to unsettle.
+ *  - `arcade` — the peak held all the way out on both axes: the car does not let go at all.
+ *  - `drift` — a tire that can be held sideways: lateral grip falls to 0.7 past 25°, the longitudinal
+ *    clamp is near the physical one (`traction: 2` — a launch at exactly 1 is a 0.4 g crawl; 2 keeps
+ *    it punchy) so the rear can be spun up, and a friction circle (`circle: 0.85` — most of it, so a
+ *    spinning rear loses most but not all of its lateral grip and the slide stays progressive):
+ *    power oversteer, and a slide the throttle keeps alive. A 600 N·m car lights its tires off the
+ *    line on it; that is the tire, and a traction control is the game's.
+ */
+export const Tire = {
+  road: (): Tire => ({ side: pts([ 0, 0, 3, 1.2, 20, 1.0 ]), forward: pts([ 0, 0, 0.06, 1.2, 0.2, 1.0 ]), traction: 10, circle: 0 }),
+  arcade: (): Tire => ({ side: pts([ 0, 0, 3, 1.2, 90, 1.2 ]), forward: pts([ 0, 0, 0.06, 1.2, 1.0, 1.2 ]), traction: 10, circle: 0 }),
+  drift: (): Tire => ({ side: pts([ 0, 0, 4, 1.2, 25, 0.75, 90, 0.7 ]), forward: pts([ 0, 0, 0.08, 1.2, 0.5, 0.85 ]), traction: 2, circle: 0.85 }),
+  /** Both curves multiplied by `k` — a grip slider, a cold tire, a wet road. A new tire; `t` is untouched. */
+  scale: (t: Tire, k: number): Tire => ({
+    ...t,
+    side: t.side.map((p) => ({ x: p.x, y: p.y * k })),
+    forward: t.forward.map((p) => ({ x: p.x, y: p.y * k })),
+  }),
+}
+
+/** @internal The tire as the blob carries it: every field filled in. */
+export interface ResolvedTire {
+  side: Point[]
+  forward: Point[]
+  traction: number
+  circle: number
+}
+
+export function resolveTire(tire: Tire): ResolvedTire {
+  const road = Tire.road()
+  return {
+    side: tire.side.length > 0 ? tire.side : road.side,
+    forward: tire.forward.length > 0 ? tire.forward : road.forward,
+    traction: tire.traction !== undefined && tire.traction > 0 ? tire.traction : road.traction!,
+    circle: Math.max(0, Math.min(1, tire.circle ?? road.circle!)),
+  }
+}
+
+export class Wheel extends Aspect<"wheel", Node> {
+  static readonly aspect = "wheel"
+
+  /** Wheel radius in metres. Default: measured from the node's rendered bounds, else 0.35. Too small
+   *  and the car scrapes, too large and it floats. */
+  radius?: number
+  /** Wheel width in metres. Default: measured, else 0.25. */
+  width?: number
+  /** Axle group, front to back. Default: derived from Z. Set it for a car whose wheels are not in neat
+   *  left/right pairs — an axle's wheels are paired for the differential and the anti-roll bar. */
+  axle?: number
+  /** Does this wheel steer? Default: the wheels on the front axle. */
+  steer?: boolean
+  /** This wheel's SHARE of the engine's torque, 0 = not driven. Default: from the vehicle's
+   *  `driveAxle` (1 on that axle). An axle's share is the sum of its two wheels', the left/right
+   *  split their ratio, so `0.6` / `0.4` front-to-rear is `driven: 0.3` on each front wheel and
+   *  `0.2` on each rear. Structural: baked at attach. */
+  driven?: number
+
+  suspension: WheelSuspension = { travel: 0.4, stiffness: 1.4, damping: 0.5 }
+  /** The tire (default `Tire.road()`). Live: re-assign it or re-configure the aspect and the car
+   *  retunes in place — a grip slider, a tire that heats up. */
+  tire: Tire = Tire.road()
+
+  /** INPUT: brake torque on this wheel THIS frame, N·m (default 0). Sticky, like `Vehicle.throttle`:
+   *  write it every frame from a driver system's `updateBefore` — the foot brake's share, the
+   *  handbrake's 4500 on a rear wheel, an ABS's pulses — and the same physics step applies it. A
+   *  braking wheel is clamped at the physical tire limit (the `traction` boost is for drive only). */
+  brake = 0
+
+  /** Scene-editor inspector. `steer` / `driven` are deliberately absent: they are tri-state
+   *  (undefined = derive it from the axle), which a slider cannot express. */
+  static fields: FieldMeta<Wheel> = {
+    radius: { min: 0.05, step: 0.01 },
+    width: { min: 0.02, step: 0.01 },
+    axle: { min: 0, step: 1 },
+    brake: { hidden: true },
+    suspension: { hidden: true },
+    tire: { hidden: true },
+  }
+  static editor = { rebuild: true }
+
+  /** @internal Set by `Vehicle` at attach — the car this wheel belongs to, and its index in the blob. */
+  _vehicle: Vehicle | null = null
+  /** @internal */
+  _index = -1
+  /** @internal Suspension attachment point in chassis space; the wheel hangs below it. */
+  _attach = new Vec3()
+  /** @internal Resting centre in chassis space (what the author placed). */
+  _rest = new Vec3()
+
+  onDetach(): void {
+    this._vehicle = null
+    this._index = -1
+  }
+
+  /** Re-configuring a wheel on a live car retunes the car: the tire is live; size, suspension, the
+   *  driven share and the axle are structural (re-attach the Vehicle). */
+  onReconfigure(): void {
+    this._vehicle?._retuneSoon()
+  }
+
+  /** @internal Called by Vehicle once the car exists, with the geometry it resolved. */
+  _bind(vehicle: Vehicle, index: number, rest: Vec3, attach: Vec3): void {
+    this._vehicle = vehicle
+    this._index = index
+    this._rest = rest
+    this._attach = attach
+  }
+
+  // ---- live state ------------------------------------------------------------------------------
+  // Every getter reads the car's ONE shared state buffer, which is refreshed once per phase.
+
+  private _state(k: number): number {
+    const v = this._vehicle
+    if (!v || this._index < 0) return 0
+    return v._wheelState(this._index, k)
+  }
+
+  /** Touching the ground this step. */
+  get contact(): boolean { return this._state(0) !== 0 }
+  /** Longitudinal slip RATIO, signed: 0 = rolling in sync with the ground, towards +1 = spinning up
+   *  (wheelspin), towards −1 = locking under braking — whichever way the car travels. Smoke, tire
+   *  marks, wheelspin sound and traction control key off this. */
+  get slip(): number { return this._state(1) }
+  /** Slip ANGLE in degrees, signed: how far the tire's travel direction is off from where it points,
+   *  positive when the contact patch slides to the tire's RIGHT. Past the curve's peak (~3°) the tire
+   *  is letting go sideways. */
+  get slipAngle(): number { return this._state(2) }
+  /** This wheel's steer angle in degrees, right-positive. */
+  get steerAngle(): number { return this._state(4) }
+  /** Wheel spin in rad/s (× radius ≈ the speed the tire is laying down). Forward-positive; a model
+   *  turns about the right-hand axle by MINUS the integrated angle. */
+  get spin(): number { return this._state(5) }
+  /** The tire's lateral force this step, N, positive toward the tire's right — the road pushing the
+   *  patch back against its slide. */
+  get sideForce(): number { return this._state(6) }
+  /** The tire's longitudinal force this step, N, positive pushing the car forward. */
+  get forwardForce(): number { return this._state(7) }
+  /** How fast the contact patch slides sideways, m/s, positive to the tire's right. */
+  get sideSlipSpeed(): number { return this._state(8) }
+  /** How fast the tread runs over the road, m/s, positive spinning up, negative locking. Force ×
+   *  sliding speed (`|sideForce × sideSlipSpeed| + |forwardForce × slipSpeed|`) is the friction's
+   *  heat into the tread, W — a tire-temperature model integrates it. */
+  get slipSpeed(): number { return this._state(9) }
+  /** The suspension's force on the wheel this step, N — the tire's LOAD (0 in the air). What a
+   *  friction budget divides by: `hypot(sideForce, forwardForce) / (load × μ)`. */
+  get load(): number { return this._state(10) }
+  /** Suspension compression, 0 = fully extended (drooping) … 1 = fully compressed. */
+  get compression(): number {
+    const travel = this.suspension.travel ?? 0.4
+    const min = travel * SUSPENSION_MIN_FRACTION
+    const span = travel - min
+    if (span <= 0) return 0
+    const length = this._state(3)
+    return Math.max(0, Math.min(1, 1 - (length - min) / span))
+  }
+  /** Where the wheel's centre is right now, in CHASSIS space: the suspension's attachment point,
+   *  down by however far it hangs this step. Put a wheel model here (see the file header). */
+  get position(): Vec3 {
+    return new Vec3(this._attach.x, this._attach.y - this._state(3), this._attach.z)
+  }
+
+  /** Edit mode: this wheel's own circle at its resting height, its travel range, and a mark when the
+   *  engine drives it — enough to place a wheel without running the game. */
+  rebuild(): void {
+    const travel = this.suspension.travel ?? 0.4
+    const r = this.radius ?? this._measure().radius
+    const world = new Mat4(this.node.worldMatrix)
+    const P = (x: number, y: number, z: number): Vec3 => world.transformPoint([ x, y, z ])
+    const ring: Vec3[] = []
+    for (let i = 0; i < 24; i++) {
+      const t = (i / 24) * Math.PI * 2
+      ring.push(P(0, Math.sin(t) * r, Math.cos(t) * r))
+    }
+    Gizmos.polyline(ring, { color: this.steer === false ? "#9aa3b2" : "#5b8ef0", closed: true })
+    Gizmos.line(P(0, travel * (1 - SUSPENSION_MIN_FRACTION), 0), P(0, -travel * SUSPENSION_MIN_FRACTION, 0), { color: "#59606d" })
+    if (this.driven) Gizmos.cross(P(0, 0, 0), r * 0.35, { color: "#e0b25a" })
+  }
+
+  /** @internal Radius/width from the node's rendered bounds, so a placed model needs no numbers.
+   *  The axle is the node's X: a disc's diameter is the larger of the two axes across it. */
+  _measure(): { radius: number, width: number } {
+    const b = Shape.boundsOf(this.node)
+    if (!b) return { radius: 0.35, width: 0.25 }
+    const size = new Vec3(cx(b.max) - cx(b.min), cy(b.max) - cy(b.min), cz(b.max) - cz(b.min))
+    const across = Math.max(size.z, size.y)
+    return { radius: across > 0 ? across * 0.5 : 0.35, width: size.x > 0 ? size.x : 0.25 }
+  }
+}