clawmate 1.3.0 → 1.4.1

package/renderer/js/pet-engine.js

@@ -1,72 +1,72 @@
 /**
- * 핵심 이동/물리 엔진 (리뉴얼)
- * requestAnimationFrame 기반 — 스텝 이동 + 점프 + 레펠 + 중력 낙하
+ * Core movement/physics engine (renewed)
+ * requestAnimationFrame based -- step movement + jump + rappel + gravity fall
  *
- * 이동 모드:
- *   crawling   — 표면 위에서 한발자국씩 기어가는 이동
- *   jumping    — 포물선 궤도 점프
- *   falling    — 중력에 의한 자유 낙하
- *   rappelling — 실(thread)을 타고 진자운동하며 하강
+ * Movement modes:
+ *   crawling   -- step-by-step crawling on surfaces
+ *   jumping    -- parabolic trajectory jump
+ *   falling    -- gravity-based free fall
+ *   rappelling -- pendulum swing descent on a thread
  */
 const PetEngine = (() => {
-  // --- 물리 상수 ---
-  const GRAVITY = 0.3;        // 중력 가속도 (px/frame^2)
-  const STEP_SIZE = 4;        // 한 걸음 크기 (px)
-  const JUMP_VX = 3;          // 점프 수평 초기 속도
-  const JUMP_VY = -7;         // 점프 수직 초기 속도 (위로)
-  const BOUNCE_FACTOR = 0.3;  // 착지 바운스 계수
-  const CHAR_SIZE = 64;       // 캐릭터 크기 (px)
-  const ANIM_INTERVAL = 150;  // 애니메이션 프레임 전환 간격 (ms) — 부드러운 전환
-  const THREAD_SPEED = 0.8;   // 레펠 하강 속도 (px/frame)
-
-  // --- 위치 및 속도 ---
+  // --- Physics constants ---
+  const GRAVITY = 0.3;        // Gravity acceleration (px/frame^2)
+  const STEP_SIZE = 4;        // Step size (px)
+  const JUMP_VX = 3;          // Jump horizontal initial velocity
+  const JUMP_VY = -7;         // Jump vertical initial velocity (upward)
+  const BOUNCE_FACTOR = 0.3;  // Landing bounce factor
+  const CHAR_SIZE = 64;       // Character size (px)
+  const ANIM_INTERVAL = 150;  // Animation frame transition interval (ms) -- smooth transition
+  const THREAD_SPEED = 0.8;   // Rappel descent speed (px/frame)
+
+  // --- Position and velocity ---
   let x = 0, y = 0;
-  let vx = 0, vy = 0;         // 현재 속도 벡터
-
-  // --- 표면/방향 ---
-  let edge = 'bottom';        // 현재 부착된 가장자리 (bottom, left, right, top, surface)
-  let direction = 1;           // 이동 방향: 1=오른쪽/아래, -1=왼쪽/위
-  let flipX = false;           // 캐릭터 좌우 반전 여부
-  let prevFlipX = false;       // 이전 프레임 flipX (전환 감지용)
-  let flipTransition = 0;      // flipX 전환 진행도 (0~1, 1이면 완료)
-  const FLIP_DURATION = 120;   // flipX 전환 시간 (ms)
-  let flipStartTime = 0;       // flipX 전환 시작 시각
+  let vx = 0, vy = 0;         // Current velocity vector
+
+  // --- Surface/direction ---
+  let edge = 'bottom';        // Currently attached edge (bottom, left, right, top, surface)
+  let direction = 1;           // Movement direction: 1=right/down, -1=left/up
+  let flipX = false;           // Character horizontal flip
+  let prevFlipX = false;       // Previous frame flipX (for transition detection)
+  let flipTransition = 0;      // flipX transition progress (0~1, 1 = complete)
+  const FLIP_DURATION = 120;   // flipX transition duration (ms)
+  let flipStartTime = 0;       // flipX transition start time
   let screenW, screenH;
 
-  // --- 엔진 상태 ---
+  // --- Engine state ---
   let running = false;
   let petContainer = null;
   let speedMultiplier = 1.0;
   let animFrame = 0;
   let lastAnimTime = 0;
-  let animFrameChanged = false;  // 애니메이션 프레임 전환 플래그 (이동과 동기화)
+  let animFrameChanged = false;  // Animation frame change flag (synced with movement)
 
-  // --- 이동 모드 ---
+  // --- Movement mode ---
   let movementMode = 'crawling';  // crawling | jumping | falling | rappelling
-  let onSurface = true;           // 표면 위에 있는지 여부
+  let onSurface = true;           // Whether on a surface
 
-  // --- 스텝 시스템 (애니메이션 프레임 동기화) ---
+  // --- Step system (animation frame sync) ---
 
-  // --- 레펠(thread) 시스템 ---
-  // 부착점에서 실을 내려 진자운동하며 하강
+  // --- Rappel (thread) system ---
+  // Pendulum swing descent from attachment point
   let thread = null;  // { attachX, attachY, length, angle, swingVel } | null
 
-  // --- 윈도우 표면 목록 ---
-  // 외부 윈도우의 타이틀바 등을 추가 표면으로 등록
+  // --- Window surface list ---
+  // Register external window title bars etc. as additional surfaces
   let windowSurfaces = [];  // [{ id, x, y, width, height }]
 
-  // --- 착지 시 현재 올라가 있는 표면 참조 ---
+  // --- Reference to current surface when landed ---
   let currentSurface = null;
 
   /**
-   * 초기화: 컨테이너 설정 및 화면 하단 중앙 배치
+   * Initialization: set up container and place at bottom-center of screen
    */
   function init(container) {
     petContainer = container;
     screenW = window.innerWidth;
     screenH = window.innerHeight;
 
-    // 화면 하단 중앙에서 시작
+    // Start at bottom-center of screen
     x = (screenW - CHAR_SIZE) / 2;
     y = screenH - CHAR_SIZE;
     edge = 'bottom';
@@ -76,7 +76,7 @@ const PetEngine = (() => {
     currentSurface = null;
     updateVisual();
 
-    // 화면 크기 변경 대응
+    // Handle window resize
     window.addEventListener('resize', () => {
       screenW = window.innerWidth;
       screenH = window.innerHeight;
@@ -86,14 +86,14 @@ const PetEngine = (() => {
   }
 
   /**
-   * 속도 배율 설정 (성격/진화 단계에 따른 속도 조절)
+   * Set speed multiplier (adjusts speed based on personality/evolution stage)
    */
   function setSpeedMultiplier(mult) {
     speedMultiplier = mult;
   }
 
   /**
-   * 화면 경계 내로 위치 제한
+   * Clamp position within screen bounds
    */
   function clampPosition() {
     x = Math.max(0, Math.min(x, screenW - CHAR_SIZE));
@@ -101,24 +101,24 @@ const PetEngine = (() => {
   }
 
   // ===================================
-  //  시각적 업데이트
+  //  Visual update
   // ===================================
 
   /**
-   * 컨테이너 위치 및 회전/반전 업데이트
-   * 가장자리별로 캐릭터가 올바른 방향을 향하도록 transform 적용
+   * Update container position and rotation/flip
+   * Apply transform so character faces correct direction per edge
    *
-   * EDGE_OFFSET: 스프라이트 테두리의 빈 픽셀(4px)을 보정하여
-   * 다리가 실제로 벽면/바닥/천장에 밀착하도록 렌더링 위치 조정
+   * EDGE_OFFSET: Compensates for empty pixels (4px) at sprite border
+   * so legs render flush against wall/floor/ceiling
    */
   const EDGE_OFFSET = 4;
 
   function updateVisual() {
     if (!petContainer) return;
 
-    // --- flipX 부드러운 전환 처리 ---
+    // --- Smooth flipX transition handling ---
     if (flipX !== prevFlipX) {
-      // 방향이 바뀌었으면 전환 시작
+      // Start transition when direction changed
       flipStartTime = Date.now();
       flipTransition = 0;
       prevFlipX = flipX;
@@ -128,7 +128,7 @@ const PetEngine = (() => {
       flipTransition = Math.min(1, elapsed / FLIP_DURATION);
     }
 
-    // 전환 중일 때 CSS transition 적용
+    // Apply CSS transition during flip
     if (flipTransition < 1) {
       petContainer.style.transition = `transform ${FLIP_DURATION}ms ease-in-out`;
     } else {
@@ -138,21 +138,21 @@ const PetEngine = (() => {
     let renderX = x;
     let renderY = y;
 
-    // 표면에 붙어있을 때만 오프셋 적용 (공중 상태에서는 불필요)
+    // Apply offset only when attached to surface (not needed in mid-air)
     if (onSurface && movementMode === 'crawling') {
       switch (edge) {
         case 'bottom':
         case 'surface':
-          renderY += EDGE_OFFSET;  // 바닥: 다리를 아래로 밀착
+          renderY += EDGE_OFFSET;  // Floor: press legs down
           break;
         case 'top':
-          renderY -= EDGE_OFFSET;  // 천장: 다리를 위로 밀착
+          renderY -= EDGE_OFFSET;  // Ceiling: press legs up
           break;
         case 'left':
-          renderX -= EDGE_OFFSET;  // 왼쪽 벽: 다리를 왼쪽으로 밀착
+          renderX -= EDGE_OFFSET;  // Left wall: press legs left
           break;
         case 'right':
-          renderX += EDGE_OFFSET;  // 오른쪽 벽: 다리를 오른쪽으로 밀착
+          renderX += EDGE_OFFSET;  // Right wall: press legs right
           break;
       }
     }
@@ -163,41 +163,41 @@ const PetEngine = (() => {
     let transform = '';
 
     if (movementMode === 'rappelling' || movementMode === 'jumping' || movementMode === 'falling') {
-      // 공중 상태: 바닥 기준 기본 자세 (회전 없음)
+      // Mid-air: default floor-based pose (no rotation)
       if (flipX) transform = 'scaleX(-1)';
     } else if (edge === 'left') {
-      // 왼쪽 벽: 다리가 왼쪽 가장자리를 향하도록 반시계 회전
+      // Left wall: rotate counter-clockwise so legs face left edge
       transform = 'rotate(-90deg)';
       if (flipX) transform += ' scaleX(-1)';
     } else if (edge === 'right') {
-      // 오른쪽 벽: 다리가 오른쪽 가장자리를 향하도록 시계 회전
+      // Right wall: rotate clockwise so legs face right edge
       transform = 'rotate(90deg)';
       if (flipX) transform += ' scaleX(-1)';
     } else if (edge === 'top') {
-      // 천장: 다리가 위를 향하도록 상하 반전
+      // Ceiling: flip vertically so legs face upward
       transform = 'scaleY(-1)';
       if (flipX) transform += ' scaleX(-1)';
     } else {
-      // 바닥/표면: 기본 자세
+      // Floor/surface: default pose
       if (flipX) transform = 'scaleX(-1)';
     }
 
     petContainer.style.transform = transform || 'none';
 
-    // 레펠 스레드 시각화 갱신
+    // Update rappel thread visualization
     updateThreadVisual();
   }
 
   /**
-   * SVG 라인으로 레펠 실(thread) 시각화
-   * thread가 없으면 숨기고, 있으면 부착점 → 캐릭터 상단 연결
+   * Visualize rappel thread as SVG line
+   * Hide when no thread; when active, connect attachment point to character top
    */
   function updateThreadVisual() {
     const line = document.getElementById('thread-line');
     if (!line) return;
 
     if (!thread) {
-      // 실이 없으면 숨김
+      // Hide when no thread
       line.setAttribute('x1', '0');
       line.setAttribute('y1', '0');
       line.setAttribute('x2', '0');
@@ -206,7 +206,7 @@ const PetEngine = (() => {
       return;
     }
 
-    // 부착점에서 캐릭터 상단 중앙까지 실 표시
+    // Draw thread from attachment point to character top-center
     line.style.display = 'block';
     line.setAttribute('x1', thread.attachX);
     line.setAttribute('y1', thread.attachY);
@@ -217,56 +217,56 @@ const PetEngine = (() => {
   }
 
   // ===================================
-  //  스텝 기반 이동 (뚝뚝 끊어 걷기)
+  //  Step-based movement (choppy walking)
   // ===================================
 
   /**
-   * 스텝 이동: 애니메이션 프레임 전환 시에만 한 걸음 이동
-   * 다리 움직임(프레임 변화)과 실제 위치 이동이 1:1 동기화되어
-   * 다리가 움직일 때만 몸이 이동하는 자연스러운 보행 구현
+   * Step movement: move one step only when animation frame transitions
+   * Leg motion (frame change) and actual position movement are 1:1 synced
+   * so the body only moves when legs move, creating natural walking
    *
-   * @param {number} stepScale - 스텝 크기 배율 (0.6 = 짐 들고 느리게, 1.0 = 기본)
+   * @param {number} stepScale - Step size multiplier (0.6 = slow with load, 1.0 = default)
    */
   function stepMove(stepScale) {
-    // 애니메이션 프레임이 바뀌지 않았으면 이동 안 함
+    // Do not move if animation frame has not changed
     if (!animFrameChanged) return;
 
-    // 한 걸음 전진
+    // Advance one step
     const stepDist = STEP_SIZE * stepScale * speedMultiplier;
 
     if (edge === 'bottom' || edge === 'top' || edge === 'surface') {
-      // 수평 이동 (바닥, 천장, 윈도우 표면)
+      // Horizontal movement (floor, ceiling, window surface)
       x += stepDist * direction;
       flipX = direction < 0;
     } else if (edge === 'left') {
-      // 왼쪽 벽: y축 이동 (direction=1이면 아래로, -1이면 위로)
+      // Left wall: y-axis movement (direction=1 goes down, -1 goes up)
       y += stepDist * direction;
     } else if (edge === 'right') {
-      // 오른쪽 벽: y축 이동
+      // Right wall: y-axis movement
       y += stepDist * direction;
     }
   }
 
   // ===================================
-  //  윈도우 표면 탐지
+  //  Window surface detection
   // ===================================
 
   /**
-   * 주어진 위치 아래에 있는 윈도우 표면을 찾음
-   * 캐릭터가 수평 범위 안에 있고, 표면 상단 근처에 있을 때 착지 가능
+   * Find window surface below a given position
+   * Landable when character is within horizontal range and near surface top
    *
-   * @param {number} px - 캐릭터 x 좌표
-   * @param {number} py - 캐릭터 하단 y 좌표 (y + CHAR_SIZE)
-   * @returns {object|null} 착지 가능한 표면 또는 null
+   * @param {number} px - Character x coordinate
+   * @param {number} py - Character bottom y coordinate (y + CHAR_SIZE)
+   * @returns {object|null} Landable surface or null
    */
   function findSurfaceBelow(px, py) {
     let closest = null;
     let closestDist = Infinity;
 
     for (const s of windowSurfaces) {
-      // 수평 범위 확인: 캐릭터가 표면 위에 겹치는지
+      // Check horizontal range: whether character overlaps surface
       if (px + CHAR_SIZE > s.x && px < s.x + s.width) {
-        // 표면 상단에 근접했는지 (위에서 떨어지는 중)
+        // Check if near surface top (falling from above)
         if (py >= s.y && py <= s.y + 10) {
           const dist = Math.abs(py - s.y);
           if (dist < closestDist) {
@@ -280,8 +280,8 @@ const PetEngine = (() => {
   }
 
   /**
-   * 외부에서 윈도우 표면 목록 등록
-   * (예: 다른 창의 타이틀바를 걸어다닐 수 있는 표면으로 설정)
+   * Register window surface list from external source
+   * (e.g., register title bars of other windows as walkable surfaces)
    *
    * @param {Array} surfaces - [{ id, x, y, width, height }]
    */
@@ -290,28 +290,28 @@ const PetEngine = (() => {
   }
 
   // ===================================
-  //  물리 상태별 이동 처리
+  //  Physics state-based movement handling
   // ===================================
 
   /**
-   * 메인 이동 로직: movementMode에 따라 물리 연산 수행
+   * Main movement logic: perform physics calculations based on movementMode
    *
-   * @param {string} state - StateMachine의 현재 상태 (walking, idle 등)
+   * @param {string} state - Current StateMachine state (walking, idle, etc.)
    */
   function moveForState(state) {
     switch (movementMode) {
 
-      // --- 포물선 점프 ---
+      // --- Parabolic jump ---
       case 'jumping':
-        vy += GRAVITY;  // 중력 적용
+        vy += GRAVITY;  // Apply gravity
         x += vx;
         y += vy;
         flipX = vx < 0;
 
-        // 바닥 착지 감지
+        // Floor landing detection
         if (y >= screenH - CHAR_SIZE) {
           y = screenH - CHAR_SIZE;
-          // 바운스 효과: 약간 튕김
+          // Bounce effect: slight rebound
           if (Math.abs(vy) > 2) {
             vy = -vy * BOUNCE_FACTOR;
           } else {
@@ -324,7 +324,7 @@ const PetEngine = (() => {
           }
         }
 
-        // 윈도우 표면 착지 감지 (아래로 떨어지는 중일 때만)
+        // Window surface landing detection (only while falling downward)
         if (vy > 0 && movementMode === 'jumping') {
           const landSurface = findSurfaceBelow(x, y + CHAR_SIZE);
           if (landSurface) {
@@ -338,7 +338,7 @@ const PetEngine = (() => {
           }
         }
 
-        // 벽/천장 충돌 → 해당 가장자리에 붙음
+        // Wall/ceiling collision -> attach to that edge
         if (x <= 0 && movementMode === 'jumping') {
           x = 0;
           edge = 'left';
@@ -347,7 +347,7 @@ const PetEngine = (() => {
           currentSurface = null;
           vx = 0;
           vy = 0;
-          direction = 1; // 아래쪽 방향
+          direction = 1; // Downward direction
         }
         if (x >= screenW - CHAR_SIZE && movementMode === 'jumping') {
           x = screenW - CHAR_SIZE;
@@ -367,16 +367,16 @@ const PetEngine = (() => {
           currentSurface = null;
           vx = 0;
           vy = 0;
-          direction = 1; // 오른쪽 방향
+          direction = 1; // Rightward direction
         }
         break;
 
-      // --- 자유 낙하 (중력) ---
+      // --- Free fall (gravity) ---
       case 'falling':
         vy += GRAVITY;
         y += vy;
 
-        // 윈도우 표면 착지 감지
+        // Window surface landing detection
         if (vy > 0) {
           const fallSurface = findSurfaceBelow(x, y + CHAR_SIZE);
           if (fallSurface) {
@@ -389,7 +389,7 @@ const PetEngine = (() => {
           }
         }
 
-        // 바닥 착지
+        // Floor landing
         if (y >= screenH - CHAR_SIZE) {
           y = screenH - CHAR_SIZE;
           edge = 'bottom';
@@ -400,23 +400,23 @@ const PetEngine = (() => {
         }
         break;
 
-      // --- 레펠: 실을 타고 진자운동하며 하강 ---
+      // --- Rappel: pendulum swing descent on thread ---
       case 'rappelling':
         if (thread) {
-          // 실 길이 증가 → 하강
+          // Increase thread length -> descend
           thread.length += THREAD_SPEED * speedMultiplier;
 
-          // 진자 흔들림 물리
+          // Pendulum swing physics
           thread.swingVel += Math.sin(thread.angle) * 0.01;
-          thread.swingVel *= 0.98; // 감쇠
+          thread.swingVel *= 0.98; // Damping
 
           thread.angle += thread.swingVel;
 
-          // 부착점 기준 진자 위치 계산
+          // Calculate pendulum position from attachment point
           x = thread.attachX + Math.sin(thread.angle) * thread.length - CHAR_SIZE / 2;
           y = thread.attachY + Math.cos(thread.angle) * thread.length;
 
-          // 좌우 화면 경계 반사
+          // Bounce off left/right screen edges
           if (x <= 0) {
             x = 0;
             thread.swingVel = Math.abs(thread.swingVel) * 0.5;
@@ -426,7 +426,7 @@ const PetEngine = (() => {
             thread.swingVel = -Math.abs(thread.swingVel) * 0.5;
           }
 
-          // 윈도우 표면 착지 감지
+          // Window surface landing detection
           const rappelSurface = findSurfaceBelow(x, y + CHAR_SIZE);
           if (rappelSurface) {
             y = rappelSurface.y - CHAR_SIZE;
@@ -437,7 +437,7 @@ const PetEngine = (() => {
             currentSurface = rappelSurface;
           }
 
-          // 바닥 도달
+          // Reached floor
           if (y >= screenH - CHAR_SIZE) {
             y = screenH - CHAR_SIZE;
             thread = null;
@@ -449,7 +449,7 @@ const PetEngine = (() => {
         }
         break;
 
-      // --- 표면 위 기어가기 (스텝 기반) ---
+      // --- Surface crawling (step-based) ---
       case 'crawling':
       default:
         switch (state) {
@@ -457,17 +457,17 @@ const PetEngine = (() => {
           case 'ceiling_walk':
             stepMove(1.0);
 
-            // 수평 이동 시 경계 처리
+            // Boundary handling for horizontal movement
             if (edge === 'bottom' || edge === 'top') {
               if (x <= 0) { x = 0; direction = 1; }
               if (x >= screenW - CHAR_SIZE) { x = screenW - CHAR_SIZE; direction = -1; }
             }
 
-            // 윈도우 표면 위 이동 시 가장자리에서 떨어짐
+            // Fall off edge when moving on window surface
             if (edge === 'surface' && currentSurface) {
               if (x <= currentSurface.x - CHAR_SIZE / 2 ||
                   x >= currentSurface.x + currentSurface.width - CHAR_SIZE / 2) {
-                // 표면 가장자리에서 떨어짐 → 낙하 모드
+                // Fell off surface edge -> falling mode
                 movementMode = 'falling';
                 onSurface = false;
                 currentSurface = null;
@@ -479,7 +479,7 @@ const PetEngine = (() => {
 
           case 'climbing_up':
             if (edge === 'bottom' || edge === 'surface') {
-              // 바닥/표면에서 벽으로 전환
+              // Transition from floor/surface to wall
               if (direction > 0) {
                 x = screenW - CHAR_SIZE;
                 edge = 'right';
@@ -488,33 +488,33 @@ const PetEngine = (() => {
                 edge = 'left';
               }
               currentSurface = null;
-              direction = -1; // 벽에서 위쪽 방향
+              direction = -1; // Upward direction on wall
             }
 
-            // 벽에서 위로 기어오름: y 감소
+            // Climbing up wall: y decreases
             if (edge === 'left' || edge === 'right') {
               stepMove(0.7);
-              // stepMove가 direction(-1)을 적용하므로 y가 감소함
+              // stepMove applies direction(-1) so y decreases
             }
 
-            // 천장 도달
+            // Reached ceiling
             if (y <= 0) {
               y = 0;
               edge = 'top';
-              direction = 1; // 천장에서 오른쪽으로 이동
+              direction = 1; // Move rightward on ceiling
             }
             break;
 
           case 'climbing_down':
-            // 벽에서 아래로 기어내려감: y 증가
+            // Climbing down wall: y increases
             if (edge === 'left' || edge === 'right') {
-              // direction을 1(아래)로 설정해서 stepMove
+              // Set direction to 1 (down) for stepMove
               const prevDir = direction;
               direction = 1;
               stepMove(0.7);
               direction = prevDir;
             } else if (edge === 'top') {
-              // 천장에서 벽으로 내려가기 시작
+              // Start descending from ceiling to wall
               if (x < screenW / 2) {
                 x = 0;
                 edge = 'left';
@@ -522,19 +522,19 @@ const PetEngine = (() => {
                 x = screenW - CHAR_SIZE;
                 edge = 'right';
               }
-              direction = 1; // 아래 방향
+              direction = 1; // Downward direction
             }
 
-            // 바닥 도달
+            // Reached floor
             if (y >= screenH - CHAR_SIZE) {
               y = screenH - CHAR_SIZE;
               edge = 'bottom';
-              direction = Math.random() < 0.5 ? 1 : -1; // 랜덤 방향
+              direction = Math.random() < 0.5 ? 1 : -1; // Random direction
             }
             break;
 
           case 'scared':
-            // 도망: 스텝 스킵하고 빠르게 연속 이동
+            // Flee: skip steps, fast continuous movement
             if (edge === 'bottom' || edge === 'top' || edge === 'surface') {
               x += STEP_SIZE * 2.5 * direction * speedMultiplier;
               flipX = direction < 0;
@@ -544,7 +544,7 @@ const PetEngine = (() => {
             break;
 
           case 'carrying':
-            // 짐 들고 느리게 이동
+            // Slow movement while carrying
             stepMove(0.6);
             if (edge === 'bottom' || edge === 'top' || edge === 'surface') {
               if (x <= 0) { x = 0; direction = 1; }
@@ -553,7 +553,7 @@ const PetEngine = (() => {
             break;
 
           case 'excited':
-            // 작은 점프 효과 (제자리에서 통통 뜀)
+            // Small jump effect (bouncing in place)
             if (typeof StateMachine !== 'undefined') {
               const elapsed = StateMachine.getElapsed();
               const jumpOffset = Math.sin(elapsed / 150) * 8;
@@ -565,22 +565,22 @@ const PetEngine = (() => {
             }
             break;
 
-          // 점프 중 상태 (StateMachine에서 전이된 물리 상태)
+          // Jumping state (physics state transitioned from StateMachine)
           case 'jumping':
-            // movementMode가 jumping이 아니면 시작
+            // Initiate if movementMode is not yet jumping
             if (movementMode === 'crawling') {
               _initiateRandomJump();
             }
             break;
 
-          // 레펠 중 상태
+          // Rappelling state
           case 'rappelling':
             if (movementMode === 'crawling') {
               startRappel();
             }
             break;
 
-          // 낙하 중 상태
+          // Falling state
           case 'falling':
             if (movementMode === 'crawling') {
               movementMode = 'falling';
@@ -589,7 +589,7 @@ const PetEngine = (() => {
             }
             break;
 
-          // 커스텀 이동 패턴 실행 중
+          // Custom movement pattern in progress
           case 'custom':
             if (activeCustomMovement) {
               updateCustomMovement(now - (updateCustomMovement._lastTime || now));
@@ -601,7 +601,7 @@ const PetEngine = (() => {
           case 'sleeping':
           case 'interacting':
           case 'playing':
-            // 정지 또는 미세한 흔들림 (이동 없음)
+            // Stationary or subtle sway (no movement)
             break;
         }
         break;
@@ -612,26 +612,26 @@ const PetEngine = (() => {
   }
 
   /**
-   * StateMachine이 jumping 상태로 전이했을 때 랜덤 목표로 점프
-   * 현재 위치 기준 화면 중앙 방향 또는 랜덤 위치로 도약
+   * Random jump when StateMachine transitions to jumping state
+   * Leap toward screen center or random position from current location
    */
   function _initiateRandomJump() {
-    // 화면 중앙 근처의 랜덤 목표 지점
+    // Random target point near screen center
     const targetX = screenW * 0.2 + Math.random() * screenW * 0.6;
     const targetY = screenH * 0.3 + Math.random() * screenH * 0.4;
     jumpTo(targetX, targetY);
   }
 
   // ===================================
-  //  점프 명령
+  //  Jump commands
   // ===================================
 
   /**
-   * 목표 지점을 향해 포물선 점프 시작
-   * 초기 속도(vx, vy)를 계산하여 포물선 궤도 생성
+   * Start parabolic jump toward target point
+   * Calculate initial velocity (vx, vy) to create parabolic trajectory
    *
-   * @param {number} targetX - 목표 x 좌표
-   * @param {number} targetY - 목표 y 좌표
+   * @param {number} targetX - Target x coordinate
+   * @param {number} targetY - Target y coordinate
    */
   function jumpTo(targetX, targetY) {
     if (movementMode !== 'crawling') return;
@@ -640,14 +640,14 @@ const PetEngine = (() => {
     const dy = targetY - y;
     const dist = Math.hypot(dx, dy);
 
-    // 비행 시간 추정 (거리 기반)
+    // Estimate flight time (distance-based)
     const time = Math.max(20, dist / (JUMP_VX * 2 + 2));
 
-    // 포물선 초기 속도 계산
+    // Calculate parabolic initial velocity
     vx = dx / time;
     vy = (dy / time) - (GRAVITY * time) / 2;
 
-    // vx, vy 범위 제한 (너무 빠르지 않게)
+    // Clamp vx, vy range (prevent excessive speed)
     const maxV = 8;
     vx = Math.max(-maxV, Math.min(maxV, vx));
     vy = Math.max(-12, Math.min(maxV, vy));
@@ -662,29 +662,29 @@ const PetEngine = (() => {
   }
 
   // ===================================
-  //  레펠(Thread) 시스템
+  //  Rappel (Thread) system
   // ===================================
 
   /**
-   * 레펠 시작: 천장이나 벽에서 실을 내려 하강
-   * 부착점을 현재 위치에 설정하고 진자운동 시작
+   * Start rappel: descend by lowering thread from ceiling or wall
+   * Set attachment point at current position and begin pendulum swing
    */
   function startRappel() {
-    // 천장, 왼쪽 벽, 오른쪽 벽에서만 레펠 가능
+    // Rappel only possible from ceiling, left wall, or right wall
     if (edge !== 'top' && edge !== 'left' && edge !== 'right') return;
 
     let attachX, attachY;
 
     if (edge === 'top') {
-      // 천장에서 레펠: 현재 위치 바로 위에 부착
+      // Rappel from ceiling: attach directly above current position
       attachX = x + CHAR_SIZE / 2;
       attachY = 0;
     } else if (edge === 'left') {
-      // 왼쪽 벽에서 레펠: 벽의 현재 y 위치에 부착
+      // Rappel from left wall: attach at current y position on wall
       attachX = 0;
       attachY = y;
     } else {
-      // 오른쪽 벽에서 레펠
+      // Rappel from right wall
       attachX = screenW;
       attachY = y;
     }
@@ -692,9 +692,9 @@ const PetEngine = (() => {
     thread = {
       attachX: attachX,
       attachY: attachY,
-      length: CHAR_SIZE,                        // 초기 실 길이
-      angle: 0,                                  // 진자 각도 (라디안)
-      swingVel: (Math.random() - 0.5) * 0.05,   // 초기 흔들림 속도
+      length: CHAR_SIZE,                        // Initial thread length
+      angle: 0,                                  // Pendulum angle (radians)
+      swingVel: (Math.random() - 0.5) * 0.05,   // Initial swing velocity
     };
 
     movementMode = 'rappelling';
@@ -707,7 +707,7 @@ const PetEngine = (() => {
   }
 
   /**
-   * 레펠 해제: 실을 놓아 자유 낙하 전환
+   * Release rappel: let go of thread to transition to free fall
    */
   function releaseThread() {
     if (!thread) return;
@@ -722,41 +722,41 @@ const PetEngine = (() => {
   }
 
   /**
-   * 화면 중앙으로 이동
-   * 천장에서는 레펠로 하강, 그 외에는 점프
+   * Move to screen center
+   * Descend via rappel from ceiling, otherwise jump
    */
   function moveToCenter() {
     const cx = (screenW - CHAR_SIZE) / 2;
     const cy = (screenH - CHAR_SIZE) / 2;
 
     if (edge === 'top') {
-      // 천장에서는 레펠로 내려감
+      // From ceiling, descend via rappel
       startRappel();
     } else {
-      // 바닥/벽에서는 중앙으로 점프
+      // From floor/wall, jump to center
       jumpTo(cx, cy);
     }
   }
 
   // ===================================
-  //  애니메이션 프레임 갱신
+  //  Animation frame update
   // ===================================
 
   /**
-   * 현재 상태에 맞는 애니메이션 프레임 렌더링
-   * 공중 상태일 때는 기존 프레임셋을 재활용
+   * Render animation frame matching current state
+   * Reuse existing frameset when in mid-air
    *
-   * @param {string} state     - StateMachine 상태
-   * @param {number} timestamp - requestAnimationFrame 타임스탬프
+   * @param {string} state     - StateMachine state
+   * @param {number} timestamp - requestAnimationFrame timestamp
    */
   function updateAnimation(state, timestamp) {
     if (timestamp - lastAnimTime > ANIM_INTERVAL) {
       animFrame++;
       lastAnimTime = timestamp;
-      animFrameChanged = true;  // 이동 시스템에 프레임 전환 알림
+      animFrameChanged = true;  // Notify movement system of frame transition
     }
 
-    // 이동 모드에 따라 적절한 프레임셋으로 매핑
+    // Map to appropriate frameset based on movement mode
     let effectiveState = state;
     if (movementMode === 'jumping') effectiveState = 'jumping';
     if (movementMode === 'falling') effectiveState = 'falling';
@@ -768,11 +768,11 @@ const PetEngine = (() => {
   }
 
   // ===================================
-  //  위치/상태 접근자
+  //  Position/state accessors
   // ===================================
 
   /**
-   * 현재 위치 및 상태 정보 반환
+   * Return current position and state info
    * @returns {{ x, y, edge, direction, flipX, movementMode, onSurface, thread }}
    */
   function getPosition() {
@@ -784,7 +784,7 @@ const PetEngine = (() => {
   }
 
   /**
-   * 위치 직접 설정 (드래그 등)
+   * Set position directly (for drag, etc.)
    */
   function setPosition(nx, ny) {
     x = nx;
@@ -803,8 +803,8 @@ const PetEngine = (() => {
   }
 
   /**
-   * 가장 가까운 가장자리로 즉시 이동 (드래그 후)
-   * 모든 물리 상태를 초기화하고 표면에 붙음
+   * Snap to nearest edge instantly (after drag)
+   * Reset all physics state and attach to surface
    */
   function snapToNearestEdge() {
     const distBottom = screenH - CHAR_SIZE - y;
@@ -827,7 +827,7 @@ const PetEngine = (() => {
       edge = 'right';
     }
 
-    // 물리 상태 완전 초기화
+    // Full physics state reset
     movementMode = 'crawling';
     onSurface = true;
     currentSurface = null;
@@ -839,8 +839,8 @@ const PetEngine = (() => {
   }
 
   /**
-   * 자유 낙하 시작 (화면 중앙 근처에서 놓았을 때)
-   * 중력에 의해 바닥 또는 가장 가까운 표면으로 떨어짐
+   * Start free fall (when released near screen center)
+   * Fall to floor or nearest surface by gravity
    */
   function startFalling() {
     movementMode = 'falling';
@@ -856,7 +856,7 @@ const PetEngine = (() => {
   }
 
   /**
-   * 레펠 스레드 정보 반환
+   * Return rappel thread info
    * @returns {object|null}
    */
   function getThread() {
@@ -864,36 +864,36 @@ const PetEngine = (() => {
   }
 
   // ===================================
-  //  커스텀 이동 패턴 레지스트리
+  //  Custom movement pattern registry
   // ===================================
 
-  // 등록된 커스텀 이동 패턴 저장소
-  // 각 핸들러: { init(params), update(deltaTime), isComplete(), cleanup() }
+  // Registered custom movement pattern store
+  // Each handler: { init(params), update(deltaTime), isComplete(), cleanup() }
   let customMovements = {};
-  let activeCustomMovement = null;  // 현재 실행 중인 커스텀 이동 { name, handler, state }
+  let activeCustomMovement = null;  // Currently active custom movement { name, handler, state }
 
   /**
-   * 커스텀 이동 패턴 등록
-   * @param {string} name - 패턴 이름 (예: 'zigzag', 'patrol')
+   * Register custom movement pattern
+   * @param {string} name - Pattern name (e.g., 'zigzag', 'patrol')
    * @param {object} handler - { init, update, isComplete, cleanup }
    */
   function registerMovement(name, handler) {
     if (!handler || typeof handler.update !== 'function') {
-      console.error(`[PetEngine] 이동 패턴 '${name}' 등록 실패: update 함수 필수`);
+      console.error(`[PetEngine] Failed to register movement pattern '${name}': update function required`);
       return false;
     }
-    // 기본 메서드 보완
+    // Fill in default methods
     handler.init = handler.init || (() => {});
     handler.isComplete = handler.isComplete || (() => false);
     handler.cleanup = handler.cleanup || (() => {});
     customMovements[name] = handler;
-    console.log(`[PetEngine] 커스텀 이동 패턴 등록: ${name}`);
+    console.log(`[PetEngine] Custom movement pattern registered: ${name}`);
     return true;
   }
 
   /**
-   * 등록된 커스텀 이동 패턴 제거
-   * @param {string} name - 패턴 이름
+   * Remove registered custom movement pattern
+   * @param {string} name - Pattern name
    */
   function unregisterMovement(name) {
     if (activeCustomMovement && activeCustomMovement.name === name) {
@@ -903,24 +903,24 @@ const PetEngine = (() => {
   }
 
   /**
-   * 커스텀 이동 패턴 실행
-   * @param {string} name - 등록된 패턴 이름
-   * @param {object} params - 패턴 초기화 파라미터
-   * @returns {boolean} 실행 성공 여부
+   * Execute custom movement pattern
+   * @param {string} name - Registered pattern name
+   * @param {object} params - Pattern initialization parameters
+   * @returns {boolean} Whether execution succeeded
    */
   function executeCustomMovement(name, params = {}) {
     const handler = customMovements[name];
     if (!handler) {
-      console.warn(`[PetEngine] 미등록 이동 패턴: ${name}`);
+      console.warn(`[PetEngine] Unregistered movement pattern: ${name}`);
       return false;
     }
 
-    // 기존 커스텀 이동이 있으면 정리
+    // Clean up existing custom movement if any
     if (activeCustomMovement) {
       activeCustomMovement.handler.cleanup();
     }
 
-    // 패턴 초기화 시 현재 위치/화면 정보 전달
+    // Pass current position/screen info on pattern initialization
     const context = {
       x, y, screenW, screenH,
       charSize: CHAR_SIZE,
@@ -930,18 +930,18 @@ const PetEngine = (() => {
     const state = handler.init(Object.assign({}, params, context)) || {};
     activeCustomMovement = { name, handler, state };
 
-    // CUSTOM 상태로 전환
+    // Transition to CUSTOM state
     if (typeof StateMachine !== 'undefined') {
       StateMachine.forceState('custom');
     }
 
-    console.log(`[PetEngine] 커스텀 이동 실행: ${name}`);
+    console.log(`[PetEngine] Executing custom movement: ${name}`);
     return true;
   }
 
   /**
-   * 커스텀 이동 매 프레임 갱신
-   * @param {number} deltaTime - 프레임 간 경과 시간 (ms)
+   * Update custom movement every frame
+   * @param {number} deltaTime - Elapsed time between frames (ms)
    */
   function updateCustomMovement(deltaTime) {
     if (!activeCustomMovement) return;
@@ -958,17 +958,17 @@ const PetEngine = (() => {
 
     handler.update(deltaTime, state, context);
 
-    // 핸들러가 setPos로 위치를 설정했을 수 있음
+    // Handler may have set position via setPos
     clampPosition();
 
-    // 완료 확인
+    // Check completion
     if (handler.isComplete(state)) {
       stopCustomMovement();
     }
   }
 
   /**
-   * 현재 커스텀 이동 강제 중지 → IDLE 복귀
+   * Force stop current custom movement -> return to IDLE
    */
   function stopCustomMovement() {
     if (!activeCustomMovement) return;
@@ -981,24 +981,24 @@ const PetEngine = (() => {
   }
 
   /**
-   * 등록된 커스텀 이동 패턴 목록 반환
+   * Return list of registered custom movement patterns
    */
   function getRegisteredMovements() {
     return Object.keys(customMovements);
   }
 
-  // --- 사전 등록 이동 패턴 ---
+  // --- Pre-registered movement patterns ---
 
-  // 지그재그: 대각선 방향 교대로 이동
+  // Zigzag: alternating diagonal movement
   registerMovement('zigzag', {
     init(params) {
       return {
-        amplitude: params.amplitude || 40,     // 좌우 진폭 (px)
-        speed: params.speed || 2,              // 전진 속도
-        segmentLength: params.segmentLength || 60, // 한 구간 길이
+        amplitude: params.amplitude || 40,     // Horizontal amplitude (px)
+        speed: params.speed || 2,              // Forward speed
+        segmentLength: params.segmentLength || 60, // Segment length
         traveled: 0,
-        totalDistance: params.distance || 300,  // 총 이동 거리
-        zigDir: 1,                             // 지그재그 방향
+        totalDistance: params.distance || 300,  // Total travel distance
+        zigDir: 1,                             // Zigzag direction
         startX: params.x,
         startY: params.y,
       };
@@ -1007,9 +1007,9 @@ const PetEngine = (() => {
       const step = state.speed * (dt / 16);
       state.traveled += step;
 
-      // 수평 전진
+      // Horizontal advance
       const moveX = step * (ctx.direction || 1);
-      // 수직 지그재그
+      // Vertical zigzag
       const segProgress = (state.traveled % state.segmentLength) / state.segmentLength;
       if (segProgress < 0.05) state.zigDir *= -1;
       const moveY = state.zigDir * step * 0.7;
@@ -1023,14 +1023,14 @@ const PetEngine = (() => {
     cleanup() {},
   });
 
-  // 순찰: 두 지점 사이를 왕복
+  // Patrol: round-trip between two points
   registerMovement('patrol', {
     init(params) {
       return {
         pointA: { x: params.pointAX || 100, y: params.pointAY || params.y },
         pointB: { x: params.pointBX || params.screenW - 164, y: params.pointBY || params.y },
         speed: params.speed || 1.5,
-        laps: params.laps || 3,                // 왕복 횟수
+        laps: params.laps || 3,                // Number of round trips
         currentLap: 0,
         targetIdx: 0,                          // 0=A, 1=B
       };
@@ -1042,7 +1042,7 @@ const PetEngine = (() => {
       const dist = Math.hypot(dx, dy);
 
       if (dist < 5) {
-        // 목표 도달 → 방향 전환
+        // Reached target -> reverse direction
         state.targetIdx = 1 - state.targetIdx;
         if (state.targetIdx === 0) state.currentLap++;
         return;
@@ -1059,14 +1059,14 @@ const PetEngine = (() => {
     cleanup() {},
   });
 
-  // 원형 회전: 중심점 기준 회전
+  // Circular rotation: revolve around center point
   registerMovement('circle', {
     init(params) {
       return {
         centerX: params.centerX || params.x,
         centerY: params.centerY || params.y - 50,
         radius: params.radius || 50,
-        speed: params.speed || 0.03,           // 각속도 (rad/frame)
+        speed: params.speed || 0.03,           // Angular velocity (rad/frame)
         angle: 0,
         totalAngle: params.revolutions ? params.revolutions * Math.PI * 2 : Math.PI * 4,
         traveled: 0,
@@ -1088,12 +1088,12 @@ const PetEngine = (() => {
     cleanup() {},
   });
 
-  // 떨기: 빠르게 좌우 진동
+  // Shake: fast horizontal vibration
   registerMovement('shake', {
     init(params) {
       return {
-        intensity: params.intensity || 4,      // 떨림 강도 (px)
-        duration: params.duration || 800,       // 지속 시간 (ms)
+        intensity: params.intensity || 4,      // Shake intensity (px)
+        duration: params.duration || 800,       // Duration (ms)
         elapsed: 0,
         originX: params.x,
         originY: params.y,
@@ -1104,7 +1104,7 @@ const PetEngine = (() => {
       state.elapsed += dt;
       state.phase += dt * 0.05;
 
-      // 감쇠하는 사인파 진동
+      // Damped sinusoidal vibration
       const decay = 1 - (state.elapsed / state.duration);
       const offsetX = Math.sin(state.phase) * state.intensity * decay;
       ctx.setPos(state.originX + offsetX, state.originY);
@@ -1115,7 +1115,7 @@ const PetEngine = (() => {
     cleanup() {},
   });
 
-  // 댄스: 여러 동작을 연속 수행 (점프 + 회전 + 떨기 조합)
+  // Dance: sequential combo of moves (jump + spin + shake)
   registerMovement('dance', {
     init(params) {
       return {
@@ -1132,18 +1132,18 @@ const PetEngine = (() => {
 
       const t = state.elapsed / state.duration;
 
-      // 구간별 다른 동작
+      // Different moves per phase
       if (t < 0.25) {
-        // 구간 1: 좌우 스윙
+        // Phase 1: left-right swing
         const swingX = Math.sin(state.phase * 8) * 20;
         ctx.setPos(state.originX + swingX, state.originY);
         ctx.setFlip(swingX < 0);
       } else if (t < 0.5) {
-        // 구간 2: 상하 바운스
+        // Phase 2: up-down bounce
         const bounceY = Math.abs(Math.sin(state.phase * 6)) * -30;
         ctx.setPos(state.originX, state.originY + bounceY);
       } else if (t < 0.75) {
-        // 구간 3: 작은 원
+        // Phase 3: small circle
         const angle = state.phase * 10;
         ctx.setPos(
           state.originX + Math.cos(angle) * 15,
@@ -1151,7 +1151,7 @@ const PetEngine = (() => {
         );
         ctx.setFlip(Math.cos(angle) < 0);
       } else {
-        // 구간 4: 빠른 좌우 떨기 (피니시)
+        // Phase 4: fast horizontal shake (finish)
         const shake = Math.sin(state.phase * 20) * 6 * (1 - t);
         ctx.setPos(state.originX + shake, state.originY);
       }
@@ -1163,15 +1163,15 @@ const PetEngine = (() => {
   });
 
   // ===================================
-  //  메인 루프
+  //  Main loop
   // ===================================
 
   let frameId = null;
 
   /**
-   * 엔진 시작: requestAnimationFrame 루프 가동
+   * Start engine: begin requestAnimationFrame loop
    */
-  let lastLoopTimestamp = 0;  // 이전 루프 타임스탬프 (deltaTime 계산용)
+  let lastLoopTimestamp = 0;  // Previous loop timestamp (for deltaTime calculation)
 
   function start() {
     if (running) return;
@@ -1182,16 +1182,16 @@ const PetEngine = (() => {
     function loop(timestamp) {
       if (!running) return;
 
-      // 커스텀 이동용 deltaTime 계산
+      // Calculate deltaTime for custom movement
       const deltaTime = timestamp - lastLoopTimestamp;
       lastLoopTimestamp = timestamp;
 
       const state = StateMachine.update();
 
-      // 애니메이션을 먼저 갱신 → animFrameChanged 플래그 설정
+      // Update animation first -> set animFrameChanged flag
       updateAnimation(state, timestamp);
 
-      // 커스텀 이동이 활성 상태이면 전용 업데이트 실행
+      // Run dedicated update if custom movement is active
       if (activeCustomMovement && state === 'custom') {
         updateCustomMovement(deltaTime);
         clampPosition();
@@ -1200,7 +1200,7 @@ const PetEngine = (() => {
         moveForState(state);
       }
 
-      // 프레임 전환 플래그 리셋 (다음 프레임까지 대기)
+      // Reset frame transition flag (wait until next frame)
       animFrameChanged = false;
       frameId = requestAnimationFrame(loop);
     }
@@ -1208,23 +1208,23 @@ const PetEngine = (() => {
   }
 
   /**
-   * 엔진 정지
+   * Stop engine
    */
   function stop() {
     running = false;
     if (frameId) cancelAnimationFrame(frameId);
   }
 
-  // --- 공개 API ---
+  // --- Public API ---
   return {
     init, start, stop,
     getPosition, setPosition, setEdge, setDirection,
     snapToNearestEdge, setSpeedMultiplier,
     moveForState, updateAnimation,
-    // 물리 기반 이동
+    // Physics-based movement
     jumpTo, startRappel, releaseThread, moveToCenter,
     setSurfaces, getThread, startFalling,
-    // 커스텀 이동 패턴 시스템
+    // Custom movement pattern system
     registerMovement, unregisterMovement,
     executeCustomMovement, stopCustomMovement,
     getRegisteredMovements,