@jgengine/assets 0.10.0 → 0.11.0

package/dist/provisioning.d.ts

@@ -0,0 +1,88 @@
+import type { AssetAlias, IndexEntry, SingleAsset } from "./manifest.js";
+/**
+ * How an asset id's bytes reach a clean checkout:
+ * - `committed` — resolves to a self-hosted / remote URL carried in the shipped
+ *   index (a {@link SingleAsset}); no pull step, available immediately.
+ * - `provisioned` — a pack {@link IndexEntry}; the id is declared but its GLB is
+ *   fetched on demand by `assets pull <source>` into the consumer's served dir.
+ * - `dangling` — nothing in the index, singles, or aliases owns the id, so no
+ *   provisioning step exists and it can never resolve on a clean clone.
+ */
+export type AssetProvenanceKind = "committed" | "provisioned" | "dangling";
+/** The resolved ownership of one logical asset id — the provisioning contract for that id. */
+export interface AssetProvenance {
+    id: string;
+    kind: AssetProvenanceKind;
+    /**
+     * Where the bytes live once available: the committed URL for `committed`, the
+     * `<source>/<file>` served path for `provisioned`, or `null` for `dangling`.
+     */
+    resolvedPath: string | null;
+    /** The pack source that must be pulled, for `provisioned` ids. */
+    sourceId?: string;
+    /** The exact command that makes a `provisioned` id resolve, e.g. `assets pull quaternius-stylized-nature`. */
+    provisioningStep?: string;
+    /** When the id was reached through an alias, the alias key that pointed at it. */
+    viaAlias?: string;
+}
+/** Override the data {@link resolveProvenance} resolves against; every field defaults to the shipped catalog. */
+export interface ResolveProvenanceOptions {
+    /** Index entries to resolve against; defaults to the shipped generated index. */
+    index?: readonly IndexEntry[];
+    singles?: readonly SingleAsset[];
+    aliases?: readonly AssetAlias[];
+}
+/**
+ * Resolve one logical asset id (a pack id, a single id, or an alias key) to its
+ * {@link AssetProvenance}. Aliases are followed one hop to their target. An id
+ * that matches no declared owner is `dangling` — the signal a clean-clone gate
+ * turns into a hard failure, because no provisioning step can ever satisfy it.
+ */
+export declare function resolveProvenance(id: string, options?: ResolveProvenanceOptions): AssetProvenance;
+/** A logical asset id referenced by some consumer (a game, scene, or config), for validation. */
+export interface AssetReference {
+    /** Who references the id — a game id, scene path, or config name — surfaced in the failure. */
+    consumer: string;
+    /** The logical asset id / alias key the consumer expects to resolve. */
+    id: string;
+}
+/** The verdict for one {@link AssetReference}. */
+export interface ReferenceValidation {
+    reference: AssetReference;
+    provenance: AssetProvenance;
+    ok: boolean;
+    /** Set only when `ok` is false — a one-line diagnostic naming consumer, id, and resolved path. */
+    error?: string;
+}
+/** Options for {@link validateAssetReferences}: the resolution data plus an optional on-disk `present` check. */
+export interface ValidateAssetReferencesOptions extends ResolveProvenanceOptions {
+    /**
+     * Optional predicate reporting whether a `provisioned` id's bytes are already
+     * on disk (its `resolvedPath`). When supplied, a provisioned-but-absent id is a
+     * failure — the stricter "clean checkout with a provisioning pass already run"
+     * mode. Omit it for the pre-merge gate, where a declared provisioning owner is
+     * enough and the pull runs later in `ensure-ready`.
+     */
+    present?: (resolvedPath: string) => boolean;
+}
+/** The aggregate result of validating a set of references against the provisioning contract. */
+export interface ValidateAssetReferencesResult {
+    ok: boolean;
+    results: readonly ReferenceValidation[];
+    /** One diagnostic line per failing reference. */
+    errors: readonly string[];
+    /** The unique provisioning steps every `provisioned` reference needs, e.g. for `ensure-ready`. */
+    provisioning: readonly string[];
+}
+/**
+ * Validate that every {@link AssetReference} resolves against the declared
+ * provisioning contract — not by grepping source text, but by resolving each
+ * logical id to its committed / provisioned / dangling owner. A `dangling`
+ * reference fails with the referencing consumer, the logical id, the (null)
+ * resolved path, and the missing provisioning step; a `provisioned` reference
+ * passes and contributes its `assets pull <source>` step to `provisioning`
+ * (unless `present` is supplied and reports the bytes absent).
+ *
+ * @capability asset-reference-integrity validate asset references against the provisioning contract (dangling / committed / provisioned)
+ */
+export declare function validateAssetReferences(references: readonly AssetReference[], options?: ValidateAssetReferencesOptions): ValidateAssetReferencesResult;

