@spatialwalk/avatarkit 1.0.0-beta.68 → 1.0.0-beta.69

package/dist/vite.d.ts

@@ -1,4 +1,19 @@
 import { Plugin } from 'vite';
-
+/**
+ * Vite plugin for @spatialwalk/avatarkit
+ * Automatically handles WASM file configuration for development and production builds
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'vite'
+ * import { avatarkitVitePlugin } from '@spatialwalk/avatarkit/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     avatarkitVitePlugin()
+ *   ]
+ * })
+ * ```
+ */
 export declare function avatarkitVitePlugin(): Plugin;
 export default avatarkitVitePlugin;

package/dist/wasm/avatarCoreAdapter.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Avatar Core WASM 适配器
+ *
+ * 完全替换 FlameComplete3DGSManager，提供 avatar_core_wasm 的完整功能
+ * 包括牙齿细分、眼部追踪等高级特性
+ */
 export interface WasmModuleConfig {
     baseUrl?: string;
     [key: string]: unknown;
@@ -59,45 +65,184 @@ export declare class AvatarCoreAdapter {
     private flameInfo?;
     private characterInfo?;
     constructor(options?: AvatarCoreOptions);
+    /**
+     * 加载 WASM 模块并设置 API
+     * 每次都创建全新的 WASM 实例，确保 C++ 内存是干净的
+     *
+     * 注意：这里使用动态 import() 导入 WASM 模块。
+     * Vite 在构建时会自动为 WASM 文件和 JS glue 代码添加 hash（如 avatar_core_wasm-CxWuw7eS.wasm），
+     * 确保浏览器缓存与版本一致，不会有缓存问题。
+     *
+     * Hash 的作用机制：
+     * - WASM 文件内容变化 → hash 自动变化 → URL 变化 → 浏览器拉取新版本
+     * - WASM 文件内容不变 → hash 保持不变 → URL 不变 → 浏览器使用缓存
+     * - Emscripten 生成的 JS 内部会使用 hard-coded 的 hash 路径加载 .wasm 文件
+     */
     loadWASMModule(): Promise<void>;
+    /**
+     * 验证 WASM 模块功能
+     */
     private validateWASMModule;
+    /**
+     * 初始化内存视图
+     */
     private initializeMemoryViews;
+    /**
+     * 设置 C API 函数包装
+     */
     private setupCAPIFunctions;
+    /**
+     * 读取当前动画帧的 FlameParams（用于过渡或调试）
+     */
+    /**
+     * Get current frame parameters
+     * @param frameIndex Frame index
+     * @param characterId Optional character ID for multi-character support
+     */
     getCurrentFrameParams(frameIndex?: number, characterId?: string): Promise<FlameParams>;
+    /**
+     * 初始化 Avatar Core 核心
+     */
     private initializeAvatarCore;
+    /**
+     * 加载模板资源（从预加载的 ArrayBuffers）
+     */
     loadTemplateResourcesFromBuffers(templateResources: Record<string, ArrayBuffer>): Promise<boolean>;
+    /**
+     * 加载角色数据（从预加载的 ArrayBuffers）
+     */
+    /**
+     * Load character from buffers and return handle
+     * @param shapeBuffer Shape data buffer
+     * @param pointCloudBuffer Point cloud data buffer
+     * @param characterId Optional character ID for multi-character support
+     * @returns Character handle
+     */
     loadCharacterFromBuffers(shapeBuffer: ArrayBuffer, pointCloudBuffer: ArrayBuffer, characterId?: string): Promise<number>;
     private loadAnimationFromData;
+    /**
+     * Load animation from ArrayBuffer (for CDN-based dynamic loading)
+     * @param animData Animation data buffer
+     * @param characterId Optional character ID for multi-character support
+     * @returns Animation handle
+     */
     loadAnimationFromBuffer(animData: ArrayBuffer, characterId?: string): Promise<number>;
     switchAnimationFile(animationFile: string): Promise<number>;
+    /**
+     * 获取动画总帧数
+     * @param animationHandle Optional animation handle (for multi-character support)
+     */
     getAnimationTotalFrames(animationHandle?: number): Promise<number>;
+    /**
+     * 从动画中获取指定帧的参数
+     * @param frameIndex Frame index
+     * @param characterId Optional character ID for multi-character support
+     */
     getAnimationFrameParams(frameIndex?: number, characterId?: string): Promise<number>;
+    /**
+     * 设置眼部追踪配置（对齐 app 实现）
+     * @param config Eye tracking configuration
+     * @param characterId Optional character ID for multi-character support
+     */
     setEyeTrackingConfig(config: {
         enabled: boolean;
         auto_eyelid_adjustment?: boolean;
         eyelid_threshold?: number;
     }, characterId?: string): Promise<boolean>;
+    /**
+     * 设置眼部追踪目标（高级功能）
+     * @param x Target X coordinate
+     * @param y Target Y coordinate
+     * @param z Target Z coordinate
+     * @param characterId Optional character ID for multi-character support
+     */
     setGazeTarget(x: number, y: number, z: number, characterId?: string): Promise<boolean>;
+    /**
+     * 重置眼部追踪
+     */
     resetEyeTracking(): Promise<boolean>;
+    /**
+     * 查询 FLAME 模型信息
+     */
     private queryFlameInfo;
+    /**
+     * 查询角色信息
+     */
     private queryCharacterInfo;
+    /**
+     * 检查错误码并抛出异常
+     */
     private checkError;
+    /**
+     * 更新进度回调
+     */
     private updateProgress;
+    /**
+     * 获取性能指标
+     */
     getPerformanceMetrics(): PerformanceMetrics & {
         flameInfo?: FlameInfo;
         characterInfo?: CharacterInfo;
         version?: string;
     };
+    /**
+     * 获取角色的点云数量
+     * @param characterHandle 角色 handle（可选，默认使用当前角色）
+     * @returns 点云数量，如果角色未加载则返回 null
+     */
     getPointCount(characterHandle?: number): number | null;
+    /**
+     * 释放当前角色和动画资源（但保留 core）
+     */
+    /**
+     * Remove a specific character by handle
+     * @param characterHandle Character handle to remove
+     * @param characterId Optional character ID for cleanup
+     */
     removeCharacter(characterHandle: number, characterId?: string): void;
+    /**
+     * Release current character (legacy method, kept for backward compatibility)
+     * @deprecated Use removeCharacter() instead for multi-character support
+     */
     releaseCurrentCharacter(): void;
+    /**
+     * 释放所有资源（包括 core）
+     */
     release(): void;
+    /**
+     * 兼容性接口：提供与 FlameComplete3DGSManager 相同的接口
+     */
     loadFlameModel(_modelData: any): Promise<boolean>;
     load3DGSData(_original3DGSPoints: any, _binding: any, _flameFaces: any): Promise<boolean>;
+    /**
+     * 计算帧并返回 GPU 友好的 flat 格式（零拷贝，协方差预计算）
+     * 🚀 性能优化版本：
+     * - C++ 预计算协方差矩阵
+     * - 零拷贝直接访问 WASM 内存http://localhost:3000/us/
+     * - 直接输出 GPU 格式 [pos3, color4, cov6]
+     */
+    /**
+     * Compute complete frame from animation
+     * @param params Frame parameters
+     * @param characterHandle Optional character handle (for multi-character support)
+     */
     computeCompleteFrameFlat(params?: {
         frameIndex?: number;
     }, characterHandle?: number): Promise<Float32Array | null>;
+    /**
+     * 计算帧并返回 GPU 友好的 flat 格式（从 FLAME 参数）
+     * 🔑 用于 Realtime: 接受自定义 FLAME 参数并计算 Splat
+     */
+    /**
+     * Compute frame from Flame parameters
+     * @param flameParams Flame parameters
+     * @param characterHandle Optional character handle (for multi-character support)
+     */
     computeFrameFlatFromParams(flameParams: FlameParams, characterHandle?: number): Promise<Float32Array | null>;
+    /**
+     * 获取 WASM 内存使用情况（MB）
+     * @returns WASM 内存使用量（MB），如果模块未加载则返回 null
+     */
     getWASMMemoryMB(): number | null;
 }
 export {};

package/dist/wasm/avatarCoreMemory.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Avatar Core WASM 内存管理工具
+ *
+ * 提供高效的内存分配、数据传递和零拷贝访问功能
+ * 专门为 avatar_core_wasm 优化
+ */
 interface WASMModule {
     _malloc: (size: number) => number;
     _free: (ptr: number) => void;
@@ -41,13 +47,26 @@ export declare class AvatarCoreMemoryManager {
     private allocatedPointers;
     private structPointers;
     constructor(wasmModule: WASMModule);
+    /**
+     * 分配 WASM 内存并复制数据 - 纯 API 方式
+     */
     allocateAndCopy(arrayBuffer: ArrayBuffer): MemoryAllocation;
+    /**
+     * 创建 AvatarTemplateConfig 结构体
+     */
     createTemplateConfig(resources: TemplateResources): number;
+    /**
+     * 创建 AvatarCharacterData 结构体 - 新版 Emscripten 方式
+     */
     createCharacterData(shapeBuffer: ArrayBuffer, plyBuffer: ArrayBuffer, characterId?: string): {
         dataPtr: number;
         shapePtr: number;
         plyPtr: number;
     };
+    /**
+     * 读取 AvatarFlameParams 结构体数据
+     * Used to extract current animation frame parameters from WASM memory
+     */
     readFlameParams(paramsPtr: number): {
         shape_params: number[];
         expr_params: number[];
@@ -59,6 +78,9 @@ export declare class AvatarCoreMemoryManager {
         eyelid: number[];
         has_eyelid: boolean;
     };
+    /**
+     * 创建 AvatarFlameParams 结构体 - 新版 Emscripten 方式
+     */
     createFlameParams(params: {
         shape_params?: number[];
         expr_params?: number[];
@@ -70,7 +92,25 @@ export declare class AvatarCoreMemoryManager {
         eyelid?: number[];
         has_eyelid?: boolean;
     }): number;
+    /**
+     * 读取 AvatarSplatPointFlatArray 结构体数据（预计算协方差）
+     *
+     * 结构体布局:
+     * - AvatarSplatPointFlat* points (0-3, 32位指针)
+     * - uint32_t point_count (4-7)
+     * - float compute_time_ms (8-11)
+     *
+     * 每个点布局 (52 bytes):
+     * - position[3]   (12 bytes)
+     * - color[4]      (16 bytes, RGBA)
+     * - covariance[6] (24 bytes, 预计算好的协方差矩阵上三角)
+     *
+     * ⚠️ 使用 getValue 逐个读取，避免动态内存的 HEAPF32 detachment 问题
+     */
     readSplatPointFlatArray(arrayPtr: number): Float32Array | null;
+    /**
+     * 读取AvatarMeshData结构体数据
+     */
     readMeshData(outputPtr: number): {
         vertices: Float32Array;
         vertexCount: number;
@@ -80,9 +120,21 @@ export declare class AvatarCoreMemoryManager {
         landmarkCount: number;
         computeTime: number;
     };
+    /**
+     * 释放指定指针的内存
+     */
     free(ptr: number): void;
+    /**
+     * 释放结构体内存
+     */
     freeStruct(name: string): void;
+    /**
+     * 清理所有分配的内存
+     */
     cleanup(): void;
+    /**
+     * 获取内存使用统计
+     */
     getMemoryStats(): {
         allocatedPointers: number;
         structPointers: number;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@spatialwalk/avatarkit",
   "type": "module",
-  "version": "1.0.0-beta.68",
+  "version": "1.0.0-beta.69",
   "packageManager": "pnpm@10.18.2",
-  "description": "SPAvatar SDK - 3D Gaussian Splatting Avatar Rendering SDK",
-  "author": "SPAvatar Team",
+  "description": "AvatarKit SDK - 3D Gaussian Splatting Avatar Rendering SDK",
+  "author": "AvatarKit Team",
   "license": "MIT",
   "keywords": [
     "avatar",