@esengine/ecs-framework 2.7.1 → 2.11.1

package/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @esengine/ecs-framework v2.7.1
+ * @esengine/ecs-framework v2.11.1
  * TypeScript definitions
  */
 /**
@@ -5355,6 +5355,114 @@ declare class IncrementalSerializer {
     static resetVersion(): void;
 }
 
+/**
+ * 轻量级实体句柄
+ *
+ * 使用数值表示实体，包含索引和代数信息。
+ * 28位索引 + 20位代数 = 48位，在 JavaScript 安全整数范围内。
+ *
+ * Lightweight entity handle.
+ * Uses numeric value to represent entity with index and generation.
+ * 28-bit index + 20-bit generation = 48-bit, within JavaScript safe integer range.
+ *
+ * @example
+ * ```typescript
+ * const handle = makeHandle(42, 1);
+ * console.log(indexOf(handle)); // 42
+ * console.log(genOf(handle));   // 1
+ * console.log(isValidHandle(handle)); // true
+ * ```
+ */
+/**
+ * 实体句柄类型
+ *
+ * 使用 branded type 提供类型安全。
+ *
+ * Entity handle type.
+ * Uses branded type for type safety.
+ */
+type EntityHandle = number & {
+    readonly __brand: 'EntityHandle';
+};
+/**
+ * 索引位数 | Index bits
+ */
+declare const INDEX_BITS = 28;
+/**
+ * 代数位数 | Generation bits
+ */
+declare const GEN_BITS = 20;
+/**
+ * 索引掩码 | Index mask
+ */
+declare const INDEX_MASK: number;
+/**
+ * 代数掩码 | Generation mask
+ */
+declare const GEN_MASK: number;
+/**
+ * 最大实体数量 | Maximum entity count
+ */
+declare const MAX_ENTITIES: number;
+/**
+ * 最大代数值 | Maximum generation value
+ */
+declare const MAX_GENERATION: number;
+/**
+ * 空句柄常量 | Null handle constant
+ */
+declare const NULL_HANDLE: EntityHandle;
+/**
+ * 创建实体句柄
+ * Create entity handle
+ *
+ * @param index 实体索引 | Entity index
+ * @param generation 实体代数 | Entity generation
+ * @returns 实体句柄 | Entity handle
+ */
+declare function makeHandle(index: number, generation: number): EntityHandle;
+/**
+ * 从句柄提取索引
+ * Extract index from handle
+ *
+ * @param handle 实体句柄 | Entity handle
+ * @returns 实体索引 | Entity index
+ */
+declare function indexOf(handle: EntityHandle): number;
+/**
+ * 从句柄提取代数
+ * Extract generation from handle
+ *
+ * @param handle 实体句柄 | Entity handle
+ * @returns 实体代数 | Entity generation
+ */
+declare function genOf(handle: EntityHandle): number;
+/**
+ * 检查句柄是否有效（非空）
+ * Check if handle is valid (non-null)
+ *
+ * @param handle 实体句柄 | Entity handle
+ * @returns 是否有效 | Whether valid
+ */
+declare function isValidHandle(handle: EntityHandle): boolean;
+/**
+ * 比较两个句柄是否相等
+ * Compare two handles for equality
+ *
+ * @param a 第一个句柄 | First handle
+ * @param b 第二个句柄 | Second handle
+ * @returns 是否相等 | Whether equal
+ */
+declare function handleEquals(a: EntityHandle, b: EntityHandle): boolean;
+/**
+ * 将句柄转换为字符串（用于调试）
+ * Convert handle to string (for debugging)
+ *
+ * @param handle 实体句柄 | Entity handle
+ * @returns 字符串表示 | String representation
+ */
+declare function handleToString(handle: EntityHandle): string;
+
 /**
  * 场景接口定义
  *
@@ -5557,6 +5665,19 @@ type IScene = {
      * 根据ID查找实体
      */
     findEntityById(id: number): Entity | null;
+    /**
+     * 释放实体句柄
+     *
+     * 从句柄管理器中销毁句柄并清理映射关系。
+     * 当实体被销毁时调用此方法。
+     *
+     * Release entity handle.
+     * Destroys the handle in the handle manager and cleans up the mapping.
+     * Called when an entity is destroyed.
+     *
+     * @param handle 实体句柄 | Entity handle
+     */
+    releaseEntityHandle(handle: EntityHandle): void;
     /**
      * 根据名称查找实体
      */
