@fmsim/machine 2.0.0-beta.99 → 2.0.1

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

@@ -10,15 +10,15 @@
 
 import * as THREE from 'three'
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
-import { RealObjectGroup, registerRealObjectFactory, disposeObject3D } from '@hatiolab/things-scene'
+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 { 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,
-  CARRIER_COLORS,
+  carrierColorsFromLegend,
   ABNORMAL_COLORS
 } from '../utils/stocker-gauge'
 import { Z_FMSIM } from './z-priority'
@@ -312,23 +312,30 @@ class MCSRealObject3D extends RealObjectGroup {
             : this.buildBoxGeometry(w, depth, h)
 
     const isPlane = shape === 'plane'
-    const material = isPlane
+    // 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,
         })
-      : new THREE.MeshStandardMaterial({
+      : MaterialBank.material(
+          'mcs|body',
+          {
+            metalness,
+            roughness,
+            opacity,
+            side: opacity < 1 ? THREE.DoubleSide : THREE.FrontSide,
+            ...(this._config.emissiveIntensity
+              ? { emissive: color, emissiveIntensity: this._config.emissiveIntensity }
+              : {}),
+          },
           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)보다 항상 앞에 렌더링
+        )
+    // z-fighting 방지: 바닥면(floor grid)보다 앞. bank body 는 공유 base 라 polygonOffset 은 모든 mcs
+    // body 공통 상수 — 반환 material 에 세팅(같은 값이라 멱등, 인스턴스별 발산 없음).
     material.polygonOffset = true
     material.polygonOffsetFactor = -1
     material.polygonOffsetUnit = -1
@@ -360,6 +367,11 @@ class MCSRealObject3D extends RealObjectGroup {
     this._ownMesh.castShadow = !isPlane
     this._ownMesh.receiveShadow = true
     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 ──
@@ -375,7 +387,8 @@ class MCSRealObject3D extends RealObjectGroup {
       'strokeStyle' in after ||
       'id' in after ||
       'EMPTYTYPE' in after ||
-      'CARRIERSTATUS' in after
+      'CARRIERSTATUS' in after ||
+      'showText' in after
     ) {
       // 연속 setState에 의한 다중 rebuild 방지: 한 프레임에 한 번만 실행
       if (!this._updatePending) {
@@ -415,8 +428,9 @@ class MCSRealObject3D extends RealObjectGroup {
     ctx.fillStyle = statusColor
     ctx.fillRect(0, 0, usedW, usedH)
 
-    // 텍스트 (사용 영역 중앙)
-    if (text) {
+    // 텍스트 (사용 영역 중앙) — showText(= 현재 홀더의 showCarrierText) off 면 미표시. 2D 와 동일.
+    const showText = !!(this.component.state as any)?.showText
+    if (text && showText) {
       const fontSize = Math.round(Math.min(usedW, usedH) * 0.7)
       ctx.font = `bold ${fontSize}px Arial`
       ctx.textAlign = 'center'
@@ -468,22 +482,10 @@ class MCSRealObject3D extends RealObjectGroup {
   // RealObjectGroup 기본 동작 비활성화
   updateDimension() {}
 
-  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
-      }
-    })
-  }
+  // updateAlpha override 제거 — 코어 RealObject.updateAlpha(=applyMaterialOpacity)로 수렴.
+  // 코어가 canonical(=build 시 config.opacity 로 만든 material) 위에 factor = state.alpha × faint 를
+  // 공유 변형 스왑으로 일괄 적용한다(원본 base 불변). 기존 in-place 변이는 (1) faint 미적용,
+  // (2) 코어 applyFocusDim 과 이중 적용 소지가 있어 방언이었다. config.opacity 는 canonical 로 보존.
 }
 
 // ── 헬퍼 ────────────────────────────────────────────────
@@ -573,11 +575,9 @@ class OHTLineRealObject3D extends RealObjectGroup {
     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,
-    })
+    // 공유 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[] = []
 
@@ -605,13 +605,16 @@ class OHTLineRealObject3D extends RealObjectGroup {
     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()
-      ;(this._mesh.material as THREE.Material).dispose()
+      // material 은 MaterialBank 공유(앱 수명) — 여기서 dispose 하면 다른 인스턴스가 깨진다.
       this._mesh = undefined
     }
     this.build()
@@ -628,8 +631,8 @@ class OHTLineRealObject3D extends RealObjectGroup {
     super.onchange(after, before)
   }
 
+  // updateAlpha override 제거 — 코어 RealObject.updateAlpha(=applyMaterialOpacity)로 수렴(faint).
   updateDimension() {}
-  updateAlpha() {}
 }
 
 registerRealObjectFactory('OHTLine', (component: Component) => new OHTLineRealObject3D(component))
@@ -702,24 +705,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)
@@ -744,34 +755,45 @@ class StockerRealObject3D extends MCSRealObject3D {
     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': {
-        // 세그먼트 비율/색상은 2D 와 공유되는 단일 소스에서 계산 (필드/색상 drift 방지)
-        const [f, e, ee] = carrierSegmentsFromData(data)
+        // 세그먼트 비율/색상은 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
-        const segments = total > 0
-          ? [f, e, ee].map(s => ({ ratio: s.ratio, color: s.color }))
-          : [{ ratio: 1, color: '#dddddd' }]
-        return {
-          segments,
-          borderColor: CARRIER_COLORS.full,
-          label: total > 0 ? `F${f.count} E${e.count} EE${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 [n, a] = abnormalSegmentsFromData(data)
         const total = n.count + a.count
-        const segments = total > 0
-          ? [n, a].map(s => ({ ratio: s.ratio, color: s.color }))
-          : [{ ratio: 1, color: '#dddddd' }]
-        return {
-          segments,
-          borderColor: a.count > 0 ? ABNORMAL_COLORS.abnormal : ABNORMAL_COLORS.normal,
-          label: total > 0 ? `N${n.count} A${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'
@@ -782,11 +804,48 @@ class StockerRealObject3D extends MCSRealObject3D {
           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()

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

@@ -12,7 +12,7 @@
 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, disposeObject3D } from '@hatiolab/things-scene'
+import { RealObjectGroup, registerRealObjectFactory, disposeObject3D, MaterialBank } from '@hatiolab/things-scene'
 import type { Component } from '@hatiolab/things-scene'
 import { TRANSPORT_SURFACE_HEIGHT } from './machine-3d.js'
 
@@ -77,11 +77,8 @@ export class OHT3D extends RealObjectGroup {
     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,
-    })
+    // MaterialBank 공유 — dedup + faint 안전(코어 변형 스왑, disposeObject3D 가 __bankOwned 스킵).
+    const frameMat = MaterialBank.material('oht|frame', { roughness: 0.5, metalness: 0.4 }, FRAME_COLOR)
 
     // ── 1. 하단 그리퍼 바 (캐리어를 집는 가로 바 — 이동 방향과 직교) ──
     const gripperBarW = w * 0.7
@@ -116,11 +113,7 @@ export class OHT3D extends RealObjectGroup {
     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 bodyMat = MaterialBank.material('oht|body', { roughness: 0.3, metalness: 0.5 }, bodyColor)
     const bodyMesh = new THREE.Mesh(bodyGeo, bodyMat)
     bodyMesh.position.y = bodyBaseY + bodyH / 2
     bodyMesh.castShadow = true
@@ -131,11 +124,7 @@ export class OHT3D extends RealObjectGroup {
     const trolleyW = w * 0.6
     const trolleyD = h * 1.15
     const trolleyGeo = new THREE.BoxGeometry(trolleyW, trolleyH, trolleyD)
-    const trolleyMat = new THREE.MeshStandardMaterial({
-      color: TROLLEY_COLOR,
-      roughness: 0.6,
-      metalness: 0.3,
-    })
+    const trolleyMat = MaterialBank.material('oht|trolley', { roughness: 0.6, metalness: 0.3 }, TROLLEY_COLOR)
     const trolleyMesh = new THREE.Mesh(trolleyGeo, trolleyMat)
     trolleyMesh.position.y = trolleyBaseY + trolleyH / 2
     trolleyMesh.castShadow = true
@@ -156,6 +145,9 @@ export class OHT3D extends RealObjectGroup {
 
     this._ownMeshes = [gripperMesh, armMesh, bodyMesh, trolleyMesh, ...wheelMeshes]
     for (const m of this._ownMeshes) this.components3D.add(m)
+
+    // mesh 는 super.build() 이후 생성 → 코어 faint 를 명시 적용(편집 흐림이 mesh 에 닿게).
+    this.updateAlpha()
   }
 
   updateDimension() {}
@@ -172,16 +164,8 @@ export class OHT3D extends RealObjectGroup {
     this.updateHidden()
   }
 
-  updateAlpha() {
-    const { alpha = 1 } = this.component.state
-    for (const m of this._ownMeshes) {
-      const materials = Array.isArray(m.material) ? m.material : [m.material]
-      for (const mat of materials) {
-        ;(mat as THREE.MeshStandardMaterial).opacity = alpha
-        ;(mat as THREE.MeshStandardMaterial).transparent = alpha < 1
-      }
-    }
-  }
+  // updateAlpha override 제거 — 코어 RealObject.updateAlpha(=applyMaterialOpacity)로 수렴.
+  // canonical(bank base opacity 1) × state.alpha × faint. view 모드 불변, 편집 모드 faint 추가.
 
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
     if ('width' in after || 'height' in after || 'depth' in after ||

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

@@ -12,7 +12,7 @@
 
 import * as THREE from 'three'
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
-import { RealObjectGroup, registerRealObjectFactory, disposeObject3D } from '@hatiolab/things-scene'
+import { RealObjectGroup, registerRealObjectFactory, disposeObject3D, MaterialBank } from '@hatiolab/things-scene'
 import type { Component } from '@hatiolab/things-scene'
 import { TRANSPORT_SURFACE_HEIGHT } from './machine-3d.js'
 
@@ -68,11 +68,9 @@ export class Shuttle3D extends RealObjectGroup {
     // ── 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,
-    })
+    // MaterialBank 공유 — 정적/상태색 dedup + faint 안전(코어가 공유 base 변형 스왑). dispose 는
+    // disposeObject3D 가 __bankOwned 를 건너뛰어 안전.
+    const baseMat = MaterialBank.material('shuttle|base', { roughness: 0.7, metalness: 0.3 }, BASE_COLOR)
     const baseMesh = new THREE.Mesh(baseGeo, baseMat)
     baseMesh.position.y = baseH / 2
     baseMesh.castShadow = true
@@ -81,11 +79,7 @@ export class Shuttle3D extends RealObjectGroup {
     // ── 2. 좌우 마스트 기둥 (statusColor 적용) ──
     const mastBaseY = baseH
     const bodyColor = this.resolveColor()
-    const mastMat = new THREE.MeshStandardMaterial({
-      color: bodyColor,
-      roughness: 0.4,
-      metalness: 0.5,
-    })
+    const mastMat = MaterialBank.material('shuttle|mast', { roughness: 0.4, metalness: 0.5 }, bodyColor)
 
     const mastGeometries: THREE.BufferGeometry[] = []
 
@@ -108,11 +102,7 @@ export class Shuttle3D extends RealObjectGroup {
 
     // ── 3. 상단 포크 (2개의 평행 암 + 백 플레이트) ──
     const forkBaseY = mastBaseY + mastH
-    const forkMat = new THREE.MeshStandardMaterial({
-      color: FORK_COLOR,
-      roughness: 0.4,
-      metalness: 0.6,
-    })
+    const forkMat = MaterialBank.material('shuttle|fork', { roughness: 0.4, metalness: 0.6 }, FORK_COLOR)
 
     const forkGeometries: THREE.BufferGeometry[] = []
 
@@ -139,6 +129,9 @@ export class Shuttle3D extends RealObjectGroup {
 
     this._ownMeshes = [baseMesh, mastMesh, forkMesh]
     for (const m of this._ownMeshes) this.components3D.add(m)
+
+    // mesh 는 super.build() 이후 생성 → 코어 faint 를 명시 적용(편집 흐림이 mesh 에 닿게).
+    this.updateAlpha()
   }
 
   updateDimension() {}
@@ -155,16 +148,9 @@ export class Shuttle3D extends RealObjectGroup {
     this.updateHidden()
   }
 
-  updateAlpha() {
-    const { alpha = 1 } = this.component.state
-    for (const m of this._ownMeshes) {
-      const materials = Array.isArray(m.material) ? m.material : [m.material]
-      for (const mat of materials) {
-        ;(mat as THREE.MeshStandardMaterial).opacity = alpha
-        ;(mat as THREE.MeshStandardMaterial).transparent = alpha < 1
-      }
-    }
-  }
+  // updateAlpha override 제거 — 코어 RealObject.updateAlpha(=applyMaterialOpacity)로 수렴.
+  // 코어가 canonical(=bank base, opacity 1) 위에 state.alpha × faint 를 일괄. view 모드는
+  // 1×state.alpha = 기존 in-place 결과와 동일 → 불변, 편집 모드만 faint 추가.
 
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
     if ('width' in after || 'height' in after || 'depth' in after ||