@threenative/assets 0.3.0 → 0.3.2

package/LICENSES/Basis-Universal-Apache-2.0.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2019-2026 Binomial LLC
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -7,8 +7,55 @@ managed file.
 
 Node-only. Carries the encoder dependencies the runtime must never inherit.
 
+## The delete-test, and the receipt that makes it possible
+
+Every baking pass in here obeys one rule: **delete the entire baked output and the game runs
+identically, just slower.** That is what separates a baking pass from a compiler of game meaning —
+the thing this project has already tried once and deleted. A pass that cannot pass the delete-test
+does not ship.
+
+Each compile therefore writes `public/bake.receipt.json` beside the manifest, listing every file
+the run produced — compiled outputs, auxiliary outputs like the lightmap atlas, and the Basis
+transcoder — with the producer and the source each came from. The producer writes it because only
+the producer knows: a consumer that reconstructed the list by globbing `public/` would either miss
+an output or delete a source asset, and both mistakes look like a passing test.
+
+Two consequences worth knowing before you add a pass:
+
+- **A pass that writes a file it does not declare fails the build**, by name
+  (`TN_ASSETS_UNDECLARED_OUTPUT`). Declare auxiliary outputs through `auxiliaryOutputs`.
+- **Nothing in the shipped runtime reads the receipt.** `@threenative/core` falls back to the
+  source path when the manifest is absent, and deleting the receipt is part of the test.
+
+`pnpm bake:delete-test --template starter` runs it: build, switch the dev server's asset watcher
+off so it cannot re-bake what is about to be deleted, run the scenario, delete every file the
+receipt names plus the manifest and the receipt, run the same scenario again, and compare. The
+comparison is against a same-code band measured in the same run — captures are not
+bit-deterministic — not against an assumed zero.
+
+It went in **red**, and the red was the finding: the loader's no-manifest fallback resolved
+`<basePath>/<logical path>`, which in a compiled project points at nothing, because the sources live
+in `assets/` and the outputs are content-addressed. A logical path now resolves against an ordered
+candidate list — verbatim first, then the source directory — and the gate is green. It runs as part
+of `pnpm test:templates`, not in CI: the delete-test compares captured frames, and the CI job that
+scaffolds templates deliberately runs only non-visual scenarios because its runner has no GPU. A run
+there reports `frames: 0`, which is the runner, not the game. The account is in
+`docs/verification/bake-delete-test-2026-08-31.md` and `delete-test-passes-2026-09-01.md`.
+
 ## Embedded model textures
 
