lecodes-sdk 2.4.1 → 2.4.2

package/src/g2/Scene2D.ts

@@ -132,7 +132,7 @@ export class Scene2D implements Presentable {
    *  types: it is what makes a Scene2D a `SystemHost` there. */
   readonly _systems = new Map<Function, Aspect<any, any, any>>()
 
-  /** Attach (and configure) a system, or reconfigure it if already present. Returns the scene typed
+  /** Build a system from `opts` (a class already on the scene is detached and built afresh). Returns the scene typed
    *  as now-having it (`scene.system(Hud).hud`). A 3D `System<'x'>` (target Scene) is rejected here. */
   // `this: Self` (not `Self & Scene2D`): with the intersection TS infers Self = Scene2D and a chain
   // `scene.system(A).system(B)` loses A's accessor from the result type.

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/Model.ts

@@ -35,8 +35,9 @@ export interface TrianglePick {
 }
 
 export class Model extends Node {
-  /** The model's Animator — always present, its clip table = the GLB's embedded clips. Configure
-   *  more (external clips, blend spaces, layers) with `model.aspect(Animator, {...})`. */
+  /** The model's Animator — always present, its clip table = the GLB's embedded clips. Add to it
+   *  with `model.anim.addClip(name, clip)` (external clips), `model.anim.addLayer()`; set its fields
+   *  (`model.anim.speed = 1.5`) — never `model.aspect(Animator, …)`, which would build a fresh one. */
   declare readonly anim: Animator
   /** @internal loaded through the lightmap material (a baked static); clones inherit it. */
   _lightmapped = false

package/src/gl/Scene.ts

@@ -364,7 +364,7 @@ export class Scene implements Presentable {
    *  types: it is what makes a Scene a `SystemHost` there. */
   readonly _systems = new Map<Function, Aspect<any, any, any>>()
 
-  /** Attach (and configure) a system, or reconfigure it if already present. Returns the scene typed
+  /** Build a system from `opts` (a class already on the scene is detached and built afresh). Returns the scene typed
    *  as now-having it (`scene.system(Hud).hud`). A `System<'x', Scene2D>` is rejected here. */
   // `this: Self` (not `Self & Scene`): with the intersection TS infers Self = Scene and a chain
   // `scene.system(A).system(B)` loses A's accessor from the result type.