@nice2dev/game-engine 0.1.0 → 1.0.2

package/dist/cjs/index.js

@@ -36,6 +36,7 @@ var SceneEditor3D = require('./runtime3d/SceneEditor3D.js');
 var ActionTemplates = require('./templates/ActionTemplates.js');
 var PuzzleTemplates = require('./templates/PuzzleTemplates.js');
 var RPGTemplates = require('./templates/RPGTemplates.js');
+var InventorySystem = require('./inventory/InventorySystem.js');
 var SportsTemplates = require('./templates/SportsTemplates.js');
 var StrategyTemplates = require('./templates/StrategyTemplates.js');
 var PartyTemplates = require('./templates/PartyTemplates.js');
@@ -70,6 +71,13 @@ var TutorialBranching = require('./tutorials/TutorialBranching.js');
 var DevTools = require('./devtools/DevTools.js');
 var KidTools = require('./kids/KidTools.js');
 var BenchmarkSuite = require('./performance/BenchmarkSuite.js');
+var IconSprite = require('./integration/IconSprite.js');
+var WebGPURenderPipeline = require('./rendering/WebGPURenderPipeline.js');
+var AudioBridge = require('./audio/AudioBridge.js');
+var DialogueSystem = require('./dialogue/DialogueSystem.js');
+var QuestSystem = require('./quest/QuestSystem.js');
+var SaveSystemV2 = require('./engine/SaveSystemV2.js');
+var GameplayAnalytics = require('./devtools/GameplayAnalytics.js');
 
 
 
@@ -88,6 +96,7 @@ exports.PRESET_PLATFORMER = InputManager.PRESET_PLATFORMER;
 exports.PRESET_TOPDOWN = InputManager.PRESET_TOPDOWN;
 exports.PRESET_TWIN_STICK = InputManager.PRESET_TWIN_STICK;
 exports.GamepadNavigationProvider = GamepadNavigation.GamepadNavigationProvider;
+exports.NiceGamepadNavigationProvider = GamepadNavigation.GamepadNavigationProvider;
 exports.useGamepadNavigation = GamepadNavigation.useGamepadNavigation;
 exports.useGamepadEdges = useGamepads.useGamepadEdges;
 exports.useGamepads = useGamepads.useGamepads;
@@ -99,6 +108,7 @@ exports.PhysicsEngine2D = PhysicsEngine2D.PhysicsEngine2D;
 exports.PhysicsSystem = PhysicsEngine2D.PhysicsSystem;
 exports.SceneManager = SceneManager.SceneManager;
 exports.GameUI = GameUI.GameUI;
+exports.NiceGameUI = GameUI.GameUI;
 exports.PLAYER_COLORS = LocalMultiplayer.PLAYER_COLORS;
 exports.PlayerManager = LocalMultiplayer.PlayerManager;
 exports.SplitScreenManager = LocalMultiplayer.SplitScreenManager;
@@ -111,8 +121,8 @@ exports.KEYBOARD_GROUPS = MiniGameTypes.KEYBOARD_GROUPS;
 exports.MINI_PLAYER_COLORS = MiniGameTypes.MINI_PLAYER_COLORS;
 exports.MINI_PLAYER_NAMES = MiniGameTypes.MINI_PLAYER_NAMES;
 exports.gameRegistry = MiniGameTypes.gameRegistry;
-exports.LootTable = Procedural.LootTable;
 exports.PerlinNoise = Procedural.PerlinNoise;
+exports.ProceduralLootTable = Procedural.LootTable;
 exports.ProceduralSprite = Procedural.ProceduralSprite;
 exports.SeededRandom = Procedural.SeededRandom;
 exports.WaveGenerator = Procedural.WaveGenerator;
@@ -232,6 +242,11 @@ exports.createVNState = RPGTemplates.createVNState;
 exports.generateDungeon = RPGTemplates.generateDungeon;
 exports.parseVNLabels = RPGTemplates.parseVNLabels;
 exports.xpForLevel = RPGTemplates.xpForLevel;
