ice3 0.2.1 → 0.2.3

package/README.md

@@ -9,13 +9,13 @@
 ICE3 是面向工业场景的浏览器 3D Runtime。公开代码通过单向 facade 暴露 Scene、
 Geometry、Camera、Asset 和 Tileset API。
 
-## 安装
+## 1. 安装
 
 ```bash
 npm install ice3
 ```
 
-## 最小使用
+## 2. 最小使用
 
 ```ts
 import {
@@ -54,9 +54,10 @@ WebGL2 兼容别名。拾取使用 `await engine.pick(point)`。
 完整文档和相关工具见
 [Engine 文档](https://github.com/ice-3d/ice3-engine/blob/main/README.md)。
 
-工业模型接入 Runtime 前，使用配套的
-[ICE3 Toolchain](https://github.com/ice-3d/ice3-toolchain/blob/main/README.md)
-进行离线格式转换、验证、切分、LOD 和 Tileset 发布。功能与格式支持见
-[Toolchain 功能指南](https://github.com/ice-3d/ice3-toolchain/blob/main/docs/guides/capabilities.md)。
+工业模型接入 Runtime 前，使用
+[ICE3 Studio](https://github.com/ice-3d/ice3-studio/blob/main/README.md)
+完成 Source Import、Prepare、验证、partition、LOD 和 Tileset 发布。当前生产链见
+[Studio Asset Pipeline](https://github.com/ice-3d/ice3-studio/blob/main/docs/reference/asset-pipeline.md)。
+公开 package 的当前版本为 `0.2.3`。
 
 本项目采用 MIT License。

package/dist/_types/assets/ICEGLBReader.d.ts

@@ -1,4 +1,11 @@
 import type { ICEPreparedAssetSnapshot } from './ICEPreparedGLB.js';
-export declare function readPreparedGLB(bytes: ArrayBuffer): ICEPreparedAssetSnapshot;
+export interface ICEPreparedReadOptions {
+    /**
+     * URL the GLB was loaded from. Texture images are resolved against it, as
+     * glTF requires external resources to be relative to the referencing file.
+     */
+    readonly baseUrl?: string;
+}
+export declare function readPreparedGLB(bytes: ArrayBuffer, options?: ICEPreparedReadOptions): ICEPreparedAssetSnapshot;
 export declare function verifyPreparedGLBIntegrity(bytes: ArrayBuffer): Promise<boolean>;
 //# sourceMappingURL=ICEGLBReader.d.ts.map

package/dist/_types/assets/ICEPreparedGLB.d.ts

@@ -22,6 +22,31 @@ export interface ICEPreparedMaterial {
     readonly baseColor: string;
     readonly edgeColor?: string;
     readonly shading?: 'directional' | 'flat' | 'water';
+    /** Base-colour texture resolved from the source glTF. */
+    readonly map?: {
+        readonly url: string;
+        readonly scale?: readonly [number, number];
+    };
+    /** Tangent-space normal map. */
+    readonly normalMap?: {
+        readonly url: string;
+        readonly strength?: number;
+    };
+    /**
+     * Packed ORM map: R occlusion, G roughness, B metallic. A glTF may ship the
+     * two halves as separate slots; when they resolve to the same image the
+     * renderer samples it once.
+     */
+    readonly ormMap?: {
+        readonly url: string;
+        readonly scale?: readonly [number, number];
+        readonly occlusion: boolean;
+        readonly metallicRoughness: boolean;
+    };
+    /** Metallic-roughness factors straight from the glTF material. */
+    readonly metallic?: number;
+    readonly roughness?: number;
+    readonly emissive?: readonly [number, number, number];
 }
 export interface ICEPreparedMesh {
     readonly id: string;

package/dist/_types/assets/index.d.ts

@@ -1,4 +1,5 @@
 export { readPreparedGLB, verifyPreparedGLBIntegrity, } from './ICEGLBReader.js';
+export type { ICEPreparedReadOptions } from './ICEGLBReader.js';
 export type { ICEPreparedAssetSnapshot, ICEPreparedBatch, ICEPreparedBatching, ICEPreparedContract, ICEPreparedGeometry, ICEPreparedMaterial, ICEPreparedMesh, ICEPreparedNode, ICEPreparedStats, } from './ICEPreparedGLB.js';
 export { applyPreviewGeometryDelta, parsePreviewGeometryPacket, } from './ICEPreviewGeometryPacket.js';
 export type { ICEPreviewGeometry, ICEPreviewGeometryBackend, ICEPreviewGeometryDelta, ICEPreviewGeometryManifest, ICEPreviewGeometryMaterial, ICEPreviewGeometryNode, ICEPreviewGeometryPacket, ICEPreviewGeometryRange, ICEPreviewGeometryRangeUsage, ICEPreviewGeometryRecord, ICEPreviewGeometryResidencyMode, } from './ICEPreviewGeometryPacket.js';

package/dist/_types/core/camera/ICEPerspectiveCamera.d.ts

@@ -21,6 +21,11 @@ export declare class ICEPerspectiveCamera {
     setClipPlanes(near: number, far: number): this;
     getPosition(): ICEVector3;
     getTarget(): ICEVector3;
+    /**
+     * 投影矩阵。屏幕空间效果要从深度重建视空间坐标，光有 viewProjection 不够。
+     */
+    getProjectionMatrix(aspect: number): ICEMatrix4;
+    getViewMatrix(): ICEMatrix4;
     getViewProjectionMatrix(aspect: number): ICEMatrix4;
 }
 //# sourceMappingURL=ICEPerspectiveCamera.d.ts.map

package/dist/_types/core/index.d.ts

@@ -9,7 +9,7 @@ export { ICEIndexedGeometry } from './geometry/ICEIndexedGeometry.js';
 export type { ICEIndexedGeometryOptions } from './geometry/ICEIndexedGeometry.js';
 export type { ICEGeometry, ICEGeometryBounds, ICEGeometryBufferUpdate, ICEGeometryByteRange, ICEGeometryIdentity, } from './geometry/ICEGeometry.js';
 export { ICEBasicMaterial } from './material/ICEBasicMaterial.js';
-export type { ICEBasicMaterialOptions } from './material/ICEBasicMaterial.js';
+export type { ICEBasicMaterialMap, ICEBasicMaterialNormalMap, ICEBasicMaterialOptions, ICEBasicMaterialOrmMap, } from './material/ICEBasicMaterial.js';
 export { ICEPerspectiveCamera } from './camera/ICEPerspectiveCamera.js';
 export type { ICEPerspectiveCameraOptions } from './camera/ICEPerspectiveCamera.js';
 export { ICEFrustum } from './culling/ICEFrustum.js';

package/dist/_types/core/material/ICEBasicMaterial.d.ts

@@ -1,13 +1,63 @@
+/**
+ * Base-colour texture reference.
+ *
+ * `url` points at an image the renderer loads asynchronously; `scale` tiles it
+ * over the metre-based UV projection (`[1,1]` means one texture repeat per metre).
+ */
+export declare const DEFAULT_ROUGHNESS = 0.85;
+export interface ICEBasicMaterialMap {
+    readonly url: string;
+    readonly scale?: readonly [number, number];
+}
+/**
+ * Tangent-space normal map.
+ *
+ * `strength` multiplies the sampled X/Y perturbation, matching glTF's
+ * `normalTexture.scale`; 1 is neutral.
+ */
+export interface ICEBasicMaterialNormalMap {
+    readonly url: string;
+    readonly strength?: number;
+}
+/**
+ * Packed occlusion / roughness / metallic map, the glTF ORM layout:
+ * R = ambient occlusion, G = roughness, B = metallic.
+ *
+ * `occlusion` and `metallicRoughness` say which channels the image actually
+ * carries — an exporter may ship only the metallic-roughness half, and using the
+ * R channel then would darken surfaces for no reason.
+ */
+export interface ICEBasicMaterialOrmMap {
+    readonly url: string;
+    readonly scale?: readonly [number, number];
+    readonly occlusion?: boolean;
+    readonly metallicRoughness?: boolean;
+}
 export interface ICEBasicMaterialOptions {
     readonly color: string;
     readonly edgeColor?: string;
     readonly shading?: 'directional' | 'flat' | 'water';
+    readonly map?: ICEBasicMaterialMap;
+    readonly normalMap?: ICEBasicMaterialNormalMap;
+    readonly ormMap?: ICEBasicMaterialOrmMap;
+    /** 0 = dielectric, 1 = metal. Drives the specular tint and strength. */
+    readonly metallic?: number;
+    /** 0 = mirror-smooth highlight, 1 = broad and dull. */
+    readonly roughness?: number;
+    /** Linear RGB emitted by the surface, added after lighting. */
+    readonly emissive?: readonly [number, number, number];
 }
 export declare class ICEBasicMaterial {
     readonly typeId = "ice3:BasicMaterial";
     readonly color: string;
     readonly edgeColor: string | undefined;
     readonly shading: 'directional' | 'flat' | 'water' | undefined;
+    readonly map: ICEBasicMaterialMap | undefined;
+    readonly normalMap: ICEBasicMaterialNormalMap | undefined;
+    readonly ormMap: ICEBasicMaterialOrmMap | undefined;
+    readonly metallic: number;
+    readonly roughness: number;
+    readonly emissive: readonly [number, number, number] | undefined;
     constructor(options: ICEBasicMaterialOptions);
     toJSON(): Record<string, unknown>;
 }

package/dist/_types/renderer/InstanceBatch.d.ts

@@ -11,4 +11,11 @@ export interface ICEInstanceBatch {
     readonly materialKey: string;
 }
 export declare function collectInstanceBatches(renderables: readonly ICEGeometryRenderable[], output?: ICEInstanceBatch[]): readonly ICEInstanceBatch[];
+/**
+ * 落单的网格：几何与材质组合只出现一次，实例化省不下开销，主通道仍按单体绘制。
+ *
+ * 单独抽出来是因为**每个附加通道都要画同一批东西**。深度通道漏掉这一条，
+ * 落单的网格就既不参与遮挡也不接收遮蔽（SPEC-007 第 5 节）。
+ */
+export declare function renderablesOutsideInstanceBatches(renderables: readonly ICEGeometryRenderable[], batches: readonly ICEInstanceBatch[]): ICEGeometryRenderable[];
 //# sourceMappingURL=InstanceBatch.d.ts.map

package/dist/_types/renderer/SceneBounds.d.ts

@@ -0,0 +1,16 @@
+import type { ICEGeometry } from '../core/index.js';
+import type { ICEGeometryRenderable } from './Renderables.js';
+import type { ICEBounds } from './ShadowFrustum.js';
+type LocalBounds = Readonly<{
+    min: readonly [number, number, number];
+    max: readonly [number, number, number];
+}>;
+/** 几何的局部包围盒：只在首次见到该几何时扫描一遍顶点。 */
+export declare function geometryLocalBounds(geometry: ICEGeometry): LocalBounds | null;
+/**
+ * 累加所有可渲染网格的世界包围盒。返回 `null` 表示场景是空的，
+ * 调用方应退回默认视锥而不是用空盒子去拟合（否则视锥退化成一条线）。
+ */
+export declare function accumulateSceneBounds(renderables: readonly ICEGeometryRenderable[]): ICEBounds | null;
+export {};
+//# sourceMappingURL=SceneBounds.d.ts.map

package/dist/_types/renderer/ShadowFrustum.d.ts

@@ -0,0 +1,20 @@
+export type ICEBounds = Readonly<{
+    min: readonly [number, number, number];
+    max: readonly [number, number, number];
+}>;
+/** 光源方向（与主着色器、阴影 pass 共用同一约定：指向"光传播"的方向）。 */
+export declare const SHADOW_LIGHT_DIRECTION: readonly [number, number, number];
+export type ICEShadowFrustum = Readonly<{
+    /** 光照视图投影矩阵（列主序 16 元素）。 */
+    matrix: Float32Array;
+    /** 一个纹素在世界空间里的边长（米）：法线偏移量按它来算。 */
+    texelWorld: number;
+}>;
+/**
+ * 场景包围盒 → 光照视图投影矩阵（列主序 16 元素）。
+ *
+ * 传入 `null` 时退回一个覆盖 600 米场地的默认盒，避免直接抛错：
+ * 阴影是可选效果，宁可保守覆盖也不要整帧失败。
+ */
+export declare function shadowFrustum(bounds: ICEBounds | null, mapSize?: number): ICEShadowFrustum;
+//# sourceMappingURL=ShadowFrustum.d.ts.map

package/dist/_types/renderer/WebGL2DepthMath.d.ts

@@ -0,0 +1,22 @@
+export type PerspectiveProjection = {
+    /** 投影矩阵列主序元素，与 `ICEMatrix4.elements` 一致。 */
+    readonly elements: Float32Array | readonly number[];
+    readonly near: number;
+    readonly far: number;
+};
+/**
+ * NDC `(x, y, depth)` → 视空间坐标（右手系，相机看向 −Z）。
+ *
+ * `depth` 取深度缓冲里的值，范围 `[0, 1]`。
+ */
+export declare function viewPositionFromNdc(ndcX: number, ndcY: number, depth: number, projection: PerspectiveProjection): [number, number, number];
+/** 视空间坐标 → NDC；`w` 不为正说明落在相机背面。 */
+export declare function ndcFromViewPosition(position: readonly [number, number, number], projection: PerspectiveProjection): [number, number, number, number];
+/**
+ * 视空间半径 → 屏幕像素半径。
+ *
+ * 用样本点到相机的深度换算，靠近相机时半径自然放大、远处收小；这正是
+ * "按视距自适应"要的效果，而且不需要知道世界单位与像素的比例。
+ */
+export declare function screenRadiusForWorldRadius(worldRadius: number, viewDepth: number, viewportHeight: number, projection: PerspectiveProjection): number;
+//# sourceMappingURL=WebGL2DepthMath.d.ts.map

package/dist/_types/renderer/WebGL2InstanceBatch.d.ts

@@ -1,7 +1,7 @@
 import { WebGL2GeometryCache } from './WebGL2GeometryCache.js';
 import type { ICEInstanceBatch } from './InstanceBatch.js';
 export type { ICEGeometryRenderable } from './Renderables.js';
-export { collectInstanceBatches, type ICEInstanceBatch, } from './InstanceBatch.js';
+export { collectInstanceBatches, renderablesOutsideInstanceBatches, type ICEInstanceBatch, } from './InstanceBatch.js';
 export interface WebGL2InstanceEntry {
     readonly vertexArray: WebGLVertexArrayObject;
     readonly matrixBuffer: WebGLBuffer;

package/dist/_types/renderer/WebGL2Program.d.ts

@@ -1,5 +1,13 @@
 import type { ICEMatrix4 } from '../core/index.js';
 export declare function directionalLightingShade(normal: readonly [number, number, number]): number;
+/**
+ * Mirror of the shader's specular curve, exported so the response can be tested
+ * without a GPU: smoother surfaces get a tighter, stronger highlight.
+ */
+export declare function specularShininess(roughness: number): number;
+export declare function specularGain(roughness: number): number;
+/** Metals tint their highlight with the base colour; dielectrics stay neutral. */
+export declare function specularReflectance(metallic: number, color: readonly [number, number, number]): [number, number, number];
 export declare class WebGL2Program {
     private readonly gl;
     static readonly POSITION_ATTRIBUTE = 0;
@@ -17,16 +25,62 @@ export declare class WebGL2Program {
     private readonly shadowMapLocation;
     private readonly lightMatrixLocation;
     private readonly shadowEnabledLocation;
+    private readonly shadowNormalOffsetLocation;
+    private readonly shadowDebugLocation;
     private readonly instancingLocation;
     private readonly pickModeLocation;
+    private readonly clipPlaneLocation;
+    private readonly baseColorMapLocation;
+    private readonly useBaseColorMapLocation;
+    private readonly uvScaleLocation;
+    private readonly normalMapLocation;
+    private readonly ormMapLocation;
+    private readonly useOrmMapLocation;
+    private readonly ormOcclusionLocation;
+    private readonly ormMetallicRoughnessLocation;
+    private readonly useNormalMapLocation;
+    private readonly normalScaleLocation;
+    private readonly metallicLocation;
+    private readonly roughnessLocation;
+    private readonly emissiveLocation;
+    private readonly sceneDepthLocation;
+    private readonly useSceneDepthLocation;
+    private readonly projectionLocation;
+    private readonly viewportLocation;
+    private readonly clipRangeLocation;
+    private readonly aoRadiusLocation;
+    private readonly aoStrengthLocation;
     constructor(gl: WebGL2RenderingContext);
     use(): void;
     setMatrix(matrix: ICEMatrix4): void;
     setColor(color: readonly [number, number, number, number]): void;
+    /**
+     * Bind a base-colour texture to unit 0 and enable sampling. Passing `null`
+     * restores flat shading without touching the bound texture.
+     */
+    setBaseColorMap(texture: WebGLTexture | null, scale: readonly [number, number]): void;
+    /** Bind a tangent-space normal map to unit 1; `null` disables perturbation. */
+    setNormalMap(texture: WebGLTexture | null, strength: number): void;
+    /**
+     * Bind the packed ORM map. `occlusion` / `metallicRoughness` describe which
+     * halves of the image are meaningful; both false disables sampling.
+     */
+    setOrmMap(texture: WebGLTexture | null, occlusion: boolean, metallicRoughness: boolean): void;
+    /** Metallic-roughness factors plus emission for the current draw. */
+    setSurface(metallic: number, roughness: number, emissive: readonly [number, number, number] | undefined): void;
+    /** 绑定相机深度纹理（unit 2）并传入重建视空间所需的相机参数。 */
+    setSceneDepth(texture: WebGLTexture | null, projection: {
+        readonly elements: Float32Array;
+    } | null, near: number, far: number, deviceWidth: number, deviceHeight: number): void;
+    /** 遮蔽半径（米）与强度，供运行时调节。强度 0 等于关闭。 */
+    setOcclusion(radius: number, strength: number): void;
     setClipOffset(x: number, y: number): void;
+    setClipPlane(plane: readonly [number, number, number, number]): void;
     setVertexColors(enabled: boolean): void;
     /** 绑定阴影贴图与光源矩阵；关闭时着色器跳过采样。 */
-    setShadow(enabled: boolean, texture: WebGLTexture | null, matrix: Float32Array | null, unit?: number): void;
+    setShadow(enabled: boolean, texture: WebGLTexture | null, matrix: Float32Array | null, normalOffset?: number, unit?: number): void;
+    /** 阴影调试通道：0 关闭，1 输出遮蔽判定，2 输出深度图。 */
+    setShadowDebug(mode: number): void;
     setDirectionalShading(enabled: boolean): void;
     setWaterShading(enabled: boolean): void;
     setCameraPosition(position: readonly [number, number, number]): void;

package/dist/_types/renderer/WebGL2RendererBackend.d.ts

@@ -11,8 +11,16 @@ export declare class WebGL2RendererBackend implements ICERendererBackend {
     private onContextLost;
     private onContextRestored;
     private program;
+    private clipPlane;
     private shadowMap;
-    private readonly shadowEnabled;
+    /**
+     * 方向光阴影开关。默认开启：没有影子的厂区看起来像浮在地上，
+     * 而多一次全场景深度 pass 的代价远小于这个观感损失。
+     * 要关掉用 `initialize({ shadows: false })` 或页面地址 `?shadows=0`。
+     */
+    private shadowEnabled;
+    /** `?shadowdebug=1` 输出遮蔽判定，`=2` 输出深度图；排查阴影问题的唯一可信手段。 */
+    private shadowDebug;
     private semanticProgram;
     private geometryCache;
     private instanceCache;
@@ -27,12 +35,47 @@ export declare class WebGL2RendererBackend implements ICERendererBackend {
     private lastFrameProfile;
     private backgroundRgba;
     private frameStats;
+    private textures;
+    private sceneDepth;
+    private occlusionRadius;
+    /**
+     * 三圈采样比双圈多找到约 1.7 个亮度点的遮蔽（同参数 96.36 → 94.65），原样沿用到
+     * 默认值就把厂区压得发闷。0.30 是回调后的值：整帧 95.70（无遮蔽 99.59），
+     * 高光像素 878（无遮蔽 1088），接触暗部仍看得见。详见 SPEC-007 第 5.5 节。
+     */
+    private occlusionStrength;
+    private options;
+    /**
+     * Bind the material's colour and (if it has one) its base-colour texture.
+     * Called for every opaque/shaded draw so a batched draw and a single mesh draw
+     * cannot drift apart.
+     */
+    private applyMaterial;
+    /** Edge overlays are line work: never sampled, always flat. */
+    private applyEdgeMaterial;
+    /**
+     * `?ao=<radius>,<strength>` 覆盖遮蔽参数（`ao=off` 关闭）。
+     *
+     * 屏幕空间遮蔽的合适参数与场景尺度强相关，靠改代码重编译来找太慢。这里只读一次
+     * 页面地址，纯属调参通道，不参与渲染决策。
+     */
+    private readOcclusionOverride;
+    /**
+     * `?shadows=1` / `?shadows=0` 覆盖阴影开关，与 `?ao` 同属调参通道。
+     *
+     * 阴影是一次额外全场景 pass，默认不开；演示与对比时靠地址栏切换，
+     * 不必为看清"有影子/没影子"重编译一次。
+     */
+    private readShadowOverride;
+    private ensureTextureCache;
     private readonly handleContextLost;
     private readonly handleContextRestored;
     initialize(options: {
         readonly canvas: HTMLCanvasElement;
         readonly onContextLost?: () => void;
         readonly onContextRestored?: () => void;
+        readonly onUploadReady?: () => void;
+        readonly shadows?: boolean;
     }): void;
     resize(viewport: ICEViewport, dpr: number): void;
     setBackgroundColor(color: string): void;
@@ -40,6 +83,7 @@ export declare class WebGL2RendererBackend implements ICERendererBackend {
     prepareGeometry(geometry: ICEGeometry, update?: import('../core/index.js').ICEGeometryBufferUpdate): void;
     releaseGeometry(geometry: ICEGeometry): void;
     releaseBatchGeometry(geometry: ICEGeometry): void;
+    setClipPlane(plane: readonly [number, number, number, number] | null): void;
     render(frame: ICEFrame): void;
     enableProfiling(enabled: boolean): void;
     get frameProfile(): ICEFrameStageProfile | null;

package/dist/_types/renderer/WebGL2SceneDepth.d.ts

@@ -0,0 +1,19 @@
+export declare class WebGL2SceneDepth {
+    private readonly gl;
+    private readonly framebuffer;
+    private depthTexture;
+    private readonly program;
+    private readonly matrixLocation;
+    private readonly instancingLocation;
+    private width;
+    private height;
+    constructor(gl: WebGL2RenderingContext);
+    get texture(): WebGLTexture | null;
+    begin(viewProjection: Float32Array, width: number, height: number): void;
+    setMatrix(matrix: Float32Array): void;
+    setInstancing(enabled: boolean): void;
+    end(width: number, height: number): void;
+    dispose(): void;
+    private ensureTexture;
+}
+//# sourceMappingURL=WebGL2SceneDepth.d.ts.map

package/dist/_types/renderer/WebGL2Shader.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Compile and link a program, throwing with the driver's info log on failure.
+ *
+ * WebGL fails silently: `compileShader`/`linkProgram` only set a status flag, and
+ * code that returns `null` on failure turns a shader typo into "this pass simply
+ * does nothing". That is exactly how a depth pass can run for two rounds without
+ * changing a single pixel (SPEC-007). Every program in the renderer goes through
+ * here so a broken shader is loud and quotable.
+ */
+export declare function createShaderProgram(gl: WebGL2RenderingContext, vertexSource: string, fragmentSource: string, label: string): WebGLProgram;
+//# sourceMappingURL=WebGL2Shader.d.ts.map

package/dist/_types/renderer/WebGL2ShadowMap.d.ts

@@ -1,26 +1,42 @@
+import { type ICEBounds } from './ShadowFrustum.js';
 /** 光源方向（与主着色器的 diffuse 保持同一方向）。 */
-export declare const LIGHT_DIRECTION: readonly [number, number, number];
+export { SHADOW_LIGHT_DIRECTION as LIGHT_DIRECTION } from './ShadowFrustum.js';
 export declare class WebGL2ShadowMap {
     private readonly gl;
+    /** 最近一次着色器编译/链接失败的原因，供诊断读取。 */
+    lastError: string | null;
     private framebuffer;
     private depthTexture;
     private program;
-    private lightMatrixLocation;
+    private matrixLocation;
+    private instancingLocation;
     private matrixScratch;
+    private texelWorldValue;
     constructor(gl: WebGL2RenderingContext);
     /** 深度纹理，供主着色器采样。 */
     get texture(): WebGLTexture | null;
     get matrix(): Float32Array;
+    /** 一个深度纹素在世界空间的边长（米）。法线偏移按它换算，别用魔数。 */
+    get texelWorld(): number;
+    /**
+     * 按场景包围盒拟合视锥。每帧调用没有意义——场景内容不变时矩阵也不会变，
+     * 所以由调用方决定何时重算（包围盒变化或首帧）。
+     */
+    setBounds(bounds: ICEBounds | null): void;
     /** 绑定阴影帧缓冲，返回是否成功。 */
     begin(): boolean;
+    /**
+     * 非实例化绘制：矩阵换成 `lightViewProjection × world`，顶点位置直接当世界坐标用。
+     *
+     * 阴影通道原先只会画实例化批次，瓦片（渲染批次）与落单网格因此完全不投影。
+     * 补这两条路径靠的就是这个入口——和 `WebGL2SceneDepth` 同一套写法。
+     */
+    setMatrix(matrix: Float32Array): void;
+    setInstancing(enabled: boolean): void;
     /** 解绑，恢复默认帧缓冲。 */
     end(width: number, height: number): void;
     dispose(): void;
     private createResources;
-    /** 正交光源矩阵：覆盖整片场地，与主着色器的光方向一致。 */
-    private updateLightMatrix;
     private createProgram;
-    private compile;
 }
-export declare const SHADOW_BIAS = 0.0018;
 //# sourceMappingURL=WebGL2ShadowMap.d.ts.map

package/dist/_types/renderer/WebGL2TextureCache.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Base-colour texture cache.
+ *
+ * Materials reference textures by URL; the renderer turns each URL into one
+ * `WebGLTexture` the first time a frame needs it and keeps it for later frames.
+ * Loading is asynchronous, so the first frames after a URL appears draw with the
+ * flat material colour and switch to the texture once the upload lands — a
+ * self-correcting behaviour that never blocks the frame loop.
+ */
+export type ICEImageLoader = (url: string) => Promise<ImageBitmap>;
+export type ICEWebGL2TextureStats = {
+    readonly loaded: number;
+    readonly pending: number;
+    readonly failed: number;
+};
+/** Default loader: fetch the image and decode it off the main thread. */
+export declare const fetchImageLoader: ICEImageLoader;
+export declare class WebGL2TextureCache {
+    private readonly gl;
+    private readonly load;
+    private readonly onUpload?;
+    private readonly entries;
+    private disposed;
+    constructor(gl: WebGL2RenderingContext, load?: ICEImageLoader, onUpload?: (() => void) | undefined);
+    /** Texture for `url`, or `null` while it is still loading (or after failure). */
+    texture(url: string): WebGLTexture | null;
+    stats(): ICEWebGL2TextureStats;
+    dispose(): void;
+    private upload;
+}
+//# sourceMappingURL=WebGL2TextureCache.d.ts.map

package/dist/_types/renderer/WebGL2Uv.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Box-projected texture coordinates.
+ *
+ * Studio generates geometry procedurally, so meshes reach the renderer without a
+ * UV attribute. The projection is derived from the surface instead: each fragment
+ * is projected along the dominant axis of its normal, which is stable inside a
+ * face and needs no extra vertex channel.
+ *
+ * This mirrors `box_projected_uvs` in Studio's exporter, so a surface textured in
+ * the viewport and the same surface exported as glTF land on the same texels.
+ * Coordinates are in metres; tiling is a material concern.
+ */
+export type ICEUvScale = readonly [number, number];
+export declare const DEFAULT_UV_SCALE: ICEUvScale;
+export declare function boxProjectedUv(position: readonly [number, number, number], normal: readonly [number, number, number], scale?: ICEUvScale): [number, number];
+//# sourceMappingURL=WebGL2Uv.d.ts.map

package/dist/_types/renderer/index.d.ts

@@ -15,7 +15,7 @@ export { WebGPUBundleCache } from './WebGPUBundleCache.js';
 export { buildSelectionMask, WebGPUSelectionMaskBuffer, type ICESelectionMaskLayout, } from './WebGPUSelectionMask.js';
 export { collectWebGPUPickIds, WebGPUPicker, } from './WebGPUPicker.js';
 export { collectRenderables, selectionIdentity, type ICEGeometryRenderable, } from './Renderables.js';
-export { collectInstanceBatches, type ICEInstanceBatch, } from './InstanceBatch.js';
+export { collectInstanceBatches, renderablesOutsideInstanceBatches, type ICEInstanceBatch, } from './InstanceBatch.js';
 export { queueBatchGeneration } from './ICEWebGL2BatchGenerationUploader.js';
 export type { ICEFrameStageProfile, } from './RendererProfiler.js';
 export { RendererProfiler, } from './RendererProfiler.js';

package/dist/_types/renderer/types.d.ts

@@ -49,9 +49,15 @@ export interface ICERendererBackend {
         readonly onContextLost?: () => void;
         readonly onContextRestored?: () => void;
         readonly onError?: (error: ICEEngineError) => void;
+        /** A deferred GPU upload (for example a base-colour texture) just landed. */
+        readonly onUploadReady?: () => void;
+        /** Directional-light shadows. On by default; pass false to skip the extra scene pass. */
+        readonly shadows?: boolean;
     }): void;
     resize(viewport: ICEViewport, dpr: number): void;
     setBackgroundColor?(color: string): void;
+    /** Clip plane `[nx, ny, nz, d]`: fragments with `dot(world, n) + d < 0` are discarded; `null` disables. */
+    setClipPlane?(plane: readonly [number, number, number, number] | null): void;
     prepareBatchGeometry?(geometry: ICEGeometry): void;
     releaseBatchGeometry?(geometry: ICEGeometry): void;
     prepareGeometry?(geometry: ICEGeometry, update?: ICEGeometryBufferUpdate): void;

package/dist/_types/runtime/ICE3.d.ts

@@ -72,6 +72,7 @@ export declare class ICE3 extends ICEEventDispatcher {
     private generatedOverlayCanvas;
     private scene;
     private camera;
+    private clipPlane;
     private viewport;
     private dpr;
     private frameId;
@@ -96,6 +97,11 @@ export declare class ICE3 extends ICEEventDispatcher {
     setScene(scene: ICEScene): this;
     setCamera(camera: ICEPerspectiveCamera): this;
     setBackgroundColor(color: string): this;
+    /**
+     * Section plane `[nx, ny, nz, d]`: fragments with `dot(world, n) + d < 0`
+     * are discarded. `null` (or a zero plane) disables clipping.
+     */
+    setClipPlane(plane: readonly [number, number, number, number] | null): this;
     prepareRenderBatchGeometry(geometry: ICEGeometry): this;
     releaseRenderBatchGeometry(geometry: ICEGeometry): this;
     prepareGeometry(geometry: ICEGeometry, update?: import('../core/index.js').ICEGeometryBufferUpdate): this;