@fmsim/machine 1.0.83 → 2.0.0-beta.2

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

@@ -0,0 +1,361 @@
+/**
+ * MCS 설비 컴포넌트 3D 팩토리
+ *
+ * 10,000+ 인스턴스를 위한 최소 폴리곤 설계:
+ *   - 컴포넌트당 단일 Mesh (draw call 최소화)
+ *   - BoxGeometry / ExtrudeGeometry(hexagon) 만 사용
+ *   - Machine: 높은 depth, 컨테이너는 반투명
+ *   - Unit: 낮은 depth, 불투명
+ */
+
+import * as THREE from 'three'
+import { RealObjectGroup, registerRealObjectFactory } from '@hatiolab/things-scene'
+import type { Component } from '@hatiolab/things-scene'
+
+// ── 설정 타입 ────────────────────────────────────────────
+
+interface MCS3DConfig {
+  /** state.depth 미설정 시 기본 depth.
+   *  defaultDepth > 0이면 절대값, 아니면 min(w,h) * depthRatio */
+  depthRatio: number
+  defaultDepth?: number
+  /** true이면 syncZPosOffset = TRANSPORT_SURFACE_HEIGHT */
+  defaultZPosFromParent?: boolean
+  /** 1.0 = 불투명, 0.35 = 반투명 컨테이너 */
+  opacity: number
+  metalness: number
+  roughness: number
+  /** statusColor 미사용 시 기본 색상 */
+  defaultColor: number
+  /** 'box' | 'hexagon' */
+  shape: 'box' | 'hexagon'
+  /** mesh 생성 전 가시성 판정 — false 반환 시 mesh 미생성 */
+  isVisible?: (component: Component) => boolean
+  /** 부모 대비 크기 비율 (기본 1.0). < 1이면 부모 중심에 배치. */
+  sizeRatio?: number
+}
+
+/**
+ * 포트 기본 높이 (절대값).
+ * 모든 이송장치의 상단 높이 = 이 값.
+ * 캐리어가 이송장치 간 높이 차 없이 이동할 수 있는 기준 높이.
+ */
+export const TRANSPORT_SURFACE_HEIGHT = 30
+
+const DEFAULTS: MCS3DConfig = {
+  depthRatio: 0.5,
+  opacity: 1.0,
+  metalness: 0.3,
+  roughness: 0.7,
+  defaultColor: 0xaabbcc,
+  shape: 'box',
+}
+
+// ── 3D 오브젝트 ──────────────────────────────────────────
+
+class MCSRealObject3D extends RealObjectGroup {
+  private _config: MCS3DConfig
+
+  constructor(component: Component, config: MCS3DConfig) {
+    super(component)
+    this._config = config
+  }
+
+  // width, height 절대값 (음수 값은 양수로 취급)
+  private get absSize(): { w: number; h: number } {
+    const { width = 10, height = 10 } = this.component.state
+    return { w: Math.abs(width), h: Math.abs(height) }
+  }
+
+  get effectiveDepth(): number {
+    const { depth } = this.component.state
+    if (depth) return depth
+    if (this._config.defaultDepth) return this._config.defaultDepth
+    const { w, h } = this.absSize
+    return Math.min(w, h) * this._config.depthRatio
+  }
+
+  protected get syncZPosOffset(): number {
+    // Port: 이송 표면 높이에 배치
+    if (this._config.defaultZPosFromParent) {
+      return TRANSPORT_SURFACE_HEIGHT
+    }
+    // Carrier: Port 안이면 중앙, 그 외 컨테이너면 상단 위
+    if (this._config.sizeRatio && this._config.sizeRatio < 1) {
+      const parentType = this.component.parent?.state?.type
+      if (parentType === 'Port' || parentType === 'Shelf' || parentType === 'OHT' || parentType === 'Shuttle') {
+        return 0
+      }
+      return TRANSPORT_SURFACE_HEIGHT
+    }
+    return 0
+  }
+
+  // 컴포넌트의 상태 색상(statusColor) 또는 fillStyle → Three.js 색상 변환
+  private resolveColor(): number {
+    const comp = this.component as any
+
+    // 1) MCSStatusMixin.statusColor (legend 기반 상태 색상)
+    //    '#F0F0F0'은 상태 미설정 시 기본 fallback — 무시하고 defaultColor 사용
+    try {
+      const sc = comp.statusColor
+      if (typeof sc === 'string' && sc && sc.toUpperCase() !== '#F0F0F0') return new THREE.Color(sc).getHex()
+    } catch {
+      /* statusColor 미구현 시 무시 */
+    }
+
+    // 2) state.fillStyle fallback
+    const { fillStyle } = this.component.state
+    if (fillStyle && typeof fillStyle === 'string') {
+      try {
+        return new THREE.Color(fillStyle).getHex()
+      } catch {
+        /* 파싱 실패 시 무시 */
+      }
+    }
+
+    return this._config.defaultColor
+  }
+
+  // ── Geometry helpers ──
+
+  /**
+   * 바닥면(-Y 방향) 삼각형 제거: z-fighting 근본 해결.
+   * 바닥면이 없으면 floor grid와 겹칠 면 자체가 없어진다.
+   */
+  private removeBottomFace(geometry: THREE.BufferGeometry): THREE.BufferGeometry {
+    const posAttr = geometry.getAttribute('position')
+    const normAttr = geometry.getAttribute('normal')
+    const index = geometry.getIndex()
+
+    if (!posAttr || !normAttr || !index) return geometry
+
+    const newIndices: number[] = []
+    const normalY = new THREE.Vector3()
+
+    for (let i = 0; i < index.count; i += 3) {
+      const a = index.getX(i)
+      const b = index.getX(i + 1)
+      const c = index.getX(i + 2)
+
+      // 세 꼭짓점 노말의 Y 성분 평균으로 방향 판단
+      const avgY = (normAttr.getY(a) + normAttr.getY(b) + normAttr.getY(c)) / 3
+
+      // -Y 방향 삼각형 제거 (threshold -0.9: 거의 아래를 향하는 면만)
+      if (avgY > -0.9) {
+        newIndices.push(a, b, c)
+      }
+    }
+
+    geometry.setIndex(newIndices)
+    return geometry
+  }
+
+  // ── Geometry builders ──
+
+  private buildBoxGeometry(w: number, d: number, h: number): THREE.BufferGeometry {
+    const geo = new THREE.BoxGeometry(w, d, h)
+    return this.removeBottomFace(geo)
+  }
+
+  private buildHexagonGeometry(w: number, d: number, h: number): THREE.BufferGeometry {
+    // Buffer의 2D 형태: 좌우 끝이 꺾인 육각형
+    const offset = Math.min(w, h) * 0.2
+    const hw = w / 2
+    const hh = h / 2
+
+    const shape = new THREE.Shape()
+    shape.moveTo(-hw + offset, -hh)
+    shape.lineTo(hw - offset, -hh)
+    shape.lineTo(hw, 0)
+    shape.lineTo(hw - offset, hh)
+    shape.lineTo(-hw + offset, hh)
+    shape.lineTo(-hw, 0)
+    shape.closePath()
+
+    const geo = new THREE.ExtrudeGeometry(shape, {
+      steps: 1,
+      depth: d,
+      bevelEnabled: false,
+    })
+
+    // 중심 정렬 후 Y-up 좌표계 회전 (extrude 축: +Z → +Y)
+    geo.translate(0, 0, -d / 2)
+    geo.rotateX(Math.PI / 2)
+
+    return this.removeBottomFace(geo)
+  }
+
+  // ── Build ──
+
+  build() {
+    super.build()
+
+    // 가시성 판정 — e.g., Carrier는 데이터 없으면 mesh 미생성
+    if (this._config.isVisible && !this._config.isVisible(this.component)) return
+
+    const { w: rawW, h: rawH } = this.absSize
+    const rawDepth = this.effectiveDepth
+    if (!rawW || !rawH) return
+
+    const ratio = this._config.sizeRatio ?? 1.0
+    const w = rawW * ratio
+    const h = rawH * ratio
+    const depth = rawDepth * ratio
+
+    const color = this.resolveColor()
+    const { opacity, metalness, roughness, shape } = this._config
+
+    const geometry =
+      shape === 'hexagon'
+        ? this.buildHexagonGeometry(w, depth, h)
+        : this.buildBoxGeometry(w, depth, h)
+
+    const material = new THREE.MeshStandardMaterial({
+      color,
+      metalness,
+      roughness,
+      opacity,
+      transparent: opacity < 1,
+      side: opacity < 1 ? THREE.DoubleSide : THREE.FrontSide,
+      depthWrite: opacity >= 0.9,
+    })
+    // z-fighting 방지: 바닥면(floor grid)보다 항상 앞에 렌더링
+    material.polygonOffset = true
+    material.polygonOffsetFactor = -1
+    material.polygonOffsetUnit = -1
+
+    const mesh = new THREE.Mesh(geometry, material)
+    // sizeRatio < 1이면 부모 중심에 배치 (rawDepth/2), 아니면 자체 중심 (depth/2)
+    mesh.position.y = ratio < 1 ? rawDepth / 2 : depth / 2
+    mesh.castShadow = true
+    mesh.receiveShadow = true
+    this.object3d.add(mesh)
+  }
+
+  // ── Change handling ──
+
+  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 // Carrier: CARRIERNAME 변경 시 가시성 재판정
+    ) {
+      this.update()
+      return
+    }
+
+    super.onchange(after, before)
+  }
+
+  // RealObjectGroup 기본 동작 비활성화 (update()에서 일괄 처리)
+  updateDimension() {}
+  updateAlpha() {}
+}
+
+// ── 팩토리 등록 헬퍼 ─────────────────────────────────────
+
+function register(type: string, overrides: Partial<MCS3DConfig> = {}) {
+  const config: MCS3DConfig = { ...DEFAULTS, ...overrides }
+  registerRealObjectFactory(type, (component: Component) => new MCSRealObject3D(component, config))
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Machine (인프라 설비) — 높은 depth, 컨테이너는 반투명
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+register('Equipment', {
+  defaultDepth: 3 * TRANSPORT_SURFACE_HEIGHT,
+  opacity: 0.5,
+  metalness: 0.4,
+  roughness: 0.6,
+  defaultColor: 0x8899aa,
+})
+
+register('Buffer', {
+  defaultDepth: TRANSPORT_SURFACE_HEIGHT,
+  opacity: 0.5,
+  metalness: 0.3,
+  roughness: 0.7,
+  defaultColor: 0x99aa88,
+  shape: 'hexagon',
+})
+
+register('AGVLine', {
+  depthRatio: 0.12,
+  metalness: 0.6,
+  roughness: 0.3,
+  defaultColor: 0x888899,
+})
+
+register('OHTLine', {
+  depthRatio: 0.12,
+  metalness: 0.6,
+  roughness: 0.3,
+  defaultColor: 0x888899,
+})
+
+register('STOCKER', {
+  defaultDepth: 5 * TRANSPORT_SURFACE_HEIGHT,
+  opacity: 0.35,
+  metalness: 0.3,
+  roughness: 0.6,
+  defaultColor: 0x8899bb,
+})
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Unit (이동체 · 홀더) — 낮은 depth, 불투명
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+register('Port', {
+  depthRatio: 0.5,
+  defaultZPosFromParent: true,
+  opacity: 0.5,
+  metalness: 0.4,
+  roughness: 0.6,
+  defaultColor: 0xb0a090,
+})
+
+register('Shelf', {
+  depthRatio: 0.25,
+  metalness: 0.3,
+  roughness: 0.7,
+  defaultColor: 0xaabbcc,
+})
+
+register('Carrier', {
+  depthRatio: 0.5,
+  metalness: 0.2,
+  roughness: 0.8,
+  defaultColor: 0x66bb66,
+  isVisible: (c: Component) => !!(c.state as any).id,
+  sizeRatio: 0.8,
+})
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Gauge (용량 게이지) — 얇은 바
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+register('ZoneCapacityBar', {
+  depthRatio: 0.15,
+  metalness: 0.2,
+  roughness: 0.8,
+  defaultColor: 0x44aa44,
+})
+
+register('StockerCapacityBar', {
+  depthRatio: 0.15,
+  metalness: 0.2,
+  roughness: 0.8,
+  defaultColor: 0x44aa44,
+})
+
+register('MCSGaugeCapacityBar', {
+  depthRatio: 0.15,
+  metalness: 0.2,
+  roughness: 0.8,
+  defaultColor: 0x44aa44,
+})

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

@@ -0,0 +1,172 @@
+/**
+ * OHT (Overhead Hoist Transport) 3D Factory
+ *
+ * 천장 레일에 매달려 이동하는 반송 차량. 캐리어를 호이스트로 운반.
+ * 구조 (바닥 원점, y=0~depth):
+ *   - 하단 그리퍼 바 (캐리어 집는 가로 바)
+ *   - 호이스트 암 (좌우 수직 기둥)
+ *   - 본체 하우징 (statusColor 적용)
+ *   - 상단 트롤리 (납작+넓은 레일 클램프 + 좌우 바퀴)
+ */
+
+import * as THREE from 'three'
+import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
+import { RoundedBoxGeometry } from 'three/examples/jsm/geometries/RoundedBoxGeometry.js'
+import { RealObjectGroup, registerRealObjectFactory } from '@hatiolab/things-scene'
+import type { Component } from '@hatiolab/things-scene'
+import { TRANSPORT_SURFACE_HEIGHT } from './machine-3d.js'
+
+const TROLLEY_COLOR = 0x222222
+const FRAME_COLOR = 0x444444
+const DEFAULT_BODY_COLOR = 0x6688cc
+
+/** OHT 레일 높이: 스토커(5x) 위 */
+const OHT_RAIL_HEIGHT = 6 * TRANSPORT_SURFACE_HEIGHT
+
+export class OHT3D extends RealObjectGroup {
+  get effectiveDepth(): number {
+    const { depth } = this.component.state
+    return depth || TRANSPORT_SURFACE_HEIGHT
+  }
+
+  /** 천장 레일 높이에 배치 */
+  protected get syncZPosOffset(): number {
+    return OHT_RAIL_HEIGHT
+  }
+
+  private resolveColor(): number {
+    const comp = this.component as any
+
+    try {
+      const sc = comp.statusColor
+      if (typeof sc === 'string' && sc && sc.toUpperCase() !== '#F0F0F0') return new THREE.Color(sc).getHex()
+    } catch {
+      /* statusColor 미구현 시 무시 */
+    }
+
+    const { fillStyle } = this.component.state
+    if (fillStyle && typeof fillStyle === 'string') {
+      try {
+        return new THREE.Color(fillStyle).getHex()
+      } catch {
+        /* 파싱 실패 시 무시 */
+      }
+    }
+
+    return DEFAULT_BODY_COLOR
+  }
+
+  build() {
+    super.build()
+
+    const { width = 10, height = 10 } = this.component.state
+    const w = Math.abs(width)
+    const h = Math.abs(height)
+    const d = this.effectiveDepth
+    if (!w || !h) return
+
+    // 높이 배분: 그리퍼 8%, 호이스트암 22%, 본체 45%, 간격 5%, 트롤리 12%, 바퀴 8%
+    const gripperBarH = d * 0.08
+    const armH = d * 0.22
+    const bodyH = d * 0.45
+    const gap = d * 0.05
+    const trolleyH = d * 0.12
+    const wheelH = d * 0.08
+
+    const armThickness = Math.min(w, h) * 0.12
+    const bodyCornerR = Math.min(w, h, bodyH) * 0.1
+
+    const frameMat = new THREE.MeshStandardMaterial({
+      color: FRAME_COLOR,
+      roughness: 0.5,
+      metalness: 0.4,
+    })
+
+    // ── 1. 하단 그리퍼 바 (캐리어를 집는 가로 바) ──
+    const gripperBarW = w * 0.7
+    const gripperBarD = h * 0.15
+    const gripperGeo = new THREE.BoxGeometry(gripperBarW, gripperBarH, gripperBarD)
+    const gripperMesh = new THREE.Mesh(gripperGeo, frameMat)
+    gripperMesh.position.y = gripperBarH / 2
+    gripperMesh.castShadow = true
+    this.object3d.add(gripperMesh)
+
+    // ── 2. 호이스트 암 (좌우 수직 기둥 + 하단 가로연결) ──
+    const armBaseY = gripperBarH
+    const armGeometries: THREE.BufferGeometry[] = []
+
+    // 좌우 수직 기둥
+    for (const xSign of [-1, 1]) {
+      const pillar = new THREE.BoxGeometry(armThickness, armH, armThickness)
+      pillar.translate(xSign * (w * 0.3), armBaseY + armH / 2, 0)
+      armGeometries.push(pillar)
+    }
+
+    // 하단 가로 연결 바 (그리퍼와 암을 잇는 수평 바)
+    const crossBarW = w * 0.6 + armThickness
+    const crossBarH = armThickness * 0.6
+    const crossBar = new THREE.BoxGeometry(crossBarW, crossBarH, armThickness)
+    crossBar.translate(0, armBaseY + crossBarH / 2, 0)
+    armGeometries.push(crossBar)
+
+    const armMesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(armGeometries), frameMat)
+    armMesh.castShadow = true
+    this.object3d.add(armMesh)
+
+    // ── 3. 본체 하우징 (statusColor 적용) ──
+    const bodyBaseY = armBaseY + armH
+    const bodyColor = this.resolveColor()
+    const bodyGeo = new RoundedBoxGeometry(w, bodyH, h, 4, bodyCornerR)
+    const bodyMat = new THREE.MeshStandardMaterial({
+      color: bodyColor,
+      roughness: 0.3,
+      metalness: 0.5,
+    })
+    const bodyMesh = new THREE.Mesh(bodyGeo, bodyMat)
+    bodyMesh.position.y = bodyBaseY + bodyH / 2
+    bodyMesh.castShadow = true
+    bodyMesh.receiveShadow = true
+    this.object3d.add(bodyMesh)
+
+    // ── 4. 상단 트롤리 플레이트 (납작하고 넓은 레일 클램프) ──
+    const trolleyBaseY = bodyBaseY + bodyH + gap
+    const trolleyW = w * 1.15
+    const trolleyD = h * 0.6
+    const trolleyGeo = new THREE.BoxGeometry(trolleyW, trolleyH, trolleyD)
+    const trolleyMat = new THREE.MeshStandardMaterial({
+      color: TROLLEY_COLOR,
+      roughness: 0.6,
+      metalness: 0.3,
+    })
+    const trolleyMesh = new THREE.Mesh(trolleyGeo, trolleyMat)
+    trolleyMesh.position.y = trolleyBaseY + trolleyH / 2
+    trolleyMesh.castShadow = true
+    this.object3d.add(trolleyMesh)
+
+    // ── 5. 좌우 바퀴 (트롤리 위, 레일을 타는 원통형 바퀴) ──
+    const wheelBaseY = trolleyBaseY + trolleyH
+    const wheelRadius = wheelH / 2
+    const wheelDepth = h * 0.2
+    for (const xSign of [-1, 1]) {
+      const wheelGeo = new THREE.CylinderGeometry(wheelRadius, wheelRadius, wheelDepth, 12)
+      wheelGeo.rotateX(Math.PI / 2)
+      const wheelMesh = new THREE.Mesh(wheelGeo, trolleyMat)
+      wheelMesh.position.set(xSign * (trolleyW * 0.35), wheelBaseY + wheelRadius, 0)
+      wheelMesh.castShadow = true
+      this.object3d.add(wheelMesh)
+    }
+  }
+
+  updateDimension() {}
+  updateAlpha() {}
+
+  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
+    }
+    super.onchange(after, before)
+  }
+}
+
+registerRealObjectFactory('OHT', (component: Component) => new OHT3D(component))

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

