@jgengine/assets 0.10.0 → 0.12.0

package/dist/spriteIndexGen.js

@@ -0,0 +1,108 @@
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { sourceById } from "./sources/index.js";
+/** Strips the `.svg`/`.png` extension off a pulled sprite/icon filename to get its id suffix. */
+export function keyFromSpriteFile(file) {
+    return file.replace(/\.(svg|png)$/i, "");
+}
+/** Builds one sprite/icon `IndexEntry` — same shape as a model entry, minus `dims`. */
+export function entryForSpriteFile(source, file) {
+    return {
+        id: `${source.id}/${keyFromSpriteFile(file)}`,
+        source: source.id,
+        categories: source.categories,
+        file,
+    };
+}
+function collectSpriteFiles(dir) {
+    const found = [];
+    for (const name of readdirSync(dir)) {
+        const full = join(dir, name);
+        if (statSync(full).isDirectory()) {
+            found.push(...collectSpriteFiles(full));
+        }
+        else if (/\.(svg|png)$/i.test(name)) {
+            found.push({ file: name, full });
+        }
+    }
+    return found;
+}
+/** Walks a pulled sprite-pack directory and returns one `IndexEntry` per SVG/PNG, deduped by filename. */
+export function indexSpriteSourceDir(source, dir) {
+    const seen = new Set();
+    const entries = [];
+    for (const { file } of collectSpriteFiles(dir).sort((a, b) => a.file.localeCompare(b.file))) {
+        if (seen.has(file))
+            continue;
+        seen.add(file);
+        entries.push(entryForSpriteFile(source, file));
+    }
+    return entries;
+}
+function safeIdentifier(sourceId) {
+    return `s_${sourceId.replace(/[^a-zA-Z0-9]/g, "_")}`;
+}
+function renderTsBarrel(sourceIds) {
+    const ordered = [...sourceIds].sort((a, b) => a.localeCompare(b));
+    const imports = ordered
+        .map((id) => `import ${safeIdentifier(id)} from "./${id}.json" with { type: "json" };`)
+        .join("\n");
+    const table = ordered
+        .map((id) => `  ${JSON.stringify(id)}: ${safeIdentifier(id)} as IndexEntry[],`)
+        .join("\n");
+    return `// AUTO-GENERATED by \`assets reindex-sprites\`. Do not edit by hand.
+import type { IndexEntry } from "../manifest";
+${imports}
+
+/** Pulled sprite/icon entries grouped by source id. */
+export const generatedSpriteBySource: Record<string, IndexEntry[]> = {
+${table}
+};
+
+/** Every pulled sprite/icon entry across all sources, flattened. */
+export const generatedSpriteIndex: IndexEntry[] = Object.values(generatedSpriteBySource).flat();
+`;
+}
+function renderJsBarrel(sourceIds) {
+    const ordered = [...sourceIds].sort((a, b) => a.localeCompare(b));
+    const imports = ordered
+        .map((id) => `import ${safeIdentifier(id)} from "./${id}.json" with { type: "json" };`)
+        .join("\n");
+    const table = ordered.map((id) => `  ${JSON.stringify(id)}: ${safeIdentifier(id)},`).join("\n");
+    return `// AUTO-GENERATED by \`assets reindex-sprites\`. Do not edit by hand.
+${imports}
+
+export const generatedSpriteBySource = {
+${table}
+};
+
+export const generatedSpriteIndex = Object.values(generatedSpriteBySource).flat();
+`;
+}
+/** Same shape as `reindex` (models) but walks SVG/PNG files and skips dims measurement — sprites have no footprint. */
+export function reindexSprites(spritesDir, outDir) {
+    mkdirSync(outDir, { recursive: true });
+    const perSource = [];
+    const subdirs = existsSync(spritesDir)
+        ? readdirSync(spritesDir).filter((name) => statSync(join(spritesDir, name)).isDirectory())
+        : [];
+    for (const sourceId of subdirs.sort((a, b) => a.localeCompare(b))) {
+        const source = sourceById.get(sourceId);
+        if (source === undefined || source.kind !== "sprite") {
+            perSource.push({ source: `${sourceId} (unknown, skipped)`, count: 0 });
+            continue;
+        }
+        const entries = indexSpriteSourceDir(source, join(spritesDir, sourceId));
+        writeFileSync(join(outDir, `${sourceId}.json`), `${JSON.stringify(entries, null, 2)}\n`);
+        perSource.push({ source: sourceId, count: entries.length });
+    }
+    const barrelIds = readdirSync(outDir)
+        .filter((name) => name.endsWith(".json"))
+        .map((name) => name.slice(0, -".json".length))
+        .filter((id) => sourceById.has(id));
+    writeFileSync(join(outDir, "index.ts"), renderTsBarrel(barrelIds));
+    if (!/[/\\]src[/\\]generated-sprites$/i.test(outDir)) {
+        writeFileSync(join(outDir, "index.js"), renderJsBarrel(barrelIds));
+    }
+    return { perSource, total: perSource.reduce((sum, entry) => sum + entry.count, 0) };
+}

