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

package/src/mcs-carrier-holder.ts

@@ -1,7 +1,22 @@
-import { Model, Properties } from '@hatiolab/things-scene'
 import { themesColorMap, themesAnimationMap } from '@fmsim/api'
 import MCSUnit from './mcs-unit.js'
-import Carrier from './carrier.js'
+import { parseIfJsonString } from './utils/data-value'
+
+/**
+ * Holder.data 변경 감지 시 carrierManager 에 전달할 4 키 묶음 + multiCarriers 배열.
+ * 비교 결과 단 하나라도 다르면 carrierManager.update 호출.
+ * (데이터 키는 모두 대문자 전제 — 케이스 정규화 없이 직접 읽는다)
+ */
+const CARRIER_DATA_KEYS = ['CARRIERNAME', 'CARRIERTYPE', 'EMPTYTYPE', 'CARRIERSTATUS'] as const
+
+function multiCarriersChanged(a: any, b: any): boolean {
+  // MULTICARRIERS 값이 JSON 문자열로 올 수 있어 파싱 후 비교. shallow JSON 비교로 충분 —
+  // 각 항목이 4 키 primitive 만 가짐. 빈/누락은 같은 '[]' 직렬화로 동치 취급.
+  return (
+    JSON.stringify(parseIfJsonString(a?.MULTICARRIERS) ?? []) !==
+    JSON.stringify(parseIfJsonString(b?.MULTICARRIERS) ?? [])
+  )
+}
 
 export default class MCSCarrierHolder extends MCSUnit {
   static get properties(): any {
@@ -28,55 +43,63 @@ export default class MCSCarrierHolder extends MCSUnit {
         label: 'show-carrier-text',
         name: 'showCarrierText'
       }
+      // 적층 두께는 carrier 측 (Carrier.added) 에서 자기 default depth 를 결정.
+      // holder 측에는 별도 carrierDepth 속성을 두지 않는다.
     ]
   }
 
