reze-engine 0.65.0 → 0.66.0

package/src/graph/presets/unlit.ts

@@ -1,16 +1,12 @@
 // Unlit — the texture, at its own brightness, and nothing else.
 //
-// What FOOTAGE needs. A media plane carries pixels somebody already finished
-// somewhere else: a gradient painted in Photoshop, a title card, a rendered
-// element. Shading it is not a stylistic choice but a mistake — the scene's sun
+// What a picture needs: a media plane carries pixels somebody already finished
+// somewhere else — a gradient painted in Photoshop, a title card, a rendered
+// element. Shading it is not a stylistic choice but a mistake: the scene's sun
 // would dim one side of a card that has no side, and the world colour would
-// tint artwork whose colour is the point. Blender's answer is the same one:
-// wire the image straight into an Emission shader and let it out at the value
-// it was authored at.
-//
-// Emission rather than Principled with roughness 1: emission is radiance, so it
-// leaves the light loop entirely instead of being an unusually flat surface
-// inside it. That is also what lets a card sit in front of a lamp without
+// tint artwork whose colour is the point. Unity's answer is the same one, its
+// Unlit shader: the colour out at the value it was authored at, never in the
+// light loop — which is also what lets a card sit in front of a lamp without
 // picking up its highlight.
 
 import type { ShaderGraph } from "../schema"
@@ -26,12 +22,12 @@ export const UNLIT_GRAPH: ShaderGraph = {
     // one of its own.
     { id: "mat", type: "material_diffuse" },
     { id: "base", type: "mix/multiply", inputs: { fac: 1.0 } },
-    { id: "emit", type: "emission", inputs: { strength: 1.0 } },
+    { id: "emit", type: "vector_math/scale", inputs: { scale: 1.0 } },
   ],
   links: [
     { from: { node: "tex", socket: "color" }, to: { node: "base", socket: "a" } },
     { from: { node: "mat", socket: "color" }, to: { node: "base", socket: "b" } },
-    { from: { node: "base", socket: "color" }, to: { node: "emit", socket: "color" } },
+    { from: { node: "base", socket: "color" }, to: { node: "emit", socket: "a" } },
   ],
-  output: { node: "emit", socket: "color" },
+  output: { node: "emit", socket: "vector" },
 }

package/src/graph/registry.ts

