@esengine/ecs-framework 2.0.5 → 2.0.7

package/bin/Utils/WasmCore.d.ts

@@ -0,0 +1,234 @@
+/**
+ * 统一的WASM ECS核心模块
+ *
+ * 为小游戏优化的高性能ECS引擎，提供简洁的API和自动回退机制
+ * 适用于NPM包发布和多种部署环境
+ *
+ */
+/** 实体ID类型 */
+export type EntityId = number;
+/** 组件掩码类型 */
+export type ComponentMask = bigint;
+/** 查询结果接口 */
+export interface QueryResult {
+    /** 查询到的实体ID数组 */
+    entities: Uint32Array;
+    /** 实体数量 */
+    count: number;
+}
+/** 性能统计接口 */
+export interface PerformanceStats {
+    /** 实体总数 */
+    entityCount: number;
+    /** 索引数量 */
+    indexCount: number;
+    /** 查询次数 */
+    queryCount: number;
+    /** 更新次数 */
+    updateCount: number;
+    /** 是否使用WASM */
+    wasmEnabled: boolean;
+}
+/**
+ * 统一的WASM ECS核心类
+ *
+ * 提供高性能的ECS操作，自动选择WASM或JavaScript实现
+ * 针对小游戏场景优化，易于使用且性能卓越
+ * 支持NPM包发布和多种部署环境
+ */
+export declare class WasmEcsCore {
+    /** WASM核心实例 */
+    private wasmCore;
+    /** WASM模块 */
+    private wasmModule;
+    /** 是否已初始化 */
+    private initialized;
+    /** 是否使用WASM */
+    private usingWasm;
+    private silent;
+    private jsEntityMasks;
+    private jsNextEntityId;
+    private jsQueryCount;
+    private jsUpdateCount;
+    /**
+     * 设置静默模式
+     */
+    setSilent(silent: boolean): void;
+    /**
+     * 初始化ECS核心
+     *
+     * 尝试加载WASM模块，失败时自动回退到JavaScript实现
+     *
+     * @returns 初始化是否成功
+     */
+    initialize(): Promise<boolean>;
+    /**
+     * 创建新实体
+     *
+     * @returns 新实体的ID
+     */
+    createEntity(): EntityId;
+    /**
+     * 删除实体
+     *
+     * @param entityId 实体ID
+     * @returns 是否删除成功
+     */
+    destroyEntity(entityId: EntityId): boolean;
+    /**
+     * 更新实体的组件掩码
+     *
+     * @param entityId 实体ID
+     * @param mask 组件掩码
+     */
+    updateEntityMask(entityId: EntityId, mask: ComponentMask): void;
+    /**
+     * 批量更新实体掩码（高性能）
+     *
+     * @param entityIds 实体ID数组
+     * @param masks 组件掩码数组
+     */
+    batchUpdateMasks(entityIds: EntityId[], masks: ComponentMask[]): void;
+    /**
+     * 查询包含指定组件的实体
+     *
+     * @param mask 组件掩码
+     * @param maxResults 最大结果数
+     * @returns 查询结果
+     */
+    queryEntities(mask: ComponentMask, maxResults?: number): QueryResult;
+    /**
+     * 查询指定掩码的实体（带缓存优化）
+     *
+     * @param mask 组件掩码
+     * @returns 查询结果
+     */
+    queryCached(mask: ComponentMask): QueryResult;
+    /**
+     * 查询包含多个组件的实体
+     *
+     * @param masks 组件掩码数组
+     * @param maxResults 最大结果数
+     * @returns 查询结果
+     */
+    queryMultipleComponents(masks: ComponentMask[], maxResults?: number): QueryResult;
+    /**
+     * 排除查询：包含某些组件但不包含其他组件
+     *
+     * @param includeMask 必须包含的组件掩码
+     * @param excludeMask 必须排除的组件掩码
+     * @param maxResults 最大结果数
+     * @returns 查询结果
+     */
+    queryWithExclusion(includeMask: ComponentMask, excludeMask: ComponentMask, maxResults?: number): QueryResult;
+    /**
+     * 获取实体的组件掩码
+     *
+     * @param entityId 实体ID
+     * @returns 组件掩码，如果实体不存在则返回null
+     */
+    getEntityMask(entityId: EntityId): ComponentMask | null;
+    /**
+     * 检查实体是否存在
+     *
+     * @param entityId 实体ID
+     * @returns 是否存在
+     */
+    entityExists(entityId: EntityId): boolean;
+    /**
+     * 创建组件掩码
+     *
+     * @param componentIds 组件ID数组
+     * @returns 组件掩码
+     */
+    createComponentMask(componentIds: number[]): ComponentMask;
+    /**
+     * 检查掩码是否包含组件
+     *
+     * @param mask 组件掩码
+     * @param componentId 组件ID
+     * @returns 是否包含
+     */
+    maskContainsComponent(mask: ComponentMask, componentId: number): boolean;
+    /**
+     * 获取性能统计信息
+     *
+     * @returns 性能统计
+     */
+    getPerformanceStats(): PerformanceStats;
+    /**
+     * 清空所有数据
+     */
+    clear(): void;
+    /**
+     * 是否使用WASM实现
+     *
+     * @returns 是否使用WASM
+     */
+    isUsingWasm(): boolean;
+    /**
+     * 是否已初始化
+     *
+     * @returns 是否已初始化
+     */
+    isInitialized(): boolean;
+    /**
+     * 确保已初始化
+     */
+    private ensureInitialized;
+    /**
+     * 清理资源
+     */
+    cleanup(): void;
+}
+/**
+ * 全局ECS核心实例
+ *
+ * 提供单例模式的ECS核心，确保整个应用使用同一个实例
+ */
+export declare const ecsCore: WasmEcsCore;
+/**
+ * 初始化ECS引擎
+ *
+ * 便捷的初始化函数，推荐在应用启动时调用
+ *
+ * @param silent 是否静默模式
+ * @returns 初始化是否成功
+ *
+ * @example
+ * ```typescript
+ * import { initializeEcs } from 'ecs-framework';
+ *
+ * async function main() {
+ *     // 使用默认配置（JavaScript实现）
+ *     await initializeEcs();
+ *
+ *     // 或者自定义配置
+ *     await initializeEcs({
+ *         enabled: false,  // 禁用WASM
+ *         silent: true     // 静默模式
+ *     });
+ * }
+ * ```
+ */
+export declare function initializeEcs(silent?: boolean): Promise<boolean>;
+/**
+ * 快速查询工具函数
+ *
+ * 为常见查询操作提供便捷的API
+ */
+export declare const Query: {
+    /**
+     * 查询拥有指定组件的所有实体
+     */
+    withComponent: (componentId: number, maxResults?: number) => QueryResult;
+    /**
+     * 查询拥有多个组件的实体
+     */
+    withComponents: (componentIds: number[], maxResults?: number) => QueryResult;
+    /**
+     * 查询拥有某些组件但不拥有其他组件的实体
+     */
+    withExclusion: (includeIds: number[], excludeIds: number[], maxResults?: number) => QueryResult;
+};
+//# sourceMappingURL=WasmCore.d.ts.map

package/bin/Utils/WasmCore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WasmCore.d.ts","sourceRoot":"","sources":["../../src/Utils/WasmCore.ts"],"names":[],"mappings":"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"}