@hatiolab/things-scene 10.0.5 → 10.1.0

package/dist-types/threed/instanced-set.d.ts

@@ -0,0 +1,211 @@
+import * as THREE from 'three';
+/**
+ * 같은 형상을 여러 자리에 그리는 묶음 — `THREE.InstancedMesh` 를 감싼다.
+ *
+ * ## 어디에 쓰나
+ *
+ * **한 컴포넌트가 같은 것을 여러 번 그리는 자리.** 스토커의 선반 칸과 기둥, 컨베이어의
+ * 롤러, 랙의 단. 이런 것들은 애초에 개별 컴포넌트가 아니라 **한 컴포넌트가 그리는 반복
+ * 구조**라서, 소유자가 분명하고 things-scene 의 「컴포넌트 하나 = RealObject 하나」를
+ * 깨지 않는다.
+ *
+ * figure-model 의 `sizing: 'repeat'` — 「개수가 늘어난다. 새 geometry 가 생기지 않는다」
+ * — 가 가리키는 런타임이 이것이다.
+ *
+ * ## 무엇을 얻고 무엇을 잃나
+ *
+ * 얻는 것 — draw call 이 개수와 무관하게 **하나**가 되고, Object3D 가 하나뿐이라 프레임
+ * 마다 도는 씬 그래프 순회도 하나로 준다.
+ *
+ * 잃는 것 — **컬링이 묶음 단위다.** 인스턴스 하나하나를 잘라내지 못하므로 화면 밖까지
+ * 정점 처리를 태운다. 그리고 색 말고 다른 재질 속성은 인스턴스별로 줄 수 없다.
+ *
+ * ## 흩어져 있으면 손해인가 — 실기에서 재보니 아니었다
+ *
+ * 롤러 5000개를 넓게 흩어 놓고(상당수 화면 밖) 견준 값. `test/browser/check-spinning.mjs`
+ *
+ *   실기 GPU (Apple M5)      그리기      프레임   draw call   삼각형
+ *     낱개                   3.95ms    18.5ms       3122    99904
+ *     묶음                   0.61ms    16.7ms          1   160000
+ *
+ *   소프트웨어 (swiftshader)
+ *     낱개                   1.57ms    32.3ms       3122    99904
+ *     묶음                   0.14ms    43.8ms          1   160000
+ *
+ * **같은 장면인데 결론이 반대다.** 소프트웨어에서는 삼각형을 60% 더 그리는 것이 곧 CPU
+ * 시간이라 묶음이 졌다. 실기 GPU 에서 16만 삼각형은 거의 공짜이고, 3122 번의 draw call
+ * 제출이 3.95ms 를 먹는다.
+ *
+ * 그래서 「뭉쳐 있어야 한다」는 조건은 실기에서는 성립하지 않는다. 컬링을 잃는 대신
+ * draw call 을 얻는 거래이고, 실기에서는 그 거래가 남는다.
+ *
+ * ## 무엇이 실제로 비싼가
+ *
+ * 프레임마다 **전부** 다시 쓰면 그 비용이 개수에 비례한다. 2만 개에서는 낱개보다
+ * 커진다(갱신 2.2ms 대 0.9ms) — 그래도 그리기 절감(5.6ms → 0.33ms)이 그것을 덮는다.
+ *
+ * 움직이는 것만 고치면(`setRotation` + `commitMatrices`) 갱신이 20~85배 싸다.
+ * 행렬 버퍼는 통째로 올라가지만 그 비용은 작다(2만 개에서 0.33ms).
+ *
+ * ## 안정된 참조
+ *
+ *
+ * `object3d` 는 `THREE.Group` 이고 그 안에 `InstancedMesh` 가 하나 있다. 개수가 용량을
+ * 넘으면 안쪽 mesh 를 다시 만드는데, 바깥 Group 이 그대로라 소유자가 붙여 둔 참조가
+ * 끊기지 않는다.
+ */
+export interface InstancedPlacement {
+    /** 묶음 로컬 좌표(three 축: x 오른쪽 · y 위 · z 앞). */
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    /** 크기. 수 하나면 세 축 모두. 없으면 1. */
+    scale?: number | {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /** 축별 회전(라디안). 없으면 0. */
+    rotation?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    };
+    /**
+     * 이 인스턴스의 색. 없으면 재질의 색 그대로.
+     *
+     * **인스턴스별로 줄 수 있는 것은 색뿐이다** — metalness·roughness·투명도는 재질에
+     * 있고 묶음 전체가 나눠 쓴다. 상태를 색으로 표현하는 것은 되고, 상태에 따라 재질을
+     * 바꾸는 것은 안 된다.
+     */
+    color?: string | number;
+}
+export interface InstancedSetOptions {
+    geometry: THREE.BufferGeometry;
+    material: THREE.Material;
+    /** 처음 잡아 둘 자리 수. 넘으면 다시 만든다. 기본 16 */
+    capacity?: number;
+    name?: string;
+    castShadow?: boolean;
+    receiveShadow?: boolean;
+}
+export declare class InstancedSet {
+    /** 소유자가 붙여 두는 안정된 노드. 안쪽 mesh 가 바뀌어도 이것은 그대로다. */
+    readonly object3d: THREE.Group;
+    private _mesh;
+    private _geometry;
+    private _material;
+    private _capacity;
+    private _count;
+    /**
+     * 놓은 배치를 들고 있는다.
+     *
+     * 회전만 바꿀 때 자리와 크기를 알아야 행렬을 다시 쓸 수 있다. 행렬에서 되읽어
+     * 분해할 수도 있지만, 프레임마다 도는 자리(롤러)에서는 그 분해가 그대로 비용이 된다.
+     */
+    private _placements;
+    private _name;
+    private _castShadow;
+    private _receiveShadow;
+    /** 행렬을 만들 때 쓰는 임시값 — 인스턴스마다 새로 만들지 않는다. */
+    private static readonly _m;
+    private static readonly _p;
+    private static readonly _q;
+    private static readonly _e;
+    private static readonly _s;
+    private static readonly _c;
+    constructor(options: InstancedSetOptions);
+    private _makeMesh;
+    /** 안쪽 mesh. 레이캐스트 대상으로 쓴다. */
+    get mesh(): THREE.InstancedMesh;
+    /** 지금 그려지는 개수. */
+    get count(): number;
+    /** 잡아 둔 자리 수. 개수가 이것을 넘으면 mesh 를 다시 만든다. */
+    get capacity(): number;
+    /**
+     * 배치를 통째로 갈아 끼운다.
+     *
+     * 용량이 모자라면 안쪽 mesh 를 다시 만든다 — geometry 와 material 은 그대로 나눠
+     * 쓰므로 다시 만드는 비용은 행렬 버퍼뿐이다.
+     */
+    place(placements: readonly InstancedPlacement[]): void;
+    /** 인스턴스 하나의 자리·크기·회전·색을 고친다. 범위를 벗어나면 아무것도 하지 않는다. */
+    update(index: number, placement: InstancedPlacement): void;
+    /**
+     * 회전만 바꾼다 — 자리와 크기는 그대로다.
+     *
+     * 프레임마다 도는 것(컨베이어 롤러, 회전 설비)을 위한 자리다. 여러 개를 고친 뒤
+     * `commitMatrices()` 를 **한 번** 부른다.
+     *
+     * **경계구를 다시 재지 않는다.** 제 축으로 도는 것은 인스턴스의 반지름을 바꾸지
+     * 않으므로 다시 잴 이유가 없고, 매 프레임 다시 재면 인스턴스를 전부 훑어 그것이
+     * 회전 비용의 대부분이 된다.
+     */
+    setRotation(index: number, rotation: {
+        x?: number;
+        y?: number;
+        z?: number;
+    }): void;
+    /**
+     * 고친 행렬을 GPU 로 올린다. **경계구는 건드리지 않는다.**
+     *
+     * `setRotation` 처럼 자리·크기를 바꾸지 않은 변경에 쓴다. 자리가 바뀌었으면
+     * `commit()` 을 써야 컬링이 어긋나지 않는다.
+     */
+    commitMatrices(): void;
+    /**
+     * 색만 고친다 — 상태 표현이 가장 자주 바뀌는 자리다.
+     *
+     * 행렬은 건드리지 않으므로 자리를 다시 계산하지 않는다.
+     */
+    setColor(index: number, color: string | number): void;
+    /**
+     * 레이캐스트가 준 `instanceId` 를 논리 색인으로 옮긴다.
+     *
+     * 지금은 같은 수지만 계약으로 둔다 — 나중에 빈 칸을 건너뛰며 채우게 되면 둘이
+     * 갈린다. 부르는 쪽이 `instanceId` 를 그대로 쓰면 그때 조용히 어긋난다.
+     */
+    indexOf(instanceId: number): number;
+    /**
+     * 바뀐 것을 GPU 로 올린다.
+     *
+     * 경계구를 다시 잰다 — `InstancedMesh` 의 그것은 인스턴스 행렬까지 보므로, 이걸
+     * 빠뜨리면 묶음이 화면 안에 있는데도 잘려 사라진다.
+     */
+    commit(): void;
+    /**
+     * 행렬 버퍼를 해제한다.
+     *
+     * **geometry 와 material 은 해제하지 않는다** — 창고(GeometryBank·MaterialBank)가
+     * 여러 곳과 나눠 쓰는 것이라 여기서 지우면 남은 쪽이 함께 죽는다.
+     */
+    dispose(): void;
+    private _writeMatrix;
+    private _writeColor;
+}
+/**
+ * 격자로 자리를 만든다 — 선반 칸·기둥처럼 규칙적으로 늘어선 것.
+ *
+ * 개수만 바뀌고 형상은 그대로인 구조가 이 모양이다. `sizing: 'repeat'` 이 뜻하는 것도
+ * 이것이다.
+ *
+ * @param counts 축별 개수. 0 이면 그 축은 한 줄로 친다
+ * @param pitch 축별 간격
+ * @param origin 첫 자리. 없으면 원점
+ */
+export declare function gridPlacements(counts: {
+    x?: number;
+    y?: number;
+    z?: number;
+}, pitch: {
+    x?: number;
+    y?: number;
+    z?: number;
+}, origin?: {
+    x?: number;
+    y?: number;
+    z?: number;
+}): InstancedPlacement[];
+//# sourceMappingURL=instanced-set.d.ts.map

