Changelog

本页内容由 VitePress 直接 include packages/engine/CHANGELOG.md，changesets 在每次发版时自动维护，无需手工编辑。

@tripo3d/engine

3.0.0

Major Changes

• 4afaafe: 发布 Engine 3.0：围绕 Three.js 原生对象重新设计 Engine、ECS、渲染管线、Pointer、History 和 Vue 集成。这是一次不提供 2.x 兼容层的破坏性升级。

  Engine 与渲染设备

  • createEngine() 现在同步创建并持有唯一 Canvas、原生 WebGLRenderer、默认 PerspectiveCamera、默认 World 和默认 RenderView；Engine 初始为 stopped，由业务把 engine.canvas 放入 DOM 后调用 engine.start()。
  • 使用 engine.start() / engine.stop() 控制帧循环，使用 engine.dispose() 执行不可逆的终态释放。删除 mount()、unmount() 和 remount 生命周期。
  • engine.renderer 直接暴露原生 Three.js WebGLRenderer，不再提供 Engine Renderer wrapper。默认 renderer 参数为 alpha: true、antialias: false，业务仍可通过 CreateEngineOptions.renderer 覆盖允许的原生参数。Canvas MSAA 与 Pipeline 离屏 MSAA 相互独立，不再自动推导或重复开启。
  • 新增固定 DPR、设备 DPR 与 [min, max] 设备 DPR 静态保护区间三种策略。pixelRatio 默认为 'device'，也可传入正数或 [min, max]。不提供基于运行时帧率自动切换 DPR 的 adaptive 策略，避免模型导入等掉帧触发 Canvas drawing buffer 重建。
  • Engine 自动观察 Canvas 尺寸；stopped 期间发生的尺寸变化会在下次 start() 时重新测量并提交。
  • Three.js 最低 peerDependency 提升为 >=0.183.0。

  ECS、World 与生命周期

  • Entity 是独立的 ECS 载体，并与一个原生 Object3D 保持一对一绑定。engine.createEntity() 创建绑定 Group 的浮动 Entity；engine.createEntity(root) 会一次性接纳并全量绑定 parentless raw Object3D 子树。
  • Object3D scene graph 是唯一层级事实。业务必须通过 Entity.add()、attach()、remove()、removeFromParent() 和 clear() 修改已接纳对象的层级；不再维护第二棵 Entity 树，也不支持通过原生 Object3D.add/remove/attach 修改已接纳层级后由 Engine 自动修复。
  • createComponent(name, setup)、Engine-global createSystem() 和 Entity-local createScript() 统一采用同步 setup Definition。Component setup 接收 { engine, entity, onDestroy }，每个 Entity 安装一次，并通过 addComponent() / getComponent() 原样返回 setup result；重复 add 幂等返回同一 identity。四类 Definition 接口统一为 structural type，不再保留旧 Component 的 nominal brand；规范 create* 工厂负责校验、默认值与冻结。
  • Entity Component API 统一为 addComponent()、getComponent()、hasComponent() 和 removeComponent()。Component presence 与 World Query 同步；remove/终态会先发布 absence，再按 LIFO 尽量执行全部 onDestroy，Component cleanup 位于 Script 之后、标准 Three.js 资源释放之前。
  • System 与 Script setup 提供 enabled、事件、resize、update、late-update 和 destroy 等生命周期登记能力。Component result 不支持 Promise/thenable、installation input 或整体 replacement；Engine 也不会自动调用 result 的 dispose()。
  • World membership 由 Entity 对应 Object3D 的 Scene ancestry 决定。Engine 提供默认 World，并支持 createWorld() / destroyWorld() 管理额外 World。
  • 新增 World-local lazy Query：使用 world.createQuery(component) 或组合 QueryDescriptor 查询当前 membership，不需要注册或手工释放 Query。
  • Entity.destroy()、World.destroy() 和 engine.dispose() 均为不可逆、幂等的终态操作。Entity 子树销毁会释放其当前引用的标准 Three.js geometry、material、texture 和 skeleton 资源，并在同一次终态操作内按 identity 去重。
  • 新增独立 disposeObject3D(root, { force? }) 工具，统一 Entity、World 与 Engine 终态的标准 Three.js 资源释放规则。默认保留 userData.shared === true 的资源，force: true 可显式忽略该保护。

  Pipeline 与 RenderView

  • 每个 Engine 内建并独占一个私有 EffectComposer、一个支持 Multi-View 的固定 DefaultMainPass 和一个固定 OutputPass。业务不能替换 main/output，也不接触 Composer identity 或内部 passes 数组。
  • Pipeline 只公开 after-render 和 after-output 两个业务阶段；默认 stage 为 after-render。同一 stage、同一执行 lane 内按 order 和注册顺序稳定执行，Pass Definition 与原生 Pass 的 enabled 共同决定本帧计划。
  • 默认 auto 输出模式固定执行 DefaultMain → after-render → OutputPass 上屏 → Canvas Pass，并忽略 after-output 的 Composer contribution。manual 模式让 OutputPass 写入 sRGB buffer，再执行 after-output；只有最终有效 Composer contribution 声明 present: true 才会上屏，缺少 presenter 时不 fallback，并在每个连续异常周期输出一次 warning。
  • PassContext.usePass(pass, options?) 是唯一借用入口：默认加入 Composer；present: true 声明 manual 模式的最终 presenter；target: 'canvas' 在 Composer 完成后直接操作默认 framebuffer，适合 Gizmo/HUD，且不产生隐式全屏复制。Pipeline 不接管借入 Pass 的资源，业务必须在 Definition 的 onDestroy() 中释放。
  • Composer 与 Canvas 是两条固定 lane。Engine 不分析、拒绝或修正跨 lane 顺序；业务负责保证最终 presenter 与直接 Canvas 绘制的组合语义有效。
  • 默认 RenderView 绑定默认 World 和默认 Camera。使用 pipeline.addView() 可组合多 World、多 Camera 和归一化 viewport；Camera 由业务创建并维护投影矩阵，Pipeline 只借用 Camera identity。
  • 新增 Pipeline render target 的 samples 和 stencil 配置。samples 默认 0，与 Canvas antialias 完全独立；因此默认路径关闭 Canvas MSAA、离屏 MSAA 和 resolve blit，业务可按需显式选择离屏 MSAA 或 FXAA。

  Pointer 与 Events

  • Pointer 直接基于当前帧有效 RenderView 和 Entity 候选执行 raycast。空间事件改为通过 entity.onPointer() 注册，并沿 Entity route 派发。
  • 使用 entity.pointerEvents 控制候选策略，使用 entity.pointerPriority 控制业务优先级。engine.pointer 公开 enabled、raycaster、hitTest()、onMissed() 和引用计数式 suspend()。
  • 新增 opaque createEvent() token，以及 Engine、System 和 Script context 上的类型化 emitEvent()、onEvent() 和 onceEvent()。内部 EventBus identity 不再作为公共 API 暴露。

  Plugin、History 与 Vue

  • Plugin 改为仅通过 createEngine({ plugins }) 构造期静态安装；删除运行期 engine.use() 和公开 Plugin 列表。Plugin setup 必须同步，Engine dispose 时按逆安装顺序调用 Plugin dispose。
  • History 从 Engine Core 中拆出为独立的 @tripo3d/engine/history 子入口。createHistory() 提供异步 execute()、undo()、redo() 和 transaction；需要 Engine 销毁时自动清栈时，将 createHistoryPlugin(history) 加入静态 plugins。
  • Vue 集成从 @tripo3d/engine/vue 导出 Canvas 和 createPluginVue()。Canvas 接纳 Engine Canvas、自动 start，并在 prop replacement 或组件卸载时 stop、dispose 和移除 Canvas；默认 overlay 保持 pointer-events: none。
  • createPluginVue() 只对 Engine 构造期已经存在的关键 Three.js/Engine identity 执行 markRaw()。后续创建的 Three.js 对象、Component/System/Script setup result 或业务状态不会被自动 reactive、Proxy 或 markRaw，由业务在进入 Vue 响应式边界前自行决定。

  从 2.x 迁移

  • engine.mount(target) / engine.unmount() → 业务插入 engine.canvas 后调用 engine.start() / engine.stop()；Vue 项目可使用新的 Canvas 组件托管 DOM 与终态释放。
  • engine.renderer wrapper → 原生 WebGLRenderer；旧的 renderer frame hooks、显示相机列表和 mount API 没有直接兼容入口。
  • engine.createEntityTree(root) → engine.createEntity(root)；engine.getEntityByObject(object) → engine.getEntity(object)。
  • 旧 Entity 子节点 API → add() / attach() / remove() / clear()；旧 Component typed-key API → createComponent(name, setup) 与 addComponent() / getComponent() / hasComponent() / removeComponent()。
  • engine.createCamera() / createCamera() / createView() → 业务直接创建原生 Three.js Camera，并通过 pipeline.addView({ camera, world, viewport }) 注册 RenderView。
  • engine.events → createEvent() 加 engine.emitEvent() / onEvent() / onceEvent()。
  • engine.history → 从 @tripo3d/engine/history 创建独立 History；如需随 Engine 清栈，安装 createHistoryPlugin(history)。
  • engine.lifecycle、engine.systems 和 engine.scripts 不再公开。生命周期在 createSystem() / createScript() setup context 中登记，System 通过 Engine API 管理，Script 通过 Entity API 管理。
  • 旧 Pipeline composer、sceneRenderPass、onRender、replaceMainPass 和 pipeline.clear() 不再公开。改用 after-render / after-output 两阶段 createPass() Definition、PassContext.usePass() 与 auto / manual 输出模式；Gizmo/HUD 使用 target: 'canvas'。
  • disposeObject3D() 不再公开。Engine 只释放 Engine-owned Entity 子树发现的标准 Three.js 资源；业务创建并借给 Engine 的 Camera、Pass 及未接纳资源仍由业务释放。
  • createStateCell()、isBrowser()、独立 camera/view factories，以及 manager、runtime 和内部 adapter 类型已从公共入口移除。源码 deep import 不受支持。