+| Setting | Default | Override |
+| --- | --- | --- |
+| `assets.models.sharedImages` | `true`: write each distinct image once under `shared/images/` | `false` embeds and re-encodes duplicate images in every model |
+
+With no asset config, models share their content-addressed images across the build and reuse the
+store on later builds. Tiny images retain their original bytes when KTX2 would grow the download
+without reducing resolution; an explicit slot codec override can still force compression.
+Automatic cooking also retains sources whose encode dimensions are not divisible by four,
+without changing their bytes or dimensions. The report and manifest name `block-size` as the
+reason; these retained bytes still count toward the uncooked budget. An explicit compression
+codec override rejects an unaligned image, while `codec: "none"` remains available.
+
 The images inside a `.glb` go through the pipeline too, on by default. A prop carrying three
 2048x2048 JPEGs is a small file and about 64 MiB of VRAM once the driver decodes it, so each
 embedded image is transcoded to KTX2/Basis (UASTC for normal maps, ETC1S for colour and
@@ -77,9 +124,10 @@ reduces further. Because that gap is silent by nature, the compile step prints b
 simplified candela.glb: 99482 -> 15104 triangles (15.2% kept, requested 5.0%) — the error tolerance 0.001 stopped it short
 ```
 
-Mobile native targets still refuse compressed assets — Android QuickJS and iOS JSC have no
-WebAssembly and therefore no Basis transcoder — so an Android or iOS build needs
-`assets.models: "none"`, exactly as it already did for compressed geometry.
+Android QuickJS and iOS JSC have no WebAssembly and therefore no Basis transcoder. The build
+automatically skips the unsupported texture and model passes for those targets; games do not
+need an `assets.models: "none"` override. Already-compressed source assets still fail native
+preflight when their required decoder is unavailable.
 
 ## Static lightmaps
 
@@ -104,3 +152,101 @@ fail closed on KTX2 because those native hosts do not yet carry a decoder.
 | Web gameplay | Packed-tarball sandbox required `material.lightMap` before reaching the goal could win. |
 | Negative control | Setting `material.lightMap = null` made `staticLightReady` and the win assertion fail. |
 | Native status | Linux desktop rendered the packed GLB/KTX2 with a clean playtest; Android/iOS still fail closed because their hosts have no KTX2 decoder. |
+
+## Audio conditioning
+
+`AssetKind` classified `.ogg`, `.wav` and `.mp3` as audio from the beginning and nothing acted on
+it, so audio was classified and then shipped through untouched. This pass does the conditioning a
+game should never hand-roll, and — like the model pass — measures its own output rather than
+trusting that the chain behaved.
+
+Which clips loop, which are positional, and what a clip is *for* are facts only the game knows, so
+every one of them is declared. There is no filename convention: a pass that decided `chime.ogg`
+must be a chime would be confidently wrong on the first asset named against it.
+
+```ts
+assets: {
+  audio: {
+    overrides: [
+      { glob: "audio/*-bed.ogg", loop: true },
+      { glob: "audio/music/*.ogg", loop: { crossFadeMs: 0 } },
+      { glob: "audio/step-*.ogg", positional: true, spectrum: { band: "sub", maxPercent: 15 } },
+      { glob: "audio/landmark.ogg", spectrum: { band: "high", minPercent: 40 } },
+    ],
+  },
+}
+```
+
+| Declaration | What it turns on |
+| --- | --- |
+| `loop: true` | Equal-power tail-onto-head cross-fade, then the seam assertion below. |
+| `loop: { crossFadeMs: 0 }` | Keeps the clip's own length — a bar-accurate musical loop — and still asserts the seam. |
+| `loop: { spliceToleranceMs }` | How far the splice may move to find a quiet join. Default 25 ms. |
+| `positional: true` | Mono downmix, which halves the decoded cost as well as the wire cost. |
+| `spectrum: { band, minPercent }` | Fails the build when too little of the clip's energy is in the band it is for. |
+| `spectrum: { band, maxPercent }` | Fails the build when too much of it is somewhere it should not be. |
+| `normalise: "peak"` | Lifts a quiet clip to the ceiling. Off by default: see below. |
+| `peakDb` | The ceiling, in dBFS. Default `-1`. |
+| `conditioning: "none"` | Ships the bytes as committed. Measurement, and a declared loop's assertion, still run. |
+| `assets.audio: "none"` | Drops the pass, exactly as `textures: "none"` drops the KTX2 pass. |
+
+**Ogg Vorbis is forced, not preferred.** `packages/runtime-native`'s `decodeAudioFile` implements
+exactly RIFF/WAVE and Ogg Vorbis, compiled into desktop, Android and iOS alike, so an MP3 asset is
+silent on every native target. The pass therefore reads only those two containers and fails the
+bake, naming the file and the re-encode command, rather than letting a build reach a player and
+play nothing. Both codecs are in-process WASM — as with the KTX2 pass, users install nothing extra
+and there is no `ffmpeg` in the install story.
+
+**Content is the check that matters most.** The hand pass this replaces got every join right and
+never looked at what was *in* the clips: it shipped a chime that was 83% low-mid where a struck bell
+should be, and fifteen footsteps carrying up to 45% of their energy below 100 Hz — a band a wood has
+nothing in, and which spends a phone speaker's whole headroom on something nobody can hear. A seam
+check alone would have caught neither, which is why both a floor and a ceiling are declarable.
+
+Bands are named, not measured in Hz, and the names and edges are the audio inspector's own — `sub`
+(0-100 Hz), `low` (100-500), `mid` (500-2k), `high` (2k-8k), `air` (8k-Nyquist) — so a game declares
+one band in one vocabulary and means the same thing to the build gate and to
+`packages/playtest`'s inspector. Percentages are on the same 0-100 scale for the same reason. Every
+clip's full five-band profile is measured and reported whether or not a bound was declared.
+
+**The seam is judged as a ratio, not a magnitude.** A click is a step that is anomalous *where it
+happens*: the same 0.02 jump is inaudible under a dense bed and an obvious tick in near-silence, so
+an absolute bound condemns loud clips and excuses quiet ones. What the pass measures is the wrap
+step against the 99th-percentile ordinary step within 50 ms of the join, and the default limit is
+`1.5x` — not `1.0x`, because a flawless wrap that lands on the signal's steepest point legitimately
+*is* the largest step in its neighbourhood, and a looped pure sine scores `1.000000000000223` there
+on float error alone. This is the same measurement `packages/playtest`'s audio inspector makes, so
+the build gate and the inspector cannot disagree about one file; `audio-seam-parity.spec.ts` pins
+them together.
+
+It is measured on the **decoded output bytes**, because a cross-fade that is exact in the
+intermediate PCM and undone by the encoder is still a click in the player's ears.
+
+**The fade length is not a lottery ticket, and this was checked rather than assumed.** After a
+tail-onto-head cross-fade the wrap step is exactly the source's own adjacent-sample delta wherever
+the splice lands, so with a fixed fade length the *bare step* is a draw from the material's step
+distribution — on one real bed it moved from 0.0084 at a 250 ms fade to 0.0807 at 400 ms, a spread
+that would make a magnitude gate's verdict luck. In the ratio the gate actually reads, the same
+sweep over 17 fade lengths and three real beds stays between 0.00x and 0.89x and never reaches the
+1.5x limit, because the numerator and denominator move together. The pass also searches a declared
+tolerance for the quietest join, which takes it to 0.00x at every fade length tested and 0.00x-0.23x
+after a real encode.
+
+The one configuration that can still lose that lottery is `spliceToleranceMs: 0`, which pins the
+fade where the declared length puts it. When the gate fires it says which situation the build is in
+— splice pinned, no fade at all, or a search that had room and found nothing — and it deliberately
+never offers raising `seamMaxRatio` or walking `crossFadeMs` as the way out, because a throwing gate
+people learn to tune around is worse than no gate.
+
+**The peak is a ceiling, not a target.** Normalising every clip up to one level would make a
+footstep as loud as a chime and force the game to undo the pipeline in its volume settings — that
+is deciding how the game sounds, and it belongs to the game.
+
+**A pass with nothing to do says so.** A source that is already Ogg Vorbis, already the right
+channel count, under the ceiling and carrying no DC is shipped byte-identical, because re-encoding
+it would cost a generation of lossy Vorbis to deliver the same audio.
+
+Measured over one game's nineteen generated clips: the three declared beds cross-fade to seam
+ratios of `0.10x`, `0.03x` and `0.10x`, and the other sixteen pass through byte-identical. The
+declared-band checks fail the build on both of that game's real defects — the chime that came back
+a hum, and the footsteps built out of sub-bass — neither of which any seam check would have seen.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,48 @@
+# Third-party notices
+
+The private KTX2 adapter in this package derives from `ktx2-encoder` 0.6.0, copyright 2020
+Hu Song, under the MIT License. Its bundled `basis_encoder.js` and `basis_encoder.wasm` derive
+from Basis Universal, copyright 2016–2026 Binomial LLC, under Apache License 2.0.
+
+The Basis build is intentionally modified from upstream commit
+`1b33fd5098c6e7b58324146b8f5518cbb4cdfb72`: the wasm32 ceiling for the lower-memory ETC1S and
+UASTC LDR 4x4 compressors is raised from 12 to 16 Mi texels. The conservative HDR ceiling is
+unchanged. The modified source patch and reproducible build are in `scripts/`.
+
+Build provenance:
+
+- Emscripten 4.0.15 container digest:
+  `sha256:27bc6267cb285223b8aebb7627bfebae7cb3ad2aaa0d5923b8aa5321793033e8`
+- Configuration: wasm32, non-threaded Release, `KTX2_ZSTANDARD=ON`, `SUPPORT_ASTCENC=OFF`,
+  `-s EXPORT_ES6=1`
+- `basis_encoder.js` SHA-256:
+  `059621ec63379c496ac93814f53afc6c7065ecdf6291b2ac8db951cb7bac4c64`
+- `basis_encoder.wasm` SHA-256:
+  `f020c8ed7d2ccadf752c0e64b86195f09e0bfeacc2de3d94b28c89ea72ce5bd5`
+
+The complete MIT and Apache-2.0 license texts remain available from the upstream projects:
+https://github.com/gz65555/ktx2-encoder and https://github.com/BinomialLLC/basis_universal.
+The Apache-2.0 text is also shipped in `LICENSES/Basis-Universal-Apache-2.0.txt`.
+Basis Universal's NOTICE attribution is:
+
+> Basis Universal™ Supercompressed GPU Texture Compression Library. Copyright © 2016–2026
+> Binomial LLC. All rights reserved except as granted under the Apache 2.0 license. Basis
+> Universal is a trademark of Binomial LLC.
+
+The MIT terms for the derived `ktx2-encoder` portions are:
+
+> Copyright (c) 2020 HU SONG
+>
+> Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+> and associated documentation files (the "Software"), to deal in the Software without
+> restriction, including without limitation the rights to use, copy, modify, merge, publish,
+> distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
+> Software is furnished to do so, subject to the following conditions: the above copyright notice
+> and this permission notice shall be included in all copies or substantial portions of the
+> Software.
+>
+> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+> BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+> NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+> DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+> OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/apply-worker.d.ts

@@ -0,0 +1,2 @@
+
+export {  }