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

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

@@ -9,10 +9,19 @@
  */
 
 import * as THREE from 'three'
-import { RealObjectGroup, registerRealObjectFactory, disposeObject3D } from '@hatiolab/things-scene'
+import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
+import { RealObjectGroup, registerRealObjectFactory, disposeObject3D, MaterialBank } 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 { LEGEND_CAPACITY, resolveCarrierLegend } from '../features/mcs-status-default'
+import { getValueOnRanges } from '../utils/get-value-on-ranges'
+import { fitGaugeScale } from '../utils/fit-gauge-scale'
+import {
+  carrierSegmentsFromData,
+  abnormalSegmentsFromData,
+  carrierColorsFromLegend,
+  ABNORMAL_COLORS
+} from '../utils/stocker-gauge'
+import { Z_FMSIM } from './z-priority'
 
 // ── 설정 타입 ────────────────────────────────────────────
 
@@ -29,8 +38,8 @@ interface MCS3DConfig {
   roughness: number
   /** statusColor 미사용 시 기본 색상 */
   defaultColor: number
-  /** 'box' | 'hexagon' */
-  shape: 'box' | 'hexagon'
+  /** 'box' | 'hexagon' | 'plane' | 'triangle' */
+  shape: 'box' | 'hexagon' | 'plane' | 'triangle'
   /** mesh 생성 전 가시성 판정 — false 반환 시 mesh 미생성 */
   isVisible?: (component: Component) => boolean
   /** 부모 대비 크기 비율 (기본 1.0). < 1이면 부모 중심에 배치. */
@@ -41,6 +50,14 @@ interface MCS3DConfig {
   matteTop?: boolean
   /** 상판에 2D 렌더링 텍스처 적용 */
   texturedTop?: boolean
+  /** 자체 발광 강도 (0~1). 조명 약한 면에서도 색상 유지 */
+  emissiveIntensity?: number
+  /** 바닥면 유지 (기본 false — 바닥면 제거) */
+  keepBottomFace?: boolean
+  /** syncZPosOffset 고정값 (설정 시 다른 로직 무시) */
+  zPosOverride?: number
+  /** z-priority — polygonOffset 으로 z-fight 완화. 기본 0 (OBJECTS). */
+  zPriority?: number
 }
 
 /**
@@ -69,36 +86,68 @@ class MCSRealObject3D extends RealObjectGroup {
     this._config = config
   }
 
-  // width, height 절대값 (음수 값은 양수로 취급)
+  get zPriority(): number {
+    return this._config.zPriority ?? 0
+  }
+
+  // width, height 절대값 (음수 값은 양수로 취급).
+  // `resizable:false` 컴포넌트(예: Scanner)는 state.width/height 가 없고
+  // bounds 만 있을 수 있으므로 bounds 를 fallback 으로 사용.
+  //
+  // `??` only catches null/undefined — a property-panel input that produced
+  // NaN would slip through and corrupt every downstream Math.* call. Use a
+  // finite check so NaN falls through to bounds → 10 like missing values do.
   protected get absSize(): { w: number; h: number } {
-    const { width = 10, height = 10 } = this.component.state
+    const state = (this.component.state || {}) as any
+    const bounds = (this.component.bounds || {}) as any
+    const width = pickFinite(state.width, bounds.width, 10)
+    const height = pickFinite(state.height, bounds.height, 10)
     return { w: Math.abs(width), h: Math.abs(height) }
   }
 
   get effectiveDepth(): number {
     const { depth } = this.component.state
-    if (depth) return depth
+    // Truthy `if (depth)` already rejected NaN/0/undefined, but be explicit
+    // so the intent (and the resolution chain) reads cleanly: only an
+    // explicit positive finite number wins; everything else → defaults.
+    if (typeof depth === 'number' && Number.isFinite(depth) && depth > 0) {
+      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 {
+    // 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 색상 변환
   protected resolveColor(): number {
     const comp = this.component as any
@@ -107,14 +156,14 @@ class MCSRealObject3D 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 {
@@ -163,7 +212,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 {
@@ -194,6 +243,43 @@ 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
+  }
+
+  /**
+   * 삼각형 prism — 2D Triangle 의 꼭짓점(state.x1/y1, x2/y2, x3/y3) 을 그대로 사용.
+   * things-scene 의 TriangleExtrude 와 동일한 방식 — 각 Scanner 인스턴스의
+   * 실제 정점 배치(방향, 비대칭 등) 가 3D 에 반영된다.
+   *
+   * `geometry.center()` 로 로컬 원점을 bounding-box 중심으로 맞추므로
+   * 후속 placement 와 정합.
+   */
+  private buildTriangleGeometry(d: number): THREE.BufferGeometry {
+    const state = (this.component.state || {}) as any
+    const { x1 = 0, y1 = 0, x2 = 0, y2 = 0, x3 = 0, y3 = 0 } = state
+
+    const shape = new THREE.Shape()
+    shape.moveTo(x1, y1)
+    shape.lineTo(x2, y2)
+    shape.lineTo(x3, y3)
+    shape.closePath()
+
+    const geo = new THREE.ExtrudeGeometry(shape, {
+      steps: 1,
+      depth: d,
+      bevelEnabled: false,
+    })
+
+    // bounding box 중심으로 원점 정렬 후 Y-up 좌표계로 회전
+    geo.center()
+    geo.rotateX(Math.PI / 2)
+
+    return this.removeBottomFace(geo)
+  }
+
   // ── Build ──
 
   protected _ownMesh?: THREE.Mesh
@@ -217,20 +303,39 @@ 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,
-    })
-    // z-fighting 방지: 바닥면(floor grid)보다 항상 앞에 렌더링
+      shape === 'plane'
+        ? this.buildPlaneGeometry(w, h)
+        : shape === 'hexagon'
+          ? this.buildHexagonGeometry(w, depth, h)
+          : shape === 'triangle'
+            ? this.buildTriangleGeometry(depth)
+            : this.buildBoxGeometry(w, depth, h)
+
+    const isPlane = shape === 'plane'
+    // Standard body 는 MaterialBank 공유(색 변형) — 인스턴스 dedup + faint 안전(코어가 공유 base 의
+    // 변형만 스왑, 원본 base 불변). plane 은 unlit MeshBasicMaterial 이라 bank(Standard 전용) 비대상 → raw.
+    const material: THREE.Material = isPlane
+      ? new THREE.MeshBasicMaterial({
+          color,
+          opacity,
+          transparent: opacity < 1,
+          side: THREE.DoubleSide,
+        })
+      : MaterialBank.material(
+          'mcs|body',
+          {
+            metalness,
+            roughness,
+            opacity,
+            side: opacity < 1 ? THREE.DoubleSide : THREE.FrontSide,
+            ...(this._config.emissiveIntensity
+              ? { emissive: color, emissiveIntensity: this._config.emissiveIntensity }
+              : {}),
+          },
+          color,
+        )
+    // z-fighting 방지: 바닥면(floor grid)보다 앞. bank body 는 공유 base 라 polygonOffset 은 모든 mcs
+    // body 공통 상수 — 반환 material 에 세팅(같은 값이라 멱등, 인스턴스별 발산 없음).
     material.polygonOffset = true
     material.polygonOffsetFactor = -1
     material.polygonOffsetUnit = -1
