3、脚本

Cocos Creator 脚本用于实现用户定义的（游戏）行为，支持 JavaScript 和 TypeScript 两种编程语言。通过编写脚本组件，并将它挂载到场景节点中来驱动场景中的物体。

在组件脚本的编写过程中，开发者可以通过声明属性，将脚本中需要调节的变量映射到 属性检查器 中，以便策划和美术进行调整。与此同时，也可以通过注册特定的回调函数，来帮助初始化、更新甚至销毁节点。

语言支持

#

Cocos Creator 支持 TypeScript 和 JavaScript 两种编程语言。但需要注意的是，JavaScript 只支持以插件脚本的形式导入使用。

Cocos Creator 支持 TypeScript 4.1.0，使用时有以下需要注意：

• 不支持 const enums。

• 重导出 TypeScript 类型和接口时应该使用 export type。例如使用 export type { Foo } from './foo'; 而不是 export { Foo } from './foo';。

• 不支持 export = 和 import =。

• 命名空间导出的变量必须声明为 const，而不是 var 或 let。

• 同一命名空间的不同声明不会共享作用域，需要显式使用限定符。

• 编译过程中的类型错误将被忽略。

• 编译时不会读取 tsconfig.json，意味着 tsconfig.json 的编译选项并不会影响编译。

脚本使用

#

创建脚本

#

在创建脚本时，名称不能为空，输入框默认为 NewComponent。

import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('NewComponent')
export class NewComponent extends Component {
   start() {

   }

   update(deltaTime: number) {
       
   }
}

1. 项目中所有脚本的类名 ClassName （如上例中的NewComponent） 不允许重复，即使脚本文件在不同的目录下，各自的代码里也不允许有相同的类名。
2. 脚本文件名称和脚本的类名不同，在输入初始的文件名之后，文件名会被处理为类名。脚本文件生成后，对文件的后续操作脚本重命名，新的文件名不会再去生成并替换代码里的类名，不再影响了。
3. 我们推荐用户使用 TypeScript 来编写脚本，目前 资源管理器 中仅支持创建 TypeScript 文件。但如果用户想要使用 JavaScript 来编写脚本的话，可以直接在操作系统的文件夹中创建 JavaScript 文件，或在其他代码编辑软件中创建 JavaScript 文件。

添加脚本到场景节点中

#

将脚本添加到场景节点中，实际上就是为这个节点添加一个脚本组件。

在 层级管理器 选中某个节点，此时 属性检查器 面板会显示该节点的属性。以下两种添加方式：

• 直接将 资源管理器 中的脚本拖拽当前节点的到 属性检查器 中，即为挂载了一个组件。
• 点击 属性检查器 最下方的 添加组件 按钮，选择（自定义脚本 - NewComponent），即为挂载组件。

脚本运行环境

#

Cocos Creator 3.0 引擎的 API 都存在模块 cc 中，使用标准的 ES6 模块导入语法将其导入：

import {
    Component,  // 导入类 Component
    _decorator, // 导入命名空间 _decorator
    Vec3 // 导入类 Vec3
} from 'cc';

// 将整个 Cocos Creator 模块导入为命名空间 Cocos Creator
import * as modules from 'cc'; 

@_decorator.ccclass("MyComponent")
export class MyComponent extends Component {
    public v = new Vec3();
}

注意，由于历史原因，cc 是 Cocos Creator 3.0 保留使用的标识符，其行为 相当于 在任何模块顶部定义了名为 cc 的对象。因此，开发者不应该将 cc 用作任何 全局对象 的名称。

装饰器

#

ccclass

#

将装饰器 ccclass 应用在类上时，此类称为 cc 类。cc 类注入了额外的信息以控制 Cocos Creator 对该类对象的序列化、编辑器对该类对象的展示等。因此，未声明 ccclass 的组件类，也无法作为组件添加到节点上。

ccclass 装饰器的参数 name 指定了 cc 类的名称，cc 类名是 独一无二 的，这意味着即便在不同目录下的同名类也是不允许的。

组件类装饰器

#

此类装饰器是只能用来修饰 Component 的子类。

executeInEditMode

#