+exports.InventoryManager = InventorySystem.InventoryManager;
+exports.InventoryProvider = InventorySystem.InventoryProvider;
+exports.useContainer = InventorySystem.useContainer;
+exports.useEquipment = InventorySystem.useEquipment;
+exports.useInventoryManager = InventorySystem.useInventoryManager;
 exports.DEFAULT_BASKETBALL_CONFIG = SportsTemplates.DEFAULT_BASKETBALL_CONFIG;
 exports.DEFAULT_BILLIARDS_CONFIG = SportsTemplates.DEFAULT_BILLIARDS_CONFIG;
 exports.DEFAULT_GOLF_CONFIG = SportsTemplates.DEFAULT_GOLF_CONFIG;
@@ -523,4 +538,78 @@ exports.GuidedWizard = KidTools.GuidedWizard;
 exports.KID_BLOCK_PALETTES = KidTools.KID_BLOCK_PALETTES;
 exports.BUILTIN_BENCHMARKS = BenchmarkSuite.BUILTIN_BENCHMARKS;
 exports.BenchmarkRunner = BenchmarkSuite.BenchmarkRunner;
+exports.CHARACTER_ANIMATION_STATES = IconSprite.CHARACTER_ANIMATION_STATES;
+exports.OBJECT_ANIMATION_STATES = IconSprite.OBJECT_ANIMATION_STATES;
+exports.createIconAnimationClip = IconSprite.createIconAnimationClip;
+exports.createIconAnimator = IconSprite.createIconAnimator;
+exports.createIconEntity = IconSprite.createIconEntity;
+exports.getIconTextureId = IconSprite.getIconTextureId;
+exports.iconToSvgString = IconSprite.iconToSvgString;
+exports.loadSvgImage = IconSprite.loadSvgImage;
+exports.rasterizeSvg = IconSprite.rasterizeSvg;
+exports.registerIconAnimationSet = IconSprite.registerIconAnimationSet;
+exports.registerIconCanvasTexture = IconSprite.registerIconCanvasTexture;
+exports.registerIconCatalog = IconSprite.registerIconCatalog;
+exports.registerIconTexture = IconSprite.registerIconTexture;
+exports.svgToDataUrl = IconSprite.svgToDataUrl;
+exports.BLOOM_DEFAULTS = WebGPURenderPipeline.BLOOM_DEFAULTS;
+exports.COLOR_GRADING_DEFAULTS = WebGPURenderPipeline.COLOR_GRADING_DEFAULTS;
+exports.DEFAULT_PBR = WebGPURenderPipeline.DEFAULT_PBR;
+exports.DEFAULT_RENDER_CONFIG = WebGPURenderPipeline.DEFAULT_RENDER_CONFIG;
+exports.DOF_DEFAULTS = WebGPURenderPipeline.DOF_DEFAULTS;
+exports.FXAA_DEFAULTS = WebGPURenderPipeline.FXAA_DEFAULTS;
+exports.GPUResourceTracker = WebGPURenderPipeline.GPUResourceTracker;
+exports.INSTANCE_LAYOUT = WebGPURenderPipeline.INSTANCE_LAYOUT;
+exports.PostProcessStack = WebGPURenderPipeline.PostProcessStack;
+exports.QUALITY_PRESET_CONFIGS = WebGPURenderPipeline.QUALITY_PRESET_CONFIGS;
+exports.RenderPipelineManager = WebGPURenderPipeline.RenderPipelineManager;
+exports.SSAO_DEFAULTS = WebGPURenderPipeline.SSAO_DEFAULTS;
+exports.STANDARD_VERTEX_LAYOUT = WebGPURenderPipeline.STANDARD_VERTEX_LAYOUT;
+exports.WebGPURenderer = WebGPURenderPipeline.WebGPURenderer;
+exports.applyQualityPreset = WebGPURenderPipeline.applyQualityPreset;
+exports.AudioBusMixer = AudioBridge.AudioBusMixer;
+exports.DEFAULT_SPATIAL = AudioBridge.DEFAULT_SPATIAL;
+exports.GameAudioBridge = AudioBridge.GameAudioBridge;
+exports.GameAudioSettings = AudioBridge.GameAudioSettings;
+exports.MusicManager = AudioBridge.MusicManager;
+exports.SFXPool = AudioBridge.SFXPool;
+exports.useGameAudio = AudioBridge.useGameAudio;
+exports.ChoiceList = DialogueSystem.ChoiceList;
+exports.DEFAULT_TEXT_SPEED = DialogueSystem.DEFAULT_TEXT_SPEED;
+exports.DialogueBox = DialogueSystem.DialogueBox;
+exports.DialogueEngine = DialogueSystem.DialogueEngine;
+exports.DialogueTreeBuilder = DialogueSystem.DialogueTreeBuilder;
+exports.EMOTION_COLORS = DialogueSystem.EMOTION_COLORS;
+exports.applyLocalization = DialogueSystem.applyLocalization;
+exports.createEmptyDialogueTree = DialogueSystem.createEmptyDialogueTree;
+exports.deserializeDialogueTree = DialogueSystem.deserializeDialogueTree;
+exports.extractTranslatableStrings = DialogueSystem.extractTranslatableStrings;
+exports.findUnreachableNodes = DialogueSystem.findUnreachableNodes;
+exports.serializeDialogueTree = DialogueSystem.serializeDialogueTree;
+exports.useTypewriter = DialogueSystem.useTypewriter;
+exports.validateDialogueTree = DialogueSystem.validateDialogueTree;
+exports.DIFFICULTY_COLORS = QuestSystem.DIFFICULTY_COLORS;
+exports.DIFFICULTY_XP_MULTIPLIERS = QuestSystem.DIFFICULTY_XP_MULTIPLIERS;
+exports.QuestBuilder = QuestSystem.QuestBuilder;
+exports.QuestList = QuestSystem.QuestList;
+exports.QuestManager = QuestSystem.QuestManager;
+exports.QuestTracker = QuestSystem.QuestTracker;
+exports.createEmptyQuest = QuestSystem.createEmptyQuest;
+exports.DEFAULT_SAVE_CONFIG = SaveSystemV2.DEFAULT_SAVE_CONFIG;
+exports.MigrationEngine = SaveSystemV2.MigrationEngine;
+exports.SaveSystemV2 = SaveSystemV2.SaveSystemV2;
+exports.compressSaveData = SaveSystemV2.compressSaveData;
+exports.crc32 = SaveSystemV2.crc32;
+exports.decompressSaveData = SaveSystemV2.decompressSaveData;
+exports.AnalyticsDashboard = GameplayAnalytics.AnalyticsDashboard;
+exports.DEFAULT_HEATMAP_CONFIG = GameplayAnalytics.DEFAULT_HEATMAP_CONFIG;
+exports.DEFAULT_RECORDING_CONFIG = GameplayAnalytics.DEFAULT_RECORDING_CONFIG;
+exports.DEFAULT_TELEMETRY_CONFIG = GameplayAnalytics.DEFAULT_TELEMETRY_CONFIG;
+exports.FunnelTracker = GameplayAnalytics.FunnelTracker;
+exports.GameplayAnalytics = GameplayAnalytics.GameplayAnalytics;
+exports.HeatmapGenerator = GameplayAnalytics.HeatmapGenerator;
+exports.SessionPlayer = GameplayAnalytics.SessionPlayer;
+exports.SessionRecorder = GameplayAnalytics.SessionRecorder;
+exports.TelemetryPipeline = GameplayAnalytics.TelemetryPipeline;
+exports.useGameplayAnalytics = GameplayAnalytics.useGameplayAnalytics;
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/input/GamepadNavigation.js

