Merge pull request #996 from bbassie/feature/instance-udp

Add UDP communication support for instances

docs/configuration.md

@@ -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.1.10 or later, earlier versions crash when a packet is received on a headless server.
+
+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.

docs/developing-for-clusterio.md

@@ -292,6 +292,19 @@ Parameters:
 - `channel`: string identifying which channel to send it on.
 - `data`: table that can be converted to JSON with `compat.table_to_json`
 
+#### clusterio_api.send_udp(channel, data)
+
+Send data to Clusterio over the given channel using UDP instead of stdout.
+Clusterio plugins receive it as `udp-channel_name` events, see the [Communicating over UDP section](writing-plugins.md#communicating-over-udp) in the Writing Plugins document.
+Requires `factorio.enable_lua_udp` to be enabled on the instance and Factorio 2.1.10 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.
+
+**Note**: Delivery is not guaranteed and payloads should be kept well below 32 kB.
+
+Parameters:
+- `channel`: string identifying which channel to send it on.
+- `data`: string with the payload to send, any bytes are allowed.
+
 
 ### serialize library
 

docs/writing-plugins.md

@@ -147,7 +147,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**:
@@ -303,7 +303,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 = {
@@ -501,6 +501,43 @@ 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.
+This needs Factorio 2.1.10 or later, earlier versions crash when a packet is received on a headless server.
+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 32 kB.
+
+Data out from Factorio is sent with the `send_udp` API of the Clusterio module.
+Unlike `send_json` the payload is an arbitrary string, and it is delivered to plugins as a `udp-channel_name` event with the payload as a Buffer:
+
+```lua
+clusterio_api.send_udp("my_plugin_foo", "123")
+```
+
+```js
+export default async function(context) {
+    const { instance, logger } = context;
+    instance.server.handleUdp("my_plugin_foo", async data => {
+        logger.info(`got ${data.toString()}`);
+    });
+}
+```
+
+Like `handle` for `send_json`, `handleUdp` logs errors thrown by the handler.
+Use `instance.server.on("udp-my_plugin_foo", ...)` for custom error handling.
+
+Data into Factorio is sent with the `sendUdp` method on the instance 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
+instance.hooks.start.attach(plugin.name, async () => {
+    await instance.sendUdp("my_plugin_foo:123");
+});
+```
+
 
 ## Defining Link Messages