lecodes-sdk 2.4.1 → 2.4.3

package/src/g2/Shape2D.ts

@@ -12,11 +12,12 @@
 // a collider that wraps the art instead of one centred on the pivot (half of it underground), which
 // is why every character used to carry a hand-computed offset.
 //
-// RE-CONFIGURING REBUILDS IT IN PLACE: `node.aspect(Shape2D, { capsule: … })` on a live node swaps the
-// fixture while the body keeps its id, its velocity and its place in the world. That is what makes a
-// crouch (and a live editor edit) possible.
+// EVERY DIMENSION IS LIVE: `node.shape.capsule = …` on a live node swaps the fixture at once while the
+// body keeps its id, its velocity and its place in the world. That is what makes a crouch (and a
+// live editor edit) possible.
 
 import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
 import { Vec2, cx, cy, type Vec2Like } from "../math/vec"
 import { ALL_GROUPS } from "./groups2d"
 import type { Node2D } from "./Node2D"
@@ -35,17 +36,36 @@ export type ShapeFixture2D = {
 export class Shape2D extends Aspect<"shape", Node2D> {
   static readonly aspect = "shape"
 
+  // Every dimension is LIVE and applies AT ONCE: a write swaps the fixture in place, the body keeping
+  // its id, its velocity and its place in the world (a crouch, a live editor edit) — synchronous,
+  // because the caller reads the result back right away (`controller.resizing`). A write that leaves
+  // the geometry's signature unchanged does nothing.
+  private _box?: Vec2Like
+  private _circle?: number
+  private _cap?: { from: Vec2Like, to: Vec2Like, radius: number }   // `_capsule()` is the mover's view
+  private _segment?: { from: Vec2Like, to: Vec2Like }
+  private _polygon?: Vec2Like[]
+  private _chain?: Vec2Like[]
+  private _loop?: boolean
+  private _flip?: boolean
+  private _origin?: Vec2Like
+
   /** Box half-extents [hw, hh] (world units). */
-  box?: Vec2Like
+  get box(): Vec2Like | undefined { return this._box }
+  set box(v: Vec2Like | undefined) { this._box = v; this._changed() }
   /** Circle radius. */
-  circle?: number
+  get circle(): number | undefined { return this._circle }
+  set circle(v: number | undefined) { this._circle = v; this._changed() }
   /** Capsule between two local points, with a radius. */
-  capsule?: { from: Vec2Like, to: Vec2Like, radius: number }
+  get capsule(): { from: Vec2Like, to: Vec2Like, radius: number } | undefined { return this._cap }
+  set capsule(v: { from: Vec2Like, to: Vec2Like, radius: number } | undefined) { this._cap = v; this._changed() }
   /** Thin segment (an edge) between two local points. */
-  segment?: { from: Vec2Like, to: Vec2Like }
+  get segment(): { from: Vec2Like, to: Vec2Like } | undefined { return this._segment }
+  set segment(v: { from: Vec2Like, to: Vec2Like } | undefined) { this._segment = v; this._changed() }
   /** Convex polygon, up to 8 local points (a convex hull is computed — a CONCAVE outline silently
    *  becomes its hull; use `chain` for those). */
-  polygon?: Vec2Like[]
+  get polygon(): Vec2Like[] | undefined { return this._polygon }
+  set polygon(v: Vec2Like[] | undefined) { this._polygon = v; this._changed() }
   /**
    * A polyline of connected segments — the one shape that expresses a long CONCAVE surface (rolling
    * terrain, a cave wall) in one piece, seam-free. Pass only the points that should be solid; the
@@ -55,14 +75,23 @@ export class Shape2D extends Aspect<"shape", Node2D> {
    * must not self-intersect. It is ONE-SIDED: solid on the right of the point order — walk the points
    * so that the solid material is on your right, or set `flip`.
    */
-  chain?: Vec2Like[]
+  get chain(): Vec2Like[] | undefined { return this._chain }
+  set chain(v: Vec2Like[] | undefined) { this._chain = v; this._changed() }
   /** `chain`: close the contour (an island / a room boundary). Needs at least 4 points. */
-  loop?: boolean
+  get loop(): boolean | undefined { return this._loop }
+  set loop(v: boolean | undefined) { this._loop = v; this._changed() }
   /** `chain`: put the solid side on the other side of the line. */
-  flip?: boolean
+  get flip(): boolean | undefined { return this._flip }
+  set flip(v: boolean | undefined) { this._flip = v; this._changed() }
   /** The collider's centre relative to the node, in world units. Applies to EVERY kind — it
    *  translates a capsule's / segment's / polygon's / chain's points too, unlike the old `offset`. */
-  origin?: Vec2Like
+  get origin(): Vec2Like | undefined { return this._origin }
+  set origin(v: Vec2Like | undefined) { this._origin = v; this._changed() }
+
+  /** Scene-editor inspector: the geometry fields (accessors, so they are listed here by name). */
+  static fields: FieldMeta<Shape2D> = {
+    box: {}, circle: {}, capsule: {}, segment: {}, polygon: {}, chain: {}, loop: {}, flip: {}, origin: {},
+  }
 
   /** @internal Geometry as of the last build — an unchanged signature means nothing to rebuild. */
   private _sig = ""
@@ -72,7 +101,7 @@ export class Shape2D extends Aspect<"shape", Node2D> {
   private _fx: ShapeFixture2D | null = null
   private _handle = 0
 
-  /** @internal — the character claimed this shape; record the geometry so a later re-configure is
+  /** @internal — the character claimed this shape; record the geometry so a later write is
    *  compared against it. */
   _claimedByCharacter(): void { this._sig = this._signature(); this._resizeRefused = false }
 
@@ -97,11 +126,11 @@ export class Shape2D extends Aspect<"shape", Node2D> {
   onDetach(): void { this._handle = 0; this._fx = null; this._sig = ""; this._resizeRefused = false }
 
   /**
-   * Re-configuring the aspect swaps the fixture in place — same body, same id, same velocity, same
-   * position. Nothing happens when the geometry is unchanged, so re-applying the same options in a
-   * loop is free.
+   * A dimension was written: swap the fixture in place — same body, same id, same velocity, same
+   * position. Nothing happens when the signature is unchanged, so writing the same dimensions every
+   * frame is free.
    */
-  onReconfigure(): void {
+  private _changed(): void {
     const sig = this._signature()
     if (sig === this._sig) return
 
@@ -110,9 +139,9 @@ export class Shape2D extends Aspect<"shape", Node2D> {
     if (this.node._xfKind === 1) {
       const cap = this._capsule()
       const ok = _creator2d.characterSetCapsule(this.node._xf, cap.x1, cap.y1, cap.x2, cap.y2, cap.radius)
-      // On refusal NOTHING changed — so DON'T commit the signature. The next identical
-      // `aspect(Shape2D, …)` then still sees a difference and retries; committing here would swallow
-      // every retry for good, which is the whole trap in this design.
+      // On refusal NOTHING changed — so DON'T commit the signature. The next write of the same
+      // dimensions then still sees a difference and retries; committing here would swallow every
+      // retry for good, which is the whole trap in this design.
       this._resizeRefused = !ok
       if (ok) this._sig = sig
       return
@@ -218,7 +247,7 @@ export class Shape2D extends Aspect<"shape", Node2D> {
     _creator2d.physicsAddChain(handle, new Float32Array(p), p.length / 2, loop, fx.friction, fx.bounce, category, mask)
   }
 
-  // Everything that changes the GEOMETRY, so a re-configure that only touches the material is free.
+  // Everything that changes the GEOMETRY, so a write that changed nothing is free.
   private _signature(): string {
     const o = this.origin ? `${cx(this.origin)},${cy(this.origin)}` : ""
     if (this.chain) return `chain:${this.chain.map(v => `${cx(v)},${cy(v)}`).join(";")}|${this.loop}|${this.flip}|${o}`
@@ -243,7 +272,7 @@ export class Shape2D extends Aspect<"shape", Node2D> {
    * Sprite anchor space is Y-DOWN while the world is Y-up (see docs/conventions.md), so `anchor: [.5, 1]`
    * ("feet") puts the art ABOVE the origin: its centre sits at +h/2. A node with no sprite falls back
    * to 8x8 at the origin. This is a SNAPSHOT taken when the fixture is built — growing the sprite later
-   * does not resize the collider; re-configure the aspect to re-measure.
+   * does not resize the collider; write a dimension (`origin = undefined` will do) to re-measure.
    */
   private _autoBox(): { hw: number, hh: number, x: number, y: number } {
     const n = this.node as { size?: Vec2, anchor?: Vec2, scale?: Vec2 }

package/src/gl/CameraPlace.ts

@@ -1,52 +1,52 @@
-// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
-// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
-// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
-// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
-//
-//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
-//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
-//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
-//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
-//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
-//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
-//     releases.
-//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
-// See docs/scene-camera-place-plan.md.
-
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { Gizmos } from "../scene/gizmos"
-import type { Camera } from "./Camera"
-import type { Node } from "./Node"
-
-export class CameraPlace extends Aspect<"cameraPlace", Node> {
-  static readonly aspect = "cameraPlace"
-  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
-  fov = 60
-  /** Near clip distance. */
-  near = 0.01
-  /** Far clip distance = view range. */
-  far = 1000
-  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
-   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
-  active = false
-  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
-  static fields: FieldMeta<CameraPlace> = {
-    fov: { label: "FOV", min: 1, max: 179, step: 1 },
-    near: { min: 0.001, max: 10, step: 0.01 },
-    far: { min: 1, max: 100000, step: 1 },
-    active: { label: "Active camera" },
-  }
-  static editor = { rebuild: true }
-
-  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
-  applyTo(camera: Camera): void {
-    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
-  }
-
-  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
-   *  clicking it selects the node. Play mode never calls this. */
-  rebuild(): void {
-    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
-  }
-}
+// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
+// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
+// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
+// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
+//
+//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
+//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
+//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
+//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
+//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
+//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
+//     releases.
+//   • Edit mode: draws an anchored frustum gizmo (the editor's camera preview reads the same place).
+// See docs/scene-camera-place-plan.md.
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import { Gizmos } from "../scene/gizmos"
+import type { Camera } from "./Camera"
+import type { Node } from "./Node"
+
+export class CameraPlace extends Aspect<"cameraPlace", Node> {
+  static readonly aspect = "cameraPlace"
+  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
+  fov = 60
+  /** Near clip distance. */
+  near = 0.01
+  /** Far clip distance = view range. */
+  far = 1000
+  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
+   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
+  active = false
+  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
+  static fields: FieldMeta<CameraPlace> = {
+    fov: { label: "FOV", min: 1, max: 179, step: 1 },
+    near: { min: 0.001, max: 10, step: 0.01 },
+    far: { min: 1, max: 100000, step: 1 },
+    active: { label: "Active camera" },
+  }
+  static editor = { rebuild: true }
+
+  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
+  applyTo(camera: Camera): void {
+    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
+  }
+
+  /** Edit mode: the frustum marker (−Z = view), anchored on the node so it follows drags live and
+   *  clicking it selects the node. Play mode never calls this. */
+  rebuild(): void {
+    Gizmos.frustum(this.fov, { node: this.node, color: this.active ? "#ffffff" : "#9aa3b2" })
+  }
+}