@@ -1,23 +1,23 @@
 'use strict';
 
 var jsxRuntime = require('react/jsx-runtime');
-var react = require('react');
+var React = require('react');
 
-const Ctx = react.createContext(undefined);
+const Ctx = React.createContext(undefined);
 /* ── Provider ──────────────────────────────────────────────────── */
 function GamepadNavigationProvider({ children }) {
-    const [focusables, setFocusables] = react.useState([]);
-    const [activeId, setActiveId] = react.useState(null);
-    const focusablesRef = react.useRef([]);
-    const activeIdRef = react.useRef(null);
-    const focusTrapStackRef = react.useRef([]);
-    const gameModeLockRef = react.useRef(0);
-    const enterGameMode = react.useCallback(() => { gameModeLockRef.current += 1; }, []);
-    const exitGameMode = react.useCallback(() => { gameModeLockRef.current = Math.max(0, gameModeLockRef.current - 1); }, []);
-    const pushFocusTrap = react.useCallback((prefix, onDismiss) => {
+    const [focusables, setFocusables] = React.useState([]);
+    const [activeId, setActiveId] = React.useState(null);
+    const focusablesRef = React.useRef([]);
+    const activeIdRef = React.useRef(null);
+    const focusTrapStackRef = React.useRef([]);
+    const gameModeLockRef = React.useRef(0);
+    const enterGameMode = React.useCallback(() => { gameModeLockRef.current += 1; }, []);
+    const exitGameMode = React.useCallback(() => { gameModeLockRef.current = Math.max(0, gameModeLockRef.current - 1); }, []);
+    const pushFocusTrap = React.useCallback((prefix, onDismiss) => {
         focusTrapStackRef.current = [...focusTrapStackRef.current, { prefix, onDismiss }];
     }, []);
-    const popFocusTrap = react.useCallback(() => {
+    const popFocusTrap = React.useCallback(() => {
         var _a;
         const stack = focusTrapStackRef.current;
         if (stack.length === 0)
@@ -26,16 +26,16 @@ function GamepadNavigationProvider({ children }) {
         focusTrapStackRef.current = stack.slice(0, -1);
         (_a = top.onDismiss) === null || _a === void 0 ? void 0 : _a.call(top);
     }, []);
-    react.useEffect(() => { focusablesRef.current = focusables; }, [focusables]);
-    react.useEffect(() => { activeIdRef.current = activeId; }, [activeId]);
-    const register = react.useCallback((meta) => {
+    React.useEffect(() => { focusablesRef.current = focusables; }, [focusables]);
+    React.useEffect(() => { activeIdRef.current = activeId; }, [activeId]);
+    const register = React.useCallback((meta) => {
         setFocusables(prev => {
             if (prev.some(f => f.id === meta.id))
                 return prev;
             return [...prev, meta];
         });
     }, []);
-    const unregister = react.useCallback((id) => {
+    const unregister = React.useCallback((id) => {
         setFocusables(prev => {
             var _a, _b;
             const filtered = prev.filter(f => f.id !== id);
@@ -52,7 +52,7 @@ function GamepadNavigationProvider({ children }) {
             return filtered;
         });
     }, []);
-    const moveFocus = react.useCallback((dx, dy) => {
+    const moveFocus = React.useCallback((dx, dy) => {
         var _a, _b;
         if (gameModeLockRef.current > 0)
             return;
@@ -96,12 +96,12 @@ function GamepadNavigationProvider({ children }) {
         activeIdRef.current = best.id;
         (_b = best.ref.current) === null || _b === void 0 ? void 0 : _b.focus();
     }, []);
-    const setActiveById = react.useCallback((id) => {
+    const setActiveById = React.useCallback((id) => {
         setActiveId(id);
         activeIdRef.current = id;
     }, []);
     // Keyboard navigation (Arrow keys)
-    react.useEffect(() => {
+    React.useEffect(() => {
         const handler = (e) => {
             if (gameModeLockRef.current > 0)
                 return;
@@ -131,7 +131,7 @@ function GamepadNavigationProvider({ children }) {
         return () => window.removeEventListener("keydown", handler);
     }, [moveFocus, popFocusTrap]);
     // Gamepad polling
-    react.useEffect(() => {
+    React.useEffect(() => {
         let raf = 0;
         let prevDx = 0, prevDy = 0;
         const poll = () => {
@@ -170,7 +170,7 @@ function GamepadNavigationProvider({ children }) {
     return jsxRuntime.jsx(Ctx.Provider, { value: value, children: children });
 }
 function useGamepadNavigation() {
-    const ctx = react.useContext(Ctx);
+    const ctx = React.useContext(Ctx);
     if (!ctx)
         throw new Error("useGamepadNavigation must be inside GamepadNavigationProvider");
     return ctx;

package/dist/cjs/input/useGamepads.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var react = require('react');
+var React = require('react');
 
 /**
  * useGamepads — polls connected gamepads every frame.
@@ -42,9 +42,9 @@ function snapshot(gp) {
     };
 }
 function useGamepads() {
-    const [pads, setPads] = react.useState([]);
-    const rafRef = react.useRef(0);
-    react.useEffect(() => {
+    const [pads, setPads] = React.useState([]);
+    const rafRef = React.useRef(0);
+    React.useEffect(() => {
         const poll = () => {
             var _a, _b;
             const raw = (_b = (_a = navigator.getGamepads) === null || _a === void 0 ? void 0 : _a.call(navigator)) !== null && _b !== void 0 ? _b : [];
@@ -67,7 +67,7 @@ function useGamepads() {
  */
 function useGamepadEdges() {
     const pads = useGamepads();
-    const prevRef = react.useRef([]);
+    const prevRef = React.useRef([]);
     const justPressed = (padIndex, button) => {
         const cur = pads.find(p => p.index === padIndex);
         const prev = prevRef.current.find(p => p.index === padIndex);
@@ -77,7 +77,7 @@ function useGamepadEdges() {
         const pv = prev === null || prev === void 0 ? void 0 : prev[button];
         return cv === true && pv !== true;
     };
-    react.useEffect(() => { prevRef.current = pads; });
+    React.useEffect(() => { prevRef.current = pads; });
     return { pads, justPressed };
 }
 

package/dist/cjs/integration/IconSprite.js

@@ -0,0 +1,281 @@
+'use strict';
+
+/* ────────────────────────────────────────────────────────────────
+   IconSprite — Bridge between @nice2dev/icons-gaming SVG icons
+   and the game-engine Canvas 2D renderer.
+
+   Converts React SVG icon components to rasterized textures that
+   can be used as Sprite assets, including multi-frame animation
+   sheets generated from different animation states.
+──────────────────────────────────────────────────────────────── */
+/* ── SVG to Image conversion ──────────────────────────────────── */
+/**
+ * Render an icon component to an SVG string using React's static markup API.
+ * This function must be called with the result of ReactDOMServer.renderToStaticMarkup().
+ */
+function iconToSvgString(svgMarkup, size) {
+    // Ensure SVG has xmlns for standalone rendering
+    if (!svgMarkup.includes('xmlns=')) {
+        svgMarkup = svgMarkup.replace('<svg', '<svg xmlns="http://www.w3.org/2000/svg"');
+    }
+    // Ensure dimensions
+    if (!svgMarkup.includes('width=')) {
+        svgMarkup = svgMarkup.replace('<svg', `<svg width="${size}" height="${size}"`);
+    }
+    return svgMarkup;
+}
+/**
+ * Convert an SVG string to a data URL suitable for Image loading.
+ */
+function svgToDataUrl(svgString) {
+    const encoded = encodeURIComponent(svgString)
+        .replace(/'/g, '%27')
+        .replace(/"/g, '%22');
+    return `data:image/svg+xml,${encoded}`;
+}
+/**
+ * Load an SVG data URL into an HTMLImageElement (async).
+ */
+function loadSvgImage(dataUrl) {
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        img.onload = () => resolve(img);
+        img.onerror = () => reject(new Error('Failed to load SVG image'));
+        img.src = dataUrl;
+    });
+}
+/**
+ * Rasterize an SVG string to an OffscreenCanvas / HTMLCanvasElement.
+ */
+async function rasterizeSvg(svgString, size) {
+    const dataUrl = svgToDataUrl(svgString);
+    const img = await loadSvgImage(dataUrl);
+    const canvas = document.createElement('canvas');
+    canvas.width = size;
+    canvas.height = size;
+    const ctx = canvas.getContext('2d');
+    if (!ctx)
+        throw new Error('Failed to get 2D context');
+    ctx.drawImage(img, 0, 0, size, size);
+    return canvas;
+}
+/* ── Texture registration ─────────────────────────────────────── */
+/**
+ * Generate a deterministic texture ID for an icon + options combination.
+ */
+function getIconTextureId(displayName, options) {
+    const parts = [`icon:${displayName}`];
+    if (options === null || options === void 0 ? void 0 : options.size)
+        parts.push(`s${options.size}`);
+    if (options === null || options === void 0 ? void 0 : options.color)
+        parts.push(`c${options.color}`);
+    if ((options === null || options === void 0 ? void 0 : options.animation) && options.animation !== 'none')
+        parts.push(`a${options.animation}`);
+    return parts.join(':');
+}
+/**
+ * Register an SVG icon as a texture in the game-engine renderer.
+ *
+ * @param renderer  The Renderer2D instance
+ * @param textureId Unique texture identifier
+ * @param svgMarkup Static SVG markup from ReactDOMServer.renderToStaticMarkup(<Icon ... />)
+ * @param size      Rasterization size in px
+ * @returns         Promise that resolves when the texture is ready
+ *
+ * @example
+ * ```ts
+ * import { renderToStaticMarkup } from 'react-dom/server';
+ * import { GiWarrior } from '@nice2dev/icons-gaming';
+ * import { registerIconTexture, getIconTextureId } from '@nice2dev/game-engine';
+ *
+ * const id = getIconTextureId('GiWarrior', { size: 64 });
+ * const svg = renderToStaticMarkup(<GiWarrior size={64} color="#e74c3c" />);
+ * await registerIconTexture(renderer, id, svg, 64);
+ * ```
+ */
+async function registerIconTexture(renderer, textureId, svgMarkup, size) {
+    const existing = renderer.getTexture(textureId);
+    if (existing)
+        return; // already loaded
+    const prepared = iconToSvgString(svgMarkup, size);
+    const dataUrl = svgToDataUrl(prepared);
+    await renderer.loadTexture(textureId, dataUrl);
+}
+/**
+ * Register an SVG icon as a rasterized canvas texture (sync-safe after await).
+ * Useful when you need pixel-perfect rendering without scaling artifacts.
+ */
+async function registerIconCanvasTexture(renderer, textureId, svgMarkup, size) {
+    const existing = renderer.getTexture(textureId);
+    if (existing)
+        return;
+    const prepared = iconToSvgString(svgMarkup, size);
+    const canvas = await rasterizeSvg(prepared, size);
+    renderer.setTexture(textureId, canvas);
+}
+/* ── Entity helpers ───────────────────────────────────────────── */
+/**
+ * Create a game entity with Sprite component sourced from an icon texture.
+ *
+ * The texture must already be registered via `registerIconTexture()`.
+ *
+ * @example
+ * ```ts
+ * const entityId = createIconEntity(world, 'GiWarrior', textureId, {
+ *   x: 200, y: 150, displayWidth: 64, displayHeight: 64, layer: 1,
+ * });
+ * ```
+ */
+function createIconEntity(world, name, textureId, options) {
+    var _a, _b, _c, _d, _e, _f;
+    const entity = world.createEntity((_a = options === null || options === void 0 ? void 0 : options.name) !== null && _a !== void 0 ? _a : name);
+    entity.tags.add('icon-sprite');
+    world.addComponent(entity.id, 'Transform', {
+        position: { x: (_b = options === null || options === void 0 ? void 0 : options.x) !== null && _b !== void 0 ? _b : 0, y: (_c = options === null || options === void 0 ? void 0 : options.y) !== null && _c !== void 0 ? _c : 0 },
+        scale: { x: 1, y: 1 },
+    });
+    const spriteOverrides = {
+        assetId: textureId,
+        width: (_d = options === null || options === void 0 ? void 0 : options.displayWidth) !== null && _d !== void 0 ? _d : 32,
+        height: (_e = options === null || options === void 0 ? void 0 : options.displayHeight) !== null && _e !== void 0 ? _e : 32,
+        layer: (_f = options === null || options === void 0 ? void 0 : options.layer) !== null && _f !== void 0 ? _f : 0,
+        visible: true,
+    };
+    if (options === null || options === void 0 ? void 0 : options.tint)
+        spriteOverrides.tint = options.tint;
+    if ((options === null || options === void 0 ? void 0 : options.opacity) !== undefined)
+        spriteOverrides.opacity = options.opacity;
+    world.addComponent(entity.id, 'Sprite', spriteOverrides);
+    return entity.id;
+}
+/* ── Animation sheet helpers ──────────────────────────────────── */
+/**
+ * Create a SpriteAnimation clip from multiple icon animation frames.
+ *
+ * Each frame is a separate registered texture. The AnimatorComponent
+ * switches `assetId` each frame to show different icon states.
+ *
+ * @param frames  Array of { assetId, duration } for each frame
+ * @param loop    Whether animation loops
+ */
+function createIconAnimationClip(frames, fps = 8, loop = true) {
+    return {
+        frames: frames.map(f => ({
+            assetId: f.assetId,
+            srcRect: null,
+            duration: f.duration,
+        })),
+        fps,
+        loop,
+    };
+}
+/**
+ * Predefined character animation state sequences.
+ * Maps game animation concepts to sets of icon animation states
+ * that can be baked into textures.
+ */
+const CHARACTER_ANIMATION_STATES = [
+    'idle', 'move', 'jump', 'attack-melee', 'attack-ranged', 'attack-magic', 'damage', 'death',
+];
+const OBJECT_ANIMATION_STATES = [
+    'idle', 'spin', 'float', 'shake', 'glow', 'bounce', 'flicker',
+];
+/**
+ * Batch-register all animation states of an icon as separate textures.
+ *
+ * @returns Map of animation state → texture ID
+ *
+ * @example
+ * ```ts
+ * const textures = await registerIconAnimationSet(
+ *   renderer,
+ *   'GiWarrior',
+ *   (anim) => renderToStaticMarkup(<GiWarrior size={64} animation={anim} color="#e74c3c" />),
+ *   CHARACTER_ANIMATION_STATES,
+ *   64,
+ * );
+ * // textures = { idle: 'icon:GiWarrior:s64:aidle', move: 'icon:GiWarrior:s64:amove', ... }
+ * ```
+ */
+async function registerIconAnimationSet(renderer, displayName, renderFn, states, size) {
+    const result = {};
+    for (const state of states) {
+        const textureId = getIconTextureId(displayName, { size, animation: state });
+        const svgMarkup = renderFn(state);
+        await registerIconTexture(renderer, textureId, svgMarkup, size);
+        result[state] = textureId;
+    }
+    return result;
+}
+/**
+ * Create an Animator component configuration from a registered animation set.
+ *
+ * @param textureMap Result from `registerIconAnimationSet()`
+ * @param defaultState Initial animation state (default: 'idle')
+ * @param fps Frames per second for each clip
+ */
+function createIconAnimator(textureMap, defaultState = 'idle', fps = 1) {
+    const animations = {};
+    for (const [state, assetId] of Object.entries(textureMap)) {
+        animations[state] = {
+            frames: [{ assetId, srcRect: null }],
+            fps,
+            loop: true,
+        };
+    }
+    return {
+        currentAnimation: defaultState,
+        animations,
+        frame: 0,
+        elapsed: 0,
+        playing: true,
+        loop: true,
+    };
+}
+/**
+ * Register an entire icon map (e.g. `characterIcons`, `weaponIcons`)
+ * and return a catalog array for the asset manager / picker.
+ *
+ * @param renderer   Renderer2D
+ * @param iconMap    Map of name→icon render functions (SVG markup generators)
+ * @param category   Category label for the asset catalog
+ * @param size       Texture size
+ *
+ * @example
+ * ```ts
+ * const catalog = await registerIconCatalog(
+ *   renderer,
+ *   {
+ *     GiWarrior: () => renderToStaticMarkup(<GiWarrior size={64} color="#e74c3c" />),
+ *     GiMage: () => renderToStaticMarkup(<GiMage size={64} color="#3498db" />),
+ *   },
+ *   'characters',
+ *   64,
+ * );
+ * ```
+ */
+async function registerIconCatalog(renderer, iconMap, category, size) {
+    const catalog = [];
+    for (const [name, renderFn] of Object.entries(iconMap)) {
+        const textureId = getIconTextureId(name, { size });
+        await registerIconTexture(renderer, textureId, renderFn(), size);
+        catalog.push({ name, textureId, category });
+    }
+    return catalog;
+}
+
+exports.CHARACTER_ANIMATION_STATES = CHARACTER_ANIMATION_STATES;
+exports.OBJECT_ANIMATION_STATES = OBJECT_ANIMATION_STATES;
+exports.createIconAnimationClip = createIconAnimationClip;
+exports.createIconAnimator = createIconAnimator;
+exports.createIconEntity = createIconEntity;
+exports.getIconTextureId = getIconTextureId;
+exports.iconToSvgString = iconToSvgString;
+exports.loadSvgImage = loadSvgImage;
+exports.rasterizeSvg = rasterizeSvg;
+exports.registerIconAnimationSet = registerIconAnimationSet;
+exports.registerIconCanvasTexture = registerIconCanvasTexture;
+exports.registerIconCatalog = registerIconCatalog;
+exports.registerIconTexture = registerIconTexture;
+exports.svgToDataUrl = svgToDataUrl;
+//# sourceMappingURL=IconSprite.js.map

package/dist/cjs/integration/IconSprite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IconSprite.js","sources":["../../../src/integration/IconSprite.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}