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:
bbassieandClaude Fable 5.1 committed 2026-10-15 16:38:28 +00:00
1 parent ec51adc71c
commit 788ae17657
15 files changed
+394 -17

No files matched your search

+25 -1
View File
@@ -6,7 +6,7 @@ import fs from "node:fs/promises";
import { slowTest, testMatrix } from "../common.js";
import {
execCtl, execCtlProcess, sendRcon, getControl,
requiresFactorio, hasFactorio, instancesDir,
requiresFactorio, hasFactorio, getFactorioVersion, instancesDir,
} from "./index.js";
const instId = 48;
@@ -21,6 +21,11 @@ const requireApi = [
"or package.loaded['__level__/modules/clusterio/api.lua']", // 2.0.0
].join(" ");
// --enable-lua-udp was added in Factorio 2.0.59
function hasLuaUdp() {
return lib.integerFullVersion(getFactorioVersion()) >= lib.integerFullVersion("2.0.59");
}
function getUser(name) {
return getControl().send(new lib.UserGetRequest(name));
}
@@ -111,6 +116,7 @@ describe("Clusterio Instance", function() {
await execCtl(`${instSetConfig} factorio.enable_whitelist true`);
await execCtl(`${instSetConfig} factorio.enable_save_patching ${savePatchingEnabled}`);
await execCtl(`${instSetConfig} factorio.enable_script_commands ${scriptCommandsEnabled}`);
await execCtl(`${instSetConfig} factorio.enable_lua_udp ${hasLuaUdp()}`);
await execCtl(`instance save create ${instName}`);
await execCtl(`instance start ${instName}`);
});
@@ -152,6 +158,24 @@ describe("Clusterio Instance", function() {
const userLeave = await getUser("JoiningPlayer");
assert(!userLeave.instances.has(instId), "Player is not shown as offline");
});
it("should respond to a player join and leave event sent over UDP", async function() {
// The host port is passed to the module by updateInstanceData on startup
if (!hasLuaUdp() || !scriptCommandsEnabled) {
this.skip();
}
await sendRcon(instId,
`/sc ${requireApi} api.send_udp("player_event",` +
"{ type='join', name='UdpPlayer' })"
);
const userJoin = await getUser("UdpPlayer");
assert(userJoin.instances.has(instId), "Player is not shown as online");
await sendRcon(instId,
`/sc ${requireApi} api.send_udp("player_event",` +
"{ type='leave', name='UdpPlayer', reason='quit' })"
);
const userLeave = await getUser("UdpPlayer");
assert(!userLeave.instances.has(instId), "Player is not shown as offline");
});
}
it("should respond to a player ban and unban event", async function() {
await execCtl(`${instSetConfig} factorio.sync_banlist bidirectional`);