First Extension

Through this article, we will learn to create a Cocos Creator extension and execute a custom script through the extension.

Creating and Installing Extensions

First, find the folder ~/.CocosCreator/extensions (Mac) or C:\Users\${your user name}\.CocosCreator\extensions (Windows) in the global directory, or the ${your project path}/extensions folder. If the extensions folder does not exist, create a new one.

Second, create an empty folder inside the extensions folder named hello-world.

Third, create two files browser.js and package.json in the folder. These files will be empty. Use any text editor to create these files or on MacOS use touch browser.js and touch package.json from a command prompt.

The structure of the directory where the extension is located should be the following:

  1. hello-world
  2.   |--browser.js
  3.   |--package.json

Define the Description File package.json

Every extension needs a package.json file to describe the purpose of the extension. Only after the description file package.json is fully defined, can Cocos Creator 3.0 know the specific functions defined in this extension, loading entry and other information.

Although the definition of many fields in package.json is similar to that of node.js‘s npm package, they are obviously customized for different products and services. The npm module downloaded from the npm community cannot be directly put into Cocos Creator 3.0 to become an extension, but one can use the modules in the npm community in the Cocos Creator 3.0 extension.

To continue creating an extension, fill in the content in the newly created package.json file:

  1. {
  2.     "name": "hello-world",
  3.     "version": "1.0.0",
  4.     "main": "./browser.js",
  5.     "description": "A simple extension",
  6.     "contributions": {
  7.         "menu": [{
  8.             "path": "Develop",
  9.             "label": "test",
  10.             "message": "log"
  11.         }],
  12.         "messages": {
  13.             "log": {
  14.                 "methods": ["log"]
  15.             }
  16.         }
  17.     }
  18. }

The meanings of the fields are as follows:

  • name String — Defines the package name, which is globally unique and relates to the login name on the official website server in the future.

    Note: if the plugin will be uploaded to the Cocos Store, there are certain restrictions on the package name. The name only allows lowercase letters, numbers, hyphens (-), underscores (_), dots (.), and begin with a lowercase letter or number.

  • version String — The version number. We recommend using the semver standard to manage your package versions.

  • main String (optional) — The entry file

  • description String (optional) — Describe your package in one sentence.
  • contributions Object (optional) — Configuration objects that extend the existing functionality of the editor.

Next, it is necessary to define a messages object in contributions, which is the method of editor message registration. This message can be bound to one or more methods defined in the extension. For more definition data, please refer to the Message documentation.

Next, define a menu array in contributions to provide basic information of a menu to the menu component. Finally, bind this menu to a message. For more details, please refer to the Menu documentation.

Careful that after the menu is pressed, the triggered action is notified by the message between the extensions, and the message system is the way of interaction between the extensions.

For a detailed package.json format definition, please refer to the Extension documentation.

Entry program browser.js

After defining the description file, the next step is to write the entry program browser.js.

The content is as follows:

  1. 'use strict';
  3. // The method defined in the extension
  4. exports.methods = {
  5.     log() {
  6.         console.log('Hello World');
  7.     },
  8. };
  10. // Execute when the extension is started
  11. exports.load = function() {};
  13. // Execute when the extension is closed
  14. exports.unload = function() {};

This entry program will be loaded during the startup of Cocos Creator. The methods defined in methods will be used as the operation interface, which can be called across extensions through messages or communicate with the panel.

Runing an extension

First, open Cocos Creator 3.0, find and open the Extension -> Extension Manager at the top, and select the extension location (global or project) on the panel.

Second, find the Refresh button at the top and click to manually update the extended list information at that location. Then the extension list will show the extensions that have been found. Extensions can be started, closed, or restarted from the list control.

If the extension has been started, a Develop menu will appear in the top menu area with a tester menu item. After clicking, the message will be triggered according to the definition, and the corresponding method in the extension will be executed according to the message definition, and then the log information of Hello World will be printed out on the console.