mirror of
https://github.com/clusterio/clusterio.git
synced 2026-11-22 00:13:12 +09:00
Add UDP communication support for instances
Add opt-in UDP messaging between the host and the Factorio server using the --enable-lua-udp option of Factorio 2.0.59+. When factorio.enable_lua_udp is set the instance binds a localhost UDP socket, starts Factorio with --enable-lua-udp on factorio.lua_udp_port (random if null, like the RCON port) and tells the clusterio module the host port via clusterio_private.update_instance. Data from Factorio is sent with clusterio_api.send_udp(channel, data) in the same IPC format as send_json, so plugins receive it through the existing ipc-<channel> events. Packets not sent from the Lua UDP port are ignored, as that is the only unauthenticated way into the IPC handler. Data to Factorio is sent with the new sendUdp method on instances and instance plugins, and is dispatched in-game as on_udp_packet_received events by polling helpers.recv_udp every tick from the clusterio module. Plugins requiring UDP declare the new LuaUdp feature flag, which like SavePatching and ScriptCommands refuses to load the plugin on instances without the option enabled. Verified against a headless 2.1.17 server: send_udp and recv_udp are silent no-ops when the option is off, so a stale port in a save that is moved to an instance without UDP does no harm. The integration test matrix now starts the instance with UDP enabled on Factorio 2.0.59+ and round trips a player event over it. Closes #969 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
1 parent
ec51adc71c
commit
788ae17657
15 files changed
+394
-17
No files matched your search
@@ -606,6 +606,23 @@ Like factorio.enable_save_patching, plugins that need script commands can't be l
|
||||
Defaults to true.
|
||||
|
||||
|
||||
### factorio.enable_lua_udp
|
||||
|
||||
Enable UDP messaging between the host and the Factorio server by passing `--enable-lua-udp` to Factorio.
|
||||
This lets plugins send UDP packets to the server and receive data sent with `clusterio_api.send_udp` in-game.
|
||||
Requires Factorio 2.0.59 or later.
|
||||
|
||||
Defaults to false.
|
||||
|
||||
|
||||
### factorio.lua_udp_port
|
||||
|
||||
UDP port on localhost the Factorio server receives Lua UDP messages on when `factorio.enable_lua_udp` is enabled.
|
||||
If null a random port in the dynamic range is assigned each time the instance starts.
|
||||
|
||||
Defaults to null.
|
||||
|
||||
|
||||
### factorio.enable_whitelist
|
||||
|
||||
Turn on the whitelist on the server.
|
||||
|
||||
@@ -251,6 +251,20 @@ Parameters:
|
||||
- `channel`: string identifying which channel to send it on.
|
||||
- `data`: table that can be converted to JSON with game.table_to_json
|
||||
|
||||
#### clusterio_api.send_udp(channel, data)
|
||||
|
||||
Send JSON data to Clusterio over the given channel using UDP instead of stdout.
|
||||
Clusterio plugins receive it the same way as data sent with `send_json`.
|
||||
Requires `factorio.enable_lua_udp` to be enabled on the instance and Factorio 2.0.59 or later, otherwise the data is silently dropped.
|
||||
The port to send to is passed to the module with a script command on startup, so `factorio.enable_script_commands` must be enabled as well.
|
||||
See the [Communicating over UDP section](writing-plugins.md#communicating-over-udp) in the Writing Plugins document for more information.
|
||||
|
||||
**Note**: Delivery is not guaranteed and payloads must be less than 64 kB.
|
||||
|
||||
Parameters:
|
||||
- `channel`: string identifying which channel to send it on.
|
||||
- `data`: table that can be converted to JSON with game.table_to_json
|
||||
|
||||
|
||||
### serialize library
|
||||
|
||||
|
||||
+25
-2
@@ -131,7 +131,7 @@ The following properties are recognized:
|
||||
See [Migrating Stored Data](#migrating-stored-data)
|
||||
|
||||
**features**:
|
||||
Array of features the plugin needs from the instances it is loaded on, `"SavePatching"` and/or `"ScriptCommands"`.
|
||||
Array of features the plugin needs from the instances it is loaded on, any of `"SavePatching"`, `"ScriptCommands"` and `"LuaUdp"`.
|
||||
See [Handling Invalid Configuration](#handling-invalid-configuration)
|
||||
|
||||
**messages**:
|
||||
@@ -286,7 +286,7 @@ See [Configuration System](config-system.md) for more details on how this system
|
||||
|
||||
### Handling Invalid Configuration
|
||||
|
||||
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:
|
||||
If the plugin requires save patching, script commands or Lua UDP to function, which can be disabled to run vanilla or scenarios not compatible with Clusterio, declare it under `features` in the `plugin` export:
|
||||
|
||||
```js
|
||||
export const plugin = {
|
||||
@@ -482,6 +482,29 @@ Data out from Factorio does not have the same limits as data into Factorio, RCON
|
||||
For `send_json` it's possible that payloads greater than 4kB are received after payloads that were sent at a later point in time.
|
||||
For RCON, commands longer than 50 characters may end up being executed after shorter commands sent after it.
|
||||
|
||||
### Communicating over UDP
|
||||
|
||||
Instances can optionally exchange UDP packets with the Factorio server for low latency fire-and-forget communication, using the `--enable-lua-udp` option of Factorio 2.0.59 and later.
|
||||
This is disabled by default and enabled by setting `factorio.enable_lua_udp` on the instance.
|
||||
Sending data out of Factorio also needs `factorio.enable_script_commands`, as the port to send to is passed to the module with a script command on startup.
|
||||
Plugins requiring it should declare the `LuaUdp` feature.
|
||||
Note that UDP does not guarantee delivery or ordering, and packets should be kept well below 64 kB.
|
||||
|
||||
Data out from Factorio is sent with the `send_udp` API of the Clusterio module and is delivered to plugins as the same `ipc-channel_name` events as `send_json` uses:
|
||||
|
||||
```lua
|
||||
clusterio_api.send_udp("my_plugin_foo", { data = 123 })
|
||||
```
|
||||
|
||||
Data into Factorio is sent with the `sendUdp` method on the plugin object and delivered in-game as `defines.events.on_udp_packet_received` events with the packet in `event.payload`.
|
||||
The Clusterio module polls for received packets every tick, all modules and mods receive every packet so make sure the payload identifies your plugin.
|
||||
|
||||
```js
|
||||
async onStart() {
|
||||
await this.sendUdp("my_plugin_foo:123");
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Defining Link Messages
|
||||
|
||||
|
||||
Reference in new issue
Block a user