2.3.0

Minor Changes

• 8b05df9: - @tripo3d/engine: 重构 pipeline 为按 order 排序的单链 pass 模型，新增 createPass/sceneRenderPass 与 removePass，移除 stage 相关 API 及 PipelinePass 系列类型，addPass 改为返回实例 T；disposeObject3D 增加 options（force/skip 共享资源）

2.2.0

Minor Changes

• e129708: - @tripo3d/engine: 重构指针系统，新增实体级 pointer capture、三态 pointerEvents 与 order 继承及 wheel/pointercancel 等事件；PointerEventFamily 移除 activate 成员（破坏性）
  • @tripo3d/assimp: 新增 vite 插件 tripoAssimp 与 baseUrl 选项托管 worker/wasm 资源，createAssimpConverter 改为全局单例

2.1.0

Minor Changes

• 7f24712: - @tripo3d/engine: 新增 defineEvents —— 为共享事件总线提供类型安全视图的 helper。
  • defineEvents<T>(engine) 把全引擎共享、未带泛型的 engine.events 在类型层投影为 TypedEventBus<T>，直接复用 @tripo3d/utils 的 EventBus 全量方法面（on/once/off/emit/has/clear），按事件映射 T 类型化供外部消费；不重复声明总线方法面。入参取整个 engine 实例（而非 engine.events），便于在 system 的 setup 内直接 defineEvents(engine)。
  • TypedEventBus<T> 经同态映射 { [K in keyof T]: T[K] } 包装满足 EventBus 的 Record 约束，故事件映射用 interface 或 type 声明均可，且事件名收窄与载荷类型推导不丢。
  • 运行时即原总线本身（零额外开销），仅在类型层做投影；事件天然按 system 划分命名空间，typed view 通常在 system 的 setup 内创建后对外暴露。
  • 释放由调用方自管：on/once 返回解绑函数，订阅方在自身生命周期内自行解绑；引擎 dispose 时 engine.events.clear() 兜底。
