lecodes-assets 0.1.2 → 0.2.1

package/src/retarget/unityAnim.ts

@@ -0,0 +1,171 @@
+// Unity `.anim` (AnimationClip) reader — the clips that never made it into an FBX.
+//
+// Asset packs routinely ship a rig as FBX but its animations as Unity's own AnimationClip assets:
+// the polyperfect cat and all three dogs have EMPTY FBX files and eight `.anim` clips each (Sit,
+// Sleep, StandUp, …) that no glTF tool can see. When the package was serialised as text those are
+// plain YAML, so the curves are readable without Unity.
+//
+// Only what a retarget needs is parsed — rotation, position and scale curves keyed by transform
+// PATH — with a hand-rolled line scanner rather than a YAML library: these files run to tens of
+// thousands of lines (a 2.6 MB Sleep clip) and the shape is fixed and shallow.
+//
+// Two traps in the format:
+//   * `m_EditorCurves` / `m_EulerEditorCurves` repeat every curve component-by-component for the
+//     editor's graph view, and make up most of the file. Parsing past them double-counts everything,
+//     so the scan stops at the first section that is not one of the three curve lists.
+//   * `path` is the transform's FULL hierarchy path from the animator root
+//     (`actor:skin_Root_M/actor:skin_Spine1_M/…`), which only matches a rig by its LAST segment.
+import type { Clip, Pose, Quat, Rig, Vec3 } from './rig'
+import { qnorm, qslerp } from './rig'
+
+export interface UnityCurve { path: string; bone: string; times: number[]; values: number[][] }
+export interface UnityClip {
+  name: string
+  duration: number
+  sampleRate: number
+  rotation: UnityCurve[]
+  position: UnityCurve[]
+  scale: UnityCurve[]
+}
+
+const SECTIONS: Record<string, keyof Pick<UnityClip, 'rotation' | 'position' | 'scale'>> = {
+  m_RotationCurves: 'rotation',
+  m_PositionCurves: 'position',
+  m_ScaleCurves: 'scale',
+}
+
+const numbersIn = (s: string): number[] => {
+  const out: number[] = []
+  for (const m of s.matchAll(/-?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?/g)) out.push(Number(m[0]))
+  return out
+}
+
+/** Parse one `.anim` file's text. Throws when it is Unity's binary form rather than YAML. */
+export function parseUnityAnim(text: string, fallbackName = 'clip'): UnityClip {
+  if (!text.startsWith('%YAML')) {
+    throw new Error('not a text-serialised Unity asset — re-export the project with Asset Serialization = Force Text')
+  }
+  const clip: UnityClip = { name: fallbackName, duration: 0, sampleRate: 30, rotation: [], position: [], scale: [] }
+  const lines = text.split('\n')
+
+  let section: UnityCurve[] | null = null
+  let cur: UnityCurve | null = null
+  let pending: number | null = null            // time of a keyframe whose value line has not arrived
+  let stopTime: number | null = null
+  let inSettings = false
+
+  const flush = (): void => {
+    if (cur && section && cur.times.length) section.push(cur)
+    cur = null
+    pending = null
+  }
+
+  for (const raw of lines) {
+    const line = raw.replace(/\r$/, '')
+    // Top-level key (two-space indent): switches or ends a section.
+    const top = /^  (m_[A-Za-z]+):(.*)$/.exec(line)
+    if (top) {
+      flush()
+      const key = top[1]
+      inSettings = key === 'm_AnimationClipSettings'
+      if (key === 'm_Name') { clip.name = top[2].trim() || fallbackName; section = null; continue }
+      if (key === 'm_SampleRate') { clip.sampleRate = Number(top[2].trim()) || 30; section = null; continue }
+      const which = SECTIONS[key]
+      if (which) {
+        // `m_RotationCurves: []` — present but empty.
+        section = top[2].trim() === '[]' ? null : clip[which]
+        continue
+      }
+      // Anything else ends curve parsing; the editor mirrors below must not be read.
+      section = null
+      continue
+    }
+    if (inSettings) {
+      const st = /^    m_StopTime:\s*(\S+)/.exec(line)
+      if (st) stopTime = Number(st[1])
+      continue
+    }
+    if (!section) continue
+
+    if (/^  - curve:/.test(line)) { flush(); cur = { path: '', bone: '', times: [], values: [] }; continue }
+    if (!cur) continue
+
+    const p = /^    path:\s*(.*)$/.exec(line)
+    if (p) {
+      cur.path = p[1].trim()
+      cur.bone = cur.path.split('/').pop() ?? cur.path
+      flush()
+      continue
+    }
+    const t = /^\s+time:\s*(\S+)\s*$/.exec(line)
+    if (t) { pending = Number(t[1]); continue }
+    const v = /^\s+value:\s*\{(.*)\}\s*$/.exec(line)
+    if (v && pending !== null) {
+      cur.times.push(pending)
+      cur.values.push(numbersIn(v[1]))
+      pending = null
+    }
+  }
+  flush()
+
+  let maxT = 0
+  for (const list of [ clip.rotation, clip.position, clip.scale ]) {
+    for (const c of list) maxT = Math.max(maxT, c.times[c.times.length - 1] ?? 0)
+  }
+  clip.duration = stopTime !== null && stopTime > 0 ? stopTime : maxT
+  return clip
+}
+
+const sample = (c: UnityCurve, time: number, n: number): number[] => {
+  const last = c.times.length - 1
+  if (time <= c.times[0]) return c.values[0].slice(0, n)
+  if (time >= c.times[last]) return c.values[last].slice(0, n)
+  let i = 0
+  while (i < last && c.times[i + 1] < time) i++
+  const u = (time - c.times[i]) / (c.times[i + 1] - c.times[i] || 1)
+  const a = c.values[i], b = c.values[i + 1]
+  // Unity writes Hermite tangents too; linear/slerp between keys is what a 24-30 fps baked curve
+  // reproduces to well under a degree, and a retarget resamples at its own rate anyway.
+  if (n === 4) return qslerp(a as unknown as Quat, b as unknown as Quat, u)
+  return [ 0, 1, 2 ].map((k) => a[k] + (b[k] - a[k]) * u)
+}
+
+export interface AttachReport { name: string; bound: number; total: number; unbound: string[] }
+
+/**
+ * Turn parsed `.anim` clips into `Clip`s driving `rig`, binding each curve's LAST path segment to a
+ * bone name. Curves that bind nothing (a mesh group, a control rig) are counted and reported.
+ */
+export function attachUnityClips(rig: Rig, clips: UnityClip[]): { clips: Clip[]; report: AttachReport[] } {
+  const out: Clip[] = []
+  const report: AttachReport[] = []
+  for (const uc of clips) {
+    const bind = (list: UnityCurve[], n: number): { node: number; c: UnityCurve; n: number }[] => {
+      const res: { node: number; c: UnityCurve; n: number }[] = []
+      for (const c of list) {
+        const node = rig.index.get(c.bone)
+        if (node !== undefined) res.push({ node, c, n })
+      }
+      return res
+    }
+    const rot = bind(uc.rotation, 4), pos = bind(uc.position, 3), scl = bind(uc.scale, 3)
+    const total = uc.rotation.length + uc.position.length + uc.scale.length
+    const bound = rot.length + pos.length + scl.length
+    const unbound = [ ...uc.rotation, ...uc.position, ...uc.scale ]
+      .filter((c) => !rig.index.has(c.bone)).map((c) => c.bone)
+    report.push({ name: uc.name, bound, total, unbound: [ ...new Set(unbound) ] })
+    const base = rig.bind.local
+    out.push({
+      name: uc.name,
+      duration: uc.duration,
+      sample: (time: number): Pose => {
+        const pose: Pose = { t: base.t.map((v) => [ ...v ] as Vec3), r: base.r.map((v) => [ ...v ] as Quat), s: base.s.map((v) => [ ...v ] as Vec3) }
+        for (const { node, c } of rot) pose.r[node] = qnorm(sample(c, time, 4) as Quat)
+        for (const { node, c } of pos) pose.t[node] = sample(c, time, 3) as Vec3
+        for (const { node, c } of scl) pose.s[node] = sample(c, time, 3) as Vec3
+        return pose
+      },
+    })
+  }
+  return { clips: out, report }
+}