package/dist/verify.d.ts

@@ -8,6 +8,7 @@ export interface VerifyInput {
     singles: readonly SingleAsset[];
     aliases: readonly AssetAlias[];
     index: readonly IndexEntry[];
+    materialAliases?: readonly AssetAlias[];
 }
 export declare function verifyData(input: VerifyInput): VerifyResult;
 export declare function verifyManifest(): VerifyResult;

package/dist/verify.js

@@ -1,7 +1,13 @@
 import { aliases } from "./aliases.js";
 import { generatedIndex } from "./generated/index.js";
+import { materialAliases } from "./materials.js";
 import { singles } from "./singles.js";
 import { sources } from "./sources/index.js";
+/** Providers allowed repo-wide; Kenney.nl is permanently barred — see CLAUDE.md "Never Kenney". */
+const ALLOWED_PROVIDERS = ["quaternius", "kaykit", "ambientcg", "gameicons"];
+function containsKenney(value) {
+    return value.toLowerCase().includes("kenney");
+}
 export function verifyData(input) {
     const errors = [];
     for (const source of input.sources) {
@@ -9,6 +15,11 @@ export function verifyData(input) {
             errors.push(`source ${source.id}: missing license`);
         if (source.author.trim().length === 0)
             errors.push(`source ${source.id}: missing author`);
+        if (!ALLOWED_PROVIDERS.includes(source.provider)) {
+            errors.push(`source ${source.id}: provider "${source.provider}" is not allowlisted (Never Kenney — see CLAUDE.md)`);
+        }
+        if (containsKenney(source.id))
+            errors.push(`source ${source.id}: id contains banned "kenney" substring`);
     }
     for (const single of input.singles) {
         if (single.license.trim().length === 0)
@@ -17,6 +28,20 @@ export function verifyData(input) {
             errors.push(`single ${single.id}: missing author`);
         if (single.url.trim().length === 0)
             errors.push(`single ${single.id}: missing url`);
+        if (containsKenney(single.id))
+            errors.push(`single ${single.id}: id contains banned "kenney" substring`);
+        if (containsKenney(single.url))
+            errors.push(`single ${single.id}: url contains banned "kenney" substring`);
+    }
+    for (const entry of input.index) {
+        if (containsKenney(entry.id))
+            errors.push(`index entry ${entry.id}: id contains banned "kenney" substring`);
+    }
+    for (const alias of [...input.aliases, ...(input.materialAliases ?? [])]) {
+        if (containsKenney(alias.key))
+            errors.push(`alias ${alias.key}: key contains banned "kenney" substring`);
+        if (containsKenney(alias.target))
+            errors.push(`alias ${alias.key}: target contains banned "kenney" substring`);
     }
     const knownIds = new Set([
         ...input.index.map((entry) => entry.id),
@@ -27,8 +52,20 @@ export function verifyData(input) {
             errors.push(`alias ${alias.key}: target "${alias.target}" not found in index or singles`);
         }
     }
+    const materialIds = new Set(input.sources.filter((source) => source.kind === "material").map((source) => source.id));
+    for (const alias of input.materialAliases ?? []) {
+        if (!materialIds.has(alias.target)) {
+            errors.push(`material alias ${alias.key}: target "${alias.target}" is not a material source`);
+        }
+    }
+    const seenIds = new Set();
+    for (const source of input.sources) {
+        if (seenIds.has(source.id))
+            errors.push(`source ${source.id}: duplicate id`);
+        seenIds.add(source.id);
+    }
     return { ok: errors.length === 0, errors };
 }
 export function verifyManifest() {
-    return verifyData({ sources, singles, aliases, index: generatedIndex });
+    return verifyData({ sources, singles, aliases, index: generatedIndex, materialAliases });
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@jgengine/assets",
-  "version": "0.10.0",
+  "version": "0.12.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",
+  "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "repository": {
@@ -13,7 +13,7 @@
   "files": [
     "dist",
     "CHANGELOG.md",
-    "llms.txt"
+    "skills"
   ],
   "bin": {
     "assets": "dist/cli/pull.js"
@@ -35,7 +35,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.10.0",
+    "@jgengine/core": "^0.12.0",
     "fflate": "^0.8.2"
   },
   "devDependencies": {

package/skills/jgengine/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: jgengine
+description: Route game work to the smallest useful JGengine guidance set.
+---
+
+# JGengine intake and router
+
+Read the repository [README](../../../README.md) for package truth, commands, layering, and license. This skill decides what to load; it is not an engine manual.
+
+## 1. Establish the target
+
+Treat the pitch as a unique composition of needs, not a genre to fill in — never reach for a genre kit, preset, archetype, or class template ("default sports car", "default RPG", "default FPS") in the SDK or skills (see [AGENTS.md](../../../AGENTS.md)). Use `game-design` to turn the pitch into a testable player promise, verbs, loops, progression, failure, and completion scenario. Use `level-design` when play depends on authored spaces, routes, encounters, exploration, or spatial pacing. Capture only decisions that change architecture:
+
+- player point of view and controls
+- world shape and authored content
+- core loop, interaction, combat, and progression
+- solo, local, hosted, or persistent multiplayer
+- HUD/menu states and **custom** UI art direction (every game owns its presentation — no stock drop-in face)
+- one observable completion scenario
+
+For a new in-repo game, scaffold with `bun run new:game "<id-or-title>"` (thin script alias for `jgengine create`, auto-detects the in-repo variant). Outside this monorepo, start with `npx jgengine create`; never copy `Games/*`.
+
+## 2. Select domains
+
+Load only rows the target needs. Do not preload every domain.
+
+| Need | Skill | Owner |
+| --- | --- | --- |
+| player promise, pillars, verbs, loops, economy, progression, balance | `game-design` | experience and rule intent |
+| metrics, topology, encounters, navigation, spatial pacing | `level-design` | playable space intent |
+| scene placement, terrain painting, paths, asset authoring | `jgengine-editor` | editor document and authoring tools |
+| runtime world, movement, input, interaction, AI, navigation, audio | `jgengine-world` | spatial simulation and world runtime |
+| game state, systems, inventory, crafting, quests, economy, turns | `jgengine-gameplay` | non-combat rules and state |
+| targeting, stats, damage, effects, abilities, projectiles, loot | `jgengine-combat` | combat resolution |
+| HUD, menus, layout, accessibility, touch presentation | `jgengine-ui` | player-facing interface |
+| models, sprites, materials, audio files, source licensing | `jgengine-assets` | asset discovery and catalogs |
+| authority, transport, replication, sessions, host persistence | `jgengine-multiplayer` | network topology and persistence adapters |
+
+World content routes editor-first: any request that adds, moves, restyles, or removes something visible in the world — however phrased ("design this world", "place the enemies", "make it look better") — starts in `jgengine-editor`; the other domains consume the authored document. Scenes normally require both `jgengine-editor` for authoring and `jgengine-world` for runtime consumption. Combat and multiplayer are opt-in, not default intake.
+
+## 3. Discover before designing
+
+Within each selected domain:
+
+1. Search `capabilities.md` by intent; it maps needs to imports.
+2. Open `api.md` only when exact signatures or export inventory are needed.
+3. Open the linked reference only for a deeper recipe or trap.
+4. For how several primitives wire into a running loop, read the domain's `recipes/` — connected, genre-free walkthroughs organized by composition seam; this skill's own [recipes/minimal-game.md](recipes/minimal-game.md) is the default whole-game walkthrough. Prefer a recipe over reading a game's source; the games under `Games/*` are not templates or references, and a hybrid game is just a different composition of the same primitives.
+
+If no capability fits, identify the upstream package seam before writing game-local code. In this repository, implement a reusable primitive with its first adopter; if editor-owned content cannot be expressed, file the editor gap first.
+
+## 4. Build and finish
+
+Keep scene coordinates in the editor document, state serializable, randomness injected, and hot-path work bounded. Use `jgengine-verify` for evidence appropriate to the change. Inside this monorepo, `workflow` owns issue/PR completion. Visual polish work also uses the `jgengine-ui` quality reference.