ctx.sceneRender 在指定 DOM 容器中创建临时、隔离的场景实例。它不会改变玩家当前主舞台或存档状态,适合鉴赏大图和场景预览。

API

方法返回值说明
mount(container, layers, options?)Promise<SceneRenderHandle>渲染图层并返回清理句柄
每个图层支持 assetPathdistanceoffsetname;返回句柄提供幂等的 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);
输出:
function
#stage 中出现由两层素材组成的夜空天台场景,主游戏场景保持不变。关闭弹窗时调用 handle.dispose(),临时画布和引擎实例会被释放。
扩展必须在不再显示预览时调用 dispose(),否则临时渲染实例会继续占用图形和内存资源。