@jgengine/assets 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,7 +1,8 @@
 # Changelog
 
-All eight `@jgengine/*` packages are versioned in lockstep, so this one file
-covers every release. Format follows [Keep a Changelog](https://keepachangelog.com);
+The lockstep game SDK set is `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`
+(this file’s 0.x.y releases). The CLI package `jgengine` and `@jgengine/github` use
+**separate** version lines and may lag. Format follows [Keep a Changelog](https://keepachangelog.com);
 each release **leads with a Migrate block** — the concrete steps to move a game
 from the previous version onto the new APIs — because the point of a bump is to
 let consumers pick up the better stuff, not just to list what moved.
@@ -11,6 +12,42 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## 0.12.0
+
+### Migrate
+
+- **Author games through `defineGame` from `@jgengine/shell`** — it is the single public authoring entry (and carries the define-game capability tag). Core's constructor was renamed `defineGame` → `defineGameDefinition` (`@jgengine/core/game/defineGame`); only hosts and tooling call it. If you imported `defineGame` from core, switch the import to `@jgengine/shell`. `GamePlayer`/`GamePlayerShell` are `@internal` now — `GameHost` is the documented mount, and it owns the editor summon (`?mode=editor`, F2+E, dev save endpoint), so delete any per-game editor bootstrap.
+- **Declare your world with `world()`** (`@jgengine/core/world/place`): `world({ id, ground: { mode, size, surface? }, physics? })` with `flat` / `round` / `voxel` / `board` ground. New scaffolds emit a thin infinite flat place instead of the old 96 m meadow. `environment()` still works but is demoted to the legacy consumption path for editor-written scene data — **nothing required** for existing games; new worlds should use `world()` and author all dressing in the editor.
+- Everything else is additive — stat pools, minimap marker sources, auction house, city/path generation, editor workspaces require no changes to existing games.
+
+### Added
+
+- **World = place: `world()` API** (#1178) — a world is substrate + laws, not a coded diorama. `@jgengine/core/world/place` ships `world({ id, ground: { mode, size, surface?, generator? }, physics? })`; size is discriminated by mode (flat `{x,z}` with `Infinity` axes, round `{radius}`, voxel generator domain, board `{x,y}` cells — TS and runtime both reject mismatches). `ground.surface` carries matter/feel laws (metal vs slime vs felt) read by the same rule systems; per-place `physics` resolves over the game default; multiple worlds per game are first-class. The shell renders place substrates (`PlaceScene`) under the engine default sky; seeds derive from world id + save via `seedForPlace`.
+- **`@jgengine/shell/gameKit`** — happy-path authoring surface: authoring, mount, stores, systems, authored-scene helpers, HUD primitives, seeded rng in one import.
+- **Portable generic stat pools** — `@jgengine/core/stats/statPool`: bounded named pools (health, energy, heat, ammo…) with the entity-stats integration rebuilt on them; recipe in skill `jgengine-combat`.
+- **Auction-house economy primitives** (#1086) — `@jgengine/core/economy/auctionBook` (timed bid auctions, escrowed bids, outbid refunds, optional buyout, anti-snipe close extension, seller settlement minus house cut) plus market price history.
+- **Portable minimap marker sources** — core world seam feeding game minimaps; recipe in skill `jgengine-ui`.
+- **Unified seed-driven path network + city generation v2** (#1103, #1106) — streets/blocks/buildings with grid-ness, curviness, branching and block-size dials; zone bands, weighted building-class mixes, massing pieces, balance presets, junction-centered clustering, road-derived block polygons and parcels. Shell renders realistic roads: real intersections, curbs, lane lines, tunnels, and roads riding bridge decks.
+- **Physical fidelity** — mesh-accurate hitboxes (shots pass through holes in concave models, #1075), auto-fit entity/object colliders from measured model bounds (#1072), movement obstruction reading fitted boxes + compound-box openings (#1077).
+- **Editor overhaul** (#1110) — materials / lighting / scripting / animation-timeline / multiplayer workspaces, command palette, minimap bake wired end-to-end (#1036), real offscreen GLB thumbnails in the content browser, hierarchy drag-drop + keyboard + context menus + per-object visibility/lock, multi-select inspector, console RPC, asset drag-place, ortho projection, pivot modes, play chrome.
+- **Editor authoring pipeline** — author entity definitions and starter catalogs (#1012), author catalogs/schema fields in the Data tab (#1043), promote an authored scene folder into a runnable game (#1011), authored triggers promoted to a shared primitive with goal/win rules (#1013), asset import rewrites the game's `game/assets.ts` (#1042).
+- **Skills** — research-backed `game-design` and `level-design` skills (#962); every-game-owns-custom-UI invariant codified (#1148).
+
+### Changed
+
+- `npx jgengine create` scaffolds a thin infinite flat `world()` place; the editor `blankWorld` no longer pre-bakes seeded grass. Dressing belongs in `editor.scene.json`.
+- Environment studio visual-quality pass — turf tufts, depth-aware water, relief soil, weathered poles; grass fields no longer rebuild geometry per frame (#1090).
+
+## 0.11.0
+
+### Migrate
+
+- **Nothing required** — classic `loop.onTick` fan-out still runs after systems. Prefer moving per-frame work into `defineGame({ systems: [...] })` with `defineSystem` (`@jgengine/core/game/defineSystem`); install a system with `feature: "quest"` (etc.) instead of a redundant `features` flag. See skill `jgengine` → [reference-systems.md](.claude/skills/jgengine/reference-systems.md).
+
+### Added
+
+- **Composable game systems** (#842) — `defineSystem` / `compileSystemSchedule` / `composeGameLoop` / `installSystems`. `defineGame({ systems })` is the single authoring path: fixed / frame / interval / event-only / manual ticks, multi-subscribe channels, deterministic stage order + optional `before`/`after`/`dependsOn`, system-owned save / replicate / reset / dispose. Installing a system activates its `feature` without a separate flag. `GameLoop` gains optional `onReset` / `onDispose`. `ctx.game.registerSave` / `registerReplicate` for system modules. Adopters: tower-guard, claudecraft (runtime without a giant tick fan-out).
+
 ## 0.10.0
 
 ### Migrate

package/README.md

@@ -1,37 +1,45 @@
 # @jgengine/assets
 
-A self-generating, license-verified index of thousands of CC0 3D models — hosted at **zero cost**. No GLB bytes ship in the npm tarball; every byte comes from infrastructure you don't pay for:
+A self-generating, license-verified index of thousands of CC0 3D models, PBR materials, **and 2D sprite/icon packs** G�� hosted at **zero cost**. No GLB, texture, or sprite bytes ship in the npm tarball; every byte comes from infrastructure you don't pay for:
 
 | What | Where it lives | Whose bandwidth |
 |------|----------------|-----------------|
-| Pack GLBs (Kenney, Quaternius, KayKit…) | Fetched at `pull` time from the provider's CDN | Provider's |
+| Pack GLBs (Quaternius, KayKitGǪ) | Fetched at `pull` time from the provider's CDN | Provider's |
+| PBR materials (ambientCG) | Fetched at `pull` time (provider or the `packs` release mirror) | Provider's / GitHub's |
+| Sprite/icon packs (game-icons.net) | Fetched at `pull` time (provider or the `packs` release mirror) | Provider's / GitHub's |
 | The generated index (JSON) | Inside this npm package | npm (KB) |
 | Your one-off models | `packages/assets/local/`, served via jsDelivr-over-GitHub | GitHub + jsDelivr |
-| A consumer's downloaded bytes | Their `public/models/` (gitignored) | The consumer's |
+| A consumer's downloaded bytes | Their `public/models/` + `public/materials/` + `public/sprites/` (gitignored) | The consumer's |
 
 ## Layers
 
-1. **Sources** (`src/sources/*.ts`) — one entry per downloadable pack. Every entry carries required `license` + `author` and a `download` that is either a pinned `{ url, sha256? }` or a `{ scrape }` marker.
-2. **Generated index** (`src/generated/*.json`) — machine-produced from the real `.glb` filenames after a pack is extracted. Never hand-typed. Committed JSON; bytes are not.
-3. **Aliases** (`src/aliases.ts`) — hand-authored semantic keys (`nature/tree_pine → kenney-nature/tree_pineDefaultA`).
-4. **Singles** (`src/singles.json`) — long-tail one-offs (per-model `url` + `license`).
+1. **Sources** (`src/sources/*.ts`) G�� one entry per downloadable pack. Every entry carries required `license` + `author` and a `download` that is either a pinned `{ url, sha256? }` or a `{ scrape }` marker.
+2. **Generated index** (`src/generated/*.json`) G�� machine-produced from the real `.glb` filenames after a pack is extracted. Never hand-typed. Committed JSON; bytes are not.
+3. **Aliases** (`src/aliases.ts`) G�� hand-authored semantic keys (`nature/tree_pine G�� quaternius-stylized-nature/Pine_1`).
+4. **Singles** (`src/singles.json`) G�� long-tail one-offs (per-model `url` + `license`).
+5. **Materials** (`src/sources/ambientcg.ts` + `src/materials.ts`) G�� `kind: "material"` sources, one CC0 PBR material each (hundreds of ambientCG materials: grass, rock, wood, brick, metal, fabricGǪ). `pull` normalizes the maps to fixed filenames, so `buildMaterialCatalog({ basePath })` resolves ids and `material/GǪ` aliases to map URLs with no generated index at all.
+6. **Sprites** (`src/sources/gameicons.ts` + `src/spriteIndexGen.ts`) G�� `kind: "sprite"` sources, packs of individual SVG/PNG icon and UI files (game-icons.net's ~4,000 CC BY 3.0 icons as one mirrored repo). Same shape as models G�� `reindex-sprites` discovers real files after a pull and writes `src/generated-sprites/*.json`, resolved through `buildSpriteCatalog({ basePath })`.
 
-Everything collapses into the core `AssetCatalog` via `buildCatalog({ basePath })`.
+Model entries collapse into the core `AssetCatalog` via `buildCatalog({ basePath })`; materials resolve through `buildMaterialCatalog({ basePath })`; sprites/icons resolve through `buildSpriteCatalog({ basePath })`.
 
-## `add` — one command for anything
+## `add` G�� one command for anything
 
-`assets add <query>` is the front door. It fuzzy-searches **every** catalog at once — 3D models, whole packs, HUD components (the shadcn registry), and `game-icon` glyphs — then does the fetch and prints the exact copy-paste wiring. One mental model instead of four.
+`assets add <query>` is the front door. It fuzzy-searches **every** catalog at once G�� 3D models, whole packs, PBR materials, sprite/icon packs, HUD components (the shadcn registry), and `game-icon` glyphs G�� then does the fetch and prints the exact copy-paste wiring. One mental model instead of six.
 
 ```bash
-assets add astronaut --dir ../../apps/dev/public   # model → pull + reindex + print the assets.ts snippet
-assets add nature    --dir ../../apps/dev/public   # whole pack → pull + reindex + how to wire an id
-assets add "mana bar"                              # HUD component → the `npx shadcn add` cmd + <VitalBar/> usage
-assets add sword                                    # icon → the game-icon name to drop in a slot
+assets add astronaut --dir ../../apps/dev/public   # model G�� pull + reindex + print the assets.ts snippet
+assets add nature    --dir ../../apps/dev/public   # whole pack G�� pull + reindex + how to wire an id
+assets add grass --kind material --dir ../../apps/dev/public  # PBR material G�� pull maps + resolve snippet
+assets add "game icons" --dir ../../apps/dev/public  # sprite pack G�� pull + reindex-sprites + resolve snippet
+assets add "mana bar"                              # HUD component G�� the `npx shadcn add` cmd + <VitalBar/> usage
+assets add sword                                    # icon G�� the game-icon name to drop in a slot
 ```
 
 - A **model / pack** match is fully automated: if the pack isn't already in `<dir>/models/`, it's pulled and extracted, then `reindex` runs so the id is addressable, then the `buildCatalog` + model-seam snippet is printed.
-- A **component / icon** match prints the one-liner to run and the import + usage — no bytes to pull.
-- Ambiguous query? `add` lists the top matches across kinds; narrow with `--kind model|pack|component|icon` or a more specific term. `--json` emits the ranked matches for scripting.
+- A **material** match pulls the maps into `<dir>/materials/<id>/` with normalized names (`color.jpg`, `normal.jpg`, `roughness.jpg`, `ao.jpg`, `displacement.jpg`) and prints the `buildMaterialCatalog` resolve snippet G�� no reindex needed, the material catalog is fully static.
+- A **sprite / spritePack** match works like model/pack: if the pack isn't already in `<dir>/sprites/`, it's pulled and extracted, then `reindex-sprites` runs so individual SVG/PNG ids are addressable, then the `buildSpriteCatalog` snippet is printed.
+- A **component / icon** match prints the one-liner to run and the import + usage G�� no bytes to pull.
+- Ambiguous query? `add` lists the top matches across kinds; narrow with `--kind model|pack|material|component|icon|sprite|spritePack` or a more specific term. `--json` emits the ranked matches for scripting.
 
 The same ranking is available programmatically: `import { findAssets } from "@jgengine/assets"`.
 
@@ -39,98 +47,143 @@ The same ranking is available programmatically: `import { findAssets } from "@jg
 
 ```
 assets add <query> [--kind <k>] [--dir <dir>] [--mirror <baseUrl>] [--json]
-                                               # unified import: models, packs, components, icons
-assets list [--category <c>] [--source <s>]   # browse the generated index
-assets search <term>                          # grep the index
+                                               # unified import: models, packs, materials, sprites, components, icons
+assets list [--category <c>] [--source <s>] [--kind material|sprite|spritePack]
+                                               # browse the generated model/sprite index, or the material/sprite-pack catalog
+assets search <term>                          # grep the model index
 assets pull <source-id> [--dir public] [--mirror <baseUrl>] [--offline]
-                                               # download + extract a whole pack's GLBs into <dir>/models/<source>/
+                                               # download + extract a pack into <dir>/models|materials|sprites/<source>/
 assets register <path|url> --category <c> --license <l> [--author <a>]
                                                # register a one-off single into the shipped index
-assets reindex [public/models]                # regenerate generated/*.json from pulled packs
+assets reindex [public/models]                # regenerate generated/*.json from pulled model packs
+assets reindex-sprites [public/sprites]       # regenerate generated-sprites/*.json from pulled sprite packs
 assets verify                                 # license + alias-integrity gate
+assets provenance <id> [<id>...]              # resolve each id's owner (committed/provisioned/dangling); non-zero on any dangling
 ```
 
-Run in-repo with `bun run --cwd packages/assets src/cli/pull.ts <verb> …`. (`add <path|url> --license …` still works as an alias for `register`.)
+### Reference integrity
+
+Every logical asset id resolves to a declared **owner** through the provisioning contract (`resolveProvenance`): `committed` (a single's shipped URL — resolves on a clean clone with no pull), `provisioned` (a pack index entry whose GLB `assets pull <source>` fetches into the served dir), or `dangling` (nothing owns it, so it can never resolve). `validateAssetReferences(refs)` turns a set of `{ consumer, id }` references into a clean-clone gate: it fails on any dangling reference — naming the consumer, the logical id, and the null resolved path — and returns the exact `assets pull <source>` steps the checkout still needs so provisioning stays deterministic and `ensure-ready`-driven. It resolves references structurally against the catalog rather than grepping source text.
+
+At runtime the shell validates a model fetch *before* parsing (`classifyAssetResponse` in `@jgengine/core/scene/assetDiagnostics`): it checks HTTP status, content type, and the GLB/glTF signature, then reports `missing`, `html` (a dev-server fallback page served in place of the file), `corrupt`, or `unsupported` with the URL — replacing the opaque `Unexpected token <` GLTF parse error the old path produced when a model was absent.
+
+Run in-repo with `bun run --cwd packages/assets src/cli/pull.ts <verb> GǪ`. (`add <path|url> --license GǪ` still works as an alias for `register`.)
 
 ### Mirror fallback and offline pulls
 
 `pull` never has just one path to the bytes. For a given `source-id` it tries, in order, until one succeeds:
 
-1. **Mirror base override** — `--mirror <baseUrl>` (or the `JGENGINE_ASSETS_MIRROR` env var if `--mirror` is not passed) — the archive is expected at `<baseUrl>/<provider>/<source-id>.zip`, e.g. `https://my-mirror.example.com/kenney/kenney-nature.zip`.
-2. **The default GitHub-release mirror** — `https://github.com/Noisemaker111/jgengine/releases/download/packs/<provider>-<source-id>.zip`, on this repo's own rolling `packs` release (no separate assets repo). github.com is reachable from every cloud sandbox with no network-policy change, so zero-setup sessions still pull. `.github/workflows/mirror-assets.yml` (weekly cron + manual dispatch) keeps the release in sync with `src/sources/*.ts` automatically — adding a catalog entry is the whole publishing step, no manual upload. Skip this hop with `JGENGINE_ASSETS_NO_DEFAULT_MIRROR=1`.
-3. **The primary provider path** — the source's pinned `{ url, sha256? }` or, for providers that rotate URLs (Kenney), a scrape of the asset page.
-4. **The pack's own `mirror`** — an optional direct archive URL set on the `AssetSource` entry itself (`src/sources/*.ts`), tried as a last resort.
+1. **Mirror base override** G�� `--mirror <baseUrl>` (or the `JGENGINE_ASSETS_MIRROR` env var if `--mirror` is not passed) G�� the archive is expected at `<baseUrl>/<provider>/<source-id>.zip`, e.g. `https://my-mirror.example.com/quaternius/quaternius-stylized-nature.zip`.
+2. **The default GitHub-release mirror** G�� `https://github.com/Noisemaker111/jgengine/releases/download/packs/<provider>-<source-id>.zip`, on this repo's own rolling `packs` release (no separate assets repo). github.com is reachable from every cloud sandbox with no network-policy change, so zero-setup sessions still pull. `.github/workflows/mirror-assets.yml` (weekly cron + manual dispatch) keeps the release in sync with `src/sources/*.ts` automatically G�� adding a catalog entry is the whole publishing step, no manual upload. Skip this hop with `JGENGINE_ASSETS_NO_DEFAULT_MIRROR=1`. Model/sprite pack failures fail the job; individual ambientCG material 404s are soft (logged, non-fatal).
+3. **The primary provider path** G�� pinned `{ url, sha256? }` when stable: **KayKit** G�� `github.com/KayKit-Game-Assets/*/archive/GǪ/main.zip`; **Quaternius** free Standard packs G�� OpenGameArt direct zips (site pages JS-gate). Else scrape. `extractGlbs` packs co-located `.gltf`+`.bin` into `.glb`, flattens external image URIs to basenames, and returns each referenced texture so `pull` writes it beside the models — a pulled pack renders textured out of the box.
+4. **The pack's own `mirror`** G�� an optional direct archive URL set on the `AssetSource` entry itself (`src/sources/*.ts`), tried as a last resort.
 
-If every attempt fails, `pull` throws one aggregated error naming every URL it tried and why each one failed. Whenever the source's `download` is pinned with a `sha256`, the downloaded bytes are hashed and checked against it **no matter which path supplied them** — a mirror serving stale or tampered bytes is rejected and the next source in the chain is tried instead.
+If every attempt fails, `pull` throws one aggregated error naming every URL it tried and why each one failed. Whenever the source's `download` is pinned with a `sha256`, the downloaded bytes are hashed and checked against it **no matter which path supplied them** G�� a mirror serving stale or tampered bytes is rejected and the next source in the chain is tried instead.
 
-`--offline` skips the network entirely: it succeeds immediately if `<dir>/models/<source-id>/` already has files in it, and otherwise fails fast with a message telling you to pull once on a connected machine or point `--mirror`/`JGENGINE_ASSETS_MIRROR` at a reachable archive — useful for CI scripts that should error in seconds instead of hanging on a blocked fetch.
+`--offline` skips the network entirely: it succeeds immediately if `<dir>/models/<source-id>/` already has files in it, and otherwise fails fast with a message telling you to pull once on a connected machine or point `--mirror`/`JGENGINE_ASSETS_MIRROR` at a reachable archive G�� useful for CI scripts that should error in seconds instead of hanging on a blocked fetch.
 
-**Network-restricted environments** — a `403` on `CONNECT` from an outbound proxy means the environment's network policy blocks that provider host (common in sandboxed cloud sessions); it is a policy decision, not a transient failure, so retrying never helps. Either allowlist the host in the environment settings, or pull once on a machine that can reach the providers, then:
+**Network-restricted environments** G�� a `403` on `CONNECT` from an outbound proxy means the environment's network policy blocks that provider host (common in sandboxed cloud sessions); it is a policy decision, not a transient failure, so retrying never helps. Either allowlist the host in the environment settings, or pull once on a machine that can reach the providers, then:
 
 - commit (or otherwise host) the resulting `public/models/<source-id>/` directory so restricted environments read it straight off disk and use `assets pull --offline` as a fast, honest no-op check, or
 - host your own mirror of the zip archives at `<baseUrl>/<provider>/<source-id>.zip` and set `JGENGINE_ASSETS_MIRROR=<baseUrl>` (or pass `--mirror <baseUrl>`) so `pull` fetches from it instead of the original provider.
 
 ## Adding assets
 
-**A whole new pack** — add one entry to the matching `src/sources/*.ts` (this is the layer contributors PR). No filenames are hand-typed; `reindex` reads the real `.glb` names out of the extracted pack, so entries can't silently 404.
+**A whole new pack** G�� add one entry to the matching `src/sources/*.ts` (this is the layer contributors PR). No filenames are hand-typed; `reindex` reads the real `.glb` names out of the extracted pack, so entries can't silently 404.
 
 ```ts
-// src/sources/kenney.ts → KENNEY_PACKS
-{ id: "kenney-food", slug: "food-kit", title: "Food Kit", categories: ["food", "prop"] },
+// src/sources/quaternius.ts G�� QUATERNIUS_PACKS
+{ id: "quaternius-fantasy-props", slug: "fantasypropsmegakit", title: "Fantasy Props MegaKit", categories: ["fantasy", "prop"] },
 ```
 
 ```bash
-bun src/cli/pull.ts pull kenney-food --dir ../../apps/dev/public   # fetch + extract GLBs
-bun src/cli/pull.ts reindex ../../apps/dev/public/models           # regenerate generated/*.json + barrel
-bun src/cli/pull.ts verify                                         # license + alias gate
+bun src/cli/pull.ts pull quaternius-fantasy-props --dir ../../apps/dev/public   # fetch + extract GLBs
+bun src/cli/pull.ts reindex ../../apps/dev/public/models                        # regenerate generated/*.json + barrel
+bun src/cli/pull.ts verify                                                      # license + alias gate
 ```
 
-A **new provider** is just a new `src/sources/<provider>.ts` added to the `sources` array in `src/sources/index.ts`. Pinned providers use `download: { url, sha256? }`; providers that rotate URLs (Kenney) use `download: { scrape: <page> }`. Any entry can also carry an optional top-level `mirror: <archiveUrl>` — a direct URL `pull` falls back to if both a `--mirror`/`JGENGINE_ASSETS_MIRROR` override and the primary path fail (see "Mirror fallback and offline pulls" above).
+A **new provider** is just a new `src/sources/<provider>.ts` added to the `sources` array in `src/sources/index.ts`. Pinned providers use `download: { url, sha256? }`; providers whose pages JS-gate the download and can't be pinned use `download: { scrape: <page> }`. Any entry can also carry an optional top-level `mirror: <archiveUrl>` G�� a direct URL `pull` falls back to if both a `--mirror`/`JGENGINE_ASSETS_MIRROR` override and the primary path fail (see "Mirror fallback and offline pulls" above). Kenney.nl is not an eligible provider for this repo G�� see CLAUDE.md "Never Kenney".
+
+**A whole new sprite/icon pack** G�� same shape as a model pack, just `kind: "sprite"` and `reindex-sprites` instead of `reindex`; files are matched by `.svg`/`.png` extension, deduped by basename regardless of archive nesting, so no filenames are hand-typed here either. `src/sources/gameicons.ts` is the current example (`gameicons-icons`); a new sprite provider follows the same shape in its own `src/sources/<provider>.ts`.
+
+```bash
+bun src/cli/pull.ts pull gameicons-icons --dir ../../apps/dev/public        # fetch + extract SVG/PNG
+bun src/cli/pull.ts reindex-sprites ../../apps/dev/public/sprites           # regenerate generated-sprites/*.json + barrel
+```
 
-**A single one-off** — no code edit, zero bytes stored (URL) or copied into `local/` (path):
+**A single one-off** G�� no code edit, zero bytes stored (URL) or copied into `local/` (path):
 
 ```bash
-assets add "https://poly.pizza/…/model.glb" --category prop --license CC0-1.0 --author "Some Author"
+assets add "https://poly.pizza/GǪ/model.glb" --category prop --license CC0-1.0 --author "Some Author"
 ```
 
 ## Importing in code
 
-Build the catalog once, then address ids (or aliases) — resolve returns `{ url }`:
+Build the catalog once, then address ids (or aliases) G�� resolve returns `{ url }`:
 
 ```ts
 import { buildCatalog } from "@jgengine/assets";
 
 const catalog = buildCatalog({ basePath: "/models" });
 
-catalog.resolve("kenney-nature/tree_pineDefaultA"); // { url: "/models/kenney-nature/tree_pineDefaultA.glb" }
-catalog.resolve("nature/tree_pine");                // alias → same url
+catalog.resolve("quaternius-stylized-nature/Pine_1"); // { url: "/models/quaternius-stylized-nature/Pine_1.glb" }
+catalog.resolve("nature/tree_pine");                   // alias G�� same url
 
 // wire ids straight into a game's model seams:
 export const game: PlayableGame = {
-  // …
+  // GǪ
   objectModels: {
-    "kenney-nature/tree_pineDefaultA": { url: catalog.resolve("kenney-nature/tree_pineDefaultA")!.url, scale: 1.4 },
+    "quaternius-stylized-nature/Pine_1": { url: catalog.resolve("quaternius-stylized-nature/Pine_1")!.url, scale: 1.4 },
   },
   entityModels: {
-    hero: { url: catalog.resolve("kenney-space/astronautA")!.url, scale: 1.1 },
+    hero: { url: catalog.resolve("kaykit-adventurers/Barbarian")!.url, scale: 1.1 },
   },
 };
 ```
 
-`buildCatalog({ sources: ["kenney-nature"] })` restricts to chosen packs; `includeAliases` / `includeSingles` default true. Discover ids with `assets add <query>` (or `assets search <term>` / `assets list --category <c>`) instead of memorizing them.
+`buildCatalog({ sources: ["quaternius-stylized-nature"] })` restricts to chosen packs; `includeAliases` / `includeSingles` default true. Discover ids with `assets add <query>` (or `assets search <term>` / `assets list --category <c>`) instead of memorizing them.
+
+Materials resolve the same way G�� ids (or `material/GǪ` aliases) to normalized PBR map URLs:
+
+```ts
+import { buildMaterialCatalog } from "@jgengine/assets";
+
+const materials = buildMaterialCatalog({ basePath: "/materials" });
+
+materials.resolve("ambientcg-grass001")!.maps.color; // "/materials/ambientcg-grass001/color.jpg"
+materials.resolve("material/grass")!.maps.normal;    // alias G�� "/materials/ambientcg-grass001/normal.jpg"
+```
+
+Sprite/icon packs resolve the same way once pulled + reindexed G�� individual files, not whole packs:
+
+```ts
+import { buildSpriteCatalog } from "@jgengine/assets";
+
+const sprites = buildSpriteCatalog({ basePath: "/sprites" });
+
+sprites.resolve("gameicons-icons/sword")!.url; // "/sprites/gameicons-icons/sword.svg"
+```
 
 ### Serving the bytes
 
-A resolved id only yields a **URL** — the GLB must be somewhere your app serves. For a game, `pull` the packs into your app's `public/`, and line `basePath` up with it:
+A resolved id only yields a **URL** G�� the GLB must be somewhere your app serves. For a game, `pull` the packs into your app's `public/`, and line `basePath` up with it:
 
 ```bash
-bun src/cli/pull.ts pull kenney-nature --dir ../../apps/dev/public   # → apps/dev/public/models/kenney-nature/*.glb
+bun src/cli/pull.ts pull quaternius-stylized-nature --dir ../../apps/dev/public   # G�� apps/dev/public/models/quaternius-stylized-nature/*.glb
 ```
 
-`buildCatalog({ basePath: "/models" })` then resolves to `/models/kenney-nature/…`, which the dev server serves from `public/models/` (gitignored — the bytes are the consumer's, fetched once from the provider's CDN).
+`buildCatalog({ basePath: "/models" })` then resolves to `/models/quaternius-stylized-nature/GǪ`, which the dev server serves from `public/models/` (gitignored G�� the bytes are the consumer's, fetched once from the provider's CDN).
+
+Sprite/icon packs pull the same way, into `public/sprites/`:
+
+```bash
+bun src/cli/pull.ts pull gameicons-icons --dir ../../apps/dev/public        # G�� apps/dev/public/sprites/gameicons-icons/*.svg
+bun src/cli/pull.ts reindex-sprites ../../apps/dev/public/sprites           # G�� src/generated-sprites/gameicons-icons.json
+```
 
 ## Notes
 
-- Kenney rotates download URLs, so its sources `scrape` the asset page at pull time.
-- Quaternius / KayKit pages gate downloads behind JS; automated `pull` falls back to a clear error when no archive link is found — download those manually into the staging dir, then `reindex`.
+- Quaternius / KayKit pages gate downloads behind JS; sources without a pinned OpenGameArt/GitHub zip `scrape` the pack page as a fallback, and automated `pull` falls back to a clear error when no archive link is found G�� download those manually into the staging dir, then `reindex`.
 - `pull`'s mirror fallback and `--offline` guard exist for network-restricted environments (CI, sandboxes without provider access); see "Mirror fallback and offline pulls" above.
+- `gameicons-icons` is **CC BY 3.0**, not CC0 G�� a game using it needs one credit line (source, "game-icons.net contributors", license) per the engine's asset-credit rule; the repo's own per-author `license.txt` files carry the individual credits behind this pack's single collective `author` field.
+- `src/generated-sprites/` starts empty for a brand-new sprite source G�� same as any brand-new model pack, the committed per-file index only exists after someone runs `pull` + `reindex-sprites` with real network access; until then the source is fully declared (and the weekly mirror job will fetch it) but has no individually-addressable ids yet.

package/dist/aliases.d.ts

@@ -1,2 +1,7 @@
 import type { AssetAlias } from "./manifest.js";
+/**
+ * Semantic keys → live catalog ids. Prefer these in games so re-homes only
+ * touch this table. Never point at kenney-*. Curated starter theme ids
+ * (`asset:person_casual`, `nature_tree`, …) come from {@link starterAliases}.
+ */
 export declare const aliases: readonly AssetAlias[];

package/dist/aliases.js

@@ -1,11 +1,30 @@
+import { starterAliases } from "./packs/starter.js";
+/**
+ * Semantic keys → live catalog ids. Prefer these in games so re-homes only
+ * touch this table. Never point at kenney-*. Curated starter theme ids
+ * (`asset:person_casual`, `nature_tree`, …) come from {@link starterAliases}.
+ */
 export const aliases = [
-    { key: "nature/tree_pine", target: "kenney-nature/tree_pineDefaultA" },
-    { key: "nature/tree", target: "kenney-nature/tree_blocks" },
-    { key: "nature/rock", target: "kenney-nature/cliff_block_rock" },
-    { key: "nature/mushroom", target: "kenney-nature/mushroom_red" },
-    { key: "nature/flower", target: "kenney-nature/flower_purpleA" },
-    { key: "weapon/blaster", target: "kenney-blaster/blaster-a" },
-    { key: "space/astronaut", target: "kenney-space/astronautA" },
-    { key: "space/ship", target: "kenney-space/craft_racer" },
-    { key: "space/rocket", target: "kenney-space/rocket_baseA" },
+    { key: "nature/tree_pine", target: "quaternius-stylized-nature/Pine_1" },
+    { key: "nature/tree_common", target: "quaternius-stylized-nature/CommonTree_1" },
+    { key: "nature/tree_dead", target: "quaternius-stylized-nature/DeadTree_1" },
+    { key: "nature/bush", target: "quaternius-stylized-nature/Bush_Common" },
+    { key: "nature/rock", target: "quaternius-stylized-nature/Rock_Medium_1" },
+    { key: "character/rogue", target: "kaykit-adventurers/Rogue" },
+    { key: "character/knight", target: "kaykit-adventurers/Knight" },
+    { key: "character/mage", target: "kaykit-adventurers/Mage" },
+    { key: "character/barbarian", target: "kaykit-adventurers/Barbarian" },
+    { key: "scifi/alien", target: "quaternius-modular-scifi/Alien_Cyclop" },
+    { key: "scifi/chest", target: "quaternius-modular-scifi/Prop_Chest" },
+    { key: "scifi/crate", target: "quaternius-modular-scifi/Prop_Crate3" },
+    { key: "scifi/computer", target: "quaternius-modular-scifi/Prop_Computer" },
+    { key: "dungeon/chest", target: "kaykit-dungeon/chest" },
+    { key: "furniture/bed", target: "kaykit-furniture/bed_double_A" },
+    { key: "furniture/couch", target: "kaykit-furniture/couch" },
+    { key: "furniture/table", target: "kaykit-furniture/table_medium" },
+    { key: "city/car_sedan", target: "kaykit-city-builder/car_sedan" },
+    { key: "city/car_police", target: "kaykit-city-builder/car_police" },
+    { key: "city/building_a", target: "kaykit-city-builder/building_A" },
+    { key: "city/streetlight", target: "kaykit-city-builder/streetlight" },
+    ...starterAliases(),
 ];

package/dist/catalogs/build.d.ts

@@ -1,5 +1,20 @@
 import { type AssetCatalog } from "@jgengine/core/scene/assetCatalog";
 import type { IndexEntry } from "../manifest.js";
+/**
+ * A durable, hand-or-tool authored catalog entry that is not part of the generated pack index,
+ * singles, or aliases — the shape the editor writes into a promoted game's `src/game/assets.ts`
+ * when an asset is imported. `label` is human-facing only and is intentionally not registered
+ * into the catalog (it mirrors how a single asset's author/license live only in the source
+ * literal), so at runtime an extra resolves to exactly `{ url }`.
+ */
+export interface CatalogExtra {
+    /** Catalog id the entry resolves under (matches what a folder rescan would produce). */
+    id: string;
+    /** URL the shipped game serves the model from (e.g. `/models/imported/Ship.glb`). */
+    url: string;
+    /** Human-facing label kept only in the source literal; never registered into the catalog. */
+    label?: string;
+}
 export interface BuildCatalogOptions {
     /** URL prefix where pulled pack GLBs live (consumer's `public/models`). */
     basePath?: string;
@@ -7,6 +22,18 @@ export interface BuildCatalogOptions {
     sources?: readonly string[];
     includeAliases?: boolean;
     includeSingles?: boolean;
+    /**
+     * Extra catalog entries registered after packs/singles and before aliases: imported assets the
+     * editor persists into a promoted game's typed catalog. Registered last-writer-wins after packs
+     * (so an extra can override a pack id) but before aliases (so an alias can target an extra).
+     */
+    extras?: readonly CatalogExtra[];
 }
 export declare function entryUrl(basePath: string, entry: IndexEntry): string;
+/**
+ * Builds a game's asset catalog from the generated CC0 pack index plus singles, extras, and aliases.
+ * Registration order is packs → singles → {@link BuildCatalogOptions.extras | extras} → aliases:
+ * packs and singles come first, extras override them last-writer-wins, and aliases resolve last so
+ * they can target an extra. See {@link BuildCatalogOptions} for filtering and opt-outs.
+ */
 export declare function buildCatalog(options?: BuildCatalogOptions): AssetCatalog;

package/dist/catalogs/build.js

@@ -2,32 +2,58 @@ import { createAssetCatalog } from "@jgengine/core/scene/assetCatalog";
 import { aliases } from "../aliases.js";
 import { generatedIndex } from "../generated/index.js";
 import { singles } from "../singles.js";
+import { sources as declaredSources } from "../sources/index.js";
 export function entryUrl(basePath, entry) {
     return `${basePath.replace(/\/+$/, "")}/${entry.source}/${entry.file}`;
 }
+/**
+ * Builds a game's asset catalog from the generated CC0 pack index plus singles, extras, and aliases.
+ * Registration order is packs → singles → {@link BuildCatalogOptions.extras | extras} → aliases:
+ * packs and singles come first, extras override them last-writer-wins, and aliases resolve last so
+ * they can target an extra. See {@link BuildCatalogOptions} for filtering and opt-outs.
+ */
 export function buildCatalog(options = {}) {
     const basePath = options.basePath ?? "/models";
     const includeAliases = options.includeAliases ?? true;
     const includeSingles = options.includeSingles ?? true;
     const sourceFilter = options.sources === undefined ? null : new Set(options.sources);
+    if (sourceFilter !== null) {
+        const knownSourceIds = new Set(declaredSources.map((source) => source.id));
+        for (const id of sourceFilter) {
+            if (!knownSourceIds.has(id)) {
+                throw new Error(`buildCatalog: unknown source id "${id}" — not declared in packages/assets/src/sources/*.ts`);
+            }
+        }
+    }
     const catalog = createAssetCatalog();
     for (const entry of generatedIndex) {
         if (sourceFilter !== null && !sourceFilter.has(entry.source))
             continue;
         const url = entryUrl(basePath, entry);
-        catalog.register(entry.id, entry.dims === undefined ? { url } : { url, dims: entry.dims });
+        catalog.register(entry.id, {
+            url,
+            ...(entry.dims === undefined ? {} : { dims: entry.dims }),
+            ...(entry.collisionMesh === undefined ? {} : { collisionMesh: entry.collisionMesh }),
+        });
     }
     if (includeSingles) {
         for (const single of singles) {
             catalog.register(single.id, { url: single.url });
         }
     }
+    for (const extra of options.extras ?? []) {
+        catalog.register(extra.id, { url: extra.url });
+    }
     if (includeAliases) {
         for (const alias of aliases) {
             const ref = catalog.resolve(alias.target);
             if (ref === null)
                 continue;
-            catalog.register(alias.key, ref.dims === undefined ? { url: ref.url } : { url: ref.url, dims: ref.dims });
+            catalog.register(alias.key, {
+                url: ref.url,
+                ...(ref.dims === undefined ? {} : { dims: ref.dims }),
+                ...(ref.collisionMesh === undefined ? {} : { collisionMesh: ref.collisionMesh }),
+            });
         }
     }
     return catalog;

package/dist/catalogs/buildSprites.d.ts

@@ -0,0 +1,10 @@
+import { type AssetCatalog } from "@jgengine/core/scene/assetCatalog";
+/** Options for `buildSpriteCatalog`. */
+export interface BuildSpriteCatalogOptions {
+    /** URL prefix where pulled sprite/icon files live (consumer's `public/sprites`). */
+    basePath?: string;
+    /** Restrict to these source ids; omit for all. */
+    sources?: readonly string[];
+}
+/** Resolves individual pulled sprite/icon ids (e.g. `gameicons-icons/sword`) to `{ url }`. */
+export declare function buildSpriteCatalog(options?: BuildSpriteCatalogOptions): AssetCatalog;

package/dist/catalogs/buildSprites.js

@@ -0,0 +1,15 @@
+import { createAssetCatalog } from "@jgengine/core/scene/assetCatalog";
+import { generatedSpriteIndex } from "../generated-sprites/index.js";
+import { entryUrl } from "./build.js";
+/** Resolves individual pulled sprite/icon ids (e.g. `gameicons-icons/sword`) to `{ url }`. */
+export function buildSpriteCatalog(options = {}) {
+    const basePath = options.basePath ?? "/sprites";
+    const sourceFilter = options.sources === undefined ? null : new Set(options.sources);
+    const catalog = createAssetCatalog();
+    for (const entry of generatedSpriteIndex) {
+        if (sourceFilter !== null && !sourceFilter.has(entry.source))
+            continue;
+        catalog.register(entry.id, { url: entryUrl(basePath, entry) });
+    }
+    return catalog;
+}

package/dist/catalogs/starter.d.ts

@@ -1,2 +1,7 @@
 import { type BuildCatalogOptions } from "./build.js";
+/**
+ * Catalog restricted to the curated starter packs (people/props/nature/urban).
+ * Prefer this for scaffolds and probes so `asset:person_casual` etc. resolve
+ * without pulling the whole library. Full index: {@link buildCatalog}.
+ */
 export declare function createStarterCatalog(options?: BuildCatalogOptions): import("@jgengine/core/scene/assetCatalog").AssetCatalog<import("@jgengine/core/scene/assetCatalog").ModelAssetRef>;

package/dist/catalogs/starter.js

@@ -1,4 +1,13 @@
+import { STARTER_SOURCE_PACKS } from "../packs/starter.js";
 import { buildCatalog } from "./build.js";
+/**
+ * Catalog restricted to the curated starter packs (people/props/nature/urban).
+ * Prefer this for scaffolds and probes so `asset:person_casual` etc. resolve
+ * without pulling the whole library. Full index: {@link buildCatalog}.
+ */
 export function createStarterCatalog(options = {}) {
-    return buildCatalog(options);
+    return buildCatalog({
+        ...options,
+        sources: options.sources ?? STARTER_SOURCE_PACKS,
+    });
 }

package/dist/cli/paths.d.ts

@@ -1,4 +1,12 @@
-/** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import. */
+/** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import.
+ * @internal
+ */
 export declare function resolveGeneratedDir(cliDir: string): string;
+/** Sprite-pack counterpart of `resolveGeneratedDir` — a separate generated tree, same sibling layout.
+ * @internal
+ */
+export declare function resolveGeneratedSpritesDir(cliDir: string): string;
+/** @internal */
 export declare function resolvePackageTreeRoot(cliDir: string): string;
+/** @internal */
 export declare function resolvePackageRoot(cliDir: string): string;

package/dist/cli/paths.js

@@ -1,11 +1,21 @@
 import { join, resolve } from "node:path";
-/** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import. */
+/** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import.
+ * @internal
+ */
 export function resolveGeneratedDir(cliDir) {
     return join(resolve(cliDir, ".."), "generated");
 }
+/** Sprite-pack counterpart of `resolveGeneratedDir` — a separate generated tree, same sibling layout.
+ * @internal
+ */
+export function resolveGeneratedSpritesDir(cliDir) {
+    return join(resolve(cliDir, ".."), "generated-sprites");
+}
+/** @internal */
 export function resolvePackageTreeRoot(cliDir) {
     return resolve(cliDir, "..");
 }
+/** @internal */
 export function resolvePackageRoot(cliDir) {
     return resolve(cliDir, "..", "..");
 }

package/dist/cli/pull.d.ts

@@ -1,8 +1,20 @@
 #!/usr/bin/env node
 /** Sibling of `cli/` under `src/` (dev) or `dist/` (published) so reindex writes the tree consumers import. */
 export declare const generatedDir: string;
+/** Sprite-pack counterpart of `generatedDir`. */
+export declare const generatedSpritesDir: string;
 export { resolveGeneratedDir } from "./paths.js";
+/** @internal */
 export declare function flag(argv: string[], name: string): string | undefined;
+/**
+ * The runtime's own fetch, with a curl fallback for hosts it cannot reach —
+ * some proxied sandboxes tear down bun's TLS stream to GitHub's release-asset
+ * host while curl (which honors SSL_CERT_FILE) gets through fine.
+ */
+export declare const cliFetch: typeof fetch;
+/** @internal */
 export declare function describeNetworkFailure(error: unknown): string;
+/** @internal */
 export declare function isPopulated(dir: string): boolean;
+/** @internal */
 export declare function cmdPull(argv: string[]): Promise<void>;