lecodes-sdk 1.0.0 → 1.2.0

package/src/gl/Particles.ts

@@ -40,6 +40,11 @@ const TAG_ANGULAR_VELOCITY = 17
 const TAG_GROUND = 18
 const TAG_VELOCITY_LIFE = 19
 const TAG_ORDER = 20
+const TAG_SMOOTH_PATH = 21
+const TAG_RIBBON_ORIENT = 22
+const TAG_LIT = 23
+/** `TrailOptions.orient` → the native axis code (0 = the camera-facing default). */
+const RIBBON_AXIS: Record<"camera" | "x" | "y" | "z", number> = { camera: 0, x: 1, y: 2, z: 3 }
 
 /** @internal — exported for the tag-sync test only. */
 export const _particleTags = {
@@ -49,7 +54,8 @@ export const _particleTags = {
   SPACE: TAG_SPACE, INHERIT_VELOCITY: TAG_INHERIT_VELOCITY, RATE_DISTANCE: TAG_RATE_DISTANCE,
   RENDER_MODE: TAG_RENDER_MODE, MESH_GEOMETRY: TAG_MESH_GEOMETRY,
   ANGULAR_VELOCITY: TAG_ANGULAR_VELOCITY, GROUND: TAG_GROUND, VELOCITY_LIFE: TAG_VELOCITY_LIFE,
-  ORDER: TAG_ORDER,
+  ORDER: TAG_ORDER, SMOOTH_PATH: TAG_SMOOTH_PATH, RIBBON_ORIENT: TAG_RIBBON_ORIENT,
+  LIT: TAG_LIT,
 }
 
 // --- curve builders -----------------------------------------------------------------------------
@@ -286,11 +292,29 @@ export type ParticlesOptions = ParticlesMaterialOptions & {
    *  spread evenly along the path — trail density independent of speed, no per-frame clumps.
    *  Meant for `space: 'world'`. */
   rateOverDistance?: number
+  /** Spread those spawn points along a CURVE through the emitter's recent path instead of the
+   *  straight line between where it was last frame and where it is now. A straight line cuts the
+   *  corner by however far the path bows inside one frame, which grows with the frame TIME — so a
+   *  fast curving emitter looks faceted, and looks worse the slower the machine. Default false
+   *  (the straight line); costs three stored positions and one curve evaluation per spawn.
+   *
+   *  The curve needs a point one frame AHEAD, so each frame's spawns are placed provisionally and
+   *  nudged into place on the next frame, once it exists. Nothing else observes them in between. */
+  smooth?: boolean
   /** Draw order among blended systems at the same depth — higher draws later, i.e. on top (Unity's
    *  sortingOrder). Systems are depth-sorted by their node, so the emitters of one effect tie and
    *  without this the engine picks who covers whom per frame (smoke popping over a fireball).
    *  Default 0; a fireball wants 2, its smoke 1, a smoke trail -1. */
   order?: number
+  /** Sprites take the light of the PLACE each one is in — the level's baked light grid (`env.lightmap.volume`).
+   *  A sprite is unlit: its colour is the picture, which is right for fire and wrong for dust — a puff kicked up
+   *  under an awning glows as if it stood in the sun. With `lit` every particle's colour is multiplied by the light
+   *  where it is, relative to the level's OPEN ground: exactly the authored colour out in the sun, the ambient's
+   *  share of it (tinted the way the shade is) under a roof — per particle, so a trail of puffs laid from the sun
+   *  into the shade is lit along its length. Author the colour for the open; nothing else to tune. Without a grid
+   *  — a level with no bake, a host that has none — the colours are drawn as authored. Points, quads, stretch and
+   *  `Trail`; mesh particles are lit by their material. Default false. */
+  lit?: boolean
   /** Coarse draw order among ALL blended draws, 0 (first) … 7 (last) — see `Mesh.renderPriority`.
    *  Default 5: meshes sit at 4 and decals at 3, so smoke covers a car's glass and its skid marks
    *  whatever the camera does (the engine's depth sort compares object centres, and an emitter's
@@ -477,7 +501,9 @@ export class Particles extends Node {
     if (options.space !== undefined) out.push(TAG_SPACE, 1, options.space === "world" ? 1 : 0)
     if (options.inheritVelocity !== undefined) out.push(TAG_INHERIT_VELOCITY, 1, options.inheritVelocity)
     if (options.rateOverDistance !== undefined) out.push(TAG_RATE_DISTANCE, 1, options.rateOverDistance)
+    if (options.smooth !== undefined) out.push(TAG_SMOOTH_PATH, 1, options.smooth ? 1 : 0)
     if (options.order !== undefined) out.push(TAG_ORDER, 1, options.order)
+    if (options.lit !== undefined) out.push(TAG_LIT, 1, options.lit ? 1 : 0)
     if (options.rate !== undefined) out.push(TAG_RATE, 1, options.rate)
     if (options.shape !== undefined) pushShape(out, options.shape)
     if (options.velocityOverLife !== undefined) pushVelocityLife(out, options.velocityOverLife)
@@ -530,7 +556,11 @@ export class Particles extends Node {
   set space(val: "local" | "world") { this._send([ TAG_SPACE, 1, val === "world" ? 1 : 0 ]) }
   set inheritVelocity(val: number) { this._send([ TAG_INHERIT_VELOCITY, 1, val ]) }
   set rateOverDistance(val: number) { this._send([ TAG_RATE_DISTANCE, 1, val ]) }
+  /** Lay a frame's spawns along a curve through the emitter's path, not the straight chord. */
+  set smooth(val: boolean) { this._send([ TAG_SMOOTH_PATH, 1, val ? 1 : 0 ]) }
   set order(val: number) { this._send([ TAG_ORDER, 1, val ]) }
+  /** Colours × the baked light where each particle is — see `ParticlesOptions.lit`. */
+  set lit(val: boolean) { this._send([ TAG_LIT, 1, val ? 1 : 0 ]) }
   /** Coarse draw order, 0 … 7 — see `Mesh.renderPriority`. Write-only. */
   set renderPriority(v: number) {
     if (_creator.setRenderPriority) _creator.setRenderPriority(this.id, Math.max(0, Math.min(7, Math.round(v))))
@@ -620,8 +650,31 @@ export type TrailOptions = Omit<ParticlesMaterialOptions, "render" | "stretch">
   width?: ParticleValue
   /** Minimum emitter movement (world units) between recorded points. Default 0.05. */
   minDistance?: number
-  /** Point capacity (default 128). */
+  /** Point capacity (default 128). A spawn that does not fit is DROPPED, so a fast emitter at a
+   *  small `minDistance` wants headroom: a sword tip covers metres inside one `time` window. */
   maxPoints?: number
+  /** Follow a CURVE through the emitter's recent path instead of the straight line between frames.
+   *  A trail is where this shows most — the strip is the path — and it shows worse the lower the
+   *  frame rate, since a longer frame bows further off its own chord. Default false; see
+   *  `ParticlesOptions.smooth`. */
+  smooth?: boolean
+  /** The strip takes the baked light of the place each of its points is at — `ParticlesOptions.lit`. Smoke and
+   *  dust trails; leave it off for a glowing one. Default false. */
+  lit?: boolean
+  /** Which way the strip's WIDTH points.
+   *
+   *  `'camera'` (default) rolls the strip about its own length to stay flat to the viewer — it can
+   *  never disappear, which is why it is the default, but it bears no relation to the thing that drew
+   *  it. An AXIS (`'x'`/`'y'`/`'z'`) uses that axis of the emitter's own transform, as it was when
+   *  each point was laid: on a node riding a sword's blade, `'z'` (the blade) makes the strip the
+   *  surface the blade actually swept, and `width` stops being a made-up number — it is the blade. */
+  orient?: "camera" | "x" | "y" | "z"
+  /** With `orient` on an axis: the floor under the strip's APPARENT width, 0..1 of its real width,
+   *  below which it rolls back toward the camera. An honestly oriented strip goes edge-on — and
+   *  vanishes — whenever the swing happens in the plane of view; this is the hybrid that keeps it
+   *  readable. 0 = never roll (honest, and it will vanish), 1 = always (the same as `'camera'`).
+   *  Default 0.4: a sweep still reads as a sweep, and a swing toward the camera still shows. */
+  faceCamera?: number
   color?: ParticleColor
   /** Opacity along the trail. Defaults to fading the tail out (`curve().to(0)`). */
   opacity?: ParticleValue
@@ -635,6 +688,8 @@ export type TrailOptions = Omit<ParticlesMaterialOptions, "render" | "stretch">
 export class Trail extends Node {
   private _material: Material
   private _rateDistance: number
+  private _orient = 0
+  private _faceCamera = 0.4
 
   constructor(options: TrailOptions = {}) {
     super()
@@ -650,6 +705,13 @@ export class Trail extends Node {
       TAG_RATE_DISTANCE, 1, this._rateDistance,
       TAG_LIFETIME, 2, time, time,
     ]
+    if (options.smooth) out.push(TAG_SMOOTH_PATH, 1, 1)
+    if (options.lit) out.push(TAG_LIT, 1, 1)
+    if (options.orient !== undefined || options.faceCamera !== undefined) {
+      this._orient = RIBBON_AXIS[options.orient ?? "camera"]
+      if (options.faceCamera !== undefined) this._faceCamera = options.faceCamera
+      out.push(TAG_RIBBON_ORIENT, 2, this._orient, this._faceCamera)
+    }
     pushParam(out, 0, options.width ?? 0.1)
     pushParam(out, 2, options.opacity ?? curve().to(0))
     if (options.color !== undefined) pushColor(out, options.color)
@@ -686,6 +748,22 @@ export class Trail extends Node {
     this._send([ TAG_RATE_DISTANCE, 1, this._rateDistance ])
   }
 
+  /** Follow a curve through the emitter's path instead of the straight chord between frames. */
+  set smooth(val: boolean) { this._send([ TAG_SMOOTH_PATH, 1, val ? 1 : 0 ]) }
+  set lit(val: boolean) { this._send([ TAG_LIT, 1, val ? 1 : 0 ]) }
+
+  /** Which way the strip's width points — see `TrailOptions.orient`. Keeps the current `faceCamera`. */
+  set orient(val: "camera" | "x" | "y" | "z") {
+    this._orient = RIBBON_AXIS[val]
+    this._send([ TAG_RIBBON_ORIENT, 2, this._orient, this._faceCamera ])
+  }
+
+  /** The hybrid's floor — see `TrailOptions.faceCamera`. */
+  set faceCamera(val: number) {
+    this._faceCamera = val
+    this._send([ TAG_RIBBON_ORIENT, 2, this._orient, val ])
+  }
+
   /** Pause/resume laying down points — existing ones still age out, so the trail fades naturally
    *  after e.g. a sword swing ends. */
   set emitting(val: boolean) { this._send([ TAG_RATE_DISTANCE, 1, val ? this._rateDistance : 0 ]) }

package/src/gl/Scene.ts

@@ -177,7 +177,8 @@ const installRenderSyncedFrames = (): void => {
 export class Scene implements Presentable {
   /** @internal native scene handle. */
   readonly _id: number
-  /** @internal the IBL intensity this scene was built with (Lightmap.load's ambient floor). */
+  /** @internal what `environmentIntensity` currently asks for — the accessor's backing field, so it
+   *  answers on hosts whose engine has no live setter too. */
   _environmentIntensity = 20000
   readonly camera: Camera
   /** The listener + global 3D audio knobs (docs/audio-plan.md). */
@@ -309,6 +310,26 @@ export class Scene implements Presentable {
   setBloom(enabled: boolean, intensity = 0.2): void {
     _creator.setBloomOptions(this._id, enabled, intensity, 1)
   }
+  /**
+   * How bright the environment (IBL) lights the scene, in lux — `SceneOptions.environmentIntensity`
+   * after the fact. Live: it changes the probe's intensity, not the probe, so it costs nothing and
+   * can be dragged. (`setDefaultIbl`, the call that installs a probe, rebuilds the cubemap from the
+   * ktx every time — never drive a slider through a scene option that has to re-open.)
+   *
+   * `lecodes lightmap bake` reads the same number off the live probe, so a scene dimmed here bakes
+   * dimmed. Hosts without the call keep whatever the scene opened with, and the getter still
+   * reports what was asked for.
+   */
+  get environmentIntensity(): number { return this._environmentIntensity }
+  set environmentIntensity(lux: number) {
+    this._environmentIntensity = lux
+    if (_creator.setEnvironmentIntensity) _creator.setEnvironmentIntensity(this._id, lux)
+    else if (!Scene._warnedEnvIntensity) {
+      Scene._warnedEnvIntensity = true
+      console.warn("[scene] this host has no setEnvironmentIntensity — environmentIntensity stays as the scene opened")
+    }
+  }
+  private static _warnedEnvIntensity = false
   /** The scene's stencil buffer on / off (see `SceneOptions.stencil`). */
   setStencil(enabled: boolean): void {
     if (_creator.setSceneStencil) _creator.setSceneStencil(this._id, enabled)
@@ -367,6 +388,18 @@ export class Scene implements Presentable {
     return new Promise<void>((res) => _creator.warmRender(this._id, res))
   }
 
+  /** Precompile the scene's shader variants so nothing is compiled mid-game. Every material the host
+   *  knows is queued for the sun / shadow / fog / skinning variants and the dynamic-light key — the
+   *  first point light (a muzzle flash, an explosion) would otherwise rebuild every lit shader in view
+   *  on that frame. Call it once the sun and fog are set, typically under a loading screen; materials
+   *  loaded later are queued in the background as they are created. Resolves at once on a host
+   *  without the bridge. */
+  precompileShaders(): Promise<void> {
+    const fn = _creator.precompileShaders
+    if (!fn) return Promise.resolve()
+    return new Promise<void>((res) => fn.call(_creator, this._id, res))
+  }
+
   // ---- Presentable (docs/navigation-presentable-plan.md) ----
   // A scene is a destination like a screen: opening it replaces whatever is visible (suspending
   // an active Router until Router.restore()), and it can be pushed onto the Router stack. The

package/src/gl/animation/AnimationClip.ts

@@ -82,6 +82,8 @@ export class AnimationClip {
   readonly _index: number
   /** @internal events: seconds + name, sorted (the engine gets them normalized via setClipEvents). */
   _events: { t: number, name: string }[] = []
+  /** @internal anchor spans per bone, seconds (the engine gets them normalized via setClipAnchors). */
+  _anchors: { bone: string, donor: string, spans: { from: number, to: number, socket: string, rotation: number, pin: number }[] }[] = []
 
   private constructor(set: number, index: number, info: ClipInfo) {
     this._set = set
@@ -119,6 +121,48 @@ export class AnimationClip {
     _creator.setClipEvents(this._set, this._index, new Float32Array(this._events.map((e) => (d > 0 ? e.t / d : 0))))
   }
 
+  /** ANCHOR SPANS for a bone — what an anchored IK chain ending in `bone` rides while this clip plays
+   *  (`IK.TwoBone` with `anchor`; the sockets come from `anim.sockets(...)`). `donor` names the socket
+   *  set of the gun the take was AUTHORED on ('' = the live set: no delta); `spans` = `[from, to,
+   *  socket, rotation?, pin?]` in SECONDS — the socket the hand is on through that window (`''` = free:
+   *  it rides the joint itself), `rotation` 0..1 how much of the socket's turn it takes (default 1),
+   *  `pin` 0..1 how much it sits ON the socket instead of keeping its own relation to it (default 0: a
+   *  magazine is REACHED, and the take's motion is what carries the hand there).
+   *  Gaps between spans = the chain's own socket, pinned by the chain's `anchorPin` — that is where a
+   *  hand holding the gun is nailed to the grip, so the layers below cannot slide it. A clip WITHOUT
+   *  anchors takes no part: the hand keeps the take's own relation to the gun. Part of the clip, like
+   *  events; `AnimationClip.from` carries them re-timed. Chainable.
+   *    reload.anchors('hand_l', { donor: 'tr15', spans: [[0.9, 1.4, 'mag'], [1.4, 2.0, ''], [2.0, 2.4, 'mag'], [2.4, 2.7, 'bolt']] }) */
+  anchors(bone: string, def: { donor?: string, spans?: readonly (readonly [number, number, string, number?, number?])[] }): this {
+    const spans = (def.spans ?? []).map(([ from, to, socket, rotation, pin ]) => ({
+      from: Math.min(Math.max(0, from), this.duration), to: Math.min(Math.max(0, to), this.duration), socket,
+      rotation: rotation ?? 1, pin: pin ?? 0,
+    })).filter((s) => s.to > s.from).sort((a, b) => a.from - b.from)
+    const rec = { bone, donor: def.donor ?? "", spans }
+    const i = this._anchors.findIndex((a) => a.bone === bone)
+    if (i >= 0) this._anchors[i] = rec
+    else this._anchors.push(rec)
+    this._pushAnchors(rec)
+    return this
+  }
+  /** Drop a bone's anchor spans. */
+  clearAnchors(bone: string): this {
+    this._anchors = this._anchors.filter((a) => a.bone !== bone)
+    _creator.setClipAnchors?.(this._set, this._index, bone, "", "", new Float32Array(0))
+    return this
+  }
+  private _pushAnchors(a: { bone: string, donor: string, spans: { from: number, to: number, socket: string, rotation: number, pin: number }[] }): void {
+    const d = this.duration
+    const spans = new Float32Array(a.spans.length * 4)
+    a.spans.forEach((s, i) => {
+      spans[i * 4] = d > 0 ? s.from / d : 0
+      spans[i * 4 + 1] = d > 0 ? s.to / d : 0
+      spans[i * 4 + 2] = s.rotation
+      spans[i * 4 + 3] = s.pin
+    })
+    _creator.setClipAnchors?.(this._set, this._index, a.bone, a.donor, a.spans.map((s) => s.socket).join("\n"), spans)
+  }
+
   /** Load ONE clip from a GLB: the file's only/first clip, or the one named / at the given index. */
   static load(source: string | FetchResponse, clip?: string | number): Promise<AnimationClip> {
     return AnimationClip._loadSet(source).then(([setId, infos]) => {
@@ -200,6 +244,14 @@ export class AnimationClip {
     out._events = windowed
       ? clip._events.filter((ev) => ev.t >= st - 1e-6 && ev.t <= e + 1e-6).map((ev) => ({ t: Math.min(Math.max(0, ev.t - st), e - st), name: ev.name }))
       : clip._events.map((ev) => ({ ...ev }))
+    // the anchor spans too: clipped to the window and re-timed (a mirrored clip keeps its bone names —
+    // mirror the sockets yourself if a hand's anchors must swap sides)
+    for (const a of clip._anchors) {
+      const spans = windowed
+        ? a.spans.map((s) => ({ ...s, from: Math.max(0, s.from - st), to: Math.min(e - st, s.to - st) })).filter((s) => s.to > s.from)
+        : a.spans.map((s) => ({ ...s }))
+      if (spans.length > 0 || a.donor) out.anchors(a.bone, { donor: a.donor, spans: spans.map((s) => [ s.from, s.to, s.socket, s.rotation ] as const) })
+    }
     return out
   }
 

package/src/gl/animation/Animator.ts

@@ -17,9 +17,12 @@
 // default. A clip may be replaced at any time; a one-shot on a layer with no loop holds its last frame.
 //
 // The surface, top to bottom: clips → playing → root motion → the feet and the warp (`anim.feet`,
-// `anim.warp` — locomotion's post-processing of the pose) → level of detail → engine-facing.
+// `anim.warp` — locomotion's post-processing of the pose) → sockets (what IK chains ride) → level of
+// detail → engine-facing.
 
 import { Aspect } from "../../core/Aspect"
+import { Vec3, type Vec3Like } from "../../math/vec"
+import { Quat, type QuatLike } from "../../math/quat"
 import type { Node } from "../Node"
 import type { AnimationClip } from "./AnimationClip"
 import { Core, type ActiveClip, type ClipInfo, type ClipEventHandler, type LayerOptions, type LoopDef, type LoopOptions, type PlayOptions, type StopOptions } from "./core"
@@ -122,6 +125,41 @@ export class Animator extends Aspect<"anim", Node> {
    *  turn too); on for a rig whose root carries the heading (`lecodes assets retarget --root-rotation yaw`). */
   get rootRotation(): boolean { return this._rootRotation }
   set rootRotation(on: boolean) { this._rootRotation = on; if (this._rootMotion) this._c.setRootMotion(true, on) }
+  /** The body's WORLD velocity this frame (m/s): what `anim.warp`'s stride and orientation fit the clips
+   *  to. A `Locomotion` feeds it itself; when you drive the gait by hand set it every frame (the
+   *  CharacterController's velocity, or your own). Reads back the last value fed. */
+  get motion(): readonly [number, number, number] { return this._motion }
+  set motion(v: { x: number, y: number, z: number } | readonly [number, number, number]) {
+    const [ x, y, z ] = Array.isArray(v) ? v as readonly [number, number, number] : [ (v as { x: number }).x, (v as { y: number }).y, (v as { z: number }).z ]
+    this._motion = [ x, y, z ]
+    this._c.setMotion(x, y, z)
+  }
+  private _motion: readonly [number, number, number] = [ 0, 0, 0 ]
+
+  // ---- sockets (what anchored IK chains ride — IK.ts) ---------------------------------------------
+  /** SOCKETS: named frames on a bone of this rig — a weapon's grip / magazine / bolt empties, placed in
+   *  the scene editor. A NODE socket is read by the engine every frame (a socket on a moving part
+   *  follows it); a `{ position, quaternion }` one is fixed in the bone's space. The default set is the
+   *  LIVE one (the weapon in the hands); `set: 'tr15'` names a DONOR set — the same sockets on the gun a
+   *  take was authored on, which a clip's `anchors()` refer to. Chainable.
+   *    arms.anim.sockets('ik_hand_gun', { grip_r: w.gripR, grip_l: w.gripL, mag: w.mag })
+   *    arms.anim.sockets('ik_hand_gun', { grip_l: { position: [0.03, -0.12, -0.05] } }, { set: 'tr15' }) */
+  sockets(joint: Node | string, table: Record<string, Node | { position?: Vec3Like, quaternion?: QuatLike }>, options: { set?: string } = {}): this {
+    const bone = typeof joint === "string" ? this.node.bone(joint) : joint
+    if (!bone) { console.warn(`Animator.sockets: no bone '${String(joint)}' under ${this.node.name || "the node"}`); return this }
+    const set = options.set ?? ""
+    for (const [ name, at ] of Object.entries(table)) {
+      if (typeof (at as Node).id === "number") this._c.setSocket(set, name, bone.id, (at as Node).id, null)
+      else {
+        const o = at as { position?: Vec3Like, quaternion?: QuatLike }
+        const p = new Vec3(o.position ?? [ 0, 0, 0 ]), q = o.quaternion ? new Quat(o.quaternion) : Quat.identity
+        this._c.setSocket(set, name, bone.id, 0, new Float32Array([ p.x, p.y, p.z, q.x, q.y, q.z, q.w ]))
+      }
+    }
+    return this
+  }
+  /** Drop a socket (the live set, or `set`). */
+  removeSocket(name: string, set = ""): this { this._c.removeSocket(set, name); return this }
 
   // ---- level of detail --------------------------------------------------------------------------
   /** `'auto'` (default): a character small on screen or out of view is evaluated every 2nd / 4th frame
@@ -130,9 +168,11 @@ export class Animator extends Aspect<"anim", Node> {
   get lod(): "auto" | "full" { return this._lod }
   set lod(v: "auto" | "full") { this._lod = v; _pushLod(this.node) }
 
-  // ---- engine-facing (a Locomotion, a bench) --------------------------------------------------
+  // ---- engine-facing (a Locomotion, a bench, the IK aspects) ----------------------------------
   /** The native animator's id — 0 until something is played or bound. */
   get _id(): number { return this._c.id }
+  /** @internal the engine-facing core (IK.ts) */
+  get _core(): Core { return this._c }
   /** Bind a clip to the base layer without playing it; its native slot (-1 = no such clip). */
   _slot(clip: string | number): number { return this._c.slotIndex(clip) }
 }

package/src/gl/animation/DynamicBone.ts

@@ -36,12 +36,14 @@ export type DynamicBoneFloor = "none" | "probe" | number | Vec3Like
  *  on the standard humanoid bones (hips, spine, head, limbs — the Ragdoll's layout); `'none'`; or the
  *  nodes carrying the colliders to use. */
 export type DynamicBoneColliders = "auto" | "humanoid" | "none" | Node[]
-/** The cloth's OUTSIDE, which makes every collider one-sided: `'none'` = a collider pushes a bone to its
- *  nearest surface (tails, ropes); `'auto'` = away from the root bone's own axis (a cloak's strips round a
- *  spine face out from it); a vector = a fixed direction in the root bone's frame (a cape on the back:
- *  `[0, 0, -1]`). With a side the body is under the cloth by definition: an arm that swung through the
- *  cape pushes it away, and a bone that ended up inside a capsule leaves it on the outside — never
- *  through it to be held against the chest from the wrong side. */
+/** The cloth's SIDE of every collider marked `oneSided`: `'none'` = no side, every collider pushes a bone to
+ *  its nearest surface (tails, ropes); `'auto'` = away from the root bone's own axis (a cloak's strips round
+ *  a spine face out from it); a vector = a fixed direction in the root bone's frame (a cape hanging BEHIND
+ *  the arms: the body's backward). A one-sided collider that is moving AWAY from that side — an arm swinging
+ *  forward under the cape — puts a bone it has run into over to the side instead of carrying it: the arm
+ *  passes through the cloth and the cape hangs behind it again, instead of being dragged round the body.
+ *  Still, or moving toward the cloth, it pushes like any other collider, so cloth draped on an arm at rest
+ *  stays where it is. Two-sided colliders (the body's) never read the side. */
 export type DynamicBoneSide = "none" | "auto" | Vec3Like
 
 const VERSION = 1
@@ -82,12 +84,17 @@ export class DynamicBoneCollider extends Aspect<"dynamicBoneCollider", Node> {
   end?: Vec3Like
   /** The bone the capsule reaches (its origin), instead of `end`. */
   to?: string
+  /** ONE-SIDED: the cloth belongs on the chain's `side` of this capsule (see DynamicBone.side). While the capsule
+   *  moves away from that side it puts a bone it has run into over to the side instead of carrying it — an arm
+   *  under a cape may push the cape back, never drag it forward round the body. Needs a `side` on the DynamicBone. */
+  oneSided = false
 
   static fields: FieldMeta<DynamicBoneCollider> = {
     radius: { min: 0, max: 2, step: 0.005 },
     offset: { hidden: true },
     end: { hidden: true },
     to: { hidden: true },
+    oneSided: { label: "One-sided" },
   }
 
   private _id = 0
@@ -109,14 +116,14 @@ export class DynamicBoneCollider extends Aspect<"dynamicBoneCollider", Node> {
   onAttach(): void {
     if (!supported()) return
     const [ a, b ] = this._segment()
-    this._id = _creator.dynamicBoneColliderCreate!(this.node.id, a.x, a.y, a.z, b.x, b.y, b.z, this.radius)
+    this._id = _creator.dynamicBoneColliderCreate!(this.node.id, a.x, a.y, a.z, b.x, b.y, b.z, this.radius, this.oneSided ? 1 : 0)
     DynamicBone._collidersChanged()
   }
 
   onReconfigure(): void {
     if (!this._id) return
     const [ a, b ] = this._segment()
-    _creator.dynamicBoneColliderSet!(this._id, a.x, a.y, a.z, b.x, b.y, b.z, this.radius)
+    _creator.dynamicBoneColliderSet!(this._id, a.x, a.y, a.z, b.x, b.y, b.z, this.radius, this.oneSided ? 1 : 0)
   }
 
   onDetach(): void {
@@ -149,7 +156,8 @@ export class DynamicBone extends Aspect<"dynamicBone", Node> {
   mass: DynamicBoneCurve = 1
   /** Bones (by name) that ride the animation exactly while their subtrees still simulate: a sheet's
    *  several roots under one anchor (a cloak's seven strips under the spine), so ONE chain owns them all
-   *  and `link` ties neighbouring strips. */
+   *  and `link` ties neighbouring strips — neighbours in THIS order, so list the strips round the ring
+   *  (front-left … back … front-right); the front stays open. */
   pinned?: string[]
   /** Metres a PINNED bone may be pushed off its animated place by a collider — a soft pin. Its particle
    *  collides and takes the edge pushes like a free bone (the strip below hangs from where it IS) and is
@@ -365,13 +373,28 @@ export class DynamicBone extends Aspect<"dynamicBone", Node> {
     }
   }
 
-  /** Neighbour links: the bones at the same depth, in tree order, tied pairwise. */
+  /** Neighbour links: the bones at the same depth tied pairwise, the columns in the order of `pinned` (a cloak's
+   *  strips listed round the ring) — columns not listed there follow in tree order. Tree order alone is the
+   *  engine's child order, which for a GLB is the file's node order REVERSED (Filament prepends each child), so
+   *  strips added to a rig later were tied across the body instead of to their neighbours: the ermine's cloak
+   *  had one true neighbour pair out of eight, the rest were rods through the chest. */
   private _links(): Uint16Array | undefined {
     if (this.link <= 0) return undefined
+    const index = new Map<Node, number>(this._chain.map((n, i) => [ n, i ]))
+    const column = new Int32Array(this._chain.length).fill(-1)   // per bone: the chain index of its depth-1 ancestor
+    for (let i = 1; i < this._chain.length; i++) {
+      const p = index.get(this._chain[i]!.parent!) ?? 0
+      column[i] = this._depths[i] === 1 ? i : column[p]!
+    }
+    const ring = this.pinned ?? []
+    const key = (i: number): number => { const k = ring.indexOf(this._chain[column[i]!]!.name); return k < 0 ? ring.length + column[i]! : k }
     const byDepth = new Map<number, number[]>()
     this._depths.forEach((d, i) => { if (d > 0) (byDepth.get(d) ?? byDepth.set(d, []).get(d)!).push(i) })
     const pairs: number[] = []
-    for (const row of byDepth.values()) for (let k = 0; k + 1 < row.length; k++) pairs.push(row[k]!, row[k + 1]!)
+    for (const row of byDepth.values()) {
+      row.sort((a, b) => key(a) - key(b))
+      for (let k = 0; k + 1 < row.length; k++) pairs.push(row[k]!, row[k + 1]!)
+    }
     return pairs.length ? new Uint16Array(pairs) : undefined
   }
 
@@ -447,7 +470,7 @@ export class DynamicBone extends Aspect<"dynamicBone", Node> {
         const len = local.length()
         end = len > 1e-6 ? local.scale((p.length ?? 0.2) / len) : new Vec3(0, p.length ?? 0.2, 0)
       }
-      const id = _creator.dynamicBoneColliderCreate!(bone.id, 0, 0, 0, end.x, end.y, end.z, p.radius ?? 0.05)
+      const id = _creator.dynamicBoneColliderCreate!(bone.id, 0, 0, 0, end.x, end.y, end.z, p.radius ?? 0.05, 0)
       if (id) this._own.push(id)
     }
   }