@jgengine/assets 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -15,6 +15,30 @@ the latest and surface the migration steps.
 
 _Nothing yet._
 
+## 0.6.0
+
+An additive release: **every 0.5.0 API is unchanged**, so upgrading is only a
+version bump. The headline is a whole outdoor-world layer — composable
+`environment(...)` descriptors, renderer-free query primitives so gameplay reads
+the same world the shell renders, a standalone rigid-body physics sim, and the
+`@jgengine/shell` renderers that draw it all.
+
+### Migrate
+
+- Bump every `@jgengine/*` dependency to `^0.6.0` (the eight packages version in lockstep).
+- No code change is required — 0.6.0 adds surface, it doesn't move or remove any.
+- Optional: describe an outdoor scene once with `environment({ terrain, weather, vegetation, water, structures })` from `@jgengine/core/world/features`. `@jgengine/shell`'s `EnvironmentScene` renders it (terrain, rain/snow, grass, ocean, buildings), and gameplay reads the same world through the renderer-free primitives — `resolveTerrainField(...)` for ground-snap/collision, `windField(...)` for sway/sailing, `waterSurface(...)` for buoyancy, `scatter(...)` for prop/spawn placement, `buildingIndex(...)` for placement avoidance — no three.js needed.
+
+### Added
+
+- `@jgengine/core/world` query primitives — pure, renderer-free world sampling so gameplay and rendering read one source of truth. `world/terrain` (`TerrainField`, `noiseField`, `resolveTerrainField`, `resolveGroundStep` for slope-limited movement), `world/wind` (`windField` — one wind source for weather sway, grass, sailing, fire spread), `world/water` (`waterSurface` / `waterSurfaceFromDescriptor` — CPU Gerstner matching the ocean shader, for buoyancy and shorelines), `world/scatter` (`scatter` — seeded, overlap-aware point distribution for vegetation/props/spawns), `world/buildings` (`generateBuilding`, `generateBuildingDistrict`) and `world/buildingIndex` (`buildingIndex` — `at`/`within`/`nearest`/`isInside`/`blockers` over a district).
+- `@jgengine/core/world/features` composable outdoor descriptors — `environment(...)` plus `terrain()`, `rain()`, `snow()`, `grass()`, `ocean()`, `building()`.
+- `@jgengine/core/world/regions` (`createRegionField` — blend content-agnostic biomes by nearest selector, adding `tint`/`water`/`fog`/`speedMultiplier`/opaque `data`; extends `TerrainField` so it ground-snaps too) and `@jgengine/core/world/scatterItems` (`scatterItems` — region-driven content scatter: density per region, grounded, above-water/slope-aware, with `pickWeighted` for weighted rolls).
+- `@jgengine/core/physics/physicsWorld` — standalone fixed-capacity rigid-body sim (SoA buffers, spatial-hash broadphase, sleeping) for many colliding dynamic bodies (piles, debris, stress scenes). Distinct from the `defineGame` `physics: { gravity }` character-controller config.
+- `ctx.time` simulation clock (`@jgengine/core/time/simClock`) — `onTick`'s `dt` is now **game time**, so `rate * dt` decay/regen/AI obeys pause and fast-forward for free without per-system wiring. Configure with `defineGame({ time: { scale?, speeds?, dayLength?, start?, startPaused? } })` (all optional; default is real-time 1:1). `ctx.time` exposes `pause`/`play`/`toggle`/`setSpeed`/`cycleSpeed` + `snapshot()`/`calendar()`; `useGameClock()` binds it in React.
+- `@jgengine/shell` environment/terrain/water/weather/structures renderers — `EnvironmentScene` mounts an `environment()` descriptor as R3F renderers; `GrassField`, `ProceduralGround`, `Ocean`, `RainField`, `SnowField`, `LightningStrike`, `GeneratedBuilding`, and `world/InstancedBodies` (renders `PhysicsWorld` bodies).
+- `@jgengine/react/liveBind` — `useFrameBind` drives a DOM/SVG element from a per-frame value without re-rendering React (HUDs bound to live engine state never re-render or lag).
+
 ## 0.5.0
 
 An additive release: **every 0.4.0 API is unchanged**, so upgrading is only a

