mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-16 15:30:41 +09:00
Move export for plugin declaration (#555)
Change the expected exported name of plugin declarations to be "plugin" at the main entrypoint instead of the default export. This makes the plugin's code organisation more flexible especially when using CommonJS JavaScript modules as they can export additional symbols from the plugin declaration file.
This commit is contained in:
1 parent
8884116ee9
commit
b0f6c95fca
33 files changed
+71
-62
No files matched your search
@@ -6,7 +6,7 @@ Clusterio uses a field based configuration system to manage settings for the con
|
||||
Plugins can add their own config fields for the controller and instances configs.
|
||||
The fields are defined early in the startup, and fields for disabled plugins will still be created.
|
||||
|
||||
The built-in config fields are defined in [packages/lib/config/definitions.js](/packages/lib/config/definitions.js) while plugins can add their own config field definitions to the `controllerConfigFields` and `instanceConfigFields` properties of the `info.js` export.
|
||||
The built-in config fields are defined in [packages/lib/config/definitions.js](/packages/lib/config/definitions.js) while plugins can add their own config field definitions to the `controllerConfigFields` and `instanceConfigFields` properties of the `plugin` export.
|
||||
A `<plugin_name>.load_plugin` field is automatically created for each plugin and it's used to enable/disable the loading plugins on startup.
|
||||
|
||||
|
||||
|
||||
+12
-14
@@ -25,7 +25,7 @@ The plugin classes have pre-defined hooks that are called during various stages
|
||||
The basic file structure of a plugin is the following.
|
||||
|
||||
plugin_name/
|
||||
+- info.js
|
||||
+- index.js
|
||||
+- package.json
|
||||
+- controller.js
|
||||
+- instance.js
|
||||
@@ -44,14 +44,12 @@ A possible workflow for developing plugins is to place the plugin in a sub-direc
|
||||
To add it to `plugin-list.json` so that it gets loaded use the `plugin add <path>` sub-command to either clusteriocontroller, clusteriohost or clusterioctl.
|
||||
Note that it's important that the path starts with ./ or ../ (use .\ or ..\ on Windows).
|
||||
|
||||
For a plugin the most important file is the `info.js` file.
|
||||
Without it the plugin will not recognized by Clusterio.
|
||||
Here's an example of it:
|
||||
For a plugin to be recognised by Clusterio it needs to export an entry named `plugin` from its main entrypoint.
|
||||
By default the main entrypoint is the `index.js` file, but this may be changed by setting the `"main"` entry to a different file in `package.json`.
|
||||
Here's an example of `index.js`:
|
||||
|
||||
```js
|
||||
const lib = require("@clusterio/lib"); // For messages
|
||||
|
||||
module.exports = {
|
||||
module.exports.plugin = {
|
||||
name: "foo_frobber",
|
||||
title: "Foo Frobber",
|
||||
description: "Does advanced frobnication",
|
||||
@@ -202,8 +200,8 @@ For plugin hooks expections thrown are automatically catched and logged, but for
|
||||
## Plugin Configuration
|
||||
|
||||
Clusterio provides a configuration system that handles storing, distributing, editing and validating config fields for you.
|
||||
You can take advantage of it by declaring config fields under either `controllerConfigFields` or `instanceConfigFields` in the `info.js` export.
|
||||
For example in info.js:
|
||||
You can take advantage of it by declaring config fields under either `controllerConfigFields` or `instanceConfigFields` in the `plugin` export.
|
||||
For example in index.js:
|
||||
|
||||
```ts
|
||||
import type * as lib from "@clusterio/lib";
|
||||
@@ -330,9 +328,9 @@ The requests are similar to HTTP requests, except both parties of a link may ini
|
||||
|
||||
### Defining Events
|
||||
|
||||
Events are defined as properties of the messages object exported by `info.js` that map to instances of the `Event` class from `lib/link`.
|
||||
Events are defined as properties of the messages object exported on `plugin` that map to instances of the `Event` class from `lib/link`.
|
||||
The name of the property correspond to the handler invoked on the plugin class.
|
||||
The Event constructor takes an object of properties that define the event, for example the following could be defined in `info.js`:
|
||||
The Event constructor takes an object of properties that define the event, for example the following could be defined in `plugin`:
|
||||
|
||||
```js
|
||||
messages: {
|
||||
@@ -404,10 +402,10 @@ Use a request if you need a confirmation that the message was received.
|
||||
|
||||
### Definining Requests
|
||||
|
||||
Requests are defined as properties of the messages object exported by `info.js` that map to instances of the `Request` class from `lib/link`.
|
||||
Requests are defined as properties of the messages object exported by `plugin` that map to instances of the `Request` class from `lib/link`.
|
||||
The name of the property corresponds to the handler invoked on the plugin class.
|
||||
The Request constructor takes an object of properties that define the event.
|
||||
For example, the following could be defined in `info.js`:
|
||||
For example, the following could be defined in `plugin`:
|
||||
|
||||
```js
|
||||
messages: {
|
||||
@@ -484,7 +482,7 @@ Same as the requestProperties only for the response sent back by the target.
|
||||
|
||||
Link messages are sent by calling the `.send()` method on the Event/Request instance with the link you want to send it over and the data to send.
|
||||
For `InstancePlugin` code the link to the host is the `instance` itself, which is accessible through the `.instance` property of the `InstancePlugin`.
|
||||
The `.info` property of the plugin class exposes the data exported from the plugin's `info.js` module.
|
||||
The `.info` property of the plugin class exposes the data exported from the plugin's `plugin` export.
|
||||
In other words:
|
||||
|
||||
```js
|
||||
|
||||
Reference in new issue
Block a user