lecodes-cli 2.4.6 → 2.4.7

package/src/commands/app/android.ts

@@ -24,6 +24,7 @@ import {
   type AndroidRuntimePlugin, type AndroidShellIdentity, runtimeManifestTemplate, urlSchemeFilter, appLinksFilter,
 } from "./templates/android"
 import { GRADLEW_BAT, GRADLEW_SH } from "./templates/gradlew"
+import { readServiceAccount, serviceAccountToken, uploadToPlay } from "./play"
 
 /* The Android arm of `lecodes app` — the mirror of the iOS flows in index.ts, over Gradle
  * instead of Xcode: init / sync / open / doctor checks as functions the shared command nodes call,
@@ -637,10 +638,9 @@ const buildAndroid = async (flags: FlagValues<typeof androidBuildFlags>): Promis
   }
   if (produced.length === 0) throw new CliError("Gradle finished but produced no .apk/.aab — check android/app/build/outputs.")
 
-  const slug = flags.slug ?? slugify(config.name ?? basename(root))
   const outDir = resolve(root, flags.out ?? join(root, "dist"))
   mkdirSync(outDir, { recursive: true })
-  const stem = `${slug}-${config.version ?? "1.0.0"}-${config.android.versionCode ?? 1}${configuration === "debug" ? "-debug" : ""}`
+  const stem = `${artifactStem(root, config, flags.slug)}${configuration === "debug" ? "-debug" : ""}`
   for (const src of produced) {
     const unsigned = configuration === "release" && !signing
     const dest = join(outDir, `${stem}${unsigned ? "-unsigned" : ""}${src.endsWith(".aab") ? ".aab" : ".apk"}`)
@@ -651,7 +651,7 @@ const buildAndroid = async (flags: FlagValues<typeof androidBuildFlags>): Promis
   success(configuration === "debug"
     ? "Debug build done — `adb install` the .apk to test (or `lecodes dev --android --apk <file>`)."
     : signing
-      ? "Release build done — upload the .aab in the Play Console (the .apk side-loads for testing)."
+      ? "Release build done — `lecodes app upload android` sends the .aab to Play (the .apk side-loads for testing)."
       : "Unsigned release build done — sign it before it goes anywhere.")
 }
 
@@ -664,6 +664,84 @@ export const androidBuild = defineCommand({
   run: ({ flags }) => buildAndroid(flags),
 })
 
+/** dist/'s name for a build of this app.json — `<slug>-<version>-<versionCode>`, so the upload
+ *  finds the bundle of the versionCode app.json says, never an older one left in dist/. */
+const artifactStem = (root: string, config: AppConfig, slug?: string): string =>
+  `${slug ?? slugify(config.name ?? basename(root))}-${config.version ?? "1.0.0"}-${config.android?.versionCode ?? 1}`
+
+/* ---------------------------------------- upload ---------------------------------------- */
+
+/** The project .env key the service account key is remembered under (CI sets it itself). */
+export const PLAY_KEY_ENV = "LECODES_PLAY_SERVICE_ACCOUNT"
+
+const androidUploadFlags = {
+  aab: str("the bundle (default: the dist/<name>-<version>-<versionCode>.aab `app build android` wrote)", { value: "<file>" }),
+  track: str("internal | alpha | beta | production | a closed track's name", { value: "<t>", default: "internal" }),
+  draft: bool("a draft release, rolled out in Play Console (the only kind a never-published app takes)"),
+  key: str("the service account's JSON key (remembered in the project .env)", { value: "<json>" }),
+  slug: str("file name stem of the default bundle, as given to `app build android --slug`", { value: "<name>" }),
+}
+
+/** `lecodes app upload android` — the bundle onto a Play track through one edit (play.ts). */
+const uploadAndroid = async (flags: FlagValues<typeof androidUploadFlags>): Promise<void> => {
+  const root = projectRoot()
+  const config = readAppConfigAt(root)
+  if (!config?.android?.applicationId || !existsSync(join(root, "android"))) {
+    throw new CliError("No Android shell here — run `lecodes app init android` first.")
+  }
+  const packageName = config.android.applicationId
+
+  const aabPath = flags.aab ? resolve(flags.aab) : join(root, "dist", `${artifactStem(root, config, flags.slug)}.aab`)
+  if (!existsSync(aabPath)) {
+    throw new CliError(`No bundle at ${relative(root, aabPath) || aabPath} — run \`lecodes app build android\` first (it names the file by app.json's version + versionCode).`)
+  }
+
+  // The key: --key on first use, then the project .env — per project, not ~/.lecodes like the
+  // iOS key, because two apps may live in two developer accounts.
+  const given = flags.key
+  const keyPath = given ? resolve(given.startsWith("~/") ? join(homedir(), given.slice(2)) : given) : process.env[PLAY_KEY_ENV]
+  if (!keyPath) {
+    throw new CliError([
+      `A Google Play service account key is needed: --key <file.json> (remembered in the project .env as ${PLAY_KEY_ENV}).`,
+      "  Google Cloud: enable the Google Play Android Developer API, then IAM → Service accounts → Keys → Add key → JSON;",
+      "  Play Console → Users and permissions: invite the account's email with \"Release to testing tracks\" for the app.",
+    ].join("\n"))
+  }
+  if (!existsSync(keyPath)) throw new CliError(`Service account key not found: ${keyPath}`)
+  const key = readServiceAccount(keyPath)
+  if (given) {
+    upsertDotEnv(root, { [PLAY_KEY_ENV]: envValue(envPathFor(root, keyPath)) })
+    note(`Stored the key reference in .env (${PLAY_KEY_ENV})`)
+  }
+
+  const size = (statSync(aabPath).size / (1024 * 1024)).toFixed(1)
+  note(`Uploading ${relative(root, aabPath) || aabPath} (${size} MB) to ${packageName}, track ${flags.track}${flags.draft ? " as a draft" : ""} — as ${key.client_email}`)
+  const token = await serviceAccountToken(key)
+  const { versionCode } = await uploadToPlay(token, {
+    packageName, aab: readFileSync(aabPath), track: flags.track, status: flags.draft ? "draft" : "completed",
+  })
+
+  // A versionCode Play has seen is spent: app.json moves past it for the next build (`app upload
+  // ios` does the same with buildNumber). Never backwards — --aab may name an older bundle.
+  const fresh = readAppConfigAt(root)!
+  const next = Math.max(fresh.android!.versionCode ?? 1, versionCode + 1)
+  if (next !== fresh.android!.versionCode) {
+    fresh.android!.versionCode = next
+    writeJson(join(root, "app.json"), fresh)
+  }
+  success(`Uploaded versionCode ${versionCode} to the ${flags.track} track${flags.draft ? " as a draft — roll it out in Play Console" : ""}.`)
+  note(`android.versionCode is ${next} for the next build.`)
+}
+
+export const androidUpload = defineCommand({
+  name: "android",
+  summary: "Upload the .aab to a Google Play track (then bumps android.versionCode)",
+  description: `One edit of the Google Play Developer API — the bundle onto the track as one release, then the commit; Play changes only when every step went through. Authenticated with a Cloud service account's JSON key: --key on first use, then the project .env remembers it (${PLAY_KEY_ENV}; in CI set the variable to the key's path, e.g. a GitLab File variable). The app must already exist in Play Console under app.json android.applicationId (the API cannot create it), the account be invited there with "Release to testing tracks". A successful upload spends the versionCode, so app.json android.versionCode moves past it for the next build.`,
+  flags: androidUploadFlags,
+  examples: ["lecodes app upload android --key ~/keys/play.json", "lecodes app upload android --track internal", "lecodes app upload android --draft"],
+  run: ({ flags }) => uploadAndroid(flags),
+})
+
 /* --------------------------------------- signing --------------------------------------- */
 
 /** The four names the generated app/build.gradle.kts reads with System.getenv — the project

package/src/commands/app/index.ts

@@ -20,7 +20,7 @@ import {
 } from "./shared"
 import { isLocalPluginSpec, type PluginEntry } from "lecodes-sdk/compile"
 import {
-  ANDROID_SDK_MIN_VERSION, ANDROID_SDK_REPO, androidBuild, doctorAndroidChecks, initAndroid,
+  ANDROID_SDK_MIN_VERSION, ANDROID_SDK_REPO, androidBuild, androidUpload, doctorAndroidChecks, initAndroid,
   keystore, openAndroid, shellSdkVersionAndroid, syncAndroid, type SyncArtifacts,
 } from "./android"
 import { desktopBuild, initDesktop } from "./desktop"
@@ -979,17 +979,8 @@ const iosUpload = defineCommand({
 
 const upload = defineCommand({
   name: "upload",
-  summary: "Upload a build to the store: ios (App Store Connect)",
-  commands: [
-    iosUpload,
-    // Not wired yet — kept as a node so `app upload android` says what to do instead of "unknown command".
-    defineCommand({
-      name: "android",
-      summary: "Play upload (not wired yet)",
-      hidden: true,
-      run: () => { throw new CliError("Play upload isn't wired yet — upload android/app/build/outputs/bundle/release/*.aab in the Play Console (`lecodes app build android` produces it).") },
-    }),
-  ],
+  summary: "Upload a build to the store: ios (App Store Connect) | android (Google Play)",
+  commands: [iosUpload, androidUpload],
 })
 
 /* --------------------------------------- open ---------------------------------------- */