@@ -0,0 +1,159 @@
+/**
+ * Shuttle 3D Factory
+ *
+ * 스토커 내부에서 캐리어를 선반↔포트 간 이송하는 포크 캐리지.
+ * 수평 레일 위를 이동하며, 포크를 밀어넣어 캐리어를 적재/하역.
+ *
+ * 구조 (바닥 원점, y=0~depth):
+ *   - 하단 베이스 플레이트 (납작, 넓음, 레일 위 주행부)
+ *   - 중앙 마스트 (좌우 수직 기둥, statusColor 적용)
+ *   - 상단 포크 (2개의 평행한 가로 암, 캐리어 적재면)
+ */
+
+import * as THREE from 'three'
+import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
+import { RealObjectGroup, registerRealObjectFactory } from '@hatiolab/things-scene'
+import type { Component } from '@hatiolab/things-scene'
+import { TRANSPORT_SURFACE_HEIGHT } from './machine-3d.js'
+
+const BASE_COLOR = 0x333333
+const FORK_COLOR = 0x777777
+const DEFAULT_BODY_COLOR = 0x6688cc
+
+export class Shuttle3D extends RealObjectGroup {
+  get effectiveDepth(): number {
+    const { depth } = this.component.state
+    return depth || TRANSPORT_SURFACE_HEIGHT
+  }
+
+  protected get syncZPosOffset(): number {
+    return 0
+  }
+
+  private resolveColor(): number {
+    const comp = this.component as any
+
+    try {
+      const sc = comp.statusColor
+      if (typeof sc === 'string' && sc && sc.toUpperCase() !== '#F0F0F0') return new THREE.Color(sc).getHex()
+    } catch {
+      /* statusColor 미구현 시 무시 */
+    }
+
+    const { fillStyle } = this.component.state
+    if (fillStyle && typeof fillStyle === 'string') {
+      try {
+        return new THREE.Color(fillStyle).getHex()
+      } catch {
+        /* 파싱 실패 시 무시 */
+      }
+    }
+
+    return DEFAULT_BODY_COLOR
+  }
+
+  build() {
+    super.build()
+
+    const { width = 10, height = 10 } = this.component.state
+    const w = Math.abs(width)
+    const h = Math.abs(height)
+    const d = this.effectiveDepth
+    if (!w || !h) return
+
+    // 높이 배분: 베이스 15%, 마스트 55%, 포크 30%
+    const baseH = d * 0.15
+    const mastH = d * 0.55
+    const forkH = d * 0.30
+
+    const mastThickness = Math.min(w, h) * 0.15
+
+    // ── 1. 하단 베이스 플레이트 (납작하고 넓은 주행부) ──
+    const basePad = Math.min(w, h) * 0.05
+    const baseGeo = new THREE.BoxGeometry(w + basePad * 2, baseH, h + basePad * 2)
+    const baseMat = new THREE.MeshStandardMaterial({
+      color: BASE_COLOR,
+      roughness: 0.7,
+      metalness: 0.3,
+    })
+    const baseMesh = new THREE.Mesh(baseGeo, baseMat)
+    baseMesh.position.y = baseH / 2
+    baseMesh.castShadow = true
+    baseMesh.receiveShadow = true
+    this.object3d.add(baseMesh)
+
+    // ── 2. 좌우 마스트 기둥 (statusColor 적용) ──
+    const mastBaseY = baseH
+    const bodyColor = this.resolveColor()
+    const mastMat = new THREE.MeshStandardMaterial({
+      color: bodyColor,
+      roughness: 0.4,
+      metalness: 0.5,
+    })
+
+    const mastGeometries: THREE.BufferGeometry[] = []
+
+    // 좌우 수직 기둥
+    for (const xSign of [-1, 1]) {
+      const pillar = new THREE.BoxGeometry(mastThickness, mastH, mastThickness)
+      pillar.translate(xSign * (w / 2 - mastThickness / 2), mastBaseY + mastH / 2, 0)
+      mastGeometries.push(pillar)
+    }
+
+    // 중간 가로 연결 바 (구조 강성)
+    const crossBarW = w - mastThickness
+    const crossBarH = mastThickness * 0.5
+    const crossBar = new THREE.BoxGeometry(crossBarW, crossBarH, mastThickness)
+    crossBar.translate(0, mastBaseY + mastH * 0.4, 0)
+    mastGeometries.push(crossBar)
+
+    const mastMesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(mastGeometries), mastMat)
+    mastMesh.castShadow = true
+    this.object3d.add(mastMesh)
+
+    // ── 3. 상단 포크 (2개의 평행 암 + 백 플레이트) ──
+    const forkBaseY = mastBaseY + mastH
+    const forkMat = new THREE.MeshStandardMaterial({
+      color: FORK_COLOR,
+      roughness: 0.4,
+      metalness: 0.6,
+    })
+
+    const forkGeometries: THREE.BufferGeometry[] = []
+
+    // 백 플레이트 (마스트 상단을 잇는 가로판)
+    const backPlateH = forkH * 0.4
+    const backPlate = new THREE.BoxGeometry(w, backPlateH, mastThickness * 0.8)
+    backPlate.translate(0, forkBaseY + backPlateH / 2, -h * 0.35)
+    forkGeometries.push(backPlate)
+
+    // 2개의 포크 암 (앞으로 뻗은 평행 막대)
+    const forkArmW = mastThickness * 0.7
+    const forkArmH = forkH * 0.25
+    const forkArmD = h * 0.85
+    const forkSpacing = w * 0.55
+
+    for (const xSign of [-1, 1]) {
+      const arm = new THREE.BoxGeometry(forkArmW, forkArmH, forkArmD)
+      arm.translate(xSign * (forkSpacing / 2), forkBaseY + forkArmH / 2, forkArmD / 2 - h * 0.35)
+      forkGeometries.push(arm)
+    }
+
+    const forkMesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(forkGeometries), forkMat)
+    forkMesh.castShadow = true
+    this.object3d.add(forkMesh)
+  }
+
+  updateDimension() {}
+  updateAlpha() {}
+
+  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
+    }
+    super.onchange(after, before)
+  }
+}
+
+registerRealObjectFactory('Shuttle', (component: Component) => new Shuttle3D(component))