跳到主要内容

脚本属性

脚本属性用于定义脚本公开且可配置的接口。你可以暴露特定参数，在通过代码实例化和配置脚本时设置，或通过 PlayCanvas 编辑器可视化调整。这意味着只需编写一次脚本，就能为不同实例或团队成员调整行为和属性。

为什么使用脚本属性？​

  • 明确的公开接口：正式定义脚本中允许定制的部分，提升代码清晰度和可维护性。
  • 可选的编辑器集成：属性会显示为检查器面板中的可编辑字段，美术、设计师和其他开发者无需查看代码即可配置。
  • 代码配置：通过代码创建或管理实体与脚本组件时，可直接设置属性初始值，实现灵活的动态配置。
  • 复用：创建通用脚本，例如移动脚本，再为不同实体调整速度、方向、目标等属性，可以在编辑器或代码中完成。
  • 协作：非程序岗位的团队成员也能调整玩法、角色数值和视觉属性。
  • 快速迭代：在编辑器中修改数值，或在代码中修改初始化参数，快速测试不同配置。

工作方式​

在脚本中声明属性，相当于定义一个可以初始化和修改的字段。

  • 代码中：为 Script 组件添加脚本时设置属性值，或在运行时通过脚本实例修改。
  • 编辑器中：编辑器解析脚本文件，在 Inspector 中生成数字输入框、复选框、拾色器和资源选择器等控件，让你为各个脚本实例设置属性值。

例如，在旋转脚本中暴露 speed，编辑器中就会显示数字字段。在代码中，可在 initialize 内设置 this.speed = 5;，或配置实体时设置 entity.script.myScript.speed = 5;。这样，同一脚本逻辑可通过可视化或代码配置，为不同对象设置不同旋转速度。

两套系统：ESM 与经典脚本​

PlayCanvas 为两种脚本方式提供对应的属性定义系统：

  1. ESM 脚本属性：用于现代 ES 模块（.mjs）脚本，通常在类成员上方通过 JSDoc 注释声明。推荐新项目使用。
  2. 经典脚本属性：用于较早的经典 .js 脚本，通过 MyScript.attributes.add(...) API 声明。

两者都旨在定义可配置接口，但语法和部分能力有所不同。点击上述链接查看具体用法。

无论使用编辑器可视化工具，还是完全通过代码构建场景，理解并使用脚本属性都有助于创建灵活、易维护且便于协作的 PlayCanvas 项目。