@@ -5824,114 +5945,6 @@ declare class ReferenceTracker {
     private _findRecord;
 }
 
-/**
- * 轻量级实体句柄
- *
- * 使用数值表示实体，包含索引和代数信息。
- * 28位索引 + 20位代数 = 48位，在 JavaScript 安全整数范围内。
- *
- * Lightweight entity handle.
- * Uses numeric value to represent entity with index and generation.
- * 28-bit index + 20-bit generation = 48-bit, within JavaScript safe integer range.
- *
- * @example
- * ```typescript
- * const handle = makeHandle(42, 1);
- * console.log(indexOf(handle)); // 42
- * console.log(genOf(handle));   // 1
- * console.log(isValidHandle(handle)); // true
- * ```
- */
-/**
- * 实体句柄类型
- *
- * 使用 branded type 提供类型安全。
- *
- * Entity handle type.
- * Uses branded type for type safety.
- */
-type EntityHandle = number & {
-    readonly __brand: 'EntityHandle';
-};
-/**
- * 索引位数 | Index bits
- */
-declare const INDEX_BITS = 28;
-/**
- * 代数位数 | Generation bits
- */
-declare const GEN_BITS = 20;
-/**
- * 索引掩码 | Index mask
- */
-declare const INDEX_MASK: number;
-/**
- * 代数掩码 | Generation mask
- */
-declare const GEN_MASK: number;
-/**
- * 最大实体数量 | Maximum entity count
- */
-declare const MAX_ENTITIES: number;
-/**
- * 最大代数值 | Maximum generation value
- */
-declare const MAX_GENERATION: number;
-/**
- * 空句柄常量 | Null handle constant
- */
-declare const NULL_HANDLE: EntityHandle;
-/**
- * 创建实体句柄
- * Create entity handle
- *
- * @param index 实体索引 | Entity index
- * @param generation 实体代数 | Entity generation
- * @returns 实体句柄 | Entity handle
- */
-declare function makeHandle(index: number, generation: number): EntityHandle;
-/**
- * 从句柄提取索引
- * Extract index from handle
- *
- * @param handle 实体句柄 | Entity handle
- * @returns 实体索引 | Entity index
- */
-declare function indexOf(handle: EntityHandle): number;
-/**
- * 从句柄提取代数
- * Extract generation from handle
- *
- * @param handle 实体句柄 | Entity handle
- * @returns 实体代数 | Entity generation
- */
-declare function genOf(handle: EntityHandle): number;
-/**
- * 检查句柄是否有效（非空）
- * Check if handle is valid (non-null)
- *
- * @param handle 实体句柄 | Entity handle
- * @returns 是否有效 | Whether valid
- */
-declare function isValidHandle(handle: EntityHandle): boolean;
-/**
- * 比较两个句柄是否相等
- * Compare two handles for equality
- *
- * @param a 第一个句柄 | First handle
- * @param b 第二个句柄 | Second handle
- * @returns 是否相等 | Whether equal
- */
-declare function handleEquals(a: EntityHandle, b: EntityHandle): boolean;
-/**
- * 将句柄转换为字符串（用于调试）
- * Convert handle to string (for debugging)
- *
- * @param handle 实体句柄 | Entity handle
- * @returns 字符串表示 | String representation
- */
-declare function handleToString(handle: EntityHandle): string;
-
 /**
  * 实体句柄管理器
  *
@@ -6571,6 +6584,19 @@ declare class Scene implements IScene {
      * @returns 实体实例或 null | Entity instance or null
      */
     findEntityByHandle(handle: EntityHandle): Entity | null;
+    /**
+     * 释放实体句柄
+     *
+     * 从句柄管理器中销毁句柄并清理映射关系。
+     * 当实体被销毁时调用此方法。
+     *
+     * Release entity handle.
+     * Destroys the handle in the handle manager and cleans up the mapping.
+     * Called when an entity is destroyed.
+     *
+     * @param handle 实体句柄 | Entity handle
+     */
+    releaseEntityHandle(handle: EntityHandle): void;
     /**
      * 根据标签查找实体
      * @param tag 实体标签