lecodes-assets 0.2.0 → 2.4.10

package/src/sky/index.ts

@@ -0,0 +1,200 @@
+// 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
+  /** 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[]): 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. */
+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")
+    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. 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 })
+  }
+  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.`,
+    )
+  }
+  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: ${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

@@ -0,0 +1,208 @@
+// `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 — 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)
+//
+// The packing exists because terrain.mat runs at Filament feature level 1 (nine samplers): four
+// albedos + four separate normal maps + the control map + the lightmap would be ten. Z is
+// reconstructed in the shader, so only XY ship. A layer without a normal map gets a flat (128,128).
+//
+// 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 { findKtxEncoder, ktxEncodeArgs, KTX_ENCODER_MISSING, type KtxEncoder } from "./doctor/transcodeKtx2"
+
+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 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
+  /** 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, roughness: string | null, sourceSize: [number, number] }[]
+  normals: string[]
+  /** The matching `Terrain.create` fragment. */
+  snippet: string
+}
+
+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, roughness?: string): TerrainPackLayer => {
+  const p = resolve(input)
+  if (!existsSync(p)) throw new Error(`not found: ${input}`)
+  if (statSync(p).isDirectory()) {
+    const files = readdirSync(p).filter((f) => IMAGE_EXT.test(f))
+    // plain "_Albedo" over "_AlbedoSmoothness" (Unity packs ship both; the smoothness alpha is dropped anyway)
+    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))
+    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
+  if (!nrm) {
+    const stem = p.slice(0, -extname(p).length)
+    for (const cand of [ stem.replace(/albedo/i, "Normal"), stem.replace(/albedo/i, "normal"), `${stem}_Normal`, `${stem}_normal`, stem.replace(/_?(basecolor|diffuse|_d)$/i, "_Normal") ]) {
+      if (cand === stem) continue
+      const hit = [ ".png", ".jpg", ".jpeg", ".tga", ".webp", ".tif", ".tiff", ".bmp" ].map((e) => cand + e).find((f) => existsSync(f))
+      if (hit) { nrm = hit; break }
+    }
+  }
+  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"
+
+type Raw = { data: Buffer, width: number, height: number }
+
+/** Any supported image → RGBA at `size`² (TGA/BMP through the in-house decoders, the rest via sharp). */
+const loadRgba = async (path: string, size: number): Promise<Raw & { sourceSize: [number, number] }> => {
+  const sharp = (await import("sharp")).default
+  let bytes: Uint8Array = new Uint8Array(readFileSync(path))
+  const mime = sniffMime(bytes, path)
+  if (mime === "image/x-tga" || mime === "image/bmp") {
+    const rgba = mime === "image/x-tga" ? decodeTga(bytes) : decodeBmp(bytes)
+    if (!rgba) throw new Error(`${path}: could not decode the ${mime === "image/bmp" ? "BMP" : "TGA"}`)
+    bytes = encodePng(rgba)
+  }
+  const img = sharp(Buffer.from(bytes))
+  const meta = await img.metadata()
+  const { data, info } = await img.resize(size, size, { fit: "fill", kernel: "lanczos3" }).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+  return { data, width: info.width, height: info.height, sourceSize: [ meta.width ?? 0, meta.height ?? 0 ] }
+}
+
+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> => {
+  if (layers.length === 0) throw new Error("no layers")
+  if (layers.length > 4) throw new Error(`${layers.length} layers — a terrain material takes at most four`)
+  const size = opts.size ?? 1024
+  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 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`)
+    seen.add(l.name)
+  }
+  mkdirSync(opts.outDir, { recursive: true })
+  const ext = opts.png ? ".png" : ".ktx2"
+
+  const writeImage = async (raw: Raw, channels: 3 | 4, out: string, srgb: boolean): Promise<void> => {
+    let pipe = sharp(raw.data, { raw: { width: raw.width, height: raw.height, channels: 4 } })
+    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 (enc) {
+      encodeKtx2(enc, png, out, channels, srgb, opts.quality ?? 1)
+      unlinkSync(png)
+    }
+  }
+
+  const result: TerrainPackResult = { layers: [], normals: [], snippet: "" }
+  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)
+    // 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, 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
+  const packCount = layers.length > 2 ? 2 : 1
+  for (let k = 0; k < packCount; k++) {
+    const a = normalRaws[k * 2] ?? null, b = normalRaws[k * 2 + 1] ?? null
+    const n = size * size
+    const out = Buffer.alloc(n * 4)
+    for (let i = 0; i < n; i++) {
+      const o = i * 4
+      out[o] = a ? a.data[o] : 128
+      out[o + 1] = a ? (opts.flipY ? 255 - a.data[o + 1] : a.data[o + 1]) : 128
+      out[o + 2] = b ? b.data[o] : 128
+      out[o + 3] = b ? (opts.flipY ? 255 - b.data[o + 1] : b.data[o + 1]) : 128
+    }
+    const file = join(opts.outDir, `normals${k * 2}${k * 2 + 1}${ext}`)
+    await writeImage({ data: out, width: size, height: size }, 4, file, false)
+    result.normals.push(file)
+    log(`   normals${k * 2}${k * 2 + 1}${"".padEnd(7)} ${a ? layers[k * 2].name : "flat"} + ${b ? layers[k * 2 + 1].name : layers[k * 2 + 1] ? "flat" : "—"}`)
+  }
+
+  const rel = (f: string): string => "./" + basename(f)
+  result.snippet = [
+    "layers: [",
+    ...result.layers.map((l, i) => `  { albedo: asset('${rel(l.file)}'), tiling: 4${normalRaws[i] ? ", normalScale: 1" : ""} },`),
+    `], normals: [ ${result.normals.map((f) => `asset('${rel(f)}')`).join(", ")} ]`,
+  ].join("\n")
+  return result
+}

package/src/textures/resolveImage.ts

@@ -0,0 +1,202 @@
+// Turn an FBX texture reference (embedded bytes or a filename) into GLB-embeddable image bytes.
+// PNG/JPEG pass through; TGA/BMP are decoded here and re-encoded as PNG (no native deps); anything
+// else goes through `sharp` when it's installed, otherwise the texture is skipped with a warning.
+
+import { existsSync, readFileSync } from "node:fs"
+import { basename, dirname, join, isAbsolute } from "node:path"
+import { deflateSync } from "node:zlib"
+import { createHash } from "node:crypto"
+import type { FbxTexture } from "../fbx/read"
+
+export type ResolvedImage = { data: Uint8Array, mimeType: "image/png" | "image/jpeg", hash: string, converted: boolean, source: string }
+type Warn = (w: { level: "warn" | "info", message: string }) => void
+
+export const sniffMime = (b: Uint8Array, hintName = ""): string => {
+  if (b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) return "image/png"
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return "image/jpeg"
+  if (b.length >= 12 && b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 && b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50) return "image/webp"
+  if (b.length >= 2 && b[0] === 0x42 && b[1] === 0x4d) return "image/bmp"
+  if (b.length >= 4 && b[0] === 0x44 && b[1] === 0x44 && b[2] === 0x53 && b[3] === 0x20) return "image/vnd-ms.dds"
+  if (b.length >= 4 && b[0] === 0x38 && b[1] === 0x42 && b[2] === 0x50 && b[3] === 0x53) return "image/vnd.adobe.photoshop"
+  if (b.length >= 4 && ((b[0] === 0x49 && b[1] === 0x49 && b[2] === 0x2a) || (b[0] === 0x4d && b[1] === 0x4d && b[2] === 0x00))) return "image/tiff"
+  if (b.length >= 12 && b[0] === 0xab && b[1] === 0x4b && b[2] === 0x54 && b[3] === 0x58) return "image/ktx2"
+  const ext = hintName.toLowerCase().split(".").pop() ?? ""
+  if (ext === "tga" || ext === "targa") return "image/x-tga"
+  // TGA has no magic; accept the footer or a plausible header when the extension says so
+  if (b.length > 26) {
+    const foot = new TextDecoder().decode(b.subarray(b.length - 18, b.length - 2))
+    if (foot === "TRUEVISION-XFILE") return "image/x-tga"
+  }
+  return "application/octet-stream"
+}
+
+const hashOf = (b: Uint8Array): string => createHash("sha1").update(b).digest("hex")
+
+/** Resolve an FBX texture to PNG/JPEG bytes (null = unusable, warned). */
+export const resolveTextureImage = async (t: FbxTexture, embedded: Uint8Array | null, baseDir: string | undefined, warn: Warn): Promise<ResolvedImage | null> => {
+  let data: Uint8Array | null = embedded && embedded.length > 0 ? embedded : null
+  let source = "embedded"
+  const hint = t.relative || t.filename || t.absolute || t.name
+  if (!data) {
+    const found = findExternal(t, baseDir)
+    if (!found) { warn({ level: "warn", message: `texture '${hint}': not embedded and not found next to the FBX — skipped` }); return null }
+    data = new Uint8Array(readFileSync(found))
+    source = found
+  }
+  const mime = sniffMime(data, hint)
+  if (mime === "image/png" || mime === "image/jpeg") return { data, mimeType: mime, hash: hashOf(data), converted: false, source }
+  if (mime === "image/x-tga") {
+    const rgba = decodeTga(data)
+    if (rgba) { const png = encodePng(rgba); return { data: png, mimeType: "image/png", hash: hashOf(png), converted: true, source } }
+  }
+  if (mime === "image/bmp") {
+    const rgba = decodeBmp(data)
+    if (rgba) { const png = encodePng(rgba); return { data: png, mimeType: "image/png", hash: hashOf(png), converted: true, source } }
+  }
+  // last resort: sharp (optional dependency)
+  try {
+    const sharp = (await import("sharp")).default
+    const png = new Uint8Array(await sharp(Buffer.from(data)).png().toBuffer())
+    return { data: png, mimeType: "image/png", hash: hashOf(png), converted: true, source }
+  } catch (e) {
+    warn({ level: "warn", message: `texture '${hint}': ${mime} is not supported without 'sharp' (bun add sharp) — skipped` })
+    return null
+  }
+}
+
+const findExternal = (t: FbxTexture, baseDir: string | undefined): string | null => {
+  const candidates: string[] = []
+  const names = [ t.absolute, t.filename, t.relative ].filter(Boolean)
+  for (const n of names) {
+    if (isAbsolute(n) && existsSync(n)) return n
+    if (baseDir) {
+      candidates.push(join(baseDir, n))
+      const b = basename(n.replace(/\\/g, "/"))
+      candidates.push(join(baseDir, b), join(baseDir, "textures", b), join(baseDir, "Textures", b))
+    }
+  }
+  for (const c of candidates) if (existsSync(c)) return c
+  return null
+}
+
+// ---- TGA --------------------------------------------------------------------------------------
+
+export type Rgba = { width: number, height: number, data: Uint8Array }
+
+export const decodeTga = (b: Uint8Array): Rgba | null => {
+  if (b.length < 18) return null
+  const idLen = b[0], cmapType = b[1], imgType = b[2]
+  const cmapStart = b[3] | (b[4] << 8), cmapLen = b[5] | (b[6] << 8), cmapBits = b[7]
+  const width = b[12] | (b[13] << 8), height = b[14] | (b[15] << 8)
+  const bpp = b[16], desc = b[17]
+  const topDown = (desc & 0x20) !== 0
+  const rle = imgType === 9 || imgType === 10 || imgType === 11
+  const kind = imgType & 7 // 1 = colormapped, 2 = truecolor, 3 = grayscale
+  if (width === 0 || height === 0 || ![ 1, 2, 3 ].includes(kind)) return null
+  let p = 18 + idLen
+  let cmap: Uint8Array | null = null
+  const cmapBytes = (cmapBits + 7) >> 3
+  if (cmapType === 1) { cmap = b.subarray(p, p + cmapLen * cmapBytes); p += cmapLen * cmapBytes }
+  const bytesPP = bpp >> 3
+  const out = new Uint8Array(width * height * 4)
+  const px = new Uint8Array(4)
+  const readPixel = (at: number): void => {
+    if (kind === 3) { const g = b[at]; px[0] = g; px[1] = g; px[2] = g; px[3] = bytesPP > 1 ? b[at + 1] : 255; return }
+    if (kind === 1 && cmap) {
+      const idx = (bytesPP === 2 ? b[at] | (b[at + 1] << 8) : b[at]) - cmapStart
+      const c = idx * cmapBytes
+      if (cmapBytes >= 3) { px[0] = cmap[c + 2]; px[1] = cmap[c + 1]; px[2] = cmap[c]; px[3] = cmapBytes === 4 ? cmap[c + 3] : 255 }
+      else { const v = cmap[c] | (cmap[c + 1] << 8); px[0] = ((v >> 10) & 31) * 8; px[1] = ((v >> 5) & 31) * 8; px[2] = (v & 31) * 8; px[3] = 255 }
+      return
+    }
+    if (bytesPP === 4) { px[0] = b[at + 2]; px[1] = b[at + 1]; px[2] = b[at]; px[3] = b[at + 3]; return }
+    if (bytesPP === 3) { px[0] = b[at + 2]; px[1] = b[at + 1]; px[2] = b[at]; px[3] = 255; return }
+    if (bytesPP === 2) { const v = b[at] | (b[at + 1] << 8); px[0] = ((v >> 10) & 31) * 8; px[1] = ((v >> 5) & 31) * 8; px[2] = (v & 31) * 8; px[3] = 255; return }
+    px[0] = px[1] = px[2] = b[at]; px[3] = 255
+  }
+  const total = width * height
+  let i = 0
+  const put = (): void => {
+    const y = topDown ? Math.floor(i / width) : height - 1 - Math.floor(i / width)
+    const o = (y * width + (i % width)) * 4
+    out[o] = px[0]; out[o + 1] = px[1]; out[o + 2] = px[2]; out[o + 3] = px[3]
+    i++
+  }
+  if (!rle) {
+    for (; i < total && p + bytesPP <= b.length;) { readPixel(p); p += bytesPP; put() }
+  } else {
+    while (i < total && p < b.length) {
+      const head = b[p++]
+      const count = (head & 0x7f) + 1
+      if (head & 0x80) { readPixel(p); p += bytesPP; for (let k = 0; k < count && i < total; k++) put() }
+      else for (let k = 0; k < count && i < total && p + bytesPP <= b.length; k++) { readPixel(p); p += bytesPP; put() }
+    }
+  }
+  return { width, height, data: out }
+}
+
+// ---- BMP (uncompressed 24/32-bit) --------------------------------------------------------------
+
+export const decodeBmp = (b: Uint8Array): Rgba | null => {
+  if (b.length < 54 || b[0] !== 0x42 || b[1] !== 0x4d) return null
+  const dv = new DataView(b.buffer, b.byteOffset, b.byteLength)
+  const offset = dv.getUint32(10, true)
+  const width = dv.getInt32(18, true)
+  const rawHeight = dv.getInt32(22, true)
+  const bpp = dv.getUint16(28, true)
+  const compression = dv.getUint32(30, true)
+  if ((bpp !== 24 && bpp !== 32) || (compression !== 0 && compression !== 3)) return null
+  const height = Math.abs(rawHeight)
+  const topDown = rawHeight < 0
+  const stride = ((width * bpp / 8) + 3) & ~3
+  const out = new Uint8Array(width * height * 4)
+  for (let y = 0; y < height; y++) {
+    const srcY = topDown ? y : height - 1 - y
+    let s = offset + srcY * stride
+    for (let x = 0; x < width; x++) {
+      const o = (y * width + x) * 4
+      out[o] = b[s + 2]; out[o + 1] = b[s + 1]; out[o + 2] = b[s]; out[o + 3] = bpp === 32 ? b[s + 3] : 255
+      s += bpp / 8
+    }
+  }
+  return { width, height, data: out }
+}
+
+// ---- PNG encoder (RGBA8, filter 0, zlib) -----------------------------------------------------------
+
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256)
+  for (let n = 0; n < 256; n++) { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; t[n] = c >>> 0 }
+  return t
+})()
+const crc32 = (parts: Uint8Array[]): number => {
+  let c = 0xffffffff
+  for (const p of parts) for (let i = 0; i < p.length; i++) c = CRC_TABLE[(c ^ p[i]) & 0xff] ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+const chunk = (type: string, data: Uint8Array): Uint8Array => {
+  const t = new TextEncoder().encode(type)
+  const out = new Uint8Array(12 + data.length)
+  const dv = new DataView(out.buffer)
+  dv.setUint32(0, data.length)
+  out.set(t, 4); out.set(data, 8)
+  dv.setUint32(8 + data.length, crc32([ t, data ]))
+  return out
+}
+
+export const encodePng = (img: Rgba): Uint8Array => {
+  const { width, height, data } = img
+  const raw = new Uint8Array((width * 4 + 1) * height)
+  for (let y = 0; y < height; y++) { raw[y * (width * 4 + 1)] = 0; raw.set(data.subarray(y * width * 4, (y + 1) * width * 4), y * (width * 4 + 1) + 1) }
+  const ihdr = new Uint8Array(13)
+  const dv = new DataView(ihdr.buffer)
+  dv.setUint32(0, width); dv.setUint32(4, height)
+  ihdr[8] = 8; ihdr[9] = 6; ihdr[10] = 0; ihdr[11] = 0; ihdr[12] = 0
+  const idat = new Uint8Array(deflateSync(raw, { level: 6 }))
+  const sig = new Uint8Array([ 0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a ])
+  const parts = [ sig, chunk("IHDR", ihdr), chunk("IDAT", idat), chunk("IEND", new Uint8Array(0)) ]
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0))
+  let o = 0
+  for (const p of parts) { out.set(p, o); o += p.length }
+  return out
+}