package/src/commands/app/play.ts

@@ -0,0 +1,107 @@
+import { sign } from "node:crypto"
+import { readFileSync } from "node:fs"
+import { CliError } from "../../cli"
+
+/* Google Play: the Developer API's one upload path, the v3 EDIT — the Android twin of `app upload
+ * ios`. An edit is a transaction: insert → upload the bundle → put it on a track → commit. Nothing
+ * reaches Play before the commit, so a failure anywhere leaves the app as it was (an uncommitted
+ * edit simply expires). The edit calls take a bare access token: a service account's JSON key
+ * produces one here (CI, a key nobody signs in with); a user's OAuth refresh token would be the
+ * other source (the platform's "Connect Google Play") and changes nothing below. */
+
+const SCOPE = "https://www.googleapis.com/auth/androidpublisher"
+
+/** `LECODES_PLAY_API_URL` points the edit calls at a fake (the tests). */
+const apiBase = () => process.env.LECODES_PLAY_API_URL ?? "https://androidpublisher.googleapis.com"
+
+/** The fields of a Cloud service account's JSON key the token exchange needs. */
+export interface ServiceAccountKey {
+  client_email: string
+  private_key: string
+  token_uri?: string
+}
+
+export const readServiceAccount = (path: string): ServiceAccountKey => {
+  let key: Partial<ServiceAccountKey> & { type?: string }
+  try {
+    key = JSON.parse(readFileSync(path, "utf8"))
+  } catch {
+    throw new CliError(`${path} is not a JSON key file.`)
+  }
+  if (key.type !== "service_account" || !key.client_email || !key.private_key) {
+    throw new CliError(`${path} is not a service account key (Google Cloud → IAM → Service accounts → Keys → Add key → JSON).`)
+  }
+  return key as ServiceAccountKey
+}
+
+/** A service account's access token: a JWT signed with its key, traded at its token_uri (RFC 7523). */
+export const serviceAccountToken = async (key: ServiceAccountKey, now = Math.floor(Date.now() / 1000)): Promise<string> => {
+  const tokenUri = key.token_uri ?? "https://oauth2.googleapis.com/token"
+  const part = (v: object) => Buffer.from(JSON.stringify(v)).toString("base64url")
+  const unsigned = `${part({ alg: "RS256", typ: "JWT" })}.${part({ iss: key.client_email, scope: SCOPE, aud: tokenUri, iat: now, exp: now + 3600 })}`
+  const signature = sign("RSA-SHA256", Buffer.from(unsigned), key.private_key).toString("base64url")
+  const res = await fetch(tokenUri, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({ grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", assertion: `${unsigned}.${signature}` }),
+  })
+  const body = await res.json().catch(() => ({})) as { access_token?: string, error?: string, error_description?: string }
+  if (!res.ok || !body.access_token) {
+    throw new CliError(`Google refused the key of ${key.client_email}: ${body.error_description ?? body.error ?? `HTTP ${res.status}`} (a deleted or rotated key fails here — make a new one).`)
+  }
+  return body.access_token
+}
+
+export interface PlayRelease {
+  packageName: string
+  aab: Uint8Array
+  /** internal | alpha | beta | production | a closed track's own name. */
+  track: string
+  /** draft = the only status an app that was never published accepts. */
+  status: "completed" | "draft"
+}
+
+/** What to do about the refusals a first setup runs into; Google's own message stays in front. */
+const HINTS: [RegExp, (r: PlayRelease) => string][] = [
+  [/caller does not have permission|insufficient permissions/i, () => "invite the service account in Play Console → Users and permissions with \"Release to testing tracks\" for this app (a new grant can take hours to reach the API)"],
+  [/package not found/i, r => `Play Console has no app ${r.packageName} — create it there first (the API cannot); app.json android.applicationId must match`],
+  [/version code .*already been used/i, () => "bump app.json android.versionCode and build again"],
+  [/only releases with status draft/i, () => "the app was never published — upload with --draft, then roll the release out in Play Console"],
+  [/has not been used in project|is disabled/i, () => "enable the Google Play Android Developer API in the key's Cloud project"],
+]
+
+const playError = (step: string, status: number, text: string, release: PlayRelease): CliError => {
+  let message = text
+  try { message = (JSON.parse(text) as { error?: { message?: string } }).error?.message ?? text } catch { /* not JSON: as is */ }
+  const hint = HINTS.find(([re]) => re.test(message))?.[1](release)
+  return new CliError(`Google Play refused the ${step} (HTTP ${status}): ${message.trim()}${hint ? `\n  → ${hint}` : ""}`)
+}
+
+/** One edit: the bundle onto `track` as one release. Returns the versionCode Play read from it. */
+export const uploadToPlay = async (token: string, release: PlayRelease): Promise<{ versionCode: number }> => {
+  const app = `applications/${encodeURIComponent(release.packageName)}`
+  const call = async <T>(step: string, method: string, path: string, body?: Uint8Array | object): Promise<T> => {
+    const bytes = body instanceof Uint8Array
+    const res = await fetch(`${apiBase()}/${path}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${token}`,
+        ...(body ? { "content-type": bytes ? "application/octet-stream" : "application/json" } : {}),
+      },
+      body: bytes ? body : body ? JSON.stringify(body) : undefined,
+    })
+    const text = await res.text()
+    if (!res.ok) throw playError(step, res.status, text, release)
+    return (text ? JSON.parse(text) : {}) as T
+  }
+
+  const edit = await call<{ id: string }>("edit", "POST", `androidpublisher/v3/${app}/edits`, {})
+  const editPath = `androidpublisher/v3/${app}/edits/${encodeURIComponent(edit.id)}`
+  const bundle = await call<{ versionCode: number }>("bundle", "POST", `upload/${editPath}/bundles?uploadType=media`, release.aab)
+  await call("track", "PUT", `${editPath}/tracks/${encodeURIComponent(release.track)}`, {
+    track: release.track,
+    releases: [{ versionCodes: [String(bundle.versionCode)], status: release.status }],
+  })
+  await call("commit", "POST", `${editPath}:commit`)
+  return { versionCode: bundle.versionCode }
+}

