@jgengine/assets 0.13.0 → 0.15.0-next.0

package/skills/jgengine/capabilities.md

@@ -16,6 +16,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `GameContextModels` (interface) · `import { GameContextModels } from "@jgengine/core/runtime/gameContext"`
 
+## default-walk-codes — stock WASD + jump key codes for the shell walk controller
+
+- `DEFAULT_WALK_CODES` (const) · `import { DEFAULT_WALK_CODES } from "@jgengine/shell/gameKit"`
+
 ## define-game — single public game-authoring path — compose systems, world, presentation, and authored scene in one definition
 
 - `defineGame` (function) · `import { defineGame } from "@jgengine/shell/gameKit"`
@@ -32,6 +36,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `SystemDefinition` (interface) · `import { SystemDefinition } from "@jgengine/shell/gameKit"`
 
+## grounded — ground an XZ point onto the world surface as a pose triple
+
+- `grounded` (function) · `import { grounded } from "@jgengine/shell/gameKit"`
+
 ## headless-runner — play a real game loop with no renderer — tick, feed input, read the world snapshot
 
 - `HeadlessRunner` (interface) · `import { HeadlessRunner } from "@jgengine/core/runtime/headlessRunner"`
@@ -95,8 +103,12 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 ## render-fallback-diagnostics — Enable/disable the dev-only placeholder-fallback probe.
 
 - `armFallbackSeams` (function) · `import { armFallbackSeams } from "@jgengine/core/devtools/fallbackSeams"`
+- `armTextureErrors` (function) · `import { armTextureErrors } from "@jgengine/core/devtools/textureErrors"`
 - `fallbackSeamsSnapshot` (function) · `import { fallbackSeamsSnapshot } from "@jgengine/core/devtools/fallbackSeams"`
 - `reportFallbackSeam` (function) · `import { reportFallbackSeam } from "@jgengine/core/devtools/fallbackSeams"`
+- `reportTextureLoadError` (function) · `import { reportTextureLoadError } from "@jgengine/core/devtools/textureErrors"`
+- `resetTextureErrors` (function) · `import { resetTextureErrors } from "@jgengine/core/devtools/textureErrors"`
+- `textureErrorsSnapshot` (function) · `import { textureErrorsSnapshot } from "@jgengine/core/devtools/textureErrors"`
 
 ## runtime-save — save/load the whole game world through a pluggable backend, autosave or save points
 

package/skills/jgengine/recipes/minimal-game.md