package/src/retarget/writeMarks.ts

@@ -0,0 +1,132 @@
+// Foot marks for a GLB that was NOT retargeted (a pack whose clips were captured on the model's own
+// rig): every clip is posed on the document's skeleton, the feet found by name (the same vocabulary
+// the runtime uses: a `foot`/`ankle` bone per side, its `toe`/`ball` child as the contact), the marks
+// measured (marks.ts) and written to the animation's `extras.lecodes.contacts` — the block
+// `retarget()` writes for the clips it produces.
+
+import type { Document } from '@gltf-transform/core'
+import { rigFromDocument, worldOf, type Vec3, type Quat } from './rig'
+import { headingCurve } from './heading'
+import { detectMarks, type ClipMarks, type FootTrack, type LevelKind } from './marks'
+
+export interface WriteMarksOptions {
+  /** the baked heading curve must END here (degrees, + = left) — a stop that turns; heading.ts `endAt` */
+  headingEnd?: number
+  /** which clips carry LEVELS: a staircase or a platform (see `stairsMatcher`) */
+  stairs?: (clip: string) => LevelKind
+  /** sampling rate of the measurement (default 60) */
+  fps?: number
+  /** only these clips (default: all) */
+  clips?: string[]
+  warn?: (message: string) => void
+}
+
+const lower = (s: string): string => s.toLowerCase()
+const shortName = (s: string): string => { const i = s.lastIndexOf(':'); return i >= 0 ? s.slice(i + 1) : s }
+/** 1 left / 2 right / 0 unknown — the runtime's `sideOf` (curves.cpp). */
+const sideOf = (full: string): 0 | 1 | 2 => {
+  const n = lower(shortName(full))
+  const has = (s: string): boolean => n.includes(s)
+  const starts = (s: string): boolean => n.startsWith(s)
+  const ends = (s: string): boolean => n.endsWith(s)
+  if (has('left') || starts('l_') || starts('l.') || starts('l ') || ends('_l') || ends('.l') || ends(' l') || has('lft')) return 1
+  if (has('right') || starts('r_') || starts('r.') || starts('r ') || ends('_r') || ends('.r') || ends(' r') || has('rgt')) return 2
+  const raw = shortName(full)
+  if (raw.length > 1 && raw[0] === 'l' && raw[1] === raw[1]!.toUpperCase() && raw[1] !== raw[1]!.toLowerCase()) return 1
+  if (raw.length > 1 && raw[0] === 'r' && raw[1] === raw[1]!.toUpperCase() && raw[1] !== raw[1]!.toLowerCase()) return 2
+  return 0
+}
+const isFootName = (s: string): boolean => { const n = lower(shortName(s)); return n.includes('foot') || n.includes('ankle') }
+const isToeName = (s: string): boolean => { const n = lower(shortName(s)); return n.includes('toe') || n.includes('ball') }
+const isEndName = (s: string): boolean => { const n = lower(shortName(s)); return n.endsWith('_end') || n.endsWith('end') && n.includes('toe') }
+const headingOf = (q: Quat): number => Math.atan2(2 * (q[0] * q[2] + q[3] * q[1]), 1 - 2 * (q[0] * q[0] + q[1] * q[1]))
+
+/** Measure and write every clip's marks. Returns one row per clip written. */
+export const writeMarks = (doc: Document, opts: WriteMarksOptions = {}): { clip: string; marks: ClipMarks; travel: [ number, number ] }[] => {
+  const rig = rigFromDocument(doc, 'marks')
+  const fps = opts.fps ?? 60
+  const depth = (i: number): number => { let d = 0; for (let p = rig.parents[i]!; p >= 0; p = rig.parents[p]!) d++; return d }
+  const isDesc = (j: number, anc: number): boolean => { for (let p = rig.parents[j]!; p >= 0; p = rig.parents[p]!) if (p === anc) return true; return false }
+  // the feet: per side the shallowest foot-named joint, its contact = the first toe-named descendant that is not a leaf end
+  const packFeet: { foot: number; contact: number }[] = [ { foot: -1, contact: -1 }, { foot: -1, contact: -1 } ]
+  const feet = packFeet
+  rig.names.forEach((n, i) => {
+    if (!n || !isFootName(n) || isEndName(n)) return
+    const s = sideOf(n)
+    if (!s) return
+    const f = feet[s - 1]!
+    if (f.foot < 0 || depth(i) < depth(f.foot)) f.foot = i
+  })
+  for (const f of feet) {
+    if (f.foot < 0) continue
+    for (let j = 0; j < rig.names.length; j++) if (isToeName(rig.names[j]!) && !isEndName(rig.names[j]!) && isDesc(j, f.foot)) { f.contact = j; break }
+    if (f.contact < 0) f.contact = f.foot
+  }
+  if (feet[0]!.foot < 0 && feet[1]!.foot < 0) throw new Error('writeMarks: no foot bones found (names with "foot"/"ankle" per side)')
+  const anims = doc.getRoot().listAnimations()
+  const nodes = doc.getRoot().listNodes()
+  const rows: { clip: string; marks: ClipMarks; travel: [ number, number ] }[] = []
+  for (const clip of rig.clips) {
+    if (opts.clips && !opts.clips.includes(clip.name)) continue
+    const anim = anims.find((a) => a.getName() === clip.name)
+    if (!anim) continue
+    // A GLB that merged several rigs (a donor built from many clip files) has several joints per
+    // name: use the feet THIS clip animates — the ones under a node with a channel — else the
+    // pack's feet found above (a native pack has one rig)
+    const animated = new Set<number>()
+    for (const ch of anim.listChannels()) { const i = nodes.indexOf(ch.getTargetNode()!); if (i >= 0) animated.add(i) }
+    const feet = packFeet.map((f) => ({ ...f }))
+    if (animated.size) {
+      const under = (j: number): boolean => { for (let p = j; p >= 0; p = rig.parents[p]!) if (animated.has(p)) return true; return false }
+      rig.names.forEach((n, i) => {
+        if (!n || !isFootName(n) || isEndName(n) || !under(i)) return
+        const sd = sideOf(n)
+        if (!sd) return
+        const f = feet[sd - 1]!
+        if (f.foot < 0 || !under(f.foot) || depth(i) < depth(f.foot)) { f.foot = i; f.contact = -1 }
+      })
+      for (const f of feet) {
+        if (f.foot < 0 || f.contact >= 0) continue
+        for (let j = 0; j < rig.names.length; j++) if (isToeName(rig.names[j]!) && !isEndName(rig.names[j]!) && isDesc(j, f.foot)) { f.contact = j; break }
+        if (f.contact < 0) f.contact = f.foot
+      }
+    }
+    // the clip's root: the shallowest joint it translates among the feet's ancestors (the hips when
+    // nothing above them moves) — travel and the `at` frame are measured against it
+    let rootIdx = -1
+    for (const ch of anim.listChannels()) {
+      if (ch.getTargetPath() !== 'translation') continue
+      const i = nodes.indexOf(ch.getTargetNode()!)
+      if (i < 0) continue
+      const above = feet.some((f) => f.foot >= 0 && isDesc(f.foot, i))
+      if (above && (rootIdx < 0 || depth(i) < depth(rootIdx))) rootIdx = i
+    }
+    if (rootIdx < 0) { const f = feet.find((x) => x.foot >= 0)!; rootIdx = rig.parents[f.foot]!; while (rig.parents[rootIdx]! >= 0 && !/hips|pelvis|root/i.test(rig.names[rootIdx]!)) rootIdx = rig.parents[rootIdx]! }
+    const n = Math.max(2, Math.round(clip.duration * fps) + 1)
+    const dt = clip.duration / (n - 1)
+    const root: Vec3[] = [], heading: number[] = []
+    const tracks: (FootTrack | null)[] = feet.map((f) => (f.foot >= 0 ? { contact: [], ankle: [] } : null))
+    for (let k = 0; k < n; k++) {
+      const w = worldOf(rig, clip.sample(k * dt))
+      root.push(w.pos[rootIdx]!)
+      heading.push(headingOf(w.rot[rootIdx]!))
+      feet.forEach((f, s) => { const t = tracks[s]; if (t) { t.contact.push(w.pos[f.contact]!); t.ankle.push(w.pos[f.foot]!) } })
+      // (the standalone writer measures feet only — a native pack's hands are the retargeter's concern)
+    }
+    const kind = opts.stairs?.(clip.name) ?? false
+    const floor = Math.min(...feet.filter((f) => f.foot >= 0).map((f) => rig.bind.worldPos[f.contact]![1]))
+    const res = detectMarks({ dt, root, heading, feet: { l: tracks[0] ?? undefined, r: tracks[1] ?? undefined }, stairs: kind === 'stairs' ? true : kind, floor: Number.isFinite(floor) ? floor : undefined })
+    for (const w of res.warnings) opts.warn?.(`${clip.name}: ${w}`)
+    const marks: ClipMarks = {
+      feet: { l: tracks[0] ? rig.names[feet[0]!.contact]! : null, r: tracks[1] ? rig.names[feet[1]!.contact]! : null },
+      l: res.l, r: res.r, first: res.first, ...(res.stairs ? { stairs: res.stairs } : {}),
+    }
+    const travel: [ number, number ] = [ root[n - 1]![0] - root[0]![0], root[n - 1]![2] - root[0]![2] ]
+    const extras = (anim.getExtras() ?? {}) as Record<string, unknown>
+    // the HEADING curve (heading.ts): the smoothed direction of the root's travel — the node's turn under root rotation
+    const headingBaked = headingCurve(root, heading, dt, { endAt: opts.headingEnd })
+    anim.setExtras({ ...extras, lecodes: { ...((extras.lecodes as Record<string, unknown>) ?? {}), contacts: marks, travel, heading: headingBaked } })
+    rows.push({ clip: clip.name, marks, travel })
+  }
+  return rows
+}