package/src/commands/assets.ts

@@ -9,7 +9,7 @@ import { loadPeer } from "../hosts/peerInstall"
  */
 export default defineCommand({
   name: "assets",
-  summary: "The asset pipeline: convert / probe / doctor / retarget / unpack / scene / sky / terrain-pack …",
+  summary: "The asset pipeline: convert / probe / doctor / unwrap / retarget / unpack / scene / sky / terrain-pack …",
   usage: "<command> [args…]",
   passthrough: true,
   examples: ["lecodes assets convert hero.fbx --clips anims/*.fbx -o hero.glb", "lecodes assets doctor hero.glb --fix --ktx2", "lecodes assets --help"],

package/src/commands/lightmap.ts

@@ -1,10 +1,11 @@
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs"
+import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync } from "node:fs"
 import { tmpdir } from "node:os"
 import { basename, dirname, join, relative, resolve } from "node:path"
 import { deflateSync } from "node:zlib"
-import { buildBundle } from "./compile"
-import { readAppConfigAt, resolveDesktopRenderer } from "./app/shared"
+import { buildBundle, type BundleResource } from "./compile"
+import { readAppConfigAt } from "./app/shared"
 import { runDesktopRender } from "../hosts/desktopRenderer"
+import { loadPeer } from "../hosts/peerInstall"
 import { CliError, bool, c, defineCommand, log, logErr, note, num, str, warnErr } from "../cli"
 import { bundleFlags, bundleOptions, localProject } from "./shared"
 
@@ -12,17 +13,22 @@ import { bundleFlags, bundleOptions, localProject } from "./shared"
  * `lecodes lightmap` — the baked lighting of a level (engines/bake).
  *
  *   bake      compile the app with a synthetic entry that puts it in BAKE mode (`globalThis.__lecodesLightmap`),
- *             run it in the native desktop host; when the app calls `Lightmap.load(...)` — the point where its
+ *             run it in the bake host (lecodes-bake); when the app calls `Lightmap.load(...)` — the point where its
  *             scene is complete — the SDK calls `_creator.lightmapBake` instead of loading: the host describes
  *             every registered static to creator-bake, which traces the sun, the sky and the lamps on the
- *             NVIDIA card and writes <out>/<name>.bake + <name>-light[_n].ktx2 + <name>-aux[_n].ktx2 itself
+ *             GPU (--tracer: OptiX on NVIDIA, else Vulkan ray query on any card with hardware ray tracing) and
+ *             writes <out>/<name>.bake + <name>-light[_n].ktx2 + <name>-aux[_n].ktx2 itself
  *             (no toktx, no PNG intermediates). "[lightmap] done" is the success marker.
  *   stats     the per-instance numbers a .bake carries (mean lux, sun / sky visibility, texels, rect)
  *   diff      the noise of a bake per instance: two bakes with different --seed compared texel by texel
  *   inspect   PNGs from the float layers a `bake --debug-dir` kept: whole pages or one instance's rect
  *
- * Only a desktop host built with the CUDA toolkit has the bake — a local build via LECODES_DESKTOP_EXE.
- * The props need lightmap UVs first: `lecodes assets doctor assets/props/*.glb --lightmap-uv`.
+ * The bake is not in the shipped desktop / server hosts: it runs in lecodes-bake (hosts/desktop CREATOR_DESKTOP_BAKE),
+ * the windowless host with the bake built in — resolved by hosts/desktopRenderer.ts resolveBakeExe (LECODES_BAKE_EXE
+ * for a local build, else the published release product "bake").
+ * Lightmap UVs: before the host runs, every GLB the app references that has none is unwrapped IN PLACE (lecodes-assets
+ * `unwrapGlbFiles`, what `lecodes assets unwrap` runs — the pre-step below); `--no-unwrap` skips it. A level in one GLB
+ * that wants groups or a zone is unwrapped by hand first (`lecodes assets unwrap --groups`), and then left alone here.
  */
 
 const range = (name: string, value: number, min: number, max: number): number => {
@@ -31,7 +37,7 @@ const range = (name: string, value: number, min: number, max: number): number =>
 }
 
 type BakeInstance = { key: string, receiver: boolean, page?: number, rect?: number[], st?: number[], texels?: number, area?: number, charts?: number, mean?: number[], sunVis?: number, skyVis?: number, share?: number }
-type BakeData = { version: number, size: number, pages: number, texel: number, lightScale: number, light: string[], aux: string[], direct?: string[], indirect?: string[], probes?: { file: string, size: number, levels: number, count: number, spacing: number } | null, volume?: { file: string, n: number[], cell: number[], valid: number } | null, texels?: number, instances: BakeInstance[], sun?: unknown, sky?: unknown, lights?: unknown[] }
+type BakeData = { version: number, size: number, pages: number, texel: number, lightScale: number, light: string[], aux: string[], direct?: string[], indirect?: string[], probes?: { file: string, size: number, levels: number, count: number, spacing: number } | null, volume?: { file: string, n: number[], cell: number[], valid: number } | null, uv1?: string | null, texels?: number, instances: BakeInstance[], sun?: unknown, sky?: unknown, lights?: unknown[] }
 
 const readBake = (file: string): BakeData => {
   if (!existsSync(file)) throw new CliError(`No bake at ${file} — run \`lecodes lightmap bake\` first.`)
@@ -52,6 +58,23 @@ const probeBoxOf = (s: string): [number, number, number, number, number, number]
   return [ Math.min(v[0], v[3]), Math.min(v[1], v[4]), Math.min(v[2], v[5]), Math.max(v[0], v[3]), Math.max(v[1], v[4]), Math.max(v[2], v[5]) ]
 }
 
+/** Every `--cube` on the line (`--cube a --cube b`, `--cube=a`): the argv grammar keeps a repeated flag's LAST value, so
+ *  the patterns are read off argv by its own rule — a value is the next token unless it starts with "-" (a negative
+ *  number aside). Each must compile as a regular expression here too (the bake's std::regex has the last word). */
+const cubePatternsOf = (argv: string[]): string[] => {
+  const out: string[] = []
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === "--") break
+    if (a.startsWith("--cube=")) out.push(a.slice("--cube=".length))
+    else if (a === "--cube" && i + 1 < argv.length && (!argv[i + 1].startsWith("-") || /^-(\d|\.\d)/.test(argv[i + 1]))) out.push(argv[++i])
+  }
+  for (const p of out) {
+    try { new RegExp(p) } catch (e) { throw new CliError(`bad --cube pattern: ${p} (${e instanceof Error ? e.message : String(e)})`) }
+  }
+  return out.filter((p) => p !== "")
+}
+
 /** A .bake with no pages and no scale: enough for the compiler to stage the files and for Lightmap.load to
  *  no-op with a "rebake" warning. The two KTX2 placeholders are 4x4 pages of the right formats. */
 const placeholderBake = (stem: string): string => JSON.stringify({ version: 4, placeholder: true, size: 4, pages: 0, texel: 0, lightScale: 0, light: [ `${stem}-light.ktx2` ], aux: [ `${stem}-aux.ktx2` ], instances: [] }) + "\n"