@@ -254,11 +359,19 @@ class MCSRealObject3D extends RealObjectGroup {
     }
 
     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
+    // 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.object3d.add(this._ownMesh)
+    this.components3D.add(this._ownMesh)
+
+    // mesh 는 super.build() *이후* 생성되므로, 코어의 build-시점 faint 적용이 이 mesh 에 못 닿는다.
+    // mesh 생성 직후 명시 적용 — 코어 applyMaterialOpacity 가 content-alpha × faint 를 일괄 처리.
+    // view 모드에선 factor=1(=state.alpha 없음) → canonical(config.opacity) 그대로, 고객 화면 불변.
+    this.updateAlpha()
   }
 
   // ── Change handling ──
@@ -353,7 +466,7 @@ class MCSRealObject3D extends RealObjectGroup {
   update() {
     // 자신의 mesh만 제거 (자식 컴포넌트 3D 오브젝트 보존)
     if (this._ownMesh) {
-      this.object3d.remove(this._ownMesh)
+      this.components3D.remove(this._ownMesh)
       disposeObject3D(this._ownMesh)
       this._ownMesh = undefined
     }
@@ -367,22 +480,24 @@ class MCSRealObject3D extends RealObjectGroup {
   // 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
-      }
-    })
+  // updateAlpha override 제거 — 코어 RealObject.updateAlpha(=applyMaterialOpacity)로 수렴.
+  // 코어가 canonical(=build 시 config.opacity 로 만든 material) 위에 factor = state.alpha × faint 를
+  // 공유 변형 스왑으로 일괄 적용한다(원본 base 불변). 기존 in-place 변이는 (1) faint 미적용,
+  // (2) 코어 applyFocusDim 과 이중 적용 소지가 있어 방언이었다. config.opacity 는 canonical 로 보존.
+}
+
+// ── 헬퍼 ────────────────────────────────────────────────
+
+/**
+ * Returns the first argument that is a finite number. NaN slips past `??`
+ * (which only catches null/undefined), so without this a property-panel
+ * input producing NaN would corrupt absSize and cascade through Math.*.
+ */
+function pickFinite(...candidates: unknown[]): number {
+  for (const c of candidates) {
+    if (typeof c === 'number' && Number.isFinite(c)) return c
   }
+  return 0
 }
 
 // ── 팩토리 등록 헬퍼 ─────────────────────────────────────
