ctx.sceneRender 在指定 DOM 容器中创建临时、隔离的场景实例。它不会改变玩家当前主舞台或存档状态,适合鉴赏大图和场景预览。
API
| 方法 | 返回值 | 说明 |
|---|
mount(container, layers, options?) | Promise<SceneRenderHandle> | 渲染图层并返回清理句柄 |
每个图层支持 assetPath、distance、offset 和 name;返回句柄提供幂等的 dispose()。
案例:在鉴赏弹窗中预览夜空场景
输入: 页面中有一个空容器 stage,项目包含背景图和前景图。
const stage = document.querySelector<HTMLElement>("#stage");
if (!stage) throw new Error("缺少 #stage 容器");
const handle = await ctx.sceneRender.mount(
stage,
[
{ assetPath: "images/scenes/night-sky.png", distance: 4, name: "天空" },
{ assetPath: "images/scenes/rooftop.png", distance: 1, name: "天台" },
],
);
console.log(typeof handle.dispose);
输出:
#stage 中出现由两层素材组成的夜空天台场景,主游戏场景保持不变。关闭弹窗时调用 handle.dispose(),临时画布和引擎实例会被释放。
扩展必须在不再显示预览时调用 dispose(),否则临时渲染实例会继续占用图形和内存资源。