引擎迁移
PlayCanvas Engine 不断演进，更新偶尔会引入破坏性变更，需要用户相应调整脚本。
本指南概述各版本的重要破坏性变更，帮助你将代码迁移到较新版本。有关版本号规则，以及如何控制项目接受哪些发布版本，请参阅版本编号与发布。
排查问题时，建议使用引擎的调试版本，它会记录已弃用 API 的提示、警告，以及错误用法引发的错误。
将当前和目标引擎版本提供给编程助手，使其能够对照本指南检查 API 用法。按照**借助 AI 开发**中的方式，使用调试版引擎逐组审查并测试相关修改。
从 2.4.0 迁移到 2.5.0
2.5.0 的破坏性变更
ShaderMaterial
ShaderMaterial 以前会自动向每个片元着色器注入所需代码，简化伽马校正、色调映射和雾效处理。此功能现已移除，各个着色器需要自行包含相关功能。
如果遇到缺少 gammaCorrectOutput、toneMap 或 addFog 等函数的着色器错误，请确保在着色器中显式包含所需函数。详情见此更新。
从 1.75.0 迁移到 2.4.0
从主版本 1 迁移到主版本 2 是一次较大的升级，包含多项破坏性变更。
破坏性变更
WebGL 1
已停止支持 WebGL1；引擎现在仅支持 WebGL2 和处于测试阶段的 WebGPU。如果应用依赖 WebGL1，需要继续使用引擎 v1。
AudioSourceComponent
此前已被 SoundComponent 取代的 AudioSourceComponent 现已完全移除。
旧版脚本
自 2016 年起被弃用、并已维持只读状态多年的旧版脚本系统，现在已完全移除。
已弃用函数
大量用于向后兼容的已弃用函数已被移除。如果应用在 Engine 1 的调试版本中出现弃用警告，应先解决这些问题，再迁移到 Engine 2。Engine 2 不再显示这些弃用警告，对应的兼容代码也已删除。
基础材质
BasicMaterial 已被移除。可以改用设置了自发光颜色或自发光贴图的 StandardMaterial，实现相同功能。
着色器材质
如果遇到 Material class cannot be instantiated, use ShaderMaterial instead 错误，需要将代码改为使用 ShaderMaterial。引擎着色器现在使用线性工作流，请注意片元着色器中如何使用 gammaCorrectOutput 进行最终伽马校正。
渲染到纹理
渲染到纹理时，在 Layer 上配置 RenderTarget 的旧方式已完全移除。现在必须直接在相机上设置 RenderTarget。
引擎渲染回调
以前，引擎会在每帧为相机和图层渲染执行多个回调。现在已改为支持多个订阅者的事件系统，新事件由 Scene 类发出。详情见此拉取请求。
StandardMaterial 颜色调制标记
StandardMaterial 的颜色调制选项曾存在含义不清且行为不一致的问题，因此 Ambient、Diffuse 和 Emissive 的调制标记已被移除。以前，这些标记仅在应用纹理等特定情况下生效；现在始终应用调制颜色。若要禁用调制，请将颜色设为中性值，即创建新材质时使用的默认颜色：
各类调制颜色的默认值如下：
- Ambient：
new Color(1, 1, 1)（白色）。 - Diffuse：
new Color(1, 1, 1)（白色）。 - Emissive：
new Color(0, 0, 0)（黑色）。
有一个需要注意的行为：为确保材质默认不发光，自发光调制颜色初始为黑色。分配自发光纹理后，应将自发光颜色设为白色，否则黑色调制会覆盖纹理的自发光贡献，使其无法显示发光效果。
视频纹理显示为黑色
如果视频纹理显示为黑色，请检查调试版引擎的警告。原因很可能是材质的自发光调制颜色为黑色。将自发光颜色改为白色即可修复。
伽马校正、色调映射和雾效设置
以前，gammaCorrection 和 toneMapping 在 Scene 上全局设置，影响所有相机的渲染。现在，这些设置直接位于各个相机上，可为不同相机配置独立的渲染效果。
以前，雾效通过 Scene.fog、Scene.fogColor 和 Scene.fogEnd 等 Scene 属性直接访问。现在，这些设置统一移到 Scene.fog 属性下，使用 Scene.fog.type、Scene.fog.color、Scene.fog.end 等属性配置。
详情见此拉取请求。
伽马空间纹理
Diffuse、Emissive、Specular 和 Sheen 等表示颜色的纹理通常存储在 sRGB 空间中，以保留颜色范围并减少色带。引擎使用它们时，会从 sRGB 转换到线性空间，以进行准确的光照计算。以前，该转换通过着色器运算完成，会影响性能。移除 WebGL1 支持后，可以利用硬件高效执行转换，无需额外开销。唯一要求是使用 sRGB 格式创建纹理：
- 加载表示 sRGB 颜色的 Texture 资源时，需要指定 sRGB 编码。详情见此拉取请求。
- 创建表示 sRGB 颜色的 Texture 实例时，需要使用
PIXELFORMAT_SRGBA8等 sRGB 像素格式。
实例化
如果代码修改了 transformVS 着色器块中的实例化部分，需要将相关定制移到 transformInstancingVS 中，并配置材质，指定使用了哪些顶点属性。详情见此拉取请求。
其他变更
各个引擎版本的详细变更，请查阅对应的版本说明：