@nice2dev/game-engine 1.1.5 → 1.1.6

package/dist/types/systems/NiceInventory.d.ts

@@ -0,0 +1,534 @@
+/**
+ * NiceInventory - Comprehensive Inventory System
+ *
+ * Professional inventory system for RPGs, survival games, and simulators.
+ * Supports slots, stacking, equipment, containers, and item management.
+ *
+ * Features:
+ * - Slot-based inventories with customizable sizes
+ * - Item stacking with max stack limits
+ * - Weight and volume limits
+ * - Equipment slots (armor, weapons, accessories)
+ * - Container systems (chests, bags)
+ * - Item categories and filtering
+ * - Drag-and-drop support
+ * - Item comparison
+ * - Auto-sort and organization
+ * - Crafting material tracking
+ * - Currency management
+ * - Loot generation integration
+ *
+ * @packageDocumentation
+ */
+import { EventEmitter } from 'eventemitter3';
+/** Unique identifier for items */
+export type ItemId = string;
+/** Unique identifier for item instances */
+export type ItemInstanceId = string;
+/** Unique identifier for inventories */
+export type InventoryId = string;
+/** Unique identifier for containers */
+export type ContainerId = string;
+/** Unique identifier for equipment slots */
+export type EquipSlotId = string;
+/** Item rarity */
+export type ItemRarity = 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary' | 'mythic' | 'unique';
+/** Item type/category */
+export type ItemType = 'weapon' | 'armor' | 'accessory' | 'consumable' | 'material' | 'quest' | 'currency' | 'container' | 'tool' | 'key' | 'misc';
+/** Equipment slot type */
+export type EquipmentSlot = 'head' | 'chest' | 'legs' | 'feet' | 'hands' | 'shoulders' | 'back' | 'neck' | 'ring1' | 'ring2' | 'trinket1' | 'trinket2' | 'mainHand' | 'offHand' | 'twoHand' | 'ammo';
+/** Stat modifier */
+export interface StatModifier {
+    stat: string;
+    value: number;
+    type: 'flat' | 'percent' | 'multiply';
+}
+/** Item requirement */
+export interface ItemRequirement {
+    type: 'level' | 'stat' | 'class' | 'quest' | 'skill' | 'reputation';
+    target?: string;
+    value: number | string;
+    operator?: '==' | '!=' | '>' | '<' | '>=' | '<=';
+}
+/** Item effect */
+export interface ItemEffect {
+    type: 'heal' | 'mana' | 'buff' | 'debuff' | 'damage' | 'teleport' | 'summon' | 'custom';
+    value?: number;
+    duration?: number;
+    target?: string;
+    data?: Record<string, unknown>;
+}
+/** Item definition */
+export interface ItemDefinition {
+    id: ItemId;
+    name: string;
+    description?: string;
+    shortDescription?: string;
+    type: ItemType;
+    subType?: string;
+    rarity: ItemRarity;
+    icon?: string;
+    model?: string;
+    maxStack: number;
+    weight: number;
+    volume?: number;
+    value: number;
+    sellValue?: number;
+    buyValue?: number;
+    equipSlot?: EquipmentSlot;
+    twoHanded?: boolean;
+    stats?: StatModifier[];
+    effects?: ItemEffect[];
+    requirements?: ItemRequirement[];
+    durabilityMax?: number;
+    cooldown?: number;
+    charges?: number;
+    isUsable?: boolean;
+    isConsumable?: boolean;
+    isQuestItem?: boolean;
+    isSoulbound?: boolean;
+    isUnique?: boolean;
+    isTradeable?: boolean;
+    isDroppable?: boolean;
+    isDestroyable?: boolean;
+    setId?: string;
+    tags?: string[];
+    lore?: string[];
+    metadata?: Record<string, unknown>;
+}
+/** Item instance (actual item in inventory) */
+export interface ItemInstance {
+    instanceId: ItemInstanceId;
+    itemId: ItemId;
+    definition: ItemDefinition;
+    quantity: number;
+    durability?: number;
+    charges?: number;
+    enchantments?: StatModifier[];
+    gems?: ItemId[];
+    customName?: string;
+    customDescription?: string;
+    boundTo?: string;
+    createdAt: number;
+    modifiedAt: number;
+    metadata: Map<string, unknown>;
+}
+/** Inventory slot */
+export interface InventorySlot {
+    index: number;
+    item: ItemInstance | null;
+    locked: boolean;
+    filter?: ItemType[];
+}
+/** Inventory definition */
+export interface InventoryDefinition {
+    id: InventoryId;
+    name: string;
+    size: number;
+    maxWeight?: number;
+    maxVolume?: number;
+    slotFilters?: Map<number, ItemType[]>;
+    lockedSlots?: number[];
+    isPlayerInventory?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Inventory instance */
+export interface Inventory {
+    definition: InventoryDefinition;
+    slots: InventorySlot[];
+    equipment: Map<EquipmentSlot, ItemInstance | null>;
+    currentWeight: number;
+    currentVolume: number;
+    currencies: Map<string, number>;
+}
+/** Container (chests, bags, etc.) */
+export interface Container {
+    id: ContainerId;
+    name: string;
+    inventory: Inventory;
+    isOpen: boolean;
+    isLocked: boolean;
+    lockLevel?: number;
+    keyItemId?: ItemId;
+    position?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    metadata?: Record<string, unknown>;
+}
+/** Equipment set definition */
+export interface EquipmentSet {
+    id: string;
+    name: string;
+    description?: string;
+    itemIds: ItemId[];
+    bonuses: Array<{
+        requiredPieces: number;
+        stats: StatModifier[];
+        description?: string;
+    }>;
+}
+/** Sort options */
+export interface SortOptions {
+    by: 'name' | 'type' | 'rarity' | 'value' | 'weight' | 'quantity' | 'recent';
+    ascending: boolean;
+    groupByType?: boolean;
+}
+/** Filter options */
+export interface FilterOptions {
+    types?: ItemType[];
+    rarity?: ItemRarity[];
+    minLevel?: number;
+    maxLevel?: number;
+    searchText?: string;
+    tags?: string[];
+    equipSlots?: EquipmentSlot[];
+    usableOnly?: boolean;
+    equippableOnly?: boolean;
+}
+/** Transfer result */
+export interface TransferResult {
+    success: boolean;
+    transferred: number;
+    remaining: number;
+    error?: string;
+}
+/** Inventory event types */
+export type InventoryEventType = 'item:added' | 'item:removed' | 'item:moved' | 'item:stacked' | 'item:split' | 'item:used' | 'item:equipped' | 'item:unequipped' | 'item:destroyed' | 'item:dropped' | 'item:picked' | 'item:modified' | 'inventory:created' | 'inventory:destroyed' | 'inventory:sorted' | 'inventory:full' | 'container:opened' | 'container:closed' | 'container:locked' | 'container:unlocked' | 'currency:changed' | 'weight:exceeded' | 'set:bonus:activated' | 'set:bonus:deactivated' | 'error';
+/** Inventory event */
+export interface InventoryEvent {
+    type: InventoryEventType;
+    inventoryId?: InventoryId;
+    containerId?: ContainerId;
+    itemInstanceId?: ItemInstanceId;
+    item?: ItemInstance;
+    slot?: number;
+    targetSlot?: number;
+    targetInventoryId?: InventoryId;
+    equipSlot?: EquipmentSlot;
+    quantity?: number;
+    currency?: string;
+    amount?: number;
+    setId?: string;
+    setBonusLevel?: number;
+    error?: Error;
+    timestamp: number;
+}
+/** Event callback */
+export type InventoryEventCallback = (event: InventoryEvent) => void;
+/** Inventory system configuration */
+export interface InventoryConfig {
+    /** Default inventory size */
+    defaultInventorySize: number;
+    /** Enable weight limits */
+    enableWeight: boolean;
+    /** Enable volume limits */
+    enableVolume: boolean;
+    /** Enable durability */
+    enableDurability: boolean;
+    /** Auto-stack on pickup */
+    autoStack: boolean;
+    /** Allow partial transfers */
+    allowPartialTransfer: boolean;
+    /** Destroy item on 0 durability */
+    destroyOnBreak: boolean;
+    /** Debug mode */
+    debug: boolean;
+}
+export declare const DEFAULT_INVENTORY_CONFIG: InventoryConfig;
+/** Default rarity colors */
+export declare const RARITY_COLORS: Record<ItemRarity, string>;
+/** Default rarity order */
+export declare const RARITY_ORDER: Record<ItemRarity, number>;
+export declare class NiceInventory extends EventEmitter<Record<InventoryEventType, [InventoryEvent]>> {
+    private config;
+    private itemDefinitions;
+    private inventories;
+    private containers;
+    private equipmentSets;
+    private instanceCounter;
+    constructor(config?: Partial<InventoryConfig>);
+    /**
+     * Register an item definition
+     */
+    registerItem(item: ItemDefinition): void;
+    /**
+     * Register multiple items
+     */
+    registerItems(items: ItemDefinition[]): void;
+    /**
+     * Get item definition
+     */
+    getItemDefinition(id: ItemId): ItemDefinition | undefined;
+    /**
+     * Register equipment set
+     */
+    registerEquipmentSet(set: EquipmentSet): void;
+    /**
+     * Create a new inventory
+     */
+    createInventory(definition: InventoryDefinition): Inventory;
+    /**
+     * Get inventory
+     */
+    getInventory(id: InventoryId): Inventory | undefined;
+    /**
+     * Delete inventory
+     */
+    deleteInventory(id: InventoryId): boolean;
+    /**
+     * Create an item instance
+     */
+    createItemInstance(itemId: ItemId, quantity?: number): ItemInstance | null;
+    /**
+     * Add item to inventory
+     */
+    addItem(inventoryId: InventoryId, itemId: ItemId, quantity?: number, targetSlot?: number): TransferResult;
+    /**
+     * Remove item from inventory
+     */
+    removeItem(inventoryId: InventoryId, itemId: ItemId, quantity?: number): TransferResult;
+    /**
+     * Remove item from specific slot
+     */
+    removeFromSlot(inventoryId: InventoryId, slotIndex: number, quantity?: number): ItemInstance | null;
+    /**
+     * Move item within inventory
+     */
+    moveItem(inventoryId: InventoryId, fromSlot: number, toSlot: number): boolean;
+    /**
+     * Transfer item between inventories
+     */
+    transferItem(fromInventoryId: InventoryId, fromSlot: number, toInventoryId: InventoryId, toSlot?: number, quantity?: number): TransferResult;
+    /**
+     * Split stack
+     */
+    splitStack(inventoryId: InventoryId, slotIndex: number, quantity: number, targetSlot?: number): boolean;
+    /**
+     * Equip item
+     */
+    equipItem(inventoryId: InventoryId, slotIndex: number, equipSlot?: EquipmentSlot): boolean;
+    /**
+     * Unequip item
+     */
+    unequipItem(inventoryId: InventoryId, equipSlot: EquipmentSlot, targetSlot?: number): boolean;
+    /**
+     * Get equipped item
+     */
+    getEquippedItem(inventoryId: InventoryId, equipSlot: EquipmentSlot): ItemInstance | null;
+    /**
+     * Get all equipped items
+     */
+    getEquippedItems(inventoryId: InventoryId): Map<EquipmentSlot, ItemInstance>;
+    /**
+     * Calculate equipment stats
+     */
+    getEquipmentStats(inventoryId: InventoryId): Map<string, number>;
+    /**
+     * Check set bonuses
+     */
+    private checkSetBonuses;
+    /**
+     * Use item
+     */
+    useItem(inventoryId: InventoryId, slotIndex: number, _target?: unknown): boolean;
+    /**
+     * Reduce item durability
+     */
+    reduceDurability(inventoryId: InventoryId, equipSlot: EquipmentSlot, amount?: number): boolean;
+    /**
+     * Repair item
+     */
+    repairItem(inventoryId: InventoryId, equipSlot: EquipmentSlot, amount?: number): boolean;
+    /**
+     * Get currency
+     */
+    getCurrency(inventoryId: InventoryId, currencyId: string): number;
+    /**
+     * Add currency
+     */
+    addCurrency(inventoryId: InventoryId, currencyId: string, amount: number): boolean;
+    /**
+     * Remove currency
+     */
+    removeCurrency(inventoryId: InventoryId, currencyId: string, amount: number): boolean;
+    /**
+     * Set currency
+     */
+    setCurrency(inventoryId: InventoryId, currencyId: string, amount: number): boolean;
+    /**
+     * Create container
+     */
+    createContainer(id: ContainerId, name: string, size: number, position?: {
+        x: number;
+        y: number;
+        z: number;
+    }): Container;
+    /**
+     * Get container
+     */
+    getContainer(id: ContainerId): Container | undefined;
+    /**
+     * Open container
+     */
+    openContainer(id: ContainerId): boolean;
+    /**
+     * Close container
+     */
+    closeContainer(id: ContainerId): boolean;
+    /**
+     * Unlock container
+     */
+    unlockContainer(id: ContainerId, keyItemId?: ItemId): boolean;
+    /**
+     * Lock container
+     */
+    lockContainer(id: ContainerId): boolean;
+    /**
+     * Sort inventory
+     */
+    sortInventory(inventoryId: InventoryId, options: SortOptions): boolean;
+    /**
+     * Filter inventory items
+     */
+    filterItems(inventoryId: InventoryId, options: FilterOptions): ItemInstance[];
+    /**
+     * Count items in inventory
+     */
+    countItem(inventoryId: InventoryId, itemId: ItemId): number;
+    /**
+     * Has item
+     */
+    hasItem(inventoryId: InventoryId, itemId: ItemId, quantity?: number): boolean;
+    /**
+     * Get empty slot count
+     */
+    getEmptySlotCount(inventoryId: InventoryId): number;
+    /**
+     * Check if inventory is full
+     */
+    isInventoryFull(inventoryId: InventoryId): boolean;
+    /**
+     * Get all items
+     */
+    getAllItems(inventoryId: InventoryId): ItemInstance[];
+    /**
+     * Find item slot
+     */
+    findItemSlot(inventoryId: InventoryId, itemId: ItemId): number;
+    /**
+     * Get inventory stats
+     */
+    getInventoryStats(inventoryId: InventoryId): {
+        totalSlots: number;
+        usedSlots: number;
+        emptySlots: number;
+        lockedSlots: number;
+        currentWeight: number;
+        maxWeight: number | undefined;
+        totalValue: number;
+        itemCount: number;
+        uniqueItems: number;
+    };
+    /**
+     * Export inventory state
+     */
+    exportState(inventoryId: InventoryId): {
+        slots: Array<{
+            index: number;
+            itemId?: ItemId;
+            quantity?: number;
+            durability?: number;
+            charges?: number;
+            metadata?: Record<string, unknown>;
+        }>;
+        equipment: Array<{
+            slot: EquipmentSlot;
+            itemId: ItemId;
+            durability?: number;
+            charges?: number;
+        }>;
+        currencies: Record<string, number>;
+    } | null;
+    /**
+     * Import inventory state
+     */
+    importState(inventoryId: InventoryId, data: NonNullable<ReturnType<typeof this.exportState>>): boolean;
+    /**
+     * Destroy the inventory system
+     */
+    destroy(): void;
+}
+/**
+ * Create an inventory system
+ */
+export declare function createInventorySystem(config?: Partial<InventoryConfig>): NiceInventory;
+/**
+ * Fluent builder for creating items
+ */
+export declare class ItemBuilder {
+    private item;
+    constructor(id: ItemId, name: string, type: ItemType);
+    description(desc: string): this;
+    rarity(r: ItemRarity): this;
+    icon(icon: string): this;
+    model(model: string): this;
+    stack(max: number): this;
+    weight(w: number): this;
+    value(v: number): this;
+    sellValue(v: number): this;
+    buyValue(v: number): this;
+    equipSlot(slot: EquipmentSlot, twoHanded?: boolean): this;
+    stat(stat: string, value: number, type?: StatModifier['type']): this;
+    effect(effect: ItemEffect): this;
+    requirement(req: ItemRequirement): this;
+    requireLevel(level: number): this;
+    durability(max: number): this;
+    charges(num: number): this;
+    cooldown(ms: number): this;
+    usable(): this;
+    consumable(): this;
+    questItem(): this;
+    soulbound(): this;
+    unique(): this;
+    notTradeable(): this;
+    notDroppable(): this;
+    notDestroyable(): this;
+    setId(id: string): this;
+    tags(...tags: string[]): this;
+    lore(...lines: string[]): this;
+    build(): ItemDefinition;
+}
+/**
+ * Create an item builder
+ */
+export declare function item(id: ItemId, name: string, type: ItemType): ItemBuilder;
+/**
+ * Create a weapon
+ */
+export declare function weapon(id: ItemId, name: string, slot?: EquipmentSlot): ItemBuilder;
+/**
+ * Create armor
+ */
+export declare function armor(id: ItemId, name: string, slot: EquipmentSlot): ItemBuilder;
+/**
+ * Create a consumable
+ */
+export declare function consumable(id: ItemId, name: string): ItemBuilder;
+/**
+ * Create a material
+ */
+export declare function material(id: ItemId, name: string): ItemBuilder;
+/**
+ * Create an inventory definition
+ */
+export declare function inventoryDef(id: InventoryId, name: string, size: number, maxWeight?: number): InventoryDefinition;
+/**
+ * Get rarity color
+ */
+export declare function getRarityColor(rarity: ItemRarity): string;
+/**
+ * Compare items by rarity
+ */
+export declare function compareRarity(a: ItemRarity, b: ItemRarity): number;

package/dist/types/systems/NiceLOD.d.ts

@@ -0,0 +1,144 @@
+import { EventEmitter } from 'events';
+export type EntityId = string;
+export type LODGroupId = string;
+export type LODModelId = string;
+export interface Vector3 {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface LODLevel {
+    level: number;
+    modelId: LODModelId;
+    triangleCount: number;
+    distance: number;
+    screenSize?: number;
+    fadeStart?: number;
+    fadeEnd?: number;
+}
+export interface LODObject {
+    id: EntityId;
+    position: Vector3;
+    boundingRadius: number;
+    currentLevel: number;
+    targetLevel: number;
+    fadeProgress: number;
+    lodGroup?: LODGroupId;
+    levels: LODLevel[];
+    forceLevel?: number;
+    isStatic: boolean;
+    priority: number;
+    lastUpdateFrame: number;
+}
+export interface LODGroup {
+    id: LODGroupId;
+    name: string;
+    enabled: boolean;
+    distanceMultiplier: number;
+    biasLevel: number;
+    memberIds: EntityId[];
+}
+export type QualityPreset = 'low' | 'medium' | 'high' | 'ultra';
+export interface LODBias {
+    globalDistanceMultiplier: number;
+    globalLevelBias: number;
+    transitionDuration: number;
+    ditherTransition: boolean;
+    crossFade: boolean;
+}
+export interface PerformanceBudget {
+    maxTriangles: number;
+    maxDrawCalls: number;
+    targetFrameTime: number;
+}
+export interface PerformanceStats {
+    currentTriangles: number;
+    currentDrawCalls: number;
+    currentFrameTime: number;
+    averageFrameTime: number;
+    lodSwitches: number;
+}
+export interface FrustumPlane {
+    normal: Vector3;
+    distance: number;
+}
+export interface Frustum {
+    planes: FrustumPlane[];
+}
+export type LODEventType = 'lod-changed' | 'lod-fade-started' | 'lod-fade-completed' | 'object-registered' | 'object-unregistered' | 'group-created' | 'group-removed' | 'budget-exceeded' | 'quality-changed';
+export interface LODEvent {
+    type: LODEventType;
+    entityId?: EntityId;
+    groupId?: LODGroupId;
+    data?: Record<string, unknown>;
+}
+export interface LODSystemConfig {
+    defaultDistances?: number[];
+    defaultTransitionDuration?: number;
+    updateFrequency?: number;
+    screenSizeMetric?: 'height' | 'diagonal';
+    enableFrustumCulling?: boolean;
+    enableOcclusionCulling?: boolean;
+    maxTriangleBudget?: number;
+    autoAdjustQuality?: boolean;
+    hysteresis?: number;
+}
+export declare const DEFAULT_LOD_CONFIG: LODSystemConfig;
+export declare class NiceLOD extends EventEmitter {
+    private objects;
+    private groups;
+    private config;
+    private bias;
+    private budget;
+    private stats;
+    private cameraPosition;
+    private frustum?;
+    private frameCounter;
+    private updateCounter;
+    private qualityPreset;
+    constructor(config?: Partial<LODSystemConfig>);
+    registerObject(entityId: EntityId, position: Vector3, levels: LODLevel[], options?: {
+        boundingRadius?: number;
+        lodGroup?: LODGroupId;
+        isStatic?: boolean;
+        priority?: number;
+    }): void;
+    unregisterObject(entityId: EntityId): void;
+    getObject(entityId: EntityId): LODObject | undefined;
+    updateObjectPosition(entityId: EntityId, position: Vector3): void;
+    createGroup(id: LODGroupId, name: string): LODGroup;
+    removeGroup(groupId: LODGroupId): void;
+    getGroup(groupId: LODGroupId): LODGroup | undefined;
+    setGroupDistanceMultiplier(groupId: LODGroupId, multiplier: number): void;
+    setGroupBias(groupId: LODGroupId, bias: number): void;
+    forceLevel(entityId: EntityId, level: number | undefined): void;
+    forceGroupLevel(groupId: LODGroupId, level: number | undefined): void;
+    setCameraPosition(position: Vector3): void;
+    setFrustum(frustum: Frustum): void;
+    setBias(bias: Partial<LODBias>): void;
+    getBias(): LODBias;
+    setQualityPreset(preset: QualityPreset): void;
+    getQualityPreset(): QualityPreset;
+    setBudget(budget: Partial<PerformanceBudget>): void;
+    getBudget(): PerformanceBudget;
+    getStats(): PerformanceStats;
+    reportFrameTime(frameTime: number): void;
+    private autoAdjustQuality;
+    update(deltaTime: number): void;
+    private updateLODs;
+    private updateTransitions;
+    private setObjectLevel;
+    private addToStats;
+    isObjectVisible(entityId: EntityId): boolean;
+    private isInFrustum;
+    getVisibleObjects(): LODObject[];
+    getCurrentLevel(entityId: EntityId): number;
+    getCurrentModel(entityId: EntityId): LODModelId | undefined;
+    getFadeProgress(entityId: EntityId): number;
+    getTriangleCount(entityId: EntityId): number;
+    getTotalTriangleCount(): number;
+    private calculateDistance;
+}
+export declare function createLODSystem(config?: Partial<LODSystemConfig>): NiceLOD;
+export declare function defineLODLevel(options: LODLevel): LODLevel;
+export default NiceLOD;