默认情况下，所有组件都只会在运行时执行，也就是说它们的生命周期回调在编辑器模式下并不会触发。executeInEditMode 允许当前组件在编辑器模式下运行，默认值为 false。

const { ccclass, executeInEditMode } = _decorator;

@ccclass('Example')
@executeInEditMode(true)
export class Example extends Component {
    update (dt: number) {
        // 会在编辑器下每帧执行
    }
}

requireComponent

#

requireComponent 参数用来指定当前组件的依赖组件，默认值为 null。当组件添加到节点上时，如果依赖的组件不存在，引擎会自动将依赖组件添加到同一个节点，防止脚本出错。该选项在运行时同样有效。

const { ccclass, requireComponent } = _decorator;

@ccclass('Example')
@requireComponent(Sprite)
export class Example extends Component {
}

executionOrder

#

executionOrder 用来指定脚本生命周期回调的执行优先级。小于 0 的脚本将优先执行，大于 0 的脚本将最后执行。

• 对于同一节点上的不同组件，数值小的先执行，数值相同的按组件添加先后顺序执行
• 对于不同节点上的同一组件，按节点树排列决定执行的先后顺序

该优先级设定只对 onLoad、onEnable、start、update 和 lateUpdate 有效，对 onDisable 和 onDestroy 无效。

const { ccclass, executionOrder } = _decorator;

@ccclass('Example')
@executionOrder(3)
export class Example extends Component {
}

disallowMultiple

#

同一节点上只允许添加一个同类型（含子类）的组件，防止逻辑发生冲突，默认值为 false。

const { ccclass, disallowMultiple } = _decorator;

@ccclass('Example')
@disallowMultiple(true)
export class Example extends Component {
}

menu

#

@menu(path) 用来将当前组件添加到组件菜单中，方便用户查找。

需要注意该菜单是添加在 属性检查器 面板中按下添加组件按钮后的下拉框内。

const { ccclass, menu } = _decorator;

@ccclass('Example')
@menu('foo/bar')
export class Example extends Component {
}

属性装饰器

#

属性装饰器 property 可以被应用在 cc 类的属性或访问器上。属性装饰器用于控制 Cocos Creator 编辑器中对该属性的序列化、属性检查器 中对该属性的展示等。

@property({
    type: Node,
    visible: true,
})
targetNode: Node | null = null;

生命周期

#

Cocos Creator 为组件脚本提供了生命周期的回调函数。开发者只需要定义特定的回调函数，Creator 就会在特定的时期自动执行相关脚本，开发者不需要手工调用它们。

目前提供给开发者的生命周期回调函数主要有（按生命周期触发先后排列）：

• onLoad
• onEnable
• start
• update
• lateUpdate
• onDisable
• onDestroy

onLoad

#

组件脚本的初始化阶段，我们提供了 onLoad 回调函数。onLoad 回调会在节点首次激活时触发，比如所在的场景被载入，或者所在节点被激活的情况下。在 onLoad 阶段，保证了你可以获取到场景中的其他节点，以及节点关联的资源数据。onLoad 总是会在任何 start 方法调用前执行，这能用于安排脚本的初始化顺序。

import { _decorator, Component, Node, SpriteFrame, find } from 'cc';
const { ccclass, property } = _decorator;

@ccclass("test")
export class test extends Component {
    @property({type:SpriteFrame})
    bulletSprite=null;
    @property({type:Node})
    gun=null;

    _bulletRect=null;

    onLoad(){
        this._bulletRect=this.bulletSprite.getRect();
        this.gun = find('hand/weapon', this.node);
    }
}

onEnable

#

当组件的 enabled 属性从 false 变为 true 时，或者所在节点的 active 属性从 false 变为 true 时，会激活 onEnable 回调。倘若节点第一次被创建且 enabled 为 true，则会在 onLoad 之后，start 之前被调用。

start

#

start 回调函数会在组件第一次激活前，也就是第一次执行 update 之前触发。start 通常用于初始化一些中间状态的数据，这些数据可能在 update 时会发生改变，并且被频繁的 enable 和 disable。

import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

@ccclass("starttest")
export class starttest extends Component {

    private _timer: number = 0.0;

    start () {
        this._timer = 1.0;
    }