package/src/sky/analyze.ts

@@ -0,0 +1,136 @@
+// Reading back a KTX1 cubemap so `sky` can report what the environment actually contains — above
+// all WHERE ITS SUN IS. A scene lights itself with a directional light that the artist aims by hand;
+// if that direction disagrees with the sun visible in the sky, every shadow in the level points
+// somewhere the picture says it shouldn't. Measuring it beats guessing.
+//
+// cmgen writes KTX1 with GL_R11F_G11F_B10F (0x8C3A): one 32-bit word per texel, 6 faces in the
+// order +X -X +Y -Y +Z -Z, mip levels back to back, each level prefixed by its per-face byte size.
+
+export type SkyAnalysis = {
+  size: number
+  faces: number
+  mips: number
+  /** Unit vector pointing TOWARD the brightest texel — where the sun is in the sky. */
+  toSun: [number, number, number]
+  /** What a `light.direction` must be to match it: the negated `toSun`. */
+  lightDirection: [number, number, number]
+  /** Degrees above the horizon; negative means the brightest point is below it. */
+  elevation: number
+  /** Colour of the bright core (every texel within a decade of the peak), normalized so the
+   *  brightest channel is 1 — the light source's tint, not one noisy texel's. */
+  sunTint: string
+  /** Peak luminance. A real sun disc reads in the thousands; a few units means an overcast or
+   *  post-sunset sky with no disc at all, where a strong directional light would be wrong. */
+  peakLuminance: number
+  /** Mean luminance over the whole sphere, and over the upper hemisphere alone. */
+  meanLuminance: number
+  upperMeanLuminance: number
+}
+
+const readU32 = (b: Uint8Array, o: number): number =>
+  (b[o] | (b[o + 1] << 8) | (b[o + 2] << 16) | (b[o + 3] << 24)) >>> 0
+
+/** One 11/11/10 packed float triple → linear RGB. */
+const unpackR11G11B10 = (w: number): [number, number, number] => {
+  const part = (exp: number, mant: number, mbits: number): number => {
+    if (exp === 0) return (mant / (1 << mbits)) * 2 ** -14
+    if (exp === 31) return 65504
+    return (1 + mant / (1 << mbits)) * 2 ** (exp - 15)
+  }
+  return [
+    part((w >>> 6) & 0x1f, w & 0x3f, 6),
+    part((w >>> 17) & 0x1f, (w >>> 11) & 0x3f, 6),
+    part((w >>> 27) & 0x1f, (w >>> 22) & 0x1f, 5),
+  ]
+}
+
+/** Cubemap face + in-face uv → direction, matching filament's face order and orientation. */
+const dirFor = (face: number, s: number, t: number): [number, number, number] => {
+  const a = 2 * s - 1
+  const b = 1 - 2 * t
+  switch (face) {
+    case 0: return [1, b, -a]
+    case 1: return [-1, b, a]
+    case 2: return [a, 1, -b]
+    case 3: return [a, -1, b]
+    case 4: return [a, b, 1]
+    default: return [-a, b, -1]
+  }
+}
+
+const hex2 = (v: number): string => Math.max(0, Math.min(255, Math.round(v * 255))).toString(16).padStart(2, "0")
+
+/** Scan mip 0 of a cmgen KTX1 cubemap. `step` subsamples — 4 keeps a 512 cube under a few ms. */
+export const analyzeSkyKtx = (buf: Uint8Array, step = 4): SkyAnalysis => {
+  if (buf.length < 64 || buf[1] !== 0x4b || buf[2] !== 0x54 || buf[3] !== 0x58) {
+    throw new Error("not a KTX1 file")
+  }
+  const width = readU32(buf, 12 + 6 * 4)
+  const height = readU32(buf, 12 + 7 * 4)
+  const faces = readU32(buf, 12 + 10 * 4)
+  const mips = readU32(buf, 12 + 11 * 4)
+  const kvLen = readU32(buf, 12 + 12 * 4)
+  if (faces !== 6) throw new Error(`expected a cubemap (6 faces), got ${faces}`)
+
+  const base = 64 + kvLen
+  const faceBytes = readU32(buf, base)
+  const data = base + 4
+
+  let peak = -1
+  let peakDir: [number, number, number] = [0, 1, 0]
+  let total = 0
+  let count = 0
+  let upper = 0
+  let upperCount = 0
+
+  for (let face = 0; face < 6; face++) {
+    const start = data + face * faceBytes
+    for (let y = 0; y < height; y += step) {
+      for (let x = 0; x < width; x += step) {
+        const [r, g, b] = unpackR11G11B10(readU32(buf, start + (y * width + x) * 4))
+        const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b
+        total += lum
+        count++
+        const d = dirFor(face, (x + 0.5) / width, (y + 0.5) / height)
+        if (d[1] > 0) { upper += lum; upperCount++ }
+        if (lum > peak) { peak = lum; peakDir = d }
+      }
+    }
+  }
+
+  // Second pass for the TINT. One texel's colour is a bad answer: the single brightest sample can
+  // sit on the rim of a clipped sun where the sky's blue still dominates, which reported a blue sun
+  // for a clear-day HDRI. Average the whole bright core instead — every texel within a decade of
+  // the peak — so the tint describes the light source rather than one pixel of it.
+  const cutoff = peak * 0.1
+  let sr = 0, sg = 0, sb = 0, sn = 0
+  for (let face = 0; face < 6 && cutoff > 0; face++) {
+    const start = data + face * faceBytes
+    for (let y = 0; y < height; y += step) {
+      for (let x = 0; x < width; x += step) {
+        const [r, g, b] = unpackR11G11B10(readU32(buf, start + (y * width + x) * 4))
+        if (0.2126 * r + 0.7152 * g + 0.0722 * b < cutoff) continue
+        sr += r; sg += g; sb += b; sn++
+      }
+    }
+  }
+  const peakRgb: [number, number, number] = sn > 0 ? [sr / sn, sg / sn, sb / sn] : [1, 1, 1]
+
+  const len = Math.hypot(peakDir[0], peakDir[1], peakDir[2]) || 1
+  const toSun: [number, number, number] = [peakDir[0] / len, peakDir[1] / len, peakDir[2] / len]
+  const mx = Math.max(peakRgb[0], peakRgb[1], peakRgb[2]) || 1
+  const r2 = (v: number): number => Math.round(v * 100) / 100
+
+  return {
+    size: width,
+    faces,
+    mips,
+    toSun: [r2(toSun[0]), r2(toSun[1]), r2(toSun[2])],
+    lightDirection: [r2(-toSun[0]), r2(-toSun[1]), r2(-toSun[2])],
+    elevation: Math.round(Math.asin(Math.max(-1, Math.min(1, toSun[1]))) * (180 / Math.PI) * 10) / 10,
+    sunTint: `#${hex2(peakRgb[0] / mx)}${hex2(peakRgb[1] / mx)}${hex2(peakRgb[2] / mx)}`,
+    peakLuminance: Math.round(peak * 10) / 10,
+    meanLuminance: Math.round((total / Math.max(1, count)) * 1000) / 1000,
+    upperMeanLuminance: Math.round((upper / Math.max(1, upperCount)) * 1000) / 1000,
+  }
+}

