@fmsim/machine 2.0.0-beta.10 → 2.0.0-beta.100

package/src/factories/agv-3d.ts

@@ -10,7 +10,7 @@
  * Based on operato-scene Vehicle3D, adapted for fmsim:
  *   - extends RealObjectGroup (Conveyor3D와 동일 패턴)
  *   - statusColor from MCSStatusMixin
- *   - 바닥 원점 (y=0~depth)
+ *   - 볼륨 중심 원점 (things-scene 기본 컨벤션) - mesh 로컬 [-d/2, +d/2]
  */
 
 import * as THREE from 'three'
@@ -30,10 +30,6 @@ export class AGV3D extends RealObjectGroup {
     return depth || TRANSPORT_SURFACE_HEIGHT
   }
 
-  protected get syncZPosOffset(): number {
-    return 0
-  }
-
   private resolveColor(): number {
     const comp = this.component as any
 
@@ -41,14 +37,14 @@ export class AGV3D extends RealObjectGroup {
     //    '#F0F0F0'은 상태 미설정 시 기본 fallback — 무시하고 defaultColor 사용
     try {
       const sc = comp.statusColor
-      if (typeof sc === 'string' && sc && sc.toUpperCase() !== '#F0F0F0') return new THREE.Color(sc).getHex()
+      if (typeof sc === 'string' && sc && sc.toUpperCase() !== '#F0F0F0' && sc !== 'transparent') return new THREE.Color(sc).getHex()
     } catch {
       /* statusColor 미구현 시 무시 */
     }
 
     // 2) state.fillStyle fallback
     const { fillStyle } = this.component.state
-    if (fillStyle && typeof fillStyle === 'string') {
+    if (fillStyle && typeof fillStyle === 'string' && fillStyle !== 'transparent') {
       try {
         return new THREE.Color(fillStyle).getHex()
       } catch {
@@ -118,7 +114,8 @@ export class AGV3D extends RealObjectGroup {
     plat.receiveShadow = true
 
     this._ownMeshes = [bumper, body, plat]
-    for (const m of this._ownMeshes) this.object3d.add(m)
+    // ownGroup이 center-origin ↔ bottom-up 좌표계 변환을 자동 처리
+    for (const m of this._ownMeshes) this.components3D.add(m)
   }
 
   updateDimension() {}
@@ -126,7 +123,7 @@ export class AGV3D extends RealObjectGroup {
   update() {
     // 자신의 mesh만 제거 (Carrier 등 자식 컴포넌트 3D 보존)
     for (const m of this._ownMeshes) {
-      this.object3d.remove(m)
+      this.components3D.remove(m)
       disposeObject3D(m)
     }
     this._ownMeshes = []
@@ -150,10 +147,12 @@ export class AGV3D extends RealObjectGroup {
 
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
     if ('width' in after || 'height' in after || 'depth' in after ||
-        'fillStyle' in after || 'strokeStyle' in after || 'id' in after) {
+        'fillStyle' in after || 'strokeStyle' in after || 'id' in after ||
+        'EMPTYTYPE' in after || 'CARRIERSTATUS' in after) {
       this.update()
       return
     }
+
     super.onchange(after, before)
   }
 }

package/src/factories/conveyor-3d.ts

@@ -16,23 +16,20 @@ import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUti
 import { RealObjectGroup, registerRealObjectFactory } from '@hatiolab/things-scene'
 import type { Component } from '@hatiolab/things-scene'
 import { TRANSPORT_SURFACE_HEIGHT } from './machine-3d.js'
+import { Z_FMSIM } from './z-priority'
 
 const FRAME_COLOR = 0x888899
 const ROLLER_COLOR = 0xaaaabc
 const DEFAULT_COLOR = 0x999999
 
 export class Conveyor3D extends RealObjectGroup {
+  get zPriority(): number { return Z_FMSIM.CONVEYOR }
+
   get effectiveDepth(): number {
     const { depth } = this.component.state
     return depth || TRANSPORT_SURFACE_HEIGHT
   }
 
-  // group origin = 바닥 (y=0). MCSRealObject3D와 동일 컨벤션.
-  // 기하는 build()에서 y=0(바닥)~y=depth(상단) 범위로 배치.
-  protected get syncZPosOffset(): number {
-    return 0
-  }
-
   private resolveColor(): number {
     const comp = this.component as any
 
@@ -40,14 +37,14 @@ export class Conveyor3D extends RealObjectGroup {
     //    '#F0F0F0'은 상태 미설정 시 기본 fallback — 무시하고 defaultColor 사용
     try {
       const sc = comp.statusColor
-      if (typeof sc === 'string' && sc && sc.toUpperCase() !== '#F0F0F0') return new THREE.Color(sc).getHex()
+      if (typeof sc === 'string' && sc && sc.toUpperCase() !== '#F0F0F0' && sc !== 'transparent') return new THREE.Color(sc).getHex()
     } catch {
       /* statusColor 미구현 시 무시 */
     }
 
     // 2) state.fillStyle fallback
     const { fillStyle } = this.component.state
-    if (fillStyle && typeof fillStyle === 'string') {
+    if (fillStyle && typeof fillStyle === 'string' && fillStyle !== 'transparent') {
       try {
         return new THREE.Color(fillStyle).getHex()
       } catch {
@@ -61,16 +58,31 @@ export class Conveyor3D extends RealObjectGroup {
   build() {
     super.build()
 
-    const { width, height, conveyorType } = this.component.state
+    const { width: rawWidth, height: rawHeight, conveyorType, orientation } = this.component.state
     const depth = this.effectiveDepth
-    if (!width || !height) return
+    if (!rawWidth || !rawHeight) return
+
+    // orientation: 'horizontal' = 롤러가 Z축(세로), 'vertical' = 롤러가 X축(가로)
+    // default = 긴 방향에 수직 (긴 축을 따라 이송)
+    const isVertical = orientation === 'vertical' ? true
+      : orientation === 'horizontal' ? false
+      : rawWidth < rawHeight  // default: 세로가 길면 롤러는 가로(X축)
+    // isVertical=true → 롤러 축이 X(가로), 이송 방향이 Z(세로)
+    // isVertical=false → 롤러 축이 Z(세로), 이송 방향이 X(가로)
+    const width = rawWidth
+    const height = rawHeight
 
     // 2D와 동일 로직으로 rollWidth 산출
     const rollWidth = Math.max(10, Math.min(width, height) / 2)
     const rollerDiameter = Math.max(rollWidth, 2)
     const frameH = Math.min(rollerDiameter, depth)
     const legH = Math.max(depth - frameH, 0)
-    const railW = Math.max(height * 0.06, 2)
+
+    // isVertical일 때 이송 방향이 Z축: 레일은 Z축을 따라, 벨트폭은 width
+    // !isVertical일 때 이송 방향이 X축: 레일은 X축을 따라, 벨트폭은 height
+    const beltWidth = isVertical ? width : height
+    const railLen = isVertical ? height : width
+    const railW = Math.max(beltWidth * 0.06, 2)
     const legThickness = Math.max(railW * 0.8, 2)
 
     const frameMaterial = new THREE.MeshStandardMaterial({
@@ -84,11 +96,21 @@ export class Conveyor3D extends RealObjectGroup {
     const frameGeometries: THREE.BufferGeometry[] = []
     const railY = depth - frameH / 2
 
-    // Side rails (along X)
-    for (const zSign of [-1, 1]) {
-      const rail = new THREE.BoxGeometry(width, frameH, railW)
-      rail.translate(0, railY, zSign * (height / 2 - railW / 2))
-      frameGeometries.push(rail)
+    // Side rails — 이송 방향을 따라, 벨트 양측에 배치
+    if (isVertical) {
+      // 레일이 Z축(세로)을 따라, ±X에 배치
+      for (const xSign of [-1, 1]) {
+        const rail = new THREE.BoxGeometry(railW, frameH, height)
+        rail.translate(xSign * (width / 2 - railW / 2), railY, 0)
+        frameGeometries.push(rail)
+      }
+    } else {
+      // 레일이 X축(가로)을 따라, ±Z에 배치
+      for (const zSign of [-1, 1]) {
+        const rail = new THREE.BoxGeometry(width, frameH, railW)
+        rail.translate(0, railY, zSign * (height / 2 - railW / 2))
+        frameGeometries.push(rail)
+      }
     }
 
     // 4 legs at corners
@@ -96,49 +118,66 @@ export class Conveyor3D extends RealObjectGroup {
       const legTopY = depth - frameH
       const legCenterY = legTopY - legH / 2
 
+      // 다리 위치: 레일 안쪽에 정렬
+      const legXPos = isVertical ? (width / 2 - railW / 2) : (width / 2 - legThickness / 2)
+      const legZPos = isVertical ? (height / 2 - legThickness / 2) : (height / 2 - railW / 2)
+
       for (const xSign of [-1, 1]) {
         for (const zSign of [-1, 1]) {
-          const lx = xSign * (width / 2 - legThickness / 2)
-          const lz = zSign * (height / 2 - railW / 2)
           const leg = new THREE.BoxGeometry(legThickness, legH, legThickness)
-          leg.translate(lx, legCenterY, lz)
+          leg.translate(xSign * legXPos, legCenterY, zSign * legZPos)
           frameGeometries.push(leg)
         }
       }
 
-      // Cross-bracing: 앞뒤 다리 연결 (Z 방향)
+      // Cross-bracing
       const braceH = legThickness * 0.6
       const braceW = legThickness * 0.6
-      const braceLen = height - railW
       const braceY = legTopY - legH * 0.35
 
-      for (const xSign of [-1, 1]) {
-        const brace = new THREE.BoxGeometry(braceW, braceH, braceLen)
-        brace.translate(xSign * (width / 2 - legThickness / 2), braceY, 0)
-        frameGeometries.push(brace)
+      // 이송 방향 브레이스 (레일과 평행)
+      if (isVertical) {
+        for (const xSign of [-1, 1]) {
+          const brace = new THREE.BoxGeometry(braceW, braceH, height - legThickness)
+          brace.translate(xSign * legXPos, braceY, 0)
+          frameGeometries.push(brace)
+        }
+      } else {
+        for (const zSign of [-1, 1]) {
+          const brace = new THREE.BoxGeometry(width - legThickness, braceH, braceW)
+          brace.translate(0, braceY, zSign * legZPos)
+          frameGeometries.push(brace)
+        }
       }
 
-      // Cross-bracing: 좌우 다리 연결 (X 방향)
-      const braceLenX = width - legThickness
-      for (const zSign of [-1, 1]) {
-        const brace = new THREE.BoxGeometry(braceLenX, braceH, braceW)
-        brace.translate(0, braceY, zSign * (height / 2 - railW / 2))
-        frameGeometries.push(brace)
+      // 벨트폭 방향 브레이스 (레일과 수직)
+      if (isVertical) {
+        for (const zSign of [-1, 1]) {
+          const brace = new THREE.BoxGeometry(width - railW, braceH, braceW)
+          brace.translate(0, braceY, zSign * legZPos)
+          frameGeometries.push(brace)
+        }
+      } else {
+        for (const xSign of [-1, 1]) {
+          const brace = new THREE.BoxGeometry(braceW, braceH, height - railW)
+          brace.translate(xSign * legXPos, braceY, 0)
+          frameGeometries.push(brace)
+        }
       }
     }
 
     const frameMesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(frameGeometries), frameMaterial)
     frameMesh.castShadow = true
     frameMesh.receiveShadow = true
-    this.object3d.add(frameMesh)
+    this.components3D.add(frameMesh)
 
     // --- Rollers, Belt, or Rails ---
     if (conveyorType === 'rail') {
-      this.buildRails(width, height, depth, frameH, railW)
+      this.buildRails(width, height, depth, frameH, railW, isVertical)
     } else if (conveyorType === 'belt') {
-      this.buildBelt(width, height, depth, frameH, railW)
+      this.buildBelt(width, height, depth, frameH, railW, isVertical)
     } else {
-      this.buildRollers(width, height, depth, frameH, railW, rollWidth)
+      this.buildRollers(width, height, depth, frameH, railW, rollWidth, isVertical)
     }
   }
 
@@ -148,28 +187,45 @@ export class Conveyor3D extends RealObjectGroup {
     depth: number,
     frameH: number,
     railW: number,
-    rollWidth: number
+    rollWidth: number,
+    isVertical: boolean = false
   ) {
     const rollerRadius = Math.max(rollWidth / 8, 1)
-    const rollerLength = height - railW * 2 - 0.5
     const diameter = rollerRadius * 2
-    // 롤러 간 최소 간격 (z-fighting 방지용 미세 갭만)
     const step = diameter * 1.05
-    // 롤러 상단 = 이송 표면 (y=depth)
     const rollerY = depth - rollerRadius
     const color = this.resolveColor()
 
     const rollerGeometries: THREE.BufferGeometry[] = []
-    const count = Math.max(1, Math.floor(width / step))
-    const totalSpan = (count - 1) * step
-    const startX = -totalSpan / 2
-
-    for (let i = 0; i < count; i++) {
-      const x = startX + i * step
-      const roller = new THREE.CylinderGeometry(rollerRadius, rollerRadius, rollerLength, 16)
-      roller.rotateX(Math.PI / 2)
-      roller.translate(x, rollerY, 0)
-      rollerGeometries.push(roller)
+
+    if (isVertical) {
+      // 롤러 축 = X축(가로), 이송 방향 = Z축(세로)
+      const rollerLength = width - railW * 2 - 0.5
+      const count = Math.max(1, Math.floor(height / step))
+      const totalSpan = (count - 1) * step
+      const startZ = -totalSpan / 2
+
+      for (let i = 0; i < count; i++) {
+        const z = startZ + i * step
+        const roller = new THREE.CylinderGeometry(rollerRadius, rollerRadius, rollerLength, 16)
+        roller.rotateZ(Math.PI / 2)
+        roller.translate(0, rollerY, z)
+        rollerGeometries.push(roller)
+      }
+    } else {
+      // 롤러 축 = Z축(세로), 이송 방향 = X축(가로) — 기존 동작
+      const rollerLength = height - railW * 2 - 0.5
+      const count = Math.max(1, Math.floor(width / step))
+      const totalSpan = (count - 1) * step
+      const startX = -totalSpan / 2
+
+      for (let i = 0; i < count; i++) {
+        const x = startX + i * step
+        const roller = new THREE.CylinderGeometry(rollerRadius, rollerRadius, rollerLength, 16)
+        roller.rotateX(Math.PI / 2)
+        roller.translate(x, rollerY, 0)
+        rollerGeometries.push(roller)
+      }
     }
 
     if (rollerGeometries.length > 0) {
@@ -178,26 +234,35 @@ export class Conveyor3D extends RealObjectGroup {
         new THREE.MeshStandardMaterial({ color, metalness: 0.9, roughness: 0.2 })
       )
       rollerMesh.castShadow = true
-      this.object3d.add(rollerMesh)
+      this.components3D.add(rollerMesh)
     }
   }
 
-  private buildBelt(width: number, height: number, depth: number, frameH: number, railW: number) {
+  private buildBelt(width: number, height: number, depth: number, frameH: number, railW: number, isVertical: boolean = false) {
     const drumRadius = frameH * 0.38
-    const drumLength = height - railW * 2
     const beltY = depth - drumRadius
     const color = this.resolveColor()
 
+    // 이송 방향 길이와 벨트폭
+    const transportLen = isVertical ? height : width
+    const beltWidth = isVertical ? width : height
+    const drumLength = beltWidth - railW * 2
+
     // Two end drums
     const drumGeometries: THREE.BufferGeometry[] = []
     const drumInset = drumRadius * 1.5
-    const leftDrumX = -width / 2 + drumInset
-    const rightDrumX = width / 2 - drumInset
+    const drum1 = -transportLen / 2 + drumInset
+    const drum2 = transportLen / 2 - drumInset
 
-    for (const dx of [leftDrumX, rightDrumX]) {
+    for (const dp of [drum1, drum2]) {
       const drum = new THREE.CylinderGeometry(drumRadius, drumRadius, drumLength, 16)
-      drum.rotateX(Math.PI / 2)
-      drum.translate(dx, beltY, 0)
+      if (isVertical) {
+        drum.rotateZ(Math.PI / 2)
+        drum.translate(0, beltY, dp)
+      } else {
+        drum.rotateX(Math.PI / 2)
+        drum.translate(dp, beltY, 0)
+      }
       drumGeometries.push(drum)
     }
 
@@ -206,7 +271,7 @@ export class Conveyor3D extends RealObjectGroup {
       new THREE.MeshStandardMaterial({ color: ROLLER_COLOR, metalness: 0.9, roughness: 0.2 })
     )
     drumMesh.castShadow = true
-    this.object3d.add(drumMesh)
+    this.components3D.add(drumMesh)
 
     // Belt surface
     const beltThickness = drumRadius * 0.12
@@ -217,18 +282,20 @@ export class Conveyor3D extends RealObjectGroup {
     })
 
     // Flat belt top surface spanning between drums
-    const flatLen = rightDrumX - leftDrumX
-    const flatGeo = new THREE.BoxGeometry(flatLen, beltThickness, drumLength)
+    const flatLen = drum2 - drum1
+    const flatGeo = isVertical
+      ? new THREE.BoxGeometry(drumLength, beltThickness, flatLen)
+      : new THREE.BoxGeometry(flatLen, beltThickness, drumLength)
     const flatMesh = new THREE.Mesh(flatGeo, beltMaterial)
     flatMesh.position.set(0, beltY + drumRadius, 0)
     flatMesh.castShadow = true
-    this.object3d.add(flatMesh)
+    this.components3D.add(flatMesh)
 
     // Belt wrap around drums (segmented half-cylinder)
     const wrapSegments = 12
-    for (const [dx, angleStart] of [
-      [leftDrumX, Math.PI / 2],
-      [rightDrumX, -Math.PI / 2],
+    for (const [dp, angleStart] of [
+      [drum1, Math.PI / 2],
+      [drum2, -Math.PI / 2],
     ] as [number, number][]) {
       const wrapGeometries: THREE.BufferGeometry[] = []
       for (let i = 0; i < wrapSegments; i++) {
@@ -236,36 +303,47 @@ export class Conveyor3D extends RealObjectGroup {
         const a1 = angleStart + (Math.PI * (i + 1)) / wrapSegments
         const r = drumRadius + beltThickness / 2
 
-        const x0 = dx + Math.cos(a0) * r
+        const p0 = dp + Math.cos(a0) * r
         const y0 = beltY + Math.sin(a0) * r
-        const x1 = dx + Math.cos(a1) * r
+        const p1 = dp + Math.cos(a1) * r
         const y1 = beltY + Math.sin(a1) * r
 
-        const segLen = Math.sqrt((x1 - x0) ** 2 + (y1 - y0) ** 2) * 1.05
-        const segAngle = Math.atan2(y1 - y0, x1 - x0)
-
-        const seg = new THREE.BoxGeometry(segLen, beltThickness, drumLength)
-        seg.rotateZ(segAngle)
-        seg.translate((x0 + x1) / 2, (y0 + y1) / 2, 0)
-        wrapGeometries.push(seg)
+        const segLen = Math.sqrt((p1 - p0) ** 2 + (y1 - y0) ** 2) * 1.05
+        const segAngle = Math.atan2(y1 - y0, p1 - p0)
+
+        if (isVertical) {
+          const seg = new THREE.BoxGeometry(drumLength, beltThickness, segLen)
+          seg.rotateX(-segAngle)
+          seg.translate(0, (y0 + y1) / 2, (p0 + p1) / 2)
+          wrapGeometries.push(seg)
+        } else {
+          const seg = new THREE.BoxGeometry(segLen, beltThickness, drumLength)
+          seg.rotateZ(segAngle)
+          seg.translate((p0 + p1) / 2, (y0 + y1) / 2, 0)
+          wrapGeometries.push(seg)
+        }
       }
       const wrapMesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(wrapGeometries), beltMaterial)
       wrapMesh.castShadow = true
-      this.object3d.add(wrapMesh)
+      this.components3D.add(wrapMesh)
     }
 
     // Flat belt bottom (return path)
-    const bottomGeo = new THREE.BoxGeometry(flatLen, beltThickness, drumLength * 0.85)
+    const bottomGeo = isVertical
+      ? new THREE.BoxGeometry(drumLength * 0.85, beltThickness, flatLen)
+      : new THREE.BoxGeometry(flatLen, beltThickness, drumLength * 0.85)
     const bottomMesh = new THREE.Mesh(bottomGeo, beltMaterial)
     bottomMesh.position.set(0, beltY - drumRadius, 0)
-    this.object3d.add(bottomMesh)
+    this.components3D.add(bottomMesh)
   }
 
-  private buildRails(width: number, height: number, depth: number, frameH: number, railW: number) {
+  private buildRails(width: number, height: number, depth: number, frameH: number, railW: number, isVertical: boolean = false) {
     const color = this.resolveColor()
     const railHeight = frameH * 0.3
     const railY = depth - railHeight / 2
-    const innerWidth = height - railW * 2
+    const beltWidth = isVertical ? width : height
+    const transportLen = isVertical ? height : width
+    const innerWidth = beltWidth - railW * 2
     // 두 레일 간격: 내부 폭의 60%
     const railSpacing = innerWidth * 0.6
 
@@ -277,16 +355,24 @@ export class Conveyor3D extends RealObjectGroup {
 
     const railGeometries: THREE.BufferGeometry[] = []
 
-    // Two parallel rails running along X axis
-    for (const zSign of [-1, 1]) {
-      const rail = new THREE.BoxGeometry(width - railW * 2, railHeight, railW * 0.8)
-      rail.translate(0, railY, zSign * (railSpacing / 2))
-      railGeometries.push(rail)
+    // Two parallel rails running along transport direction
+    if (isVertical) {
+      for (const xSign of [-1, 1]) {
+        const rail = new THREE.BoxGeometry(railW * 0.8, railHeight, transportLen - railW * 2)
+        rail.translate(xSign * (railSpacing / 2), railY, 0)
+        railGeometries.push(rail)
+      }
+    } else {
+      for (const zSign of [-1, 1]) {
+        const rail = new THREE.BoxGeometry(transportLen - railW * 2, railHeight, railW * 0.8)
+        rail.translate(0, railY, zSign * (railSpacing / 2))
+        railGeometries.push(rail)
+      }
     }
 
     const railMesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(railGeometries), railMaterial)
     railMesh.castShadow = true
-    this.object3d.add(railMesh)
+    this.components3D.add(railMesh)
   }
 
   updateDimension() {}
@@ -295,6 +381,7 @@ export class Conveyor3D extends RealObjectGroup {
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
     if (
       'conveyorType' in after ||
+      'orientation' in after ||
       'width' in after ||
       'height' in after ||
       'depth' in after ||

package/src/factories/crane-3d.ts

@@ -22,13 +22,27 @@ const FORK_COLOR = 0x999999
 const DEFAULT_BODY_COLOR = 0xcc8844
 
 export class Crane3D extends RealObjectGroup {
+  /** 캐리지 포크 group — Crane.state.forkZ (0~100) 가 변하면 position.y 만 lerp.
+   *  build() 시 inner 에 add 되고, *_mastBaseY 와 mastH 를 함께 보관* 해서
+   *  setForkZ 가 비율 계산에 사용. */
+  private forkGroup?: THREE.Group
+  private forkMastBaseY = 0
+  private forkMastH = 0
+
   get effectiveDepth(): number {
     const { depth } = this.component.state
     return depth || 5 * TRANSPORT_SURFACE_HEIGHT - 2
   }
 
-  protected get syncZPosOffset(): number {
-    return 0
+  /**
+   * 0~100 정규화 z (= state.forkZ) 를 mast 높이 비율로 변환해서 포크 group 의
+   * three-up y 위치 갱신. build() 가 안 끝났으면 noop — build 가 forkZ 를 다시
+   * 반영하면서 끝난다.
+   */
+  applyForkZ(z: number): void {
+    if (!this.forkGroup) return
+    const clamped = Math.max(0, Math.min(100, Number(z) || 0))
+    this.forkGroup.position.y = this.forkMastBaseY + (clamped / 100) * this.forkMastH
   }
 
   private resolveColor(): number {
@@ -62,6 +76,8 @@ export class Crane3D extends RealObjectGroup {
     const d = this.effectiveDepth
     if (!w || !h) return
 
+    const inner = this.components3D
+
     // 높이 배분: 하단 클램프 4%, 마스트 92%, 상단 클램프 4%
     const clampH = d * 0.04
     const mastH = d * 0.92
@@ -81,7 +97,7 @@ export class Crane3D extends RealObjectGroup {
     const bottomClamp = new THREE.Mesh(bottomClampGeo, clampMat)
     bottomClamp.position.y = clampH / 2
     bottomClamp.castShadow = true
-    this.object3d.add(bottomClamp)
+    inner.add(bottomClamp)
 
     // ── 2. 수직 마스트 (좌우 기둥 + 상·하 가로 연결 바) ──
     const mastBaseY = clampH
@@ -115,10 +131,12 @@ export class Crane3D extends RealObjectGroup {
 
     const mastMesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(mastGeometries), mastMat)
     mastMesh.castShadow = true
-    this.object3d.add(mastMesh)
+    inner.add(mastMesh)
 
-    // ── 3. 캐리지 포크 (마스트 40% 높이, 양쪽으로 뻗는 포크 암) ──
-    const forkY = mastBaseY + mastH * 0.4
+    // ── 3. 캐리지 포크 (별도 group — state.forkZ 변경 시 group.position.y lerp) ──
+    // 포크 geometry 는 *_mastBaseY 기준 local 0 에 둠* — 즉 group.position.y = 0
+    // 일 때 mast 바닥 자리에. forkZ 0~100 에 따라 group.position.y 만 변경하면
+    // mast 따라 위/아래 이동. mesh 재구축 불필요.
     const forkMat = new THREE.MeshStandardMaterial({
       color: FORK_COLOR,
       roughness: 0.4,
@@ -127,15 +145,13 @@ export class Crane3D extends RealObjectGroup {
 
     const forkGeometries: THREE.BufferGeometry[] = []
 
-    // 캐리지 중심 플레이트 (마스트에 부착, 양쪽 포크의 베이스)
     const plateW = w * 0.9
     const plateH = d * 0.08
     const plateD = pillarThick * 0.8
     const centerPlate = new THREE.BoxGeometry(plateW, plateH, plateD)
-    centerPlate.translate(0, forkY + plateH / 2, 0)
+    centerPlate.translate(0, plateH / 2, 0) // local 0 = mast 바닥
     forkGeometries.push(centerPlate)
 
-    // 양쪽 포크 암 (좌/우 선반 방향으로 뻗음)
     const armW = pillarThick * 0.6
     const armH = plateH * 0.4
     const armD = h * 0.6
@@ -144,31 +160,56 @@ export class Crane3D extends RealObjectGroup {
     for (const zSign of [-1, 1]) {
       for (const xSign of [-1, 1]) {
         const arm = new THREE.BoxGeometry(armW, armH, armD)
-        arm.translate(xSign * (armSpacing / 2), forkY + armH / 2, zSign * (plateD / 2 + armD / 2))
+        arm.translate(xSign * (armSpacing / 2), armH / 2, zSign * (plateD / 2 + armD / 2))
         forkGeometries.push(arm)
       }
     }
 
     const forkMesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(forkGeometries), forkMat)
     forkMesh.castShadow = true
-    this.object3d.add(forkMesh)
+
+    const forkGroup = new THREE.Group()
+    forkGroup.add(forkMesh)
+    inner.add(forkGroup)
+    this.forkGroup = forkGroup
+    this.forkMastBaseY = mastBaseY
+    // forkZ=100 시점에 mast 의 *_위쪽 한계*. 포크 자체 두께 (plateH) 만큼은 마스트
+    // 안에 머무르도록 limit 보정 — 그렇지 않으면 forkZ=100 일 때 포크가 상단
+    // 클램프와 충돌. mastH * 0.92 로 약간 보수적 (= 마스트 본체 92% 까지만 이동).
+    this.forkMastH = mastH * 0.92
+
+    // 초기 forkZ 반영 — state.forkZ 가 이미 set 되어 있으면 그 위치에 배치
+    const initialForkZ = Number((this.component.state as any).forkZ)
+    this.applyForkZ(Number.isFinite(initialForkZ) ? initialForkZ : 0)
 
     // ── 4. 상단 클램프 (천장 레일에 물리는 가이드부) ──
     const topClampGeo = new THREE.BoxGeometry(clampW, clampH, clampD)
     const topClamp = new THREE.Mesh(topClampGeo, clampMat)
     topClamp.position.y = mastBaseY + mastH + clampH / 2
     topClamp.castShadow = true
-    this.object3d.add(topClamp)
+    inner.add(topClamp)
   }
 
   updateDimension() {}
   updateAlpha() {}
 
+  /** build() 직전 호출. forkGroup 참조를 깨끗이 비워둔다 — 새 build 가 다시 set. */
+  clear() {
+    this.forkGroup = undefined
+    super.clear()
+  }
+
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
     if ('width' in after || 'height' in after || 'depth' in after || 'fillStyle' in after || 'strokeStyle' in after) {
       this.update()
       return
     }
+    // forkZ 는 mesh 재구축 없이 group.position.y 만 갱신. 같은 onchange 에서
+    // left/top 도 함께 변경될 수 있으므로 super 도 반드시 호출해 본체 transform
+    // 갱신 path (state.left/top → obj3d.position.x/z) 가 동작하게 함.
+    if ('forkZ' in after) {
+      this.applyForkZ(Number(after.forkZ) || 0)
+    }
     super.onchange(after, before)
   }
 }