ice3 0.2.0 → 0.2.2

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.2`。
 
 本项目采用 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

@@ -21,6 +21,32 @@ export interface ICEPreparedMaterial {
     readonly id: string;
     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/ICEPreviewGeometryPacket.d.ts

@@ -0,0 +1,60 @@
+export type ICEPreviewGeometryBackend = 'cpu' | 'gpu';
+export type ICEPreviewGeometryResidencyMode = 'cpu' | 'cold' | 'warm' | 'resident' | 'snapshot';
+export type ICEPreviewGeometryRangeUsage = 'vertex_attributes' | 'indices';
+export interface ICEPreviewGeometryRange {
+    readonly byteOffset: number;
+    readonly byteLength: number;
+    readonly usage: ICEPreviewGeometryRangeUsage;
+}
+export interface ICEPreviewGeometryNode {
+    readonly nodeId: string;
+    readonly parentId: string | null;
+    readonly name: string;
+    readonly matrix: readonly number[];
+    readonly materialId: string | null;
+    readonly geometryId: string | null;
+    readonly visible: boolean;
+}
+export interface ICEPreviewGeometryRecord {
+    readonly geometryId: string;
+    readonly residentGeometryId: string | null;
+    readonly topologyDigest: string;
+    readonly attributeDigest: string;
+    readonly vertexCount: number;
+    readonly indexCount: number;
+    readonly indexWidth: 2 | 4;
+    readonly ranges: readonly ICEPreviewGeometryRange[];
+}
+export interface ICEPreviewGeometry extends ICEPreviewGeometryRecord {
+    readonly positions: Float32Array;
+    readonly indices: Uint16Array | Uint32Array;
+}
+export interface ICEPreviewGeometryMaterial {
+    readonly materialId: string;
+    readonly baseColor: readonly [number, number, number, number];
+    readonly metallic: number;
+    readonly roughness: number;
+    readonly opacity: number;
+}
+export interface ICEPreviewGeometryManifest {
+    readonly schemaVersion: number;
+    readonly transportVersion: number;
+    readonly revision: number;
+    readonly parentRevision: number | null;
+    readonly sourceDigest: string;
+    readonly backend: ICEPreviewGeometryBackend;
+    readonly residencyMode: ICEPreviewGeometryResidencyMode;
+    readonly nodes: readonly ICEPreviewGeometryNode[];
+    readonly geometries: readonly ICEPreviewGeometryRecord[];
+    readonly materials: readonly ICEPreviewGeometryMaterial[];
+    readonly removedNodeIds: readonly string[];
+    readonly removedGeometryIds: readonly string[];
+}
+export interface ICEPreviewGeometryPacket extends Omit<ICEPreviewGeometryManifest, 'geometries'> {
+    readonly geometries: readonly ICEPreviewGeometry[];
+    readonly binary: Uint8Array;
+}
+export type ICEPreviewGeometryDelta = ICEPreviewGeometryPacket;
+export declare function parsePreviewGeometryPacket(input: Uint8Array | ArrayBuffer): ICEPreviewGeometryPacket;
+export declare function applyPreviewGeometryDelta(base: ICEPreviewGeometryPacket, delta: ICEPreviewGeometryDelta): ICEPreviewGeometryPacket;
+//# sourceMappingURL=ICEPreviewGeometryPacket.d.ts.map

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

@@ -1,5 +1,8 @@
 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';
 export { readTileset } from './ICETilesetReader.js';
 export type { ICETilesetSnapshot, ICETilesetTile, } from './ICETileset.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -11,15 +11,21 @@ export interface ICEPerspectiveCameraOptions {
 export declare class ICEPerspectiveCamera {
     readonly id: string;
     readonly fov: number;
-    readonly near: number;
-    readonly far: number;
+    near: number;
+    far: number;
     private eye;
     private lookTarget;
     constructor(options: ICEPerspectiveCameraOptions);
     setPosition(position: ICEVector3Tuple): this;
     setTarget(target: ICEVector3Tuple): this;
+    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/geometry/ICEGeometry.d.ts

@@ -2,6 +2,18 @@ export interface ICEGeometryBounds {
     readonly min: readonly [number, number, number];
     readonly max: readonly [number, number, number];
 }
+export interface ICEGeometryIdentity {
+    readonly geometryId: string;
+    readonly topologyDigest: string;
+    readonly attributeDigest: string;
+}
+export interface ICEGeometryByteRange {
+    readonly byteOffset: number;
+    readonly byteLength: number;
+}
+export interface ICEGeometryBufferUpdate {
+    readonly positionRanges: readonly ICEGeometryByteRange[];
+}
 export interface ICEGeometry {
     readonly typeId: string;
     readonly positions: Float32Array;
@@ -9,6 +21,7 @@ export interface ICEGeometry {
     readonly edgeIndices?: Uint16Array | Uint32Array;
     readonly colors?: Float32Array;
     readonly semanticIndices?: Uint32Array;
+    readonly identity?: ICEGeometryIdentity;
     getBounds(): ICEGeometryBounds;
     toJSON(): Record<string, unknown>;
 }

package/dist/_types/core/geometry/ICEIndexedGeometry.d.ts

@@ -1,4 +1,4 @@
-import type { ICEGeometry, ICEGeometryBounds } from './ICEGeometry.js';
+import type { ICEGeometry, ICEGeometryBounds, ICEGeometryIdentity } from './ICEGeometry.js';
 export interface ICEIndexedGeometryOptions {
     readonly id: string;
     readonly positions: Float32Array;
@@ -6,6 +6,7 @@ export interface ICEIndexedGeometryOptions {
     readonly edgeIndices?: Uint16Array | Uint32Array;
     readonly colors?: Float32Array;
     readonly semanticIndices?: Uint32Array;
+    readonly identity?: ICEGeometryIdentity;
 }
 export declare class ICEIndexedGeometry implements ICEGeometry {
     readonly typeId = "ice3:IndexedGeometry";
@@ -15,6 +16,7 @@ export declare class ICEIndexedGeometry implements ICEGeometry {
     readonly edgeIndices?: Uint16Array | Uint32Array;
     readonly colors?: Float32Array;
     readonly semanticIndices?: Uint32Array;
+    readonly identity: ICEGeometryIdentity;
     constructor(options: ICEIndexedGeometryOptions);
     getBounds(): ICEGeometryBounds;
     toJSON(): Record<string, unknown>;

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

@@ -7,9 +7,9 @@ export { ICEBoxGeometry } from './geometry/ICEBoxGeometry.js';
 export type { ICEBoxGeometryOptions } from './geometry/ICEBoxGeometry.js';
 export { ICEIndexedGeometry } from './geometry/ICEIndexedGeometry.js';
 export type { ICEIndexedGeometryOptions } from './geometry/ICEIndexedGeometry.js';
-export type { ICEGeometry, ICEGeometryBounds } from './geometry/ICEGeometry.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,11 +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/WebGL2GeometryCache.d.ts

@@ -1,5 +1,9 @@
-import type { ICEGeometry } from '../core/index.js';
+import type { ICEGeometry, ICEGeometryBufferUpdate } from '../core/index.js';
 export interface GeometryEntry {
+    geometry: ICEGeometry;
+    readonly geometryId: string;
+    readonly attributeDigest: string;
+    readonly topologyDigest: string;
     readonly vertexArray: WebGLVertexArrayObject;
     readonly positionBuffer: WebGLBuffer;
     readonly triangleIndexBuffer: WebGLBuffer;
@@ -19,24 +23,34 @@ export declare class WebGL2GeometryCache {
     private readonly entries;
     private active;
     private readonly pinned;
+    private readonly objectKeys;
+    private readonly legacyKeys;
+    private objectKeySequence;
     private gl;
     private uploads;
+    private updatedBytes;
     private evictions;
     private frameId;
     private readonly inactiveGraceFrames;
     private readonly maxBytes;
     constructor(options?: WebGL2GeometryCacheOptions);
     retain(gl: WebGL2RenderingContext, geometry: ICEGeometry): Readonly<GeometryEntry>;
+    private createEntry;
     beginFrame(): void;
-    pin(gl: WebGL2RenderingContext, geometry: ICEGeometry): Readonly<GeometryEntry>;
+    pin(gl: WebGL2RenderingContext, geometry: ICEGeometry, update?: ICEGeometryBufferUpdate): Readonly<GeometryEntry>;
     unpin(geometry: ICEGeometry): void;
     endFrame(): void;
     clear(): void;
     dispose(): void;
     get totalBytes(): number;
     get uploadCount(): number;
+    get updateBytes(): number;
     get evictionCount(): number;
     private deleteEntry;
     private enforceBudget;
+    private applyPositionUpdate;
+    private canReuse;
+    private sameTopology;
+    private keyFor;
 }
 //# sourceMappingURL=WebGL2GeometryCache.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,4 +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;
@@ -10,14 +19,73 @@ export declare class WebGL2Program {
     private readonly colorLocation;
     private readonly clipOffsetLocation;
     private readonly vertexColorLocation;
+    private readonly directionalShadingLocation;
+    private readonly waterShadingLocation;
+    private readonly cameraPositionLocation;
+    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, 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;
     setInstancing(enabled: boolean): void;
+    setPickMode(enabled: boolean): void;
     dispose(): void;
     private createProgram;
     private compile;

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

@@ -11,6 +11,12 @@ export declare class WebGL2RendererBackend implements ICERendererBackend {
     private onContextLost;
     private onContextRestored;
     private program;
+    private clipPlane;
+    private shadowMap;
+    /** 方向光阴影开关：默认关闭，由 `initialize({ shadows })` 或页面地址 `?shadows=` 打开。 */
+    private shadowEnabled;
+    /** `?shadowdebug=1` 输出遮蔽判定，`=2` 输出深度图；排查阴影问题的唯一可信手段。 */
+    private shadowDebug;
     private semanticProgram;
     private geometryCache;
     private instanceCache;
@@ -25,17 +31,55 @@ 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;
     prepareBatchGeometry(geometry: ICEGeometry): void;
+    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