@fmsim/machine 1.0.87 → 2.0.0-beta.12

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

@@ -0,0 +1,767 @@
+/**
+ * MCS 설비 컴포넌트 3D 팩토리
+ *
+ * 10,000+ 인스턴스를 위한 최소 폴리곤 설계:
+ *   - 컴포넌트당 단일 Mesh (draw call 최소화)
+ *   - BoxGeometry / ExtrudeGeometry(hexagon) 만 사용
+ *   - Machine: 높은 depth, 컨테이너는 반투명
+ *   - Unit: 낮은 depth, 불투명
+ */
+
+import * as THREE from 'three'
+import { RealObjectGroup, registerRealObjectFactory, disposeObject3D } from '@hatiolab/things-scene'
+import type { Component } from '@hatiolab/things-scene'
+import { LEGEND_CAPACITY } from '../features/mcs-status-default'
+import { getVaueOnRanges } from '../utils/get-value-on-ranges'
+
+// ── 설정 타입 ────────────────────────────────────────────
+
+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
+  /** 상부 면 제거 (5면 개방 박스) */
+  openTop?: boolean
+  /** 상판 무반사 (MeshBasicMaterial) */
+  matteTop?: boolean
+  /** 상판에 2D 렌더링 텍스처 적용 */
+  texturedTop?: boolean
+}
+
+/**
+ * 포트 기본 높이 (절대값).
+ * 모든 이송장치의 상단 높이 = 이 값.
+ * 캐리어가 이송장치 간 높이 차 없이 이동할 수 있는 기준 높이.
+ */
+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 절대값 (음수 값은 양수로 취급)
+  protected 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 색상 변환
+  protected 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 ──
+
+  protected _ownMesh?: THREE.Mesh
+
+  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
+
+    // BoxGeometry material groups: +x(0), -x(1), +y(2), -y(3), +z(4), -z(5)
+    let meshMaterial: THREE.Material | THREE.Material[] = material
+    if (shape === 'box') {
+      if (this._config.openTop) {
+        // 상단면 제거 → 5면 개방 박스
+        const invisible = new THREE.MeshBasicMaterial({ visible: false })
+        meshMaterial = [material, material, invisible, material, material, material]
+      } else if (this._config.texturedTop) {
+        // 상판에 2D 렌더링 텍스처
+        const topMat = this.buildTopTexture(w, h)
+        meshMaterial = [material, material, topMat, material, material, material]
+      } else if (this._config.matteTop) {
+        // 상판만 무반사
+        const matte = new THREE.MeshBasicMaterial({ color, opacity, transparent: opacity < 1 })
+        meshMaterial = [material, material, matte, material, material, material]
+      }
+    }
+
+    this._ownMesh = new THREE.Mesh(geometry, meshMaterial)
+    // sizeRatio < 1이면 부모 중심에 배치 (rawDepth/2), 아니면 자체 중심 (depth/2)
+    this._ownMesh.position.y = ratio < 1 ? rawDepth / 2 : depth / 2
+    this._ownMesh.castShadow = true
+    this._ownMesh.receiveShadow = true
+    this.object3d.add(this._ownMesh)
+  }
+
+  // ── Change handling ──
+
+  private _updatePending = false
+
+  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 ||
+      'EMPTYTYPE' in after ||
+      'CARRIERSTATUS' in after
+    ) {
+      // 연속 setState에 의한 다중 rebuild 방지: 한 프레임에 한 번만 실행
+      if (!this._updatePending) {
+        this._updatePending = true
+        queueMicrotask(() => {
+          this._updatePending = false
+          this.update()
+        })
+      }
+      return
+    }
+
+    super.onchange(after, before)
+  }
+
+  /**
+   * 상판 텍스처: 컴포넌트의 2D render()를 캔버스에 그려서 텍스처로 사용
+   */
+  protected buildTopTexture(w: number, h: number): THREE.MeshBasicMaterial {
+    const scale = 4
+    const cw = this.nextPow2(w * scale)
+    const ch = this.nextPow2(h * scale)
+    const canvas = document.createElement('canvas')
+    canvas.width = cw
+    canvas.height = ch
+    const ctx = canvas.getContext('2d')!
+
+    const statusColor = '#' + this.resolveColor().toString(16).padStart(6, '0')
+    const emptyType = (this.component.state as any)?.EMPTYTYPE || ''
+    const text = emptyType === 'FULL' ? 'F' : emptyType === 'EMPTY' ? 'E' : emptyType === 'EMPTYEMPTY' ? 'X' : ''
+
+    // 실제 사용 영역 (nextPow2 이전 크기)
+    const usedW = w * scale
+    const usedH = h * scale
+
+    // 바탕: 캐리어 상태 색상 (사용 영역만)
+    ctx.fillStyle = statusColor
+    ctx.fillRect(0, 0, usedW, usedH)
+
+    // 텍스트 (사용 영역 중앙)
+    if (text) {
+      const fontSize = Math.round(Math.min(usedW, usedH) * 0.7)
+      ctx.font = `bold ${fontSize}px Arial`
+      ctx.textAlign = 'center'
+      ctx.textBaseline = 'middle'
+      ctx.fillStyle = '#000000'
+      ctx.fillText(text, usedW / 2, usedH / 2)
+    }
+
+    const texture = new THREE.CanvasTexture(canvas)
+    texture.offset.set(0, 1 - usedH / ch)
+    texture.repeat.set(usedW / cw, usedH / ch)
+    texture.colorSpace = THREE.SRGBColorSpace
+
+    return new THREE.MeshBasicMaterial({
+      map: texture,
+      transparent: true,
+      side: THREE.DoubleSide,
+    })
+  }
+
+  private nextPow2(n: number): number {
+    if (!(n > 0)) return 1
+    let v = Math.ceil(n)
+    v--
+    v |= v >> 1; v |= v >> 2; v |= v >> 4; v |= v >> 8; v |= v >> 16
+    return v + 1
+  }
+
+  /**
+   * 자신의 mesh만 제거 후 rebuild.
+   * 기본 update()는 clear()로 object3d의 모든 children을 제거하는데,
+   * 컨테이너(Port 등)의 경우 자식 컴포넌트(Carrier 등)의 3D 오브젝트도 함께 제거됨.
+   * 이를 방지하기 위해 자신이 생성한 mesh만 제거한다.
+   */
+  update() {
+    // 자신의 mesh만 제거 (자식 컴포넌트 3D 오브젝트 보존)
+    if (this._ownMesh) {
+      this.object3d.remove(this._ownMesh)
+      disposeObject3D(this._ownMesh)
+      this._ownMesh = undefined
+    }
+
+    this.build()
+    this.updateTransform()
+    this.updateAlpha()
+    this.updateHidden()
+  }
+
+  // RealObjectGroup 기본 동작 비활성화
+  updateDimension() {}
+
+  updateAlpha() {
+    const { alpha = 1 } = this.component.state
+    const configOpacity = this._config.opacity
+    const effective = configOpacity * alpha
+
+    this.object3d.traverse((o: any) => {
+      if (!o.material) return
+      const materials = Array.isArray(o.material) ? o.material : [o.material]
+      for (const m of materials) {
+        if (!m.visible) continue // openTop invisible face 무시
+        if (m.map) continue // 텍스처 material은 자체 transparent 유지
+        m.opacity = effective
+        m.transparent = effective < 1
+      }
+    })
+  }
+}
+
+// ── 팩토리 등록 헬퍼 ─────────────────────────────────────
+
+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.75,
+  metalness: 0.4,
+  roughness: 0.6,
+  defaultColor: 0x8899aa,
+})
+
+register('Buffer', {
+  defaultDepth: TRANSPORT_SURFACE_HEIGHT,
+  opacity: 1.0,
+  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,
+})
+
+// STOCKER: 벽면에 용량 게이지 바를 포함하는 커스텀 3D 오브젝트
+const STOCKER_CONFIG: MCS3DConfig = {
+  ...DEFAULTS,
+  defaultDepth: 5 * TRANSPORT_SURFACE_HEIGHT,
+  opacity: 0.75,
+  metalness: 0.3,
+  roughness: 0.6,
+  defaultColor: 0x8899bb,
+}
+
+class StockerRealObject3D extends MCSRealObject3D {
+  private gaugeMesh?: THREE.Mesh
+
+  constructor(component: Component) {
+    super(component, STOCKER_CONFIG)
+  }
+
+  build() {
+    super.build()
+    this.buildGauge()
+  }
+
+  private buildGauge() {
+    const comp = this.component as any
+    const data = comp.data || {}
+    const gaugeMode = comp.root?.style?.stockerGaugeMode || 'capacity'
+
+    const gauge = this.resolveGauge(data, gaugeMode)
+
+    // 테두리는 스토커의 상태 색상 (machine status)
+    const statusColor = comp.statusColor
+    if (statusColor && statusColor.toUpperCase() !== '#F0F0F0') {
+      gauge.borderColor = statusColor
+    }
+
+    const { w, h } = this.absSize
+    const depth = this.effectiveDepth
+    const isWidthLonger = w >= h
+
+    // 게이지 캔버스 (고해상도)
+    const barW = 130
+    const barH = 26
+    const scale = 4
+    const canvasW = barW * scale
+    const canvasH = barH * scale
+    const canvas = document.createElement('canvas')
+    canvas.width = canvasW
+    canvas.height = canvasH
+    const ctx = canvas.getContext('2d')!
+
+    const pad = 12
+
+    // 배경 + 테두리
+    ctx.fillStyle = '#dddddd'
+    ctx.fillRect(0, 0, canvasW, canvasH)
+    ctx.strokeStyle = gauge.borderColor
+    ctx.lineWidth = 12
+    ctx.strokeRect(6, 6, canvasW - 12, canvasH - 12)
+
+    // 세그먼트 채움 (왼→오)
+    const innerW = canvasW - pad * 2
+    const innerH = canvasH - pad * 2
+    let x = pad
+    for (const seg of gauge.segments) {
+      const segW = Math.max(innerW * seg.ratio, seg.ratio > 0 ? 1 : 0)
+      if (segW <= 0) continue
+      ctx.fillStyle = seg.color
+      ctx.fillRect(x, pad, segW, innerH)
+      x += segW
+    }
+
+    // 텍스트
+    ctx.font = `bold ${10 * scale}px sans-serif`
+    ctx.textAlign = 'center'
+    ctx.textBaseline = 'middle'
+    ctx.fillStyle = '#333333'
+    ctx.fillText(gauge.label, canvasW / 2, canvasH / 2)
+
+    // 텍스처 → Plane
+    const texture = new THREE.CanvasTexture(canvas)
+    texture.colorSpace = THREE.SRGBColorSpace
+
+    const geo = new THREE.PlaneGeometry(barW, barH)
+    geo.rotateX(-Math.PI / 2) // 수평 (지붕 위)
+    if (!isWidthLonger) geo.rotateY(Math.PI / 2)
+
+    const mat = new THREE.MeshBasicMaterial({
+      map: texture,
+      transparent: true,
+      side: THREE.DoubleSide,
+    })
+    mat.polygonOffset = true
+    mat.polygonOffsetFactor = -2
+    mat.polygonOffsetUnit = -2
+
+    this.gaugeMesh = new THREE.Mesh(geo, mat)
+    this.gaugeMesh.position.set(0, depth + 0.5, 0)
+    this.object3d.add(this.gaugeMesh)
+  }
+
+  private resolveGauge(data: any, mode: string) {
+    switch (mode) {
+      case 'carrier': {
+        const full = Number(data.FULL_CNT) || 0
+        const empty = Number(data.EMPTY_CNT) || 0
+        const emptyEmpty = Number(data.EMPTYEMPTY_CNT) || 0
+        const total = full + empty + emptyEmpty
+        const segments = total > 0
+          ? [
+              { ratio: full / total, color: '#4AA7FE' },
+              { ratio: empty / total, color: '#8BDA5B' },
+              { ratio: emptyEmpty / total, color: '#019D59' },
+            ]
+          : [{ ratio: 1, color: '#dddddd' }]
+        return {
+          segments,
+          borderColor: '#4AA7FE',
+          label: total > 0 ? `F${full} E${empty} EE${emptyEmpty}` : '',
+        }
+      }
+      case 'abnormal': {
+        const normal = Number(data.CARRIER_NORMAL) || 0
+        const abnormal = Number(data.CARRIER_ABNORMAL) || 0
+        const total = normal + abnormal
+        const segments = total > 0
+          ? [
+              { ratio: normal / total, color: '#8BDA5B' },
+              { ratio: abnormal / total, color: '#F4B4B4' },
+            ]
+          : [{ ratio: 1, color: '#dddddd' }]
+        return {
+          segments,
+          borderColor: abnormal > 0 ? '#F4B4B4' : '#8BDA5B',
+          label: total > 0 ? `N${normal} A${abnormal}` : '',
+        }
+      }
+      default: { // capacity
+        const cur = Number(data.CURRENTCAPACITY) || 0
+        const max = Number(data.MAXCAPACITY) || 100
+        const fullup = data.FULLUP === 'T'
+        const usage = Math.round((cur / max) * 100)
+        const legend = (this.component as any).root?.style?.LEGEND_CAPACITY || LEGEND_CAPACITY
+        const color = fullup ? 'red' : (getVaueOnRanges(usage, legend) || '#44aa44')
+        return {
+          segments: [{ ratio: usage / 100, color }],
+          borderColor: color,
+          label: `${usage}%`,
+        }
+      }
+    }
+  }
+
+  onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
+    if ('data' in after) {
+      this.clearGauge()
+      this.buildGauge()
+    }
+    super.onchange(after, before)
+  }
+
+  clear() {
+    this.clearGauge()
+    return super.clear()
+  }
+
+  private clearGauge() {
+    if (this.gaugeMesh) {
+      this.object3d.remove(this.gaugeMesh)
+      this.gaugeMesh.geometry?.dispose()
+      const mat = this.gaugeMesh.material as THREE.MeshBasicMaterial
+      mat?.map?.dispose()
+      mat?.dispose()
+      this.gaugeMesh = undefined
+    }
+  }
+}
+
+registerRealObjectFactory('STOCKER', (component: Component) => new StockerRealObject3D(component))
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Unit (이동체 · 홀더) — 낮은 depth, 불투명
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// Port: 상부 개방 5면 박스
+const PORT_CONFIG: MCS3DConfig = {
+  ...DEFAULTS,
+  depthRatio: 0.5,
+  defaultZPosFromParent: true,
+  opacity: 0.5,
+  metalness: 0.4,
+  roughness: 0.6,
+  defaultColor: 0xb0a090,
+  openTop: true,
+}
+registerRealObjectFactory('Port', (component: Component) => new MCSRealObject3D(component, PORT_CONFIG))
+
+register('Shelf', {
+  depthRatio: 0.25,
+  metalness: 0.3,
+  roughness: 0.7,
+  defaultColor: 0xaabbcc,
+})
+
+// Carrier: CARRIERSTATUS에 따른 3D 애니메이션 지원
+const CARRIER_CONFIG: MCS3DConfig = {
+  ...DEFAULTS,
+  depthRatio: 0.5,
+  metalness: 0.2,
+  roughness: 0.8,
+  defaultColor: 0x66bb66,
+  isVisible: (c: Component) => !!(c.state as any).id,
+  sizeRatio: 0.8,
+  texturedTop: true,
+}
+
+class CarrierRealObject3D extends MCSRealObject3D {
+  private _animRaf: number | null = null
+  private _animStartTime = 0
+
+  constructor(component: Component) {
+    super(component, CARRIER_CONFIG)
+  }
+
+  build() {
+    super.build()
+    this.startCarrierAnimation()
+  }
+
+  /**
+   * CARRIERSTATUS의 애니메이션 설정을 읽어 3D에서 직접 실행.
+   * things-scene의 delta 시스템과 독립적으로 동작.
+   */
+  private startCarrierAnimation() {
+    this.stopCarrierAnimation()
+
+    const comp = this.component as any
+    if (!comp.app?.isViewMode) return
+
+    const carrierStatus = comp.state?.CARRIERSTATUS
+    if (!carrierStatus) return
+
+    // 애니메이션 설정 가져오기
+    const config = comp.getAnimationConfig?.(carrierStatus)
+    if (!config?.animation) return
+
+    const { type, duration = 2000, scale: animScale = 1.3 } = config.animation
+    if (!type) return
+
+    this._animStartTime = performance.now()
+
+    // 애니메이션 대상: group(object3d) — mesh 개별 변환 대신 group 전체를 변환하여
+    // 회전/스케일 중심이 component의 3D 위치(= 2D 중심)와 정확히 일치하도록 함
+    const obj = this.object3d
+
+    const animate = () => {
+      if (!this._ownMesh) return
+
+      const elapsed = performance.now() - this._animStartTime
+      const progress = (elapsed % duration) / duration // 0~1 반복
+
+      switch (type) {
+        case 'heartbeat': {
+          const t = progress < 0.5 ? progress * 2 : (1 - progress) * 2
+          const s = 1 + (animScale - 1) * t
+          obj.scale.set(s, 1, s)
+          break
+        }
+        case 'rotation': {
+          obj.rotation.y = progress * Math.PI * 2
+          break
+        }
+        case 'vibration': {
+          const theta = config.animation.theta ?? 0.26
+          const current = Math.sin(progress * Math.PI * 2) * theta
+          obj.rotation.y = current
+          break
+        }
+        case 'fade': {
+          const alpha = 0.3 + 0.7 * (progress < 0.5 ? progress * 2 : (1 - progress) * 2)
+          obj.traverse((o: any) => {
+            if (o.material && !o.material.map) {
+              o.material.opacity = alpha
+              o.material.transparent = true
+            }
+          })
+          break
+        }
+      }
+
+      this._animRaf = requestAnimationFrame(animate)
+    }
+
+    this._animRaf = requestAnimationFrame(animate)
+  }
+
+  // 자체 애니메이션이 실행 중이면 things-scene의 syncAnimationDelta 비활성화
+  syncAnimationDelta() {
+    if (!this._animRaf) {
+      super.syncAnimationDelta()
+    }
+  }
+
+  private stopCarrierAnimation() {
+    if (this._animRaf) {
+      cancelAnimationFrame(this._animRaf)
+      this._animRaf = null
+    }
+    // group 스케일/회전 초기화
+    this.object3d.scale.set(1, 1, 1)
+    this.object3d.rotation.y = 0
+  }
+
+  update() {
+    this.stopCarrierAnimation()
+    super.update()
+  }
+
+  clear() {
+    this.stopCarrierAnimation()
+    return super.clear()
+  }
+}
+
+registerRealObjectFactory('Carrier', (component: Component) => new CarrierRealObject3D(component))
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Gauge (용량 게이지) — 얇은 바
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Gauge (용량 게이지) — 2D 렌더링을 Plane 텍스처로 3D 표시
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// Gauge 컴포넌트 (StockerCapacityBar, ZoneCapacityBar, MCSGaugeCapacityBar)는
+// 3D에서 표시하지 않음. 대신 부모(STOCKER 등)의 3D 모델에서 직접 게이지를 렌더링.
+registerRealObjectFactory('StockerCapacityBar', () => null as any)
+registerRealObjectFactory('MCSGaugeCapacityBar', () => null as any)
+registerRealObjectFactory('ZoneCapacityBar', () => null as any)