iflow-engine-base 4.0.11 → 4.0.13

package/dist/index.d.ts

@@ -2073,8 +2073,6 @@ declare class ComposerModule_2 {
     get composer(): RenderPipeline | null;
     /** 返回持久化的 WebGPU RenderPipeline。 */
     get renderPipeline(): RenderPipeline | null;
-    /** 后期效果之外的背景场景，供天空等无限远背景使用。 */
-    get postProcessingBackgroundScene(): Scene;
     /** 后期效果之外的叠加场景，供剖切面和交互辅助对象使用。 */
     get postProcessingOverlayScene(): Scene;
     /** 返回当前 SSGI 节点。 */
@@ -4030,10 +4028,10 @@ export declare interface EngineKernelV3Options {
         meshDistanceCullingEnabled?: boolean;
         /** 是否对 InstancedMesh 开启距离裁剪，默认开启。 */
         instanceDistanceCullingEnabled?: boolean;
+        /** 相机交互期间实例距离裁剪的更新间隔（毫秒）；设为 0 可恢复逐帧计算，默认 100。 */
+        instanceDistanceCullingUpdateIntervalMs?: number;
         maxTrianglesPerMesh?: number;
         minProjectedSizePx?: number;
-        /** Instance 空间批次最大中心半径与实例直径之比；值越小局部恢复越准确，批次数也越多。 */
-        maxInstanceBatchRadiusSizeRatio?: number;
     };
     /** 默认开启批次深度偏移以缓解共面闪烁；确认模型不存在 z-fighting 时可显式关闭。 */
     modelDepthBias?: boolean;
@@ -5661,15 +5659,19 @@ declare class Ground_2 {
     private groundMesh;
     /** 当前为官方 Water 水面时为 true，用于 update/dispose 分支 */
     private isWaterAddon;
+    /** 未显式配置太阳方向时，使水面高光跟随场景主定向光。 */
+    private syncWaterSunDirection;
     private groundY;
-    /** 默认水面法线贴图路径（项目内为 public/textture/waternormals.jpg） */
+    private readonly lightWorldPosition;
+    private readonly lightTargetWorldPosition;
+    /** 官网案例使用的水面法线贴图。 */
     private static readonly DEFAULT_WATER_NORMALS;
     private groundList;
     constructor(engine: any);
     init(): void;
     /**
      * 切换地面类型
-     * @param id  地面 id："0" 无 | "1" 草地 | "2" 混凝土 | "3" 地砖 | "4" 湖面 | "5" 海面
+     * @param id 地面预设 ID，其中“13”为湖面，“14”为海面。
      */
     setGround(id: GroundId_2, config?: GroundConfig_2): void;
     /**
@@ -5679,7 +5681,7 @@ declare class Ground_2 {
     setHeight(y: number): void;
     /** 获取当前地面高度 */
     getHeight(): number;
-    /** 每帧调用，驱动水面动画并与场景阳光/相机同步 */
+    /** 每帧同步场景主光；水面动画和相机位置由 TSL 节点自动更新。 */
     update(): void;
     /** 获取地面列表（id + 名称） */
     getGroundList(): Array<{
@@ -5692,13 +5694,11 @@ declare class Ground_2 {
     show(): void;
     hide(): void;
     dispose(): void;
-    /**
-     * 兼容项目内本地 three 渲染器。
-     * 本地渲染器会向 lights uniforms 写入 directional/spot/point 的 shadowMap，
-     * 但 npm Water 使用的 three 版本没有把这些 sampler 挂到 UniformsLib['lights'] 上。
-     */
-    private ensureWaterShadowUniforms;
     private _dispose;
+    /** 计算从定向光目标指向光源的单位向量，作为水面的太阳方向。 */
+    private getSceneSunDirection;
+    /** 水面可见时关闭空闲限帧，保证 TSL 时间节点持续产生平滑波纹。 */
+    private updateWaterFrameRateExemption;
 }
 
 declare interface GroundConfig {
@@ -5719,25 +5719,39 @@ declare interface GroundConfig {
 }
 
 declare interface GroundConfig_2 {
-    /** 地面尺寸（默认 300） */
+    /** 地面尺寸；水面默认 10000，其他地面默认 30000 */
     size?: number;
     /** 贴图 URL（仅实体地面有效） */
     textureUrl?: string;
     /** 阳光方向（默认斜上方） */
     sunDirection?: THREE.Vector3;
-    /** 水面透明度（默认 0.82） */
+    /** 水面透明度，范围 0 至 1（默认 0.92） */
     opacity?: number;
     /** 水面法线贴图 URL（默认使用 public 下的 waternormals.jpg） */
     waterNormalsUrl?: string;
+    /** @deprecated 官网 WaterMesh 方案只使用一张法线贴图。 */
+    waterNormalsUrl2?: string;
+    /** 水体颜色，默认与官网案例一致为 0x001e0f */
+    waterColor?: THREE.ColorRepresentation;
+    /** 太阳光颜色，默认与官网案例一致为白色 */
+    sunColor?: THREE.ColorRepresentation;
     /** 水面反射扭曲强度，覆盖预设 */
     distortionScale?: number;
     /** 水面波纹密度（size uniform），覆盖预设 */
     waterSize?: number;
+    /** 反射通道的分辨率倍率，默认与官网 WaterMesh 一致为 0.5 */
+    resolutionScale?: number;
+    /** @deprecated 官网 WaterMesh 方案不使用定向水流。 */
+    flowDirection?: THREE.Vector2;
+    /** @deprecated 官网 WaterMesh 方案由内置 time 节点驱动波纹。 */
+    flowSpeed?: number;
+    /** @deprecated 官网 WaterMesh 使用固定的菲涅尔基础反射率。 */
+    reflectivity?: number;
 }
 
-declare type GroundId = "0" | "1" | "2" | "3" | "4" | "5";
+declare type GroundId = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "12" | "13" | "14";
 
-declare type GroundId_2 = "0" | "1" | "2" | "3" | "4" | "5";
+declare type GroundId_2 = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "12" | "13" | "14";
 
 /** GTAO 参数。 */
 export declare interface GTAOPostProcessingSettings {
@@ -5814,7 +5828,6 @@ declare class Hdr_2 {
     private currentBackgroundIntensity;
     private currentTexture;
     private currentEnvironmentTexture;
-    private skybox;
     private readonly textureCache;
     private previousBackground;
     private previousEnvironment;
@@ -5840,9 +5853,6 @@ declare class Hdr_2 {
     private _loadHdr;
     private _applyTexture;
     private _captureSceneState;
-    private _createSkybox;
-    private _updateSkyboxIntensity;
-    private _removeSkybox;
     private _clearHdr;
     private _getAmbientLightIntensity;
     private _setAmbientLightIntensity;
@@ -7592,6 +7602,8 @@ declare class LoaderModule_2 {
     private engine;
     private unloadedModelUrls;
     private modelLoadVersions;
+    private hasTriggeredInitialHome;
+    private homeBoundingBox;
     constructor(engine: any);
     /**
      * 批量加载模型 URL。
@@ -7617,10 +7629,18 @@ declare class LoaderModule_2 {
     isModelUnloadRequested(url: string): boolean;
     /** 校验异步任务是否仍属于当前 URL 的最新一次加载。 */
     isModelLoadActive(url: string, loadVersion: number): boolean;
+    /** info 已读取并登记模型包围盒后立即判断是否需要回正相机。 */
+    onModelInfoReady(): void;
     /** 清理模型运行状态数组，避免交互继续引用已卸载构件。 */
     private clearEngineStatus;
     /** 删除模型组缓存；对象索引种子保持单调递增，避免复用旧索引。 */
     private removeModelGroupReference;
+    /** 判断当前所有模型的最外层包围盒是否需要触发一次 Home。 */
+    private shouldTriggerHomeForCurrentModels;
+    /** 卸载后重新计算缓存，避免已删除的大模型范围继续阻止后续 Home。 */
+    private refreshHomeBoundingBoxAfterUnload;
+    /** 将 OctreeBox 返回的全场景范围转换为独立 Box3，避免引用后续被修改。 */
+    private getCurrentModelBoundingBox;
     /**
      * 把浏览器 File 列表整理成现有加载器可识别的本地虚拟模型入口。
      */
@@ -13193,9 +13213,13 @@ declare class SkyManager_2 {
     /** 设置天空生成的 IBL 环境光强度。 */
     setIntensity(intensity: number): void;
     getIntensity(): number;
-    /** 在渲染前让天空跟随相机，避免大世界坐标精度损失。 */
+    /** 在渲染前让天空球跟随相机，避免大世界坐标精度损失。 */
     update(_time?: number): void;
-    private _getBackgroundScene;
+    /**
+     * SkyMesh 默认立方体会让 positionWorld 在面边界产生可见插值差异。
+     * 保留其 WebGPU/TSL 材质，只将几何数据替换为连续球面。
+     */
+    private _createSeamlessSky;
     private _syncSkyToCamera;
     private _isOrthographicCamera;
     private _getEffectiveExposure;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iflow-engine-base",
-  "version": "4.0.11",
+  "version": "4.0.13",
   "description": "BIM Engine SDK for Vue2, Vue3, React and HTML",
   "main": "./dist/bim-engine-sdk.umd.js",
   "module": "./dist/bim-engine-sdk.es.js",