    update (deltaTime: number) {
        this._timer += deltaTime;
        if(this._timer >= 10.0){
            console.log('I am done!');
            this.enabled = false;
        }
     }
}

update

#

游戏开发的一个关键点是在每一帧渲染前更新物体的行为，状态和方位。这些更新操作通常都放在 update 回调中。

import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

@ccclass("updatetest")
export class updatetest extends Component {

    update (deltaTime: number) {
        this.node.setPosition(0.0,40.0 * deltaTime,0.0);
    }
}

增量时间deltaTime

#

首先我们得知道动画是什么。动画，动画，动态的图画，即当图画连续动起来就能形成动画，那么在人类眼中，1秒中需要24张图画快速更换才能在大脑中形成视觉暂缓而成的动画。这里我们就把图画的24张叫做24帧，也就是说人眼中需要1秒24帧的动画才能流畅播放。

因为硬件设备不同性能，A设备1秒能60帧，B设备1秒能120帧。也就是说：每分钟，A能触发update方法60次，B能触发update方法120次。

假设，要让一个角色速度为3m/s，连续移动

update(){
	// 增量距离： 将要移动的距离 = 速度3m/s * 时长1s
	distance = speed * 1;
	// 累计距离：成为新的位置
	position = position + distance;
}

这样就会导致一个问题，如果A设备为60帧，B设备120帧，那么A设备的玩家一分钟移动了3 * 60 = 180m，B设备的玩家移动了3 * 120 = 360m。

所以为了解决这个问题，那么就引入了增量事件deltaTime，这个变量代表了，当前帧与上一帧中间的间隔时间，它并不是固定的，根据设备运行动态变动的，随时都不一样的。

update(deltaTime){
	// 增量距离： 将要移动的距离 = 速度3m/s * 时长1s
	distance = speed * deltaTime;
	// 累计距离：成为新的位置
	position = position + distance;
}

lateUpdate

#

update 会在所有动画更新前执行，但如果我们要在动效（如动画、粒子、物理等）更新之后才进行一些额外操作，或者希望在所有组件的 update 都执行完之后才进行其它操作，那就需要用到 lateUpdate 回调。

import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

@ccclass("lateupdatetest")
export class lateupdatetest extends Component {

    lateUpdate (deltaTime: number) {
        this.node.setPosition(0.0,50,0.0);
    }
}

onDisable

#

当组件的 enabled 属性从 true 变为 false 时，或者所在节点的 active 属性从 true 变为 false 时，会激活 onDisable 回调。

onDestroy

#

当组件或者所在节点调用了 destroy()，则会调用 onDestroy 回调，并在当帧结束时统一回收组件。

脚本使用

#

访问节点和组件

#

你可以在 属性检查器 里修改节点和组件，也能在脚本中动态修改。动态修改的好处是能够在一段时间内连续地修改属性、过渡属性，实现渐变效果。脚本还能够响应玩家输入，能够修改、创建和销毁节点或组件，实现各种各样的游戏逻辑。要实现这些效果，你需要先在脚本中获得你要修改的节点或组件。

获得组件所在的节点

#

获得组件所在的节点很简单，只要在组件方法里访问 this.node 变量

start() {
    let node = this.node;
    node.setPosition(0.0, 0.0, 0.0);
}

获得其他组件

#

如果你经常需要获得同一个节点上的其它组件，这就要用到 getComponent 这个 API。

import { _decorator, Component, Label } from 'cc';
const { ccclass, property } = _decorator;

@ccclass("test")
export class test extends Component {
    private label: any = null

    start() {
        this.label = this.getComponent(Label);
        let text = this.name + 'started';
        // Change the text in Label Component
        this.label.string = text;
    }
}

你也可以为 getComponent 传入一个类名。对用户定义的组件而言，类名就是脚本的文件名，并且 区分大小写。例如 “SinRotate.ts” 里声明的组件，类名就是 “SinRotate”。

let rotate = this.getComponent("SinRotate");

如果在节点上找不到你要的组件，getComponent 将返回 null。

获得其它节点及其组件

#

仅仅能访问节点自己的组件通常是不够的，脚本通常还需要进行多个节点之间的交互。例如，一门自动瞄准玩家的大炮，就需要不断获取玩家的最新位置。Cocos Creator 提供了一些不同的方法来获得其它节点或组件。