@@ -72,10 +72,13 @@ export function onNewPlayer(ctx: GameContext): void {
 ```
 
 `GameUI` starts as an empty `HudCanvas` (`useHudLayout` + `HudCanvas` from the kit). That is
-intentional: **every game owns its UI**. Write a short UI art direction, then build custom
-panels for this pitch — do not ship stock drop-in widgets (`StatBar`, `Hotbar`, `Coins`, glass
-frames) as the product face. Reach for engine pieces only as headless data, layout, or
-interaction models under game-owned chrome (see `jgengine-ui`).
+intentional: **every game owns its UI composition** — layout, terminology, placement, and art
+direction. Compose the shipped building blocks the moment you need them (`StatBar`, `Hotbar`,
+`Coins`, `InventoryGrid`, `CharacterSheet`, window shells from `jgengine-ui`), then reskin via
+`HudTheme` tokens. Reaching for those is using the engine correctly, not incomplete work. What
+the engine does not ship is a whole finished game *face* or genre theme preset — do not leave an
+unarranged, unskinned generic dashboard as the product. Hand-roll markup only where no building
+block fits (see `jgengine-ui`).
 
 ## 3. Author, play, win
 

package/skills/jgengine-assets/SKILL.md

@@ -9,7 +9,7 @@ description: Source, license, catalog, and resolve game-ready media assets.
 
 This skill owns model, sprite, texture/material, and audio-file discovery; licensing; catalog metadata; pull/index workflows; and runtime asset references. Placement belongs to `jgengine-editor`, spatial audio behavior to `jgengine-world`, and rendering/UI composition to their respective domains.
 
-Search [capabilities.md](capabilities.md) before adding a resolver or catalog path. Use [api.md](api.md) for exact exports.
+Search [capabilities.md](capabilities.md) before adding a resolver or catalog path. Use [api.md](api.md) for exact exports. Turning a real item or scene into an asset via video capture and 3D reconstruction is a sourcing method under this skill — see [references/video-to-3d-capture.md](references/video-to-3d-capture.md) for the offline pipeline, hardware/cost notes, and import steps.
 
 ## Canonical workflow
 

package/skills/jgengine-assets/api.md

@@ -119,6 +119,16 @@
 
 - `COLLISION_MESH_ASSET_IDS` (const): const COLLISION_MESH_ASSET_IDS: ReadonlySet<string> — Catalog assets that ship a collision mesh in the generated index. Opt-in only: each entry adds ~10-30KB of quantized triangles to the index and a BVH raycast per query, so list only concave models whose fitted box lies (archways, rings, frames).
 
+## @jgengine/assets/credits
+
+- `CreditsGrouping` (type): type CreditsGrouping = "license" | "provider" — Grouping for {@link creditsForSources} — one section per license (default) or per provider.
+- `allAssetSources` (function): function allAssetSources(): readonly AssetSource[] — Every catalogued source, for a credits screen that lists the whole shipped catalog.
+- `creditsForAssetIds` (function): function creditsForAssetIds(ids: Iterable<string>, options: { title?: string; grouping?: CreditsGrouping; notice?: string } = {}): CreditsDocument — One call from the asset ids a game ships to a ready {@link CreditsDocument} — the credit obligation for borrowed assets, derived rather than hand-maintained.
+- `creditsForSourceIds` (function): function creditsForSourceIds(ids: Iterable<string>, options: { title?: string; grouping?: CreditsGrouping; notice?: string } = {}): CreditsDocument — One call from the source ids a game declares to a ready {@link CreditsDocument} — the usual entry point, since `buildCatalog({ sources })` already names them.
+- `creditsForSources` (function): function creditsForSources(used: readonly AssetSource[], grouping: CreditsGrouping = "license"): CreditsSection[] — Turns asset sources into credit sections, one per license or provider, each entry naming the pack and its author with the pack homepage as `href`. Feed it {@link sourcesForAssetIds} so the screen credits what shipped, and fold the result into the game's hand-authored credits with `mergeCredits`.
+- `sourcesForAssetIds` (function): function sourcesForAssetIds(ids: Iterable<string>): AssetSource[] — The distinct asset sources behind a set of asset ids — the packs a game actually ships, not the whole catalog. Unknown ids are skipped; order follows first use so a stable id list gives a stable credits screen.
+- `sourcesForSourceIds` (function): function sourcesForSourceIds(ids: Iterable<string>): AssetSource[] — The distinct sources behind a set of source ids — the shape a game already declares to `buildCatalog({ sources })` / `buildMaterialCatalog`. Unknown ids are skipped.
+
 ## @jgengine/assets/dims
 
 - `ModelDims` (interface): interface ModelDims — Measured horizontal footprint, footprint center, and lowest Y of a model in model space.

package/skills/jgengine-assets/capabilities.md

@@ -12,6 +12,26 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `readGlbClips` (function) · `import { readGlbClips } from "@jgengine/assets/dims"`
 
+## credits-for-asset-ids — build a credits document from the asset ids a game ships
+
+- `creditsForAssetIds` (function) · `import { creditsForAssetIds } from "@jgengine/assets/credits"`
+
+## credits-for-source-ids — build a credits document from the asset source ids a game declares
+
+- `creditsForSourceIds` (function) · `import { creditsForSourceIds } from "@jgengine/assets/credits"`
+
+## credits-for-sources — generate credit sections from asset pack metadata, grouped by license or provider
+
+- `creditsForSources` (function) · `import { creditsForSources } from "@jgengine/assets/credits"`
+
+## sources-for-asset-ids — resolve the asset packs behind the ids a game actually ships
+
+- `sourcesForAssetIds` (function) · `import { sourcesForAssetIds } from "@jgengine/assets/credits"`
+
+## sources-for-source-ids — resolve the asset pack metadata behind the source ids a game declares
+
+- `sourcesForSourceIds` (function) · `import { sourcesForSourceIds } from "@jgengine/assets/credits"`
+
 ## starter-packs — themed CC0 model ids (people/props/nature/urban) ready for entityModels
 
 - `StarterTheme` (type) · `import { StarterTheme } from "@jgengine/assets"`

package/skills/jgengine-assets/references/video-to-3d-capture.md

@@ -0,0 +1,69 @@
+# Video-to-3D capture (photogrammetry-via-video)
+
+An offline path for turning a real item or location into a game-ready asset:
+film it, reconstruct it, mesh it, import it. This is a **capture/sourcing**
+recipe, not a runtime feature — nothing here runs inside the engine or a
+shipped game.
+
+Adapts the reconstruction step around
+[LingBot-Map](https://github.com/Robbyant/lingbot-map) (Apache-2.0) — see
+`CREDITS.md`.
+
+## Why offline
+
+LingBot-Map is a feed-forward 3D reconstruction model: PyTorch 2.8 + CUDA
+12.8, needs an NVIDIA GPU. It has no place running per-frame in a browser
+game or inside `@jgengine/shell`. Treat it as a one-shot batch job: video in,
+point cloud out, done — same category of tool as a photogrammetry rig, not a
+package dependency.
+
+## What it needs
+
+- NVIDIA GPU, CUDA 12.8, Python 3.10, PyTorch 2.8.0.
+- No hard VRAM floor is published, but the tool ships `--offload_to_cpu` and
+  a lower `--num_scale_frames` specifically for constrained cards — an
+  8–12GB consumer GPU (3060/3080) works chunked; a 16–24GB card (4090/A6000)
+  runs full-speed without offload.
+- No CPU-only mode.
+
+## Cost if you rent instead of own
+
+Spot GPU pricing (Vast.ai/RunPod-class) for a 4090 or A6000 runs roughly
+**$0.35–0.80/hr**. At ~20 FPS on 518×378, a short 10–30s item/scene capture
+reconstructs in well under a minute of GPU time — each asset costs pennies
+to about a quarter, plus a couple minutes of environment spin-up. Cheap
+enough to do per-asset, not something to batch-justify.
+
+## Pipeline
+
+1. **Capture** — film the item or scene as a short, steady walk-around or
+   pan (good, even lighting; avoid pure reflective/transparent surfaces —
+   they break most feed-forward reconstruction). 10–30s is plenty.
+2. **Reconstruct** (rented or owned GPU box, outside this repo) — run
+   LingBot-Map's streaming inference on the clip per its README. Output is a
+   point cloud plus per-frame NPZ/depth/trajectory data, not a mesh.
+3. **Mesh + clean** (local, no GPU needed) —
+   `scripts/asset-pipeline/pointcloud_to_glb.py` in this repo turns an
+   exported point cloud (`.ply`/`.npz`) into a Poisson-reconstructed mesh and
+   writes a `.glb`. Expect to hand-clean the result (decimate, fill holes,
+   fix scale/facing) in Blender before it's asset-grade — this step is a
+   starting point, not a finisher.
+4. **Import** — bring the cleaned `.glb` in through the editor's asset
+   import flow (`jgengine-editor`) into a promoted project's `extras` array
+   (`src/game/assets.ts`), same as any other authored asset. Record source
+   units, pivot, canonical facing, and footprint in the catalog metadata per
+   `jgengine-assets`' canonical workflow — do not hardcode the geometry or
+   skip cataloging because it was scanned rather than downloaded.
+5. **Credit** — LingBot-Map is Apache-2.0 (commercial use fine); keep the
+   `CREDITS.md` entry current and add the specific asset's provenance to its
+   catalog metadata.
+
+## Traps
+
+- Point clouds are not meshes and meshes are not game-ready — budget real
+  cleanup time at step 3, not just format conversion.
+- Scale and pivot come out of the reconstruction arbitrary; fix them once in
+  catalog metadata (per `jgengine-assets`' traps), never with a per-placement
+  corrective transform.
+- Reflective, transparent, or textureless surfaces reconstruct badly — pick
+  capture subjects accordingly, or expect heavy manual repair.