脚本编程入门

无论采用现代 ESM 方式还是经典脚本系统，本指南都会介绍编写 PlayCanvas 脚本所需的基本结构和概念。

什么是脚本？

脚本是一段为场景中的实体定义行为的 JavaScript 代码，具有以下特点：

• 可复用：同一脚本可以附加到多个实体。
• 可配置：通过属性为不同实体定制行为。
• 事件驱动：响应生命周期事件和用户交互。

基本脚本结构

无论使用哪套系统，每个 PlayCanvas 脚本都遵循类似的模式：

ESM（推荐）

import { Script } from 'playcanvas';

export class MyScript extends Script {
    static scriptName = 'myScript';

    /** @attribute */
    speed = 10;

    initialize() {
        // Called once when the script starts
        console.log('Script initialized!');
    }

    update(dt) {
        // Called every frame
        this.entity.rotate(0, this.speed * dt, 0);
    }
}

ESM 脚本要点：

• 从 PlayCanvas 导入 Script 类。
• 导出一个继承 Script 的类。
• 使用 /** @attribute */ 向编辑器暴露属性。
• 文件必须使用 .mjs 扩展名。

经典脚本

var MyScript = pc.createScript('myScript');

MyScript.attributes.add('speed', { type: 'number', default: 10 });

MyScript.prototype.initialize = function() {
    // Called once when the script starts
    console.log('Script initialized!');
};

MyScript.prototype.update = function(dt) {
    // Called every frame
    this.entity.rotate(0, this.speed * dt, 0);
};

经典脚本要点：

• 使用 pc.createScript() 声明脚本。
• 使用 .attributes.add() 方法添加属性。
• 在原型上定义方法。
• 文件使用 .js 扩展名。

核心概念

脚本生命周期

脚本中有多个方法，会在不同时间自动调用：

• initialize()：脚本启动时调用一次。
• update(dt)：每帧调用，并传入帧间时间差。
• postUpdate(dt)：所有更新完成后调用。
• enable、disable、destroy 事件的处理函数。

进一步了解脚本生命周期。

属性

通过属性，可以向编辑器暴露脚本中的可配置项，无需修改代码即可调整脚本行为：

ESM

import { Color, Entity, Script } from 'playcanvas';

export class Configurable extends Script {
    static scriptName = 'configurable';

    /** @attribute */
    speed = 5;
    
    /** @attribute */
    color = new Color(1, 0, 0);
    
    /** 
     * @attribute 
     * @type {Entity}
     */
    target;
}

经典脚本

var Configurable = pc.createScript('configurable');

Configurable.attributes.add('speed', { type: 'number', default: 5 });
Configurable.attributes.add('color', { type: 'rgba', default: [1, 0, 0, 1] });
Configurable.attributes.add('target', { type: 'entity' });

进一步了解脚本属性。

访问实体

每个脚本都可以通过 this.entity 访问其附加的实体：

// Get the entity's position
const position = this.entity.getPosition();

// Find child entities
const child = this.entity.findByName('ChildName');

// Access components
const camera = this.entity.camera;
const rigidbody = this.entity.rigidbody;

下一步

• **学习 ESM 脚本：**新项目可以阅读 ESM 脚本，了解现代开发方式。
• **理解生命周期：**阅读脚本生命周期，了解代码的执行时机。
• **添加交互：**探索事件，让脚本彼此通信。

提示

应该使用哪套系统？

对于新项目，推荐使用 ESM 脚本，它提供更完善的工具支持、更简洁的语法，以及现代 JavaScript 特性。现有项目使用的经典脚本仍然受到完整支持。