-  carrier?: Carrier | null
-
-  async ready() {
-    super.ready()
+  get showOverflow() {
+    return true
+  }
 
-    for (let component of this.components) {
-      this.removeComponent(component)
+  get hierarchy() {
+    return {
+      ...super.hierarchy,
+      components: []
     }
-
-    const { width, height } = this.state
-
-    this.carrier = Model.compile(
-      {
-        type: 'Carrier',
-        left: 0,
-        top: 0,
-        width,
-        height,
-        showText: this.getState('showCarrierText') || false
-      },
-      this.root.app
-    ) as any
-
-    this.addComponent(this.carrier!)
-
-    this.carrier!.data = this.data
   }
 
   dispose(): void {
-    this.carrier = null
-
+    ;(this.root as any)?.carrierManager?.update(this, {}, this.data)
     super.dispose()
   }
 
-  get hierarchy() {
-    return {
-      ...super.hierarchy,
-      components: []
+  async ready() {
+    super.ready()
+
+    if (this._hasCarrierData(this.data)) {
+      ;(this.root as any).carrierManager.update(this, this.data || {}, undefined)
     }
   }
 
   onchangeData(after: Record<string, any>, before: Record<string, any>): void {
-    if (this.carrier) {
-      this.carrier.data = this.data
+    const afterData = after.data || {}
+    const beforeData = before.data || {}
+
+    let changed = false
+    for (const k of CARRIER_DATA_KEYS) {
+      if (afterData[k] !== beforeData[k]) {
+        changed = true
+        break
+      }
+    }
+    if (!changed) {
+      changed = multiCarriersChanged(afterData, beforeData)
+    }
+
+    if (changed) {
+      ;(this.root as any).carrierManager.update(this, afterData, beforeData)
     }
 
     super.onchangeData(after, before)
   }
+
+  /** data 안에 carrier 정보 (대표 또는 multiCarriers) 가 하나라도 있는지. */
+  private _hasCarrierData(data: any): boolean {
+    if (!data) return false
+    if (data.CARRIERNAME) return true
+    const list = parseIfJsonString(data.MULTICARRIERS)
+    if (Array.isArray(list) && list.some((a: any) => a?.CARRIERNAME)) return true
+    return false
+  }
 }

package/src/mcs-machine.ts

@@ -26,6 +26,19 @@ export default class MCSMachine extends MCSStatusMixin(ContainerAbstract) {
     return false
   }
 
+  /**
+   * id 후보를 조회할 때 백엔드에 보낼 타입명. 값이 있으면 검색(lookup) 대상.
+   * 기본은 자기 타입. 자기 타입과 다른 타입으로 조회해야 하는 특수 케이스는 override.
+   */
+  get idLookupType(): string | undefined {
+    return this.state.type
+  }
+
+  /** MCS 머신 — parentObject(부모 머신) 후보 수집 시 머신으로 식별. */
+  get isMcsMachine(): boolean {
+    return true
+  }
+
   containable(component: Component) {
     return ['rect', 'ellipse'].includes(component.state.type)
   }
@@ -70,6 +83,16 @@ export default class MCSMachine extends MCSStatusMixin(ContainerAbstract) {
     return LEGEND_MACHINE
   }
 
+  /**
+   * 2D 에서는 `state.alpha`(3D material 전용)를 무시한다. hidden/모델링 dim 흐림은 **코어(draw)가
+   * 일괄 처리**하므로 여기서 손대지 않는다 (component-drawing.ts draw 가 prerender 직후 faint 적용).
+   * fade 애니메이션은 보존. 3D 는 factory `updateAlpha()` 가 state.alpha 를 별도로 존중.
+   */
+  prerender(ctx: any) {
+    super.prerender(ctx)
+    ctx.globalAlpha = 1 - this._delta.fade
+  }
+
   render(ctx) {
     var { round = 0, lineWidth } = this.state
     var { left, top, width, height } = this.bounds

package/src/mcs-unit.ts

@@ -1,4 +1,4 @@
-import { Component, ContainerAbstract } from '@hatiolab/things-scene'
+import { ContainerAbstract } from '@hatiolab/things-scene'
 import { getPopupData } from '@fmsim/api'
 
 import { MCSStatusMixin, MCSStatusMixinProperties } from './features/mcs-status-mixin'
@@ -13,6 +13,18 @@ export default class MCSUnit extends MCSStatusMixin(ParentObjectMixin(ContainerA
     return [...MCSStatusMixinProperties, ...ParentObjectMixinProperties]
   }
 
+  get showMoveHandle() {
+    return false
+  }
+
+  /**
+   * id 후보를 조회할 때 백엔드에 보낼 타입명. 값이 있으면 검색(lookup) 대상.
+   * 기본은 자기 타입. 특수 케이스는 override.
+   */
+  get idLookupType(): string | undefined {
+    return this.state.type
+  }
+
   get hasTextProperty() {
     return true
   }
@@ -49,6 +61,14 @@ export default class MCSUnit extends MCSStatusMixin(ParentObjectMixin(ContainerA
     return LEGEND_UNIT
   }
 
+  /**
+   * 2D 에서는 state.alpha 무시. hidden/모델링 dim 흐림은 코어(draw)가 일괄 처리 (MCSMachine 동일).
+   */
+  prerender(ctx: any) {
+    super.prerender(ctx)
+    ctx.globalAlpha = 1 - this._delta.fade
+  }
+
   contains(x, y) {
     var { left, top, width, height, lineWidth = 0 } = this.state
     var extend = lineWidth / 2

package/src/mcs-vehicle.ts

@@ -1,4 +1,3 @@
-import { Properties } from '@hatiolab/things-scene'
 import { LEGEND_VEHICLE, Legend } from './features/mcs-status-default'
 import MCSCarrierHolder from './mcs-carrier-holder'
 import Node from './node'
@@ -124,22 +123,26 @@ export default class MCSVehicle extends MCSCarrierHolder {
 
     if ((this.root as any).vehicleAnimation) {
       this.trigger('waypoint', {
-        from: beforeNode,
+        from: beforeNode || afterNode,
         to: afterNode,
         duration: 5000
       })
-    } else {
-      const fromCenter = beforeNode!.center
+    } else if (beforeNode) {
+      const fromCenter = beforeNode.center
       const toCenter = afterNode.center
 
-      const { x: startX, y: startY } = beforeNode!.transcoordS2T(fromCenter.x, fromCenter.y)
+      const { x: startX, y: startY } = beforeNode.transcoordS2T(fromCenter.x, fromCenter.y)
       const { x: endX, y: endY } = afterNode.transcoordS2T(toCenter.x, toCenter.y)
 
       const theta = Math.atan2(endY - startY, endX - startX) + Math.PI / 2
 
-      // 위치 설정
       this.location = { x: endX, y: endY }
       this.setState('rotation', theta)
+    } else {
+      // beforeNode 없음: afterNode 위치로 즉시 이동
+      const toCenter = afterNode.center
+      const { x, y } = afterNode.transcoordS2T(toCenter.x, toCenter.y)
+      this.location = { x, y }
     }
   }
 }

package/src/node.ts

@@ -28,11 +28,17 @@ export default class Node extends Shape {
   static RADIUS = 8
 
   is3dish() {
-    return false
+    return true
   }
 
-  isDescendible() {
-    return false
+  /**
+   * Node 는 기본적으로 컨테이너 드롭 입양 불가 — 라인 머신(AGVLine/OHTLine/CraneRail)만
+   * 자기 containable 화이트리스트로 Node 를 받는다. 단 FloorPlate 에는 들어갈 수 있게 허용.
+   * FloorPlate 는 things-scene 코어 컨테이너라 거기에 'Node' 를 명시할 수 없으므로
+   * Node 측에서 해결한다 (FloorPlate 의 기본 containable = component.isDescendible(this)).
+   */
+  isDescendible(container?: any) {
+    return container?.state?.type === 'floor-plate'
   }
 
   render(context) {

package/src/oht.ts

@@ -1,4 +1,4 @@
-import { Component, ComponentNature, Properties, sceneComponent } from '@hatiolab/things-scene'
+import { Component, ComponentNature, sceneComponent } from '@hatiolab/things-scene'
 import MCSVehicle from './mcs-vehicle'
 
 const NATURE: ComponentNature = {
@@ -20,6 +20,11 @@ export default class OHT extends MCSVehicle {
     return 'black'
   }
 
+  /** OHT 의 parentObject 는 OHTLine. */
+  get parentObjectTypes(): string[] {
+    return ['OHTLine']
+  }
+
   getLegendFallback() {
     return (this.root as any).ohtLegendTheme || super.getLegendFallback()
   }

package/src/port-flow.ts

@@ -45,6 +45,11 @@ export default class PortFlow extends ParentObjectMixin(RectPath(Shape)) {
     return NATURE
   }
 
+  /** PortFlow 의 parentObject 는 Port (유닛). */
+  get parentObjectTypes(): string[] {
+    return ['Port']
+  }
+
   get hasTextProperty() {
     return this.getState('showText') || false
   }

package/src/port.ts

@@ -23,6 +23,11 @@ export default class Port extends MCSZoneMixin(MCSCarrierHolder) {
     return (this.root as any).portLegendTheme || super.getLegendFallback()
   }
 
+  /** Port 는 후보가 매우 많아 부모 머신 없이는 id 리스트를 조회하지 않는다 (machine 필수). */
+  get idLookupRequiresMachine() {
+    return true
+  }
+
   render(ctx: CanvasRenderingContext2D) {
     var { left, top, width, height } = this.bounds
 

package/src/scanner.ts

@@ -0,0 +1,29 @@
+import { Component, ComponentNature, Triangle, sceneComponent } from '@hatiolab/things-scene'
+import { MCSStatusMixin } from './features/mcs-status-mixin'
+
+const NATURE: ComponentNature = {
+  mutable: true,
+  resizable: false,
+  rotatable: true,
+  properties: [
+    {
+      type: 'number',
+      label: 'round',
+      name: 'round',
+      property: { min: 0, max: 100, step: 1 }
+    }
+  ]
+}
+
+@sceneComponent('Scanner')
+export default class Scanner extends MCSStatusMixin(Triangle) {
+  static get nature() {
+    return NATURE
+  }
+
+  is3dish() {
+    return true
+  }
+}
+
+Component.memoize(Scanner.prototype, 'path', false)

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

@@ -1,6 +1,7 @@
 import { Component, RootContainer } from '@hatiolab/things-scene'
 import { themesColorMap, themesColorRange, themesAnimationMap } from '@fmsim/api'
 import { Legend } from '../features/mcs-status-default'
+import CarrierManager from '../carrier-manager'
 
 // RootContainer 클래스 타입 확장
 declare module '@hatiolab/things-scene' {
@@ -24,11 +25,28 @@ declare module '@hatiolab/things-scene' {
     equipmentLegendTheme?: any
     style: any
     vehicleAnimation?: boolean
+    // 스토커 게이지 표시 모드 — 런타임 전용 transient (모델 비저장, 항상 'capacity' 시작)
+    stockerGaugeMode: string
+    _stockerGaugeMode?: string
+    _refreshStockerGauges(): void
     // 캐시 관련 속성 추가
     _animationConfigCache?: Map<string, any>
+    _carrierManager?: CarrierManager
+    carrierManager: CarrierManager
   }
 }
 
+/**
+ * 스토커 적재율 게이지 표시 모드 — 런타임 선택지.
+ * value 는 엔진 canonical(2D StockerCapacityBar / 3D buildGauge 공통), label 은 표시명.
+ * 런타임 UI(뷰어 컨트롤)가 이 목록으로 selector 를 구성한다.
+ */
+export const STOCKER_GAUGE_MODES: { value: string; label: string }[] = [
+  { value: 'capacity', label: 'Capacity' },
+  { value: 'carrier', label: 'Carrier Status' },
+  { value: 'abnormal', label: 'Abnormal Carrier' }
+]
+
 const ModelLayer = (Component as any).register('model-layer') as any
 
 Object.defineProperty(ModelLayer.prototype, 'nature', {
@@ -194,6 +212,22 @@ Object.defineProperty(ModelLayer.prototype, 'nature', {
           property: {
             options: themesColorRange
           }
+        },
+        {
+          type: 'legend',
+          label: '',
+          name: 'MOOD',
+          property: {
+            label: 'MOOD'
+          }
+        },
+        {
+          type: 'select',
+          label: 'light-preset',
+          name: 'lightPreset',
+          property: {
+            options: ['dark', 'medium', 'bright']
+          }
         }
       ],
       'value-property': 'text'
@@ -201,128 +235,145 @@ Object.defineProperty(ModelLayer.prototype, 'nature', {
   }
 })
 
-Object.defineProperty(RootContainer.prototype, 'equipmentLegendTheme', {
-  get: function () {
-    const { equipmentLegendName } = this.rootModel.state
-    return equipmentLegendName && this.state.style[equipmentLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'bufferLegendTheme', {
-  get: function () {
-    const { bufferLegendName } = this.rootModel.state
-    return bufferLegendName && this.state.style[bufferLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'agvlineLegendTheme', {
-  get: function () {
-    const { agvlineLegendName } = this.rootModel.state
-    return agvlineLegendName && this.state.style[agvlineLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'ohtlineLegendTheme', {
-  get: function () {
-    const { ohtlineLegendName } = this.rootModel.state
-    return ohtlineLegendName && this.state.style[ohtlineLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'conveyorLegendTheme', {
-  get: function () {
-    const { conveyorLegendName } = this.rootModel.state
-    return conveyorLegendName && this.state.style[conveyorLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'stokerLegendTheme', {
-  get: function () {
-    const { stokerLegendName } = this.rootModel.state
-    return stokerLegendName && this.state.style[stokerLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'agvLegendTheme', {
-  get: function () {
-    const { agvLegendName } = this.rootModel.state
-    return agvLegendName && this.state.style[agvLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'ohtLegendTheme', {
-  get: function () {
-    const { ohtLegendName } = this.rootModel.state
-    return ohtLegendName && this.state.style[ohtLegendName]
-  }
-})
-
-Object.defineProperty(RootContainer.prototype, 'shuttleLegendTheme', {
-  get: function () {
-    const { shuttleLegendName } = this.rootModel.state
-    return shuttleLegendName && this.state.style[shuttleLegendName]
-  }
-})
+/**
+ * 조명 프리셋 — 3 단계 밝기 토글.
+ *
+ * fmsim 은 디테일 조명 옵션 UI 를 노출하지 않으므로 단일 select 로 단순화.
+ * medium = things-scene 의 현재 default 값과 동일 (외관 변화 없음).
+ * 사용자가 select 변경 시 onchange 가 exposure + hemiIntensity + dirLightIntensity
+ * 를 일괄 set → three-capability 의 변경 감지 핸들러가 즉시 갱신.
+ */
+const LIGHT_PRESETS: Record<string, { exposure: number; hemiIntensity: number; dirLightIntensity: number }> = {
+  dark: { exposure: 1.2, hemiIntensity: 4.0, dirLightIntensity: 0.6 },
+  medium: { exposure: 1.2, hemiIntensity: 4.0, dirLightIntensity: 2.0 },
+  bright: { exposure: 1.2, hemiIntensity: 4.0, dirLightIntensity: 5.0 }
+}
 
-Object.defineProperty(RootContainer.prototype, 'craneLegendTheme', {
-  get: function () {
-    const { craneLegendName } = this.rootModel.state
-    return craneLegendName && this.state.style[craneLegendName]
+const _origModelLayerOnchange = ModelLayer.prototype.onchange
+ModelLayer.prototype.onchange = function (after: any) {
+  if (after && Object.prototype.hasOwnProperty.call(after, 'lightPreset')) {
+    const preset = LIGHT_PRESETS[after.lightPreset as string]
+    if (preset) {
+      this.set({
+        exposure: preset.exposure,
+        hemiIntensity: preset.hemiIntensity,
+        dirLightIntensity: preset.dirLightIntensity
+      })
+    }
   }
-})
+  return _origModelLayerOnchange.call(this, after)
+}
 
-Object.defineProperty(RootContainer.prototype, 'shelfLegendTheme', {
-  get: function () {
-    const { shelfLegendName } = this.rootModel.state
-    return shelfLegendName && this.state.style[shelfLegendName]
-  }
-})
+// === LegendTheme / AnimationTheme value resolve ===
+//
+// rootModel.state.style[name] 에 저장된 legend/animation 값은 보드 직렬화
+// 형태에 따라 (a) 정상 object 또는 (b) JSON 문자열 둘 다로 나타난다 (2026-06-09
+// 진단 — consumer 인 carrier.ts:animationPreset 이 같은 이유로 typeof string
+// 분기 + JSON5.parse 처리하는 선례 존재). LegendTheme getter 들이 이 분기를
+// 두지 않아 string 통과 → getValueOnRanges 매칭 실패 → 3D gauge 의 색상이
+// fallback 으로만 결정되던 증상.
+//
+// fix 는 getter 한 곳에서 lazy parse. WeakMap<state, Map<rawString, parsed>>
+// 으로 *raw string 자체를 key* — 보드 편집으로 raw 가 바뀌면 자연 무효화,
+// 같은 raw 의 반복 lookup 은 O(1). root 가 GC 되면 cache 도 같이 GC.
+const _legendParseCache = new WeakMap<object, Map<string, any>>()
 
-Object.defineProperty(RootContainer.prototype, 'portLegendTheme', {
-  get: function () {
-    const { portLegendName } = this.rootModel.state
-    return portLegendName && this.state.style[portLegendName]
+function parseLegendIfString(state: any, raw: any): any {
+  if (typeof raw !== 'string') return raw
+  let cache = _legendParseCache.get(state)
+  if (!cache) {
+    cache = new Map()
+    _legendParseCache.set(state, cache)
   }
-})
+  if (cache.has(raw)) return cache.get(raw)
+  let parsed: any
+  try { parsed = JSON.parse(raw) } catch { parsed = raw } // parse 실패 시 raw 보존
+  cache.set(raw, parsed)
+  return parsed
+}
 
-Object.defineProperty(RootContainer.prototype, 'carrierLegendTheme', {
-  get: function () {
-    const { carrierLegendName } = this.rootModel.state
-    return carrierLegendName && this.state.style[carrierLegendName]
+function legendThemeGetter(stateKey: string) {
+  return function (this: any) {
+    const name = this.rootModel.state[stateKey]
+    const raw = name && this.state.style[name]
+    return parseLegendIfString(this.state, raw)
   }
-})
+}
 
-Object.defineProperty(RootContainer.prototype, 'carrierAnimationTheme', {
-  get: function () {
-    const { carrierAnimationName } = this.rootModel.state
-    return carrierAnimationName && this.state.style[carrierAnimationName]
-  }
-})
+Object.defineProperty(RootContainer.prototype, 'equipmentLegendTheme', { get: legendThemeGetter('equipmentLegendName') })
+Object.defineProperty(RootContainer.prototype, 'bufferLegendTheme', { get: legendThemeGetter('bufferLegendName') })
+Object.defineProperty(RootContainer.prototype, 'agvlineLegendTheme', { get: legendThemeGetter('agvlineLegendName') })
+Object.defineProperty(RootContainer.prototype, 'ohtlineLegendTheme', { get: legendThemeGetter('ohtlineLegendName') })
+Object.defineProperty(RootContainer.prototype, 'conveyorLegendTheme', { get: legendThemeGetter('conveyorLegendName') })
+Object.defineProperty(RootContainer.prototype, 'stokerLegendTheme', { get: legendThemeGetter('stokerLegendName') })
+Object.defineProperty(RootContainer.prototype, 'agvLegendTheme', { get: legendThemeGetter('agvLegendName') })
+Object.defineProperty(RootContainer.prototype, 'ohtLegendTheme', { get: legendThemeGetter('ohtLegendName') })
+Object.defineProperty(RootContainer.prototype, 'shuttleLegendTheme', { get: legendThemeGetter('shuttleLegendName') })
+Object.defineProperty(RootContainer.prototype, 'craneLegendTheme', { get: legendThemeGetter('craneLegendName') })
+Object.defineProperty(RootContainer.prototype, 'shelfLegendTheme', { get: legendThemeGetter('shelfLegendName') })
+Object.defineProperty(RootContainer.prototype, 'portLegendTheme', { get: legendThemeGetter('portLegendName') })
+Object.defineProperty(RootContainer.prototype, 'carrierLegendTheme', { get: legendThemeGetter('carrierLegendName') })
+Object.defineProperty(RootContainer.prototype, 'carrierAnimationTheme', { get: legendThemeGetter('carrierAnimationName') })
+Object.defineProperty(RootContainer.prototype, 'stockerCapacityLegendTheme', { get: legendThemeGetter('stockerCapacityLegendName') })
+Object.defineProperty(RootContainer.prototype, 'zoneCapacityLegendTheme', { get: legendThemeGetter('zoneCapacityLegendName') })
+Object.defineProperty(RootContainer.prototype, 'batteryRateLegendTheme', { get: legendThemeGetter('batteryRateLegendName') })
 
-Object.defineProperty(RootContainer.prototype, 'stockerCapacityLegendTheme', {
+Object.defineProperty(RootContainer.prototype, 'vehicleAnimation', {
   get: function () {
-    const { stockerCapacityLegendName } = this.rootModel.state
-    return stockerCapacityLegendName && this.state.style[stockerCapacityLegendName]
+    const { vehicleAnimation } = this.rootModel.state
+    return !!vehicleAnimation
   }
 })
 
-Object.defineProperty(RootContainer.prototype, 'zoneCapacityLegendTheme', {
+Object.defineProperty(RootContainer.prototype, 'carrierManager', {
   get: function () {
-    const { zoneCapacityLegendName } = this.rootModel.state
-    return zoneCapacityLegendName && this.state.style[zoneCapacityLegendName]
+    if (!this._carrierManager) {
+      this._carrierManager = new CarrierManager(this)
+    }
+    return this._carrierManager
   }
 })
 
-Object.defineProperty(RootContainer.prototype, 'batteryRateLegendTheme', {
+// === 스토커 게이지 표시 모드 (런타임 전용 transient) ===
+//
+// 모델(state)에 저장하지 않는다 — nature 속성이 아니므로 보드 직렬화에 포함되지 않고,
+// 보드를 다시 열면 항상 기본값 'capacity' 로 시작한다. 실행 중 뷰어 컨트롤 등이
+// `scene.rootContainer.stockerGaugeMode = 'carrier'` 로 동적 변경한다.
+// (주의: scene.root 은 model_layer 라 override 가 없다. 반드시 rootContainer 에 설정.
+//  컴포넌트의 this.root 는 RootContainer(isRoot)로 해석되어 이 값을 읽는다.)
+//
+// 2D(StockerCapacityBar.gaugeMode) 와 3D(machine-3d buildGauge) 가 모두 이 값을 읽어
+// 게이지 표현이 항상 일치한다. 값이 바뀌면 setter 가 2D 리드로우 + 3D 게이지 재빌드를
+// 즉시 트리거한다.
+Object.defineProperty(RootContainer.prototype, 'stockerGaugeMode', {
   get: function () {
-    const { batteryRateLegendName } = this.rootModel.state
-    return batteryRateLegendName && this.state.style[batteryRateLegendName]
+    return this._stockerGaugeMode || 'capacity'
+  },
+  set: function (mode: string) {
+    const next = mode || 'capacity'
+    if (this._stockerGaugeMode === next) return
+    this._stockerGaugeMode = next
+    this._refreshStockerGauges()
   }
 })
 
-Object.defineProperty(RootContainer.prototype, 'vehicleAnimation', {
-  get: function () {
-    const { vehicleAnimation } = this.rootModel.state
-    return !!vehicleAnimation
+/** scene 하위 STOCKER(3D 게이지) + StockerCapacityBar(2D 게이지) 를 새 모드로 갱신. */
+RootContainer.prototype._refreshStockerGauges = function () {
+  const walk = (container: any) => {
+    const kids = container?.components
+    if (!Array.isArray(kids)) return
+    for (const c of kids) {
+      const type = c?.state?.type
+      if (type === 'STOCKER') {
+        // 3D 게이지는 스토커 자신의 real-object 가 그린다 → 재빌드 (2D 모드면 _realObject 없음)
+        c._realObject?.update?.()
+      } else if (type === 'StockerCapacityBar' || type === 'MCSGaugeCapacityBar') {
+        // 2D 게이지는 자식 컴포넌트가 그린다 → 리드로우
+        c.invalidate?.()
+      }
+      walk(c)
+    }
   }
-})
+  walk(this)
+  this.invalidate?.()
+}

package/src/shelf.ts

@@ -19,6 +19,11 @@ export default class Shelf extends MCSZoneMixin(MCSCarrierHolder) {
     return 'black'
   }
 
+  /** Shelf 의 parentObject 는 STOCKER. */
+  get parentObjectTypes(): string[] {
+    return ['STOCKER']
+  }
+
   getLegendFallback() {
     return (this.root as any).shelfLegendTheme || super.getLegendFallback()
   }

package/src/static-container.ts

@@ -13,6 +13,11 @@ const NATURE = {
 
 @sceneComponent('container')
 export default class StaticContainer extends Container {
+  // things-scene 의 `declare const Container_base` 패턴이 base 인스턴스 타입의 accessor
+  // 정보를 object-type property 로 평탄화하여 TS2611 발생. operato-scene 은 position
+  // override 케이스가 없어 미발현, fmsim 만 해당. things-scene 측 mixin 타입 패턴이
+  // 개선되면 제거.
+  // @ts-expect-error TS2611
   get position() {
     return 'static'
   }