package/dist/provisioning.js

@@ -0,0 +1,74 @@
+import { aliases } from "./aliases.js";
+import { generatedIndex } from "./generated/index.js";
+import { singles } from "./singles.js";
+function provisionedPath(entry) {
+    return `${entry.source}/${entry.file}`;
+}
+/**
+ * Resolve one logical asset id (a pack id, a single id, or an alias key) to its
+ * {@link AssetProvenance}. Aliases are followed one hop to their target. An id
+ * that matches no declared owner is `dangling` — the signal a clean-clone gate
+ * turns into a hard failure, because no provisioning step can ever satisfy it.
+ */
+export function resolveProvenance(id, options = {}) {
+    const index = options.index ?? generatedIndex;
+    const singleList = options.singles ?? singles;
+    const aliasList = options.aliases ?? aliases;
+    const alias = aliasList.find((entry) => entry.key === id);
+    if (alias !== undefined) {
+        const resolved = resolveProvenance(alias.target, { index, singles: singleList, aliases: aliasList });
+        return { ...resolved, id, viaAlias: alias.key };
+    }
+    const entry = index.find((candidate) => candidate.id === id);
+    if (entry !== undefined) {
+        return {
+            id,
+            kind: "provisioned",
+            resolvedPath: provisionedPath(entry),
+            sourceId: entry.source,
+            provisioningStep: `assets pull ${entry.source}`,
+        };
+    }
+    const single = singleList.find((candidate) => candidate.id === id);
+    if (single !== undefined) {
+        return { id, kind: "committed", resolvedPath: single.url };
+    }
+    return { id, kind: "dangling", resolvedPath: null };
+}
+/**
+ * Validate that every {@link AssetReference} resolves against the declared
+ * provisioning contract — not by grepping source text, but by resolving each
+ * logical id to its committed / provisioned / dangling owner. A `dangling`
+ * reference fails with the referencing consumer, the logical id, the (null)
+ * resolved path, and the missing provisioning step; a `provisioned` reference
+ * passes and contributes its `assets pull <source>` step to `provisioning`
+ * (unless `present` is supplied and reports the bytes absent).
+ *
+ * @capability asset-reference-integrity validate asset references against the provisioning contract (dangling / committed / provisioned)
+ */
+export function validateAssetReferences(references, options = {}) {
+    const results = [];
+    const errors = [];
+    const provisioning = new Set();
+    for (const reference of references) {
+        const provenance = resolveProvenance(reference.id, options);
+        if (provenance.kind === "dangling") {
+            const error = `${reference.consumer}: asset "${reference.id}" is dangling — no committed/provisioned owner declares it (resolved path: none). Add a source in packages/assets/src/sources/*.ts or a single, or remove the reference.`;
+            results.push({ reference, provenance, ok: false, error });
+            errors.push(error);
+            continue;
+        }
+        if (provenance.kind === "provisioned") {
+            if (provenance.provisioningStep !== undefined)
+                provisioning.add(provenance.provisioningStep);
+            if (options.present !== undefined && provenance.resolvedPath !== null && !options.present(provenance.resolvedPath)) {
+                const error = `${reference.consumer}: asset "${reference.id}" is not provisioned — expected bytes at "${provenance.resolvedPath}". Run \`${provenance.provisioningStep}\`.`;
+                results.push({ reference, provenance, ok: false, error });
+                errors.push(error);
+                continue;
+            }
+        }
+        results.push({ reference, provenance, ok: true });
+    }
+    return { ok: errors.length === 0, results, errors, provisioning: [...provisioning].sort() };
+}

package/dist/registry-catalog.json