@@ -116,18 +116,6 @@ const RAMP_OUTPUTS: Record<string, SockT> = { color: "color", alpha: "float", fa
 // routing through the BT.601 color→float conversion instead would change the value.
 const RAMP_SELECT = { color: ".rgb", alpha: ".a", fac_out: ".r" }
 
-/** Principled v2 reflectance, evaluated at compile time when it can be. */
-function foldSpecular(ior: string, level: string): string {
-  const i = Number(ior)
-  const l = Number(level)
-  if (!Number.isFinite(i) || !Number.isFinite(l)) return `principled_specular(${ior}, ${level})`
-  const r = (i - 1) / Math.max(i + 1, 1e-6)
-  // Snapped to 9 significant digits: the arithmetic leaves double noise
-  // (0.2² · 2 · 0.5 / 0.08 = 0.5000000000000001) that is meaningless in an f32
-  // and only makes the emitted shader harder to read.
-  return fmtFloat(Number(((r * r * 2 * Math.max(l, 0)) / 0.08).toPrecision(9)))
-}
-
 const uberNode = (slot: number): NodeSpec => ({
   inputs: {
     base: C([1, 1, 1], true),
@@ -176,6 +164,37 @@ const faceSdfNode = (slot: number): NodeSpec => ({
 })
 const FACE_SDF_NODES: Record<string, NodeSpec> = Object.fromEntries([0, 1, 2, 3].map((s) => [`ag_face_sdf/${s}`, faceSdfNode(s)]))
 
+// A packed property map on the slot the type names — the game's material
+// contract: R metal, G perceptual roughness (answered as smoothness, Unity's
+// word for 1 − r), B occlusion, A emission mask, each remapped through the
+// material's own min/max (see rz_property_map). The four
+// plain values are what the surface is WITHOUT a map, so one look serves a
+// converted set that brought maps and a hand-made stage that brought none.
+// Defaults are the game's: the full 0–1 range, and the glow off (min = max = 1).
+const propertyMapNode = (slot: number): NodeSpec => ({
+  inputs: {
+    uv: { type: "vector", contextDefault: "vec3f(input.uv, 0.0)" },
+    metallic: F(0),
+    smoothness: F(0.5),
+    occlusion: F(1),
+    emission: F(0),
+    metal_min: F(0),
+    metal_max: F(1),
+    rough_min: F(0),
+    rough_max: F(1),
+    ao_min: F(0),
+    ao_max: F(1),
+    emission_min: F(1),
+    emission_max: F(1),
+  },
+  outputs: { metallic: "float", smoothness: "float", occlusion: "float", emission: "float" },
+  outputSelect: { metallic: ".x", smoothness: ".y", occlusion: ".z", emission: ".w" },
+  emit: (a) =>
+    `rz_property_map(group_tex${slot}(${a.uv}.xy), rz_group_bound${slot}(), vec4f(${a.metallic}, ${a.smoothness}, ${a.occlusion}, ${a.emission}), ` +
+    `vec4f(${a.metal_min}, ${a.rough_min}, ${a.ao_min}, ${a.emission_min}), vec4f(${a.metal_max}, ${a.rough_max}, ${a.ao_max}, ${a.emission_max}))`,
+})
+const PROPERTY_MAP_NODES: Record<string, NodeSpec> = Object.fromEntries([0, 1, 2, 3].map((s) => [`property_map/${s}`, propertyMapNode(s)]))
+
 export const NODE_REGISTRY: Record<string, NodeSpec> = {
   // ── Context inputs (template locals; no emission) ──
   texture: {
@@ -409,19 +428,43 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
     outputs: { color: "color" },
     emit: (a) => `mix(${a.color}, rgb_curve(${a.color}, ${a.y0}, ${a.y1}, ${a.y2}, ${a.y3}, ${a.y4}), ${a.fac})`,
   },
-  // UV Map — one layer on a PMX, which is the mesh UV the texture node uses.
+  // UV Map — the mesh UV the texture node uses, and the second set: a PMX's
+  // second additional UV (xy) where it has one, else the first UV again.
   uv_map: {
     inputs: {},
-    outputs: { uv: "vector" },
-    contextOutputs: { uv: "vec3f(input.uv, 0.0)" },
+    outputs: { uv: "vector", uv2: "vector" },
+    contextOutputs: { uv: "vec3f(input.uv, 0.0)", uv2: "vec3f(input.uv2, 0.0)" },
+  },
+  // Whether each group image slot holds a real map, 1 or 0. A slot nobody
+  // filled is a 1×1 white stand-in, and white is not "no map" to a normal or
+  // a property map — this is how a look tells the two apart and keeps the
+  // surface's own normal where the model brought none.
+  image_bound: {
+    inputs: {},
+    outputs: { slot0: "float", slot1: "float", slot2: "float", slot3: "float" },
+    contextOutputs: {
+      slot0: "select(0.0, 1.0, rz_group_bound0())",
+      slot1: "select(0.0, 1.0, rz_group_bound1())",
+      slot2: "select(0.0, 1.0, rz_group_bound2())",
+      slot3: "select(0.0, 1.0, rz_group_bound3())",
+    },
   },
 
   // ── Normal Map, Vector Transform ──
+  // Strength scales the map's tilt, so above 1 steepens it (Unity's
+  // _NormalScale, Blender's strength); 0 is the surface's own normal.
   normal_map: {
     inputs: { color: C([0.5, 0.5, 1], true), strength: F(1) },
     outputs: { normal: "vector" },
     emit: (a) => `node_normal_map(${a.color}, ${a.strength}, n, input.worldPos, input.uv)`,
   },
+  // A normal map packed as game engines store one (DXT5nm/BC5: X in alpha, Y
+  // in green, Z rebuilt). Link the image's colour and its alpha.
+  "normal_map/packed": {
+    inputs: { color: C([1, 0.5, 1], true), alpha: F(0.5), strength: F(1) },
+    outputs: { normal: "vector" },
+    emit: (a) => `node_normal_map_packed(vec4f(${a.color}, ${a.alpha}), ${a.strength}, n, input.worldPos, input.uv)`,
+  },
   "vector_transform/world_to_camera": {
     inputs: { vector: V([0, 0, 0], true) },
     outputs: { vector: "vector" },
@@ -439,27 +482,20 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
   },
 
   // ── Shader nodes. Shaders travel as RGB here (see shader_to_rgb_diffuse), so
-  // a "transparent" shader is the colour that contributes nothing; the actual
-  // cutout is the group's alphaMode, which is where transparency belongs in a
-  // rasteriser without order-independent blending.
-  bsdf_transparent: { inputs: {}, outputs: { color: "color" }, emit: () => `vec3f(0.0)` },
-  bsdf_diffuse: {
-    inputs: { color: C([0.8, 0.8, 0.8], true) },
-    outputs: { color: "color" },
-    emit: (a) => `${a.color} * shader_to_rgb_lit(n, l, sun, amb, shadow)`,
-  },
 
   // ── Nodes with no meaning on a PMX, answered honestly with a constant ──
   // Each returns what Blender returns for the absent case, so a graph that reads
   // one degrades to a sensible look instead of failing to compile. Documented
   // rather than silently wrong.
   //
-  // attribute: MMD meshes carry no vertex colour layer, so Color reads white and
-  // Fac reads 1 — the identity for the multiply these usually feed.
+  // attribute: the vertex colour. A PMX carries none of its own, so a model
+  // keeps it in its first additional UV (RGBA) — what a converted game stage
+  // writes there, a plant's occlusion in the alpha. A model without one reads
+  // white and alpha 1, the identity for the multiply these usually feed.
   attribute: {
     inputs: {},
-    outputs: { color: "color", fac: "float" },
-    contextOutputs: { color: "vec3f(1.0)", fac: "1.0" },
+    outputs: { color: "color", fac: "float", alpha: "float" },
+    contextOutputs: { color: "input.vcolor.rgb", fac: "color_to_value(input.vcolor.rgb)", alpha: "input.vcolor.a" },
   },
   // object_info: one model, one instance — Random is the only field with a real
   // use (per-instance variation) and there are no instances to vary.
@@ -595,6 +631,66 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
   // Defaults are 104903's skin.
   ...UBER_NODES,
   ...FACE_SDF_NODES,
+  ...PROPERTY_MAP_NODES,
+
+  /**
+   * Lit — Unity's Lit (URP's PBR), term for term: what a stage, a prop or
+   * the weather is shaded with, so a surface authored with Unity's inputs
+   * looks here as it does there. See urp_lit in nodes.ts for the formula.
+   *
+   * smoothness is Unity's (1 − perceptual roughness). emission is added on
+   * top, as HDR colour. alpha < 1 is Transparent with Preserve Specular
+   * Lighting — the diffuse fades, the reflection does not; the `alpha`
+   * output is the coverage to hand the graph's opacity, on a group blending
+   * "premultiplied".
+   */
+  lit: {
+    inputs: {
+      base_color: C([0.8, 0.8, 0.8], true),
+      metallic: F(0),
+      smoothness: F(0.5),
+      /** A dielectric's reflectance, as Unreal's and HDRP's Specular: 0.5 is
+       *  URP's fixed 0.04, 1 is 0.08 — glossy cloth, lacquer, wet skin. */
+      specular: F(0.5),
+      occlusion: F(1),
+      emission: C([0, 0, 0]),
+      alpha: F(1),
+      normal: { type: "vector", contextDefault: "n" },
+    },
+    outputs: { color: "color", alpha: "float" },
+    outputSelect: { color: ".rgb", alpha: ".a" },
+    emit: (a) =>
+      `urp_lit(${a.base_color}, ${a.metallic}, ${a.smoothness}, ${a.specular}, ${a.occlusion}, ${a.emission}, ${a.alpha}, ` +
+      `${a.normal}, l, v, sun, amb, shadow, input.worldPos, true)`,
+    takesLight: true,
+  },
+
+  /**
+   * The scene's reflection along a direction — the stage's own reflection
+   * probe, box-projected to the stage's bounds, where the engine captured one;
+   * the sky where it did not. Roughness picks the blur on the game's curve.
+   * Its default vector is this surface's reflection, so a glass shell or a
+   * water surface wires only what it bends.
+   */
+  /**
+   * The highlights alone: the sun's and the lamps' specular on a GGX lobe
+   * (URP's, α = r²), untinted. A water or glass look that computes its own
+   * reflection multiplies this by its reflectance for the glints.
+   */
+  glossy_direct: {
+    inputs: { smoothness: F(0.9), normal: { type: "vector", contextDefault: "n" } },
+    outputs: { color: "color" },
+    emit: (a) => `rz_glossy_direct(${a.normal}, l, v, sun, shadow, input.worldPos, 1.0 - (${a.smoothness}))`,
+    takesLight: true,
+  },
+  reflection_probe: {
+    inputs: {
+      vector: { type: "vector", contextDefault: "reflect(-v, n)" },
+      smoothness: F(1),
+    },
+    outputs: { color: "color" },
+    emit: (a) => `rzProbeSpecular(${a.vector}, input.worldPos, 1.0 - (${a.smoothness}))`,
+  },
 
   // ── Blender 5.2 colour utilities ──
   separate_color: {
@@ -793,26 +889,6 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
     outputs: { color: "color" },
     emit: (a) => `${a.a} + vec3f(${a.b})`,
   },
-  // Blender Emission shader: color × strength. In the ShaderToRGB-era ports the
-  // emission result feeds a Mix Shader directly as radiance. Color may be a literal
-  // (body's rim tints) or linked.
-  emission: {
-    inputs: { color: C([1, 1, 1]), strength: F(1) },
-    outputs: { color: "color" },
-    emit: (a) => `${a.color} * ${a.strength}`,
-  },
-  // Blender Add Shader — radiance sum of two evaluated shading results.
-  add_shader: {
-    inputs: { a: C([0, 0, 0], true), b: C([0, 0, 0], true) },
-    outputs: { color: "color" },
-    emit: (a) => `${a.a} + ${a.b}`,
-  },
-  // Mix Shader — plain lerp between two evaluated shading results.
-  mix_shader: {
-    inputs: { fac: F(0.5), a: C([0, 0, 0], true), b: C([0, 0, 0]) },
-    outputs: { color: "color" },
-    emit: (a) => `mix(${a.a}, ${a.b}, ${a.fac})`,
-  },
 
   // ── View-dependent scalars ──
   fresnel: { inputs: { ior: F(1.45) }, outputs: { value: "float" }, emit: (a) => `fresnel(${a.ior}, n, v)` },
@@ -833,38 +909,19 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
     emit: (a) => `layer_weight_facing(${a.blend}, ${a.normal}, v)`,
   },
 
-  /**
-   * The world's radiance from a direction — Blender's Environment Texture, read
-   * off the scene's own sky rather than off an image a material carries.
-   *
-   * ITS DEFAULT VECTOR IS THE REFLECTION, which is the whole point: wire
-   * nothing and it answers what this surface reflects. The roughness input
-   * picks how blurred the answer is; at 0 it is a mirror.
-   *
-   * A scene with no HDRI has no sky to reflect, and this returns the flat world
-   * colour — the same value the ambient already carries, so such a scene looks
-   * exactly as it did.
-   */
-  environment: {
-    inputs: {
-      vector: { type: "vector", contextDefault: "reflect(-v, n)" },
-      roughness: F(0),
-    },
-    outputs: { color: "color" },
-    emit: (a) => `rzWorldSpecular(${a.vector}, ${a.roughness})`,
-  },
 
   // ── Lighting capture ──
   /**
-   * Shader → RGB on a white diffuse closure, reduced to a scalar.
-   *
-   * Rec.709 luminance, kept exactly as it was: every shipped preset ramps this,
-   * and changing the weights would move every terminator in the library.
+   * Lambert — URP's LightingLambert for the main light, plus the ambient:
+   * what a white surface facing `normal` receives. A toon look ramps `value`
+   * (its luminance) into a terminator, or tints by `color`. Shader Graph's
+   * custom-lighting idiom, in one node.
    */
-  shader_to_rgb_diffuse: {
-    inputs: {},
-    outputs: { value: "float" },
-    emit: () => `shader_to_rgb_diffuse(n, l, sun, amb, shadow)`,
+  lambert: {
+    inputs: { normal: { type: "vector", contextDefault: "n" } },
+    outputs: { color: "color", value: "float" },
+    outputSelect: { color: ".rgb", value: ".a" },
+    emit: (a) => `urp_lambert(${a.normal}, l, sun, amb, shadow)`,
   },
   /**
    * Hands this surface to the screen-space scattering pass: the colour passes
@@ -878,24 +935,6 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
     emit: (a) => `rz_subsurface(${a.strength}, ${a.color})`,
   },
 
-  /**
-   * The same closure as a COLOUR, which is what Blender's Shader to RGB
-   * actually returns.
-   *
-   * A warm sun against a cool ambient radiates warm light and cool shadow, and
-   * that colour IS the look in most of this style. Reducing it to luminance
-   * first — the only thing reachable before — leaves every ramp working on grey.
-   *
-   * Linking this into a scalar socket still yields a float, because Blender's
-   * own implicit Color → Value conversion (BT.601) happens at the link. So the
-   * two nodes differ only in whether the graph wants the colour or the scalar,
-   * and each gets Blender's answer for its own question.
-   */
-  shader_to_rgb: {
-    inputs: {},
-    outputs: { color: "color" },
-    emit: () => `shader_to_rgb_lit(n, l, sun, amb, shadow)`,
-  },
 
   // ── Vector ──
   separate_xyz: {
@@ -956,70 +995,6 @@ export const NODE_REGISTRY: Record<string, NodeSpec> = {
   // ── Principled BSDF (frozen 3.6 legacy-EEVEE semantics: eval_principled port) ──
   // normal defaults to the template's shading normal; link a bump/normal_map chain
   // to perturb it (body/cloth_rough noise bump).
-  /**
-   * Principled BSDF, Blender 5.2 socket names.
-   *
-   * v2 (4.0+) renamed most of what a graph touches and re-derived one of them,
-   * which is exactly where a transcribed port goes quietly wrong: Specular
-   * became "Specular IOR Level" and no longer sets reflectance directly — IOR
-   * does, and the level scales it. So f0 is computed the v2 way here, and the
-   * defaults land on 0.04 for ior 1.5 at level 0.5, matching both versions at
-   * their defaults while tracking v2 when a preset moves either.
-   *
-   * Emission Strength defaults to 0 in v2 where 3.6's Emission was visible, so a
-   * naive port turns every emissive material black. Following v2 means honouring
-   * that default and letting the preset say otherwise.
-   *
-   * Not implemented, and not silently wrong — a graph setting these gets the
-   * base BSDF rather than a wrong approximation of them: Coat, Transmission,
-   * Subsurface, Anisotropic, Thin Film. They need path-traced or
-   * multi-scatter machinery this renderer does not have.
-   */
-  principled: {
-    inputs: {
-      base_color: C([0.8, 0.8, 0.8], true),
-      metallic: F(0),
-      roughness: F(0.5),
-      ior: F(1.5),
-      specular_ior_level: F(0.5),
-      sheen_weight: F(0),
-      sheen_tint: F(0),
-      emission_color: C([1, 1, 1]),
-      emission_strength: F(0),
-      normal: { type: "vector", contextDefault: "n" },
-      /** Ours, not Blender's: caps firefly speculars from noise-bumped NDF
-       *  aliasing, which EEVEE hides behind TAA and we have none. */
-      spec_clamp: F(1e30),
-      /** Ours: how roughness picks the reflection's blur. 0 is the engine's
-       *  sqrt ramp; 1 is Unity's probe curve, p·(1.7−0.7p) mip-steps per
-       *  eighth, stopping where a cube's last face texel does — what a stage
-       *  ripped from a Unity game was authored against. See rzWorldSpecularLod. */
-      reflection_lod: F(0),
-      /** Ours: 1 shades the sun's and the lamps' highlights with URP's
-       *  direct-light BRDF, as a stage from a Unity game was lit — see bsdf_urp. */
-      unity_direct: F(0),
-    },
-    outputs: { color: "color" },
-    emit: (a) => {
-      // Fold the reflectance when both sockets are literals, which is nearly
-      // always. It keeps the emitted WGSL as tight as the 3.6 form was — and at
-      // the defaults it folds to exactly 0.5, which is what 3.6's Specular held,
-      // so the two versions agree byte-for-byte where a preset changed nothing.
-      const spec = foldSpecular(a.ior, a.specular_ior_level)
-      const bsdf =
-        `eval_principled(PrincipledIn(${a.base_color}, ${a.metallic}, ` +
-        `${spec}, ${a.roughness}, ` +
-        `${a.spec_clamp}, ${a.sheen_weight}, ${a.sheen_tint}, ${a.reflection_lod}, ${a.unity_direct}), ${a.normal}, l, v, sun, amb, shadow, input.worldPos)`
-      // v2 defaults Emission Strength to 0, which is the overwhelming case. Emit
-      // the term only when it can do something, so the common shader carries no
-      // dead add and the output stays readable.
-      const lit = a.emission_strength === "0.0" ? bsdf : `${bsdf} + ${a.emission_color} * ${a.emission_strength}`
-      // Unity mode also ends as SimPipeline's surfaces end: saturate()d, so no
-      // lit or glowing surface passes 1.0 before the post — its bloom works on
-      // what is left under that. A literal, as every stage graph states it.
-      return a.unity_direct === "1.0" ? `min(${lit}, vec3f(1.0))` : lit
-    },
-  },
 }
 
 // ─── Blender socket parity ────────────────────────────────────────────

package/src/graph/render-class.ts

@@ -12,8 +12,11 @@ export type RenderClass = "auto" | "eye" | "hair"
 export type AlphaMode = "opaque" | "hashed"
 
 /** How a group's colour meets the frame. "over" is the ordinary alpha blend;
- *  "additive" adds its light and never reads alpha — see StyleGroup.blend. */
-export type StyleBlend = "over" | "additive"
+ *  "additive" adds its light and never reads alpha; "premultiplied" takes a
+ *  colour already weighted by its own coverage (One, OneMinusSrcAlpha) — a
+ *  game's glass, whose reflection must not fade with its transparency. See
+ *  StyleGroup.blend. */
+export type StyleBlend = "over" | "additive" | "premultiplied"
 
 /** Descriptive manifest for hosts (reze-design) so the render-class picker is data-driven
  *  instead of hardcoding strings. The effect implementations stay engine-side; this only

package/src/graph/slots.ts

@@ -208,8 +208,12 @@ function epilogue(renderClass: RenderClass, alphaMode: AlphaMode, hasOpacity: bo
   const BURN = ` + RZ_BURN_COLOR * rz_burn`
   // The scene fog, last, as the game lays it over a lit surface; an
   // emission-only graph takes none (the game's effect shaders have no fog).
+  // A premultiplied colour takes its fog premultiplied too: the haze a pane
+  // adds is the haze over its own coverage, the rest arrives through what is
+  // behind it (the game scales its fog by the output alpha the same way).
+  const fogOver = blend === "premultiplied" ? " * out.color.a" : ""
   const FOG = takesLight
-    ? `  out.color = vec4f(mix(mix(out.color.rgb, light.fog[0].rgb, input.fog.x), light.fog[2].rgb, input.fog.y), out.color.a);\n`
+    ? `  out.color = vec4f(mix(mix(out.color.rgb, light.fog[0].rgb${fogOver}, input.fog.x), light.fog[2].rgb${fogOver}, input.fog.y), out.color.a);\n`
     : ""
   if (renderClass === "hair") {
     return `${ALBEDO}  var outAlpha = ${alphaBase};

package/src/model.ts

@@ -566,9 +566,11 @@ export class Model {
     rigidbodies: Rigidbody[] = [],
     joints: Joint[] = [],
     loadWarnings: string[] = [],
-    edgeScales: Float32Array | null = null
+    edgeScales: Float32Array | null = null,
+    additionalUvs: Float32Array[] = []
   ) {
     this.edgeScales = edgeScales
+    this.additionalUvs = additionalUvs
     // Store base vertex data (original positions before morphing)
     this.baseVertexData = new Float32Array(vertexData)
     this.vertexData = vertexData
@@ -1006,6 +1008,14 @@ export class Model {
 
   /** PMX per-vertex edge scale, when the source had one. */
   private edgeScales: Float32Array | null = null
+  private additionalUvs: Float32Array[]
+
+  /** A PMX additional UV channel (1–4) as loaded, four floats a vertex — or
+   *  null when the file has fewer. Its morphs (types 4–7) are in getMorphing(),
+   *  with uvOffsets; the engine applies neither, a native look reads both. */
+  getAdditionalUv(channel: number): Float32Array | null {
+    return this.additionalUvs[channel - 1] ?? null
+  }
   private outlineVertices: Float32Array<ArrayBuffer> | null = null
 
   /**
@@ -1132,6 +1142,28 @@ export class Model {
     return this.runtimeSkeleton.worldMatrices[idx].getPosition()
   }
 
+  /**
+   * The point `distance` model units down a bone's own axis, posed — where
+   * `#anchor <bone> along <d>` puts an effect. The axis is the bone's rest tail
+   * direction (the way a PMX editor draws it pointing) turned by the bone's
+   * pose, the same mapping the named-points tips use. Model space, like
+   * getBoneWorldPosition. A bone with no tail has no axis: the joint itself.
+   */
+  getBonePointAlong(boneName: string, distance: number): Vec3 | null {
+    const idx = this.runtimeSkeleton.nameIndex[boneName]
+    if (idx === undefined || idx < 0) return null
+    const w = this.runtimeSkeleton.worldMatrices[idx].values
+    const t = this.skeleton.bones[idx]?.tail
+    const len = t ? Math.hypot(t[0], t[1], t[2]) : 0
+    if (!t || len < 1e-6) return new Vec3(w[12], w[13], w[14])
+    const k = distance / len
+    return new Vec3(
+      w[12] + (w[0] * t[0] + w[4] * t[1] + w[8] * t[2]) * k,
+      w[13] + (w[1] * t[0] + w[5] * t[1] + w[9] * t[2]) * k,
+      w[14] + (w[2] * t[0] + w[6] * t[1] + w[10] * t[2]) * k,
+    )
+  }
+
   /**
    * A bone's forward axis, normalised — which way a foot points, where a head
    * looks. Model space, like getBoneWorldPosition: the caller composes the model

package/src/pmx-loader.ts

@@ -36,6 +36,10 @@ export class PmxLoader {
   private inverseBindMatrices: Float32Array | null = null
   private joints0: Uint16Array | null = null
   private weights0: Uint8Array | null = null
+  /** The PMX's additional UV channels (1–4), each four floats a vertex. The
+   *  engine's own shading reads none of them; a native look can name one as
+   *  the carrier of a game vertex stream (NativeLook.streams). */
+  private additionalUvs: Float32Array[] = []
   /** PMX per-vertex edge scale — the outline's width multiplier, as the
    *  game's outline takes vertex colour alpha. */
   private edgeScales: Float32Array | null = null
@@ -154,6 +158,7 @@ export class PmxLoader {
     const joints = new Uint16Array(count * 4)
     const weights = new Uint8Array(count * 4) // UNORM8, will be normalized to 255
     const edgeScales = new Float32Array(count)
+    this.additionalUvs = Array.from({ length: this.additionalVec4Count }, () => new Float32Array(count * 4))
 
     for (let i = 0; i < count; i++) {
       const px = this.getFloat32()
@@ -171,7 +176,10 @@ export class PmxLoader {
       // PMX UVs are in the same orientation as WebGPU sampling; no flip
       uvs.push(u, v)
 
-      this.offset += this.additionalVec4Count * 16
+      for (let k = 0; k < this.additionalVec4Count; k++) {
+        const a = this.additionalUvs[k]
+        for (let c = 0; c < 4; c++) a[i * 4 + c] = this.getFloat32()
+      }
       const type = this.getUint8()
       const base = i * 4
       // Initialize defaults
@@ -1142,7 +1150,8 @@ export class PmxLoader {
       this.rigidbodies,
       this.joints,
       this.warnings,
-      this.edgeScales
+      this.edgeScales,
+      this.additionalUvs
     )
   }
 

package/src/shaders/anchor-table.ts

@@ -23,6 +23,12 @@
 interface AnchorRequest {
   bone: string
   trail: boolean
+  /** Model units down the bone's own axis (`#anchor ... along d`); absent = 0,
+   *  the joint itself. */
+  along?: number
+  /** World units the bone must move before its trail keeps a point
+   *  (`trail step d`); absent = every 60 Hz tick. */
+  step?: number
 }
 
 /** The empty table — a scene with no effect installed asks for no bones. */
@@ -48,6 +54,11 @@ export interface AnchorTable {
  * Order is first-come, so a single effect gets the identity alias and the whole
  * mechanism is a no-op until a second effect exists — which is what makes this
  * safe to land before setEffects does.
+ *
+ * A point ALONG a bone is a different point: `#anchor 右手首 trail along 0.9`
+ * and a bare `#anchor 右手首` are two entries, keyed by bone and distance, since
+ * sharing one ring would hand one of them the other's path. So is a trail
+ * recorded at a different `step`: its ring keeps different points.
  */
 export function buildAnchorTable(requests: AnchorRequest[][], max: number): AnchorTable {
   const entries: AnchorRequest[] = []
@@ -58,7 +69,8 @@ export function buildAnchorTable(requests: AnchorRequest[][], max: number): Anch
   for (let e = 0; e < requests.length; e++) {
     const local: number[] = []
     for (const req of requests[e]) {
-      let g = index.get(req.bone)
+      const key = req.along || req.step ? `${req.bone}\u0000${req.along ?? 0}\u0000${req.step ?? 0}` : req.bone
+      let g = index.get(key)
       if (g === undefined) {
         if (entries.length >= max) {
           // Refused, and the effect still installs: an effect that loses one of
@@ -69,8 +81,8 @@ export function buildAnchorTable(requests: AnchorRequest[][], max: number): Anch
           continue
         }
         g = entries.length
-        index.set(req.bone, g)
-        entries.push({ bone: req.bone, trail: req.trail })
+        index.set(key, g)
+        entries.push({ bone: req.bone, trail: req.trail, ...(req.along ? { along: req.along } : {}), ...(req.step ? { step: req.step } : {}) })
       } else if (req.trail) {
         // A later request for the same bone can only ever ADD the trail — the
         // ring is shared, and turning it on for one reader turns it on for all.