lecodes-assets 0.2.1 → 2.5.0

package/src/retarget/rig.ts

@@ -268,7 +268,10 @@ export const bindVsRest = (rig: Rig): { worst: number; bone: string; skinned: nu
 export const checkUniformScale = (rig: Rig): void => {
   for (let i = 0; i < rig.names.length; i++) {
     const [ a, b, c ] = rig.rest.s[i]
-    if (Math.abs(a - b) > 1e-4 || Math.abs(b - c) > 1e-4) {
+    // RELATIVE: a Blender 0.01 armature under a 100× export leaves [99.99986, 99.99999, 100.00001] — float
+    // noise, not a squash (an absolute 1e-4 refused every rig-studio cloak bone)
+    const tol = 1e-5 * Math.max(1, Math.abs(a), Math.abs(b), Math.abs(c))
+    if (Math.abs(a - b) > tol || Math.abs(b - c) > tol) {
       throw new Error(`${rig.label}: bone "${rig.names[i]}" has a non-uniform rest scale [${rig.rest.s[i]}] — retargeting needs uniform scales`)
     }
   }

package/src/retarget/writeMarks.ts

@@ -1,132 +1,134 @@
-// 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
-}
+// 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
+  /** these clips are LOOPS (heading.ts `loop`: the travel direction smoothed periodically) */
+  loops?: string[]
+  /** 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, loop: opts.loops?.includes(clip.name) })
+    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/cmgen.ts

@@ -36,7 +36,7 @@ const findIn = (dir: string, depth = 3): string | null => {
 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())
+    const hit = join(dir, "hosts", "desktop", "build", "creator-gl", "filament", "tools", "cmgen", exeName())
     if (existsSync(hit)) return hit
     const up = dirname(dir)
     if (up === dir) break
@@ -67,5 +67,5 @@ export const checkCmgen = (cmgen: string): string | 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>.`
+  `  It ships with filament: build the desktop host once (hosts/desktop/build.ps1) and it lands at\n` +
+  `  hosts/desktop/build/creator-gl/filament/tools/cmgen/, or set LECODES_CMGEN=<path to cmgen>.`

package/src/sky/index.ts

@@ -31,22 +31,40 @@ export type SkyOptions = {
   iblName?: string
   /** Skip the sky, emit only the lighting probe. */
   iblOnly?: boolean
+  /** Take the SUN out of the lighting probe (cmgen --clamp-sun, the LeCodes fork's): for a level that has a directional
+   *  sun. The sun in the probe is the same light a second time - from everywhere, without shadows: it flattens every
+   *  object and halves the contrast of the baked shade. The drawn sky keeps its sun. `true` = 8 degrees. */
+  noSun?: boolean | number
   log?: (msg: string) => void
 }
 
+/** What `noSun` measured: the disc taken out of the probe, and what the scene should be given for it. */
+export type SunCalibration = {
+  /** The disc's illuminance on a surface facing it, in the picture's own units. */
+  discUnits: number
+  /** Degrees above the horizon (from the unclamped picture). */
+  elevation: number
+  /** A clear day's direct sun at that elevation, lux: 127 500 x exp(-0.21 / sin(elevation)). */
+  sunLux: number
+  /** environmentIntensity that makes the picture's own disc that bright: sunLux / discUnits - pixel 1.0 in nits. */
+  environmentIntensity: number
+}
+
 export type SkyResult = {
+  sun?: SunCalibration
   skyPath: string | null
   iblPath: string | null
   analysis: SkyAnalysis | null
 }
 
-const runCmgen = (cmgen: string, args: string[]): void => {
+const runCmgen = (cmgen: string, args: string[]): string => {
   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}` : ""}`)
   }
+  return `${p.stdout ?? ""}${p.stderr ?? ""}`
 }
 
 /** The file cmgen's --deploy wrote for a given role, whatever it chose to call the folder. */
@@ -91,19 +109,42 @@ export const buildSky = async (input: string, opts: SkyOptions = {}): Promise<Sk
 
     log(`   cubemap ${iblSize}… (lighting probe + SH)`)
     const d2 = join(stage, "ibl")