package/dist/catalogs/build.js

@@ -11,26 +11,23 @@ export function buildCatalog(options = {}) {
     const includeSingles = options.includeSingles ?? true;
     const sourceFilter = options.sources === undefined ? null : new Set(options.sources);
     const catalog = createAssetCatalog();
-    const urlById = new Map();
     for (const entry of generatedIndex) {
         if (sourceFilter !== null && !sourceFilter.has(entry.source))
             continue;
         const url = entryUrl(basePath, entry);
-        urlById.set(entry.id, url);
-        catalog.register(entry.id, { url });
+        catalog.register(entry.id, entry.dims === undefined ? { url } : { url, dims: entry.dims });
     }
     if (includeSingles) {
         for (const single of singles) {
-            urlById.set(single.id, single.url);
             catalog.register(single.id, { url: single.url });
         }
     }
     if (includeAliases) {
         for (const alias of aliases) {
-            const url = urlById.get(alias.target);
-            if (url === undefined)
+            const ref = catalog.resolve(alias.target);
+            if (ref === null)
                 continue;
-            catalog.register(alias.key, { url });
+            catalog.register(alias.key, ref.dims === undefined ? { url: ref.url } : { url: ref.url, dims: ref.dims });
         }
     }
     return catalog;

package/dist/cli/pull.js

@@ -2,7 +2,7 @@
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { downloadArchive, extractGlbs, resolveArchiveUrl, sha256Hex } from "../download.js";
+import { downloadArchive, extractGlbs, extractTextures, resolveArchiveUrl, sha256Hex } from "../download.js";
 import { generatedIndex } from "../generated/index.js";
 import { reindex } from "../indexGen.js";
 import { isScrapeDownload } from "../manifest.js";
@@ -71,7 +71,14 @@ async function cmdPull(argv) {
     mkdirSync(outDir, { recursive: true });
     for (const glb of glbs)
         writeFileSync(join(outDir, glb.file), glb.bytes);
-    console.log(`pulled ${glbs.length} models -> ${outDir}`);
+    const textures = extractTextures(archive);
+    for (const texture of textures) {
+        const dest = join(outDir, texture.file);
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, texture.bytes);
+    }
+    const textureNote = textures.length > 0 ? ` + ${textures.length} texture(s)` : "";
+    console.log(`pulled ${glbs.length} models${textureNote} -> ${outDir}`);
 }
 function readSingles() {
     if (!existsSync(singlesJson))

package/dist/dims.d.ts

@@ -0,0 +1,3 @@
+import type { ModelDims } from "@jgengine/core/scene/assetCatalog";
+export type { ModelDims };
+export declare function readGlbDims(bytes: Uint8Array): ModelDims | null;

package/dist/dims.js

@@ -0,0 +1,143 @@
+const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+const GLB_MAGIC = 0x46546c67;
+const CHUNK_JSON = 0x4e4f534a;
+function multiply(a, b) {
+    const out = new Array(16);
+    for (let col = 0; col < 4; col += 1) {
+        for (let row = 0; row < 4; row += 1) {
+            let sum = 0;
+            for (let k = 0; k < 4; k += 1)
+                sum += a[k * 4 + row] * b[col * 4 + k];
+            out[col * 4 + row] = sum;
+        }
+    }
+    return out;
+}
+function fromTRS(node) {
+    if (node.matrix !== undefined && node.matrix.length === 16)
+        return [...node.matrix];
+    const [tx, ty, tz] = node.translation ?? [0, 0, 0];
+    const [qx, qy, qz, qw] = node.rotation ?? [0, 0, 0, 1];
+    const [sx, sy, sz] = node.scale ?? [1, 1, 1];
+    const x2 = qx + qx;
+    const y2 = qy + qy;
+    const z2 = qz + qz;
+    const xx = qx * x2;
+    const xy = qx * y2;
+    const xz = qx * z2;
+    const yy = qy * y2;
+    const yz = qy * z2;
+    const zz = qz * z2;
+    const wx = qw * x2;
+    const wy = qw * y2;
+    const wz = qw * z2;
+    return [
+        (1 - (yy + zz)) * sx,
+        (xy + wz) * sx,
+        (xz - wy) * sx,
+        0,
+        (xy - wz) * sy,
+        (1 - (xx + zz)) * sy,
+        (yz + wx) * sy,
+        0,
+        (xz + wy) * sz,
+        (yz - wx) * sz,
+        (1 - (xx + yy)) * sz,
+        0,
+        tx,
+        ty,
+        tz,
+        1,
+    ];
+}
+function transformPoint(m, x, y, z) {
+    return [
+        m[0] * x + m[4] * y + m[8] * z + m[12],
+        m[1] * x + m[5] * y + m[9] * z + m[13],
+        m[2] * x + m[6] * y + m[10] * z + m[14],
+    ];
+}
+function readJsonChunk(bytes) {
+    if (bytes.byteLength < 20)
+        return null;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(0, true) !== GLB_MAGIC)
+        return null;
+    const chunkLength = view.getUint32(12, true);
+    const chunkType = view.getUint32(16, true);
+    if (chunkType !== CHUNK_JSON)
+        return null;
+    const start = 20;
+    const end = start + chunkLength;
+    if (end > bytes.byteLength)
+        return null;
+    const json = new TextDecoder().decode(bytes.subarray(start, end));
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+}
+function accumulate(bounds, x, y, z) {
+    if (x < bounds.min[0])
+        bounds.min[0] = x;
+    if (y < bounds.min[1])
+        bounds.min[1] = y;
+    if (z < bounds.min[2])
+        bounds.min[2] = z;
+    if (x > bounds.max[0])
+        bounds.max[0] = x;
+    if (y > bounds.max[1])
+        bounds.max[1] = y;
+    if (z > bounds.max[2])
+        bounds.max[2] = z;
+}
+function walk(gltf, nodeIndex, parent, bounds) {
+    const node = gltf.nodes?.[nodeIndex];
+    if (node === undefined)
+        return;
+    const world = multiply(parent, fromTRS(node));
+    if (node.mesh !== undefined) {
+        const mesh = gltf.meshes?.[node.mesh];
+        for (const primitive of mesh?.primitives ?? []) {
+            const accessorIndex = primitive.attributes?.POSITION;
+            if (accessorIndex === undefined)
+                continue;
+            const accessor = gltf.accessors?.[accessorIndex];
+            const min = accessor?.min;
+            const max = accessor?.max;
+            if (min === undefined || max === undefined || min.length < 3 || max.length < 3)
+                continue;
+            for (let corner = 0; corner < 8; corner += 1) {
+                const cx = (corner & 1) === 0 ? min[0] : max[0];
+                const cy = (corner & 2) === 0 ? min[1] : max[1];
+                const cz = (corner & 4) === 0 ? min[2] : max[2];
+                const [wx, wy, wz] = transformPoint(world, cx, cy, cz);
+                accumulate(bounds, wx, wy, wz);
+            }
+        }
+    }
+    for (const child of node.children ?? [])
+        walk(gltf, child, world, bounds);
+}
+export function readGlbDims(bytes) {
+    const gltf = readJsonChunk(bytes);
+    if (gltf === null)
+        return null;
+    const sceneIndex = gltf.scene ?? 0;
+    const roots = gltf.scenes?.[sceneIndex]?.nodes ?? gltf.nodes?.map((_, index) => index) ?? [];
+    const bounds = {
+        min: [Infinity, Infinity, Infinity],
+        max: [-Infinity, -Infinity, -Infinity],
+    };
+    for (const root of roots)
+        walk(gltf, root, IDENTITY, bounds);
+    if (!Number.isFinite(bounds.min[0]) || !Number.isFinite(bounds.max[0]))
+        return null;
+    return {
+        footprint: { w: bounds.max[0] - bounds.min[0], d: bounds.max[2] - bounds.min[2] },
+        center: { x: (bounds.min[0] + bounds.max[0]) / 2, z: (bounds.min[2] + bounds.max[2]) / 2 },
+        minY: bounds.min[1],
+    };
+}