1、利用属性检查器设置节点

#

// Cannon.ts

import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

@ccclass("Cannon")
export class Cannon extends Component {
    // 声明 Player 属性
    @property({ type: Node })
    private player = null;
}

这段代码在 properties 里面声明了一个 player 属性，默认值为 null，并且指定它的对象类型为 Node，然后就可以将节点拖到这个Player控件中。

2、查找子节点

#

有时候，游戏场景中会有很多个相同类型的对象，像是炮塔、敌人和特效，它们通常都有一个全局的脚本来统一管理。如果用 属性检查器 来一个一个将它们关联到这个脚本上，那工作就会很繁琐。为了更好地统一管理这些对象，我们可以把它们放到一个统一的父物体下，然后通过父物体来获得所有的子物体

// CannonManager.ts

import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

@ccclass("CannonManager")
export class CannonManager extends Component {

    start() {
        let cannons = this.node.children;
        //...
    }

}

你还可以使用 getChildByName：

this.node.getChildByName("Cannon 01");

如果子节点的层次较深，你还可以使用 find，find 将根据传入的路径进行逐级查找：

find("Cannon 01/Barrel/SFX", this.node);

3、全局名字查找

#

当 find 只传入第一个参数时，将从场景根节点开始逐级查找：

this.backNode = find("Canvas/Menu/Back");

访问已有变量里的值

#

如果你已经在一个地方保存了节点或组件的引用，你也可以直接访问它们，例如现在可以通过import{ } from + 文件名(不含路径) 来获取到对方 exports 的对象。

Global

// Global.ts, now the filename matters
import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

@ccclass("Global")
export class Global extends Component {

    public static backNode: any = null;
    public static backLabel: any = null;
}

Back

// Back.ts
import { _decorator, Component, Node, Label } from 'cc';
const { ccclass, property } = _decorator;
// this feels more safe since you know where the object comes from
import{Global}from "./Global";

@ccclass("Back")
export class Back extends Component {
    onLoad() {
        Global.backNode = this.node;
        Global.backLabel = this.getComponent(Label);
    }
}

常用节点和组件接口

#

节点状态和层级操作

#

假设我们在一个组件脚本中，通过 this.node 访问当前脚本所在节点。

1、激活或关闭节点

#

this.node.active = false;

设置 active 属性和在编辑器中切换节点的激活、关闭状态，效果是一样的。当一个节点是关闭状态时，它的所有组件都将被禁用。同时，它所有子节点，以及子节点上的组件也会跟着被禁用。要注意的是，子节点被禁用时，并不会改变它们的 active 属性，因此当父节点重新激活的时候它们就会回到原来的状态。

2、更改节点的父节点

#

this.node.parent = parentNode;

或者

this.node.removeFromParent();
parentNode.addChild(this.node);

3、索引节点的子节点

#

this.node.children //返回节点的所有子节点数组。
this.node.children.length //返回节点的子节点数量。

更改节点的变换（位置、旋转、缩放）

#

1、更改节点位置

#

有以下两种方法：

• 使用 setPosition 方法：
  • this.node.setPosition(100, 50, 100);
  • this.node.setPosition(new Vec3(100, 50, 100));
• 设置 position 变量：
  • this.node.position = new Vec3(100, 50, 100);

2、更改节点旋转

#

this.node.setRotation(90, 90, 90);

或通过欧拉角设置本地旋转：

this.node.setRotationFromEuler(90, 90, 90);

3、更改节点缩放

#

this.node.setScale(2, 2, 2);

创建和销毁节点

#

创建节点

#

import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

@ccclass("test")
export class test extends Component {

    start(){
        let node =new Node('box');
        node.setPosition(0,0,-10);
    }
}

需要注意的是，在上述的示例中通过 new Node 创建出来的节点并不会主动添加到场景内，直至用户调用 director.getScene().addChild(node) 来添加到场景内或者通过 node.parent = {a valid node} 来作为某个节点的子节点。

克隆节点

#

import { _decorator, Component, Node,instantiate, director } from 'cc';
const { ccclass, property } = _decorator;

@ccclass("test")
export class test extends Component {

