@chocozhang/three-model-render 1.0.3 → 1.0.4

package/dist/interaction/index.mjs

@@ -2,28 +2,38 @@ import * as THREE from 'three';
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js';
 
 /**
- * 创建模型点击高亮工具（OutlinePass 版）- 优化版
+ * @file clickHandler.ts
+ * @description
+ * Tool for handling model clicks and highlighting (OutlinePass version).
  *
- * ✨ 功能增强：
- * - 使用 AbortController 统一管理事件生命周期
- * - 支持防抖处理避免频繁触发
- * - 可自定义 Raycaster 参数
- * - 根据相机距离动态调整描边厚度
+ * @best-practice
+ * - Use `createModelClickHandler` to setup interaction.
+ * - Handles debouncing and click threshold automatically.
+ * - Cleanup using the returned dispose function.
+ */
+/**
+ * Create Model Click Highlight Tool (OutlinePass Version) - Optimized
+ *
+ * Features:
+ * - Uses AbortController to unify event lifecycle management
+ * - Supports debounce to avoid frequent triggering
+ * - Customizable Raycaster parameters
+ * - Dynamically adjusts outline thickness based on camera distance
  *
- * @param camera 相机
- * @param scene 场景
- * @param renderer 渲染器
- * @param outlinePass 已初始化的 OutlinePass
- * @param onClick 点击回调
- * @param options 可选配置
- * @returns dispose 函数，用于清理事件和资源
+ * @param camera Camera
+ * @param scene Scene
+ * @param renderer Renderer
+ * @param outlinePass Initialized OutlinePass
+ * @param onClick Click callback
+ * @param options Optional configuration
+ * @returns Dispose function, used to clean up events and resources
  */
 function createModelClickHandler(camera, scene, renderer, outlinePass, onClick, options = {}) {
-    // 配置项
+    // Configuration
     const { clickThreshold = 3, debounceDelay = 0, raycasterParams = {}, enableDynamicThickness = true, minThickness = 1, maxThickness = 10 } = options;
     const raycaster = new THREE.Raycaster();
     const mouse = new THREE.Vector2();
-    // 应用 raycaster 自定义参数
+    // Apply Raycaster custom parameters
     if (raycasterParams.near !== undefined)
         raycaster.near = raycasterParams.near;
     if (raycasterParams.far !== undefined)
@@ -40,25 +50,25 @@ function createModelClickHandler(camera, scene, renderer, outlinePass, onClick,
     let startY = 0;
     let selectedObject = null;
     let debounceTimer = null;
-    // 使用 AbortController 统一管理事件
+    // Use AbortController to manage events uniformly
     const abortController = new AbortController();
     const signal = abortController.signal;
-    /** 恢复对象高亮（清空 OutlinePass.selectedObjects） */
+    /** Restore object highlight (Clear OutlinePass.selectedObjects) */
     function restoreObject() {
         outlinePass.selectedObjects = [];
     }
-    /** 鼠标按下记录位置 */
+    /** Record mouse down position */
     function handleMouseDown(event) {
         startX = event.clientX;
         startY = event.clientY;
     }
-    /** 鼠标抬起判定点击或拖动（带防抖） */
+    /** Mouse up determines click or drag (with debounce) */
     function handleMouseUp(event) {
         const dx = Math.abs(event.clientX - startX);
         const dy = Math.abs(event.clientY - startY);
         if (dx > clickThreshold || dy > clickThreshold)
-            return; // 拖动不触发点击
-        // 防抖处理
+            return; // Drag does not trigger click
+        // Debounce processing
         if (debounceDelay > 0) {
             if (debounceTimer !== null) {
                 clearTimeout(debounceTimer);
@@ -72,7 +82,7 @@ function createModelClickHandler(camera, scene, renderer, outlinePass, onClick,
             processClick(event);
         }
     }
-    /** 实际的点击处理逻辑 */
+    /** Actual click processing logic */
     function processClick(event) {
         const rect = renderer.domElement.getBoundingClientRect();
         mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
@@ -81,55 +91,64 @@ function createModelClickHandler(camera, scene, renderer, outlinePass, onClick,
         const intersects = raycaster.intersectObjects(scene.children, true);
         if (intersects.length > 0) {
             let object = intersects[0].object;
-            // 点击不同模型，先清除之前高亮
+            // Click different model, clear previous highlight first
             if (selectedObject && selectedObject !== object)
                 restoreObject();
             selectedObject = object;
-            // highlightObject(selectedObject); // 可选：是否自动高亮
+            // highlightObject(selectedObject); // Optional: whether to auto highlight
             onClick(selectedObject, {
-                name: selectedObject.name || '未命名模型',
+                name: selectedObject.name || 'Unnamed Model',
                 position: selectedObject.getWorldPosition(new THREE.Vector3()),
                 uuid: selectedObject.uuid
             });
         }
         else {
-            // 点击空白 → 清除高亮
+            // Click blank -> Clear highlight
             if (selectedObject)
                 restoreObject();
             selectedObject = null;
             onClick(null);
         }
     }
-    // 使用 AbortController 的 signal 注册事件
+    // Register events using signal from AbortController
     renderer.domElement.addEventListener('mousedown', handleMouseDown, { signal });
     renderer.domElement.addEventListener('mouseup', handleMouseUp, { signal });
-    /** 销毁函数：解绑事件并清除高亮 */
+    /** Dispose function: Unbind events and clear highlight */
     return () => {
-        // 清理防抖定时器
+        // Clear debounce timer
         if (debounceTimer !== null) {
             clearTimeout(debounceTimer);
             debounceTimer = null;
         }
-        // 一次性解绑所有事件
+        // Unbind all events at once
         abortController.abort();
-        // 清除高亮
+        // Clear highlight
         restoreObject();
-        // 清空引用
+        // Clear reference
         selectedObject = null;
     };
 }
 
-// src/utils/ArrowGuide.ts
 /**
- * ArrowGuide - 优化版
- * 箭头引导效果工具，支持高亮模型并淡化其他对象
+ * @file arrowGuide.ts
+ * @description
+ * Arrow guide effect tool, supports highlighting models and fading other objects.
+ *
+ * @best-practice
+ * - Use `highlight` to focus on specific models.
+ * - Automatically manages materials and memory using WeakMap.
+ * - Call `dispose` when component unmounts.
+ */
+/**
+ * ArrowGuide - Optimized Version
+ * Arrow guide effect tool, supports highlighting models and fading other objects.
  *
- * ✨ 优化内容：
- * - 使用 WeakMap 自动回收材质，避免内存泄漏
- * - 使用 AbortController 管理事件生命周期
- * - 添加材质复用机制，减少重复创建
- * - 改进 dispose 逻辑，确保完全释放资源
- * - 添加错误处理和边界检查
+ * Features:
+ * - Uses WeakMap for automatic material recycling, preventing memory leaks
+ * - Uses AbortController to manage event lifecycle
+ * - Adds material reuse mechanism to reuse materials
+ * - Improved dispose logic ensuring complete resource release
+ * - Adds error handling and boundary checks
  */
 class ArrowGuide {
     constructor(renderer, camera, scene, options) {
@@ -144,12 +163,12 @@ class ArrowGuide {
         this.clickThreshold = 10;
         this.raycaster = new THREE.Raycaster();
         this.mouse = new THREE.Vector2();
-        // ✨ 使用 WeakMap 自动回收材质（GC 友好）
+        // Use WeakMap for automatic material recycling (GC friendly)
         this.originalMaterials = new WeakMap();
         this.fadedMaterials = new WeakMap();
-        // ✨ AbortController 用于事件管理
+        // AbortController for event management
         this.abortController = null;
-        // 配置：非高亮透明度和亮度
+        // Config: Non-highlight opacity and brightness
         this.fadeOpacity = 0.5;
         this.fadeBrightness = 0.1;
         this.clickThreshold = (_a = options === null || options === void 0 ? void 0 : options.clickThreshold) !== null && _a !== void 0 ? _a : 10;
@@ -159,30 +178,30 @@ class ArrowGuide {
         this.abortController = new AbortController();
         this.initEvents();
     }
-    // —— 工具：缓存原材质（仅首次）
+    // Tool: Cache original material (first time only)
     cacheOriginalMaterial(mesh) {
         if (!this.originalMaterials.has(mesh)) {
             this.originalMaterials.set(mesh, mesh.material);
         }
     }
-    // —— 工具：为某个材质克隆一个"半透明版本"，保留所有贴图与参数
+    // Tool: Clone a "translucent version" for a material, preserving all maps and parameters
     makeFadedClone(mat) {
         const clone = mat.clone();
         const c = clone;
-        // 只改透明相关参数，不改 map / normalMap / roughnessMap 等细节
+        // Only modify transparency parameters, do not modify detail maps like map / normalMap / roughnessMap
         c.transparent = true;
         if (typeof c.opacity === 'number')
             c.opacity = this.fadeOpacity;
         if (c.color && c.color.isColor) {
-            c.color.multiplyScalar(this.fadeBrightness); // 颜色整体变暗
+            c.color.multiplyScalar(this.fadeBrightness); // Darken color overall
         }
-        // 为了让箭头在透明建筑后也能顺畅显示，常用策略：不写深度，仅测试深度
+        // Common strategy for fluid display behind transparent objects: do not write depth, only test depth
         clone.depthWrite = false;
         clone.depthTest = true;
         clone.needsUpdate = true;
         return clone;
     }
-    // —— 工具：为 mesh.material（可能是数组）批量克隆"半透明版本"
+    // Tool: Batch clone "translucent version" for mesh.material (could be array)
     createFadedMaterialFrom(mesh) {
         const orig = mesh.material;
         if (Array.isArray(orig)) {
@@ -191,7 +210,7 @@ class ArrowGuide {
         return this.makeFadedClone(orig);
     }
     /**
-     * 设置箭头 Mesh
+     * Set Arrow Mesh
      */
     setArrowMesh(mesh) {
         this.lxMesh = mesh;
@@ -207,15 +226,15 @@ class ArrowGuide {
             mesh.visible = false;
         }
         catch (error) {
-            console.error('ArrowGuide: 设置箭头材质失败', error);
+            console.error('ArrowGuide: Failed to set arrow material', error);
         }
     }
     /**
-     * 高亮指定模型
+     * Highlight specified models
      */
     highlight(models) {
         if (!models || models.length === 0) {
-            console.warn('ArrowGuide: 高亮模型列表为空');
+            console.warn('ArrowGuide: Highlight model list is empty');
             return;
         }
         this.modelBrightArr = models;
@@ -224,9 +243,9 @@ class ArrowGuide {
             this.lxMesh.visible = true;
         this.applyHighlight();
     }
-    // ✅ 应用高亮效果：非高亮模型保留细节 → 使用"克隆后的半透明材质"
+    // Apply highlight effect: Non-highlighted models preserve details -> use "cloned translucent material"
     applyHighlight() {
-        // ✨ 使用 Set 提升查找性能
+        // Use Set to improve lookup performance
         const keepMeshes = new Set();
         this.modelBrightArr.forEach(obj => {
             obj.traverse(child => {
@@ -238,21 +257,21 @@ class ArrowGuide {
             this.scene.traverse(obj => {
                 if (obj.isMesh) {
                     const mesh = obj;
-                    // 缓存原材质（用于恢复）
+                    // Cache original material (for restoration)
                     this.cacheOriginalMaterial(mesh);
                     if (!keepMeshes.has(mesh)) {
-                        // 非高亮：如果还没给它生成过"半透明克隆材质"，就创建一次
+                        // Non-highlighted: if no "translucent clone material" generated yet, create one
                         if (!this.fadedMaterials.has(mesh)) {
                             const faded = this.createFadedMaterialFrom(mesh);
                             this.fadedMaterials.set(mesh, faded);
                         }
-                        // 替换为克隆材质（保留所有贴图/法线等细节）
+                        // Replace with clone material (preserve all maps/normals details)
                         const fadedMat = this.fadedMaterials.get(mesh);
                         if (fadedMat)
                             mesh.material = fadedMat;
                     }
                     else {
-                        // 高亮对象：确保回到原材质（避免上一次高亮后遗留）
+                        // Highlighted object: ensure return to original material (avoid leftover from previous highlight)
                         const orig = this.originalMaterials.get(mesh);
                         if (orig && mesh.material !== orig) {
                             mesh.material = orig;
@@ -263,16 +282,16 @@ class ArrowGuide {
             });
         }
         catch (error) {
-            console.error('ArrowGuide: 应用高亮失败', error);
+            console.error('ArrowGuide: Failed to apply highlight', error);
         }
     }
-    // ✅ 恢复为原材质 & 释放克隆材质
+    // Restore to original material & dispose clone material
     restore() {
         this.flowActive = false;
         if (this.lxMesh)
             this.lxMesh.visible = false;
         try {
-            // ✨ 收集所有需要释放的材质
+            // Collect all materials to dispose
             const materialsToDispose = [];
             this.scene.traverse(obj => {
                 if (obj.isMesh) {
@@ -282,7 +301,7 @@ class ArrowGuide {
                         mesh.material = orig;
                         mesh.material.needsUpdate = true;
                     }
-                    // ✨ 收集待释放的淡化材质
+                    // Collect faded materials to dispose
                     const faded = this.fadedMaterials.get(mesh);
                     if (faded) {
                         if (Array.isArray(faded)) {
@@ -294,24 +313,24 @@ class ArrowGuide {
                     }
                 }
             });
-            // ✨ 批量释放材质（不触碰贴图资源）
+            // Batch dispose materials (do not touch texture resources)
             materialsToDispose.forEach(mat => {
                 try {
                     mat.dispose();
                 }
                 catch (error) {
-                    console.error('ArrowGuide: 释放材质失败', error);
+                    console.error('ArrowGuide: Failed to dispose material', error);
                 }
             });
-            // ✨ 创建新的 WeakMap（相当于清空）
+            // Create new WeakMap (equivalent to clearing)
             this.fadedMaterials = new WeakMap();
         }
         catch (error) {
-            console.error('ArrowGuide: 恢复材质失败', error);
+            console.error('ArrowGuide: Failed to restore material', error);
         }
     }
     /**
-     * 动画更新（每帧调用）
+     * Animation update (called every frame)
      */
     animate() {
         if (!this.flowActive || !this.lxMesh)
@@ -325,16 +344,16 @@ class ArrowGuide {
             }
         }
         catch (error) {
-            console.error('ArrowGuide: 动画更新失败', error);
+            console.error('ArrowGuide: Animation update failed', error);
         }
     }
     /**
-     * 初始化事件监听器
+     * Initialize event listeners
      */
     initEvents() {
         const dom = this.renderer.domElement;
         const signal = this.abortController.signal;
-        // ✨ 使用 AbortController signal 自动管理事件生命周期
+        // Use AbortController signal to automatically manage event lifecycle
         dom.addEventListener('pointerdown', (e) => {
             this.pointerDownPos.set(e.clientX, e.clientY);
         }, { signal });
@@ -342,7 +361,7 @@ class ArrowGuide {
             const dx = Math.abs(e.clientX - this.pointerDownPos.x);
             const dy = Math.abs(e.clientY - this.pointerDownPos.y);
             if (dx > this.clickThreshold || dy > this.clickThreshold)
-                return; // 拖拽
+                return; // Dragging
             const rect = dom.getBoundingClientRect();
             this.mouse.x = ((e.clientX - rect.left) / rect.width) * 2 - 1;
             this.mouse.y = -((e.clientY - rect.top) / rect.height) * 2 + 1;
@@ -356,21 +375,21 @@ class ArrowGuide {
                 return true;
             });
             if (filtered.length === 0)
-                this.restore(); // 点击空白恢复
+                this.restore(); // Click blank space to restore
         }, { signal });
     }
     /**
-     * 释放所有资源
+     * Dispose all resources
      */
     dispose() {
-        // ✨ 先恢复材质
+        // Restore materials first
         this.restore();
-        // ✨ 使用 AbortController 一次性解绑所有事件
+        // Unbind all events at once using AbortController
         if (this.abortController) {
             this.abortController.abort();
             this.abortController = null;
         }
-        // ✨ 清空引用
+        // Clear references
         this.modelBrightArr = [];
         this.lxMesh = null;
         this.fadedMaterials = new WeakMap();
@@ -379,50 +398,59 @@ class ArrowGuide {
     }
 }
 
-// utils/LiquidFillerGroup.ts
 /**
- * LiquidFillerGroup - 优化版
- * 支持单模型或多模型液位动画、独立颜色控制
+ * @file liquidFiller.ts
+ * @description
+ * Liquid filling effect for single or multiple models using local clipping planes.
  *
- * ✨ 优化内容：
- * - 使用 renderer.domElement 替代 window 事件
- * - 使用 AbortController 管理事件生命周期
- * - 添加错误处理和边界检查
- * - 优化动画管理，避免内存泄漏
- * - 完善资源释放逻辑
+ * @best-practice
+ * - Use `fillTo` to animate liquid level.
+ * - Supports multiple independent liquid levels.
+ * - Call `dispose` to clean up resources and event listeners.
+ */
+/**
+ * LiquidFillerGroup - Optimized
+ * Supports single or multi-model liquid level animation with independent color control.
+ *
+ * Features:
+ * - Uses renderer.domElement instead of window events
+ * - Uses AbortController to manage event lifecycle
+ * - Adds error handling and boundary checks
+ * - Optimized animation management to prevent memory leaks
+ * - Comprehensive resource disposal logic
  */
 class LiquidFillerGroup {
     /**
-     * 构造函数
-     * @param models 单个或多个 THREE.Object3D
-     * @param scene 场景
-     * @param camera 相机
-     * @param renderer 渲染器
-     * @param defaultOptions 默认液体选项
-     * @param clickThreshold 点击阈值，单位像素
+     * Constructor
+     * @param models Single or multiple THREE.Object3D
+     * @param scene Scene
+     * @param camera Camera
+     * @param renderer Renderer
+     * @param defaultOptions Default liquid options
+     * @param clickThreshold Click threshold in pixels
      */
     constructor(models, scene, camera, renderer, defaultOptions, clickThreshold = 10) {
         this.items = [];
         this.raycaster = new THREE.Raycaster();
         this.pointerDownPos = new THREE.Vector2();
         this.clickThreshold = 10;
-        this.abortController = null; // ✨ 事件管理器
-        /** pointerdown 记录位置 */
+        this.abortController = null; // Event manager
+        /** pointerdown record position */
         this.handlePointerDown = (event) => {
             this.pointerDownPos.set(event.clientX, event.clientY);
         };
-        /** pointerup 判断点击空白，恢复原始材质 */
+        /** pointerup check click blank, restore original material */
         this.handlePointerUp = (event) => {
             const dx = event.clientX - this.pointerDownPos.x;
             const dy = event.clientY - this.pointerDownPos.y;
             const distance = Math.sqrt(dx * dx + dy * dy);
             if (distance > this.clickThreshold)
-                return; // 拖拽不触发
-            // ✨ 使用 renderer.domElement 的实际尺寸
+                return; // Do not trigger on drag
+            // Use renderer.domElement actual size
             const rect = this.renderer.domElement.getBoundingClientRect();
             const pointerNDC = new THREE.Vector2(((event.clientX - rect.left) / rect.width) * 2 - 1, -((event.clientY - rect.top) / rect.height) * 2 + 1);
             this.raycaster.setFromCamera(pointerNDC, this.camera);
-            // 点击空白 -> 所有模型恢复
+            // Click blank -> Restore all models
             const intersectsAny = this.items.some(item => this.raycaster.intersectObject(item.model, true).length > 0);
             if (!intersectsAny) {
                 this.restoreAll();
@@ -432,7 +460,7 @@ class LiquidFillerGroup {
         this.camera = camera;
         this.renderer = renderer;
         this.clickThreshold = clickThreshold;
-        // ✨ 创建 AbortController 用于事件管理
+        // Create AbortController for event management
         this.abortController = new AbortController();
         const modelArray = Array.isArray(models) ? models : [models];
         modelArray.forEach(model => {
@@ -443,7 +471,7 @@ class LiquidFillerGroup {
                     opacity: (_b = defaultOptions === null || defaultOptions === void 0 ? void 0 : defaultOptions.opacity) !== null && _b !== void 0 ? _b : 0.6,
                     speed: (_c = defaultOptions === null || defaultOptions === void 0 ? void 0 : defaultOptions.speed) !== null && _c !== void 0 ? _c : 0.05,
                 };
-                // 保存原始材质
+                // Save original materials
                 const originalMaterials = new Map();
                 model.traverse(obj => {
                     if (obj.isMesh) {
@@ -451,12 +479,12 @@ class LiquidFillerGroup {
                         originalMaterials.set(mesh, mesh.material);
                     }
                 });
-                // ✨ 边界检查：确保有材质可以保存
+                // Boundary check: ensure there are materials to save
                 if (originalMaterials.size === 0) {
-                    console.warn('LiquidFillerGroup: 模型没有 Mesh 对象', model);
+                    console.warn('LiquidFillerGroup: Model has no Mesh objects', model);
                     return;
                 }
-                // 应用淡线框材质
+                // Apply faded wireframe material
                 model.traverse(obj => {
                     if (obj.isMesh) {
                         const mesh = obj;
@@ -468,7 +496,7 @@ class LiquidFillerGroup {
                         });
                     }
                 });
-                // 创建液体 Mesh
+                // Create liquid Mesh
                 const geometries = [];
                 model.traverse(obj => {
                     if (obj.isMesh) {
@@ -479,12 +507,12 @@ class LiquidFillerGroup {
                     }
                 });
                 if (geometries.length === 0) {
-                    console.warn('LiquidFillerGroup: 模型没有几何体', model);
+                    console.warn('LiquidFillerGroup: Model has no geometries', model);
                     return;
                 }
                 const mergedGeometry = BufferGeometryUtils.mergeGeometries(geometries, false);
                 if (!mergedGeometry) {
-                    console.error('LiquidFillerGroup: 几何体合并失败', model);
+                    console.error('LiquidFillerGroup: Failed to merge geometries', model);
                     return;
                 }
                 const material = new THREE.MeshPhongMaterial({
@@ -495,7 +523,7 @@ class LiquidFillerGroup {
                 });
                 const liquidMesh = new THREE.Mesh(mergedGeometry, material);
                 this.scene.add(liquidMesh);
-                // 设置 clippingPlane
+                // Set clippingPlane
                 const clipPlane = new THREE.Plane(new THREE.Vector3(0, -1, 0), 0);
                 const mat = liquidMesh.material;
                 mat.clippingPlanes = [clipPlane];
@@ -506,41 +534,41 @@ class LiquidFillerGroup {
                     clipPlane,
                     originalMaterials,
                     options,
-                    animationId: null // ✨ 初始化动画 ID
+                    animationId: null // Initialize animation ID
                 });
             }
             catch (error) {
-                console.error('LiquidFillerGroup: 初始化模型失败', model, error);
+                console.error('LiquidFillerGroup: Failed to initialize model', model, error);
             }
         });
-        // ✨ 使用 renderer.domElement 替代 window，使用 AbortController signal
+        // Use renderer.domElement instead of window, use AbortController signal
         const signal = this.abortController.signal;
         this.renderer.domElement.addEventListener('pointerdown', this.handlePointerDown, { signal });
         this.renderer.domElement.addEventListener('pointerup', this.handlePointerUp, { signal });
     }
     /**
-   * 设置液位
-   * @param models 单个模型或模型数组
-   * @param percent 液位百分比 0~1
-   */
+     * Set liquid level
+     * @param models Single model or array of models
+     * @param percent Liquid level percentage 0~1
+     */
     fillTo(models, percent) {
-        // ✨ 边界检查
+        // Boundary check
         if (percent < 0 || percent > 1) {
-            console.warn('LiquidFillerGroup: percent 必须在 0~1 之间', percent);
+            console.warn('LiquidFillerGroup: percent must be between 0 and 1', percent);
             percent = Math.max(0, Math.min(1, percent));
         }
         const modelArray = Array.isArray(models) ? models : [models];
         modelArray.forEach(model => {
             const item = this.items.find(i => i.model === model);
             if (!item) {
-                console.warn('LiquidFillerGroup: 未找到模型', model);
+                console.warn('LiquidFillerGroup: Model not found', model);
                 return;
             }
             if (!item.liquidMesh) {
-                console.warn('LiquidFillerGroup: liquidMesh 已被释放', model);
+                console.warn('LiquidFillerGroup: liquidMesh already disposed', model);
                 return;
             }
-            // ✨ 取消之前的动画
+            // Cancel previous animation
             if (item.animationId !== null) {
                 cancelAnimationFrame(item.animationId);
                 item.animationId = null;
@@ -568,14 +596,14 @@ class LiquidFillerGroup {
                 animate();
             }
             catch (error) {
-                console.error('LiquidFillerGroup: fillTo 执行失败', model, error);
+                console.error('LiquidFillerGroup: fillTo execution failed', model, error);
             }
         });
     }
-    /** 设置多个模型液位，percentList 与 items 顺序对应 */
+    /** Set multiple model levels, percentList corresponds to items order */
     fillToAll(percentList) {
         if (percentList.length !== this.items.length) {
-            console.warn(`LiquidFillerGroup: percentList 长度 (${percentList.length}) 与 items 长度 (${this.items.length}) 不匹配`);
+            console.warn(`LiquidFillerGroup: percentList length (${percentList.length}) does not match items length (${this.items.length})`);
         }
         percentList.forEach((p, idx) => {
             if (idx < this.items.length) {
@@ -583,17 +611,17 @@ class LiquidFillerGroup {
             }
         });
     }
-    /** 恢复单个模型原始材质并移除液体 */
+    /** Restore single model original material and remove liquid */
     restore(model) {
         const item = this.items.find(i => i.model === model);
         if (!item)
             return;
-        // ✨ 取消动画
+        // Cancel animation
         if (item.animationId !== null) {
             cancelAnimationFrame(item.animationId);
             item.animationId = null;
         }
-        // 恢复原始材质
+        // Restore original material
         item.model.traverse(obj => {
             if (obj.isMesh) {
                 const mesh = obj;
@@ -602,7 +630,7 @@ class LiquidFillerGroup {
                     mesh.material = original;
             }
         });
-        // 释放液体 Mesh
+        // Dispose liquid Mesh
         if (item.liquidMesh) {
             this.scene.remove(item.liquidMesh);
             item.liquidMesh.geometry.dispose();
@@ -615,20 +643,20 @@ class LiquidFillerGroup {
             item.liquidMesh = null;
         }
     }
-    /** 恢复所有模型 */
+    /** Restore all models */
     restoreAll() {
         this.items.forEach(item => this.restore(item.model));
     }
-    /** 销毁方法，释放事件和资源 */
+    /** Dispose method, release events and resources */
     dispose() {
-        // ✨ 先恢复所有模型
+        // Restore all models first
         this.restoreAll();
-        // ✨ 使用 AbortController 一次性解绑所有事件
+        // Unbind all events at once using AbortController
         if (this.abortController) {
             this.abortController.abort();
             this.abortController = null;
         }
-        // ✨ 清空 items
+        // Clear items
         this.items.length = 0;
     }
 }