mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-19 15:33:12 +09:00
Merge upstream/master and address review
Resolves the ESM conflicts in patch.ts, Instance.ts and host.ts. The module gathering in Instance now goes through patch.loadModules with the instance's loadedPlugins, and imports use explicit extensions. Review changes: the existing-output check only treats ENOENT as "does not exist" and rethrows anything else, a --zip option keeps the output as a zip file for transfer (extracting stays the default), the --scenario option describes that it takes a path and what the default is, and the docs note that IPC is not available outside Clusterio. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
commit
187138bec5
297 files changed
+4980
-3274
No files matched your search
+41
-2
@@ -3,10 +3,10 @@
|
||||
<sub>This document describes the implementation and inner working of the configuration system in Clusterio, and unless you're developing Clusterio it's probably not going to be very useful for you.</sub>
|
||||
|
||||
Clusterio uses a field based configuration system to manage settings for the controller, instances, hosts, and the clusterioctl utility.
|
||||
Plugins can add their own config fields for the controller and instances configs.
|
||||
Plugins can add their own config fields for the controller, host and instance 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/src/config/definitions.ts](/packages/lib/src/config/definitions.ts) while plugins can add their own config field definitions to the `controllerConfigFields` and `instanceConfigFields` properties of the `plugin` export.
|
||||
The built-in config fields are defined in [packages/lib/src/config/definitions.ts](/packages/lib/src/config/definitions.ts) while plugins can add their own config field definitions to the `controllerConfigFields`, `hostConfigFields` 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.
|
||||
|
||||
|
||||
@@ -46,6 +46,45 @@ For plugins the group name is the name of the plugin, e.g., the `level` field of
|
||||
Value this config field should take in a newly initialized config.
|
||||
This can also be an async function returning the value to use.
|
||||
|
||||
**validator** (optional):
|
||||
Function called with the value being set and the config it belongs to.
|
||||
It should throw an error if the value is not acceptable, and the message of the error is passed on to whoever tried to set it.
|
||||
Common validators such as `greaterThanZero`, `greaterThanEqualZero`, `integer` and `filePath` are available on `Config.validators`, along with `optional` to skip null and `all` to combine several.
|
||||
The config is read only while the validator runs.
|
||||
|
||||
**dependsOn** (optional):
|
||||
Names of other fields the validator reads the value of.
|
||||
When one of those fields is changed the validator of this field is run again against the new value, and the change is rejected if it fails.
|
||||
|
||||
**restartRequired** (optional):
|
||||
True if a restart of the controller, host or instance the config belongs to is needed for changes to take effect.
|
||||
Changing such a field sets the `restartRequired` flag on the config, which the web interface uses to show that a restart is pending.
|
||||
Defaults to false.
|
||||
|
||||
**restartRequiredProps** (optional):
|
||||
For object fields, names of properties that have the opposite of `restartRequired`.
|
||||
Only used by the web interface to show which properties need a restart, `factorio.settings` uses it to mark the settings that are applied live.
|
||||
|
||||
**credential** (optional):
|
||||
Locations allowed to read the value of this field.
|
||||
Other locations can still change the value if allowed by `access`, which is what you want for tokens and passwords.
|
||||
|
||||
**readonly** (optional):
|
||||
Locations allowed to change the value of this field.
|
||||
Other locations can still read the value if allowed by `access`.
|
||||
|
||||
**hidden** (optional):
|
||||
True if the web interface should not show this field.
|
||||
Used for internal values that are managed by Clusterio.
|
||||
|
||||
**autoComplete** (optional):
|
||||
Value for the autocomplete attribute of the input in the web interface, e.g. `section-factorio new-password`.
|
||||
Only used for string and number fields.
|
||||
|
||||
**inputComponent** (optional):
|
||||
Name of the input component the web interface should render for this field instead of the default for its type.
|
||||
Plugins can add their own components through `inputComponents` on their web plugin class.
|
||||
|
||||
If the value for a field stored in on disk somehow ends up being invalid the field will take on the initial\_value instead when the config is loaded.
|
||||
|
||||
|
||||
|
||||
+322
-14
@@ -1,5 +1,15 @@
|
||||
# Configuration
|
||||
|
||||
Config values are changed with the `config set` commands of clusterioctl, clusteriocontroller and clusteriohost, or from the settings pages in the web interface.
|
||||
See [Managing a Cluster](/docs/managing-a-cluster.md) for the commands.
|
||||
|
||||
All values are checked against the type of the field when set.
|
||||
Some fields have additional rules on top of that, such as a number having to be greater than 0, and these are listed under the field.
|
||||
Setting a value that fails a check is rejected with an error and the old value is kept.
|
||||
|
||||
A few fields are internal to Clusterio.
|
||||
These are managed by Clusterio itself, hidden in the web interface and should not be modified by hand.
|
||||
|
||||
|
||||
## Controller Configuration
|
||||
|
||||
@@ -20,11 +30,30 @@ This is also used by plugins to store its data.
|
||||
Defaults to "database".
|
||||
|
||||
|
||||
### controller.mods_directory
|
||||
|
||||
Directory where mods shared with the cluster are stored.
|
||||
Mods uploaded through the web interface or downloaded from the mod portal end up here, and hosts fetch the mods they need for their instances from here.
|
||||
Needs to be writeable by the controller.
|
||||
|
||||
Defaults to "mods".
|
||||
|
||||
|
||||
### controller.autosave_interval
|
||||
|
||||
Interval in seconds the controller saves the data it holds in memory, such as users, instances, mod packs and plugin data, to controller.database_directory.
|
||||
The data is also saved on shutdown.
|
||||
Must be greater than 0.
|
||||
|
||||
Defaults to 60.
|
||||
|
||||
|
||||
### controller.http_port
|
||||
|
||||
Port to host HTTP server on.
|
||||
If set to null no HTTP server will be exposed.
|
||||
At least one of this and controller.https_port needs to be set to a port.
|
||||
Must be a whole number greater than 0.
|
||||
|
||||
Defaults to 8080.
|
||||
|
||||
@@ -35,6 +64,7 @@ Port to host HTTPS server on.
|
||||
Uses controller.tls_certificate and controller.tls_private_key as the certificate and private key for the HTTPS server.
|
||||
If set to null no HTTPS server will be exposed.
|
||||
At least one of this and controller.http_port needs to be set to a port.
|
||||
Must be a whole number greater than 0.
|
||||
|
||||
See the [Setting up TLS](/docs/setting-up-tls.md) document for a guide to setting up HTTPS with Clusterio.
|
||||
|
||||
@@ -51,10 +81,19 @@ interfaces.
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### controller.trusted_proxies
|
||||
|
||||
Comma separated list of IP addresses and/or CIDR blocks of reverse proxies in front of the controller to trust the `X-Forwarded-For` header from.
|
||||
When a connection comes from one of these addresses the last address in the `X-Forwarded-For` header is used as the remote address of the connection instead of the address of the proxy.
|
||||
Entries that are not valid IP addresses are logged as errors and ignored.
|
||||
|
||||
Defaults to null meaning the header is never trusted.
|
||||
|
||||
|
||||
### controller.public_url
|
||||
|
||||
Public address the controller is accessible on.
|
||||
Currently only used for `clusteriocontroller bootstrap create-ctl-config` in order to give the right url to connect to.
|
||||
Used as the URL in configs generated with `clusteriocontroller bootstrap create-ctl-config` and `clusterioctl host create-config`, and by plugins like Player Auth that need to show the address of the web interface in-game.
|
||||
This should be a full URL ending with a /.
|
||||
|
||||
Defaults to null meaning assume localhost.
|
||||
@@ -64,25 +103,34 @@ Defaults to null meaning assume localhost.
|
||||
|
||||
Used to override where static assets such as the web bundle is loaded from.
|
||||
This can be used if you want to put the static assets on a separate cdn url like `https://cdn.example.com/static/` while keeping the API hosted directly by clusterio.
|
||||
Due to a limitation on how the webpack assets are built the pathname component of the url have to be `/static/`.
|
||||
Due to a limitation on how the webpack assets are built the pathname component of the url have to be `/static/`, values with any other path are rejected.
|
||||
|
||||
See also the `clusteriocontroller copy-static` command for how to obtain the static asset files that need to be hosted.
|
||||
|
||||
Defaults to null meaning use the internally hosted assets.
|
||||
|
||||
|
||||
### controller.grafana_url
|
||||
|
||||
URL of a Grafana dashboard to link to from the overview page of the web interface, including the protocol.
|
||||
If null no link is shown.
|
||||
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### controller.tls_certificate
|
||||
|
||||
Path to TLS certificate to use for the HTTPS server when controller.https_port is configured.
|
||||
Both this and controller.tls_private_key have to be set for the controller to start with controller.https_port configured.
|
||||
|
||||
Defaults to "database/certificates/cert.crt".
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### controller.tls_private_key
|
||||
|
||||
Path to TLS private key to use for the HTTPS server when controller.https_port is configured.
|
||||
|
||||
Defaults to "database/certificates/cert.key".
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### controller.auth_secret
|
||||
@@ -90,6 +138,7 @@ Defaults to "database/certificates/cert.key".
|
||||
Base64 encoded authentication secret used to verify tokens issued to hosts, users, and sessions.
|
||||
This should contain 256 bytes of random data, and if changed will cause all tokens become invalid.
|
||||
Keep this secret if leaked an attacker could easily compromise the cluster.
|
||||
The value can only be read and changed from the controller itself, it is not available through clusterioctl or the web interface.
|
||||
|
||||
Defaults to null which means generate a secure secret on startup.
|
||||
|
||||
@@ -99,6 +148,7 @@ Defaults to null which means generate a secure secret on startup.
|
||||
Interval in seconds heartbeats are sent out at for WebSocket connections.
|
||||
If a WebSocket connection hasn't received a heartbeat in 2 times the heartbeat interval it will be considered stale and closed.
|
||||
A lower value means less time between connections going stale and them being closed.
|
||||
Must be greater than 0.
|
||||
|
||||
Defaults to 15.
|
||||
|
||||
@@ -110,6 +160,8 @@ A higher timeout gives more time for a client to recconect and resume an active
|
||||
In the case of the controller or client crashing the data loss is unavoidable.
|
||||
|
||||
Value should not be less than the configured `max_reconnect_delay` of the clients and it should be greater than 2 times `controller.heartbeat_interval`.
|
||||
Must be greater than 0.
|
||||
|
||||
Defaults to 60.
|
||||
|
||||
|
||||
@@ -117,18 +169,64 @@ Defaults to 60.
|
||||
|
||||
Timeout in seconds before a call to gather metrics from a host times out.
|
||||
This should be less than both the timeout and collection interval configured for the collection job in Prometheus.
|
||||
Must be greater than 0.
|
||||
|
||||
Defaults to 8.
|
||||
|
||||
|
||||
### controller.stream_timeout
|
||||
### controller.system_metrics_interval
|
||||
|
||||
Interval in seconds the controller gathers CPU, memory and disk usage from itself and every connected host for display in the web interface.
|
||||
Whether the controller needs a restart to apply an update is also checked on this interval.
|
||||
If 0 system metrics are not gathered.
|
||||
Must be 0 or greater.
|
||||
|
||||
Defaults to 10.
|
||||
|
||||
|
||||
### controller.proxy_stream_timeout
|
||||
|
||||
Timeout in seconds for proxy streams through the controller that has been created but is not yet sending data to be automatically closed.
|
||||
Streams that have started sending data before this timeout is not affected.
|
||||
Must be greater than 0.
|
||||
|
||||
Defaults to 15.
|
||||
|
||||
|
||||
### controller.factorio_username
|
||||
|
||||
Username of the Factorio.com account to authenticate with the Factorio API with.
|
||||
Together with controller.factorio_token this is used by the controller to download mods from the mod portal, and if controller.share_factorio_credentials_with_hosts is enabled, as the credentials in the server settings of instances.
|
||||
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### controller.factorio_token
|
||||
|
||||
Token of the Factorio.com account to authenticate with the Factorio API with, see controller.factorio_username.
|
||||
This is the token shown on your profile page on factorio.com, not your password.
|
||||
The value is treated as a credential, it can be set from anywhere but only read back from the controller itself.
|
||||
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### controller.share_factorio_credentials_with_hosts
|
||||
|
||||
If enabled hosts get controller.factorio_username and controller.factorio_token from the controller when they start an instance and put them in the server settings of that instance.
|
||||
Credentials set on the host with host.factorio_username and host.factorio_token, or on the instance through `username` and `token` in factorio.settings, take precedence over the ones from the controller.
|
||||
Disable this if you don't want the controller's credentials to be sent to the hosts.
|
||||
|
||||
Defaults to true.
|
||||
|
||||
|
||||
### controller.default_mod_pack_id
|
||||
|
||||
ID of the mod pack to use for instances that don't have factorio.mod_pack_id set.
|
||||
Instances without a mod pack of their own fail to start if this is null.
|
||||
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### controller.default_role_id
|
||||
|
||||
Role to automatically grant to new users.
|
||||
@@ -137,6 +235,55 @@ If null no role is granted.
|
||||
Defaults to 1 which correspond to the default Player role.
|
||||
|
||||
|
||||
### controller.mod_portal_cache_duration_minutes
|
||||
|
||||
Time in minutes the controller caches the list of mods fetched from the Factorio mod portal when browsing it from the web interface.
|
||||
Set to 0 to disable the cache and fetch the list on every request.
|
||||
Must be 0 or greater.
|
||||
|
||||
Defaults to 30.
|
||||
|
||||
|
||||
### controller.mod_portal_page_size
|
||||
|
||||
Number of results to request per page when fetching the list of mods from the Factorio mod portal.
|
||||
Must be greater than 0.
|
||||
|
||||
Defaults to 1000.
|
||||
|
||||
|
||||
### controller.allow_remote_updates
|
||||
|
||||
Whether the `controller update` command in clusterioctl and the update button in the web interface are allowed to update the `@clusterio/controller` package with npm.
|
||||
For security reasons this can only be changed locally with `clusteriocontroller config set` while the controller is stopped, and it is hidden in the web interface.
|
||||
See [Managing a Cluster](/docs/managing-a-cluster.md) for details on remote updates.
|
||||
|
||||
Defaults to true.
|
||||
|
||||
|
||||
### controller.allow_plugin_updates
|
||||
|
||||
Whether remote requests to update plugins installed on the controller with npm are allowed.
|
||||
Like controller.allow_remote_updates this can only be changed locally.
|
||||
|
||||
Defaults to true.
|
||||
|
||||
|
||||
### controller.allow_plugin_install
|
||||
|
||||
Whether remote requests to install new plugins on the controller with npm are allowed.
|
||||
Like controller.allow_remote_updates this can only be changed locally.
|
||||
|
||||
Defaults to false.
|
||||
|
||||
|
||||
### controller.version
|
||||
|
||||
Version of the controller package that last loaded this config.
|
||||
Set automatically on startup and used to detect when the controller has been updated or downgraded.
|
||||
Internal, hidden in the web interface and should not be changed.
|
||||
|
||||
|
||||
### <plugin_name>.load_plugin
|
||||
|
||||
Whether to load the plugin on the controller.
|
||||
@@ -158,6 +305,7 @@ Defaults to "New Host".
|
||||
### host.id
|
||||
|
||||
Immutable numeric id of the host which uniquely identifies this host in the cluster.
|
||||
Hidden in the web interface.
|
||||
|
||||
Defaults to a random 31 bit number.
|
||||
|
||||
@@ -170,6 +318,14 @@ This can either point to a Factorio server directory, or to a directory containi
|
||||
Defaults to "factorio".
|
||||
|
||||
|
||||
### host.mods_directory
|
||||
|
||||
Directory the host stores mods downloaded from the controller in.
|
||||
When an instance starts the mods in its mod pack are downloaded here if missing and then linked into the mods directory of the instance.
|
||||
|
||||
Defaults to "mods".
|
||||
|
||||
|
||||
### host.instances_directory
|
||||
|
||||
Directory to store instances in.
|
||||
@@ -189,6 +345,7 @@ Defaults to "http://localhost:8080/".
|
||||
|
||||
Access token used for authenticating with the controller.
|
||||
You can generate an access token with `clusterioctl host generate-token --id <host-id>`, or use the `clusterioctl host create-config` to create a new host config with the correct url and token in it.
|
||||
The value can only be read and changed from the host itself.
|
||||
|
||||
Defaults to "enter token here".
|
||||
|
||||
@@ -201,14 +358,82 @@ This is used by plugins like Server Select to give the correct address to switch
|
||||
Defaults to "localhost".
|
||||
|
||||
|
||||
### host.factorio_port_range
|
||||
|
||||
UDP ports the host hands out to instances that don't have factorio.game_port set.
|
||||
Written as a comma separated list of ports and/or ranges of ports separated with a dash, for example "34100-34199" or "34100, 34200-34210".
|
||||
A port is picked when the instance is started and remembered in factorio.host_assigned_game_port, so an instance keeps the same port as long as it is still free.
|
||||
Starting an instance fails if all ports in the range are taken.
|
||||
|
||||
Defaults to "34100-34199".
|
||||
|
||||
|
||||
### host.factorio_username
|
||||
|
||||
Username of the Factorio.com account to put in the server settings of instances on this host.
|
||||
If set this takes precedence over the credentials shared by the controller, but not over `username` set in factorio.settings of an instance.
|
||||
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### host.factorio_token
|
||||
|
||||
Token of the Factorio.com account to go with host.factorio_username.
|
||||
The value is treated as a credential, it can be set from anywhere but only read back from the host itself.
|
||||
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### host.max_reconnect_delay
|
||||
|
||||
Maximum delay in seconds to wait after connection to the controller is dropped before attempting to reconnect to it.
|
||||
The actual delay on each reconnect will be a random number between 0 and this configured value to avoid all clients trying to reconnect at the same time.
|
||||
Must be greater than 0.
|
||||
|
||||
Defaults to 60.
|
||||
|
||||
|
||||
### host.allow_remote_updates
|
||||
|
||||
Whether the `host update` command in clusterioctl and the update button in the web interface are allowed to update the `@clusterio/host` package with npm.
|
||||
For security reasons this can only be changed locally with `clusteriohost config set` while the host is stopped, and it is hidden in the web interface.
|
||||
See [Managing a Cluster](/docs/managing-a-cluster.md) for details on remote updates.
|
||||
|
||||
Defaults to true.
|
||||
|
||||
|
||||
### host.allow_plugin_updates
|
||||
|
||||
Whether remote requests to update plugins installed on the host with npm are allowed.
|
||||
Like host.allow_remote_updates this can only be changed locally.
|
||||
|
||||
Defaults to true.
|
||||
|
||||
|
||||
### host.allow_plugin_install
|
||||
|
||||
Whether remote requests to install new plugins on the host with npm are allowed.
|
||||
Like host.allow_remote_updates this can only be changed locally.
|
||||
|
||||
Defaults to false.
|
||||
|
||||
|
||||
### host.version
|
||||
|
||||
Version of the host package that last loaded this config.
|
||||
Set automatically on startup and used to detect when the host has been updated or downgraded.
|
||||
Internal, hidden in the web interface and should not be changed.
|
||||
|
||||
|
||||
### <plugin_name>.load_plugin
|
||||
|
||||
Whether to load the plugin on the host.
|
||||
Only plugins with a host or instance part have this field in the host config.
|
||||
Plugins not loaded on the host will not be loaded on the instances it hosts.
|
||||
|
||||
Defaults to true.
|
||||
|
||||
|
||||
## Instance Configuration
|
||||
|
||||
### instance.name
|
||||
@@ -221,6 +446,7 @@ Defaults to "New Instance".
|
||||
### instance.id
|
||||
|
||||
Imutable numeric id of the instance which uniquely identifies this instance in the cluster.
|
||||
Hidden in the web interface.
|
||||
|
||||
Defaluts to a random 31 bit integer.
|
||||
|
||||
@@ -230,6 +456,7 @@ Defaluts to a random 31 bit integer.
|
||||
Host this instance is assigned to.
|
||||
To change this you need to use the separate assign instance interface.
|
||||
After being assigned to a host the directory for the instance is created on the host.
|
||||
Internal and hidden in the web interface.
|
||||
|
||||
Defaults to null meaning not assigned.
|
||||
|
||||
@@ -253,23 +480,52 @@ Defaults to false.
|
||||
### factorio.version
|
||||
|
||||
Version of Factorio to use for this instance.
|
||||
Can be a version like "1.0.0" or special string "latest" meaning the latest version of Factorio found on the host.
|
||||
Can be a specific version like "2.0" or "2.0.15", a release channel like "stable" or "experimental", or the special string "latest" meaning the latest version of Factorio found on the host.
|
||||
A release channel is resolved to a version through the latest releases data the controller keeps, and the instance fails to start if that is unavailable.
|
||||
Values that don't match one of these forms are rejected.
|
||||
|
||||
Defaults to "latest".
|
||||
|
||||
|
||||
### factorio.executable_path
|
||||
|
||||
Path relative to the Factorio installation directory of the executable to run.
|
||||
If null the path is auto detected, which is `bin/x64/factorio` on Linux and Windows and `MacOS/factorio` on macOS.
|
||||
Only needed in special setups.
|
||||
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### factorio.shutdown_timeout
|
||||
|
||||
Time in seconds to wait for the Factorio server to exit after asking it to stop before the process is killed.
|
||||
Set to 0 to wait forever.
|
||||
Changing this while the instance is stopping restarts the timer with the new value.
|
||||
Must be 0 or greater.
|
||||
|
||||
Defaults to 300.
|
||||
|
||||
|
||||
### factorio.game_port
|
||||
|
||||
UDP port to run the Factorio server on.
|
||||
If null a random port in the dynamyc range assigned each time the instance starts.
|
||||
If null a port from host.factorio_port_range on the host is assigned to the instance.
|
||||
Negative values are rejected.
|
||||
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### factorio.host_assigned_game_port
|
||||
|
||||
Port from host.factorio_port_range the host has assigned to this instance while factorio.game_port is null.
|
||||
Internal, set by the host and only accessible from the host.
|
||||
|
||||
|
||||
### factorio.rcon_port
|
||||
|
||||
TCP port to start the RCON interface on the Factorio server on.
|
||||
If null a random port in the dynamic range is assigned each time the instance starts.
|
||||
Negative values are rejected.
|
||||
|
||||
Defaults to null.
|
||||
|
||||
@@ -278,16 +534,18 @@ Defaults to null.
|
||||
|
||||
Password to use for the RCON interafec.
|
||||
If null a random secure password is generated and used each time the instance starts.
|
||||
The value is treated as a credential and can only be read back by the controller and the host.
|
||||
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### player_online_autosave_slots
|
||||
### factorio.player_online_autosave_slots
|
||||
|
||||
Keeps a separate pool for autosaves where at least on player has been online since the previous autosave was done.
|
||||
This requires regular autosaving to be enabled and will rename autosaves to `_autosave_poN.zip` (where N is a slot number) whenever a player has been online for that save.
|
||||
The slot numbers start at 1, are incremented by 1 after each autosave that is renamed and reset back to 1 whenever this value is exceeded.
|
||||
Note that this value should be set to a higher value than the value of `autosave_slots` in `factorio.settings`.
|
||||
Setting this to a value lower than `autosave_slots` in factorio.settings is rejected, unless it is 0.
|
||||
The same check is done when factorio.settings is changed.
|
||||
Useful for preventing the loss of all progress when nobody is around on always online servers with auto pause disabled.
|
||||
|
||||
If 0 no autosave renaming takes place.
|
||||
@@ -295,12 +553,34 @@ If 0 no autosave renaming takes place.
|
||||
Defaults to 5.
|
||||
|
||||
|
||||
### factorio.mod_pack_id
|
||||
|
||||
ID of the mod pack to use on this instance.
|
||||
The mods in the pack are linked into the mods directory of the instance every time it starts, and any other files in that directory are removed.
|
||||
If null the mod pack set in controller.default_mod_pack_id is used.
|
||||
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### factorio.enable_save_patching
|
||||
|
||||
Whether to use save patching or not.
|
||||
When enabled lua code is patched into the game save before starting it.
|
||||
Most plugins require the use of save patching to function.
|
||||
Turning it off makes it possible to use Clusterio to run and manage regular vanilla games and scenarios not compatible with Clusterio.
|
||||
Plugins that need save patching can't be loaded on the instance while this is disabled.
|
||||
Disabling it while such a plugin is loaded is rejected, and so is loading such a plugin while it is disabled.
|
||||
|
||||
Defaults to true.
|
||||
|
||||
|
||||
### factorio.enable_script_commands
|
||||
|
||||
Allow Clusterio and plugins to send commands that disable achievements to the server over RCON, that is `/c`, `/sc`, `/mc`, `/cheat`, `/editor` and their long forms.
|
||||
Clusterio integrations and most plugins need this, and when enabled achievements are disabled on the server at startup.
|
||||
When disabled attempts to send such a command fail with an error.
|
||||
This does not stop players from using these commands themselves.
|
||||
Like factorio.enable_save_patching, plugins that need script commands can't be loaded on the instance while this is disabled.
|
||||
|
||||
Defaults to true.
|
||||
|
||||
@@ -312,6 +592,13 @@ Turn on the whitelist on the server.
|
||||
Defaults to false.
|
||||
|
||||
|
||||
### factorio.enable_authserver_bans
|
||||
|
||||
Pass the `--use-authserver-bans` flag to Factorio, which makes the server check connecting players against the multiplayer bans on Factorio.com and report bans and unbans done on the server back to it.
|
||||
|
||||
Defaults to false.
|
||||
|
||||
|
||||
### factorio.settings
|
||||
|
||||
Object with the settings to put into `server-settings.json` for the Factorio server.
|
||||
@@ -319,7 +606,7 @@ The settings in `data/server-settings.example.json` of the Factorio installation
|
||||
|
||||
Changes to the following properties will be applied live if the instance is running while it is changed: `afk_autokick_interval`, `allow_commands`, `autosave_interval`, `autosave_only_on_server`, `description`, `ignore_player_limit_for_returning_players`, `max_players`, `max_upload_slots`, `max_upload_in_kilobytes_per_second`, `name`, `only_admins_can_pause_the_game`, `game_password`, `require_user_verification`, `tags`, `visibility`.
|
||||
|
||||
Defaults to {"tags":["clusterio"],"auto_pause":false}.
|
||||
Defaults to a set of common settings filled in when the instance is created, such as `"tags": ["clusterio"]`, `"auto_pause": false` and a `name` and `description` based on the cluster and instance names.
|
||||
|
||||
|
||||
### factorio.verbose_logging
|
||||
@@ -330,6 +617,14 @@ This prints more messages to the log.
|
||||
Defaults to false.
|
||||
|
||||
|
||||
### factorio.console_logging
|
||||
|
||||
Pass the `--console-log` flag to Factorio to make it write the console output, such as chat, commands and player joins, to `console.log` in the instance directory.
|
||||
Useful for 3rd party tools that read the console log of the server.
|
||||
|
||||
Defaults to false.
|
||||
|
||||
|
||||
### factorio.strip_paths
|
||||
|
||||
Strip down absolute paths in the server log going to files inside the instance directory such that they are relative to the instance directory.
|
||||
@@ -352,25 +647,35 @@ Defaults to true.
|
||||
### factorio.sync_adminlist
|
||||
|
||||
Synchronize in-game admin list with admin status of the users in cluster.
|
||||
One of "disabled", "enabled" or "bidirectional".
|
||||
If enabled Clusterio will generate a new `server-adminlist.json` on instance startup based on the users in the cluster with admin status set to true, and keep the admins in sync with the users that have admin status while the instance is running.
|
||||
With "bidirectional" players promoted or demoted in-game with `/promote` and `/demote` are also updated in the cluster, and from there on the other instances.
|
||||
Configs from before this became a choice are migrated from true and false to "enabled" and "disabled".
|
||||
|
||||
Defaults to true.
|
||||
Defaults to "bidirectional".
|
||||
|
||||
|
||||
### factorio.sync_whitelist
|
||||
|
||||
Synchronize in-game whitelist with the whitelisted status of the users in the cluster.
|
||||
One of "disabled", "enabled" or "bidirectional".
|
||||
If enabled Clusterio will generate a new `server-whitelist.json` on instance startup based on the users in the cluster with whitelisted status set to true, and keep the whitelisted users in sync with the users that have whitelisted status while the instance in running.
|
||||
With "bidirectional" changes made in-game with `/whitelist` are picked up by watching `server-whitelist.json` for changes and updated in the cluster as well.
|
||||
This requires factorio.enable_whitelist to be on, as Factorio doesn't write the file otherwise.
|
||||
Configs from before this became a choice are migrated from true and false to "enabled" and "disabled".
|
||||
|
||||
Defaults to true.
|
||||
Defaults to "bidirectional".
|
||||
|
||||
|
||||
### factorio.sync_banlist
|
||||
|
||||
Synchronize in-game banlist with the banned status of users in the cluster.
|
||||
One of "disabled", "enabled" or "bidirectional".
|
||||
If enabled Clusterio will generate a new `server-banlist.json` on instance startup based on users in the cluster with banned status set to true, and keep the banned users in sync with the users that have the banned status while the instance is running.
|
||||
With "bidirectional" players banned or unbanned in-game with `/ban` and `/unban` are also updated in the cluster, and from there on the other instances.
|
||||
Configs from before this became a choice are migrated from true and false to "enabled" and "disabled".
|
||||
|
||||
Defaults to true.
|
||||
Defaults to "bidirectional".
|
||||
|
||||
|
||||
### factorio.max_concurrent_commands
|
||||
@@ -387,6 +692,7 @@ This means a high number of concurrent commands can amplify resends due to packe
|
||||
|
||||
Prior to 0.18.7 the maximum practical size of game update sent where arround 8 kB due to the UDP receive buffer on windows defaulting to this value, larger updates would not get through the receive buffer and cause the connection to drop.
|
||||
To stay below the 8 kB limit the maximum safe value for this option would be around 7000 / (3 * game_speed * maximum_segment_size), which is around 20 in normal circumstances.
|
||||
Must be greater than 0.
|
||||
|
||||
Defaults to 5.
|
||||
|
||||
@@ -394,7 +700,8 @@ Defaults to 5.
|
||||
### <plugin_name>.load_plugin
|
||||
|
||||
Whether to load the given plugin on the instance.
|
||||
Note that plugins need to be loaded on the controller in order for them to be loaded on instances.
|
||||
Note that plugins need to be loaded on the controller and the host in order for them to be loaded on instances.
|
||||
Loading a plugin that requires save patching or script commands is rejected while factorio.enable_save_patching or factorio.enable_script_commands respectively is disabled on the instance.
|
||||
|
||||
Defaults to true.
|
||||
|
||||
@@ -420,5 +727,6 @@ Defaults to null meaning complain about it not being set and exit.
|
||||
|
||||
Max duration in seconds to wait before attempting to reconnect with the controller after the connection is dropped.
|
||||
The actual delay on each reconnect will be a random number between 0 and this configured value to avoid all clients trying to reconnect at the same time.
|
||||
Must be 0 or greater.
|
||||
|
||||
Defaults to 60.
|
||||
@@ -229,8 +229,8 @@ Files containing and exporting a single class should be named the same as the cl
|
||||
Relative imports in lib package are prefixed with lib to make them easier to distinguish, as the names tend to be very generic.
|
||||
E.g.:
|
||||
|
||||
const libLink = require("./link");
|
||||
const libLuaTools = require("./lua_tools");
|
||||
import libLink from "./link";
|
||||
import libLuaTools from "./lua_tools";
|
||||
|
||||
Note that no sub-modules of the lib package is imported directly from the outside of it with the exception of `build_mod`.
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@ See the following example code for a hypothetical `Data` class with a single pro
|
||||
* A Data class example
|
||||
* @alias module:Data
|
||||
*/
|
||||
class Data {
|
||||
export class Data {
|
||||
/** @type {string} */
|
||||
member = "foo";
|
||||
|
||||
@@ -41,8 +41,6 @@ class Data {
|
||||
return json;
|
||||
}
|
||||
}
|
||||
|
||||
module.exports = Data;
|
||||
```
|
||||
|
||||
Serialising an instance of `Data` for JSON is as simple as doing `serialised = JSON.stringify(data)` as the `toJSON` method is automatically called by `JSON.stringify` to create a suitable object.
|
||||
@@ -53,14 +51,13 @@ For example a class holding a data property with an instance of the Data class f
|
||||
|
||||
```js
|
||||
// Composed.js
|
||||
"use strict";
|
||||
const Data = require("./Data");
|
||||
import Data from "./Data";
|
||||
|
||||
/**
|
||||
* Composed data class example
|
||||
* @alias module:Data
|
||||
*/
|
||||
class Composed {
|
||||
export class Composed {
|
||||
/** @type {module:Data|undefined} */
|
||||
data;
|
||||
|
||||
@@ -83,8 +80,6 @@ class Composed {
|
||||
|
||||
// toJSON is optional and not needed for this particular class
|
||||
}
|
||||
|
||||
module.exports = Composed;
|
||||
```
|
||||
|
||||
It's easy to create a new instance of Composed by calling `new Composed(new Data("spam"))` and serialising to and from JSON is the same as for Data.
|
||||
|
||||
@@ -6,6 +6,7 @@ Mods on the other hand work without modifications.
|
||||
|
||||
This can be disabled with the `factorio.enable_save_patching` config on a per instance basis, however disabling it means that modules are not loaded into the game and most plugins will not function.
|
||||
To use the modules outside of Clusterio the `npx clusteriohost create-scenario` command creates a scenario with the modules patched into it.
|
||||
Note that the IPC between the game and the host is not available outside of Clusterio, so modules that depend on it will not work as expected in such a scenario.
|
||||
|
||||
<sub>1: Before version 2.0 of Clusterio this was done at runtime with a patcher called Hotpatch, but due to the difficulty in supporting run time patching and the lack of documentation it was replace it with save patching instead.</sub>
|
||||
|
||||
|
||||
@@ -247,6 +247,13 @@ This command lists all plugins currently known to the remote. Newly installed pl
|
||||
|
||||
If remote plugin updates are enabled on the remote, this will execute `npm update --save <name>`. Changes will not be applied until the remote is restarted. If the `--restart` flag is provided, the remote will automatically restart once the update is complete.
|
||||
|
||||
### Update All
|
||||
|
||||
ctl> controller update --all [--restart]
|
||||
ctl> host update <host> --all [--restart]
|
||||
|
||||
Updates the Clusterio package and all plugins installed from npm in a single `npm update --save` command. Updating everything at once avoids ending up with multiple versions of `@clusterio/lib` in the installation. Requires both remote updates and remote plugin updates to be enabled on the remote.
|
||||
|
||||
### Install
|
||||
|
||||
ctl> controller plugin install <name> [--restart]
|
||||
|
||||
+166
-92
@@ -1,7 +1,7 @@
|
||||
# Writing Plugins
|
||||
|
||||
Plugins for Clusterio are classes written in JavaScript that run under Node.js.
|
||||
The plugin classes have pre-defined hooks that are called during various stages and operations of Clusterio.
|
||||
Plugins for Clusterio are JavaScript modules that run under Node.js.
|
||||
Each entrypoint of a plugin exports a function that attaches handlers to hooks called during various stages and operations of Clusterio.
|
||||
|
||||
|
||||
## Contents
|
||||
@@ -10,6 +10,7 @@ The plugin classes have pre-defined hooks that are called during various stages
|
||||
- [Defining the plugin class](#defining-the-plugin-class)
|
||||
- [Logging Messages](#logging-messages)
|
||||
- [Plugin Configuration](#plugin-configuration)
|
||||
- [Plugin Permissions](#plugin-permissions)
|
||||
- [Communicating with Factorio](#communicating-with-factorio)
|
||||
- [Defining Link Messages](#defining-link-messages)
|
||||
- [Sending Link Messages](#sending-link-messages)
|
||||
@@ -48,12 +49,12 @@ By default the main entrypoint is the `index.js` file, but this may be changed b
|
||||
Here's an example of `index.js`:
|
||||
|
||||
```js
|
||||
module.exports.plugin = {
|
||||
export const plugin = {
|
||||
name: "foo_frobber",
|
||||
title: "Foo Frobber",
|
||||
description: "Does advanced frobnication",
|
||||
instanceEntrypoint: "instance",
|
||||
controllerEntrypoint: "controller",
|
||||
instanceEntrypoint: "instance.js",
|
||||
controllerEntrypoint: "controller.js",
|
||||
messages: {
|
||||
/* See below */
|
||||
},
|
||||
@@ -75,7 +76,7 @@ The following properties are recognized:
|
||||
Currently not used.
|
||||
|
||||
**instanceEntrypoint**:
|
||||
Path to a Node.js module relative to the plugin directory which contains the InstancePlugin class definition for this plugin.
|
||||
Path to a Node.js module relative to the plugin directory which exports the instance entrypoint function for this plugin.
|
||||
This is an optional paramater.
|
||||
A plugin may have code only for instances but it must still be loaded on the controller in order for it to be possible to load it on an instance.
|
||||
|
||||
@@ -84,7 +85,7 @@ The following properties are recognized:
|
||||
See [Plugin Configuration](#plugin-configuration)
|
||||
|
||||
**controllerEntrypoint**:
|
||||
Path to a Node.js module relative to the plugin directory which contains the ControllerPlugin class definiton for this plugin.
|
||||
Path to a Node.js module relative to the plugin directory which exports the controller entrypoint function for this plugin.
|
||||
This is an optional parameter.
|
||||
A plugin can be made that only runs on the controller.
|
||||
|
||||
@@ -93,73 +94,85 @@ The following properties are recognized:
|
||||
See [Plugin Configuration](#plugin-configuration)
|
||||
|
||||
**ctlEntrypoint**:
|
||||
Path to a Node.js module relative to the plugin directory which contains the CtlPlugin class definition for this plugin.
|
||||
Path to a Node.js module relative to the plugin directory which exports the clusterioctl entrypoint function for this plugin.
|
||||
This is an optional paramater.
|
||||
A plugin can be made that only runs on the clusterioctl side.
|
||||
|
||||
**features**:
|
||||
Array of features the plugin needs from the instances it is loaded on, `"SavePatching"` and/or `"ScriptCommands"`.
|
||||
See [Handling Invalid Configuration](#handling-invalid-configuration)
|
||||
|
||||
**messages**:
|
||||
Object with link messages definitions for this plugin.
|
||||
See guide for [defining link messages](#defining-link-messages) below.
|
||||
|
||||
**permissions**:
|
||||
Array of permission definitions for this plugin.
|
||||
See [Plugin Permissions](#plugin-permissions)
|
||||
|
||||
The optional module folder contains a Clusterio module that will be patched into the save when the plugin is loaded.
|
||||
See the section on [Clusterio Modules](developing-for-clusterio.md) in the Developing for Clusterio document.
|
||||
The only restriction imposed on modules embedded into plugins is that they must be named the same as the plugin.
|
||||
|
||||
While there is no standard for how to organize a plugin it's recommended to put the ControllerPlugin class definition into controller.js and the InstancePlugin class definition into instance.js.
|
||||
While there is no standard for how to organize a plugin it's recommended to put the controller entrypoint into controller.js and the instance entrypoint into instance.js.
|
||||
You can put them into whatever file you want (even the same one for both).
|
||||
|
||||
For both instanceEntrypoint and controllerEntrypoint the path should not end with .js and it should use forward slashes for directory separators if any.
|
||||
The entrypoint paths must include the .js extension and use forward slashes for directory separators if any.
|
||||
|
||||
|
||||
## Defining the plugin class
|
||||
## Defining the plugin entrypoint
|
||||
|
||||
The plugin class should derive from its respective base class defined in `lib/plugin`.
|
||||
For example, to define a ControllerPlugin class the following code can be used:
|
||||
Each entrypoint module exports a default async function which is called once when the plugin is loaded.
|
||||
It is passed a context object with what the plugin needs to interact with Clusterio, and attaches handlers to the hooks it is interested in.
|
||||
For example, a controller entrypoint can look like this:
|
||||
|
||||
```js
|
||||
const { BaseControllerPlugin } = require("@clusterio/controller");
|
||||
export default async function(context) {
|
||||
const { controller, logger, plugin } = context;
|
||||
|
||||
class ControllerPlugin extends BaseControllerPlugin {
|
||||
async init() {
|
||||
this.foo = 42;
|
||||
await this.startFrobnication();
|
||||
}
|
||||
controller.hooks.save.attach(plugin.name, async () => {
|
||||
await saveFrobnicationData();
|
||||
});
|
||||
|
||||
// ...
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
ControllerPlugin,
|
||||
controller.hooks.shutdown.attach(plugin.name, async () => {
|
||||
logger.info("Stopping frobnication");
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
For the instance plugin it's exactly the same except "Controller" is replaced with "Instance", for host plugins "Host" is used and for the clusterioctl plugin "Ctl" is used.
|
||||
The available hooks that you can override are documented in the base classes.
|
||||
The context has the following properties:
|
||||
|
||||
It's best to avoid defining a constructor, but if you insist on defining one, forward all arguments to the base class.
|
||||
E.g.:
|
||||
**plugin**:
|
||||
The plugin's own info, as exported from the main entrypoint.
|
||||
|
||||
```js
|
||||
constructor(...args) {
|
||||
super(...args);
|
||||
**logger**:
|
||||
Logger for this plugin, see [Logging Messages](#logging-messages).
|
||||
|
||||
// Code here
|
||||
}
|
||||
```
|
||||
**controller**, **host**, **instance**, **hooks** or **control**:
|
||||
The object the entrypoint is loaded for.
|
||||
Controller entrypoints get `controller`, host entrypoints get `host`, instance entrypoints get both `instance` and `host`, clusterioctl entrypoints get `hooks` and web entrypoints get `control`.
|
||||
|
||||
The arguments passed may change, and attempting to modify them will result in unpredicatable behaviour.
|
||||
The async init method is always called immediatly after the constructor, so there's little reason to do this.
|
||||
The available hooks are documented on the `ControllerHooks`, `HostHooks`, `InstanceHooks`, `CtlHooks` and `WebHooks` classes.
|
||||
Handlers are attached under a name, which should be the name of the plugin, and a hook only accepts one handler per name.
|
||||
An error thrown by a handler is logged and does not affect the other handlers, the same goes for handlers that take more than 15 seconds to complete.
|
||||
|
||||
For TypeScript the context types are exported as `ControllerPluginContext`, `HostPluginContext`, `InstancePluginContext`, `CtlPluginContext` and `WebPluginContext` from their respective packages.
|
||||
|
||||
### Class based plugins
|
||||
|
||||
Plugins written as classes deriving from `BaseControllerPlugin`, `BaseHostPlugin`, `BaseInstancePlugin`, `BaseCtlPlugin` or `BaseWebPlugin` still load, but this way of defining plugins is deprecated and a warning is logged when such a plugin is loaded.
|
||||
The base class constructor attaches the `on*` methods overridden by the plugin to the corresponding hooks, and the async `init` method is called immediately after.
|
||||
|
||||
|
||||
## Logging Messages
|
||||
|
||||
The base plugin classes provide a winston logger for logging messages to the shared cluster log.
|
||||
The load context provides a winston logger for logging messages to the shared cluster log.
|
||||
For instances a copy of the log is also stored on the host the instance is on.
|
||||
To use it, pass a string to one of the log levels functions, for example:
|
||||
|
||||
```js
|
||||
async init() {
|
||||
this.logger.info("Initializing frobbing");
|
||||
export default async function(context) {
|
||||
context.logger.info("Initializing frobbing");
|
||||
}
|
||||
```
|
||||
|
||||
@@ -189,7 +202,7 @@ For guarding unexpected errors the best option is to log a short description alo
|
||||
try {
|
||||
// Operation that should not throw but may end up throwing
|
||||
} catch (err) {
|
||||
this.logger.error(`Operation failed:\n${err.stack}`);
|
||||
logger.error(`Operation failed:\n${err.stack}`);
|
||||
)
|
||||
```
|
||||
|
||||
@@ -225,12 +238,12 @@ export default {
|
||||
} satisfies lib.PluginDeclaration;
|
||||
```
|
||||
|
||||
Code inside the `ControllerPlugin` class will then be able to access the level config field through the `Config` object at `this.controller.config`, for example in the ControllerPluginClass:
|
||||
The controller entrypoint will then be able to access the level config field through the `Config` object at `controller.config`:
|
||||
|
||||
```ts
|
||||
async init() {
|
||||
let level = this.controller.config.get("foo_frobber.level");
|
||||
this.logger.info(`I got a frobnication level of ${level}`);
|
||||
export default async function(context: ControllerPluginContext) {
|
||||
const level = context.controller.config.get("foo_frobber.level");
|
||||
context.logger.info(`I got a frobnication level of ${level}`);
|
||||
}
|
||||
```
|
||||
|
||||
@@ -240,33 +253,76 @@ See [Configuration System](config-system.md) for more details on how this system
|
||||
|
||||
### Handling Invalid Configuration
|
||||
|
||||
If the plugin requires a certain feature to be enabled to function it should throw an error during init if this is not the case.
|
||||
The most common such feature is the save patching, which can be disabled to run vanilla or scenarios not compatible with Clusterio.
|
||||
For example:
|
||||
If the plugin requires save patching or script commands to function, which can be disabled to run vanilla or scenarios not compatible with Clusterio, declare it under `features` in the `plugin` export:
|
||||
|
||||
```js
|
||||
async init() {
|
||||
if (!this.instance.config.get("factorio.enable_save_patching")) {
|
||||
throw new Error("foo_frobber plugin requires save patching.");
|
||||
export const plugin = {
|
||||
name: "foo_frobber",
|
||||
// ...
|
||||
features: ["SavePatching"],
|
||||
};
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## Plugin Permissions
|
||||
|
||||
Permissions are granted to roles and checked on users, both on the controller and in the web UI.
|
||||
A plugin declares the permissions it uses under `permissions` in the `plugin` export.
|
||||
Names must start with the plugin name followed by a dot.
|
||||
For example in index.ts:
|
||||
|
||||
```ts
|
||||
import type * as lib from "@clusterio/lib";
|
||||
|
||||
declare module "@clusterio/lib" {
|
||||
// Extend the interface of known permission names so that
|
||||
// user.checkPermission(...) accepts our permission.
|
||||
export interface Permissions {
|
||||
"foo_frobber.frobnicate": never;
|
||||
}
|
||||
}
|
||||
|
||||
export default {
|
||||
...
|
||||
permissions: [
|
||||
{
|
||||
name: "foo_frobber.frobnicate",
|
||||
title: "Frobnicate",
|
||||
description: "Run frobnication on instances.",
|
||||
grantByDefault: false, // Whether the generated Player role is granted this permission
|
||||
},
|
||||
],
|
||||
} satisfies lib.PluginDeclaration;
|
||||
```
|
||||
|
||||
The `Permissions` interface only exists at the type level, its values are always `never` and only the keys are used.
|
||||
Adding your permission names to it gives you autocomplete and a compile error on typos when calling `user.checkPermission`, `account.hasPermission` or setting the `permission` of a web UI page.
|
||||
In JavaScript the `declare module` block is not needed.
|
||||
|
||||
Permissions declared this way are registered when the plugin is loaded.
|
||||
The older `lib.definePermission()` function still works, but a plugin should not use both for the same permission name.
|
||||
|
||||
|
||||
## Communicating with Factorio
|
||||
|
||||
For pushing data into Factorio there's RCON, which lets you send arbitrary Lua commands to invoke whatever code you want in the game.
|
||||
This is done by calling the `sendRcon` method on the plugin object.
|
||||
This is done by calling the `sendRcon` method on the instance.
|
||||
For example:
|
||||
|
||||
```js
|
||||
async onStart() {
|
||||
let response = await this.sendRcon(
|
||||
instance.hooks.start.attach(plugin.name, async () => {
|
||||
const response = await instance.sendRcon(
|
||||
"/sc rcon.print('data')"
|
||||
);
|
||||
|
||||
// Do stuff with response.
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
Because data into Factorio is streamed at a rate of 3-6 kB/s by default, it is recommended to avoid sending large commands as much as possible, and to strip down the data on the ones you send to only what's strictly necessary.
|
||||
@@ -279,15 +335,16 @@ From a plugin you listen for an event named `ipc-channel_name` in order to get d
|
||||
For example in the plugin code:
|
||||
|
||||
```js
|
||||
async init() {
|
||||
this.instance.server.on("ipc-my_plugin_foo", content =>
|
||||
this.handleFoo(content).catch(err => this.logger.error(
|
||||
export default async function(context) {
|
||||
const { instance, logger } = context;
|
||||
instance.server.on("ipc-my_plugin_foo", content =>
|
||||
handleFoo(content).catch(err => logger.error(
|
||||
`Error handling foo:\n${err.stack}`
|
||||
))
|
||||
);
|
||||
}
|
||||
|
||||
async handleFoo(content) {
|
||||
async function handleFoo(content) {
|
||||
// Do stuff with content
|
||||
}
|
||||
```
|
||||
@@ -304,11 +361,11 @@ clusterio_api.send_json("my_plugin_foo", { data = 123 })
|
||||
For convience a helper function is exposed on server specifically for handling IPC events.
|
||||
|
||||
```js
|
||||
async init() {
|
||||
this.instance.server.handle("my_plugin_foo", this.handleFoo.bind(this));
|
||||
export default async function(context) {
|
||||
context.instance.server.handle("my_plugin_foo", handleFoo);
|
||||
}
|
||||
|
||||
async handleFoo(content) {
|
||||
async function handleFoo(content) {
|
||||
// Do stuff with content
|
||||
}
|
||||
```
|
||||
@@ -445,9 +502,9 @@ Link messages are sent by calling the `.sendTo()` method on a connection object
|
||||
For example:
|
||||
|
||||
```js
|
||||
// In an InstancePlugin class
|
||||
async frobnicate() {
|
||||
const response = await this.instance.sendTo("controller", new messages.Frobnicate({
|
||||
// In an instance entrypoint
|
||||
async function frobnicate(instance) {
|
||||
const response = await instance.sendTo("controller", new messages.Frobnicate({
|
||||
verbosity: 2,
|
||||
special: false,
|
||||
}));
|
||||
@@ -464,14 +521,14 @@ Here is what that looks like in practice:
|
||||
|
||||
```js
|
||||
// ❌ BAD: The extracted method loses its `this` binding and crashes when called.
|
||||
const send = this.instance.sendTo;
|
||||
const send = instance.sendTo;
|
||||
send("controller", new messages.Frobnicate({ foo: "bar" }));
|
||||
|
||||
// ✅ GOOD: Call it directly on the connection object. (Cast args/results here if needed).
|
||||
this.instance.sendTo("controller", new messages.Frobnicate({ foo: "bar" }));
|
||||
instance.sendTo("controller", new messages.Frobnicate({ foo: "bar" }));
|
||||
|
||||
// ✅ GOOD: Explicitly bind the receiver if you need to pass a method as a value (like a handler).
|
||||
this.instance.handle(messages.Frobnicate, this.handleFrobnicate.bind(this));
|
||||
instance.handle(messages.Frobnicate, plugin.handleFrobnicate.bind(plugin));
|
||||
```
|
||||
|
||||
For classes with `static type = "request"` the send method is async and returns a promise that resolves to the response data received from the target it was sent to, or rejects with an error if the request failed.
|
||||
@@ -493,23 +550,23 @@ sendTo({ controlId: 123 }, message);
|
||||
|
||||
There are a few connection related events that plugins neeed to repsond to in order to avoid data loss and connection problems.
|
||||
The most important is the prepare disconnect for the link between controller and host.
|
||||
This is signaled to `ControllerPlugin` classes via the `onPrepareHostDisconnect` hook and to `InstancePlugin` classes via the `onPrepareControllerDisconnect` hook.
|
||||
This is signaled to controller plugins via the `prepareHostDisconnect` hook and to instance plugins via the `prepareControllerDisconnect` hook.
|
||||
|
||||
After the prepare disconnect the connection will be closed, which will result in pending requests and events being dropped.
|
||||
Plugins must respond to the prepare disconnect by stopping any processess it does that send events or requests over the link in question.
|
||||
This can be accomplished either through listening for the prepare disconnect hook, or by checking the `connected` property of the `HostConnection` class and `Host` class on the controller and host respectively.
|
||||
For example the sending of an event from an `InstancePlugin` class can be stopped while the connection is not connected, not in the dropped state, and not in the process of discunnecting by using the following code:
|
||||
For example the sending of an event from an instance plugin can be stopped while the connection is not connected, not in the dropped state, and not in the process of discunnecting by using the following code:
|
||||
|
||||
```js
|
||||
if (this.host.connected) {
|
||||
this.instance.sendTo("controller", new messages.Frobnicate({ foo: "bar" }));
|
||||
if (host.connected) {
|
||||
instance.sendTo("controller", new messages.Frobnicate({ foo: "bar" }));
|
||||
}
|
||||
```
|
||||
|
||||
If the event or request needs to be sent to the controller it can be put into a queue stored on the plugin instance and sent out when the connection is established again.
|
||||
The re-establishement of the connection is notified to plugins via the `connect` event to the `onControllerConnectionEvent` and `onHostConnectionEvent` hooks.
|
||||
If the event or request needs to be sent to the controller it can be put into a queue and sent out when the connection is established again.
|
||||
The re-establishement of the connection is notified to plugins via the `connect` event to the `controllerConnectionEvent` and `hostConnectionEvent` hooks.
|
||||
|
||||
The second connection event which is of lesser importance to respond to is the `drop` connection event served through `onControllerConnectionEvent` for `InstancePlugin` classes and through `onHostConnectionEvent` for `ControllerPlugin` classes.
|
||||
The second connection event which is of lesser importance to respond to is the `drop` connection event served through `controllerConnectionEvent` for instance plugins and through `hostConnectionEvent` for controller plugins.
|
||||
This is raised when the connection between the controller and host in question is lost, most likely due to networking issues.
|
||||
When in the dropped state the host will keep trying to reconnect to the controller in order to re-establish it, and if successful no events or requests will be lost.
|
||||
However while in the dropped state any requests and events sent gets queued up in memory until the connection is either re-established or the session times out.
|
||||
@@ -525,7 +582,7 @@ In its simplest form collecting data from plugins consists of defining the metri
|
||||
For example:
|
||||
|
||||
```js
|
||||
const { Counter } = require("@clusterio/lib");
|
||||
import { Counter } from "@clusterio/lib";
|
||||
|
||||
const fooMetric = new Counter(
|
||||
"clusterio_foo_frobber_foo_metric", "Measures the level of foo",
|
||||
@@ -541,7 +598,7 @@ It's recommended that plugin metrics follow `clusterio_<plugin_name>_<metric_nam
|
||||
For metrics that are per-instance, you must define an `instance_id` label and set it accordingly, for example:
|
||||
|
||||
```js
|
||||
const { Counter } = require("@clusterio/lib");
|
||||
import { Counter } from "@clusterio/lib";
|
||||
|
||||
const barMetric = new Gauge(
|
||||
"clusterio_foo_frobber_bar_metric", "Bar instance level",
|
||||
@@ -549,14 +606,39 @@ const barMetric = new Gauge(
|
||||
);
|
||||
|
||||
// Somewhere in the instance plugin code
|
||||
barMetric.labels(String(this.instance.id)).set(someValue);
|
||||
barMetric.labels(String(instance.id)).set(someValue);
|
||||
```
|
||||
|
||||
Metrics are automatically registered to the default registry, and this default registry is automatically polled by the controller on hosts.
|
||||
This means that it's important that you place the definition of the metric at module level so that it's not created more than once over the lifetime of a host.
|
||||
Since the metrics remember their values and would continue to be exported after an instance is shutdown, there's code at instance shutdown that removes all the values where the `instance_id` label matches the id of the instance shut down.
|
||||
|
||||
For statistics you need to update on collection there's an `onMetrics` hook on both controller and instance plugins that is run before the metrics in the default registry are collected.
|
||||
For statistics you need to update on collection there's a `metrics` hook on the controller, host and instance that is run before the metrics in the default registry are collected.
|
||||
|
||||
```js
|
||||
import { Gauge } from "@clusterio/lib";
|
||||
|
||||
const frobnicationsMetric = new Gauge(
|
||||
"clusterio_foo_frobber_frobnications", "Frobnications currently in progress"
|
||||
);
|
||||
|
||||
// In the controller entrypoint
|
||||
controller.hooks.metrics.attach(plugin.name, async () => {
|
||||
frobnicationsMetric.set(frobnications.size);
|
||||
});
|
||||
```
|
||||
|
||||
A handler may also return the results of collecting collectors that are not in the default registry, and they are added to the response.
|
||||
|
||||
```js
|
||||
import { CollectorRegistry, Counter } from "@clusterio/lib";
|
||||
|
||||
const fooRegistry = new CollectorRegistry();
|
||||
const fooCounter = new Counter("clusterio_foo_frobber_foos", "Foos frobbed", { register: false });
|
||||
fooRegistry.register(fooCounter);
|
||||
|
||||
controller.hooks.metrics.attach(plugin.name, async () => fooRegistry.collect());
|
||||
```
|
||||
|
||||
|
||||
## Adding Custom Commands to clusterioctl
|
||||
@@ -565,7 +647,7 @@ The control entrypoint for plugins allows you to extend clustectl with your own
|
||||
The creation of custom commands typically starts with defining a command tree for the plugin:
|
||||
|
||||
```js
|
||||
const { Command, CommandTree } = require("@clusterio/lib");
|
||||
import { Command, CommandTree } from "@clusterio/lib";
|
||||
const fooFrobberCommands = new CommandTree({
|
||||
name: "foo-frobber", description: "Foo Frobber Plugin commands"
|
||||
});
|
||||
@@ -574,7 +656,7 @@ const fooFrobberCommands = new CommandTree({
|
||||
Then commands are added to the the plugin's command tree:
|
||||
|
||||
```js
|
||||
const info = require("./info");
|
||||
import { messages } from "./index.js";
|
||||
|
||||
fooFrobberCommands.add(new Command({
|
||||
definition: ["frobnicate <type>", "Do frobnications", (yargs) => {
|
||||
@@ -593,22 +675,14 @@ fooFrobberCommands.add(new Command({
|
||||
|
||||
For a command the `definition` is the arguments to pass to [yargs.command](http://yargs.js.org/docs/#api-reference-commandcmd-desc-builder-handler) (see also [yargs.positional](http://yargs.js.org/docs/#api-reference-positionalkey-opt) and [yargs.options](http://yargs.js.org/docs/#api-reference-optionskey-opt) for setting up positional and optional arguments to commands).
|
||||
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 `Control` class of clusterioctl.
|
||||
It's possible to optain a reference to the plugin class with `control.plugins.get(info.name)`.
|
||||
|
||||
Note that messages sent from clusterioctl needs to have `"control-controller"` as a part of the links array 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.
|
||||
|
||||
To have the command tree become part of clusterioctl it needs to be added to the rootCommand tree in `addCommands` callback of the Ctl plugin:
|
||||
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
|
||||
const { BaseCtlPlugin } = require("@clusterio/ctl");
|
||||
|
||||
class CtlPlugin extends BaseCtlPlugin {
|
||||
async addCommands(rootCommand) {
|
||||
export default async function(context) {
|
||||
context.hooks.addCommands.attach(context.plugin.name, async (rootCommand) => {
|
||||
rootCommand.add(fooFrobberCommands);
|
||||
}
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
CtlPlugin,
|
||||
});
|
||||
}
|
||||
```
|
||||
Reference in new issue
Block a user