    @property({type:Node})
    private target: Node = null;

    start(){
        let scene = director.getScene();
        let node = instantiate(this.target);

        scene.addChild(node);
        node.setPosition(0, 0,-10);
    }
}

创建预制节点

#

import { _decorator, Component, Prefab, instantiate, director } from 'cc';
const { ccclass, property } = _decorator;

@ccclass("test")
export class test extends Component {

    @property({type:Prefab})
    private target: Prefab = null;

    start(){
        let scene = director.getScene();
        let node = instantiate(this.target);

        scene.addChild(node);
        node.setPosition(0,0,0);
    }
}

销毁节点

#

通过 node.destroy() 函数，可以销毁节点。值得一提的是，销毁节点并不会立刻被移除，而是在当前帧逻辑更新结束后，统一执行。当一个节点销毁后，该节点就处于无效状态，可以通过 isValid 判断当前节点是否已经被销毁。

import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

@ccclass("test")
export class test extends Component {

    @property({type:Node})
    private target: Node = null;

    private positionz: number = -20;

    start(){
        // 5秒后销毁节点
        setTimeout(function () {
            this.target.destroy();
          }.bind(this), 5000);
    }
    update(deltaTime: number){
        console.info(this.target.isValid);
        this.positionz += 1*deltaTime;
        if (this.target.isValid) {
            this.target.setPosition(0.0,0.0,this.positionz);
          }
    }
}

计时器

#

开始一个计时器将每隔 5s 执行一次

this.schedule(function() {
    // 这里的 this 指向 component
    this.doSomething();
}, 5);

更灵活的计时器（将在 10 秒后开始计时，每 5 秒执行一次回调，重复 3 + 1 次。）

// 以秒为单位的时间间隔
let interval = 5;
// 重复次数
let repeat = 3;
// 开始延时
let delay = 10;
this.schedule(function() {
    // 这里的 this 指向 component
    this.doSomething();
}, interval, repeat, delay);

只执行一次的计时器

this.scheduleOnce(function() {
    // 这里的 this 指向 component
    this.doSomething();
}, 2);

取消计时器

this.count = 0;
this.callback = function () {
    if (this.count == 5) {
        // 在第六次执行回调时取消这个计时器
        this.unschedule(this.callback);
    }
    this.doSomething();
    this.count++;
}
this.schedule(this.callback, 1);

取消组件中所有的计时器：unscheduleAllCallbacks

加载和切换场景

#

在 Cocos Creator 中，我们使用场景文件名（不包含扩展名）来索引指代场景。并通过以下接口进行加载和切换操作：

director.loadScene("MyScene");

通过常驻节点进行场景资源管理和参数传递

#

引擎同时只会运行一个场景，当切换场景时，默认会将场景内所有节点和其他实例销毁。如果我们需要用一个组件控制所有场景的加载，或在场景之间传递参数数据，就需要将该组件所在节点标记为「常驻节点」，使它在场景切换时不被自动销毁，常驻内存。

director.addPersistRootNode(myNode);

上面的接口会将 myNode 变为常驻节点，这样挂在上面的组件都可以在场景之间持续作用，我们可以用这样的方法来储存玩家信息，或下一个场景初始化时需要的各种数据。 需要注意的是，目标节点必须为位于层级的根节点，否则设置无效。

如果要取消一个节点的常驻属性：

director.removePersistRootNode(myNode);

需要注意的是上面的 API 并不会立即销毁指定节点，只是将节点还原为可在场景切换时销毁的节点。

场景加载回调

#

director.loadScene("MyScene", onSceneLaunched);

onSceneLaunched 就是声明在本脚本中的一个回调函数，在场景加载后可以用来进一步的进行初始化或数据传递的操作。

预加载场景

#

director.loadScene 会在加载场景之后自动切换运行新场景，有些时候我们需要在后台静默加载新场景，并在加载完成后手动进行切换。那就可以预先使用 preloadScene 接口对场景进行预加载：

director.preloadScene("table", function () {
    console.log('Next scene preloaded');
});

之后在合适的时间调用 loadScene，就可以真正切换场景。

director.loadScene("table");

就算预加载还没完成，你也可以直接调用 director.loadScene，预加载完成后场景就会启动。