@fmsim/machine 2.0.0-beta.100 → 2.0.0-beta.104

package/package.json

@@ -2,7 +2,7 @@
   "name": "@fmsim/machine",
   "description": "Layout View를 구성하는 설비(machine)들과 유닛을 구현한 모듈입니다.",
   "author": "heartyoh",
-  "version": "2.0.0-beta.100",
+  "version": "2.0.0-beta.104",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "things-scene": true,
@@ -55,5 +55,5 @@
       "prettier --write"
     ]
   },
-  "gitHead": "332f5d01766a2621d1dc9ca745aa764acfd9c960"
+  "gitHead": "9fd007d34fca773bdf6aa56f06f2ff9b189133d8"
 }

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

@@ -15,7 +15,7 @@
 
 import * as THREE from 'three'
 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'
 
@@ -76,11 +76,8 @@ export class AGV3D extends RealObjectGroup {
     const bumperPad = Math.min(w, h) * 0.03
     const bumperCornerR = Math.min(w + bumperPad * 2, h + bumperPad * 2, bumperH) * 0.2
     const bumperGeo = new RoundedBoxGeometry(w + bumperPad * 2, bumperH, h + bumperPad * 2, 4, bumperCornerR)
-    const bumperMat = new THREE.MeshStandardMaterial({
-      color: BUMPER_COLOR,
-      roughness: 0.8,
-      metalness: 0.1,
-    })
+    // MaterialBank 공유 — dedup + faint 안전(코어 변형 스왑, disposeObject3D 가 __bankOwned 스킵).
+    const bumperMat = MaterialBank.material('agv|bumper', { roughness: 0.8, metalness: 0.1 }, BUMPER_COLOR)
     const bumper = new THREE.Mesh(bumperGeo, bumperMat)
     bumper.position.y = bumperH / 2
     bumper.castShadow = true
@@ -89,11 +86,7 @@ export class AGV3D extends RealObjectGroup {
     // ── 본체 (둥근 모서리, statusColor 적용) ──
     const bodyColor = this.resolveColor()
     const bodyGeo = new RoundedBoxGeometry(w, bodyH, h, 4, cornerR)
-    const bodyMat = new THREE.MeshStandardMaterial({
-      color: bodyColor,
-      roughness: 0.3,
-      metalness: 0.5,
-    })
+    const bodyMat = MaterialBank.material('agv|body', { roughness: 0.3, metalness: 0.5 }, bodyColor)
     const body = new THREE.Mesh(bodyGeo, bodyMat)
     body.position.y = bumperH + bodyH / 2
     body.castShadow = true
@@ -103,11 +96,7 @@ export class AGV3D extends RealObjectGroup {
     const platInset = Math.min(w, h) * 0.04
     const platCornerR = Math.min(w - platInset * 2, h - platInset * 2, platH) * 0.15
     const platGeo = new RoundedBoxGeometry(w - platInset * 2, platH, h - platInset * 2, 4, platCornerR)
-    const platMat = new THREE.MeshStandardMaterial({
-      color: PLATFORM_COLOR,
-      roughness: 0.5,
-      metalness: 0.15,
-    })
+    const platMat = MaterialBank.material('agv|platform', { roughness: 0.5, metalness: 0.15 }, PLATFORM_COLOR)
     const plat = new THREE.Mesh(platGeo, platMat)
     plat.position.y = bumperH + bodyH + gapH + platH / 2
     plat.castShadow = true
@@ -116,6 +105,9 @@ export class AGV3D extends RealObjectGroup {
     this._ownMeshes = [bumper, body, plat]
     // ownGroup이 center-origin ↔ bottom-up 좌표계 변환을 자동 처리
     for (const m of this._ownMeshes) this.components3D.add(m)
+
+    // mesh 는 super.build() 이후 생성 → 코어 faint 를 명시 적용(편집 흐림이 mesh 에 닿게).
+    this.updateAlpha()
   }
 
   updateDimension() {}
@@ -134,16 +126,8 @@ export class AGV3D 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/conveyor-3d.ts

@@ -13,7 +13,7 @@
 
 import * as THREE from 'three'
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
-import { RealObjectGroup, registerRealObjectFactory } from '@hatiolab/things-scene'
+import { RealObjectGroup, registerRealObjectFactory, MaterialBank } from '@hatiolab/things-scene'
 import type { Component } from '@hatiolab/things-scene'
 import { TRANSPORT_SURFACE_HEIGHT } from './machine-3d.js'
 import { Z_FMSIM } from './z-priority'
@@ -85,11 +85,8 @@ export class Conveyor3D extends RealObjectGroup {
     const railW = Math.max(beltWidth * 0.06, 2)
     const legThickness = Math.max(railW * 0.8, 2)
 
-    const frameMaterial = new THREE.MeshStandardMaterial({
-      color: FRAME_COLOR,
-      metalness: 0.85,
-      roughness: 0.35,
-    })
+    // MaterialBank 공유(dedup). 자체 update() 없이 base 생명주기(guarded disposeObject3D) 상속 → 안전.
+    const frameMaterial = MaterialBank.material('conveyor|frame', { metalness: 0.85, roughness: 0.35 }, FRAME_COLOR)
 
     // --- Frame: side rails + legs + cross-bracing ---
     // Y 좌표: y=0(바닥) ~ y=depth(상단). 레일 상단이 depth에 위치.
@@ -179,6 +176,9 @@ export class Conveyor3D extends RealObjectGroup {
     } else {
       this.buildRollers(width, height, depth, frameH, railW, rollWidth, isVertical)
     }
+
+    // mesh 는 super.build() 이후 생성 → 코어 faint 를 명시 적용(편집 흐림이 mesh 에 닿게).
+    this.updateAlpha()
   }
 
   private buildRollers(
@@ -231,7 +231,7 @@ export class Conveyor3D extends RealObjectGroup {
     if (rollerGeometries.length > 0) {
       const rollerMesh = new THREE.Mesh(
         BufferGeometryUtils.mergeGeometries(rollerGeometries),
-        new THREE.MeshStandardMaterial({ color, metalness: 0.9, roughness: 0.2 })
+        MaterialBank.material('conveyor|roller', { metalness: 0.9, roughness: 0.2 }, color)
       )
       rollerMesh.castShadow = true
       this.components3D.add(rollerMesh)
@@ -268,18 +268,14 @@ export class Conveyor3D extends RealObjectGroup {
 
     const drumMesh = new THREE.Mesh(
       BufferGeometryUtils.mergeGeometries(drumGeometries),
-      new THREE.MeshStandardMaterial({ color: ROLLER_COLOR, metalness: 0.9, roughness: 0.2 })
+      MaterialBank.material('conveyor|drum', { metalness: 0.9, roughness: 0.2 }, ROLLER_COLOR)
     )
     drumMesh.castShadow = true
     this.components3D.add(drumMesh)
 
     // Belt surface
     const beltThickness = drumRadius * 0.12
-    const beltMaterial = new THREE.MeshStandardMaterial({
-      color: color,
-      metalness: 0.0,
-      roughness: 0.9,
-    })
+    const beltMaterial = MaterialBank.material('conveyor|belt', { metalness: 0.0, roughness: 0.9 }, color)
 
     // Flat belt top surface spanning between drums
     const flatLen = drum2 - drum1
@@ -347,11 +343,7 @@ export class Conveyor3D extends RealObjectGroup {
     // 두 레일 간격: 내부 폭의 60%
     const railSpacing = innerWidth * 0.6
 
-    const railMaterial = new THREE.MeshStandardMaterial({
-      color,
-      metalness: 0.7,
-      roughness: 0.3,
-    })
+    const railMaterial = MaterialBank.material('conveyor|rail', { metalness: 0.7, roughness: 0.3 }, color)
 
     const railGeometries: THREE.BufferGeometry[] = []
 
@@ -376,7 +368,8 @@ export class Conveyor3D extends RealObjectGroup {
   }
 
   updateDimension() {}
-  updateAlpha() {}
+  // updateAlpha override 제거 — 코어 RealObject.updateAlpha(=applyMaterialOpacity)로 수렴(faint).
+  // view 모드는 factor=1 → build-시 opacity 그대로(불변), 편집 모드만 faint 추가.
 
   onchange(after: Record<string, unknown>, before: Record<string, unknown>) {
     if (

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

@@ -13,7 +13,7 @@
 
 import * as THREE from 'three'
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
-import { RealObjectGroup, registerRealObjectFactory } from '@hatiolab/things-scene'
+import { RealObjectGroup, registerRealObjectFactory, MaterialBank } from '@hatiolab/things-scene'
 import type { Component } from '@hatiolab/things-scene'
 import { TRANSPORT_SURFACE_HEIGHT } from './machine-3d.js'
 
@@ -84,11 +84,8 @@ export class Crane3D extends RealObjectGroup {
 
     const pillarThick = Math.min(w, h) * 0.12
 
-    const clampMat = new THREE.MeshStandardMaterial({
-      color: CLAMP_COLOR,
-      roughness: 0.5,
-      metalness: 0.5,
-    })
+    // MaterialBank 공유(dedup). 자체 update() 없이 base 생명주기(guarded disposeObject3D) 상속 → 안전.
+    const clampMat = MaterialBank.material('crane|clamp', { roughness: 0.5, metalness: 0.5 }, CLAMP_COLOR)
 
     // ── 1. 하단 클램프 (바닥 레일에 물리는 바퀴부) ──
     const clampW = w * 0.7
@@ -102,11 +99,7 @@ export class Crane3D extends RealObjectGroup {
     // ── 2. 수직 마스트 (좌우 기둥 + 상·하 가로 연결 바) ──
     const mastBaseY = clampH
     const bodyColor = this.resolveColor()
-    const mastMat = new THREE.MeshStandardMaterial({
-      color: bodyColor,
-      roughness: 0.3,
-      metalness: 0.6,
-    })
+    const mastMat = MaterialBank.material('crane|mast', { roughness: 0.3, metalness: 0.6 }, bodyColor)
 
     const mastGeometries: THREE.BufferGeometry[] = []
 
@@ -137,11 +130,7 @@ export class Crane3D extends RealObjectGroup {
     // 포크 geometry 는 *_mastBaseY 기준 local 0 에 둠* — 즉 group.position.y = 0
     // 일 때 mast 바닥 자리에. forkZ 0~100 에 따라 group.position.y 만 변경하면
     // mast 따라 위/아래 이동. mesh 재구축 불필요.
-    const forkMat = new THREE.MeshStandardMaterial({
-      color: FORK_COLOR,
-      roughness: 0.4,
-      metalness: 0.5,
-    })
+    const forkMat = MaterialBank.material('crane|fork', { roughness: 0.4, metalness: 0.5 }, FORK_COLOR)
 
     const forkGeometries: THREE.BufferGeometry[] = []
 
@@ -188,10 +177,13 @@ export class Crane3D extends RealObjectGroup {
     topClamp.position.y = mastBaseY + mastH + clampH / 2
     topClamp.castShadow = true
     inner.add(topClamp)
+
+    // mesh 는 super.build() 이후 생성 → 코어 faint 를 명시 적용(편집 흐림이 mesh 에 닿게).
+    this.updateAlpha()
   }
 
   updateDimension() {}
-  updateAlpha() {}
+  // updateAlpha override 제거 — 코어 RealObject.updateAlpha(=applyMaterialOpacity)로 수렴(faint).
 
   /** build() 직전 호출. forkGroup 참조를 깨끗이 비워둔다 — 새 build 가 다시 set. */
   clear() {

package/src/factories/crane-rail-3d.ts

@@ -12,7 +12,7 @@
 
 import * as THREE from 'three'
 import * as BufferGeometryUtils from 'three/examples/jsm/utils/BufferGeometryUtils.js'
-import { RealObjectGroup, registerRealObjectFactory } from '@hatiolab/things-scene'
+import { RealObjectGroup, registerRealObjectFactory, MaterialBank } from '@hatiolab/things-scene'
 import type { Component } from '@hatiolab/things-scene'
 import { TRANSPORT_SURFACE_HEIGHT } from './machine-3d.js'
 import { Z_FMSIM } from './z-priority'
@@ -46,17 +46,10 @@ export class CraneRail3D extends RealObjectGroup {
     const railW = Math.max(h * 0.06, 2) // 레일 폭
     const supportThick = Math.max(Math.min(w, h) * 0.05, 2)
 
-    const railMat = new THREE.MeshStandardMaterial({
-      color: RAIL_COLOR,
-      roughness: 0.3,
-      metalness: 0.7,
-    })
-
-    const supportMat = new THREE.MeshStandardMaterial({
-      color: SUPPORT_COLOR,
-      roughness: 0.5,
-      metalness: 0.5,
-    })
+    // MaterialBank 공유(정적 색 dedup). 자체 update() 없이 base 생명주기(guarded disposeObject3D)
+    // 상속 → 공유 base dispose 안전.
+    const railMat = MaterialBank.material('crane-rail|rail', { roughness: 0.3, metalness: 0.7 }, RAIL_COLOR)
+    const supportMat = MaterialBank.material('crane-rail|support', { roughness: 0.5, metalness: 0.5 }, SUPPORT_COLOR)
 
     // ── 바닥 레일 (2개 평행 트랙) ──
     const bottomGeometries: THREE.BufferGeometry[] = []
@@ -98,10 +91,13 @@ export class CraneRail3D extends RealObjectGroup {
     const supportMesh = new THREE.Mesh(BufferGeometryUtils.mergeGeometries(supportGeometries), supportMat)
     supportMesh.castShadow = true
     inner.add(supportMesh)
+
+    // mesh 는 super.build() 이후 생성 → 코어 faint 를 명시 적용(편집 흐림이 mesh 에 닿게).
+    this.updateAlpha()
   }
 
   updateDimension() {}
-  updateAlpha() {}
+  // updateAlpha override 제거 — 코어 RealObject.updateAlpha(=applyMaterialOpacity)로 수렴(faint).
 
   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) {

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

@@ -10,7 +10,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 { LEGEND_CAPACITY, resolveCarrierLegend } from '../features/mcs-status-default'
 import { getValueOnRanges } from '../utils/get-value-on-ranges'
@@ -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 ──
@@ -468,22 +480,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 +573,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 +603,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 +629,8 @@ class OHTLineRealObject3D extends RealObjectGroup {
     super.onchange(after, before)
   }
 
+  // updateAlpha override 제거 — 코어 RealObject.updateAlpha(=applyMaterialOpacity)로 수렴(faint).
   updateDimension() {}
-  updateAlpha() {}
 }
 
 registerRealObjectFactory('OHTLine', (component: Component) => new OHTLineRealObject3D(component))

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 ||

package/src/mcs-machine.ts

@@ -84,32 +84,13 @@ export default class MCSMachine extends MCSStatusMixin(ContainerAbstract) {
   }
 
   /**
-   * In 2D, ignore `state.alpha`; preserve everything else.
-   *
-   * things-scene's base prerender (component-drawing.ts:31, 44) does:
-   *   const fade = (alpha || 1) - this._delta.fade
-   *   if (fade) context.globalAlpha = fade
-   *
-   * It *overwrites* `globalAlpha` (not multiplies), so the inherited
-   * parent alpha is also lost — that's a base-layer quirk we match the
-   * recovery for. Then at line 48 it applies editMode+hidden dimming
-   * with a *= 0.5.
-   *
-   * Our recovery:
-   *   1. Capture the inherited `globalAlpha` *before* super runs.
-   *   2. Let super do its work (transforms / shadow / dim flags).
-   *   3. Restore globalAlpha to inherited × editMode-hidden dim factor —
-   *      i.e., what super would have produced if our state.alpha were 1.
-   *
-   * 3D path is unaffected: 3D factories read `state.alpha` directly via
-   * their `updateAlpha()` implementations and continue to honor it (with
-   * per-config opacity fallback).
+   * 2D 에서는 `state.alpha`(3D material 전용)를 무시한다. hidden/모델링 dim 흐림은 **코어(draw)가
+   * 일괄 처리**하므로 여기서 손대지 않는다 (component-drawing.ts draw 가 prerender 직후 faint 적용).
+   * fade 애니메이션은 보존. 3D 는 factory `updateAlpha()` 가 state.alpha 를 별도로 존중.
    */
   prerender(ctx: any) {
-    const inherited = ctx.globalAlpha
     super.prerender(ctx)
-    const dim = this.app.isEditMode && this.hidden ? 0.5 : 1
-    ctx.globalAlpha = inherited * dim
+    ctx.globalAlpha = 1 - this._delta.fade
   }
 
   render(ctx) {

package/src/mcs-unit.ts

@@ -62,14 +62,11 @@ export default class MCSUnit extends MCSStatusMixin(ParentObjectMixin(ContainerA
   }
 
   /**
-   * In 2D, ignore `state.alpha`; preserve inherited alpha + editMode-hidden dim.
-   * See MCSMachine.prerender for the full rationale.
+   * 2D 에서는 state.alpha 무시. hidden/모델링 dim 흐림은 코어(draw)가 일괄 처리 (MCSMachine 동일).
    */
   prerender(ctx: any) {
-    const inherited = ctx.globalAlpha
     super.prerender(ctx)
-    const dim = this.app.isEditMode && this.hidden ? 0.5 : 1
-    ctx.globalAlpha = inherited * dim
+    ctx.globalAlpha = 1 - this._delta.fade
   }
 
   contains(x, y) {

package/src/scene/root-container-override.ts

@@ -217,6 +217,7 @@ Object.defineProperty(ModelLayer.prototype, 'nature', {
           type: 'legend',
           label: '',
           name: 'MOOD',
+          requires3d: true,
           property: {
             label: 'MOOD'
           }
@@ -225,6 +226,7 @@ Object.defineProperty(ModelLayer.prototype, 'nature', {
           type: 'select',
           label: 'light-preset',
           name: 'lightPreset',
+          requires3d: true,
           property: {
             options: ['dark', 'medium', 'bright']
           }