package/dist-types/threed/instanced-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instanced-set.d.ts","sourceRoot":"","sources":["../../src/threed/instanced-set.ts"],"names":[],"mappings":"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"}

package/dist-types/threed/managers/event-manager3d.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-manager3d.d.ts","sourceRoot":"","sources":["../../../src/threed/managers/event-manager3d.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,UAAU,CAAwB;IAC1C,OAAO,CAAC,YAAY,CAAC,CAAkB;IACvC,OAAO,CAAC,YAAY,CAAC,CAAkB;;IAIvC,IAAI,KAAK,kBAER;IAED,IAAI,WAAW,IAIQ,gBAAgB,GAAG,SAAS,CAFlD;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,EAElD;IAED,IAAI,WAAW,IAIQ,gBAAgB,GAAG,SAAS,CAFlD;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,EAElD;IAED,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK/F,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,QAAQ,GAAG,SAAS;IA0BxF;;;OAGG;IACH,OAAO,CAAC,eAAe;IASvB,mBAAmB,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,YAAY,EAAE;IAMnF,OAAO,CAAC,SAAS,CAAC,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAC,CAAc;IAEjC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM;IAK/C,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,GAAG,gBAAgB,GAAG,SAAS;IA0BtG,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU;IAyBvE;;;;OAIG;IACH,sBAAsB,IAAI,IAAI;IAQ9B,OAAO;CAMR"}
+{"version":3,"file":"event-manager3d.d.ts","sourceRoot":"","sources":["../../../src/threed/managers/event-manager3d.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAExD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,UAAU,CAAwB;IAC1C,OAAO,CAAC,YAAY,CAAC,CAAkB;IACvC,OAAO,CAAC,YAAY,CAAC,CAAkB;;IAIvC,IAAI,KAAK,kBAER;IAED,IAAI,WAAW,IAIQ,gBAAgB,GAAG,SAAS,CAFlD;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,EAElD;IAED,IAAI,WAAW,IAIQ,gBAAgB,GAAG,SAAS,CAFlD;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,SAAS,EAElD;IAED,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAK/F,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,QAAQ,GAAG,SAAS;IAkCxF;;;OAGG;IACH,OAAO,CAAC,eAAe;IASvB,mBAAmB,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,YAAY,EAAE;IAMnF,OAAO,CAAC,SAAS,CAAC,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAC,CAAc;IAEjC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM;IAK/C,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,GAAG,gBAAgB,GAAG,SAAS;IA0BtG,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU;IAyBvE;;;;OAIG;IACH,sBAAsB,IAAI,IAAI;IAQ9B,OAAO;CAMR"}

package/dist-types/threed/managers/renderer-manager.d.ts

@@ -21,12 +21,12 @@ export declare class RendererManager {
      */
     setExposure(value: number): void;
     get css3DRenderer(): CSS3DRenderer;
-    get css3DScene(): THREE.Scene;
+    get css3DScene(): THREE.Scene<THREE.Object3DEventMap>;
     get composer(): EffectComposer | undefined;
     get noSupportWebgl(): boolean;
     get domElement(): HTMLCanvasElement | undefined;
-    get hudScene(): THREE.Scene;
-    get hudCSS3DScene(): THREE.Scene;
+    get hudScene(): THREE.Scene<THREE.Object3DEventMap>;
+    get hudCSS3DScene(): THREE.Scene<THREE.Object3DEventMap>;
     get hudCamera(): THREE.OrthographicCamera | undefined;
     /**
      * HUD 직교 카메라를 초기화한다.

package/dist-types/threed/managers/renderer-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderer-manager.d.ts","sourceRoot":"","sources":["../../../src/threed/managers/renderer-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,qDAAqD,CAAA;AAKpF,OAAO,EAAE,aAAa,EAAE,MAAM,+CAA+C,CAAA;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C,qBAAa,eAAe;IAC1B,OAAO,CAAC,SAAS,CAAC,CAAqB;IACvC,OAAO,CAAC,cAAc,CAAC,CAAe;IACtC,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,SAAS,CAAC,CAAgB;IAClC,OAAO,CAAC,YAAY,CAAC,CAAa;IAClC,OAAO,CAAC,eAAe,CAAQ;IAG/B,OAAO,CAAC,SAAS,CAAC,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAC,CAA0B;IAE7C,OAAO,CAAC,iBAAiB,CAAC,CAAe;IACzC,OAAO,CAAC,cAAc,CAAC,CAAa;IACpC,OAAO,CAAC,eAAe,CAAC,CAA0B;IAElD,IAAI,QAAQ,oCAEX;IAED;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMhC,IAAI,aAAa,kBAKhB;IAED,IAAI,UAAU,gBAKb;IAED,IAAI,QAAQ,+BAEX;IAED,IAAI,cAAc,YAEjB;IAED,IAAI,UAAU,kCAEb;IAED,IAAI,QAAQ,gBAKX;IAED,IAAI,aAAa,gBAKhB;IAED,IAAI,SAAS,yCAEZ;IAED;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IA4CtC;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAQvC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO;IAmD1E,UAAU,CAAC,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM;IAmBlD,OAAO,CAAC,mBAAmB;IAI3B,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,KAAK,CAAC,QAAQ;IA4CnH,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAsB1F,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,sBAAsB,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM;IAa3C;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE;IAM3C;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM;IAO7B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAkBpC,OAAO,CAAC,MAAM,CAAC,CAAa;IAC5B,OAAO,CAAC,OAAO,CAAC,CAAc;IAE9B;;OAEG;IACH,qBAAqB;IAQrB;;OAEG;IACH,sBAAsB,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM;IAK/D,MAAM;IAsBN,OAAO,CAAC,SAAS;IAcjB,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM;IAchC,IAAI,gBAAgB,8BAEnB;IAED,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAM5C,OAAO;IAYP,UAAU;IAkCV,iBAAiB;CAMlB"}
+{"version":3,"file":"renderer-manager.d.ts","sourceRoot":"","sources":["../../../src/threed/managers/renderer-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,qDAAqD,CAAA;AAKpF,OAAO,EAAE,aAAa,EAAE,MAAM,+CAA+C,CAAA;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3C,qBAAa,eAAe;IAC1B,OAAO,CAAC,SAAS,CAAC,CAAqB;IACvC,OAAO,CAAC,cAAc,CAAC,CAAe;IACtC,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,SAAS,CAAC,CAAgB;IAClC,OAAO,CAAC,YAAY,CAAC,CAAa;IAClC,OAAO,CAAC,eAAe,CAAQ;IAG/B,OAAO,CAAC,SAAS,CAAC,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAC,CAA0B;IAE7C,OAAO,CAAC,iBAAiB,CAAC,CAAe;IACzC,OAAO,CAAC,cAAc,CAAC,CAAa;IACpC,OAAO,CAAC,eAAe,CAAC,CAA0B;IAElD,IAAI,QAAQ,oCAEX;IAED;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMhC,IAAI,aAAa,kBAKhB;IAED,IAAI,UAAU,wCAKb;IAED,IAAI,QAAQ,+BAEX;IAED,IAAI,cAAc,YAEjB;IAED,IAAI,UAAU,kCAEb;IAED,IAAI,QAAQ,wCAKX;IAED,IAAI,aAAa,wCAKhB;IAED,IAAI,SAAS,yCAEZ;IAED;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IA4CtC;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAQvC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO;IAmD1E,UAAU,CAAC,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM;IAmBlD,OAAO,CAAC,mBAAmB;IAI3B,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,KAAK,CAAC,QAAQ;IA4CnH,kBAAkB,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAsB1F,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,sBAAsB,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM;IAa3C;;OAEG;IACH,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,EAAE;IAM3C;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM;IAO7B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAkBpC,OAAO,CAAC,MAAM,CAAC,CAAa;IAC5B,OAAO,CAAC,OAAO,CAAC,CAAc;IAE9B;;OAEG;IACH,qBAAqB;IAQrB;;OAEG;IACH,sBAAsB,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM;IAK/D,MAAM;IAsBN,OAAO,CAAC,SAAS;IAcjB,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM;IAchC,IAAI,gBAAgB,8BAEnB;IAED,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAM5C,OAAO;IAYP,UAAU;IAkCV,iBAAiB;CAMlB"}

package/dist-types/threed/managers/scene-manager.d.ts

@@ -10,27 +10,51 @@ export declare class SceneManager {
     private _scene?;
     private _mixer?;
     private _timer?;
+    /** IBL(scene.environment)용 텍스처. */
     private _envTexture?;
+    /** 배경(scene.background)용 텍스처. IBL 과 다른 프리셋일 때만 따로 만든다. */
+    private _bgTexture?;
     private _renderer?;
-    get scene(): THREE.Scene | undefined;
-    get mixer(): THREE.AnimationMixer | undefined;
-    setup(): THREE.Scene;
-    setupMixer(): THREE.AnimationMixer;
+    get scene(): THREE.Scene<THREE.Object3DEventMap> | undefined;
+    get mixer(): THREE.AnimationMixer<THREE.AnimationMixerEventMap> | undefined;
+    setup(): THREE.Scene<THREE.Object3DEventMap>;
+    setupMixer(): THREE.AnimationMixer<THREE.AnimationMixerEventMap>;
     setupEnvironment(renderer: THREE.WebGLRenderer): void;
+    /** 프리셋 하나로 PMREM 텍스처를 만든다. 호출자가 dispose 를 책임진다. */
+    private _makeEnvTexture;
     /**
-     * 환경맵 프리셋을 적용한다.
+     * 환경맵 프리셋을 IBL 로 적용한다.
      */
     private _applyEnvironment;
     /**
      * 환경맵을 해제한다. (IBL 기여 제거)
      */
     private _clearEnvironment;
+    /** 배경용 텍스처를 해제한다. */
+    private _clearBackgroundTexture;
+    /** 지금 IBL 이 걸려 있나 — 진단이 쓴다. metalness 가 높은 재질은 이것이 없으면 검다. */
+    get hasEnvironment(): boolean;
     /**
-     * 3D 씬 배경(sky)을 설정한다. environment(IBL)도 함께 관리한다.
-     * @param sky - 프리셋 이름 (studio/warehouse/factory/office/home | sunny/cloudy/rainy) | 'color' | '' (none)
-     * @param skyColor - sky='color'일 때 사용할 색상
+     * 3D 씬 배경(sky)과 반사·조명(environment, IBL)을 설정한다.
+     *
+     * ## 둘은 따로다
+     *
+     * three.js 의 `scene.background` 와 `scene.environment` 는 별개다. 전에는 이 둘이
+     * 붙어 있어서 **배경 없이 반사만** 두는 것이 불가능했다. 그래서 `sky` 를 정하지 않은
+     * 보드에서 `metalness` 가 높은 재질(예: `material3d.preset = 'metal'`)이 **반사할
+     * 것이 없어 검게** 나왔다. 저작자는 자기가 고른 색이 안 나온 것으로 본다.
+     *
+     * PBR 에서 완전한 금속은 확산 성분이 없다 — 보이는 것이 전부 반사다. 그래서 이것은
+     * 프리셋 값이 틀린 것이 아니라 **반사할 환경을 줄 방법이 없던 것**이 문제였다.
+     *
+     * @param sky 배경. 프리셋 이름 | `'color'` | `''`(없음)
+     * @param skyColor `sky === 'color'` 일 때의 색
+     * @param environment IBL 을 배경과 따로 정한다.
+     *   - 주지 않으면 **`sky` 를 따른다** — 이전과 완전히 같게 동작한다
+     *   - 프리셋 이름이면 배경과 무관하게 그 반사를 쓴다 (배경 없이 반사만 가능)
+     *   - `'none'` 이면 `sky` 가 프리셋이어도 IBL 을 끈다
      */
-    setSky(sky?: string, skyColor?: string): void;
+    setSky(sky?: string, skyColor?: string, environment?: string): void;
     addFloor(component: Component): void;
     /**
      * 기존 floor를 제거하고 새로 생성하여 교체한다.

package/dist-types/threed/managers/scene-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-manager.d.ts","sourceRoot":"","sources":["../../../src/threed/managers/scene-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AA2B1D;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAItE;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,CAAa;IAC5B,OAAO,CAAC,MAAM,CAAC,CAAsB;IACrC,OAAO,CAAC,MAAM,CAAC,CAAa;IAC5B,OAAO,CAAC,WAAW,CAAC,CAAe;IACnC,OAAO,CAAC,SAAS,CAAC,CAAqB;IAEvC,IAAI,KAAK,4BAER;IAED,IAAI,KAAK,qCAER;IAED,KAAK;IAKL,UAAU;IAOV,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,aAAa;IAO9C;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;;;OAIG;IACH,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;IAmBtC,QAAQ,CAAC,SAAS,EAAE,SAAS;IAO7B;;;OAGG;IACH,WAAW,CAAC,SAAS,EAAE,SAAS;IAYhC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ;IAI/B,eAAe;IAOf,OAAO;CAyBR"}
+{"version":3,"file":"scene-manager.d.ts","sourceRoot":"","sources":["../../../src/threed/managers/scene-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,SAAS,MAAM,+BAA+B,CAAA;AA2B1D;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAItE;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAC,CAAa;IAC5B,OAAO,CAAC,MAAM,CAAC,CAAsB;IACrC,OAAO,CAAC,MAAM,CAAC,CAAa;IAC5B,mCAAmC;IACnC,OAAO,CAAC,WAAW,CAAC,CAAe;IACnC,0DAA0D;IAC1D,OAAO,CAAC,UAAU,CAAC,CAAe;IAClC,OAAO,CAAC,SAAS,CAAC,CAAqB;IAEvC,IAAI,KAAK,oDAER;IAED,IAAI,KAAK,mEAER;IAED,KAAK;IAKL,UAAU;IAOV,gBAAgB,CAAC,QAAQ,EAAE,KAAK,CAAC,aAAa;IAO9C,mDAAmD;IACnD,OAAO,CAAC,eAAe;IAYvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAQzB,qBAAqB;IACrB,OAAO,CAAC,uBAAuB;IAO/B,8DAA8D;IAC9D,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;IA4C5D,QAAQ,CAAC,SAAS,EAAE,SAAS;IAO7B;;;OAGG;IACH,WAAW,CAAC,SAAS,EAAE,SAAS;IAYhC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ;IAI/B,eAAe;IAOf,OAAO;CAgCR"}

package/dist-types/threed/material-3d.d.ts

@@ -8,6 +8,14 @@ export interface Material3D {
     opacity?: number;
     envMapIntensity?: number;
     side?: 'double' | 'front' | 'back';
+    /**
+     * 면마다 하나의 법선을 쓴다 — 각진 면이 그대로 보인다. default: false(부드럽게).
+     *
+     * 로우폴리 표현의 핵심 스위치다. 분할 수를 낮춘 원기둥은 smooth shading 에서
+     * 「덜 그린 원기둥」으로 보이고, flat shading 에서 「의도한 각기둥」으로 보인다.
+     * MaterialBank 의 `MaterialSpec.flatShading` 과 같은 값이며 spec 시그니처에 든다.
+     */
+    flatShading?: boolean;
     castShadow?: boolean;
     receiveShadow?: boolean;
 }
@@ -19,6 +27,7 @@ export interface ResolvedMaterial3D {
     opacity: number;
     envMapIntensity: number;
     side: 'double' | 'front' | 'back';
+    flatShading: boolean;
     castShadow: boolean;
     receiveShadow: boolean;
 }

package/dist-types/threed/material-3d.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"material-3d.d.ts","sourceRoot":"","sources":["../../src/threed/material-3d.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,MAAM,WAAW,UAAU;IAEzB,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAA;IAC7F,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAG1B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;IAGlC,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,iBAAiB,EAAE,MAAM,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,EAAE,MAAM,CAAA;IACvB,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;IACjC,UAAU,EAAE,OAAO,CAAA;IACnB,aAAa,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAQ3D,CAAA;AAED,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,kBAAkB,CA4B7E;AAQD,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAExE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,KAAK,CAAC,oBAAoB,EAAE,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAS7G"}
+{"version":3,"file":"material-3d.d.ts","sourceRoot":"","sources":["../../src/threed/material-3d.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,MAAM,WAAW,UAAU;IAEzB,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAA;IAC7F,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAG1B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;IAGlC;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAGrB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,iBAAiB,EAAE,MAAM,CAAA;IACzB,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,EAAE,MAAM,CAAA;IACvB,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAA;IACjC,WAAW,EAAE,OAAO,CAAA;IACpB,UAAU,EAAE,OAAO,CAAA;IACnB,aAAa,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAQ3D,CAAA;AAED,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,kBAAkB,CA8B7E;AAQD,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,CAExE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,KAAK,CAAC,oBAAoB,EAAE,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAgB7G"}

package/dist-types/threed/real-object-camera-meshed.d.ts

@@ -7,7 +7,7 @@ export declare class RealObjectCameraMeshed extends RealObjectMesh {
     createCamera(): THREE.PerspectiveCamera;
     updateCamera(): void;
     build(): void;
-    clear(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
+    clear(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>;
     buildGeometry(): void;
 }
 //# sourceMappingURL=real-object-camera-meshed.d.ts.map

package/dist-types/threed/real-object-dom-texture.d.ts

@@ -7,7 +7,7 @@ export declare class RealObjectDomTexture extends RealObject<THREE.Mesh> {
     private _debounceTimer?;
     private _origInvalidate?;
     constructor(component: any);
-    protected getObject3dInstance(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
+    protected getObject3dInstance(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>;
     build(): void;
     updateDimension(): void;
     updateAlpha(): void;
@@ -23,7 +23,7 @@ export declare class RealObjectDomTexture extends RealObject<THREE.Mesh> {
     updateText(): void;
     onchange(after: Record<string, any>, before: Record<string, any>): void;
     updateMaterial3d(): void;
-    clear(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
+    clear(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>;
     dispose(): void;
 }
 //# sourceMappingURL=real-object-dom-texture.d.ts.map

package/dist-types/threed/real-object-extrude.d.ts

@@ -1,6 +1,7 @@
 import * as THREE from 'three';
 import { RealObject } from './real-object.js';
 import { BoundUVGenerator } from './utils/bound-uv-generator.js';
+import type { TopOutline } from '../interfaces/real-object.js';
 /**
  * ExtrudeGeometry 기반 3D 오브젝트.
  *
@@ -17,6 +18,19 @@ export declare class RealObjectExtrude extends RealObject {
     protected _mesh?: THREE.Mesh;
     clear(): THREE.Object3D<THREE.Object3DEventMap>;
     get shape(): any;
+    /**
+     * 압출 계열의 톱뷰 윤곽 — **2D 경로가 곧 윤곽이다.** 압출은 2D 형상을 위로 밀어
+     * 올린 것이므로 위에서 내려다본 모습이 원래 경로와 같다. 그래서 여섯 서브클래스
+     * (rect·ellipse·triangle·star·polygon·donut) 가 이 한 구현을 함께 쓴다.
+     *
+     * 구멍(donut 의 안쪽)은 담지 않는다 — 윤곽은 실루엣이다.
+     *
+     * `outlineDivisions` 로 곡선 근사를 조절한다. 3D 쪽 분할과 같은 값을 써야 2D 와
+     * 3D 가 같은 모양으로 보인다.
+     */
+    topOutline(): TopOutline | null;
+    /** 곡선을 다각형으로 근사할 때의 분할 수. 곡선이 있는 서브클래스가 올려 잡는다. */
+    get outlineDivisions(): number;
     get boundUVGenerator(): BoundUVGenerator;
     build(): void;
     createGeometry(shape: THREE.Shape): THREE.BufferGeometry;

package/dist-types/threed/real-object-extrude.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-object-extrude.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-extrude.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAOhE;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,iBAAiB,CAAC,EAAE,gBAAgB,CAAA;IACpC,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,IAAI,CAAA;IAE5B,KAAK;IAKL,IAAI,KAAK,IAAI,GAAG,CAEf;IAED,IAAI,gBAAgB,qBAInB;IAED,KAAK;IAoCL,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,cAAc;IAoBxD,eAAe,IAAI,KAAK,CAAC,QAAQ,EAAE;IAcnC,aAAa;IAqBb,OAAO,CAAC,YAAY;IAMpB,gBAAgB;IAYhB,WAAW;IAUX,iBAAiB;IAQjB,eAAe;IAIf,UAAU;IAIV;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA+DxB,eAAe;IAMf;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG;CAajC"}
+{"version":3,"file":"real-object-extrude.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-extrude.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAOhE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAA;AAE9D;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;IAC/C,iBAAiB,CAAC,EAAE,gBAAgB,CAAA;IACpC,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,IAAI,CAAA;IAE5B,KAAK;IAKL,IAAI,KAAK,IAAI,GAAG,CAEf;IAED;;;;;;;;;OASG;IACH,UAAU,IAAI,UAAU,GAAG,IAAI;IAiB/B,mDAAmD;IACnD,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED,IAAI,gBAAgB,qBAInB;IAED,KAAK;IAoCL,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,cAAc;IAoBxD,eAAe,IAAI,KAAK,CAAC,QAAQ,EAAE;IAcnC,aAAa;IAqBb,OAAO,CAAC,YAAY;IAMpB,gBAAgB;IAYhB,WAAW;IAUX,iBAAiB;IAQjB,eAAe;IAIf,UAAU;IAIV;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IA+DxB,eAAe;IAMf;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG;CAajC"}

package/dist-types/threed/real-object-mesh.d.ts

@@ -1,15 +1,92 @@
 import * as THREE from 'three';
+import type { MaterialSpec } from './material-bank.js';
 import { RealObject } from './real-object.js';
 export declare abstract class RealObjectMesh extends RealObject<THREE.Mesh> {
-    protected getObject3dInstance(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
+    protected getObject3dInstance(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>;
     build(): void;
+    /**
+     * 불투명도.
+     *
+     * 나눠 쓰는 재질은 **고치지 않는다** — `state.alpha` 와 faint 는 코어의 오버레이가
+     * 공유 변형을 스왑해 처리하고(`applyMaterialOpacity`), fillStyle 의 alpha 는 창고
+     * 키(spec)에 들어 있다. 여기서 굽으면 같은 재질을 쓰는 다른 인스턴스가 함께 흐려진다.
+     */
     updateAlpha(): void;
     updateFillStyle(): void;
     updateStrokeStyle(): void;
     updateDimension(): void;
     protected abstract buildGeometry(): void;
+    /**
+     * 재질을 창고에서 받을 수 있나.
+     *
+     * 무늬(pattern)·그라디언트 fillStyle 은 인스턴스마다 캔버스 텍스처를 만들어야 하므로
+     * 나눠 쓸 수 없다. 색이 문자열이면 나눠 쓴다 — 캐리어·설비 대부분이 이쪽이다.
+     */
+    protected get canShareMaterial(): boolean;
+    /**
+     * 재질을 나눠 쓸 수 없는 사유. 나눠 쓸 수 있으면 `undefined`.
+     *
+     * 사유를 문장으로 두는 이유 — 진단이 「안 된다」만 말하면 저작자가 무엇을 고쳐야
+     * 하는지 알 수 없다.
+     */
+    get materialSharingIssue(): string | undefined;
+    /**
+     * 이 컴포넌트가 **재질을 반드시 나눠 써야** 하나.
+     *
+     * 대량으로 놓이는 것(캐리어·선반 칸·롤러)은 그렇다고 선언한다. 선언해 두면 무늬·
+     * 그라디언트가 들어왔을 때 **조용히 인스턴스별 재질로 갈리지 않고 진단에 잡힌다.**
+     *
+     * 컴포넌트 클래스에 `static requiresSharedMaterial = true` 로 선언한다 —
+     * `static requires3d` 와 같은 방식이라 인스턴스를 만들지 않고도 조회할 수 있다.
+     *
+     * **그림은 여전히 fillStyle 을 따른다.** 선언을 어겼다고 다른 것을 그리지는 않는다 —
+     * 화면이 원인을 지어내면 안 되기 때문이다. 대신 비용이 드러난다.
+     */
+    get requiresSharedMaterial(): boolean;
+    /**
+     * 재질 공유 상태 — 진단이 읽는다.
+     *
+     * `violated` 는 「나눠 써야 한다고 선언했는데 못 쓰고 있다」는 뜻이다. 대량 배치에서
+     * 재질이 인스턴스 수만큼 생기는 상태이므로 저작을 고쳐야 한다.
+     */
+    get materialSharing(): {
+        shared: boolean;
+        required: boolean;
+        violated: boolean;
+        reason?: string;
+        bankKey?: string;
+    };
+    /**
+     * 창고 키. 관례는 `"{컴포넌트명}|{용도}"` — 컴포넌트 종류가 다르면 base 를 나눈다.
+     *
+     * 종류를 키에 넣는 이유는 진단이다. spec 이 같으면 종류를 넘어 공유해도 결과가 같지만,
+     * 창고를 들여다볼 때 어느 컴포넌트가 무엇을 쓰는지 보이는 편이 낫다.
+     */
+    protected get materialBankKey(): string;
+    /**
+     * 창고에 넘길 intrinsic spec — **색은 넣지 않는다.**
+     *
+     * 색은 `MaterialBank.material(key, spec, color)` 의 셋째 인자로 넘겨 색상별 공유
+     * 변형이 되게 한다. spec 에 넣으면 색마다 base 가 하나씩 생겨 공유가 반토막 난다.
+     */
+    protected materialSpec(): MaterialSpec;
+    /**
+     * 재질을 세운다.
+     *
+     * 나눠 쓸 수 있으면 `MaterialBank` 에서 받는다 — **인스턴스가 수천 개여도 재질은 spec·색
+     * 조합 수만큼만 생긴다.** 전에는 인스턴스마다 `new MeshStandardMaterial()` 이라 캐리어
+     * 1만 개면 재질도 1만 개였고, 같은 geometry 를 써도 재질이 달라 draw call 이 합쳐지지
+     * 않았다.
+     *
+     * 나눠 쓸 수 없으면(무늬·그라디언트) 전처럼 제 것을 만든다.
+     */
     buildMaterial(): void;
+    /**
+     * 창고 재질을 물린다. 색·재질 속성이 바뀔 때마다 **고치지 않고 다시 받는다** —
+     * 공유물을 고치면 같은 재질을 쓰는 다른 인스턴스가 함께 바뀐다.
+     */
+    protected applyBankMaterial(): void;
     updateMaterial3d(): void;
-    clear(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
+    clear(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>;
 }
 //# sourceMappingURL=real-object-mesh.d.ts.map

package/dist-types/threed/real-object-mesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"real-object-mesh.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-mesh.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAK9B,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAG7C,8BAAsB,cAAe,SAAQ,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;IACjE,SAAS,CAAC,mBAAmB;IAI7B,KAAK;IASL,WAAW;IAMX,eAAe;IAgCf,iBAAiB;IAuBjB,eAAe,IAAI,IAAI;IAqBvB,SAAS,CAAC,QAAQ,CAAC,aAAa,IAAI,IAAI;IAExC,aAAa,IAAI,IAAI;IAOrB,gBAAgB;IAShB,KAAK;CAKN"}
+{"version":3,"file":"real-object-mesh.d.ts","sourceRoot":"","sources":["../../src/threed/real-object-mesh.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAM9B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAG7C,8BAAsB,cAAe,SAAQ,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC;IACjE,SAAS,CAAC,mBAAmB;IAI7B,KAAK;IAgBL;;;;;;OAMG;IACH,WAAW;IAUX,eAAe;IAwCf,iBAAiB;IAuBjB,eAAe,IAAI,IAAI;IA0BvB,SAAS,CAAC,QAAQ,CAAC,aAAa,IAAI,IAAI;IAExC;;;;;OAKG;IACH,SAAS,KAAK,gBAAgB,IAAI,OAAO,CAExC;IAED;;;;;OAKG;IACH,IAAI,oBAAoB,IAAI,MAAM,GAAG,SAAS,CAU7C;IAED;;;;;;;;;;;OAWG;IACH,IAAI,sBAAsB,IAAI,OAAO,CAEpC;IAED;;;;;OAKG;IACH,IAAI,eAAe,IAAI;QACrB,MAAM,EAAE,OAAO,CAAA;QACf,QAAQ,EAAE,OAAO,CAAA;QACjB,QAAQ,EAAE,OAAO,CAAA;QACjB,MAAM,CAAC,EAAE,MAAM,CAAA;QACf,OAAO,CAAC,EAAE,MAAM,CAAA;KACjB,CAcA;IAED;;;;;OAKG;IACH,SAAS,KAAK,eAAe,IAAI,MAAM,CAEtC;IAED;;;;;OAKG;IACH,SAAS,CAAC,YAAY,IAAI,YAAY;IAkBtC;;;;;;;;;OASG;IACH,aAAa,IAAI,IAAI;IAYrB;;;OAGG;IACH,SAAS,CAAC,iBAAiB,IAAI,IAAI;IAUnC,gBAAgB;IAiBhB,KAAK;CAQN"}

package/dist-types/threed/real-object-plane-2d.d.ts

@@ -8,7 +8,7 @@ export declare class RealObjectPlane2D extends RealObject<THREE.Mesh> {
     private _debounceTimer?;
     private _origInvalidate?;
     constructor(component: any);
-    protected getObject3dInstance(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
+    protected getObject3dInstance(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>;
     build(): void;
     updateAlpha(): void;
     get dimension(): {
@@ -34,7 +34,7 @@ export declare class RealObjectPlane2D extends RealObject<THREE.Mesh> {
     updateStrokeStyle(): void;
     updateText(): void;
     updateMaterial3d(): void;
-    clear(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
+    clear(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>;
     dispose(): void;
 }
 //# sourceMappingURL=real-object-plane-2d.d.ts.map

package/dist-types/threed/real-object-scene.d.ts

@@ -3,9 +3,9 @@ import { RealObject } from './real-object.js';
 export declare class RealObjectScene extends RealObject<THREE.Scene> {
     private _floor?;
     private _animationMixer?;
-    protected getObject3dInstance(): THREE.Scene;
+    protected getObject3dInstance(): THREE.Scene<THREE.Object3DEventMap>;
     dispose(): void;
-    clear(): THREE.Scene;
+    clear(): THREE.Scene<THREE.Object3DEventMap>;
     get floor(): THREE.Mesh;
     set floor(floor: THREE.Mesh | undefined);
     build(): void;

package/dist-types/threed/real-object-service.d.ts

@@ -1,7 +1,7 @@
 import * as THREE from 'three';
 import { RealObject } from './real-object.js';
 export declare class RealObjectService extends RealObject<THREE.Mesh> {
-    protected getObject3dInstance(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
+    protected getObject3dInstance(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>;
     build(): void;
     updateAlpha(): void;
     updateHidden(): void;
@@ -9,6 +9,6 @@ export declare class RealObjectService extends RealObject<THREE.Mesh> {
     updateFillStyle(): void;
     updateStrokeStyle(): void;
     updateText(): void;
-    clear(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material | THREE.Material[], THREE.Object3DEventMap>;
+    clear(): THREE.Mesh<THREE.BufferGeometry<THREE.NormalBufferAttributes, THREE.BufferGeometryEventMap>, THREE.Material<THREE.MaterialEventMap> | THREE.Material<THREE.MaterialEventMap>[], THREE.Object3DEventMap>;
 }
 //# sourceMappingURL=real-object-service.d.ts.map