@spatialwalk/avatarkit 1.0.0-beta.67 → 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.67",
+  "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",

package/vite.js

@@ -1,4 +1,4 @@
-import { copyFileSync, existsSync, writeFileSync, readdirSync } from 'node:fs';
+import { copyFileSync, existsSync, writeFileSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 /**
  * Vite plugin for @spatialwalk/avatarkit
@@ -37,43 +37,59 @@ export function avatarkitVitePlugin() {
         closeBundle() {
             if (!rootDir)
                 return;
-            // 查找 node_modules 中的 WASM 文件
-            const wasmSource = join(rootDir, 'node_modules/@spatialwalk/avatarkit/dist/avatar_core_wasm.wasm');
-            // 查找 node_modules 中的 WASM JS glue 文件
-            // 注意：Vite 可能会给 JS 文件加 hash，所以我们需要查找所有可能的文件
-            const wasmJsSourcePattern = join(rootDir, 'node_modules/@spatialwalk/avatarkit/dist');
-            // 目标路径 - 根据实际使用情况，WASM 文件应该在 assets 目录
-            // 因为 Vite 通常会把资源放在 assets 目录，而 SDK 代码使用相对路径导入
-            const wasmDest = join(rootDir, 'dist/assets/avatar_core_wasm.wasm');
+            const wasmSourceDir = join(rootDir, 'node_modules/@spatialwalk/avatarkit/dist');
+            // 先查找并读取 JS glue 文件，提取它引用的 WASM 文件名
+            let wasmFileName = null;
+            if (existsSync(wasmSourceDir)) {
+                const files = readdirSync(wasmSourceDir);
+                const wasmJsFile = files.find((f) => f.startsWith('avatar_core_wasm') && f.endsWith('.js'));
+                if (wasmJsFile) {
+                    const wasmJsSource = join(wasmSourceDir, wasmJsFile);
+                    try {
+                        const jsContent = readFileSync(wasmJsSource, 'utf-8');
+                        // 从 JS 文件中提取 WASM 文件名
+                        // 匹配 avatar_core_wasm-{hash}.wasm 或 avatar_core_wasm.wasm
+                        // 使用更精确的正则，匹配带引号或不带引号的情况
+                        const wasmMatch = jsContent.match(/["'`]?avatar_core_wasm[-\w]*\.wasm["'`]?/g);
+                        if (wasmMatch && wasmMatch.length > 0) {
+                            // 取第一个匹配，去掉引号
+                            wasmFileName = wasmMatch[0].replace(/["'`]/g, '');
+                        }
+                    }
+                    catch (error) {
+                        console.warn('⚠️ [avatarkit] Could not read JS glue file:', error);
+                    }
+                }
+            }
+            // 如果从 JS 文件中找到了 WASM 文件名，使用它；否则回退到默认名称
+            const targetWasmName = wasmFileName || 'avatar_core_wasm.wasm';
+            const wasmSource = join(wasmSourceDir, targetWasmName);
+            const wasmDest = join(rootDir, `dist/assets/${targetWasmName}`);
             const wasmJsDest = join(rootDir, 'dist/assets/avatar_core_wasm.js');
             const headersDest = join(rootDir, 'dist/_headers');
             // 复制 WASM 文件
             if (existsSync(wasmSource)) {
                 copyFileSync(wasmSource, wasmDest);
-                console.log('✅ [avatarkit] Copied WASM file to dist/assets/avatar_core_wasm.wasm');
+                console.log(`✅ [avatarkit] Copied WASM file to dist/assets/${targetWasmName}`);
             }
             else {
-                console.warn('⚠️ [avatarkit] WASM file not found at:', wasmSource);
-            }
-            // 尝试查找并复制 WASM JS glue 文件
-            // 由于 Vite 可能会给文件加 hash，我们尝试查找匹配的文件
-            try {
-                if (existsSync(wasmJsSourcePattern)) {
-                    const files = readdirSync(wasmJsSourcePattern);
-                    const wasmJsFile = files.find((f) => f.startsWith('avatar_core_wasm') && f.endsWith('.js'));
-                    if (wasmJsFile) {
-                        const wasmJsSource = join(wasmJsSourcePattern, wasmJsFile);
-                        copyFileSync(wasmJsSource, wasmJsDest);
-                        console.log(`✅ [avatarkit] Copied WASM JS file to dist/assets/avatar_core_wasm.js (from ${wasmJsFile})`);
-                    }
-                    else {
-                        console.log('ℹ️ [avatarkit] WASM JS file not found (may be handled by Vite):', wasmJsSourcePattern);
-                    }
+                console.warn(`⚠️ [avatarkit] WASM file not found: ${wasmSource}`);
+                if (wasmFileName) {
+                    console.warn(`   Expected file: ${targetWasmName} (extracted from JS glue file)`);
                 }
             }
-            catch (error) {
-                // 如果读取目录失败，不报错，因为 Vite 可能已经处理了 JS 文件
-                console.log('ℹ️ [avatarkit] Could not find WASM JS file (may be handled by Vite)');
+            // 复制 WASM JS glue 文件
+            if (existsSync(wasmSourceDir)) {
+                const files = readdirSync(wasmSourceDir);
+                const wasmJsFile = files.find((f) => f.startsWith('avatar_core_wasm') && f.endsWith('.js'));
+                if (wasmJsFile) {
+                    const wasmJsSource = join(wasmSourceDir, wasmJsFile);
+                    copyFileSync(wasmJsSource, wasmJsDest);
+                    console.log(`✅ [avatarkit] Copied WASM JS file to dist/assets/avatar_core_wasm.js (from ${wasmJsFile})`);
+                }
+                else {
+                    console.log('ℹ️ [avatarkit] WASM JS file not found (may be handled by Vite):', wasmSourceDir);
+                }
             }
             // 生成 _headers 文件（用于 Cloudflare Pages 等平台）
             const headersContent = '/*.wasm\n  Content-Type: application/wasm\n';