package/dist/download.d.ts

@@ -3,8 +3,14 @@ export interface ExtractedGlb {
     file: string;
     bytes: Uint8Array;
 }
+export interface ExtractedTexture {
+    /** Path relative to the pack output dir, e.g. "Textures/colormap.png". */
+    file: string;
+    bytes: Uint8Array;
+}
 export declare function findArchiveUrl(html: string, pageUrl: string): string | null;
 export declare function resolveArchiveUrl(source: AssetSource): Promise<string>;
 export declare function downloadArchive(url: string): Promise<Uint8Array>;
 export declare function extractGlbs(archive: Uint8Array): ExtractedGlb[];
+export declare function extractTextures(archive: Uint8Array): ExtractedTexture[];
 export declare function sha256Hex(bytes: Uint8Array): Promise<string>;

package/dist/download.js

@@ -60,6 +60,22 @@ export function extractGlbs(archive) {
     }
     return Array.from(byName, ([file, bytes]) => ({ file, bytes })).sort((a, b) => a.file.localeCompare(b.file));
 }
+const TEXTURE_ENTRY = /(?:^|\/)(Textures\/[^/]+)$/i;
+export function extractTextures(archive) {
+    const entries = unzipSync(archive, {
+        filter: (file) => TEXTURE_ENTRY.test(file.name),
+    });
+    const byRel = new Map();
+    for (const [path, bytes] of Object.entries(entries)) {
+        const match = path.match(TEXTURE_ENTRY);
+        if (match === null)
+            continue;
+        const rel = match[1];
+        if (!byRel.has(rel))
+            byRel.set(rel, bytes);
+    }
+    return Array.from(byRel, ([file, bytes]) => ({ file, bytes })).sort((a, b) => a.file.localeCompare(b.file));
+}
 export async function sha256Hex(bytes) {
     const buffer = new ArrayBuffer(bytes.byteLength);
     new Uint8Array(buffer).set(bytes);

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { sources, sourceById, kenneySources, quaterniusSources, kaykitSources }
 export { singles } from "./singles.js";
 export { aliases } from "./aliases.js";
 export { generatedIndex, generatedBySource } from "./generated/index.js";
+export { readGlbDims } from "./dims.js";
 export { buildCatalog, entryUrl, type BuildCatalogOptions } from "./catalogs/build.js";
 export { createStarterCatalog } from "./catalogs/starter.js";
 export { verifyManifest, type VerifyResult } from "./verify.js";

package/dist/index.js

@@ -3,6 +3,7 @@ export { sources, sourceById, kenneySources, quaterniusSources, kaykitSources }
 export { singles } from "./singles.js";
 export { aliases } from "./aliases.js";
 export { generatedIndex, generatedBySource } from "./generated/index.js";
+export { readGlbDims } from "./dims.js";
 export { buildCatalog, entryUrl } from "./catalogs/build.js";
 export { createStarterCatalog } from "./catalogs/starter.js";
 export { verifyManifest } from "./verify.js";

package/dist/indexGen.d.ts

@@ -1,6 +1,6 @@
-import type { AssetSource, IndexEntry } from "./manifest.js";
+import type { AssetSource, IndexEntry, ModelDims } from "./manifest.js";
 export declare function keyFromFile(file: string): string;
-export declare function entryForFile(source: AssetSource, file: string): IndexEntry;
+export declare function entryForFile(source: AssetSource, file: string, dims?: ModelDims): IndexEntry;
 export declare function indexSourceDir(source: AssetSource, dir: string): IndexEntry[];
 export interface ReindexResult {
     perSource: {

package/dist/indexGen.js

@@ -1,15 +1,17 @@
-import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { readGlbDims } from "./dims.js";
 import { sourceById } from "./sources/index.js";
 export function keyFromFile(file) {
     return file.replace(/\.glb$/i, "");
 }
-export function entryForFile(source, file) {
+export function entryForFile(source, file, dims) {
     return {
         id: `${source.id}/${keyFromFile(file)}`,
         source: source.id,
         categories: source.categories,
         file,
+        ...(dims === undefined ? {} : { dims }),
     };
 }
 function collectGlbFiles(dir) {
@@ -20,19 +22,27 @@ function collectGlbFiles(dir) {
             found.push(...collectGlbFiles(full));
         }
         else if (/\.glb$/i.test(name)) {
-            found.push(name);
+            found.push({ file: name, full });
         }
     }
     return found;
 }
+function measureDims(full) {
+    try {
+        return readGlbDims(readFileSync(full)) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function indexSourceDir(source, dir) {
     const seen = new Set();
     const entries = [];
-    for (const file of collectGlbFiles(dir).sort((a, b) => a.localeCompare(b))) {
+    for (const { file, full } of collectGlbFiles(dir).sort((a, b) => a.file.localeCompare(b.file))) {
         if (seen.has(file))
             continue;
         seen.add(file);
-        entries.push(entryForFile(source, file));
+        entries.push(entryForFile(source, file, measureDims(full)));
     }
     return entries;
 }

package/dist/manifest.d.ts

@@ -1,3 +1,5 @@
+import type { ModelDims } from "@jgengine/core/scene/assetCatalog";
+export type { ModelDims };
 export type AssetProvider = "kenney" | "quaternius" | "kaykit" | "polypizza" | "itch" | "custom";
 export interface PinnedDownload {
     url: string;
@@ -23,6 +25,8 @@ export interface IndexEntry {
     source: string;
     categories: readonly string[];
     file: string;
+    /** Footprint/center/minY measured from the GLB at reindex; absent when the model could not be read. */
+    dims?: ModelDims;
 }
 export interface AssetAlias {
     key: string;

package/dist/sources/kenney.js

@@ -1,4 +1,6 @@
 const KENNEY_PACKS = [
+    { id: "kenney-furniture", slug: "furniture-kit", title: "Furniture Kit", categories: ["furniture", "interior", "prop"] },
+    { id: "kenney-mini-characters", slug: "mini-characters", title: "Mini Characters", categories: ["character", "rigged"] },
     { id: "kenney-nature", slug: "nature-kit", title: "Nature Kit", categories: ["nature", "environment", "prop"] },
     { id: "kenney-castle", slug: "castle-kit", title: "Castle Kit", categories: ["building", "medieval", "environment"] },
     { id: "kenney-city-commercial", slug: "city-kit-commercial", title: "City Kit (Commercial)", categories: ["building", "city", "environment"] },
@@ -19,6 +21,8 @@ const KENNEY_PACKS = [
     { id: "kenney-tower-defense", slug: "tower-defense-kit", title: "Tower Defense Kit", categories: ["tower", "environment", "prop"] },
     { id: "kenney-food", slug: "food-kit", title: "Food Kit", categories: ["food", "prop"] },
     { id: "kenney-blaster", slug: "blaster-kit", title: "Blaster Kit", categories: ["weapon", "prop"] },
+    { id: "kenney-furniture", slug: "furniture-kit", title: "Furniture Kit", categories: ["furniture", "interior", "prop"] },
+    { id: "kenney-mini-characters", slug: "mini-characters", title: "Mini Characters", categories: ["character", "prop"] },
 ];
 export const kenneySources = KENNEY_PACKS.map((pack) => ({
     id: pack.id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/assets",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Self-generating, license-verified index of thousands of CC0 3D models for JGengine. Sources fetch from providers' own CDNs at pull time; the npm tarball ships only the typed index and CLI (no GLB bytes).",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -33,7 +33,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.5.0",
+    "@jgengine/core": "^0.6.0",
     "fflate": "^0.8.2"
   },
   "devDependencies": {