• 7f24712: - @tripo3d/engine: ECS 的 setup/context 钩子机制对称化重构（破坏性）。
  • 统一钩子注册：script 改为从 context 注册器登记钩子（ctx.onUpdate(cb) / ctx.onAwake(cb) 等），setup 返回纯状态 T（不再返回 T & ScriptHooks）；component（onDispose）与 system（onAwake/onEnable/onDisable/onDestroy）统一复用同一收集原语（新增内部 createHookRegistration / runHooks，钩子规格 Spec 派生 bag/registrars）。同一钩子可注册多次，按注册序触发。
  • 收窄 context 冗余：SystemContext 删去 events / history / lifecycle / pipeline（统一经 engine.* 取）；ComponentContext / ScriptContext 删去 object（经 entity.object 取）。
  • 类型收窄：entity.addScript / getScript 返回 T（原 T & ScriptHooks）；PluginScriptContext / applyScriptPlugins 的实例为纯 T；ScriptHooks 下线为内部钩子袋类型（不再公开导出），删除零消费的 CallbackHookName / FrameHookName。
  • 设计契约：脚本帧钩子无 order（脚本是实体局部行为）。跨脚本 / 跨模块的确定执行顺序请用 system（带 order）或事件解耦，不依赖脚本间执行序。

2.0.0

Major Changes

• 1c803c1: - @tripo3d/engine: 重写引擎为 v2，公共入口改为显式 allowlist，移除顶层 pointer 导出，统一经 createEngine 接线 world/camera/view/renderer

1.1.0

Minor Changes

• 70f4f05: - @tripo3d/engine: 新增 removeSystem 方法，支持按定义动态卸载并释放单个系统的生命周期订阅与清理回调

1.0.0

Major Changes

• cc7084b: - @tripo3d/utils: 新增通用事件总线 createEventBus 及 EventBus/EventHandler/DefaultEventMap 类型导出，支持泛型事件映射与 once
  • @tripo3d/engine: 移除内置 createEventBus 与 EngineEventBus/EngineEventHandler 类型导出，Engine.events 改用 @tripo3d/utils 的 EventBus

Patch Changes

• Updated dependencies [cc7084b]
  • @tripo3d/utils@0.4.0