nixie-fx-runtime

NixieFX 运行时

集成生成的 out/vfx 工件。不要在游戏中直接加载创作项目文件。

工作流

1. 确认宿主渲染器、其渲染循环、资源管线、摄像机或投影方式，以及清理生命周期。

2. 仅安装所选的可选对等依赖：

   npm install nixie-fx three
   # or
   npm install nixie-fx pixi.js
   

3. 阅读 export-bundles.md，并通过 nixie-fx/export（loadVfxExportBundle）加载完整的编译包。

4. 除非任务要求同时使用两者，否则只阅读一份后端指南：

   • Three.js（标准后端）：three.md
   • PixiJS（UI / 2D 场景）：pixi.md

5. 通过由宿主应用拥有的注入式提供方解析纹理、材质图、网格和子特效。

6. 创建渲染器和特效实例，然后在每个宿主帧中恰好更新渲染器一次。

7. 展示清单支持报告和运行时缺失资源统计。不要默默地将部分行为或缺失行为视为完整实现。

8. 在宿主作用域结束时，销毁实例、渲染器拥有的对象以及提供方资源。

包边界

仅使用公开入口：

• nixie-fx，用于与后端无关的契约和支持数据。
• nixie-fx/pixi，用于 PixiJS 集成。
• nixie-fx/three，用于 Three.js 集成。
• nixie-fx/materials，用于材质图契约。
• nixie-fx/export，用于浏览器安全的导出架构和加载。
• nixie-fx/export/node，仅用于 Node 文件系统导出工具。

绝不要深层导入 nixie-fx/src/**、将运行时源代码复制到使用方，或导入未使用的渲染器后端。

其他引擎

导出格式是与引擎无关的 JSON，官方运行时适用于 Three.js 和 PixiJS。当项目面向其他引擎时，不要强行接入这些适配器之一：共享模拟（仓库中的 src/engine/particles.ts）与渲染器无关，而 Three 适配器的源代码足够精简，可作为移植的参考实现。

运行时规则

• 由游戏负责管理应用、场景、摄像机、时钟、URL、缓存和错误报告。
• 在生成特效前预加载异步资源；渲染过程中使用的提供方 getter 必须是同步的。
• 调用一次 renderer.update(deltaSeconds)。同一帧中不要再调用 instance.update(deltaSeconds)。
• 将创作时的路径视为相对于资源包的查找键，并在宿主提供方中将其映射到 URL 或图集帧。
• 需要确定性播放时使用稳定种子。
• 暂停或销毁未激活的运行时；隐藏的场景不得持续更新。
• 对于 Three.js 性能优化，请检查每个发射器的绘制次数，并将公开的 ThreeVfxBatcher 集成到宿主最终透明物体排序流程中。请阅读 three.md 中的批处理部分。仅共享材质不会合并绘制；目前提供自定义材质会禁用默认的实例化快速路径。
• 在目标渲染器中观察到真实导出的特效之前，不要声称其与编辑器表现一致。

完成检查

• 无需安装另一个对等依赖，即可成功导入所选后端。
• 加载器接受清单、必需的特效 ID 和所选后端。
• 没有清单条目因所选后端而受阻。
• 纹理、材质图、网格和子特效均可解析，且没有缺失引用统计。
• 模拟每帧推进一次，并在拆卸后停止。
• 已在真实宿主应用中检查特效的视觉效果。