mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-23 08:23:12 +09:00
Move developer docs to docs/devs
docs/ now holds the documents for people running a cluster, and docs/devs/ holds the ones for Clusterio and plugin developers. Links to the moved files are updated across the repository. Adds an Audiences decision recording which document covers what. Part of #1254 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
0190394a99
commit
95f808a02f
15 files changed
+59
-47
No files matched your search
@@ -2,13 +2,13 @@
|
||||
|
||||
Clusterio manages distributed Factorio servers through a controller, hosts, and plugins.
|
||||
|
||||
Read [contributing](docs/contributing.md) for the project map, setup, commands, debugging, tests, and code style.
|
||||
For PR reviews, follow the [review guide](docs/pr-review-guide.md), including its candidate ledger and final evidence audit.
|
||||
Read [contributing](docs/devs/contributing.md) for the project map, setup, commands, debugging, tests, and code style.
|
||||
For PR reviews, follow the [review guide](docs/devs/pr-review-guide.md), including its candidate ledger and final evidence audit.
|
||||
Use the detailed guides for the affected area:
|
||||
|
||||
- [Communication and routing](docs/communication.md), [wire protocol](docs/devs/protocol.md), and [configuration](docs/config-system.md).
|
||||
- [Plugins](docs/writing-plugins.md), [plugin migration](docs/devs/plugin-migration-to-2.0.md), and [Factorio/Lua](docs/developing-for-clusterio.md).
|
||||
- [Compatibility policies](docs/decisions.md) and [releases](docs/release-workflow.md).
|
||||
- [Communication and routing](docs/devs/communication.md), [wire protocol](docs/devs/protocol.md), and [configuration](docs/devs/config-system.md).
|
||||
- [Plugins](docs/devs/writing-plugins.md), [plugin migration](docs/devs/plugin-migration-to-2.0.md), and [Factorio/Lua](docs/devs/developing-for-clusterio.md).
|
||||
- [Compatibility policies](docs/devs/decisions.md) and [releases](docs/devs/release-workflow.md).
|
||||
|
||||
|
||||
## Working rules
|
||||
@@ -20,7 +20,7 @@ Use the detailed guides for the affected area:
|
||||
Update affected documentation in the same change.
|
||||
- Follow nearby code and `.oxlintrc.json`: tabs, double quotes, semicolons, and `.js` extensions in relative TypeScript imports.
|
||||
Import shared public APIs through `@clusterio/lib` and check Node/browser exports when changing them.
|
||||
- Run commands from the root using the pinned pnpm version and the [documented Node requirements](docs/contributing.md#supported-nodejs-and-factorio-versions).
|
||||
- Run commands from the root using the pinned pnpm version and the [documented Node requirements](docs/devs/contributing.md#supported-nodejs-and-factorio-versions).
|
||||
Install with `pnpm install --no-frozen-lockfile`; the lockfile is intentionally ignored.
|
||||
- `pnpm build` compiles TypeScript.
|
||||
It does not regenerate validators or production web bundles; use the appropriate package's `prepare` script.
|
||||
@@ -30,7 +30,7 @@ Use the detailed guides for the affected area:
|
||||
The harness needs Factorio, recreates `temp/test/`, and shares ports 8880/4443; do not run competing suites.
|
||||
- Report checks, failures, skips, and unverified behavior precisely.
|
||||
Documentation-only changes need path, command, and formatting checks.
|
||||
- Preview cleanup with `node scripts/clean.js --dry-run`; see the [cleanup scopes](docs/contributing.md#cleaning-generated-and-runtime-files).
|
||||
- Preview cleanup with `node scripts/clean.js --dry-run`; see the [cleanup scopes](docs/devs/contributing.md#cleaning-generated-and-runtime-files).
|
||||
Runtime-data deletion and release publication require explicit authorization.
|
||||
Keep local configs, credentials, runtime data, and generated output out of commits.
|
||||
- Follow the [PR template](.github/pull_request_template.md), including `### Changelog` (`None.` when appropriate).
|
||||
@@ -20,7 +20,7 @@ Plugin authors should also follow the [2.0 migration guide](docs/devs/plugin-mig
|
||||
### Ways to support me/the project:
|
||||
|
||||
* Contribute with code/documentation.
|
||||
See [Contributing](docs/contributing.md) for how to make pull requests.
|
||||
See [Contributing](docs/devs/contributing.md) for how to make pull requests.
|
||||
Always nice to move the project forward.
|
||||
|
||||
* Support me monetarily on [patreon](https://www.patreon.com/danielv123) or paypal: danielv@live.no
|
||||
@@ -93,7 +93,7 @@ The installer offers the six plugins maintained in this repository.
|
||||
Community plugins are versioned and released independently of Clusterio; check their compatibility before installing them manually.
|
||||
|
||||
Want to make your own plugin?
|
||||
Check out the documentation on [Writing Plugins](/docs/writing-plugins.md) for where to start.
|
||||
Check out the documentation on [Writing Plugins](/docs/devs/writing-plugins.md) for where to start.
|
||||
If you have a plugin written for an earlier 2.0 alpha, see [Migrating Plugins to 2.0](/docs/devs/plugin-migration-to-2.0.md).
|
||||
Note that from 2.0 onwards minor versions of Clusterio may contain breaking changes for plugins, while breaking changes for users running a cluster are held back for major versions.
|
||||
|
||||
@@ -107,7 +107,7 @@ If you already have a supported Node.js version installed, you can set it up in
|
||||
npm init "@clusterio"
|
||||
|
||||
Otherwise see below for OS specific instructions.
|
||||
Check out all our of decisions for [node, factorio, and operation support](/docs/decisions.md#supportability).
|
||||
Check out all our of decisions for [node, factorio, and operation support](/docs/devs/decisions.md#supportability).
|
||||
|
||||
### Ubuntu setup
|
||||
|
||||
|
||||
@@ -2,12 +2,12 @@
|
||||
|
||||
Clusterio uses links, connectors, and message classes to communicate between controllers, hosts, instances, and control clients.
|
||||
A link sends and receives messages through a connector, while message classes define the requests and events that can be exchanged.
|
||||
See the [system overview](how-it-works.md#system-overview) for a diagram of the processes and their connections, and the [protocol reference](devs/protocol.md) for wire formats and session flow.
|
||||
See the [system overview](../how-it-works.md#system-overview) for a diagram of the processes and their connections, and the [protocol reference](protocol.md) for wire formats and session flow.
|
||||
|
||||
|
||||
## Links and routing
|
||||
|
||||
[Link](../packages/lib/src/link/link.ts) handles request/response matching, event dispatch, message registration, and routing through an attached router.
|
||||
[Link](../../packages/lib/src/link/link.ts) handles request/response matching, event dispatch, message registration, and routing through an attached router.
|
||||
Its connector identifies the local and remote endpoints through `connector.src` and `connector.dst`, both `Address` objects.
|
||||
|
||||
The controller's `WsServer` stores one link for each host or control connection.
|
||||
@@ -22,22 +22,22 @@ See [message permissions](writing-plugins.md#static-permission).
|
||||
At the destination, the registered schema validates the payload and `fromJSON` restores the message before its handler runs.
|
||||
|
||||
Routing can perform work before the destination handler runs.
|
||||
In particular, the [host router](../packages/host/src/Host.ts) can start or wake an instance for messages marked as instance-starting.
|
||||
In particular, the [host router](../../packages/host/src/Host.ts) can start or wake an instance for messages marked as instance-starting.
|
||||
|
||||
|
||||
## Connectors and sessions
|
||||
|
||||
[Connectors](../packages/lib/src/link/connectors.ts) transport messages, assign sequence numbers, and deliver incoming messages to links.
|
||||
[Connectors](../../packages/lib/src/link/connectors.ts) transport messages, assign sequence numbers, and deliver incoming messages to links.
|
||||
WebSocket connectors connect hosts and control clients to the controller and validate incoming message structures, including their type and addresses.
|
||||
Hosts and instances share a Node.js process and communicate in memory through paired `VirtualConnector` objects.
|
||||
|
||||
The protocol reference describes [connection and recovery behavior](devs/protocol.md#connection-flow), [connector states and events](devs/protocol.md#connector-flow), and [graceful disconnects](devs/protocol.md#graceful-disconnect).
|
||||
The protocol reference describes [connection and recovery behavior](protocol.md#connection-flow), [connector states and events](protocol.md#connector-flow), and [graceful disconnects](protocol.md#graceful-disconnect).
|
||||
For handling these events in a plugin, including queueing work and preparing for disconnection, see [connection handling](writing-plugins.md#handling-connection-events).
|
||||
|
||||
|
||||
## Message definitions and registration
|
||||
|
||||
Core request and event classes live under [packages/lib/src/data/](../packages/lib/src/data/).
|
||||
Core request and event classes live under [packages/lib/src/data/](../../packages/lib/src/data/).
|
||||
Their static `type`, `src`, and `dst` properties specify the message type and allowed endpoint types, while their schema and permission fields define the payload and access rules.
|
||||
Plugin classes also supply a `plugin` name.
|
||||
|
||||
@@ -53,6 +53,6 @@ Use broadcast destinations only for events.
|
||||
When using a request's source as a later event destination, remove its request ID with `Address.withoutRequestId()`.
|
||||
See [writing plugins](writing-plugins.md#defining-link-messages) for a complete example.
|
||||
|
||||
When changing a wire message structure in [messages_core.ts](../packages/lib/src/data/messages_core.ts), rebuild the packages with `pnpm -r run prepare` to regenerate the standalone validator.
|
||||
When changing a wire message structure in [messages_core.ts](../../packages/lib/src/data/messages_core.ts), rebuild the packages with `pnpm -r run prepare` to regenerate the standalone validator.
|
||||
When changing a request or event class, keep serialization, allowed endpoints, permission checks, registration, and handlers consistent.
|
||||
The [contributor guide](contributing.md#checking-your-code-for-errors) explains how to run focused tests.
|
||||
File renamed without changes.
@@ -4,7 +4,7 @@ You are probably reading this because you want to contribute code to Clusterio.
|
||||
Great! We need people like you.
|
||||
Though we have some conventions and workflows that we kindly ask you to follow.
|
||||
This document covers the development workflow, commands, and repository layout.
|
||||
Read our [past decisions](/docs/decisions.md) for compatibility policies and design rationale.
|
||||
Read our [past decisions](/docs/devs/decisions.md) for compatibility policies and design rationale.
|
||||
|
||||
|
||||
## Contents
|
||||
@@ -51,7 +51,7 @@ Clusterio manages distributed Factorio servers through a controller, hosts, and
|
||||
| `packages/host/lua/` | Factorio mod sources, including `clusterio_lib`. |
|
||||
| `test/` | Root test suite, fixtures, helpers, integration harness, and manual tests. Plugin tests also live under `plugins/*/test/`. |
|
||||
|
||||
Start with [how it works](how-it-works.md), [communication](communication.md), and the [config system](config-system.md) for architecture.
|
||||
Start with [how it works](../how-it-works.md), [communication](communication.md), and the [config system](config-system.md) for architecture.
|
||||
See [writing plugins](writing-plugins.md) and [developing for Clusterio](developing-for-clusterio.md) for plugin and Factorio contracts.
|
||||
|
||||
|
||||
@@ -223,7 +223,7 @@ It locates Factorio through `host.factorio_directory` in root `config-host.json`
|
||||
The full harness currently requires a usable Factorio installation: a missing directory fails discovery, and an empty directory fails setup while selecting a version.
|
||||
Some individual tests have conditional skips, but these do not make a full run without Factorio succeed.
|
||||
|
||||
Use the relevant production bundle, mod build, or [manual scenario](../test/manual/README.md) for changes affecting those surfaces.
|
||||
Use the relevant production bundle, mod build, or [manual scenario](../../test/manual/README.md) for changes affecting those surfaces.
|
||||
For documentation changes, check that links, paths, and example commands are correct.
|
||||
|
||||
|
||||
@@ -261,8 +261,8 @@ If there are no changelog entries to add, remove the code block and start the ch
|
||||
The version-compat job in CI runs the local controller with the latest published host, and the published controller with the local host.
|
||||
It fails if a link message changed its src, dst, data or response schema since that release.
|
||||
Control is left out of src and dst, and messages that only go between control and the controller are not checked, as the web UI is served by the controller it talks to.
|
||||
If the break is intended, add an entry to [scripts/version-compat-breaks.json](../scripts/version-compat-breaks.json) in the same pull request.
|
||||
Breaking changes are only accepted if the next release is intended to include them, see our decision on [breaking changes](/docs/decisions.md#breaking-changes).
|
||||
If the break is intended, add an entry to [scripts/version-compat-breaks.json](../../scripts/version-compat-breaks.json) in the same pull request.
|
||||
Breaking changes are only accepted if the next release is intended to include them, see our decision on [breaking changes](/docs/devs/decisions.md#breaking-changes).
|
||||
The entry is keyed by the published version directly before the breaking change was introduced, which is the latest release at the time.
|
||||
Every entry needs the pull request number, a reason saying what breaks, and an impact saying why end users are not or only minimally affected.
|
||||
|
||||
@@ -332,35 +332,35 @@ GitHub has no interface or functionality for keeping the branches in your fork u
|
||||
|
||||
### Publishing releases to npm
|
||||
|
||||
For publishing new releases see [package release workflow](./release-workflow.md#packages).
|
||||
For publishing new releases see [package release workflow](release-workflow.md#packages).
|
||||
|
||||
## Changelog
|
||||
|
||||
There's a [Changelog](../CHANGELOG.md) in the root of the project.
|
||||
There's a [Changelog](../../CHANGELOG.md) in the root of the project.
|
||||
If you make changes that are visible to users of this project you should add an entry to the changelog describing what has changed.
|
||||
The format of this log should be self explanatory, please follow it carefully. Please make sure to document any [breaking changes](/docs/decisions.md#breaking-changes).
|
||||
The format of this log should be self explanatory, please follow it carefully. Please make sure to document any [breaking changes](/docs/devs/decisions.md#breaking-changes).
|
||||
|
||||
|
||||
## Supported Node.js and Factorio Versions
|
||||
|
||||
For development, use the latest Node.js LTS release, following the [installation instructions](../README.md#installation).
|
||||
For development, use the latest Node.js LTS release, following the [installation instructions](../../README.md#installation).
|
||||
Make sure the Node.js built-in APIs and npm packages you use remain compatible with the supported versions.
|
||||
The GitHub Actions tests run every Factorio version on the latest Node.js, and every other supported Node.js version with the latest Factorio only, which keeps the number of jobs within GitHub's concurrent job limit.
|
||||
Coverage is collected on the oldest supported Node.js; see the [CI workflow](../.github/workflows/node.js.yml) for the version matrix.
|
||||
Coverage is collected on the oldest supported Node.js; see the [CI workflow](../../.github/workflows/node.js.yml) for the version matrix.
|
||||
|
||||
For Factorio, active support covers the latest stable version and the previous major version, using version lines such as 2.1, 2.0 and 1.1 as described in the [Factorio support policy](decisions.md#factorio).
|
||||
Older versions from 0.17 onwards receive passive support where it does not restrict actively supported versions.
|
||||
Check the Lua API documentation for the Factorio versions your changes target and preserve compatibility with the actively supported versions.
|
||||
The GitHub Actions tests use pinned Factorio releases; see the [CI workflow](../.github/workflows/node.js.yml) for the current version matrix.
|
||||
The GitHub Actions tests use pinned Factorio releases; see the [CI workflow](../../.github/workflows/node.js.yml) for the current version matrix.
|
||||
|
||||
Check out all our of decisions for [node, factorio, and operation support](/docs/decisions.md#supportability).
|
||||
Check out all our of decisions for [node, factorio, and operation support](/docs/devs/decisions.md#supportability).
|
||||
|
||||
|
||||
## Code Style
|
||||
|
||||
The style of the code is a bit of a mixed bag at the moment.
|
||||
But there are at least a few things that have been agreed upon.
|
||||
See our [decisions document](/docs/decisions.md) for justifcations.
|
||||
See our [decisions document](/docs/devs/decisions.md) for justifcations.
|
||||
|
||||
### Naming style
|
||||
|
||||
@@ -8,6 +8,7 @@ If there is a particular issue or concern you would like the team to comment on
|
||||
<!-- For code style, add (Lang) to section names if present in both -->
|
||||
|
||||
1. Documentation
|
||||
- [Audiences](#audiences)
|
||||
- [Decision Log](#decision-log)
|
||||
- [TSDoc](#tsdoc)
|
||||
2. Code Style (General)
|
||||
@@ -70,6 +71,17 @@ Remember to have one sentence per line.
|
||||
|
||||
## Documentation
|
||||
|
||||
### Audiences
|
||||
|
||||
🧾 21st November 2026 | [Github Issue #1254](https://github.com/clusterio/clusterio/issues/1254)
|
||||
|
||||
> Write each document for one audience and keep it where that audience looks: `docs/` for cluster admins and `docs/devs/` for Clusterio and plugin developers.
|
||||
|
||||
Admins were confused by developer documents mixed in with the guides they needed, and some topics were covered in several places that drifted apart.
|
||||
The root README covers installing and starting a cluster, `docs/` covers running it, the package READMEs cover the command line options of each package, and `docs/devs/` covers developing Clusterio and plugins.
|
||||
When a topic belongs to another document, link to it instead of repeating it.
|
||||
|
||||
|
||||
### Decision Log
|
||||
|
||||
🧾 22nd December 2024 | Discord Voice Call
|
||||
@@ -462,7 +474,7 @@ While we aim to increase the number of useful checks performed by CI in the futu
|
||||
> We publish packages and mods when a maintainer publishes a stable GitHub release.
|
||||
|
||||
Changes merged into the main branch are bundled into releases before publication.
|
||||
Publishing a stable GitHub release triggers the [Publish workflow](../.github/workflows/publish.yml), which publishes npm packages and Factorio mods.
|
||||
Publishing a stable GitHub release triggers the [Publish workflow](../../.github/workflows/publish.yml), which publishes npm packages and Factorio mods.
|
||||
Publishing a prerelease or pushing a tag alone does not trigger publication.
|
||||
Running clusters are updated by their operators.
|
||||
See the [release workflow](release-workflow.md) for the publication procedure.
|
||||
@@ -484,5 +496,5 @@ However, we are always looking for a better framework which is worth the effort
|
||||
|
||||
> We perform all tests through GitHub actions using Ubuntu latest, using all supported versions of node and all supported versions of factorio.
|
||||
|
||||
The [current CI workflow](../.github/workflows/node.js.yml) tests selected Node.js major versions and pinned Factorio releases.
|
||||
The [current CI workflow](../../.github/workflows/node.js.yml) tests selected Node.js major versions and pinned Factorio releases.
|
||||
However, we do not conduct tests on all supported operating systems, as the added demand on our testing resources would be significant, and the value it would provide for a cross-platform engine like NodeJS would be limited.
|
||||
@@ -122,7 +122,7 @@ There's also the `add_libraries` function exported by event_handler, which accep
|
||||
## Communicating with Clusterio
|
||||
|
||||
Clusterio uses a homebrew protocol based on sending JSON payloads over a WebSocket connection.
|
||||
See [protocol.md](devs/protocol.md) for the implementation details of it.
|
||||
See [protocol.md](protocol.md) for the implementation details of it.
|
||||
|
||||
It's also possible to write a plugin for Clusterio that exposes a custom interface over HTTP, WebSocket or any other technology supported by Node.js.
|
||||
|
||||
@@ -193,7 +193,7 @@ In particular, player-leaving, console-command, and configuration-change handler
|
||||
Use an idempotent state accessor in handlers that can run early.
|
||||
It should migrate any legacy namespace before creating fresh state, fill missing fields, and return the same state on repeated calls.
|
||||
A guard that returns early because the new namespace is absent can silently discard recovery work on an older save.
|
||||
See [player_sync's state accessor](../plugins/player_sync/module/get_script_data.lua) for an implementation that handles a renamed namespace and [the module template](../packages/create/templates/common/module/control.lua) for lifecycle setup.
|
||||
See [player_sync's state accessor](../../plugins/player_sync/module/get_script_data.lua) for an implementation that handles a renamed namespace and [the module template](../../packages/create/templates/common/module/control.lua) for lifecycle setup.
|
||||
|
||||
Use `on_load` only to restore local references and other operations permitted by Factorio's load lifecycle; do not create or migrate persistent state there.
|
||||
Perform state changes in startup or other events that permit them.
|
||||
@@ -227,7 +227,7 @@ end
|
||||
Access persistent state from the appropriate lifecycle callbacks, after initialisation or loading has made it available.
|
||||
The JSON helpers also work before runtime; other compatibility helpers may require `game` to be available.
|
||||
Legacy examples using `global` or `game.table_to_json` directly are version-specific.
|
||||
See [compat.lua](../packages/host/modules/clusterio/compat.lua) and the [Factorio support policy](decisions.md#factorio) before introducing version checks.
|
||||
See [compat.lua](../../packages/host/modules/clusterio/compat.lua) and the [Factorio support policy](decisions.md#factorio) before introducing version checks.
|
||||
|
||||
|
||||
### clusterio_api library
|
||||
@@ -10,7 +10,7 @@ Plugins still on alpha 13 should start with the [alpha 14 guide](plugin-migratio
|
||||
From 2.0.0 onwards a major version (3.0.0) contains breaking changes for users running a cluster, while a minor version (2.1.0) may contain breaking changes for the plugin API.
|
||||
This means a plugin written for 2.0 is not guaranteed to work with 2.1 without changes.
|
||||
Check the Breaking Changes section of the changelog when a new minor version is released and publish an update to your plugin if needed.
|
||||
See [Breaking Changes](/docs/decisions.md#breaking-changes) in the decision log.
|
||||
See [Breaking Changes](/docs/devs/decisions.md#breaking-changes) in the decision log.
|
||||
|
||||
|
||||
## Convert to ES modules
|
||||
@@ -22,7 +22,7 @@ Keep `"clusterio-plugin"` in the package's `"keywords"` for automatic discovery,
|
||||
An `"exports"` map is not required for ES modules.
|
||||
If you add one, expose `"./package.json": "./package.json"`; otherwise Clusterio cannot discover or load the plugin by its package name.
|
||||
Clusterio currently reads the implementation path from `"main"` rather than conditional exports.
|
||||
See [Plugin Structure](../writing-plugins.md#plugin-structure) for a compatible package example.
|
||||
See [Plugin Structure](writing-plugins.md#plugin-structure) for a compatible package example.
|
||||
|
||||
Relative imports must include the full filename with the `.js` extension.
|
||||
This also applies in TypeScript, where you import `./messages.js` even though the source file is `messages.ts`.
|
||||
@@ -77,7 +77,7 @@ Converting the plugin avoids the problem.
|
||||
Entrypoints now export a default async function instead of a class deriving from `BaseControllerPlugin`, `BaseHostPlugin`, `BaseInstancePlugin`, `BaseCtlPlugin` or `BaseWebPlugin`.
|
||||
The function is called once when the plugin loads and attaches handlers to the hooks it needs.
|
||||
Class exports still load, but they are deprecated and a warning is logged for each one.
|
||||
See [Defining the plugin entrypoint](/docs/writing-plugins.md#defining-the-plugin-entrypoint) for the details.
|
||||
See [Defining the plugin entrypoint](/docs/devs/writing-plugins.md#defining-the-plugin-entrypoint) for the details.
|
||||
|
||||
**Alpha 27**
|
||||
```js
|
||||
@@ -289,7 +289,7 @@ declare module "@clusterio/lib" {
|
||||
```
|
||||
|
||||
The plugin template's `tsconfig.browser.json` now includes `index.ts` so the web build also sees the declaration, add it to the `include` list if your plugin has its own tsconfig for the browser.
|
||||
See [Plugin Permissions](/docs/writing-plugins.md#plugin-permissions).
|
||||
See [Plugin Permissions](/docs/devs/writing-plugins.md#plugin-permissions).
|
||||
|
||||
|
||||
## Renamed ctl classes and config
|
||||
|
||||
@@ -7,7 +7,7 @@ Plugins still on an alpha should start with the [2.0 guide](plugin-migration-to-
|
||||
## Request errors
|
||||
|
||||
`RequestError` is gone.
|
||||
Errors thrown by request handlers are now received by the requester as the same class, see [Request errors](/docs/writing-plugins.md#request-errors).
|
||||
Errors thrown by request handlers are now received by the requester as the same class, see [Request errors](/docs/devs/writing-plugins.md#request-errors).
|
||||
Replace `RequestError` with the class that fits:
|
||||
|
||||
- Invalid input: `ValidationError`.
|
||||
|
||||
File renamed without changes.
@@ -2,7 +2,7 @@
|
||||
|
||||
Clusterio communicates using a simple homebrew message passing protocol based on JSON over WebSocket with limited support for reliable transport of messages.
|
||||
The protocol is implemented in [packages/lib/src/link](/packages/lib/src/link) and uses the `ws` library to handle the WebSocket connections on the Node.js side and the native WebSocket API on the browser side.
|
||||
The wire schemas are defined in [messages_core.ts](/packages/lib/src/data/messages_core.ts); see the [communication overview](../communication.md) for how links, connectors, and routing fit together.
|
||||
The wire schemas are defined in [messages_core.ts](/packages/lib/src/data/messages_core.ts); see the [communication overview](communication.md) for how links, connectors, and routing fit together.
|
||||
|
||||
Two general kinds of messages are supported: events and requests.
|
||||
Events are messages sent by one party and received by the other and offer no notification for the sender on whether it was actually received.
|
||||
@@ -111,7 +111,7 @@ Along with the following events emitted when transition between states:
|
||||
- `close` - The connector is closed, moving from any state to `closed`.
|
||||
|
||||
Invalidation or closure rejects pending requests with `SessionLost`.
|
||||
Plugins must handle lost sessions, stale state, and application retries where required; see [connection handling](../writing-plugins.md#handling-connection-events) for the plugin hooks and queueing behavior.
|
||||
Plugins must handle lost sessions, stale state, and application retries where required; see [connection handling](writing-plugins.md#handling-connection-events) for the plugin hooks and queueing behavior.
|
||||
|
||||

|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ If the script fails due to GitHub's 60/hour public access rate limit, you can se
|
||||
|
||||
## Packages
|
||||
|
||||
The [Publish workflow](../.github/workflows/publish.yml) publishes npm packages and Lua mods on GitHub's `release: released` event for a stable release.
|
||||
The [Publish workflow](../../.github/workflows/publish.yml) publishes npm packages and Lua mods on GitHub's `release: released` event for a stable release.
|
||||
Publishing a prerelease does not trigger it; see [GitHub's release event documentation](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#release).
|
||||
The npm release includes the packages under `packages/` and the six core plugins under `plugins/`.
|
||||
Community plugins hosted in separate repositories have independent versions and releases.
|
||||
@@ -44,7 +44,7 @@ For automatic discovery, include `"clusterio-plugin"` in the package's `"keyword
|
||||
Installed npm plugins are discovered from the installation's dependencies when controller, host or ctl loads its configuration, and added to `plugin-list.json`.
|
||||
Discovery starts with the root package's `dependencies`, not `devDependencies`, and follows dependencies of recognized plugins.
|
||||
It does not search arbitrary nested dependency trees for plugins.
|
||||
For tooling that needs the same discovery behavior, reuse [loadPluginList](../packages/lib/src/load_plugin_list.ts) rather than maintaining another package scanner.
|
||||
For tooling that needs the same discovery behavior, reuse [loadPluginList](../../packages/lib/src/load_plugin_list.ts) rather than maintaining another package scanner.
|
||||
|
||||
A possible workflow for developing plugins is to place the plugin in a sub-directory of where clusterio has been installed, and rely on Node.js searching up the folder heirarchy for it to find `@clusterio/lib`.
|
||||
After creating a directory for your plugin, the boilerplate can be generated automaticlly from a set of tempaltes using `npm exec @clusterio/create -y -- --plugin-template` after which you will be asked which areas your plugin will interact with and your plugin's name.
|
||||
@@ -250,7 +250,7 @@ Use `.then` or wait from a hook instead if the other plugin may also wait on you
|
||||
|
||||
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.
|
||||
See [Migrating Plugins to 2.0](devs/plugin-migration-to-2.0.md) for how to convert them.
|
||||
See [Migrating Plugins to 2.0](plugin-migration-to-2.0.md) for how to convert them.
|
||||
|
||||
|
||||
## Logging Messages
|
||||
@@ -17,7 +17,7 @@ The blue arrows point from the hosts and clients to the controller they connect
|
||||
The orange lines connect each host to the Factorio processes it manages.
|
||||
Open the [full-size diagram](assets/clusterio_2.0_block_diagram.svg) to zoom in, or use the [Draw.io source](assets/clusterio_2.0_block_diagram.drawio) to edit it.
|
||||
|
||||
For how messages are handled and routed between these components, see the [communication guide](communication.md).
|
||||
For how messages are handled and routed between these components, see the [communication guide](devs/communication.md).
|
||||
|
||||
|
||||
## Save Patching
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
*
|
||||
* Listed messages are warned about instead of failing the test, and an entry
|
||||
* with connect skips starting the cluster. Entries for other versions are
|
||||
* ignored. See docs/contributing.md for when to add an entry.
|
||||
* ignored. See docs/devs/contributing.md for when to add an entry.
|
||||
*/
|
||||
"use strict";
|
||||
import fs from "node:fs/promises";
|
||||
|
||||
Reference in new issue
Block a user