vis-core 0.33.16 → 0.33.18

package/README.md

@@ -1,25 +1,21 @@
 # vis-core
 
-## 提前初始化 GPU
+运行时使用 ZIP 分包：`manifest.json` 引用场景 JSON 和独立资源文件，场景沿用 Three.js 的 `images`、`textures`、`materials` 结构；`images[].url` 直接写相对文件路径（立方体贴图为路径数组），纹理保留原生采样参数。SHA-256、MIME、文件大小及 HDR／像素解码信息统一放在 `manifest.assets`。平台预览使用同一分包结构，资源文件保存在 IndexedDB。
 
-`SceneManager` 首次读取 URL 模板时，会先发出网络请求，再自动预热实际渲染器。现有 `load(url)`、`loadMapRegion(url, ...)` 和 `requestMapRegion(url, ...)` 调用无需修改。内存文档不会自动预热。
+平台导出明确选择用途，默认“固定场景展示”：使用保存的地图和城市几何，不重复打包行政边界或建筑、道路、河流、绿地源数据；支持已保存场景之间的 `switchScene`，禁止运行时切换区域或重建。含区域切换交互的项目需要改选动态模式或移除该交互。未完成几何创建的对象仍会收集初始化所需资源。
 
-宿主已经确认即将展示场景时，也可以更早调用：
+“支持运行时区域切换”需要配置根区域、最深层级，以及各层级使用的地图场景模板；同一模板可以用于多个层级。导出按照这份配置枚举目标区域，收集所选模板重建需要的行政边界和城市数据；未选作模板的场景仍按固定场景保存。数据可随 ZIP 打包，或显式选择由宿主部署共享目录。
 
-```ts
-const manager = new SceneManager({ container });
-void manager.prewarmRuntime().catch(error => {
-  // 预热是可选优化；正式加载仍可重新尝试初始化。
-  console.debug('GPU 预热未完成', error);
-});
+配置保存在 `manifest.json` 的 `runtimeAssets.mapNavigation`，`runtimeAssets.regions` 列出每个模板允许切换的行政区。宿主调用 `manager.switchMapRegion(templateSceneId, adcode)`、`loadMapRegion` 或 `requestMapRegion` 时必须使用配置内的模板和区域；超出范围会在创建场景前报错，`strictBundleAssets: false` 也不会放开范围。SDK 不会根据未来的宿主调用自动扩大导出范围。预览沿用同一配置，自定义脚本也不能突破该范围，脚本额外请求的文件仍需登记。重新导出会移除旧包中不再需要的原始地理数据。
 
-// 稍后需要展示时，复用预热中的或已就绪的上下文。
-await manager.load(templateUrl);
+平台上传的普通图片直接编码为 WebP 文件；HDR/TGA 保留原文件，加载时解码。模型贴图使用无损 PNG，程序生成或修改后的数据纹理保存原类型的二进制像素文件。保存、撤销重做、预览和 ZIP 导出均保留文件字节，不再把新图片转换为 Base64。视频同样保留 MP4/WebM 等原文件，JSON 仅保存文件引用和采样参数；ZIP 使用 `assets/video-<sha256>.<ext>`，相同内容只存一份。播放时按文件引用创建临时 Blob URL，在最后一个使用者释放视频时回收，支持后续定位和循环播放。
 
-// 页面卸载时，也会释放尚未被场景接管的预热上下文。
-manager.dispose();
-```
+平台内部的历史快照和增量保存快照使用原生资源路径；文件字节与解码元数据由每个编辑器的 `ProjectResourceRepository` 仓库管理。当前文档、撤销栈和重做栈共同决定资源保留，事务完成后才回收无引用文件；历史容量也计入保留的资源字节。排队保存与草稿持有独立文件引用，清空历史或关闭编辑器不会破坏已捕获的保存任务。渲染适配器及独立 SDK 导入／导出文档仍可使用临时 `ArrayBuffer` 解码描述，不能直接 `JSON.stringify` 当作项目存档。平台项目使用 `ProjectBundleWriter` 拆分 JSON 和资源，保存为 `vis-project` schema 3；运行时导出使用 `splitSceneDocument(document)`，将返回的 `manifest`、`scenes` 和 `assets` 一起写入 ZIP。SDK 使用 `SceneManager.load(zip)` 加载。
 
-每个 manager 独立持有预热状态，重复调用共用初始化 Promise。预热只初始化渲染器，不读取场景、展开材质、挂载 canvas 或启动渲染循环；首次场景按最终配置接管同一个渲染器。模板或钩子修改了深度、后端等渲染器配置时，不兼容的预热实例会释放，按最终配置重新创建。WebGPU 降级及深度精度策略与普通加载相同。
+旧大 JSON/gzip 项目由平台导入入口转换。新 ZIP 中的二进制纹理描述需要新版 gl-draw 与 vis-core；部署时同步更新 SDK。
 
-预热失败或未使用的设备丢失后可以重试。预热不能消除 GPU 冷启动成本，也不会把同步 WebGL 初始化移入后台线程；收益来自更早启动，以及与模板下载等等待重叠。测量时应分别记录预热耗时和后续加载耗时。
+例如场景图片为 `{ "uuid": "image-uuid", "url": "assets/image-<sha256>.webp" }`；manifest 5 中对应 `assets["assets/image-<sha256>.webp"] = { "sha256": "<sha256>", "bytes": 12345, "mimeType": "image/webp", "kind": "image" }`。普通图片路径可由 Three.js 原生 ObjectLoader 配合资源目录直接加载。HDR/TGA 和原始数据纹理由 SDK 根据 manifest 解码；解码描述仅供加载和运行时适配使用，不进入平台历史快照或保存的场景 JSON。相同像素字节有不同宽高／类型时使用不同路径描述布局，底层云端文件仍按 SHA-256 共享。
+
+SDK 仅接受当前场景 schema 6 和运行清单 schema 5，旧资源池和旧清单的迁移只在平台导入入口执行。`packSceneDocumentResources`、`expandSceneDocumentResources` 和 `ScenePackingCache` 已移除。普通所有权拷贝使用 `cloneSceneDocument`。
+
+平台模板、物体库和跨项目复制均使用含 `manifest.json` 与 `files/<sha256>` 的可编辑 ZIP；模板包括静态资源包和项目设置，复制包只携带选中资产的依赖。`ProjectResourceRepository` 统一管理媒体、地图数据、长脚本与静态资源包，历史差异仅持有路径。