ESM 脚本

ESM 脚本使用现代 ES 模块语法，是推荐的 PlayCanvas 脚本编写方式。它提供更好的代码组织、静态导入和打包支持，也更符合现代 JavaScript 开发者的习惯。

为什么选择 ESM 脚本？

• 现代 JavaScript：使用类、箭头函数和解构等 ES6+ 特性。
• 更完善的工具支持：更好的 IDE 自动补全和错误检测。
• 模块化代码：在脚本之间导入和导出功能。
• 性能优化：静态导入便于打包和移除未使用代码。
• 面向未来：基于持续演进的 Web 标准。

创建 ESM 脚本

ESM 脚本必须使用 .mjs 扩展名：

1. 在资源面板中新建脚本。
2. 使用 .mjs 扩展名命名，例如 PlayerController.mjs。
3. 编辑器会生成 ESM 脚本框架。

import { Script } from 'playcanvas';

export class PlayerController extends Script {
    static scriptName = 'playerController';

    initialize() {
        // Setup code here
    }

    update(dt) {
        // Frame update code here
    }
}

提示

一个文件可包含多个脚本：单个 .mjs 文件可以导出多个脚本类，但每个类都必须显式导出，编辑器才能使用。

模块导入与导出

使用标准 ES 模块语法在脚本之间共享代码：

// config.mjs - Shared configuration
export const GAME_SETTINGS = {
    playerSpeed: 5,
    jumpHeight: 10,
    gravity: -9.8
};

export function clamp(value, min, max) {
    return Math.min(Math.max(value, min), max);
}

// PlayerController.mjs - Using shared code
import { Script } from 'playcanvas';
import { GAME_SETTINGS, clamp } from './config.mjs';

export class PlayerController extends Script {
    static scriptName = 'playerController';

    update(dt) {
        const speed = GAME_SETTINGS.playerSpeed;
        // Use clamp function...
    }
}

注册脚本（仅使用引擎时）

在编辑器中，加载 .mjs 资源时会自动注册 ESM 脚本。仅使用引擎的项目没有资源流程代为处理，因此按名称将脚本附加到实体前，必须自行向应用的 ScriptRegistry 注册每个脚本类。

使用 registerScript，或注册表的 add 方法注册类：

import { registerScript } from 'playcanvas';
import { Rotator } from './rotator.mjs';

// register the class with the application's script registry
registerScript(Rotator, undefined, app);

// equivalently:
// app.scripts.add(Rotator);

注册表以类的静态 scriptName 为键。注册后即可通过名称将脚本添加到任意实体，包括程序化创建、克隆和模板实例化：

const entity = new pc.Entity();
entity.addComponent('script');

// attach the script by its registered name
entity.script.create('rotator');

提示

按名称注册支持异步和程序化流程，例如运行时通过 import() 动态导入脚本模块后注册，或实例化按名称引用脚本的模板。如果始终直接向 entity.script.create(Rotator) 传入类引用，则并非必须注册，但无法使用按名称查找。