@@ -82,12 +105,81 @@ const ensurePlaceholders = (outDir: string, stem: string): void => {
   if (missing(probes)) writeFileSync(probes, ktx2Placeholder(143))   // a scene may list the probes before the first bake wrote them
   const grid = join(outDir, `${stem}.lgrid`)
   if (missing(grid)) writeFileSync(grid, "NONE")   // ... and the light grid: the engine refuses it with a "rebake" line
+  const uv1 = join(outDir, `${stem}-uv1.bin`)
+  if (missing(uv1)) writeFileSync(uv1, "NONE")     // ... and the packed uv1: a placeholder .bake names none, so nothing reads it
+}
+
+// ---- the unwrap pre-step --------------------------------------------------------------------------
+// The bake traces TEXCOORD_1, and a raw import has none: before the host runs, the GLBs the bundle names (asset()
+// compiles to `_creatorFetch.local("<name>")` — the reference list `app build desktop` ships by) whose JSON shows a
+// primitive the unwrap would lay out without one are unwrapped IN PLACE by lecodes-assets (`unwrapGlbFiles`, the
+// `lecodes assets unwrap` code). Nothing is rebuilt after it: the bundle names the files and carries none of their bytes,
+// and the run dir links them only when the host starts. A file that has TEXCOORD_1 is never opened past its JSON.
+
+type GltfJson = {
+  nodes?: { mesh?: number, skin?: number }[]
+  meshes?: { primitives?: { mode?: number, indices?: number, attributes?: Record<string, number> }[] }[]
+  accessors?: { count?: number }[]
+}
+
+/** A GLB's JSON chunk — the 20 header bytes and the chunk itself, never the binary one — or null when it is not a GLB. */
+const readGlbJson = (file: string): GltfJson | null => {
+  let fd: number | undefined
+  try {
+    fd = openSync(file, "r")
+    const head = Buffer.alloc(20)
+    if (readSync(fd, head, 0, 20, 0) !== 20) return null
+    if (head.readUInt32LE(0) !== 0x46546c67 || head.readUInt32LE(16) !== 0x4e4f534a) return null   // "glTF", then a "JSON" chunk
+    const json = Buffer.alloc(head.readUInt32LE(12))
+    if (readSync(fd, json, 0, json.length, 20) !== json.length) return null
+    return JSON.parse(json.toString("utf8")) as GltfJson
+  } catch {
+    return null
+  } finally {
+    if (fd !== undefined) closeSync(fd)
+  }
+}
+
+/** A primitive the unwrap lays out (a triangle list with a triangle in it, on a mesh no skinned node draws) without
+ *  TEXCOORD_1 — lecodes-assets' planUnwrap verdict, read off the JSON. */
+const lacksLightmapUv = (g: GltfJson): boolean => {
+  const skinned = new Set((g.nodes ?? []).filter((n) => n.skin !== undefined && n.mesh !== undefined).map((n) => n.mesh))
+  const count = (accessor: number | undefined): number => (accessor === undefined ? 0 : g.accessors?.[accessor]?.count ?? 0)
+  return (g.meshes ?? []).some((mesh, i) => !skinned.has(i) && (mesh.primitives ?? []).some((p) => {
+    const pos = count(p.attributes?.POSITION)
+    return (p.mode ?? 4) === 4 && pos > 0 && (p.indices === undefined ? pos : count(p.indices)) >= 3 && p.attributes?.TEXCOORD_1 === undefined
+  }))
+}
+
+/** The project GLBs the bundle names. */
+const referencedGlbs = (js: string, resources: BundleResource[]): string[] => {
+  const wanted = new Set([ ...js.matchAll(/(?:fetchLocal|_creatorFetch\.local)\("([^"]+)"\)/g) ].map((m) => m[1]))
+  return [ ...new Set(resources.filter((r) => !r.remote && !r.shader && r.absPath && /\.glb$/i.test(r.name) && wanted.has(r.name)).map((r) => r.absPath!)) ]
+}
+
+const unwrapReferenced = async (js: string, resources: BundleResource[], root: string, texel: number): Promise<void> => {
+  const glbs = referencedGlbs(js, resources)
+  const raw = glbs.filter((f) => { const g = readGlbJson(f); return g !== null && lacksLightmapUv(g) })
+  if (raw.length === 0) { note(`Lightmap uvs: the ${glbs.length} GLB(s) the app references carry them`); return }
+  note(`Unwrapping ${raw.length} of the ${glbs.length} GLB(s) the app references — no lightmap uvs; written in place (--no-unwrap skips)…`)
+  const assets = await loadPeer<typeof import("lecodes-assets/cli")>("lecodes-assets", "cli", { for: "lecodes lightmap bake (lightmap uvs)" })
+  const t0 = performance.now()
+  const rel = (f: string): string => relative(root, f).replace(/\\/g, "/")
+  const reports = await assets.unwrapGlbFiles(raw, {
+    texel,
+    onFile: (r) => {
+      if (r.status === "failed") warnErr(`${rel(r.input)}: ${r.summary} — it bakes without lightmap uvs`)
+      else logErr(c.dim(`  ${r.status === "unwrapped" ? "unwrapped " : ""}${rel(r.input)}: ${r.summary}`))
+    },
+  })
+  const count = (s: string): number => reports.filter((r) => r.status === s).length
+  note(`Lightmap uvs: ${count("unwrapped")} file(s) unwrapped${count("skipped") ? `, ${count("skipped")} had nothing to unwrap` : ""}${count("failed") ? `, ${count("failed")} failed` : ""} in ${((performance.now() - t0) / 1000).toFixed(1)} s`)
 }
 
 const bake = defineCommand({
   name: "bake",
   summary: "Bake the sun, the sky and the lamps into a lux atlas for the level's statics",
-  description: "Runs the app in the desktop host in bake mode: the statics are what the app registers with Lightmap.add (a scene file does it for every node no Physics aspect moves), the bake fires at its Lightmap.load call. Writes <out>/<name>.bake + <name>-light[_n].ktx2 (irradiance, BC6H) + <name>-aux[_n].ktx2 (sky visibility, the directional share and direction of the light) + <name>-probes.ktx2 (the reflection probes: a cubemap of the level's radiance per probe, prefiltered per roughness; --probe-spacing 0 = none). Needs a desktop host built with the CUDA toolkit and an NVIDIA card (LECODES_DESKTOP_EXE for a local build).\n\nProps need lightmap UVs first: lecodes assets doctor assets/props/*.glb --lightmap-uv",
+  description: "Runs the app in bake mode in lecodes-bake — the windowless host with the bake built in (no physics, 2D, audio, net or navmesh), downloaded on first use like the desktop host; LECODES_BAKE_EXE points at a local build (hosts/desktop build.ps1 -Bake). The statics are what the app registers with Lightmap.add (a scene file does it for every node no Physics aspect moves), the bake fires at its Lightmap.load call. Writes <out>/<name>.bake + <name>-light[_n].ktx2 (irradiance, BC6H) + <name>-aux[_n].ktx2 (sky visibility, the directional share and direction of the light) + <name>-probes.ktx2 (the reflection probes: a cubemap of the level's radiance per probe, prefiltered per roughness; --probe-spacing 0 = none). Needs a GPU with hardware ray tracing (--tracer).\n\nLightmap UVs: the GLBs the app references that have none (TEXCOORD_1) are unwrapped first, IN PLACE \u2014 the same as lecodes assets unwrap, run on just those files; a file that has them is left alone, --no-unwrap skips the step. A whole level in one GLB that wants --groups / --zone is unwrapped by hand first (lecodes assets unwrap --help).",
   flags: {
     out: str("where the atlas lands", { value: "<dir>", default: "assets/lightmap" }),
     name: str("file stem — one per baked level", { value: "<stem>", default: "lightmap" }),
@@ -103,7 +195,9 @@ const bake = defineCommand({
     bounces: num("path vertices at most (Russian roulette from the third); 0 = direct light only", { default: 3 }),
     "patch-samples": num("next-event samples per texel over the BRIGHT PATCHES of a first direct pass (sunlit floors, the ceiling around a lamp) — what keeps the bounce in dark rooms from arriving as impulses (every path vertex takes one more); 0 = the cosine paths alone", { default: 64 }),
     split: bool("also write <name>-direct[_n].ktx2 / <name>-indirect[_n].ktx2 — the pages the \"direct\" / \"indirect\" views bind (list them as env.lightmap.direct / .indirect)"),
-    denoise: str("OptiX's AI denoiser over: indirect = the bounce alone (the range 2026-09-16: bounce noise 57 % -> 23 % of the mean, per-instance means unchanged), no-sun = + the sky and the lamps (the sky through a small opening: 0..3 hits of 256 rays, a texel is one of four values), all = + the sun (its shadow edges too: a sunlit pillar's mean moved 6 %), none. School, two seeds: no-sun took the sky 1.8 % -> 0.5 %, the lamps 43 % -> 21 %", { value: "<none|indirect|no-sun|all>", default: "no-sun" }),
+    denoise: str("the AI denoiser (--denoiser) over: indirect = the bounce alone (the range 2026-09-16: bounce noise 57 % -> 23 % of the mean, per-instance means unchanged), no-sun = + the sky and the lamps (the sky through a small opening: 0..3 hits of 256 rays, a texel is one of four values), all = + the sun (its shadow edges too: a sunlit pillar's mean moved 6 %), none. School, two seeds: no-sun took the sky 1.8 % -> 0.5 %, the lamps 43 % -> 21 %", { value: "<none|indirect|no-sun|all>", default: "no-sun" }),
+    tracer: str("which GPU API traces: auto = OptiX where an NVIDIA driver with OptiX opens, else Vulkan ray query — any card with hardware ray tracing (RTX, Radeon RX 6000+, Arc) with its driver alone; optix / vulkan by name (the bake fails when it cannot open)", { value: "<auto|optix|vulkan>", default: "auto" }),
+    denoiser: str("which AI denoiser --denoise runs: auto = OptiX's on an NVIDIA card, else Intel Open Image Denoise (its CUDA / HIP / CPU device, the DLLs next to the host); optix / oidn by name. Independent of --tracer; one that cannot open is a warning and the pages stay as traced", { value: "<auto|optix|oidn>", default: "auto" }),
     "light-radius": num("lamps: the emitter's radius (m) — soft shadows, no 1/d² singularity", { default: 0.05 }),
     "sun-angle": num("sun angular diameter (deg)", { default: 0.53 }),
     bias: num("ray start offset from the surface (m)", { default: 0.01 }),
@@ -115,6 +209,9 @@ const bake = defineCommand({
     "probe-indoor": bool("keep only the probes under a roof — those whose open share of the sphere (rays from the point that meet nothing) is at most 15 %, holes in the geometry or not: outdoor statics reflect the sky through their baked sky visibility instead — an environment map without the ground, but no outdoor probe can reach indoors and the atlas shrinks"),
     "probe-layout": str("rooms = every indoor point of the grid slides to the middle of its room and the points of one room merge: one probe per room, far from the walls, its box the room (stations every ~8 m along a room over 12 m), outdoor points stay on the grid; grid = everything stays on the grid. Either way the pages carry which probes each block of texels sees (rays at bake time)", { value: "<rooms|grid>", default: "rooms" }),
     "min-texels": num("instances smaller than this many ATLAS TEXELS along every axis (x --texel: 12 at 5 cm = 0.6 m) get no place in the atlas: they still cast their baked shadow and bounce, their own light is baked where they stand (six sides, no atlas texels) — cartridges, boxes, pipe elbows, a fire extinguisher: a baked shadow does not read on them and their tight charts are where the seams are. 0 = everything bakes; --dry-run lists what falls under it", { default: 12 }),
+    "thin-texels": num("ROUND AND NARROW objects leave the atlas like --min-texels: an instance none of whose lightmap charts is wider than this many texels across its short side (at --texel) — a railing's tubes, a cable, a pipe run, blinds, a gun barrel. A strip of 1-3 texels around a tube cannot hold the light's change around it and its uv seam shows as a step (the range's railing: two texels 5 mm apart on the seam, one lit, one shadowed); the ambient cube baked where it stands is smooth. A flat object has a wide chart somewhere and stays. 0 = off; --dry-run lists what falls under it", { default: 4 }),
+    cube: str("BAKE AS CUBES BY NAME: a regular expression (ECMAScript, case-sensitive) searched in every record's key — <node path>@<ordinal>, one record per mesh of a model, so SM_pipe takes every pipe node and @1$ the second mesh of each. A record that matches leaves the atlas like a --min-texels / --thin-texels one, whatever its size or charts: an occluder whose own light is baked where it stands as ambient cubes (in slabs along a long one, --object-slab) — a pipe run, a fence, a prop whose lightmap seams show. Repeat the flag (--cube SM_pipe --cube SM_fence) or join with | in one (--cube \"SM_pipe|SM_fence\", quoted for the shell); a pattern that starts with - goes as --cube=<regex>. The scene's env.lightmap.cube adds its own patterns, a node's lightmap: 'cube' marks one node by hand; --dry-run lists what matches", { value: "<regex>" }),
+    "object-slab": num("A LONG object the atlas left out (--min-texels, --thin-texels, --cube) takes its light in SLABS of this many metres along the longest axis of its bounds — round(length / this) ambient cubes, 16 at most — a 6 m pipe run, a railing along a wall: one end under a lamp, the other in the dark, where one cube gave all of it the mean. The shader blends the two slabs around each pixel along that axis. 0 = one cube an object", { value: "<m>", default: 1 }),
     "emissive-nits": num("EMISSIVE SURFACES LIGHT THE LEVEL: cd/m² of emission 1.0 (emissive factor x strength x map) — every lit region of an emissive surface (a panel drawn in a ceiling's texture, a screen, a sign) bakes as a rectangle lamp. Default: what the level's camera makes of 1.0, 1.2 x 2^EV100, so a panel lights as brightly as it looks. 0 = emissive surfaces light nothing"),
     "detail-texels": num("A SMALL SURFACE GETS A FINER TEXEL: an instance whose surface is under this many atlas texels (area / texel²) is laid out denser by sqrt(this / its texels), 3x at most — a pipe of 1 m is ~300 texels at 5 cm, its charts a few texels wide and every chart edge a step; at 2000 it bakes at ~2 cm. 0 = off", { default: 2000 }),
     volume: num("THE LIGHT GRID for movers: the cell size in metres (0.75 of it tall) — per cell in free space the baked ambient light (sky, lamps, every bounce; not the direct sun, which stays real-time on movers), links between cells a ray connects so nothing blends through a wall; written as <name>.lgrid, list it as env.lightmap.volume. 0 = none", { default: 1 }),
@@ -123,22 +220,27 @@ const bake = defineCommand({
     "dry-run": bool("only the atlas LAYOUT: pages, texel size, the largest rects — no tracing, nothing written (seconds, not minutes; the host still loads the level)"),
     frames: num("host frames to run before giving up — load headroom", { default: 900 }),
     timeout: num("host time cap (ms; default: none)"),
-    width: num("host window width (default: app.json desktop.window, else 1280)"),
-    height: num("host window height (default: app.json desktop.window, else 720)"),
-    renderer: str("desktop host + shader variant (default: app.json desktop.renderer, else gl)", { value: "<gl|vulkan>" }),
+    width: num("the bake host's virtual viewport width — it has no window; nothing in the bake depends on it (default: app.json desktop.window, else 1280)"),
+    height: num("the bake host's virtual viewport height (default: app.json desktop.window, else 720)"),
+    renderer: str("ignored: the bake host is one binary (lecodes-bake, GL shaders on Filament's NOOP backend); kept so older scripts still parse", { value: "<gl|vulkan>" }),
     logs: bool("forward the host's output"),
+    "no-unwrap": bool("leave the referenced GLBs as they are: no lightmap unwrap of those without TEXCOORD_1 (they bake without lightmap uvs)"),
   },
   examples: [ "lecodes lightmap bake", "lecodes lightmap bake --entry school.ts --name school --texel 0.04 --pages 4 --debug-dir .lightmap/school --logs" ],
-  run: async ({ flags }) => {
+  run: async ({ flags, argv }) => {
     const { root } = localProject()
     const outDir = resolve(root, flags.out)
     const stem = flags.name
+    const cube = cubePatternsOf(argv)
     if (!/^[A-Za-z0-9_-]+$/.test(stem)) throw new CliError(`--name wants a plain file stem (letters, digits, - and _), got "${stem}".`)
     const entryFile = flags.entry
     if (!existsSync(resolve(root, entryFile))) {
       throw new CliError(`No ${entryFile} in ${root} — pass --entry <file> (the file that builds the scene and calls Lightmap.load).`)
     }
     const debugDir = flags["debug-dir"] ? resolve(root, flags["debug-dir"]) : ""
+    if (!["none", "indirect", "no-sun", "all"].includes(flags.denoise)) throw new CliError(`--denoise wants none, indirect, no-sun or all, got "${flags.denoise}".`)
+    if (!["auto", "optix", "vulkan"].includes(flags.tracer)) throw new CliError(`--tracer wants auto, optix or vulkan, got "${flags.tracer}".`)
+    if (!["auto", "optix", "oidn"].includes(flags.denoiser)) throw new CliError(`--denoiser wants auto, optix or oidn, got "${flags.denoiser}".`)
     const cfg = {
       outDir: outDir.replace(/\\/g, "/"),
       stem,
@@ -157,6 +259,8 @@ const bake = defineCommand({
       patchSamples: range("patch-samples", flags["patch-samples"], 0, 1024),
       split: !!flags.split,
       denoise: flags.denoise,
+      tracer: flags.tracer,
+      denoiser: flags.denoiser,
       filter: range("filter", flags.filter, 0, 4),
       probeSpacing: range("probe-spacing", flags["probe-spacing"], 0, 100),
       probeSize: range("probe-size", flags["probe-size"], 16, 128),
@@ -164,6 +268,9 @@ const bake = defineCommand({
       probeIndoor: !!flags["probe-indoor"],
       probeLayout: probeLayoutOf(flags["probe-layout"]),
       minTexels: range("min-texels", flags["min-texels"], 0, 10000),
+      thinTexels: range("thin-texels", flags["thin-texels"], 0, 64),
+      objectSlab: range("object-slab", flags["object-slab"], 0, 100),
+      ...(cube.length ? { cube } : {}),
       volumeSpacing: range("volume", flags.volume, 0, 100),
       detailTexels: range("detail-texels", flags["detail-texels"], 0, 1e7),
       ...(flags["emissive-nits"] !== undefined ? { emissiveNits: range("emissive-nits", flags["emissive-nits"], 0, 1e7) } : {}),
@@ -187,12 +294,13 @@ const bake = defineCommand({
     ensurePlaceholders(outDir, stem)
     if (debugDir) mkdirSync(debugDir, { recursive: true })
 
-    const desktopRenderer = resolveDesktopRenderer(root, flags.renderer)
+    const desktopRenderer = "gl" as const   // lecodes-bake is the GL tree on Filament's NOOP backend: `_creator.backend` "desktop" fetches the GL shaders
     const { js, resources } = await buildBundle(bundleOptions(flags), {
       localAssets: true, desktopRenderer,
       extraEntries: [{ path: entryPath, type: "text", text: entryText }],
       entryOverride: entryPath,
     })
+    if (!flags["no-unwrap"]) await unwrapReferenced(js, resources, root, cfg.texel)
 
     // The host writes the bake itself; the PNG the render driver insists on goes to a scratch dir.
     const scratch = mkdtempSync(join(tmpdir(), "lecodes-lightmap-"))
@@ -204,7 +312,7 @@ const bake = defineCommand({
     try {
       const timeoutMs = flags.timeout || 24 * 3600 * 1000
       const res = await runDesktopRender(js, resources, {
-        renderer: desktopRenderer, width, height, frames, outPng, logs: flags.logs, timeoutMs,
+        host: "bake", renderer: desktopRenderer, width, height, frames, outPng, logs: flags.logs, timeoutMs,
         stopOnLine: (chunk) => chunk.includes("[lightmap] done") || chunk.includes("[lightmap] error"),
       })
       output = res.output
@@ -223,7 +331,7 @@ const bake = defineCommand({
       logErr(text.startsWith("error") ? c.red(`✗ ${text}`) : text.startsWith("warning") ? c.yellow(`  ${text}`) : c.dim(`  ${text}`))
     }
     if (flags["dry-run"] && /\[lightmap\] done/.test(output)) {
-      for (const l of lines) if (/atlas \d+ x|larger rect|largest rect|do not fit|charts touch/.test(l)) logErr(l.replace(/^\[lightmap\] /, "  "))
+      for (const l of lines) if (/atlas \d+ x|packed per file|largest rect|do not fit|fill:|--cube|lightmap: 'cube'/.test(l)) logErr(l.replace(/^\[lightmap\] /, "  "))
       logErr(c.green("✓ layout only — nothing written"))
       return
     }
@@ -236,13 +344,15 @@ const bake = defineCommand({
       const probeFiles = data.probes ? ` + ${data.probes.file} (${data.probes.count} probe(s) of ${data.probes.size}² at ${data.probes.spacing} m)` : ""
       const gridFile = data.volume ? ` + ${data.volume.file} (light grid ${data.volume.n.join(" x ")}, ${data.volume.valid} cell(s) in free space)` : ""
       const probeDef = (data.probes ? `, probes: asset('<rel>/${rel(data.probes.file)}')` : "") + (data.volume ? `, volume: asset('<rel>/${rel(data.volume.file)}')` : "")
-      logErr(c.green(`✓ baked → ${relative(root, outDir) || "."}/${stem}.bake + ${data.light.join(", ")} + ${data.aux.join(", ")}${splitFiles}${probeFiles}${gridFile}`))
+        + (data.uv1 ? `, uv1: asset('<rel>/${rel(data.uv1)}')` : "")
+      const uv1File = data.uv1 ? ` + ${data.uv1} (the packed lightmap uv1 — list it as env.lightmap.uv1, the rects map it)` : ""
+      logErr(c.green(`✓ baked → ${relative(root, outDir) || "."}/${stem}.bake + ${data.light.join(", ")} + ${data.aux.join(", ")}${splitFiles}${probeFiles}${gridFile}${uv1File}`))
       logErr(c.dim(`  scene file: env.lightmap: { data: asset('<rel>/${rel(`${stem}.bake`)}'), light: ${assets(data.light)}, aux: ${assets(data.aux)}${splitDef}${probeDef} }  — asset() paths are relative to the scene file`))
       if (debugDir) logErr(c.dim(`  debug layers: ${relative(root, debugDir)} (lecodes lightmap inspect --bake ${relative(root, join(outDir, `${stem}.bake`)).replace(/\\/g, "/")} --debug-dir ${relative(root, debugDir).replace(/\\/g, "/")})`))
       return
     }
-    if (lines.some((l) => /no bake module/.test(l))) {
-      throw new CliError("This desktop host has no bake module. Build hosts/desktop with the CUDA toolkit installed and point LECODES_DESKTOP_EXE at build/lecodes-desktop.exe.")
+    if (/\[lightmap\] error: this host has no bake module/.test(output)) {   // console.error: the host prefixes the line ("[ERROR] [lightmap] …")
+      throw new CliError("This host has no bake module — the bake runs in lecodes-bake. Point LECODES_BAKE_EXE at it (hosts/desktop: build.ps1 -Bake → build-bake/lecodes-bake.exe), or unset it to use the published one.")
     }
     if (lines.some((l) => /error/.test(l))) throw new CliError("The bake failed — see the lines above.")
     warnErr("The host ran to its frame cap without baking. Make sure the app calls Lightmap.load(...) after the static scene is built, and skips menus when Lightmap.baking is true. More load headroom: --frames <n>. Host output: --logs.")

package/src/declarations/lecodes-assets.d.ts

@@ -1,7 +1,34 @@
-// Types for the optional `lecodes-assets` package's CLI entry (lazy-loaded by the `assets` command).
-// The real package is installed separately; this lets the dynamic import typecheck without it
-// present. Keep in sync with tools/assets/src/cli.ts.
+// Types for the optional `lecodes-assets` package's CLI entry (lazy-loaded by the `assets` command
+// and `lightmap bake`'s unwrap pre-step). The real package is installed separately; this lets the
+// dynamic import typecheck without it present. Keep in sync with tools/assets/src/cli.ts.
 declare module "lecodes-assets/cli" {
-  /** Runs `convert | probe | doctor` with the given argv (sub-command first). Resolves to the exit code. */
+  /** Runs one `lecodes assets` command line (sub-command first). Resolves to the exit code. */
   export function runAssetsCli(argv: string[]): Promise<number>
+
+  /** One file's outcome (tools/assets src/unwrap UnwrapFileReport, the fields the CLI reads). */
+  export interface UnwrapFileReport {
+    input: string
+    /** where the unwrapped file went; null when nothing was written */
+    output: string | null
+    status: "unwrapped" | "skipped" | "failed"
+    reason?: string
+    /** one line: what the unwrap made of the file */
+    summary: string
+    ms: number
+  }
+  /** The lightmap unwrap (TEXCOORD_1, xatlas) of whole GLB files, IN PLACE unless `out` says where; a file that
+   *  carries TEXCOORD_1 is skipped unless `force`. Never throws for a file's sake: a failure is its report. */
+  export function unwrapGlbFiles(files: string[], opts?: {
+    force?: boolean
+    out?: string
+    /** the bake's texel (m) the fixed chart padding is measured in */
+    texel?: number
+    iterations?: number
+    groups?: number
+    zone?: string
+    zoneNear?: number
+    zoneMax?: number
+    zoneUp?: number
+    onFile?: (r: UnwrapFileReport) => void
+  }): Promise<UnwrapFileReport[]>
 }