@@ -51,6 +51,11 @@
       "title": "Buff Tray",
       "description": "Row of chamfered buff/debuff chips with stack counts and a remaining-duration underline, driven by a plain chip array."
     },
+    {
+      "name": "cartridge-panels",
+      "title": "Cartridge Panels",
+      "description": "Standard panel bindings for @jgengine/shell/cartridge: vital/xp/timer/score/ability-bar HUD items, upgrade-draft modal, and win/lose screens composed from the jgengine UI kit."
+    },
     {
       "name": "cast-bar",
       "title": "Cast Bar",
@@ -61,6 +66,11 @@
       "title": "Charge Meter",
       "description": "Slant-clipped charge or ultimate meter with tier ticks and a ready-state glow animation."
     },
+    {
+      "name": "chat-bubble",
+      "title": "Chat Bubble",
+      "description": "Over-entity speech bubble for proximity chat — presentational, value-driven."
+    },
     {
       "name": "combat-float-layer",
       "title": "Combat Float Layer",
@@ -106,6 +116,11 @@
       "title": "Dialogue Panel",
       "description": "Notched dialogue box with speaker nameplate, portrait well, and skill-check-annotated branching choices."
     },
+    {
+      "name": "entity-chat-bubble",
+      "title": "Entity Chat Bubble",
+      "description": "ChatBubble bound to a live entity's latest proximity chat message via useEntityChatBubble — the one-line speech bubble for any entity instance."
+    },
     {
       "name": "entity-vital-bar",
       "title": "Entity Vital Bar",
@@ -216,6 +231,11 @@
       "title": "Lock-On Marker",
       "description": "Rotating corner-bracket lock-on reticle that snaps into a diamond frame when a target is acquired, with an optional label."
     },
+    {
+      "name": "loop-dial",
+      "title": "Loop Dial",
+      "description": "Radial position-around-a-loop dial: markers at cycle fractions plus live/forecast arc windows — laps, patrols, rotation schedules."
+    },
     {
       "name": "loot-card",
       "title": "Loot Card",
@@ -241,6 +261,11 @@
       "title": "Moodle Tray",
       "description": "Buff Tray adapter for survival-game Moodle records — maps severity to buff/debuff tint and fraction to the duration ring."
     },
+    {
+      "name": "mount",
+      "title": "Mount",
+      "description": "One-call React root mount for a PlayableGame: mountGame(game) renders GameHost into #root."
+    },
     {
       "name": "objective-channel",
       "title": "Objective Channel",
@@ -256,6 +281,16 @@
       "title": "Pickup Toast Stack",
       "description": "Stacked, fading pickup toasts with rarity-tinted icon/label/count — presentational, list-driven."
     },
+    {
+      "name": "playing-card",
+      "title": "Playing Card",
+      "description": "French-deck card face with rank, suit pips, and a patterned back when face-down, plus an overlapping stack."
+    },
+    {
+      "name": "progress-strip",
+      "title": "Progress Strip",
+      "description": "Linear 1D minimap: lanes with moving markers and live/forecast segments — race standings along a lap, couriers along a line."
+    },
     {
       "name": "quest-tracker",
       "title": "Quest Tracker",
@@ -286,6 +321,11 @@
       "title": "Reticle",
       "description": "Configurable crosshair reticle — dot, cross, circle, chevron, or shotgun spread pattern — with an optional hit-flash tick overlay."
     },
+    {
+      "name": "schematic-diagram",
+      "title": "Schematic Diagram",
+      "description": "Fixed-panel node+edge schematic independent of world positions — circuit layouts, rail networks, heist floor plans, with dashed forecast edges."
+    },
     {
       "name": "score-readout",
       "title": "Score Readout",

package/dist/snippet.d.ts

@@ -7,7 +7,11 @@ export interface ModelSnippetOptions {
 }
 /** Copy-paste wiring for a pulled GLB id: resolve through the catalog, drop into a model seam. */
 export declare function modelWiringSnippet(id: string, options?: ModelSnippetOptions): string;
+/** Copy-paste wiring for a pulled PBR material: resolve the map URLs through the material catalog, then apply them onto terrain or a model. */
+export declare function materialWiringSnippet(id: string, basePath?: string): string;
 /** Copy-paste wiring for a HUD component: the `shadcn add` command plus import + usage. */
 export declare function componentWiringSnippet(component: RegistryComponent): string;
+/** Copy-paste wiring for a pulled sprite/icon-pack file: resolve through the sprite catalog. */
+export declare function spriteWiringSnippet(id: string, basePath?: string): string;
 /** Copy-paste wiring for a HUD glyph from the registry `game-icon` catalog. */
 export declare function iconWiringSnippet(name: string): string;

package/dist/snippet.js

@@ -22,6 +22,23 @@ export function modelWiringSnippet(id, options = {}) {
         `}`,
     ].join("\n");
 }