-    runCmgen(cmgen, ["-q", "--format=ktx", `--size=${iblSize}`, `--deploy=${d2}`, input])
+    let discUnits = 0
+    const sunArgs = opts.noSun ? [typeof opts.noSun === "number" ? `--clamp-sun=${opts.noSun}` : "--clamp-sun"] : []
+    const iblOut = runCmgen(cmgen, ["-q", "--format=ktx", `--size=${iblSize}`, ...sunArgs, `--deploy=${d2}`, input])
+    if (opts.noSun) {
+      const line = /Sun clamped:[^\r\n]*/.exec(iblOut)
+      if (!line) throw new Error("this cmgen has no --clamp-sun (it is the LeCodes filament fork's): point LECODES_CMGEN at hosts/desktop/build/creator-gl/filament/tools/cmgen")
+      log(`   ${line[0]}`)
+      const disc = /disc's illuminance ([0-9.eE+-]+)/.exec(iblOut)
+      if (disc) discUnits = parseFloat(disc[1])
+    }
     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
+    // Analyse whichever cubemap is sharpest — the sky when we made one, else the probe. A probe WITHOUT its sun says
+    // nothing about where the sun is: with `noSun` and no drawn sky, one more small pass keeps the disc for the reading.
+    let toScan = result.skyPath ?? result.iblPath
+    if (opts.noSun && !result.skyPath) {
+      const d3 = join(stage, "scan")
+      runCmgen(cmgen, ["-q", "--format=ktx", `--size=${iblSize}`, `--deploy=${d3}`, input])
+      toScan = deployed(d3, "_skybox") ?? deployed(d3, "_ibl") ?? toScan
+    }
     try {
       result.analysis = analyzeSkyKtx(new Uint8Array(readFileSync(toScan)))
     } catch (e) {
       log(`   (could not analyse the environment: ${(e as Error).message})`)
     }
+    // THE CALIBRATION: the picture's units are relative, the sun's illuminance is not. A clear day's direct sun at
+    // elevation h is 127 500 x exp(-0.21 / sin h) lux (the extraterrestrial constant through a clear atmosphere's
+    // optical depth); environmentIntensity = that / the disc's illuminance in the picture's units - pixel 1.0 in nits.
+    const elevation = result.analysis?.elevation ?? 0
+    if (discUnits > 0 && elevation > 2 && (result.analysis?.peakLuminance ?? 0) >= 100) {
+      const sunLux = 127500 * Math.exp(-0.21 / Math.sin(elevation * Math.PI / 180))
+      result.sun = { discUnits, elevation, sunLux, environmentIntensity: sunLux / discUnits }
+    }
   } finally {
     rmSync(stage, { recursive: true, force: true })
   }
@@ -142,10 +183,18 @@ export const formatSkyReport = (r: SkyResult, name = "SKY"): string => {
       `   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.`)
+  const round2 = (v: number): number => { const m = Math.pow(10, Math.max(0, Math.floor(Math.log10(v)) - 1)); return Math.round(v / m) * m }
+  const c = r.sun
+  if (c) {
+    out.push(`   CALIBRATED BY THE SUN: its disc is ${c.discUnits.toFixed(2)} of the picture's units of illuminance; a clear day's sun`)
+    out.push(`   at ${c.elevation}° is ~${round2(c.sunLux)} lux, so pixel 1.0 = ${round2(c.environmentIntensity)} nits. The probe has the disc taken out:`)
+    out.push(`   the directional light below IS the sun - give it that illuminance, do not tune the two by eye.`)
+  } else {
+    out.push(`   mean luminance ${a.meanLuminance} (upper hemisphere ${a.upperMeanLuminance}) — the brighter this is,`)
+    out.push(`   the lower environmentIntensity wants to be.${a.peakLuminance >= 100 ? " --no-sun measures the disc and gives the number." : ""}`)
+  }
   out.push("")
-  out.push(`   env:   { skybox: { texture: ${name} }, environmentIntensity: 16000 }`)
-  out.push(`   light: { kind: 'sun', direction: [${dx}, ${dy}, ${dz}], color: '${blueSun ? "#fff2e2" : a.sunTint}' }`)
+  out.push(`   env:   { skybox: { texture: ${name} }, environmentIntensity: ${c ? round2(c.environmentIntensity) : 16000} }`)
+  out.push(`   light: { kind: 'sun', direction: [${dx}, ${dy}, ${dz}], color: '${blueSun ? "#fff2e2" : a.sunTint}'${c ? `, intensity: ${round2(c.sunLux)}` : ""} }`)
   return out.join("\n")
 }

package/src/terrainPack.ts

@@ -1,7 +1,9 @@
 // `lecodes assets terrain-pack` — a terrain's splat layers (up to four) → what `Terrain.create`'s
 // `layers`/`normals` read (docs/terrain-plan.md §1.5):
 //
