@nice2dev/game-engine 0.1.0 → 1.0.2

package/dist/types/integration/IconSprite.d.ts

@@ -0,0 +1,196 @@
+import type { EntityId, Color } from '../core/types';
+import type { World, AnimatorComponent, SpriteAnimation } from '../ecs/World';
+import type { Renderer2D } from '../rendering/Renderer2D';
+/** Minimal icon component contract (matches @nice2dev/icons-gaming) */
+export interface IconComponent {
+    (props: IconComponentProps): unknown;
+    displayName?: string;
+}
+export interface IconComponentProps {
+    size?: number;
+    animation?: string;
+    color?: string;
+    secondaryColor?: string;
+}
+/** Options for registering an icon as a sprite texture */
+export interface IconSpriteOptions {
+    /** Render size in px (icons will be rasterized at this resolution) */
+    size?: number;
+    /** Primary SVG fill color */
+    color?: string;
+    /** Secondary SVG fill color */
+    secondaryColor?: string;
+    /** Animation state to bake into the texture (default: 'none') */
+    animation?: string;
+}
+/** Configuration for creating an icon-based entity */
+export interface IconEntityOptions extends IconSpriteOptions {
+    /** Entity name override (defaults to icon displayName) */
+    name?: string;
+    /** World position X */
+    x?: number;
+    /** World position Y */
+    y?: number;
+    /** Display width in the game world (default: same as size) */
+    displayWidth?: number;
+    /** Display height in the game world (default: same as size) */
+    displayHeight?: number;
+    /** Sprite layer for depth sorting */
+    layer?: number;
+    /** Tint color multiply */
+    tint?: Color;
+    /** Opacity 0-1 */
+    opacity?: number;
+}
+/** Frame definition for icon animation sheets */
+export interface IconAnimationFrame {
+    animation: string;
+    color?: string;
+    secondaryColor?: string;
+}
+/** Options for creating a multi-frame animation from icon states */
+export interface IconAnimationSheetOptions {
+    /** Icon size per frame */
+    size?: number;
+    /** Base color (can be overridden per frame) */
+    color?: string;
+    /** Frames per second for playback */
+    fps?: number;
+    /** Whether the animation loops */
+    loop?: boolean;
+}
+/**
+ * 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().
+ */
+export declare function iconToSvgString(svgMarkup: string, size: number): string;
+/**
+ * Convert an SVG string to a data URL suitable for Image loading.
+ */
+export declare function svgToDataUrl(svgString: string): string;
+/**
+ * Load an SVG data URL into an HTMLImageElement (async).
+ */
+export declare function loadSvgImage(dataUrl: string): Promise<HTMLImageElement>;
+/**
+ * Rasterize an SVG string to an OffscreenCanvas / HTMLCanvasElement.
+ */
+export declare function rasterizeSvg(svgString: string, size: number): Promise<HTMLCanvasElement>;
+/**
+ * Generate a deterministic texture ID for an icon + options combination.
+ */
+export declare function getIconTextureId(displayName: string, options?: IconSpriteOptions): string;
+/**
+ * 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);
+ * ```
+ */
+export declare function registerIconTexture(renderer: Renderer2D, textureId: string, svgMarkup: string, size: number): Promise<void>;
+/**
+ * Register an SVG icon as a rasterized canvas texture (sync-safe after await).
+ * Useful when you need pixel-perfect rendering without scaling artifacts.
+ */
+export declare function registerIconCanvasTexture(renderer: Renderer2D, textureId: string, svgMarkup: string, size: number): Promise<void>;
+/**
+ * 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,
+ * });
+ * ```
+ */
+export declare function createIconEntity(world: World, name: string, textureId: string, options?: Omit<IconEntityOptions, 'size' | 'color' | 'secondaryColor' | 'animation'>): EntityId;
+/**
+ * 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
+ */
+export declare function createIconAnimationClip(frames: Array<{
+    assetId: string;
+    duration?: number;
+}>, fps?: number, loop?: boolean): SpriteAnimation;
+/**
+ * Predefined character animation state sequences.
+ * Maps game animation concepts to sets of icon animation states
+ * that can be baked into textures.
+ */
+export declare const CHARACTER_ANIMATION_STATES: readonly ["idle", "move", "jump", "attack-melee", "attack-ranged", "attack-magic", "damage", "death"];
+export declare const OBJECT_ANIMATION_STATES: readonly ["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', ... }
+ * ```
+ */
+export declare function registerIconAnimationSet(renderer: Renderer2D, displayName: string, renderFn: (animation: string) => string, states: readonly string[], size: number): Promise<Record<string, string>>;
+/**
+ * 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
+ */
+export declare function createIconAnimator(textureMap: Record<string, string>, defaultState?: string, fps?: number): Partial<AnimatorComponent>;
+/** Entry in a resolved icon catalog */
+export interface IconCatalogEntry {
+    name: string;
+    textureId: string;
+    category: string;
+}
+/**
+ * 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,
+ * );
+ * ```
+ */
+export declare function registerIconCatalog(renderer: Renderer2D, iconMap: Record<string, () => string>, category: string, size: number): Promise<IconCatalogEntry[]>;

package/dist/types/inventory/InventorySystem.d.ts

@@ -0,0 +1,336 @@
+import type { EntityId } from '../core/types';
+import { EventBus } from '../core/EventBus';
+import React from 'react';
+/** Item rarity levels */
+export type ItemRarity = 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary' | 'mythic' | 'unique';
+/** Item categories */
+export type ItemCategory = 'weapon' | 'armor' | 'accessory' | 'consumable' | 'material' | 'currency' | 'quest' | 'key' | 'tool' | 'mount' | 'pet' | 'cosmetic' | 'container' | 'misc';
+/** Equipment slot types */
+export type EquipmentSlot = 'head' | 'chest' | 'legs' | 'feet' | 'hands' | 'shoulders' | 'back' | 'waist' | 'mainHand' | 'offHand' | 'twoHand' | 'ring1' | 'ring2' | 'neck' | 'trinket1' | 'trinket2';
+/** Stat modifier types */
+export type StatType = 'health' | 'mana' | 'stamina' | 'attack' | 'defense' | 'magic' | 'speed' | 'critRate' | 'critDamage' | 'dodge' | 'accuracy' | 'luck' | 'custom';
+/** Container types */
+export type ContainerType = 'player' | 'chest' | 'shop' | 'bank' | 'guild' | 'mail' | 'crafting' | 'loot';
+export interface StatModifier {
+    stat: StatType;
+    /** Flat value added */
+    flat?: number;
+    /** Percentage modifier (0.1 = +10%) */
+    percent?: number;
+    /** Custom stat name if type is 'custom' */
+    customName?: string;
+}
+export interface ItemDefinition {
+    id: string;
+    name: string;
+    description: string;
+    category: ItemCategory;
+    rarity: ItemRarity;
+    /** Icon URL or icon key */
+    icon: string;
+    /** Maximum stack size (1 = not stackable) */
+    maxStack: number;
+    /** Item weight for capacity systems */
+    weight: number;
+    /** Base value in currency */
+    value: number;
+    /** Level requirement to use/equip */
+    levelRequirement?: number;
+    /** Class/role requirements */
+    classRequirement?: string[];
+    /** Stat requirements (e.g., min strength) */
+    statRequirements?: StatModifier[];
+    /** Whether item can be traded */
+    tradable: boolean;
+    /** Whether item can be sold */
+    sellable: boolean;
+    /** Whether item is destroyed on use */
+    consumeOnUse: boolean;
+    /** Equipment slot if equippable */
+    equipSlot?: EquipmentSlot;
+    /** Stat bonuses when equipped/active */
+    stats?: StatModifier[];
+    /** Max durability (undefined = indestructible) */
+    maxDurability?: number;
+    /** Set ID if part of a set */
+    setId?: string;
+    /** Soulbound type */
+    binding?: 'none' | 'onPickup' | 'onEquip' | 'account';
+    /** Cool-down in milliseconds for consumables */
+    cooldown?: number;
+    /** Effect ID when consumed */
+    effectId?: string;
+    /** Tags for filtering/searching */
+    tags?: string[];
+    /** Custom data */
+    customData?: Record<string, unknown>;
+}
+export interface ItemInstance {
+    /** Unique instance ID */
+    instanceId: string;
+    /** Reference to item definition */
+    itemId: string;
+    /** Current stack count */
+    count: number;
+    /** Current durability */
+    durability?: number;
+    /** Bound to player ID */
+    boundTo?: string;
+    /** Enchantments applied */
+    enchantments?: string[];
+    /** Socket gems */
+    sockets?: string[];
+    /** Custom display name override */
+    customName?: string;
+    /** Last used timestamp (for cooldown) */
+    lastUsed?: number;
+    /** Created timestamp */
+    createdAt: number;
+    /** Custom instance data */
+    customData?: Record<string, unknown>;
+}
+export interface InventorySlot {
+    /** Slot index */
+    index: number;
+    /** Item in this slot (null if empty) */
+    item: ItemInstance | null;
+    /** Whether slot is locked */
+    locked?: boolean;
+}
+export interface Container {
+    id: string;
+    type: ContainerType;
+    name: string;
+    /** Owner entity ID */
+    ownerId?: EntityId;
+    /** Maximum number of slots */
+    maxSlots: number;
+    /** Maximum weight capacity (undefined = unlimited) */
+    maxWeight?: number;
+    /** Slots array */
+    slots: InventorySlot[];
+    /** Currency stored in container */
+    currency?: Map<string, number>;
+    /** Whether container is sorted */
+    sorted?: boolean;
+    /** Filter for allowed item categories */
+    allowedCategories?: ItemCategory[];
+    /** Filter for disallowed item categories */
+    disallowedCategories?: ItemCategory[];
+}
+export interface EquipmentState {
+    ownerId: EntityId;
+    slots: Map<EquipmentSlot, ItemInstance | null>;
+    /** Calculated total stats from all equipped items */
+    totalStats: Map<StatType, number>;
+}
+export interface CraftingIngredient {
+    itemId: string;
+    count: number;
+    consumed: boolean;
+}
+export interface CraftingRecipe {
+    id: string;
+    name: string;
+    description: string;
+    /** Required ingredients */
+    ingredients: CraftingIngredient[];
+    /** Output item ID */
+    outputItemId: string;
+    /** Output quantity */
+    outputCount: number;
+    /** Crafting time in milliseconds */
+    craftTime: number;
+    /** Required skill/profession */
+    requiredSkill?: string;
+    /** Required skill level */
+    requiredSkillLevel?: number;
+    /** Whether recipe is learned or always available */
+    requiresLearning: boolean;
+    /** Success rate (0-1) */
+    successRate: number;
+    /** XP granted on success */
+    experienceGrant?: number;
+}
+export interface LootEntry {
+    itemId: string;
+    /** Drop weight (relative to other entries) */
+    weight: number;
+    /** Minimum quantity */
+    minCount: number;
+    /** Maximum quantity */
+    maxCount: number;
+    /** Per-item drop chance (0-1) after selection */
+    dropChance: number;
+    /** Conditions for this entry to be included */
+    conditions?: {
+        minLevel?: number;
+        maxLevel?: number;
+        requiredTags?: string[];
+    };
+}
+export interface LootTable {
+    id: string;
+    name: string;
+    /** Entries with drop weights */
+    entries: LootEntry[];
+    /** Number of rolls on this table */
+    rolls: number;
+    /** Guaranteed drops (always included) */
+    guaranteedDrops?: {
+        itemId: string;
+        count: number;
+    }[];
+}
+export interface ShopListing {
+    itemId: string;
+    /** Override price (uses item.value if undefined) */
+    price?: number;
+    /** Currency type for this listing */
+    currencyId: string;
+    /** Available stock (-1 = unlimited) */
+    stock: number;
+    /** Restock interval in milliseconds */
+    restockInterval?: number;
+    /** Requirements to see/buy */
+    requirements?: {
+        level?: number;
+        reputation?: {
+            factionId: string;
+            minLevel: number;
+        };
+        questCompleted?: string;
+    };
+}
+export interface Shop {
+    id: string;
+    name: string;
+    /** NPC or location ID owning this shop */
+    ownerId?: string;
+    /** Buy rate (percentage of item value) */
+    buyRate: number;
+    /** Sell rate (percentage of item value) */
+    sellRate: number;
+    /** Available listings */
+    listings: ShopListing[];
+    /** Currencies accepted */
+    acceptedCurrencies: string[];
+}
+export type InventoryEventType = 'item:added' | 'item:removed' | 'item:moved' | 'item:stacked' | 'item:split' | 'item:equipped' | 'item:unequipped' | 'item:used' | 'item:destroyed' | 'item:repaired' | 'item:enchanted' | 'craft:started' | 'craft:completed' | 'craft:failed' | 'shop:bought' | 'shop:sold' | 'loot:generated' | 'currency:changed' | 'container:created' | 'container:destroyed' | 'container:sorted';
+export interface InventoryEvent {
+    type: InventoryEventType;
+    containerId?: string;
+    ownerId?: EntityId;
+    item?: ItemInstance;
+    itemId?: string;
+    slot?: number;
+    fromSlot?: number;
+    toSlot?: number;
+    count?: number;
+    currencyId?: string;
+    amount?: number;
+    recipeId?: string;
+    shopId?: string;
+    timestamp: number;
+    customData?: Record<string, unknown>;
+}
+export interface InventoryManagerConfig {
+    /** Default container size */
+    defaultSlots: number;
+    /** Enable weight system */
+    enableWeight: boolean;
+    /** Enable durability system */
+    enableDurability: boolean;
+    /** Auto-stack on pickup */
+    autoStack: boolean;
+    /** Auto-sort after changes */
+    autoSort: boolean;
+    /** Maximum containers per entity */
+    maxContainersPerEntity: number;
+}
+export declare class InventoryManager {
+    private config;
+    private eventBus;
+    private itemDefinitions;
+    private containers;
+    private equipment;
+    private recipes;
+    private lootTables;
+    private shops;
+    private learnedRecipes;
+    private cooldowns;
+    constructor(config?: Partial<InventoryManagerConfig>);
+    setEventBus(bus: EventBus): void;
+    private emit;
+    registerItem(definition: ItemDefinition): void;
+    registerItems(definitions: ItemDefinition[]): void;
+    getItemDefinition(itemId: string): ItemDefinition | undefined;
+    getAllItemDefinitions(): ItemDefinition[];
+    createContainer(type: ContainerType, ownerId?: EntityId, options?: Partial<Container>): Container;
+    getContainer(containerId: string): Container | undefined;
+    getContainersByOwner(ownerId: EntityId): Container[];
+    destroyContainer(containerId: string): boolean;
+    createItemInstance(itemId: string, count?: number, options?: Partial<ItemInstance>): ItemInstance | null;
+    addItem(containerId: string, itemId: string, count?: number, options?: Partial<ItemInstance>): ItemInstance | null;
+    removeItem(containerId: string, slotIndex: number, count?: number): ItemInstance | null;
+    moveItem(fromContainerId: string, fromSlot: number, toContainerId: string, toSlot: number): boolean;
+    splitStack(containerId: string, slotIndex: number, splitCount: number): boolean;
+    getContainerWeight(containerId: string): number;
+    getContainerFreeSlots(containerId: string): number;
+    initializeEquipment(ownerId: EntityId): EquipmentState;
+    getEquipment(ownerId: EntityId): EquipmentState | undefined;
+    equipItem(ownerId: EntityId, containerId: string, slotIndex: number): boolean;
+    unequipItem(ownerId: EntityId, equipSlot: EquipmentSlot, containerId: string): boolean;
+    private unequipToContainer;
+    private recalculateEquipmentStats;
+    damageDurability(instance: ItemInstance, damage: number): boolean;
+    repairItem(instance: ItemInstance, amount?: number): boolean;
+    useItem(containerId: string, slotIndex: number, targetEntityId?: EntityId): boolean;
+    registerRecipe(recipe: CraftingRecipe): void;
+    learnRecipe(entityId: EntityId, recipeId: string): boolean;
+    canCraft(entityId: EntityId, recipeId: string, containerId: string): boolean;
+    craft(entityId: EntityId, recipeId: string, containerId: string): ItemInstance | null;
+    registerLootTable(table: LootTable): void;
+    generateLoot(tableId: string, modifiers?: {
+        luckBonus?: number;
+        levelContext?: number;
+    }): ItemInstance[];
+    registerShop(shop: Shop): void;
+    getShop(shopId: string): Shop | undefined;
+    buyFromShop(shopId: string, listingIndex: number, quantity: number, buyerContainerId: string): boolean;
+    sellToShop(shopId: string, sellerContainerId: string, slotIndex: number, quantity: number): boolean;
+    addCurrency(containerId: string, currencyId: string, amount: number): boolean;
+    removeCurrency(containerId: string, currencyId: string, amount: number): boolean;
+    getCurrency(containerId: string, currencyId: string): number;
+    sortContainer(containerId: string, criteria?: 'category' | 'rarity' | 'name' | 'value'): void;
+    countItemsInContainer(containerId: string, itemId: string): number;
+    private removeItemsByIdFromContainer;
+    findItem(containerId: string, itemId: string): {
+        slot: InventorySlot;
+        instance: ItemInstance;
+    } | null;
+    serialize(): InventorySnapshot;
+    deserialize(snapshot: InventorySnapshot): void;
+}
+export interface InventorySnapshot {
+    containers: Array<Omit<Container, 'currency'> & {
+        currency: [string, number][];
+    }>;
+    equipment: Array<{
+        ownerId: EntityId;
+        slots: [EquipmentSlot, ItemInstance | null][];
+        totalStats: [StatType, number][];
+    }>;
+    learnedRecipes: Array<{
+        entityId: EntityId;
+        recipes: string[];
+    }>;
+}
+export declare const InventoryProvider: React.FC<{
+    manager: InventoryManager;
+    children: React.ReactNode;
+}>;
+export declare function useInventoryManager(): InventoryManager;
+export declare function useContainer(containerId: string): Container | undefined;
+export declare function useEquipment(ownerId: EntityId): EquipmentState | undefined;
+export default InventoryManager;

package/dist/types/performance/WebGPUCompute.d.ts

@@ -72,16 +72,6 @@ declare global {
     interface GPUDeviceLostInfo {
         readonly message: string;
     }
-    namespace GPUBufferUsage {
-        const STORAGE: number;
-        const COPY_SRC: number;
-        const COPY_DST: number;
-        const MAP_READ: number;
-        const UNIFORM: number;
-    }
-    namespace GPUMapMode {
-        const READ: number;
-    }
     interface GPU {
         requestAdapter(options?: {
             powerPreference?: string;