mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-23 00:13:13 +09:00
Merge remote-tracking branch 'upstream/master' into feature/wait-for-plugin
This commit is contained in:
commit
7f688d2ed0
77 files changed
+2006
-693
No files matched your search
@@ -8,6 +8,24 @@ Before `clusterioctl` can be used it needs to be configured for the cluster it w
|
||||
The easiest way to do this is to run `npx clusteriocontroller bootstrap create-ctl-config <username>` on the controller, which creates the necessary `config-ctl.json` for managing the cluster as the given user.
|
||||
|
||||
|
||||
## Output Format
|
||||
|
||||
ctl> --output json <command>
|
||||
|
||||
Print the result of the command as JSON on stdout instead of text meant for reading.
|
||||
Lists are printed as an array of objects, other results as an object, and commands that have no result print `{"success": true}`.
|
||||
If the command fails it prints `{"error": "<ClassName>", "message": "<message>"}` and exits with a non-zero exit code.
|
||||
Log messages are written to stderr in all formats.
|
||||
|
||||
`--output wire` prints the same results in the format they are sent between the controller, hosts and clusterioctl, which uses snake_case names like `is_admin`.
|
||||
The `json` format uses the property names shown in the tables of the human format.
|
||||
|
||||
`log follow` and `debug dump-ws` keep running and print one JSON object per line as entries arrive.
|
||||
`instance start-all` and `instance stop-all` print an array with an entry per instance, which has an `error` property if that instance failed to start or stop.
|
||||
|
||||
The default is `--output human`, which prints `Command ran successfully` for commands that have no result.
|
||||
|
||||
|
||||
## Hosts
|
||||
|
||||
### List hosts
|
||||
|
||||
@@ -151,6 +151,10 @@ The following properties are recognized:
|
||||
Array of features the plugin needs from the instances it is loaded on, any of `"SavePatching"`, `"ScriptCommands"` and `"LuaUdp"`.
|
||||
See [Handling Invalid Configuration](#handling-invalid-configuration)
|
||||
|
||||
**requiredMods**:
|
||||
Array of Factorio mods the plugin needs in the mod pack of the instances it is loaded on, written as Factorio dependency strings.
|
||||
See [Handling Invalid Configuration](#handling-invalid-configuration)
|
||||
|
||||
**messages**:
|
||||
Array of request and event classes for this plugin.
|
||||
See guide for [defining link messages](#defining-link-messages) below.
|
||||
@@ -347,6 +351,25 @@ export const plugin = {
|
||||
Enabling the plugin on an instance that has the feature turned off then fails config validation, so the mistake is caught when the config is edited instead of when the instance starts.
|
||||
Instances that have the feature turned off get the plugin disabled by default when it is added.
|
||||
|
||||
If the plugin talks to a Factorio mod, list the mod under `requiredMods` using the same format as `dependencies` in a mod's info.json, without a prefix.
|
||||
List a mod twice to give a version range:
|
||||
|
||||
```js
|
||||
export const plugin = {
|
||||
name: "foo_frobber",
|
||||
// ...
|
||||
requiredMods: ["frobber >= 1.2.0", "frobber < 2.0.0"],
|
||||
};
|
||||
```
|
||||
|
||||
An instance with the plugin loaded refuses to start if its mod pack is missing one of the mods, has it disabled, or has a version outside the range.
|
||||
Leave out the dependencies of the required mods. Factorio checks those itself.
|
||||
When the controller starts it downloads required mods it does not have, and their dependencies, from the mod portal for the Factorio version of the default mod pack.
|
||||
This needs `controller.factorio_username` and `controller.factorio_token` to be set.
|
||||
The mods still have to be added to the mod packs by hand.
|
||||
|
||||
Forks of a required mod are not supported.
|
||||
|
||||
Other constraints on config fields are expressed with a `validator` on the field definition, which throws when the value is not acceptable.
|
||||
Use `dependsOn` when the check involves other fields so that the validator runs when those change too.
|
||||
See [Configuration System](config-system.md) for details.
|
||||
@@ -998,6 +1021,20 @@ For a command the `definition` is the arguments to pass to [yargs.command](http:
|
||||
The `handler` is an async function that's invoked when the command is executed and it's passed the parsed command line arguments and a reference to the `Ctl` class of clusterioctl.
|
||||
Note that messages sent from clusterioctl needs to have `"control"` as a part of `src` for it to be accepted by the controller, see [Defining Link Messages](#defining-link-messages) for how to define the messages that can be sent to the controller.
|
||||
|
||||
Commands print their results through `ctl.output` so that `--output json` works for them:
|
||||
|
||||
```js
|
||||
handler: async function(args, ctl) {
|
||||
const result = await ctl.sendTo("controller", new messages.FrobnicateRequest(args.type));
|
||||
ctl.output.result(result, () => console.log(`Frobnicated ${result.count} foos`));
|
||||
},
|
||||
```
|
||||
|
||||
`ctl.output.result(data, human)` prints `data` as JSON in json and wire mode and calls `human` otherwise.
|
||||
`ctl.output.table(rows, map)` prints an array of objects as a JSON array, or as a table in human mode with `map` applied to each row first.
|
||||
`ctl.output.human` is true when the output is meant for reading.
|
||||
Commands that print nothing get `Command ran successfully` or `{"success": true}` printed for them, and errors thrown from the handler are printed as `{"error": "<ClassName>", "message": "<message>"}` in json and wire mode.
|
||||
|
||||
To have the command tree become part of clusterioctl it needs to be added to the rootCommand tree in the `addCommands` hook of the ctl entrypoint:
|
||||
|
||||
```js
|
||||
|
||||
Reference in new issue
Block a user