PlayCanvas引擎中ESM脚本属性创建方案解析

PlayCanvas引擎团队近期针对ESM脚本中属性创建的问题进行了深入讨论，本文将从技术角度全面解析该问题的背景、解决方案及最佳实践。

问题背景

在PlayCanvas引擎中，脚本组件传统上使用create()方法来实例化带有属性的脚本。这种方式依赖于预先定义的属性模式（attribute schema），但在纯引擎环境下（无编辑器支持），ESM脚本使用JSDoc标签定义模式，导致无法直接设置脚本属性。

当前开发者必须分两步操作：

const script = scripts.create('scriptName');
script.myNum = 1;

这种分离的写法不够优雅，团队希望实现属性在脚本创建时就能直接设置。

解决方案探讨

团队提出了三种主要解决方案，各有优缺点：

方案1：复用attributes属性

scripts.create('scriptName', { attributes: { myNum: 1 }})

优点：API简单，复用现有接口 缺点：编辑器与引擎行为不一致；语义上attributes在纯引擎中并不真正存在

方案2：专为引擎设计的新方法

scripts.createWithProperties('scriptName', { myNum: 1 })

优点：行为明确，不重载attributes概念 缺点：增加新方法可能导致混淆

方案3：新增properties属性

scripts.create('scriptName', { properties: { myNum: 1 }})

优点：单一方法，清晰区分attributes和properties 缺点：增加额外属性

技术决策与实现

经过深入讨论，团队最终达成以下技术共识：

1. 统一API设计：采用单一create()方法，同时支持attributes和properties参数，但行为不同：

   • attributes：仅在模式存在时有效，否则警告
   • properties：总是赋值，不考虑模式

2. 类型安全考虑：在编辑器环境中，类型验证应提前进行，避免运行时错误。建议采用scripts.add(new Class(data))方式，便于编辑器进行类型检查。

3. 属性复制策略：默认使用Object.assign进行浅拷贝，开发者可自行决定是否需要深拷贝。

最佳实践建议

对于不同场景的开发者：

编辑器用户

// 依赖编辑器类型检查
scripts.add(new MyScript({
  vertex: shaderAsset,
  fragment: anotherShader,
  depthTest: true
}));

纯引擎用户

// 直接设置属性
const script = scripts.create('MyScript', {
  properties: {
    speed: 10,
    color: new Color(1, 0, 0)
  }
});

// 或者分步设置
const script = scripts.create('MyScript');
script.speed = 10;
script.color = new Color(1, 0, 0);

技术展望

这一改进为PlayCanvas脚本系统带来更灵活的属性管理方式，特别是对纯引擎用户更加友好。未来可能会进一步优化：

1. 增强类型系统支持
2. 提供更丰富的属性复制策略
3. 改进脚本序列化/反序列化能力

通过这次改进，PlayCanvas在保持向后兼容的同时，为现代JavaScript模块化开发提供了更好的支持。