创建脚本

创建组件脚本

在 Cocos Creator 中,脚本也是资源的一部分。在 资源管理器 中创建的脚本,默认是一个 NewComponent 组件,我们称之为组件脚本。可通过以下两种方式创建:

  • 资源管理器 面板空白位置或某个文件夹资源下右击菜单,选择 Create > TypeScript > NewComponent
  • 资源管理器 左上角的 + 按钮,点击后选择 TypeScript > NewComponent

create script

在创建脚本时,名称不能为空,输入框默认为 NewComponent。我们将其修改为 say-hello,可以看到在 资源管理器 中生成了一个名为 say-hello 的脚本文件。

say-hello-1

say-hello-2

新建后的初始脚本代码如下:

  1. import { _decorator, Component, Node } from 'cc';
  2. const { ccclass, property } = _decorator;
  3. @ccclass('say_hello')
  4. export class say_hello extends Component {
  5. start() {
  6. }
  7. update(deltaTime: number) {
  8. }
  9. }

注意点

  1. 项目中所有脚本的类名 ClassName (如上例中的 ‘say_hello’) 不允许重复,即使脚本文件在不同的目录下,各自的代码里也不允许有相同的类名。

  2. 脚本文件名称和脚本的类名不同,在输入初始的文件名之后,文件名会被处理为类名,处理的逻辑详见下文 类名的生成。脚本文件生成后,对文件的后续操作脚本重命名,新的文件名不会再去生成并替换代码里的类名,不再影响了。

  3. 我们推荐用户使用 TypeScript 来编写脚本,目前 资源管理器 中仅支持创建 TypeScript 文件。但如果用户想要使用 JavaScript 来编写脚本的话,可以直接在操作系统的文件夹中创建 JavaScript 文件,或在其他代码编辑软件中创建 JavaScript 文件。

类名的生成

在获得初始文件名数据后,会生成两种规则的类名 ClassName,并以变量的方式提供给脚本模板

  • 下划线格式,变量名为 <%UnderscoreCaseClassName%>。这种格式是为了保持类名尽可能地与文件名一致,保持一致的好处是有利于代码全局搜索和替换。
  • 驼峰格式,变量名为 <%CamelCaseClassName%>。这种格式是为了保持与主流的脚本标准一致,首字母大写的驼峰格式。

添加脚本到场景节点中

将脚本添加到场景节点中,实际上就是为这个节点添加一个脚本组件。层级管理器 选中某个节点,此时 属性检查器 面板会显示该节点的属性。以下两种添加方式:

  • 直接将 资源管理器 中的脚本拖拽当前节点的到 属性检查器 中,即为挂载了一个组件。

  • 点击 属性检查器 最下方的 添加组件 按钮,选择 自定义脚本 -> say_hello,即为挂载组件。

    add component add component done

编辑脚本

开发者可根据自己的需求,选择自己喜爱的代码编辑软件(如:Vim、Sublime Text、Web Storm、VSCode 等)进行脚本编辑。编辑器的 偏好设置 > 外部程序 可设置指定的脚本打开工具。

preference script editor

外部程序配置完成后,在 资源管理器 中双击脚本资源,便会用指定的程序打开该脚本。 编辑脚本代码保存后,鼠标点击回到编辑器,编辑器会自动检测到脚本的改动,重新对其进行编译后使用。

编写脚本代码,可阅读以下文档了解相关内容:

脚本文件创建成功后,再对文件进行重命名,或者对代码里的类名进行修改,文件名和类名均不会再互相影响。

  • say-hello 为例,我们在 资源管理器 中将其重命名为 hello

重新选中该资源,查看 属性检查器,代码还是显示 class say_hello,不会变动。

重新选中 层级管理器 上刚添加组件的节点 Node,查看 属性检查器,组件名称还是显示 say_hello,不会变动。

我们继续双击当前的 hello 资源,将类名改为 say,保存后回到编辑器:

  1. import { _decorator, Component, Node } from 'cc';
  2. const { ccclass, property } = _decorator;
  3. @ccclass('say')
  4. export class say extends Component {
  5. start() {
  6. }
  7. update(deltaTime: number) {
  8. }
  9. }

同样的脚本文件名 hello 不会变化。节点 Node 里的组件名称变为 say

注意:这里需要记得将装饰器 @ccclass('say_hello') 中的内容也改为 @ccclass('say')

modify script

脚本模板

