bbassieandClaude Opus 5.5
ca3dbab49d
Turning factorio.enable_save_patching off did nothing to a save that was patched before. Its control.lua still loaded every module, so the clusterio_api interface, player_sync's join handling and the other module event handlers kept running with no plugin on the host side. When patching is disabled the instance now restores the original control.lua that patching kept as scenario.lua and removes the module files, locale files included, as listed in clusterio.json. The patch info stays with an empty module list so the patch number keeps counting. Otherwise patching the save again would reuse the number stored in the game and on_server_startup would not be raised. Data the modules put in storage is left alone. PatchInfo.fromSave dropped the version read from the save, so the check against newer patch versions never fired. It now keeps it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.1 KiB
How Clusterio works
Clusterio runs a group of Factorio servers as a cluster, managed through a web interface or the clusterioctl command-line client.
The controller is the central point of contact: clients connect to it to manage the cluster, and hosts connect to it to receive commands and exchange messages.
Each host manages its local Factorio server processes, with each server belonging to an instance.
System overview
The diagram shows one possible layout with two physical servers, each running a host and three Factorio servers. The controller shares a machine with one host in this example, but it can run on a separate machine. The number of hosts and instances can vary with the needs of the cluster.
The blue arrows point from the hosts and clients to the controller they connect to; messages can travel in both directions over those WebSocket connections. The orange lines connect each host to the Factorio processes it manages. Open the full-size diagram to zoom in, or use the Draw.io source to edit it.
For how messages are handled and routed between these components, see the communication guide.
Save Patching
In order to efficiently get data in and out of running Factorio servers and to provide custom interfaces Clusterio uses save patching[1] to add code to the game. The save patching is based on the built in event_handler library to Factorio and requires scenarios to be coded specifically for it. 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.
A save that was patched before has its modules removed again when it's started with save patching disabled.
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.
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.
User Accounts
The controller creates and stores accounts for all Factorio users that log into instances under its control. These accounts are used to store per player data and authorize management of the cluster. By default users accounts are assigned a Player role that gives a limited read access to the cluster resources, and admins of the cluster can be assigned a Cluster Admin role to get access to manage it.