-//   <name>.ktx2        one per layer: the albedo, sRGB, square, mipmapped
+//   <name>.ktx2        one per layer: the albedo, sRGB, square, mipmapped — with the layer's ROUGHNESS in its ALPHA when
+//                      the layer has a roughness source (terrain.mat: roughness = the layer's factor x albedo alpha; the
+//                      one channel the sampler budget leaves free). No source = no alpha = the factor alone.
 //   normals01.ktx2     layer 0's normal XY in RG + layer 1's in BA   (linear)
 //   normals23.ktx2     layers 2 + 3 likewise (only when there are more than two layers)
 //
@@ -12,30 +14,42 @@
 // Inputs: an albedo file per layer (PNG/JPEG/WebP/TIFF via sharp, TGA/BMP decoded here) with the
 // normal map given by `--normals`, guessed from the albedo's name (`<x>_Albedo.png` → `<x>_Normal.png`),
 // or — the Unity-pack shape — a FOLDER per layer holding `*_Albedo.*` + `*_Normal.*`.
+// Roughness: `--roughness` per layer, guessed from the name (`<x>_Roughness.*`), or a folder's `*Roughness*` /
+// `*AlbedoSmoothness*` (Unity: smoothness in the ALPHA, inverted here). A roughness image is read from its GREEN channel:
+// a grey map has it in every channel, a glTF metallicRoughness / ORM map has roughness there.
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs"
 import { basename, extname, join, resolve } from "node:path"
 import { spawnSync } from "node:child_process"
 import { decodeBmp, decodeTga, encodePng, sniffMime } from "./textures/resolveImage"
-import { findToktx, checkToktx } from "./doctor/transcodeKtx2"
+import { findKtxEncoder, ktxEncodeArgs, KTX_ENCODER_MISSING, type KtxEncoder } from "./doctor/transcodeKtx2"
 
