本系列教程转载自公众号【许彦峰】，作者是 Cocos “插件小王子”许彦峰，策划良久。文章从个人角度，阐述对新插件体系从零入门的全新理解。阅读时间 15 分钟左右，部分教程附带简洁明了的代码说明，按照教程一步一步操作，能够顺利运行插件。希望本系列教程，能让你阅读爽快的同时，又能学到干货！

hello-world

学任何新知识，最快的入门方式莫非 HelloWorld。

跟着我 3 步搞定，不需要编写一行代码，2 分钟轻松入门 Creator 3D 插件。

1. 创建插件项目

我们需要先下载 Cocos Dashboard，然后在 Dashboard 中下载 Creator 3D，这里我使用的是 v1.2.0：

新建并打开一个 Creator 3D 空项目，然后找到项目的 packages 目录，如下图所示新建对应的文件和目录：

2. 设置插件基本信息

我们在package.json里面定义一些插件信息。

比如插件名字、版本号、作者、描述等：

{"name": "hello-world","version": "1.0.0","author": "xu_yanfeng","description": "creator3d插件 hello-world"
}

3.在编辑器中查看插件

让我们回到 Creator 3D 编辑器中，点击菜单栏中的扩展->扩展管理器

打开扩展管理器面板，切换到项目选项卡，即可看到hello-world插件：

可以看到，展示的插件信息，就是我们刚刚在package.json里面定义的信息。

如果编辑器始终没有发现该插件，我们可以尝试重启编辑器。

因为目前我们还没有编写任何插件的逻辑，所以，启用按钮暂时不可用。

至此，我们的第一个插件就编写完毕了！是不是很 easy！

现在插件还没有任何功能，后续我们将一步一步完善！

给插件添加菜单

我们创建了一个插件，并且可以成功被编辑器所识别、加载。

有时我们希望能够在编辑器菜单栏中，能够显示插件自己的菜单。

在 Creator 3D 插件里面，自定义插件菜单，非常简单：

1.定义插件菜单

打开插件的package.json文件，

{"name": "hello-world","version": "1.0.0","author": "xu_yanfeng","description": "creator3d插件 hello-world","contributions": {"menu": [{"path": "插件","label": "自定义菜单"}]}
}

如上所示，增加contributions属性，并在里面增加menu来自定义插件菜单。

• path：插件菜单的显示位置，支持a/b/c表示多级菜单。

• label：菜单名字。

contributions是 Creator 3D 插件中非常重要的一个配置属性，大部分插件功能都是配置在里面。

2.在编辑器中查看插件菜单

回到编辑器中，发现菜单栏并没有出现刚刚我们定义的新菜单。

我们打开扩展管理器，点击重启(必要情况下，可能得重启下编辑器)。

此时，我们刚刚定义的菜单，已经成功显示在编辑器的菜单栏中。

给插件菜单添加逻辑

点击菜单我们需要编写一些自己的逻辑，我们该如何做呢？

首先我们需要知道，插件整体的设计理念是：消息。

1. 设置插件菜单的响应消息

如下所示，我们修改下package.json：

{// ..."contributions": {"menu": [{"path": "插件","label": "自定义菜单","message": "onMenuClick"}],"messages": {"onMenuClick": {"methods": ["log"]}}}
}

• 给菜单添加一个message属性，属性值就是响应的消息名字onMenuClick。

• 插件新增了一个messages字段，这里面定义了整个插件的所有消息，包括菜单的响应消息。

从配置中，不难发现onMenuClick消息最终要调用log方法，那么log方法的具体逻辑，又该写在哪里呢？

2.编写消息的具体逻辑

在package.json里面，我们给插件新增一个main字段，给插件绑定一个脚本，之后所有插件相关的逻辑，我们都写在这里。

{// ..."main": "./main.js",// ...
}

我们在插件当前目录，新建一个main.js，

并新增一个log方法:

这里的log一定要和消息onMenuClick里面设置的消息名字一致，才能正确关联触发。

exports.methods = {log () {console.log('hello-world');}
}

3.编辑器中测试下

回到编辑器中，和之前一样，我们需要在扩展面板重启并启用下插件(必要情况下，可能得重启下编辑器)。

然后我们点击插件的菜单，就能在控制台打印hello-world。

整个过程还是比较绕，接下来详细地给大家详细介绍下插件消息，帮助你更好地理解消息机制。

给插件添加快捷键

我们日常使用的软件，一般都有快捷键，插件同样也支持啦。

Creator 3D 插件中设置快捷键非常简单，我们需要这样做：

1. 配置快捷键

如下所示，修改package.json：

{// ..."contributions": {// ..."shortcuts": [{"message": "onMenuClick","win": "ctrl+z","mac": "cmd+z"}]}
}

我们在contributions中，新增一个shortcuts字段，

• win/mac：绑定快捷键，可以在不同平台绑定不同的快捷键。

• message：触发的消息名字，和菜单绑定消息一样。

这里我直接绑定了菜单的消息，当然，你也可以重新绑定新的消息，具体参考上节教程。

2. 编辑器中测试下

回到编辑器中，和之前一样，我们需要在扩展面板中重启并启用下插件(必要情况下，可能得重启下编辑器)。

同时我们会发现编辑器菜单上，多了快捷键信息。

我们在编辑器中，按下快捷键cmd/ctrl+z，和上节教程中点击菜单效果一样，会在控制台打印hello-world。

可以看到绑定快捷键非常简单，整个消息机制还是非常灵活的。

在实际的开发过程中，理论上快捷键应该是更好地去服务一些高频常用的功能，如果绑定大量的快捷键反而会适得其反，所以快捷键尽量不要滥用。

消息机制详解

不难发现，要想玩转creator 3d插件，就必须要理解messages！！！

我们梳理下之前的代码：

• package.json：描述插件，包括名字、作者、版本、菜单、快捷键、消息等

{"name": "hello-world","version": "1.0.0","author": "xu_yanfeng","main": "./main.js","description": "creator3d插件","contributions": {"menu": [{"message": "onMenuClick","path": "插件","label": "自定义菜单"}],"shortcuts": [{"message": "onMenuClick","win": "ctrl+z","mac": "cmd+z"}],"messages": {"onMenuClick": {"methods": ["log"]}}}
}

• main.js：插件的逻辑，消息的具体实现是写在这里面

exports.methods = {log () {console.log('hello-world')}
}

我们再次梳理下整个流程，加深下印象：

• 当我们点击菜单时，会触发设置的onMenuClick消息，然后onMenuClick消息会执行具体对应方法log。

• 当我们按下快捷键时，会触发设置的onMenuClick消息，然后onMenuClick消息会执行具体对应方法log。

我顺便整理了一张图，从图中，能够更加形象的感知之间的关系：

我们可以看到，利用消息机制，插件做到了设计上的完全解耦，非常的灵活，但同时也增加了理解难度，编写时也更叫容易犯错，有得必有失嘛！

悄悄告诉大家，Creator 3D 编辑器本身也在使用这套消息机制，并得到了充分的验证，这也充分说明这套消息机制，是完全可以胜任并满足比较复杂的插件需求，不过在易用性，还有待提高。

至此，如果你要编写的插件如果没有 UI 面板交互，基本上只需要掌握到本节的知识即可。在后续教程中，将会重点介绍插件 UI 面板相关的开发教程喔。

---

感谢原文作者许彦峰，也希望能有更多的童鞋分享关于编辑器插件开发资料喔。

本系列教程持续更新中，请大家保持关注，也欢迎各位开发者点击【阅读原文】，查看一手更新，与作者进行交流学习！