@fmsim/machine 2.0.0-beta.5 → 2.0.0-beta.53

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

@@ -9,10 +9,11 @@
  */
 
 import * as THREE from 'three'
-import { RealObjectGroup, registerRealObjectFactory } from '@hatiolab/things-scene'
+import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
+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'
+import { getValueOnRanges } from '../utils/get-value-on-ranges'
 
 // ── 설정 타입 ────────────────────────────────────────────
 
@@ -30,11 +31,23 @@ interface MCS3DConfig {
   /** statusColor 미사용 시 기본 색상 */
   defaultColor: number
   /** 'box' | 'hexagon' */
-  shape: 'box' | 'hexagon'
+  shape: 'box' | 'hexagon' | 'plane'
   /** mesh 생성 전 가시성 판정 — false 반환 시 mesh 미생성 */
   isVisible?: (component: Component) => boolean
   /** 부모 대비 크기 비율 (기본 1.0). < 1이면 부모 중심에 배치. */
   sizeRatio?: number
+  /** 상부 면 제거 (5면 개방 박스) */
+  openTop?: boolean
+  /** 상판 무반사 (MeshBasicMaterial) */
+  matteTop?: boolean
+  /** 상판에 2D 렌더링 텍스처 적용 */
+  texturedTop?: boolean
+  /** 자체 발광 강도 (0~1). 조명 약한 면에서도 색상 유지 */
+  emissiveIntensity?: number
+  /** 바닥면 유지 (기본 false — 바닥면 제거) */
+  keepBottomFace?: boolean
+  /** syncZPosOffset 고정값 (설정 시 다른 로직 무시) */
+  zPosOverride?: number
 }
 
 /**
@@ -78,37 +91,51 @@ class MCSRealObject3D extends RealObjectGroup {
   }
 
   protected get syncZPosOffset(): number {
+    // syncZPosOffset = placement + geometric (center origin = effectiveDepth/2)
+    // 중첩 보정(parent shift 상쇄)은 base RealObject.cz가 parent.geometricOffsetY를
+    // 빼는 방식으로 처리하므로 여기선 placement + 본인 geometric만 반환
+    const halfD = this.effectiveDepth / 2
+    // zPosOverride: 고정 높이 (OHTLine 등)
+    if (this._config.zPosOverride != null) {
+      return this._config.zPosOverride + halfD
+    }
     // Port: 이송 표면 높이에 배치
     if (this._config.defaultZPosFromParent) {
-      return TRANSPORT_SURFACE_HEIGHT
+      return TRANSPORT_SURFACE_HEIGHT + halfD
     }
-    // Carrier: Port 안이면 중앙, 그 외 컨테이너면 상단 위
+    // Carrier: 부모 유형에 따라 배치 위치 결정
     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
+      // OHT: 그리퍼 아래에 매달림 — placement = -effectiveDepth(carrier top이 OHT bottom)
+      if (parentType === 'OHT') {
+        return -this.effectiveDepth + halfD
+      }
+      if (parentType === 'Port' || parentType === 'Shelf' || parentType === 'Shuttle') {
+        return halfD
       }
-      return TRANSPORT_SURFACE_HEIGHT
+      return TRANSPORT_SURFACE_HEIGHT + halfD
     }
-    return 0
+    return halfD
   }
 
+  // geometric 부분(center origin: depth/2)은 base 기본값 사용 — override 불필요
+
   // 컴포넌트의 상태 색상(statusColor) 또는 fillStyle → Three.js 색상 변환
-  private resolveColor(): number {
+  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()
+      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 {
@@ -157,7 +184,7 @@ class MCSRealObject3D extends RealObjectGroup {
 
   private buildBoxGeometry(w: number, d: number, h: number): THREE.BufferGeometry {
     const geo = new THREE.BoxGeometry(w, d, h)
-    return this.removeBottomFace(geo)
+    return this._config.keepBottomFace ? geo : this.removeBottomFace(geo)
   }
 
   private buildHexagonGeometry(w: number, d: number, h: number): THREE.BufferGeometry {
@@ -188,8 +215,16 @@ class MCSRealObject3D extends RealObjectGroup {
     return this.removeBottomFace(geo)
   }
 
+  private buildPlaneGeometry(w: number, h: number): THREE.BufferGeometry {
+    const geo = new THREE.PlaneGeometry(w, h)
+    geo.rotateX(-Math.PI / 2)
+    return geo
+  }
+
   // ── Build ──
 
+  protected _ownMesh?: THREE.Mesh
+
   build() {
     super.build()
 
@@ -209,34 +244,67 @@ class MCSRealObject3D extends RealObjectGroup {
     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,
-    })
+      shape === 'plane'
+        ? this.buildPlaneGeometry(w, h)
+        : shape === 'hexagon'
+          ? this.buildHexagonGeometry(w, depth, h)
+          : this.buildBoxGeometry(w, depth, h)
+
+    const isPlane = shape === 'plane'
+    const material = isPlane
+      ? new THREE.MeshBasicMaterial({
+          color,
+          opacity,
+          transparent: opacity < 1,
+          side: THREE.DoubleSide,
+        })
+      : new THREE.MeshStandardMaterial({
+          color,
+          metalness,
+          roughness,
+          opacity,
+          transparent: opacity < 1,
+          side: opacity < 1 ? THREE.DoubleSide : THREE.FrontSide,
+          ...(this._config.emissiveIntensity ? { emissive: color, emissiveIntensity: this._config.emissiveIntensity } : {}),
+        })
     // 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)
+    // 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)
+    // ownGroup 기준(bottom-up): mesh 바닥을 y=0에 맞추고 ownGroup이 -d/2로 shift해
+    // center-origin object3d에 정렬됨.
+    //   box/hexagon (center-local geometry): y=rawDepth/2 (바닥을 0에 맞춤)
+    //   plane: y=1 (바닥 살짝 띄움)
+    this._ownMesh.position.y = isPlane ? 1 : rawDepth / 2
+    this._ownMesh.castShadow = !isPlane
+    this._ownMesh.receiveShadow = true
+    this.components3D.add(this._ownMesh)
   }
 
   // ── Change handling ──
 
+  private _updatePending = false
+
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
     if (
       'width' in after ||
@@ -244,18 +312,117 @@ class MCSRealObject3D extends RealObjectGroup {
       'depth' in after ||
       'fillStyle' in after ||
       'strokeStyle' in after ||
-      'id' in after // Carrier: CARRIERNAME 변경 시 가시성 재판정
+      'id' in after ||
+      'EMPTYTYPE' in after ||
+      'CARRIERSTATUS' in after
     ) {
-      this.update()
+      // 연속 setState에 의한 다중 rebuild 방지: 한 프레임에 한 번만 실행
+      if (!this._updatePending) {
+        this._updatePending = true
+        queueMicrotask(() => {
+          this._updatePending = false
+          this.update()
+        })
+      }
       return
     }
 
     super.onchange(after, before)
   }
 
-  // RealObjectGroup 기본 동작 비활성화 (update()에서 일괄 처리)
+  /**
+   * 상판 텍스처: 컴포넌트의 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.components3D.remove(this._ownMesh)
+      disposeObject3D(this._ownMesh)
+      this._ownMesh = undefined
+    }
+
+    this.build()
+    this.updateTransform()
+    this.updateAlpha()
+    this.updateHidden()
+  }
+
+  // RealObjectGroup 기본 동작 비활성화
   updateDimension() {}
-  updateAlpha() {}
+
+  updateAlpha() {
+    const state = this.component.state
+    // alpha가 명시적으로 설정되어 있으면 그 값을 사용, 없으면 config 기본값 적용
+    const effective = ('alpha' in state) ? (state.alpha as number) : this._config.opacity
+
+    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
+      }
+    })
+  }
 }
 
 // ── 팩토리 등록 헬퍼 ─────────────────────────────────────
@@ -287,18 +454,106 @@ register('Buffer', {
 })
 
 register('AGVLine', {
-  depthRatio: 0.12,
+  depthRatio: 0,
+  defaultDepth: 0.1,
   metalness: 0.6,
   roughness: 0.3,
   defaultColor: 0x888899,
 })
 
-register('OHTLine', {
-  depthRatio: 0.12,
-  metalness: 0.6,
-  roughness: 0.3,
-  defaultColor: 0x888899,
-})
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  OHTLine — 천장 I-beam 레일
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const OHT_LINE_RAIL_COLOR = 0xcccccc
+const OHT_LINE_HEIGHT = 7 * TRANSPORT_SURFACE_HEIGHT // OHT 상단과 일치
+
+class OHTLineRealObject3D extends RealObjectGroup {
+  private _mesh?: THREE.Mesh
+
+  get effectiveDepth(): number { return 0 }
+  protected get syncZPosOffset(): number { return OHT_LINE_HEIGHT }
+
+  build() {
+    super.build()
+
+    const { width = 10, height = 10 } = this.component.state
+    const w = Math.abs(width)
+    const h = Math.abs(height)
+    if (!w || !h) return
+
+    // I-beam 치수: 이송 방향 = 긴 변, 폭은 2D의 1/2
+    const isVertical = w < h
+    const shortSide = isVertical ? w : h              // 2D 원본 짧은 쪽 폭
+    const beltW = shortSide * 0.25                    // I-beam 폭: 원본의 1/4
+    const beamH = Math.max(beltW * 0.5, 3)           // I-beam 전체 높이
+    const inset = shortSide * 0.5                     // 양끝 여백: 원본 폭의 1/2
+    const railLen = (isVertical ? h : w) - inset * 2
+    const flangeH = beamH * 0.2                    // 플랜지 두께
+    const flangeW = beltW * 0.8                    // 플랜지 폭
+    const webH = beamH - flangeH * 2               // 웹 높이
+    const webW = Math.max(flangeW * 0.25, 1)       // 웹 두께
+
+    const mat = new THREE.MeshStandardMaterial({
+      color: OHT_LINE_RAIL_COLOR,
+      metalness: 0.5,
+      roughness: 0.4,
+    })
+
+    const geoms: THREE.BufferGeometry[] = []
+
+    // 상부 플랜지
+    const topFlange = isVertical
+      ? new THREE.BoxGeometry(flangeW, flangeH, railLen)
+      : new THREE.BoxGeometry(railLen, flangeH, flangeW)
+    topFlange.translate(0, -flangeH / 2, 0)
+    geoms.push(topFlange)
+
+    // 웹 (수직판)
+    const web = isVertical
+      ? new THREE.BoxGeometry(webW, webH, railLen)
+      : new THREE.BoxGeometry(railLen, webH, webW)
+    web.translate(0, -flangeH - webH / 2, 0)
+    geoms.push(web)
+
+    // 하부 플랜지
+    const botFlange = isVertical
+      ? new THREE.BoxGeometry(flangeW, flangeH, railLen)
+      : new THREE.BoxGeometry(railLen, flangeH, flangeW)
+    botFlange.translate(0, -flangeH - webH - flangeH / 2, 0)
+    geoms.push(botFlange)
+
+    this._mesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(geoms), mat)
+    this._mesh.castShadow = true
+    this.object3d.add(this._mesh)
+  }
+
+  update() {
+    if (this._mesh) {
+      this.object3d.remove(this._mesh)
+      this._mesh.geometry.dispose()
+      ;(this._mesh.material as THREE.Material).dispose()
+      this._mesh = undefined
+    }
+    this.build()
+    this.updateTransform()
+    this.updateHidden()
+  }
+
+  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)
+  }
+
+  updateDimension() {}
+  updateAlpha() {}
+}
+
+registerRealObjectFactory('OHTLine', (component: Component) => new OHTLineRealObject3D(component))
 
 // STOCKER: 벽면에 용량 게이지 바를 포함하는 커스텀 3D 오브젝트
 const STOCKER_CONFIG: MCS3DConfig = {
@@ -396,8 +651,9 @@ class StockerRealObject3D extends MCSRealObject3D {
     mat.polygonOffsetUnit = -2
 
     this.gaugeMesh = new THREE.Mesh(geo, mat)
+    // ownGroup 기준(bottom-up): 볼륨 상단 = +depth. 그 위로 0.5 띄움.
     this.gaugeMesh.position.set(0, depth + 0.5, 0)
-    this.object3d.add(this.gaugeMesh)
+    this.components3D.add(this.gaugeMesh)
   }
 
   private resolveGauge(data: any, mode: string) {
@@ -442,7 +698,7 @@ class StockerRealObject3D extends MCSRealObject3D {
         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')
+        const color = fullup ? 'red' : (getValueOnRanges(usage, legend) || '#44aa44')
         return {
           segments: [{ ratio: usage / 100, color }],
           borderColor: color,
@@ -452,6 +708,11 @@ class StockerRealObject3D extends MCSRealObject3D {
     }
   }
 
+  update() {
+    this.clearGauge()
+    super.update()
+  }
+
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
     if ('data' in after) {
       this.clearGauge()
@@ -467,7 +728,7 @@ class StockerRealObject3D extends MCSRealObject3D {
 
   private clearGauge() {
     if (this.gaugeMesh) {
-      this.object3d.remove(this.gaugeMesh)
+      this.components3D.remove(this.gaugeMesh)
       this.gaugeMesh.geometry?.dispose()
       const mat = this.gaugeMesh.material as THREE.MeshBasicMaterial
       mat?.map?.dispose()
@@ -483,14 +744,18 @@ registerRealObjectFactory('STOCKER', (component: Component) => new StockerRealOb
 //  Unit (이동체 · 홀더) — 낮은 depth, 불투명
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-register('Port', {
-  depthRatio: 0.5,
+// Port: 바닥판 (PlaneGeometry)
+const PORT_CONFIG: MCS3DConfig = {
+  ...DEFAULTS,
+  depthRatio: 0.01,
   defaultZPosFromParent: true,
-  opacity: 0.5,
-  metalness: 0.4,
-  roughness: 0.6,
+  opacity: 0.1,
+  metalness: 0.3,
+  roughness: 0.8,
   defaultColor: 0xb0a090,
-})
+  shape: 'plane',
+}
+registerRealObjectFactory('Port', (component: Component) => new MCSRealObject3D(component, PORT_CONFIG))
 
 register('Shelf', {
   depthRatio: 0.25,
@@ -499,14 +764,25 @@ register('Shelf', {
   defaultColor: 0xaabbcc,
 })
 
-register('Carrier', {
+// Carrier: CARRIERSTATUS에 따른 3D 애니메이션 지원
+const CARRIER_CONFIG: MCS3DConfig = {
+  ...DEFAULTS,
   depthRatio: 0.5,
-  metalness: 0.2,
-  roughness: 0.8,
-  defaultColor: 0x66bb66,
+  metalness: 0,
+  roughness: 1,
+  defaultColor: 0xf0f0f0,
   isVisible: (c: Component) => !!(c.state as any).id,
   sizeRatio: 0.8,
-})
+  texturedTop: true,
+}
+
+class CarrierRealObject3D extends MCSRealObject3D {
+  constructor(component: Component) {
+    super(component, CARRIER_CONFIG)
+  }
+}
+
+registerRealObjectFactory('Carrier', (component: Component) => new CarrierRealObject3D(component))
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 //  Gauge (용량 게이지) — 얇은 바
@@ -516,8 +792,221 @@ register('Carrier', {
 //  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)
+// Gauge 컴포넌트는 3D에서 표시하지 않음 (부모 STOCKER의 3D 모델에서 직접 게이지 렌더링)
+// null 반환으로 3D 오브젝트 생성을 억제하고, default factory fallback도 방지
+registerRealObjectFactory('StockerCapacityBar', () => undefined as any)
+registerRealObjectFactory('MCSGaugeCapacityBar', () => undefined as any)
+registerRealObjectFactory('ZoneCapacityBar', () => undefined as any)
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  PortFlow — 2D render를 Plane 텍스처로 3D 표시
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+class PortFlowRealObject3D extends RealObjectGroup {
+  private _mesh?: THREE.Mesh
+  private _texture?: THREE.CanvasTexture
+
+  get effectiveDepth(): number { return 0 }
+  protected get syncZPosOffset(): number {
+    // 부모 Port/Conveyor의 zPos와 동일하게
+    const parent = (this.component as any).parentObject
+    if (parent?.state?.zPos != null) return parent.state.zPos
+    return TRANSPORT_SURFACE_HEIGHT
+  }
+
+  build() {
+    super.build()
+
+    const { width = 10, height = 10 } = this.component.state
+    const w = Math.abs(width)
+    const h = Math.abs(height)
+    if (!w || !h) return
+
+    // 2D render를 캔버스에 캡처
+    // 화살표 날개 + 텍스트 영역이 bounds 밖으로 나가므로 전체 영역 계산
+    const { left, top } = this.component.bounds
+    const { fontSize = 24, labelPosition = 'top' } = this.component.state
+    const arrowPad = Math.min(w, h) * 0.4
+
+    // 텍스트 영역 확장
+    let padLeft = arrowPad, padRight = arrowPad, padTop = arrowPad, padBottom = arrowPad
+    if ((this.component as any).hasTextProperty) {
+      switch (labelPosition) {
+        case 'top': padTop = Math.max(padTop, fontSize + 4); break
+        case 'bottom': padBottom = Math.max(padBottom, fontSize + 4); break
+        case 'left': padLeft = Math.max(padLeft, fontSize * 4 + 4); break
+        case 'right': padRight = Math.max(padRight, fontSize * 4 + 4); break
+      }
+    }
+
+    const totalW = w + padLeft + padRight
+    const totalH = h + padTop + padBottom
+    const scale = 2
+    const canvas = document.createElement('canvas')
+    canvas.width = totalW * scale
+    canvas.height = totalH * scale
+    const ctx = canvas.getContext('2d')!
+
+    ctx.save()
+    ctx.scale(scale, scale)
+    ctx.translate(-left + padLeft, -top + padTop)
+    try {
+      // 화살표 렌더
+      this.component.render(ctx)
+      ctx.fillStyle = this.component.state.strokeStyle || '#666666'
+      ctx.fill()
+      // 텍스트 렌더
+      if ((this.component as any).hasTextProperty && (this.component as any).drawText) {
+        ;(this.component as any).drawText(ctx)
+      }
+    } catch { /* render 실패 시 빈 텍스처 */ }
+    ctx.restore()
+
+    this._texture = new THREE.CanvasTexture(canvas)
+    this._texture.colorSpace = THREE.SRGBColorSpace
+
+    const geo = new THREE.PlaneGeometry(totalW, totalH)
+    geo.rotateX(-Math.PI / 2)
+
+    const mat = new THREE.MeshBasicMaterial({
+      map: this._texture,
+      alphaTest: 0.1,
+      side: THREE.DoubleSide,
+    })
+
+    this._mesh = new THREE.Mesh(geo, mat)
+    // 비대칭 패딩 보정: 플레인 센터를 컴포넌트 bounds 센터에 맞춤
+    this._mesh.position.x = (padRight - padLeft) / 2
+    this._mesh.position.y = 1
+    this._mesh.position.z = (padBottom - padTop) / 2
+    this.object3d.add(this._mesh)
+  }
+
+  update() {
+    if (this._mesh) {
+      this.object3d.remove(this._mesh)
+      this._mesh.geometry.dispose()
+      ;(this._mesh.material as THREE.Material).dispose()
+      this._texture?.dispose()
+      this._mesh = undefined
+      this._texture = undefined
+    }
+    this.build()
+    this.updateTransform()
+    this.updateHidden()
+  }
+
+  onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
+    if ('width' in after || 'height' in after || 'orientation' in after ||
+        'direction' in after || 'strokeStyle' in after || 'INOUTTYPE' in after) {
+      this.update()
+      return
+    }
+    super.onchange(after, before)
+  }
+
+  updateDimension() {}
+  updateAlpha() {}
+}
+
+registerRealObjectFactory('PortFlow', (component: Component) => new PortFlowRealObject3D(component))
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Node — 2D render를 바닥 Plane 텍스처로 3D 표시
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+class NodeRealObject3D extends RealObjectGroup {
+  private _mesh?: THREE.Mesh
+  private _texture?: THREE.CanvasTexture
+
+  get effectiveDepth(): number { return 0 }
+  protected get syncZPosOffset(): number { return 0 }
+
+  build() {
+    super.build()
+
+    const { cx, cy } = this.component.state
+    const radius = 8
+    const size = radius * 2
+    const scale = 2
+    const pad = 2
+
+    const canvas = document.createElement('canvas')
+    canvas.width = (size + pad * 2) * scale
+    canvas.height = (size + pad * 2) * scale
+    const ctx = canvas.getContext('2d')!
+
+    ctx.save()
+    ctx.scale(scale, scale)
+    ctx.translate(-cx + radius + pad, -cy + radius + pad)
+    try {
+      this.component.render(ctx)
+      const { fillStyle = '#888888' } = this.component.state
+      ctx.fillStyle = typeof fillStyle === 'string' ? fillStyle : '#888888'
+      ctx.fill()
+      const { strokeStyle } = this.component.state
+      if (strokeStyle && typeof strokeStyle === 'string') {
+        ctx.strokeStyle = strokeStyle
+        ctx.lineWidth = 1
+        ctx.stroke()
+      }
+    } catch { /* render 실패 시 빈 텍스처 */ }
+    ctx.restore()
+
+    this._texture = new THREE.CanvasTexture(canvas)
+    this._texture.colorSpace = THREE.SRGBColorSpace
+
+    const geo = new THREE.PlaneGeometry(size + pad * 2, size + pad * 2)
+    geo.rotateX(-Math.PI / 2)
+
+    const mat = new THREE.MeshBasicMaterial({
+      map: this._texture,
+      alphaTest: 0.1,
+      side: THREE.DoubleSide,
+    })
+
+    this._mesh = new THREE.Mesh(geo, mat)
+    this._mesh.position.y = 1
+    this.object3d.add(this._mesh)
+  }
+
+  update() {
+    if (this._mesh) {
+      this.object3d.remove(this._mesh)
+      this._mesh.geometry.dispose()
+      ;(this._mesh.material as THREE.Material).dispose()
+      this._texture?.dispose()
+      this._mesh = undefined
+      this._texture = undefined
+    }
+    this.build()
+    this.updateTransform()
+    this.updateHidden()
+  }
+
+  onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
+    if ('fillStyle' in after || 'strokeStyle' in after) {
+      this.update()
+      return
+    }
+    super.onchange(after, before)
+  }
+
+  updateDimension() {}
+  updateAlpha() {}
+}
+
+registerRealObjectFactory('Node', (component: Component) => new NodeRealObject3D(component))
+
+// Scanner — 이송 표면 높이의 기둥 형태
+const SCANNER_CONFIG: MCS3DConfig = {
+  ...DEFAULTS,
+  defaultDepth: TRANSPORT_SURFACE_HEIGHT * 0.2,
+  defaultZPosFromParent: true,
+  opacity: 1,
+  metalness: 0.3,
+  roughness: 0.7,
+  defaultColor: 0x888888,
+  shape: 'box',
+}
+registerRealObjectFactory('Scanner', (component: Component) => new MCSRealObject3D(component, SCANNER_CONFIG))