+/** Copy-paste wiring for a pulled PBR material: resolve the map URLs through the material catalog, then apply them onto terrain or a model. */
+export function materialWiringSnippet(id, basePath = "/materials") {
+    return [
+        `// src/game/assets.ts`,
+        `import { buildMaterialCatalog } from "@jgengine/assets";`,
+        `export const materials = buildMaterialCatalog({ basePath: ${JSON.stringify(basePath)} });`,
+        ``,
+        `const material = materials.resolve(${JSON.stringify(id)})!;`,
+        `// material.maps => { color, normal, roughness, ao, displacement } URLs under ${basePath}/${id}/`,
+        ``,
+        `// onto the ground (terrain() in defineGame({ world: environment({ terrain: ... }) })):`,
+        `terrain({ detail: { material: { maps: material.maps, repeat: 4 } } })`,
+        ``,
+        `// onto a model (entityModels / objectModels ModelConfig):`,
+        `{ url: ..., material: { maps: material.maps } }`,
+    ].join("\n");
+}
 /** Copy-paste wiring for a HUD component: the `shadcn add` command plus import + usage. */
 export function componentWiringSnippet(component) {
     const symbol = pascalCase(component.name);
@@ -34,6 +51,16 @@ export function componentWiringSnippet(component) {
         `// <${symbol} … />  —  ${component.description}`,
     ].join("\n");
 }