package/src/sky/cmgen.ts

@@ -0,0 +1,71 @@
+// Locating filament's cmgen — the tool that turns an equirectangular HDR into the cubemaps the
+// engine wants. Same shape as findToktx (doctor/transcodeKtx2.ts): env override, then the places it
+// realistically sits, then PATH.
+//
+// cmgen is not bundled: most projects never build an environment, and the binary is ~600 KB per
+// platform. Resolution order:
+//   1. LECODES_CMGEN                      — explicit path (CI, or a local filament build)
+//   2. ~/.lecodes/cmgen/**/cmgen[.exe]    — the cache `lecodes` downloads into, newest first
+//   3. a sibling desktop build tree       — working in this monorepo, cmgen is already built
+//   4. PATH
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join, resolve } from "node:path"
+import { spawnSync } from "node:child_process"
+
+const exeName = (): string => (process.platform === "win32" ? "cmgen.exe" : "cmgen")
+
+/** Depth-limited hunt for the binary inside a directory (a release archive may nest a folder). */
+const findIn = (dir: string, depth = 3): string | null => {
+  if (depth < 0 || !existsSync(dir)) return null
+  let dirs: string[] = []
+  try {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name)
+      if (e.isFile() && e.name === exeName()) return p
+      if (e.isDirectory()) dirs.push(p)
+    }
+  } catch { return null }
+  // newest first: a cache holds cmgen-<version> folders and the freshest should win
+  dirs.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)
+  for (const d of dirs) { const hit = findIn(d, depth - 1); if (hit) return hit }
+  return null
+}
+
+/** Walk up from here looking for the monorepo's desktop build, where filament's host tools land. */
+const fromBuildTree = (): string | null => {
+  let dir = resolve(process.cwd())
+  for (let i = 0; i < 6; i++) {
+    const hit = join(dir, "packages", "desktop", "build", "creator-gl", "filament", "tools", "cmgen", exeName())
+    if (existsSync(hit)) return hit
+    const up = dirname(dir)
+    if (up === dir) break
+    dir = up
+  }
+  return null
+}
+
+export const findCmgen = (): string => {
+  const env = process.env.LECODES_CMGEN
+  if (env) {
+    if (!existsSync(env)) throw new Error(`LECODES_CMGEN points at "${env}" which doesn't exist.`)
+    return env
+  }
+  return findIn(join(homedir(), ".lecodes", "cmgen")) ?? fromBuildTree() ?? exeName()
+}
+
+/** Version string when the binary runs, else null — cmgen has no --version, so -h is the probe. */
+export const checkCmgen = (cmgen: string): string | null => {
+  try {
+    const p = spawnSync(cmgen, ["-h"], { encoding: "utf8" })
+    // cmgen exits non-zero on -h; what matters is that it ran and printed its own banner
+    const out = `${p.stdout ?? ""}${p.stderr ?? ""}`
+    if (p.error) return null
+    return /cmgen/i.test(out) ? "cmgen" : null
+  } catch { return null }
+}
+
+export const CMGEN_HELP =
+  `cmgen not found (looked at $LECODES_CMGEN, ~/.lecodes/cmgen, a sibling desktop build, PATH).\n` +
+  `  It ships with filament: build the desktop host once (packages/desktop/build.ps1) and it lands at\n` +
+  `  packages/desktop/build/creator-gl/filament/tools/cmgen/, or set LECODES_CMGEN=<path to cmgen>.`