-export type TerrainPackLayer = { name: string, albedo: string, normal?: string }
+export type TerrainPackLayer = {
+  name: string, albedo: string, normal?: string
+  /** a roughness image (read from its green channel) … */
+  roughness?: string
+  /** … or a Unity `*_AlbedoSmoothness` image: roughness = 1 − its alpha */
+  smoothnessAlpha?: string
+  /** A per-channel scale on the albedo, applied in LINEAR light (Unity's TerrainLayer `m_DiffuseRemapMax`: a tint
+   *  the artist dialled on the layer, which the packed texture must carry since a layer has no tint of its own). */
+  albedoScale?: [number, number, number]
+}
 
 export type TerrainPackOptions = {
   /** Where the files land. */
   outDir: string
   /** Output edge in pixels — every texture is resampled square (default 1024). */
   size?: number
-  /** Write PNGs instead of KTX2 (no toktx needed; larger, uncompressed on the GPU). */
+  /** Write PNGs instead of KTX2 (no KTX-Software needed; larger, uncompressed on the GPU). */
   png?: boolean
   /** Invert the normal maps' green channel (DirectX-style sources; Unity's are OpenGL-style, the default). */
   flipY?: boolean
-  /** toktx UASTC quality 0–4 (default 1). */
+  /** UASTC quality 0–4 (default 1). */
   quality?: number
   log?: (msg: string) => void
 }
 
 export type TerrainPackResult = {
-  layers: { name: string, file: string, albedo: string, normal: string | null, sourceSize: [number, number] }[]
+  layers: { name: string, file: string, albedo: string, normal: string | null, roughness: string | null, sourceSize: [number, number] }[]
   normals: string[]
   /** The matching `Terrain.create` fragment. */
   snippet: string
@@ -44,7 +58,7 @@ export type TerrainPackResult = {
 const IMAGE_EXT = /\.(png|jpe?g|webp|tiff?|tga|bmp)$/i
 
 /** A layer from a file (+ optional normal) or a folder (`*Albedo*` + `*Normal*` inside). */
-export const resolveTerrainLayer = (input: string, normal?: string, name?: string): TerrainPackLayer => {
+export const resolveTerrainLayer = (input: string, normal?: string, name?: string, roughness?: string): TerrainPackLayer => {
   const p = resolve(input)
   if (!existsSync(p)) throw new Error(`not found: ${input}`)
   if (statSync(p).isDirectory()) {
@@ -53,7 +67,12 @@ export const resolveTerrainLayer = (input: string, normal?: string, name?: strin
     const albedo = files.find((f) => /albedo/i.test(f) && !/smooth/i.test(f)) ?? files.find((f) => /albedo|basecolor|base_color|diffuse|_d\./i.test(f))
     if (!albedo) throw new Error(`${input}: no albedo image (a file named *Albedo* / *BaseColor* / *Diffuse*)`)
     const nrm = normal ?? files.find((f) => /normal|_n\./i.test(f) && !/normalmap_?dx/i.test(f))
-    return { name: name ?? cleanName(basename(p)), albedo: join(p, albedo), normal: nrm ? (normal ? resolve(normal) : join(p, nrm)) : undefined }
+    const rough = roughness ? resolve(roughness) : files.find((f) => /rough/i.test(f))
+    const smooth = rough ? undefined : files.find((f) => /albedo.*smooth|smooth.*albedo/i.test(f))
+    return {
+      name: name ?? cleanName(basename(p)), albedo: join(p, albedo), normal: nrm ? (normal ? resolve(normal) : join(p, nrm)) : undefined,
+      roughness: rough ? (roughness ? rough : join(p, rough)) : undefined, smoothnessAlpha: smooth ? join(p, smooth) : undefined,
+    }
   }
   if (!IMAGE_EXT.test(p)) throw new Error(`${input}: not an image (png/jpg/webp/tiff/tga/bmp)`)
   let nrm: string | undefined = normal ? resolve(normal) : undefined
@@ -65,7 +84,16 @@ export const resolveTerrainLayer = (input: string, normal?: string, name?: strin
       if (hit) { nrm = hit; break }
     }
   }
-  return { name: name ?? cleanName(basename(p, extname(p)).replace(/[_-]?(albedo|basecolor|base_color|diffuse)$/i, "")), albedo: p, normal: nrm }
+  let rough: string | undefined = roughness ? resolve(roughness) : undefined
+  if (!rough) {
+    const stem = p.slice(0, -extname(p).length)
+    for (const cand of [ stem.replace(/albedo/i, "Roughness"), stem.replace(/albedo/i, "roughness"), `${stem}_Roughness`, `${stem}_roughness`, stem.replace(/_?(basecolor|diffuse|_d)$/i, "_Roughness") ]) {
+      if (cand === stem) continue
+      const hit = [ ".png", ".jpg", ".jpeg", ".tga", ".webp", ".tif", ".tiff", ".bmp" ].map((e) => cand + e).find((f) => existsSync(f))
+      if (hit) { rough = hit; break }
+    }
+  }
+  return { name: name ?? cleanName(basename(p, extname(p)).replace(/[_-]?(albedo|basecolor|base_color|diffuse)$/i, "")), albedo: p, normal: nrm, roughness: rough }
 }
 
 const cleanName = (s: string): string => s.trim().replace(/\s+/g, "_").replace(/[^A-Za-z0-9_-]/g, "").toLowerCase() || "layer"
@@ -88,10 +116,10 @@ const loadRgba = async (path: string, size: number): Promise<Raw & { sourceSize:
   return { data, width: info.width, height: info.height, sourceSize: [ meta.width ?? 0, meta.height ?? 0 ] }
 }
 
-const encodeKtx2 = (toktx: string, png: string, ktx2: string, srgb: boolean, quality: number): void => {
-  const args = [ "--t2", "--encode", "uastc", "--uastc_quality", String(quality), "--zcmp", "18", "--genmipmap", "--assign_oetf", srgb ? "srgb" : "linear", ktx2, png ]
-  const p = spawnSync(toktx, args, { encoding: "utf8" })
-  if (p.status !== 0) throw new Error(`toktx failed (${p.status ?? p.error?.message ?? "?"}) on ${basename(png)}:\n${(p.stderr || p.stdout || "").trim()}`)
+const encodeKtx2 = (enc: KtxEncoder, png: string, ktx2: string, channels: 3 | 4, srgb: boolean, quality: number): void => {
+  const args = ktxEncodeArgs(enc, { input: png, output: ktx2, codec: "uastc", oetf: srgb ? "srgb" : "linear", channels, uastcQuality: quality, zstd: 18 })
+  const p = spawnSync(enc.path, args, { encoding: "utf8" })
+  if (p.status !== 0) throw new Error(`${enc.kind === "ktx" ? "ktx create" : "toktx"} failed (${p.status ?? p.error?.message ?? "?"}) on ${basename(png)}:\n${(p.stderr || p.stdout || "").trim()}`)
 }
 
 export const packTerrainTextures = async (layers: TerrainPackLayer[], opts: TerrainPackOptions): Promise<TerrainPackResult> => {
@@ -101,10 +129,8 @@ export const packTerrainTextures = async (layers: TerrainPackLayer[], opts: Terr
   if (!(size >= 16 && size <= 8192) || (size & (size - 1)) !== 0) throw new Error(`--size wants a power of two in 16..8192, got ${size}`)
   const log = opts.log ?? (() => {})
   const sharp = (await import("sharp")).default
-  const toktx = opts.png ? null : findToktx()
-  if (toktx && !checkToktx(toktx)) {
-    throw new Error("KTX-Software's toktx is needed for KTX2 output — install it (https://github.com/KhronosGroup/KTX-Software/releases, on PATH or KTX_TOKTX=<path>) or pass --png")
-  }
+  const enc = opts.png ? null : findKtxEncoder()
+  if (!opts.png && !enc) throw new Error(`${KTX_ENCODER_MISSING}\n  Or pass --png.`)
   const seen = new Set<string>()
   for (const l of layers) {
     if (seen.has(l.name)) throw new Error(`two layers named "${l.name}" — pass --names`)
@@ -118,8 +144,8 @@ export const packTerrainTextures = async (layers: TerrainPackLayer[], opts: Terr
     if (channels === 3) pipe = pipe.removeAlpha()
     const png = opts.png ? out : out.slice(0, -ext.length) + ".png"
     await pipe.png({ compressionLevel: opts.png ? 9 : 1 }).toFile(png)
-    if (toktx) {
-      encodeKtx2(toktx, png, out, srgb, opts.quality ?? 1)
+    if (enc) {
+      encodeKtx2(enc, png, out, channels, srgb, opts.quality ?? 1)
       unlinkSync(png)
     }
   }
@@ -128,16 +154,29 @@ export const packTerrainTextures = async (layers: TerrainPackLayer[], opts: Terr
   const normalRaws: (Raw | null)[] = []
   for (const l of layers) {
     const alb = await loadRgba(l.albedo, size)
+    if (l.albedoScale && l.albedoScale.some((s) => Math.abs(s - 1) > 1e-3)) {
+      const toLin = (v: number): number => (v <= 0.04045 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4))
+      const toSrgb = (v: number): number => (v <= 0.0031308 ? v * 12.92 : 1.055 * Math.pow(v, 1 / 2.4) - 0.055)
+      const lut = [ 0, 1, 2 ].map((c) => { const t = new Uint8Array(256); for (let i = 0; i < 256; i++) t[i] = Math.round(Math.min(1, toSrgb(toLin(i / 255) * l.albedoScale![c])) * 255); return t })
+      for (let i = 0; i < size * size; i++) for (let c = 0; c < 3; c++) alb.data[i * 4 + c] = lut[c][alb.data[i * 4 + c]]
+    }
     const file = join(opts.outDir, l.name + ext)
-    await writeImage(alb, 3, file, true)
+    // the layer's roughness rides the albedo's alpha (the header); without a source the albedo ships opaque
+    const roughSrc = l.roughness ?? l.smoothnessAlpha
+    if (roughSrc) {
+      if (!existsSync(roughSrc)) throw new Error(`${l.name}: roughness map not found: ${roughSrc}`)
+      const r = await loadRgba(roughSrc, size)
+      for (let i = 0; i < size * size; i++) alb.data[i * 4 + 3] = l.roughness ? r.data[i * 4 + 1] : 255 - r.data[i * 4 + 3]
+    }
+    await writeImage(alb, roughSrc ? 4 : 3, file, true)
     let nrm: (Raw & { sourceSize: [number, number] }) | null = null
     if (l.normal) {
       if (!existsSync(l.normal)) throw new Error(`${l.name}: normal map not found: ${l.normal}`)
       nrm = await loadRgba(l.normal, size)
     }
     normalRaws.push(nrm)
-    result.layers.push({ name: l.name, file, albedo: l.albedo, normal: l.normal ?? null, sourceSize: alb.sourceSize })
-    log(`   ${l.name.padEnd(16)} ${alb.sourceSize[0]}×${alb.sourceSize[1]} → ${size}²  ${nrm ? `+ normal ${nrm.sourceSize[0]}×${nrm.sourceSize[1]}` : "(flat normal)"}`)
+    result.layers.push({ name: l.name, file, albedo: l.albedo, normal: l.normal ?? null, roughness: roughSrc ?? null, sourceSize: alb.sourceSize })
+    log(`   ${l.name.padEnd(16)} ${alb.sourceSize[0]}×${alb.sourceSize[1]} → ${size}²  ${nrm ? `+ normal ${nrm.sourceSize[0]}×${nrm.sourceSize[1]}` : "(flat normal)"}${roughSrc ? ` + roughness in the alpha (${l.roughness ? basename(roughSrc) : "1 − " + basename(roughSrc) + "'s alpha"})` : ""}`)
   }
 
   // the packs: RG = layer 2k's XY, BA = layer 2k+1's; a missing map is flat