+/** Copy-paste wiring for a pulled sprite/icon-pack file: resolve through the sprite catalog. */
+export function spriteWiringSnippet(id, basePath = "/sprites") {
+    return [
+        `// src/game/assets.ts`,
+        `import { buildSpriteCatalog } from "@jgengine/assets";`,
+        `export const sprites = buildSpriteCatalog({ basePath: ${JSON.stringify(basePath)} });`,
+        ``,
+        `sprites.resolve(${JSON.stringify(id)})!.url;  // e.g. an <img src> or a HUD icon slot`,
+    ].join("\n");
+}
 /** Copy-paste wiring for a HUD glyph from the registry `game-icon` catalog. */
 export function iconWiringSnippet(name) {
     return [

package/dist/sources/ambientcg.d.ts

@@ -0,0 +1,5 @@
+import type { AssetSource } from "../manifest.js";
+/** Upstream asset id (`Grass001`) for a material source id (`ambientcg-grass001`). */
+export declare function ambientcgAssetId(source: AssetSource): string;
+/** Every ambientCG material source, generated per family (`ambientcg-grass001` … ). */
+export declare const ambientcgSources: readonly AssetSource[];

package/dist/sources/ambientcg.js

@@ -0,0 +1,64 @@
+/**
+ * ambientCG (https://ambientcg.com) — CC0 PBR materials, downloaded as flat
+ * 1K-JPG zips from the site's stable `/get?file=` endpoint and mirrored to
+ * this repo's `packs` release like every other source. Each entry is one
+ * material; families are numbered `Family001…FamilyNNN` upstream, so the
+ * catalog is generated per family instead of hand-typing hundreds of ids.
+ */
+const RESOLUTION = "1K-JPG";
+const FAMILIES = [
+    { family: "Grass", count: 5, categories: ["ground", "grass", "nature"] },
+    { family: "Ground", count: 25, categories: ["ground", "dirt", "mud"] },
+    { family: "Rock", count: 25, categories: ["rock", "cliff", "stone"] },
+    { family: "Rocks", count: 8, categories: ["rock", "scatter"] },
+    { family: "Gravel", count: 15, categories: ["ground", "gravel"] },
+    { family: "Snow", count: 6, categories: ["ground", "snow", "winter"] },
+    { family: "Ice", count: 3, categories: ["ice", "winter"] },
+    { family: "Lava", count: 4, categories: ["lava", "volcanic"] },
+    { family: "Moss", count: 2, categories: ["moss", "nature"] },
+    { family: "Bark", count: 8, categories: ["bark", "wood", "nature"] },
+    { family: "Wood", count: 30, categories: ["wood"] },
+    { family: "WoodFloor", count: 25, categories: ["wood", "floor", "interior"] },
+    { family: "Planks", count: 12, categories: ["wood", "planks"] },
+    { family: "Bricks", count: 30, categories: ["brick", "wall"] },
+    { family: "PavingStones", count: 25, categories: ["paving", "stone", "path"] },
+    { family: "Tiles", count: 30, categories: ["tile", "floor", "interior"] },
+    { family: "Concrete", count: 25, categories: ["concrete", "urban"] },
+    { family: "Asphalt", count: 12, categories: ["asphalt", "road", "urban"] },
+    { family: "Metal", count: 25, categories: ["metal"] },
+    { family: "MetalPlates", count: 10, categories: ["metal", "plates", "scifi"] },
+    { family: "Fabric", count: 25, categories: ["fabric", "cloth"] },
+    { family: "Leather", count: 12, categories: ["leather"] },
+    { family: "Marble", count: 12, categories: ["marble", "stone", "interior"] },
+    { family: "Plaster", count: 7, categories: ["plaster", "wall", "interior"] },
+    { family: "Facade", count: 6, categories: ["facade", "building"] },
+    { family: "Terrazzo", count: 8, categories: ["floor", "interior"] },
+    { family: "Wicker", count: 4, categories: ["wicker"] },
+    { family: "Rope", count: 2, categories: ["rope"] },
+    { family: "Cardboard", count: 3, categories: ["cardboard", "prop"] },
+    { family: "Paper", count: 3, categories: ["paper", "prop"] },
+    { family: "RoofingTiles", count: 8, categories: ["roof", "tile", "building"] },
+];
+/** Upstream asset id (`Grass001`) for a material source id (`ambientcg-grass001`). */
+export function ambientcgAssetId(source) {
+    const suffix = source.id.replace(/^ambientcg-/, "");
+    const digits = suffix.match(/\d+$/)?.[0] ?? "";
+    const family = FAMILIES.find((entry) => entry.family.toLowerCase() === suffix.slice(0, suffix.length - digits.length));
+    return `${family?.family ?? suffix}${digits}`;
+}
+function materialSource(family, index) {
+    const assetId = `${family.family}${String(index).padStart(3, "0")}`;
+    return {
+        id: `ambientcg-${assetId.toLowerCase()}`,
+        kind: "material",
+        provider: "ambientcg",
+        title: `${family.family} ${String(index).padStart(3, "0")} (PBR material)`,
+        license: "CC0-1.0",
+        author: "ambientCG",
+        categories: family.categories,
+        download: { url: `https://ambientcg.com/get?file=${assetId}_${RESOLUTION}.zip` },
+        homepage: `https://ambientcg.com/view?id=${assetId}`,
+    };
+}
+/** Every ambientCG material source, generated per family (`ambientcg-grass001` … ). */
+export const ambientcgSources = FAMILIES.flatMap((family) => Array.from({ length: family.count }, (_, index) => materialSource(family, index + 1)));

package/dist/sources/gameicons.d.ts

@@ -0,0 +1,10 @@
+import type { AssetSource } from "../manifest.js";
+/**
+ * game-icons.net (https://game-icons.net) — ~4,000 CC BY 3.0 SVG item/ability
+ * icons from 40+ contributing artists, mirrored as one GitHub repo
+ * (github.com/game-icons/icons). `HEAD` resolves the default branch without
+ * pinning a name or commit, so this always mirrors the current set; the
+ * per-artist `license.txt` files inside the repo carry the individual
+ * credits behind this pack's single collective `author` field.
+ */
+export declare const gameiconsSources: readonly AssetSource[];

package/dist/sources/gameicons.js

@@ -0,0 +1,21 @@
+/**
+ * game-icons.net (https://game-icons.net) — ~4,000 CC BY 3.0 SVG item/ability
+ * icons from 40+ contributing artists, mirrored as one GitHub repo
+ * (github.com/game-icons/icons). `HEAD` resolves the default branch without
+ * pinning a name or commit, so this always mirrors the current set; the
+ * per-artist `license.txt` files inside the repo carry the individual
+ * credits behind this pack's single collective `author` field.
+ */
+export const gameiconsSources = [
+    {
+        id: "gameicons-icons",
+        kind: "sprite",
+        provider: "gameicons",
+        title: "Game-Icons.net — Icon Library",
+        license: "CC BY 3.0",
+        author: "game-icons.net contributors (Lorc, Delapouite, and 40+ others — see homepage for per-icon credit)",
+        categories: ["icon", "item", "ability", "ui"],
+        download: { url: "https://codeload.github.com/game-icons/icons/zip/HEAD" },
+        homepage: "https://game-icons.net",
+    },
+];

package/dist/sources/index.d.ts

@@ -1,7 +1,14 @@
 import type { AssetSource } from "../manifest.js";
+import { ambientcgSources } from "./ambientcg.js";
+import { gameiconsSources } from "./gameicons.js";
 import { kaykitSources } from "./kaykit.js";
-import { kenneySources } from "./kenney.js";
 import { quaterniusSources } from "./quaternius.js";
 export declare const sources: readonly AssetSource[];
+/** Every source whose archive holds GLB models (Quaternius, KayKit packs). */
+export declare const modelSources: readonly AssetSource[];
+/** Every `kind: "material"` source — one CC0 PBR material each, resolvable via `buildMaterialCatalog`. */
+export declare const materialSources: readonly AssetSource[];
+/** Every `kind: "sprite"` source — a pack of individual 2D icon/UI files, resolvable via `buildSpriteCatalog`. */
+export declare const spriteSources: readonly AssetSource[];
 export declare const sourceById: ReadonlyMap<string, AssetSource>;
-export { kaykitSources, kenneySources, quaterniusSources };
+export { ambientcgSources, gameiconsSources, kaykitSources, quaterniusSources };

package/dist/sources/index.js

@@ -1,10 +1,18 @@
+import { ambientcgSources } from "./ambientcg.js";
+import { gameiconsSources } from "./gameicons.js";
 import { kaykitSources } from "./kaykit.js";
-import { kenneySources } from "./kenney.js";
 import { quaterniusSources } from "./quaternius.js";
 export const sources = [
-    ...kenneySources,
     ...quaterniusSources,
     ...kaykitSources,
+    ...ambientcgSources,
+    ...gameiconsSources,
 ];
+/** Every source whose archive holds GLB models (Quaternius, KayKit packs). */
+export const modelSources = sources.filter((source) => (source.kind ?? "model") === "model");
+/** Every `kind: "material"` source — one CC0 PBR material each, resolvable via `buildMaterialCatalog`. */
+export const materialSources = sources.filter((source) => source.kind === "material");
+/** Every `kind: "sprite"` source — a pack of individual 2D icon/UI files, resolvable via `buildSpriteCatalog`. */
+export const spriteSources = sources.filter((source) => source.kind === "sprite");
 export const sourceById = new Map(sources.map((source) => [source.id, source]));
-export { kaykitSources, kenneySources, quaterniusSources };
+export { ambientcgSources, gameiconsSources, kaykitSources, quaterniusSources };

package/dist/sources/kaykit.js

@@ -1,9 +1,57 @@
 const KAYKIT_PACKS = [
-    { id: "kaykit-adventurers", slug: "kaykit-adventurers", title: "KayKit Adventurers", categories: ["character", "rigged", "fantasy"] },
-    { id: "kaykit-skeletons", slug: "kaykit-skeletons", title: "KayKit Skeletons", categories: ["character", "monster", "creature", "undead", "rigged", "halloween"] },
-    { id: "kaykit-dungeon", slug: "kaykit-dungeon-remastered", title: "KayKit Dungeon (Remastered)", categories: ["dungeon", "environment", "prop"] },
-    { id: "kaykit-medieval-hexagon", slug: "kaykit-medieval-hexagon-pack", title: "KayKit Medieval Hexagon Pack", categories: ["hexagon", "medieval", "environment"] },
+    {
+        id: "kaykit-adventurers",
+        repo: "KayKit-Character-Pack-Adventures-1.0",
+        itch: "kaykit-adventurers",
+        title: "KayKit Adventurers",
+        categories: ["character", "rigged", "fantasy"],
+    },
+    {
+        id: "kaykit-skeletons",
+        repo: "KayKit-Character-Pack-Skeletons-1.0",
+        itch: "kaykit-skeletons",
+        title: "KayKit Skeletons",
+        categories: ["character", "monster", "creature", "undead", "rigged", "halloween"],
+    },
+    {
+        id: "kaykit-dungeon",
+        repo: "KayKit-Dungeon-Remastered-1.0",
+        itch: "kaykit-dungeon-remastered",
+        title: "KayKit Dungeon (Remastered)",
+        categories: ["dungeon", "environment", "prop"],
+    },
+    {
+        id: "kaykit-medieval-hexagon",
+        repo: "KayKit-Medieval-Hexagon-Pack-1.0",
+        itch: "kaykit-medieval-hexagon-pack",
+        title: "KayKit Medieval Hexagon Pack",
+        categories: ["hexagon", "medieval", "environment"],
+    },
+    {
+        id: "kaykit-furniture",
+        repo: "KayKit-Furniture-Bits-1.0",
+        itch: "kaykit-furniture-bits",
+        title: "KayKit Furniture Bits",
+        categories: ["furniture", "prop", "interior"],
+    },
+    {
+        id: "kaykit-city-builder",
+        repo: "KayKit-City-Builder-Bits-1.0",
+        itch: "kaykit-city-builder-bits",
+        title: "KayKit City Builder Bits",
+        categories: ["building", "city", "environment"],
+    },
+    {
+        id: "kaykit-space-base",
+        repo: "KayKit-Space-Base-Bits-1.0",
+        itch: "kaykit-space-base-bits",
+        title: "KayKit Space Base Bits",
+        categories: ["scifi", "environment", "prop"],
+    },
 ];
+function githubArchiveUrl(repo) {
+    return `https://github.com/KayKit-Game-Assets/${repo}/archive/refs/heads/main.zip`;
+}
 export const kaykitSources = KAYKIT_PACKS.map((pack) => ({
     id: pack.id,
     provider: "kaykit",
@@ -11,6 +59,7 @@ export const kaykitSources = KAYKIT_PACKS.map((pack) => ({
     license: "CC0-1.0",
     author: "Kay Lousberg",
     categories: pack.categories,
-    download: { scrape: `https://kaylousberg.itch.io/${pack.slug}` },
-    homepage: `https://kaylousberg.itch.io/${pack.slug}`,
+    download: { url: githubArchiveUrl(pack.repo) },
+    homepage: `https://kaylousberg.itch.io/${pack.itch}`,
+    mirror: githubArchiveUrl(pack.repo),
 }));

package/dist/sources/quaternius.js

@@ -1,12 +1,60 @@
+const OGA_FILES = "https://opengameart.org/sites/default/files";
 const QUATERNIUS_PACKS = [
-    { id: "quaternius-stylized-nature", slug: "stylizednaturemegakit", title: "Stylized Nature MegaKit", categories: ["nature", "environment", "prop"] },
-    { id: "quaternius-medieval-village", slug: "medievalvillagemegakit", title: "Medieval Village MegaKit", categories: ["building", "medieval", "environment"] },
-    { id: "quaternius-downtown-city", slug: "downtowncitymegakit", title: "Downtown City MegaKit", categories: ["building", "city", "environment"] },
-    { id: "quaternius-modular-scifi", slug: "modularscifimegakit", title: "Modular SciFi MegaKit", categories: ["scifi", "environment", "prop"] },
-    { id: "quaternius-fantasy-props", slug: "fantasypropsmegakit", title: "Fantasy Props MegaKit", categories: ["fantasy", "prop"] },
-    { id: "quaternius-base-characters", slug: "universalbasecharacters", title: "Universal Base Characters", categories: ["character", "rigged"] },
-    { id: "quaternius-animated-animals", slug: "ultimateanimatedanimals", title: "Ultimate Animated Animal Pack", categories: ["animal", "creature", "wildlife", "rigged", "animated"] },
-    { id: "quaternius-monsters", slug: "ultimatemonsters", title: "Ultimate Monsters", categories: ["monster", "creature", "fantasy", "rigged", "animated"] },
+    {
+        id: "quaternius-stylized-nature",
+        slug: "stylizednaturemegakit",
+        title: "Stylized Nature MegaKit",
+        categories: ["nature", "environment", "prop"],
+        ogaZip: `${OGA_FILES}/stylized_nature_megakitstandard.zip`,
+    },
+    {
+        id: "quaternius-medieval-village",
+        slug: "medievalvillagemegakit",
+        title: "Medieval Village MegaKit",
+        categories: ["building", "medieval", "environment"],
+        ogaZip: `${OGA_FILES}/medieval_village_megakitstandard.zip`,
+    },
+    {
+        id: "quaternius-downtown-city",
+        slug: "downtowncitymegakit",
+        title: "Downtown City MegaKit",
+        categories: ["building", "city", "environment"],
+        // Street Pack is the free modular city/street kit on OGA (CC0 Quaternius).
+        ogaZip: `${OGA_FILES}/Street%20Pack%20by%20%40Quaternius.zip`,
+    },
+    {
+        id: "quaternius-modular-scifi",
+        slug: "modularscifimegakit",
+        title: "Modular SciFi MegaKit",
+        categories: ["scifi", "environment", "prop"],
+        ogaZip: `${OGA_FILES}/modular_scifi_megakitstandard.zip`,
+    },
+    {
+        id: "quaternius-fantasy-props",
+        slug: "fantasypropsmegakit",
+        title: "Fantasy Props MegaKit",
+        categories: ["fantasy", "prop"],
+    },
+    {
+        id: "quaternius-base-characters",
+        slug: "universalbasecharacters",
+        title: "Universal Base Characters",
+        categories: ["character", "rigged"],
+        // OGA free dump is FBX/OBJ only — needs Pro/glTF source; scrape stays until pinned.
+    },
+    {
+        id: "quaternius-animated-animals",
+        slug: "ultimateanimatedanimals",
+        title: "Ultimate Animated Animal Pack",
+        categories: ["animal", "creature", "wildlife", "rigged", "animated"],
+    },
+    {
+        id: "quaternius-monsters",
+        slug: "ultimatemonsters",
+        title: "Ultimate Monsters",
+        categories: ["monster", "creature", "fantasy", "rigged", "animated"],
+        // OGA free dump is FBX/OBJ only — needs Pro/glTF source; scrape stays until pinned.
+    },
 ];
 export const quaterniusSources = QUATERNIUS_PACKS.map((pack) => ({
     id: pack.id,
@@ -15,6 +63,9 @@ export const quaterniusSources = QUATERNIUS_PACKS.map((pack) => ({
     license: "CC0-1.0",
     author: "Quaternius",
     categories: pack.categories,
-    download: { scrape: `https://quaternius.com/packs/${pack.slug}.html` },
+    download: pack.ogaZip !== undefined
+        ? { url: pack.ogaZip }
+        : { scrape: `https://quaternius.com/packs/${pack.slug}.html` },
     homepage: `https://quaternius.com/packs/${pack.slug}.html`,
+    ...(pack.ogaZip !== undefined ? { mirror: pack.ogaZip } : {}),
 }));

package/dist/spriteIndexGen.d.ts

@@ -0,0 +1,17 @@
+import type { AssetSource, IndexEntry } from "./manifest.js";
+/** Strips the `.svg`/`.png` extension off a pulled sprite/icon filename to get its id suffix. */
+export declare function keyFromSpriteFile(file: string): string;
+/** Builds one sprite/icon `IndexEntry` — same shape as a model entry, minus `dims`. */
+export declare function entryForSpriteFile(source: AssetSource, file: string): IndexEntry;
+/** Walks a pulled sprite-pack directory and returns one `IndexEntry` per SVG/PNG, deduped by filename. */
+export declare function indexSpriteSourceDir(source: AssetSource, dir: string): IndexEntry[];
+/** Per-source and total counts returned by `reindexSprites`. */
+export interface ReindexSpritesResult {
+    perSource: {
+        source: string;
+        count: number;
+    }[];
+    total: number;
+}
+/** Same shape as `reindex` (models) but walks SVG/PNG files and skips dims measurement — sprites have no footprint. */
+export declare function reindexSprites(spritesDir: string, outDir: string): ReindexSpritesResult;