@@ -402,6 +517,7 @@ register('Equipment', {
   metalness: 0.4,
   roughness: 0.6,
   defaultColor: 0x8899aa,
+  zPriority: Z_FMSIM.EQUIPMENT,
 })
 
 register('Buffer', {
@@ -411,21 +527,113 @@ register('Buffer', {
   roughness: 0.7,
   defaultColor: 0x99aa88,
   shape: 'hexagon',
+  zPriority: Z_FMSIM.BUFFER,
 })
 
 register('AGVLine', {
-  depthRatio: 0.12,
+  depthRatio: 0,
+  defaultDepth: 0.1,
   metalness: 0.6,
   roughness: 0.3,
   defaultColor: 0x888899,
+  zPriority: Z_FMSIM.AGV_LINE,
 })
 
-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 zPriority(): number { return Z_FMSIM.OHT_LINE }
+  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)       // 웹 두께
+
+    // 공유 base(MaterialBank) — OHTLine rail 은 정적 색이라 전 인스턴스 dedup. faint 는 코어가
+    // 공유 base 의 변형을 스왑(원본 불변). dispose 는 bank-safe(update 에서 material.dispose 안 함).
+    const mat = MaterialBank.material('oht-line|rail', { metalness: 0.5, roughness: 0.4 }, OHT_LINE_RAIL_COLOR)
+
+    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)
+
+    // mesh 가 super.build() 이후 생성 → 코어 faint 를 명시 적용(편집 흐림이 mesh 에 닿게).
+    this.updateAlpha()
+  }
+
+  update() {
+    if (this._mesh) {
+      this.object3d.remove(this._mesh)
+      this._mesh.geometry.dispose()
+      // material 은 MaterialBank 공유(앱 수명) — 여기서 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)
+  }
+
+  // updateAlpha override 제거 — 코어 RealObject.updateAlpha(=applyMaterialOpacity)로 수렴(faint).
+  updateDimension() {}
+}
+
+registerRealObjectFactory('OHTLine', (component: Component) => new OHTLineRealObject3D(component))
 
 // STOCKER: 벽면에 용량 게이지 바를 포함하는 커스텀 3D 오브젝트
 const STOCKER_CONFIG: MCS3DConfig = {
@@ -435,6 +643,7 @@ const STOCKER_CONFIG: MCS3DConfig = {
   metalness: 0.3,
   roughness: 0.6,
   defaultColor: 0x8899bb,
+  zPriority: Z_FMSIM.STOCKER,
 }
 
 class StockerRealObject3D extends MCSRealObject3D {
@@ -452,7 +661,7 @@ class StockerRealObject3D extends MCSRealObject3D {
   private buildGauge() {
     const comp = this.component as any
     const data = comp.data || {}
-    const gaugeMode = comp.root?.style?.stockerGaugeMode || 'capacity'
+    const gaugeMode = comp.root?.stockerGaugeMode || 'capacity'
 
     const gauge = this.resolveGauge(data, gaugeMode)
 
@@ -466,12 +675,20 @@ class StockerRealObject3D extends MCSRealObject3D {
     const depth = this.effectiveDepth
     const isWidthLonger = w >= h
 
-    // 게이지 캔버스 (고해상도)
-    const barW = 130
-    const barH = 26
+    // 게이지 최대 크기 (스토커가 충분히 크면 이 크기 그대로 사용).
+    const MAX_BAR_W = 130
+    const MAX_BAR_H = 26
+
+    // 스토커 지붕 footprint 에 맞춰 비례 축소 (확대는 안 함 — 현재 크기가 상한).
+    const fit = fitGaugeScale(w, h, MAX_BAR_W, MAX_BAR_H)
+
+    // PlaneGeometry 의 월드 크기는 clamp, 텍스처 캔버스 해상도는 최대 크기 기준 고정
+    // (축소되어도 선명도 유지).
+    const barW = MAX_BAR_W * fit
+    const barH = MAX_BAR_H * fit
     const scale = 4
-    const canvasW = barW * scale
-    const canvasH = barH * scale
+    const canvasW = MAX_BAR_W * scale
+    const canvasH = MAX_BAR_H * scale
     const canvas = document.createElement('canvas')
     canvas.width = canvasW
     canvas.height = canvasH
@@ -486,24 +703,32 @@ class StockerRealObject3D extends MCSRealObject3D {
     ctx.lineWidth = 12
     ctx.strokeRect(6, 6, canvasW - 12, canvasH - 12)
 
-    // 세그먼트 채움 (왼→오)
+    // 세그먼트 채움 (왼→오) + carrier/abnormal 은 세그먼트별 숫자(%) 표기 (2D 와 동일)
     const innerW = canvasW - pad * 2
     const innerH = canvasH - pad * 2
+    // 컴포넌트 폰트 설정(fontFamily/bold/italic) 을 그대로, 크기만 텍스처 scale 배 (2D 와 상대 크기 일치).
+    const fontSize = (Number((this.component as any).state?.fontSize) || 15) * scale
+    const font = this.gaugeFont(fontSize)
     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)
+      if (gauge.perSegment) {
+        this.drawGaugeSegmentNumber(ctx, seg.ratio, x, pad, segW, innerH, font, fontSize)
+      }
       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)
+    // capacity: 전체 중앙에 usage% 한 개 (2D 와 동일). carrier/abnormal 은 위 세그먼트별 숫자 사용.
+    if (gauge.label) {
+      ctx.font = font
+      ctx.textAlign = 'center'
+      ctx.textBaseline = 'middle'
+      ctx.fillStyle = '#333333'
+      ctx.fillText(gauge.label, canvasW / 2, canvasH / 2)
+    }
 
     // 텍스처 → Plane
     const texture = new THREE.CanvasTexture(canvas)
@@ -523,62 +748,107 @@ 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) {
+  private resolveGauge(
+    data: any,
+    mode: string
+  ): { segments: { ratio: number; color: string }[]; borderColor: string; label: string | null; perSegment: boolean } {
     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}` : '',
-        }
+        // 세그먼트 비율/색상은 2D 와 공유되는 단일 소스에서 계산 (필드/색상 drift 방지).
+        // 색상은 carrier 컴포넌트와 동일한 legend(테마)에서 취득.
+        const colors = carrierColorsFromLegend(resolveCarrierLegend(this.component))
+        const [f, e, ee] = carrierSegmentsFromData(data, colors)
+        const total = f.count + e.count + ee.count
+        // 접두사 없는 세그먼트별 숫자(%)로 표기 (capacity·2D 와 동일). label(중앙 한 개) 미사용.
+        return total > 0
+          ? {
+              segments: [f, e, ee].map(s => ({ ratio: s.ratio, color: s.color })),
+              borderColor: colors.full,
+              label: null,
+              perSegment: true,
+            }
+          : { segments: [{ ratio: 1, color: '#dddddd' }], borderColor: colors.full, label: null, perSegment: false }
       }
       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}` : '',
-        }
+        const [n, a] = abnormalSegmentsFromData(data)
+        const total = n.count + a.count
+        return total > 0
+          ? {
+              segments: [n, a].map(s => ({ ratio: s.ratio, color: s.color })),
+              borderColor: a.count > 0 ? ABNORMAL_COLORS.abnormal : ABNORMAL_COLORS.normal,
+              label: null,
+              perSegment: true,
+            }
+          : {
+              segments: [{ ratio: 1, color: '#dddddd' }],
+              borderColor: ABNORMAL_COLORS.normal,
+              label: null,
+              perSegment: false,
+            }
       }
-      default: { // capacity
+      default: { // capacity — 전체 중앙에 usage% 한 개
         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')
+        const legend = (this.component as any).root?.stockerCapacityLegendTheme || LEGEND_CAPACITY
+        const color = fullup ? 'red' : (getValueOnRanges(usage, legend) || '#44aa44')
         return {
           segments: [{ ratio: usage / 100, color }],
           borderColor: color,
           label: `${usage}%`,
+          perSegment: false,
         }
       }
     }
   }
 
+  /** 컴포넌트 폰트 설정(fontFamily/bold/italic)으로 CSS font 문자열 조합. size 는 텍스처 스케일 반영값. */
+  private gaugeFont(sizePx: number): string {
+    const st = (this.component as any).state || {}
+    const parts: string[] = []
+    if (st.bold) parts.push('bold')
+    if (st.italic) parts.push('italic')
+    parts.push(`${sizePx}px`)
+    parts.push(st.fontFamily || 'sans-serif')
+    return parts.join(' ')
+  }
+
+  /** 세그먼트 영역 중심에 숫자(%)만 표기. 좁으면 값% → 값 → 생략 (2D _drawSegmentLabel 과 동일 정책). */
+  private drawGaugeSegmentNumber(
+    ctx: CanvasRenderingContext2D,
+    ratio: number,
+    x: number,
+    y: number,
+    w: number,
+    h: number,
+    font: string,
+    fontSize: number
+  ) {
+    ctx.font = font
+    ctx.textAlign = 'center'
+    ctx.textBaseline = 'middle'
+    ctx.fillStyle = '#333333'
+    const value = `${Math.round(ratio * 100)}`
+    const cx = x + w / 2
+    const cy = y + h / 2
+    if (fontSize <= h && ctx.measureText(`${value}%`).width <= w) {
+      ctx.fillText(`${value}%`, cx, cy)
+    } else if (fontSize <= h && ctx.measureText(value).width <= w) {
+      ctx.fillText(value, cx, cy)
+    }
+  }
+
+  update() {
+    this.clearGauge()
+    super.update()
+  }
+
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
     if ('data' in after) {
       this.clearGauge()
@@ -594,7 +864,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()
@@ -610,16 +880,17 @@ registerRealObjectFactory('STOCKER', (component: Component) => new StockerRealOb
 //  Unit (이동체 · 홀더) — 낮은 depth, 불투명
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-// Port: 상부 개방 5면 박스
+// Port: 바닥판 (PlaneGeometry)
 const PORT_CONFIG: MCS3DConfig = {
   ...DEFAULTS,
-  depthRatio: 0.5,
+  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,
-  openTop: true,
+  shape: 'plane',
+  zPriority: Z_FMSIM.PORT,
 }
 registerRealObjectFactory('Port', (component: Component) => new MCSRealObject3D(component, PORT_CONFIG))
 
@@ -628,140 +899,295 @@ register('Shelf', {
   metalness: 0.3,
   roughness: 0.7,
   defaultColor: 0xaabbcc,
+  zPriority: Z_FMSIM.SHELF,
 })
 
 // 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,
+  // Carrier 는 이동 entity — default OBJECTS(0). zPriority 미설정.
 }
 
-class CarrierRealObject3D extends MCSRealObject3D {
-  private _animRaf: number | null = null
-  private _animStartTime = 0
+/**
+ * 적층 시 다음 carrier 의 z-position 이 *_이전 carrier 의 effectiveDepth × N*
+ * 만큼 위에 놓인다. N=1 이면 carrier 들이 맞붙어 적층 (기존), N<1 이면 부분
+ * overlap (3D box 들이 겹쳐서 적층). 사용자 의도 — carrier 두께는 두꺼워도
+ * 적층 시 *_compact 하게 보이도록* — N 을 작게.
+ */
+const CARRIER_STACK_STEP_RATIO = 0.9
 
+class CarrierRealObject3D extends MCSRealObject3D {
   constructor(component: Component) {
     super(component, CARRIER_CONFIG)
   }
 
-  build() {
-    super.build()
-    this.startCarrierAnimation()
-  }
-
   /**
-   * CARRIERSTATUS의 애니메이션 설정을 읽어 3D에서 직접 실행.
-   * things-scene의 delta 시스템과 독립적으로 동작.
+   * cz override — *carrier 자기 결정* 의 적층 위치.
+   * parent.components 안 자기 index 까지의 형제 carrier 들의 effectiveDepth
+   * 누적합을 base cz 위에 더한다. holder 측에 별도 layout 책임을 두지 않고,
+   * carrier 가 자기 stack 위치를 알아서 결정.
    */
-  private startCarrierAnimation() {
-    this.stopCarrierAnimation()
+  override get cz(): number {
+    const base = super.cz
+    const parent = this.component.parent as any
+    if (!parent?.components) return base
+    const siblings = parent.components as any[]
+    const idx = siblings.indexOf(this.component)
+    if (idx <= 0) return base
+    let offset = 0
+    for (let i = 0; i < idx; i++) {
+      const ro = siblings[i]?._realObject
+      const eff = Number(ro?.effectiveDepth)
+      const d = Number.isFinite(eff) && eff > 0 ? eff : 1
+      offset += d * CARRIER_STACK_STEP_RATIO
+    }
+    // 적층 방향 — placement (= 부모 holder 타입) 에 따라 결정.
+    // OHT 처럼 그리퍼 아래에 매달리는 holder 는 carrier 가 *_아래로_* 누적,
+    // 그 외 (Port / Shelf / Shuttle / Vehicle) 는 위로 누적.
+    // MCSRealObject3D.syncZPosOffset 의 OHT 분기 (-effectiveDepth + halfD) 와
+    // 같은 방향성 일관 적용.
+    const parentType = parent?.state?.type
+    const dir = parentType === 'OHT' ? -1 : 1
+    return base + dir * offset
+  }
+}
 
-    const comp = this.component as any
-    if (!comp.app?.isViewMode) return
+registerRealObjectFactory('Carrier', (component: Component) => new CarrierRealObject3D(component))
 
-    const carrierStatus = comp.state?.CARRIERSTATUS
-    if (!carrierStatus) return
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Gauge (용량 게이지) — 얇은 바
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-    // 애니메이션 설정 가져오기
-    const config = comp.getAnimationConfig?.(carrierStatus)
-    if (!config?.animation) return
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  Gauge (용량 게이지) — 2D 렌더링을 Plane 텍스처로 3D 표시
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-    const { type, duration = 2000, scale: animScale = 1.3 } = config.animation
-    if (!type) return
+// Gauge 컴포넌트는 3D에서 표시하지 않음 (부모 STOCKER의 3D 모델에서 직접 게이지 렌더링)
+// null 반환으로 3D 오브젝트 생성을 억제하고, default factory fallback도 방지
+registerRealObjectFactory('StockerCapacityBar', () => undefined as any)
+registerRealObjectFactory('MCSGaugeCapacityBar', () => undefined as any)
+registerRealObjectFactory('ZoneCapacityBar', () => undefined as any)
 
-    this._animStartTime = performance.now()
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+//  PortFlow — 2D render를 Plane 텍스처로 3D 표시
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-    // 애니메이션 대상: group(object3d) — mesh 개별 변환 대신 group 전체를 변환하여
-    // 회전/스케일 중심이 component의 3D 위치(= 2D 중심)와 정확히 일치하도록 함
-    const obj = this.object3d
+class PortFlowRealObject3D extends RealObjectGroup {
+  private _mesh?: THREE.Mesh
+  private _texture?: THREE.CanvasTexture
 
-    const animate = () => {
-      if (!this._ownMesh) return
+  get zPriority(): number { return Z_FMSIM.PORT_FLOW }
+  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
+  }
 
-      const elapsed = performance.now() - this._animStartTime
-      const progress = (elapsed % duration) / duration // 0~1 반복
+  build() {
+    super.build()
 
-      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
-        }
+    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
       }
-
-      this._animRaf = requestAnimationFrame(animate)
     }
 
-    this._animRaf = requestAnimationFrame(animate)
-  }
+    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')!
 
-  // 자체 애니메이션이 실행 중이면 things-scene의 syncAnimationDelta 비활성화
-  syncAnimationDelta() {
-    if (!this._animRaf) {
-      super.syncAnimationDelta()
-    }
-  }
+    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()
 
-  private stopCarrierAnimation() {
-    if (this._animRaf) {
-      cancelAnimationFrame(this._animRaf)
-      this._animRaf = null
-    }
-    // group 스케일/회전 초기화
-    this.object3d.scale.set(1, 1, 1)
-    this.object3d.rotation.y = 0
+    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() {
-    this.stopCarrierAnimation()
-    super.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()
   }
 
-  clear() {
-    this.stopCarrierAnimation()
-    return super.clear()
+  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('Carrier', (component: Component) => new CarrierRealObject3D(component))
+registerRealObjectFactory('PortFlow', (component: Component) => new PortFlowRealObject3D(component))
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-//  Gauge (용량 게이지) — 얇은 바
+//  Node — 2D render를 바닥 Plane 텍스처로 3D 표시
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-//  Gauge (용량 게이지) — 2D 렌더링을 Plane 텍스처로 3D 표시
-// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+class NodeRealObject3D extends RealObjectGroup {
+  private _mesh?: THREE.Mesh
+  private _texture?: THREE.CanvasTexture
+
+  get zPriority(): number { return Z_FMSIM.NODE }
+  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() {}
+}
 
-// Gauge 컴포넌트 (StockerCapacityBar, ZoneCapacityBar, MCSGaugeCapacityBar)는
-// 3D에서 표시하지 않음. 대신 부모(STOCKER 등)의 3D 모델에서 직접 게이지를 렌더링.
-registerRealObjectFactory('StockerCapacityBar', () => null as any)
-registerRealObjectFactory('MCSGaugeCapacityBar', () => null as any)
-registerRealObjectFactory('ZoneCapacityBar', () => null as any)
+registerRealObjectFactory('Node', (component: Component) => new NodeRealObject3D(component))
+
+// Scanner — 2D Triangle 실루엣과 정합되는 삼각형 prism.
+// 이송 표면 높이의 0.2배(=6) 얇은 기둥 — 원래 값 유지, shape 만 'box' → 'triangle'.
+const SCANNER_CONFIG: MCS3DConfig = {
+  ...DEFAULTS,
+  defaultDepth: TRANSPORT_SURFACE_HEIGHT * 0.2,
+  defaultZPosFromParent: true,
+  opacity: 1,
+  metalness: 0.3,
+  roughness: 0.7,
+  defaultColor: 0x888888,
+  shape: 'triangle',
+  zPriority: Z_FMSIM.SCANNER,
+}
+registerRealObjectFactory('Scanner', (component: Component) => new MCSRealObject3D(component, SCANNER_CONFIG))