package/src/sky/index.ts

@@ -0,0 +1,151 @@
+// Equirectangular HDR (.exr / .hdr) → the two cubemaps a LeCodes scene needs.
+//
+// The thing everyone gets wrong, so it is worth stating plainly: an environment is TWO files and
+// they are NOT interchangeable.
+//
+//   sky.ktx  — sharp, single mip. What is DRAWN behind the scene (`skybox: { texture }`).
+//   ibl.ktx  — prefiltered per roughness + spherical harmonics. What LIGHTS the scene.
+//
+// Handing the IBL to the skybox is the tempting shortcut (one file, and it "works") but that file
+// has been blurred on purpose, so the sky comes out visibly soft. cmgen emits both for this reason;
+// this command just makes the pair reproducible and names them the way the runtime expects.
+//
+// The IBL is deliberately smaller: it is only ever sampled as low-frequency lighting, so 256 is
+// plenty, while the sky is looked at directly and wants 512+.
+import { spawnSync } from "node:child_process"
+import { existsSync, mkdirSync, mkdtempSync, copyFileSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { basename, extname, join, resolve } from "node:path"
+import { findCmgen, checkCmgen, CMGEN_HELP } from "./cmgen"
+import { analyzeSkyKtx, type SkyAnalysis } from "./analyze"
+
+export type SkyOptions = {
+  /** Where the pair lands (default: beside the input). */
+  outDir?: string
+  /** Cubemap edge for the drawn sky (default 512). */
+  size?: number
+  /** Cubemap edge for the lighting probe (default 256). */
+  iblSize?: number
+  /** File names, without extension (default "sky" and "ibl" — what the runtime looks for). */
+  skyName?: string
+  iblName?: string
+  /** Skip the sky, emit only the lighting probe. */
+  iblOnly?: boolean
+  log?: (msg: string) => void
+}
+
+export type SkyResult = {
+  skyPath: string | null
+  iblPath: string | null
+  analysis: SkyAnalysis | null
+}
+
+const runCmgen = (cmgen: string, args: string[]): void => {
+  const p = spawnSync(cmgen, args, { encoding: "utf8" })
+  if (p.error) throw new Error(`cmgen failed to start: ${p.error.message}`)
+  if (p.status !== 0) {
+    const out = `${p.stdout ?? ""}${p.stderr ?? ""}`.trim()
+    throw new Error(`cmgen exited with ${p.status}${out ? `:\n${out}` : ""}`)
+  }
+}
+
+/** The file cmgen's --deploy wrote for a given role, whatever it chose to call the folder. */
+const deployed = (dir: string, suffix: string): string | null => {
+  if (!existsSync(dir)) return null
+  const hit = readdirSync(dir).find((f) => f.endsWith(`${suffix}.ktx`))
+  return hit ? join(dir, hit) : null
+}
+
+export const buildSky = async (input: string, opts: SkyOptions = {}): Promise<SkyResult> => {
+  const log = opts.log ?? (() => {})
+  if (!existsSync(input)) throw new Error(`not found: ${input}`)
+
+  const ext = extname(input).toLowerCase()
+  if (![".exr", ".hdr", ".png", ".psd"].includes(ext)) {
+    throw new Error(`unsupported input "${ext}" — cmgen reads .exr, .hdr, .png or .psd (equirectangular).`)
+  }
+
+  const cmgen = findCmgen()
+  if (!checkCmgen(cmgen)) throw new Error(CMGEN_HELP)
+
+  const outDir = resolve(opts.outDir ?? resolve(input, ".."))
+  mkdirSync(outDir, { recursive: true })
+  const size = opts.size ?? 512
+  const iblSize = opts.iblSize ?? 256
+  const skyName = opts.skyName ?? "sky"
+  const iblName = opts.iblName ?? "ibl"
+
+  const stage = mkdtempSync(join(tmpdir(), "lecodes-sky-"))
+  const result: SkyResult = { skyPath: null, iblPath: null, analysis: null }
+  try {
+    // Two passes: the sky and the probe want different resolutions, and --deploy sizes both at once.
+    if (!opts.iblOnly) {
+      log(`   cubemap ${size}… (sky)`)
+      const d = join(stage, "sky")
+      runCmgen(cmgen, ["-q", "--format=ktx", `--size=${size}`, `--deploy=${d}`, input])
+      const src = deployed(d, "_skybox")
+      if (!src) throw new Error("cmgen produced no _skybox.ktx")
+      result.skyPath = join(outDir, `${skyName}.ktx`)
+      copyFileSync(src, result.skyPath)
+    }
+
+    log(`   cubemap ${iblSize}… (lighting probe + SH)`)
+    const d2 = join(stage, "ibl")
+    runCmgen(cmgen, ["-q", "--format=ktx", `--size=${iblSize}`, `--deploy=${d2}`, input])
+    const iblSrc = deployed(d2, "_ibl")
+    if (!iblSrc) throw new Error("cmgen produced no _ibl.ktx")
+    result.iblPath = join(outDir, `${iblName}.ktx`)
+    copyFileSync(iblSrc, result.iblPath)
+
+    // Analyse whichever cubemap is sharpest — the sky when we made one, else the probe.
+    const toScan = result.skyPath ?? result.iblPath
+    try {
+      result.analysis = analyzeSkyKtx(new Uint8Array(readFileSync(toScan)))
+    } catch (e) {
+      log(`   (could not analyse the environment: ${(e as Error).message})`)
+    }
+  } finally {
+    rmSync(stage, { recursive: true, force: true })
+  }
+  return result
+}
+
+/** The report + the scene snippet to paste. The analysis is the point of the command: it turns
+ *  "aim the sun by eye until the shadows look right" into a number read off the environment. */
+export const formatSkyReport = (r: SkyResult, name = "SKY"): string => {
+  const out: string[] = []
+  const mb = (p: string): string => `${(statSync(p).size / 1048576).toFixed(1)} MB`
+  if (r.skyPath) out.push(`💾 ${r.skyPath}  (${mb(r.skyPath)})  — drawn as the sky`)
+  if (r.iblPath) out.push(`💾 ${r.iblPath}  (${mb(r.iblPath)})  — lights the scene`)
+  const a = r.analysis
+  if (!a) return out.join("\n")
+
+  const [dx, dy, dz] = a.lightDirection
+  out.push("")
+  out.push(`🔆 sun at ${a.elevation}° above the horizon · tint ${a.sunTint} · peak ${a.peakLuminance}`)
+  if (a.peakLuminance < 100) {
+    out.push(
+      `   NOTE: that peak is low — this environment has no sun DISC (overcast, or the sun is below\n` +
+      `   the horizon). The direction below is just the brightest part of the sky glow, and a strong\n` +
+      `   white directional light under it will read as wrong as one pointing the wrong way.`,
+    )
+  }
+  // Sunlight is never blue. A blue-dominant core means the disc is clipped in this HDRI and the
+  // reading has picked up the intensely blue sky glow around it — common in the 1k/2k versions.
+  // The DIRECTION is still trustworthy; the colour is not, so say so instead of handing over a
+  // number that would light the level with blue "sunlight".
+  const blueSun = parseInt(a.sunTint.slice(5, 7), 16) > parseInt(a.sunTint.slice(1, 3), 16) + 8
+  if (blueSun && a.peakLuminance >= 100) {
+    out.push(
+      `   NOTE: that tint is BLUE-dominant, which no sun is — the disc is clipped in this file and the\n` +
+      `   reading caught the sky glow around it. Trust the direction, not the colour: use a neutral\n` +
+      `   warm white (#fff2e2 or so) and tint to taste.`,
+    )
+  }
+  out.push(`   mean luminance ${a.meanLuminance} (upper hemisphere ${a.upperMeanLuminance}) — the brighter this is,`)
+  out.push(`   the lower environmentIntensity wants to be.`)
+  out.push("")
+  out.push(`   env:   { skybox: { texture: ${name} }, environmentIntensity: 16000 }`)
+  out.push(`   light: { kind: 'sun', direction: [${dx}, ${dy}, ${dz}], color: '${blueSun ? "#fff2e2" : a.sunTint}' }`)
+  return out.join("\n")
+}