从编辑器 v3.3 开始,支持在项目中管理不同的脚本模板。

  • 新建一个项目,新项目不会自动创建自定义脚本模板所在的目录 .creator/asset-template/typescript
  • 可以手动创建上述目录。也可以通过 资源管理器 的右击菜单里的菜单,点击后才生成目录。

    custom script

默认的 NewComponent 脚本模板仍在引擎内置资源目录下 resources\3d\engine\editor\assets\default_file_content\ts。 文件代码为:

  1. import { _decorator, Component, Node } from 'cc';
  2. const { ccclass, property } = _decorator;
  3. @ccclass('<%UnderscoreCaseClassName%>')
  4. export class <%UnderscoreCaseClassName%> extends Component {
  5. start() {
  6. }
  7. update(deltaTime: number) {
  8. }
  9. }
  10. /**
  11. * COMMENTS_GENERATE_IGNORE
  12. * Use "COMMENTS_GENERATE_IGNORE" tag if you do not want later created scripts to contain these comments.
  13. *
  14. * Predefined Variables
  15. * You can use predefined variables below to setup your scripting preference. For example, whether to use camel case style.
  16. *
  17. * <%UnderscoreCaseClassName%>, class name in underscore format, like 'new_component'
  18. * <%CamelCaseClassName%>, class name in camel format, like 'NewComponent'
  19. * <%Author%>, Who create this file
  20. * <%DateTime%>, when create this file
  21. * <%FileBasename%>, creating file name with extension
  22. * <%FileBasenameNoExtension%>, creating file name without extension
  23. * <%URL%>, url of this file in COCOS ASSET URL format
  24. * <%ManualUrl%>, url of office help document, like 'https://docs.cocos.com/creator/manual/en/'
  25. *
  26. *
  27. * Example:
  28. *
  29. @ccclass('<%UnderscoreCaseClassName%>')
  30. export class <%UnderscoreCaseClassName%> extends Component {
  31. // class member could be defined like this.
  32. dummy = '';
  33. // Use 'property' decorator if your want the member to be serializable.
  34. @property
  35. serializableDummy = 0;
  36. start () {
  37. // Your initialization goes here.
  38. }
  39. update (deltaTime: number) {
  40. // Your update function goes here.
  41. }
  42. }
  43. *
  44. * Learn more about scripting: <%ManualUrl%>scripting/
  45. * Learn more about CCClass: <%ManualUrl%>scripting/decorator.html
  46. * Learn more about life-cycle callbacks: <%ManualUrl%>scripting/life-cycle-callbacks.html
  47. */

注意

  1. 脚本模板中大量的注释并不会生成到脚本文件中,因为在注释里我们使用了关键词标注 COMMENTS_GENERATE_IGNORE 只要此关键词在某段注释里,那么生成脚本文件就会将该段注释忽略掉。

  2. Predefined Variables 我们准备了一些预制的变量,在生成脚本文件的时候可以作为辅助的信息,比如作者 <%Author%>

  3. 特别准备了两种类名格式:<%UnderscoreCaseClassName%><%CamelCaseClassName%>。名称前后仍可以添加自定义的前缀或后缀,如加个 Robot 前缀 Robot<%CamelCaseClassName%>

  4. 通过点击右击菜单的方式,项目自定义脚本模板目录下会自动生成一个文档网址快捷链接,双击即会调出浏览器打开指定网页:Custom Script Template Help Documentation

    custom script help

添加脚本模板

我们从复制上述内置 NewComponent 模板的代码进行修改,类名为驼峰格式,加 Robot 前缀,文件另存为无后缀名的文件 CustomComponent,保存在项目自定义脚本模板的路径下,即 .creator/asset-template/typescript/CustomComponent

custom script file

CustomComponent 模板内容修改为:

  1. import { _decorator, Component, Node } from 'cc';
  2. const { ccclass, property } = _decorator;
  3. /**
  4. *
  5. * <%UnderscoreCaseClassName%>
  6. * <%CamelCaseClassName%>
  7. * <%Author%>
  8. * <%DateTime%>
  9. * <%FileBasename%>
  10. * <%FileBasenameNoExtension%>
  11. * <%URL%>
  12. * <%ManualUrl%>
  13. *
  14. */
  15. @ccclass('Robot<%CamelCaseClassName%>')
  16. export class Robot<%CamelCaseClassName%> extends Component {
  17. start() {
  18. }
  19. update(deltaTime: number) {
  20. }
  21. }

那么最后的我们新建一个 wake up 脚本资源看看,效果如下图:

custom script menu

custom script result