fix(minimap): restore nested previous_recipe name access

Furnace previous_recipe ids are nested under prev.name.name in this context. Restore the original access path and leave an inline maintainer note to prevent repeat regressions.

.github/workflows/node.js.yml

@@ -20,8 +20,6 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - uses: pnpm/action-setup@v4
-      with:
-        version: 8
     - name: Use Node.js ${{ matrix.node-version }}
       uses: actions/setup-node@v4
       with:
@@ -48,11 +46,9 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - uses: pnpm/action-setup@v4
-      with:
-        version: 8
     - uses: actions/setup-node@v4
       with:
-        node-version: 18.x
+        node-version: 20.x
     - run: pnpm i --no-frozen-lockfile
     - run: pnpm run lint
 
@@ -61,11 +57,9 @@ jobs:
     steps:
     - uses: actions/checkout@v4
     - uses: pnpm/action-setup@v4
-      with:
-        version: 8
     - uses: actions/setup-node@v4
       with:
-        node-version: 18.x
+        node-version: 20.x
     - run: pnpm i --no-frozen-lockfile
     - run: pnpm run build-mod
     # Upload build to artifacts

.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+
+name: Publish
+
+on:
+  release:
+    types:
+      - released
+
+jobs:
+  npm:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 8
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          registry-url: https://registry.npmjs.org
+      - run: pnpm install --no-frozen-lockfile
+      - run: pnpm -r --filter='./{plugins,packages}/*' publish --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: $${{ secrets.NPM_TOKEN }}
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: pnpm-lock.yaml
+
+  factorio:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 8
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+      - run: pnpm install --no-frozen-lockfile
+      - run: pnpm -r --filter='./{plugins,packages}/*' run build-mod --output-dir ../../dist
+      - run: node ./publish.js factorio ./dist
+        env:
+          FACTORIO_TOKEN: ${{ secrets.FACTORIO_TOKEN }}
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: ./dist/*

.gitignore

@@ -30,8 +30,12 @@ dist/
 node_modules
 
 Factorio*
+!*Factorio*.ts
+!*Factorio*.tsx
+!*Factorio*.js
 /factorio
 !/test/file/factorio
+!/test/file/html/*.html
 !/test/lib/factorio
 !/packages/lib/src/factorio
 /instances

CHANGELOG.md

@@ -31,6 +31,51 @@ Many thanks to the following for contributing to this release:
 [@username](https://github.com/username)
 -->
 
+## Version 2.0.0-alpha.22
+
+### Major Features
+
+- Added a download dependencies button which downloads missing dependencies. [#726](https://github.com/clusterio/clusterio/issues/726)
+- Added an update mod button which downloads the latest compatible version of a mod. [#725](https://github.com/clusterio/clusterio/issues/725)
+
+### Features
+
+- Added online player list to instance details page. [#666](https://github.com/clusterio/clusterio/issues/666)
+- Added ability to restart instances as a single action. [#779](https://github.com/clusterio/clusterio/issues/779)
+- Added ability to exclude instances from the 'Start all' web UI button. [#451](https://github.com/clusterio/clusterio/issues/451)
+- Added plugin update detection for restart required [#759](https://github.com/clusterio/clusterio/issues/759)
+- Added detection for mismatched mod and mod pack factorio version. [#727](https://github.com/clusterio/clusterio/issues/727)
+- Added detection for dependency issues such as incompatible or wrong version. [#727](https://github.com/clusterio/clusterio/issues/727)
+- Added a quick fix button for resolving detected dependency issues. [#801](https://github.com/clusterio/clusterio/issues/801)
+
+### Changes
+
+- Restart host / controller is now the default action with stop moved to a dropdown. [#780](https://github.com/clusterio/clusterio/issues/780)
+- Restart host / controller no longer shows unless it is enabled for that machine. [#780](https://github.com/clusterio/clusterio/issues/780)
+- Plugin templates no longer depend on a dev install of Clusterio. [#786](https://github.com/clusterio/clusterio/issues/786)
+- Better error message for when a plugin is missing an index file. [#799](https://github.com/clusterio/clusterio/pull/799)
+- `ModStore.downloadMods` no longer checks if the mod is already downloaded. [#801](https://github.com/clusterio/clusterio/issues/801
+- Mod version for buildins will always be fully qualified, matching the requirement enforced on other mods. [#801](https://github.com/clusterio/clusterio/issues/801))
+- Subscriptions can now be filtered. [#788](https://github.com/clusterio/clusterio/pull/788)
+
+### Fixes
+
+- Fixed the missing space between action buttons on the users and hosts list. [#780](https://github.com/clusterio/clusterio/issues/780)
+- Fixed "rendered more hooks" error when refreshing hosts page. [#769](https://github.com/clusterio/clusterio/issues/769)
+- Fixed inventory combinator time signal not always updating [#610](https://github.com/clusterio/clusterio/issues/610)
+- Renamed templates for `.gitignore` and `.npmignore` that caused `create --plugin-template` to fail. [#800](https://github.com/clusterio/clusterio/pull/800)
+- Fixed npm update button failing to apply update and restart.
+
+### Breaking changes
+
+- `ModPortalDownloadRequest` now requires an array of mod version pairs rather than a single mod name and version. [#801](https://github.com/clusterio/clusterio/issues/801)
+- Version strings (e.g. `1.0`, `1.0.0`) now have stricter typing and validation, passing unchecked strings to functions will error. [#801](https://github.com/clusterio/clusterio/issues/801)
+
+Many thanks to the following for contributing to this release:  
+[@Cooldude2606](https://github.com/Cooldude2606)
+[@Danielv123](https://github.com/Danielv123)
+[@Hornwitser](https://github.com/Hornwitser)
+
 ## Version 2.0.0-alpha.21
 
 ### Major Features

README.md

@@ -232,7 +232,7 @@ Do not install the [Clusterio mod](https://mods.factorio.com/mod/clusterio), thi
 
 ## Running Clusterio
 
-After completing the installation start up the controller and at least one host separately.
+After completing the installation and creating your admin user, start up the controller and at least one host separately.
 The installer provides the `run-controller` and `run-host` scripts to make this simple.
 Once the controller process is running you can log into the web interface which is hosted by default on http://localhost:8080/ (adjust the port number if you changed it), use the admin authentication token provided from the installation to log in.
 

clean.js

@@ -86,8 +86,8 @@ async function removeExecutionArtifacts() {
 async function main() {
 	await yargs(process.argv.slice(2))
 		.scriptName("clean")
-		.usage("$0 <command> [options]")
-		.option("dry", {
+		.option("dry-run", {
+			alias: "dry",
 			nargs: 0,
 			describe: "Will not delete any files",
 			default: false,
@@ -108,7 +108,7 @@ async function main() {
 			DRY = argv.dry;
 			removeBuildArtifacts();
 		})
-		.demandCommand(1, "You need to specify a command to run")
+		.demandCommand(1, "A command must be specified")
 		.strict()
 		.parse();
 }

docs/developing-for-clusterio.md

@@ -120,7 +120,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 [socket.md](socket.md) for the implementation details of it.
+See [protocol.md](devs/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.
 

package.json

@@ -2,10 +2,11 @@
 	"name": "root",
 	"private": true,
 	"files": [],
+	"packageManager": "pnpm@10.28.1+sha512.7d7dbbca9e99447b7c3bf7a73286afaaf6be99251eb9498baefa7d406892f67b879adb3a1d7e687fc4ccc1a388c7175fbaae567a26ab44d1067b54fcb0d6a316",
 	"scripts": {
 		"build": "tsc --build",
 		"watch": "tsc --build --watch",
-		"build-mod": "node ./packages/lib/build_mod.js --source-dir ./packages/host/lua/clusterio_lib",
+		"build-mod": "pnpm run -r build-mod --output-dir ../../dist",
 		"test": "pnpm run build && mocha --enable-source-maps --check-leaks -R spec --recursive test \"plugins/*/test/**\" --exclude \"test/manual/**\"",
 		"silent-test": "SILENT_TEST=y pnpm test",
 		"fast-test": "FAST_TEST=y pnpm test",
@@ -27,7 +28,7 @@
 		]
 	},
 	"engines": {
-		"node": ">=18"
+		"node": ">=20"
 	},
 	"workspaces": [
 		"packages/*",

packages/controller/controller.ts

@@ -127,7 +127,8 @@ void new lib.Gauge(
 
 async function handleBootstrapCommand(
 	args: any,
-	controllerConfig: lib.ControllerConfig
+	controllerConfig: lib.ControllerConfig,
+	controllerConfigLock: lib.LockFile,
 ): Promise<void> {
 	let subCommand = args._[1];
 
@@ -141,6 +142,8 @@ async function handleBootstrapCommand(
 	await userManager.load(path.join(databaseDirectory, "users.json"));
 
 	if (subCommand === "create-admin") {
+		await controllerConfigLock.acquire(); // Also needed to write to the database files
+
 		if (!args.name) {
 			logger.error("name cannot be blank");
 			process.exitCode = 1;
@@ -156,6 +159,7 @@ async function handleBootstrapCommand(
 		admin.roleIds.add(adminRole.id);
 		admin.isAdmin = true;
 		await userManager.save(path.join(controllerConfig.get("controller.database_directory"), "users.json"));
+		await controllerConfigLock.release();
 
 	} else if (subCommand === "generate-user-token") {
 		let user = userManager.getByName(args.name);
@@ -251,6 +255,7 @@ async function initialize(): Promise<InitializeParameters> {
 			default: "plugin-list.json",
 			type: "string",
 		})
+		.option("bypass-lock-file", { hidden: true, type: "boolean", nargs: 0, default: false })
 		.command("plugin", "Manage available plugins", lib.pluginCommand)
 		.command("config", "Manage Controller config", lib.configCommand)
 		.command("bootstrap", "Bootstrap access to cluster", yargs => {
@@ -281,6 +286,7 @@ async function initialize(): Promise<InitializeParameters> {
 				type: "boolean", nargs: 0, default: false,
 				describe: "Start the controller in recovery mode with all plugins disabled and hosts disconnected",
 			});
+			yargs.option("check-user-count", { hidden: true, type: "boolean", nargs: 0, default: true });
 			yargs.option("dev", { hidden: true, type: "boolean", nargs: 0 });
 			yargs.option("dev-plugin", { hidden: true, type: "array" });
 		})
@@ -350,8 +356,14 @@ async function initialize(): Promise<InitializeParameters> {
 	lib.registerPluginMessages(pluginInfos);
 	lib.addPluginConfigFields(pluginInfos);
 
-	let controllerConfig;
 	const controllerConfigPath = args.config;
+	const controllerConfigLockPath = `${controllerConfigPath}.lock`;
+	if (args.bypassLockFile) {
+		await fs.unlink(controllerConfigLockPath).catch(() => {}); // ignore error, file might not exist
+	}
+
+	let controllerConfig;
+	const controllerConfigLock = new lib.LockFile(controllerConfigLockPath);
 	logger.info(`Loading config from ${controllerConfigPath}`);
 	try {
 		controllerConfig = await lib.ControllerConfig.fromFile("controller", controllerConfigPath);
@@ -377,10 +389,11 @@ async function initialize(): Promise<InitializeParameters> {
 	}
 
 	if (command === "config") {
-		await lib.handleConfigCommand(args, controllerConfig);
-
+		await lib.handleConfigCommand(args, controllerConfig, controllerConfigLock);
 	} else if (command === "bootstrap") {
-		await handleBootstrapCommand(args, controllerConfig);
+		await handleBootstrapCommand(args, controllerConfig, controllerConfigLock);
+	} else if (shouldRun) {
+		await controllerConfigLock.acquire(); // Hold the lock until process exit
 	}
 
 	return {
@@ -417,6 +430,14 @@ async function startup() {
 		...await Controller.bootstrap(controllerConfig)
 	);
 
+	// Refuse to start if there are no users loaded
+	if (args.checkUserCount && controller.userManager.users.size === 0) {
+		logger.fatal(
+			"Cannot start controller, no users loaded.\n" +
+			"Try `npx clusteriocontroller bootstrap create-admin <username>`");
+		process.exit(1);
+	}
+
 	let secondSigint = false;
 	process.on("SIGINT", () => {
 		if (secondSigint) {

packages/controller/package.json

@@ -3,7 +3,7 @@
 	"description": "Implementation of Clusterio controller",
 	"author": "Hornwitser",
 	"license": "MIT",
-	"version": "2.0.0-alpha.21",
+	"version": "2.0.0-alpha.22b",
 	"main": "dist/node/index.js",
 	"scripts": {
 		"prepare": "tsc --build && webpack-cli --mode production",
@@ -17,45 +17,45 @@
 		"factorio"
 	],
 	"engines": {
-		"node": ">=18"
+		"node": ">=20"
 	},
 	"dependencies": {
 		"@clusterio/lib": "workspace:*",
-		"@sinclair/typebox": "^0.30.4",
+		"@sinclair/typebox": "catalog:",
+		"set-blocking": "catalog:",
+		"jsonwebtoken": "catalog:",
+		"express": "catalog:",
+		"fs-extra": "catalog:",
+		"ws": "catalog:",
+		"jszip": "catalog:",
+		"winston": "catalog:",
+		"winston-daily-rotate-file": "catalog:",
 		"busboy": "^1.6.0",
 		"compression": "^1.8.0",
-		"express": "^4.21.2",
 		"finalhandler": "^1.3.1",
-		"fs-extra": "^11.3.0",
-		"jsonwebtoken": "^9.0.1",
-		"jszip": "^3.10.1",
-		"set-blocking": "^2.0.0",
-		"winston": "^3.17.0",
-		"winston-daily-rotate-file": "^4.7.1",
-		"ws": "^8.18.1",
 		"yargs": "^17.7.2"
 	},
 	"devDependencies": {
 		"@clusterio/web_ui": "workspace:*",
-		"@swc/core": "^1.13.3",
-		"@types/busboy": "^1.5.0",
-		"@types/compression": "^1.7.2",
-		"@types/express": "^4.17.17",
-		"@types/finalhandler": "^1.2.0",
-		"@types/fs-extra": "^11.0.1",
-		"@types/jsonwebtoken": "^9.0.9",
-		"@types/node": "^20.17.19",
-		"@types/set-blocking": "^2.0.0",
-		"@types/ws": "^8.5.14",
+		"@types/jsonwebtoken": "catalog:",
+		"@types/set-blocking": "catalog:",
+		"@types/finalhandler": "catalog:",
+		"@types/express": "catalog:",
+		"@types/fs-extra": "catalog:",
+		"@types/node": "catalog:",
+		"@types/ws": "catalog:",
 		"@types/yargs": "^17.0.33",
-		"react": "^18.2.0",
-		"react-dom": "^18.2.0",
-		"react-router-dom": "^6.29.0",
-		"typescript": "^5.7.3",
-		"webpack": "^5.98.0",
-		"webpack-cli": "^5.1.4",
-		"webpack-dev-middleware": "^6.1.1",
-		"webpack-merge": "^5.9.0"
+		"@types/compression": "^1.7.2",
+		"@types/busboy": "^1.5.0",
+		"@swc/core": "catalog:",
+		"react": "catalog:",
+		"react-dom": "catalog:",
+		"react-router-dom": "catalog:",
+		"typescript": "catalog:",
+		"webpack": "catalog:",
+		"webpack-cli": "catalog:",
+		"webpack-merge": "catalog:",
+		"webpack-dev-middleware": "^6.1.1"
 	},
 	"publishConfig": {
 		"access": "public"

packages/controller/src/BaseConnection.ts

@@ -78,7 +78,7 @@ export default class BaseConnection extends lib.Link {
 		return modPack;
 	}
 
-	getMod(mod: { name: string, version: string, sha1?: string }) {
+	getMod(mod: { name: string, version: lib.FullVersion, sha1?: string }) {
 		let filename = lib.ModInfo.filename(mod.name, mod.version);
 		let modInfo = this._controller.modStore.files.get(filename);
 		if (!modInfo) {

packages/controller/src/ControlConnection.ts

@@ -100,6 +100,8 @@ export default class ControlConnection extends BaseConnection {
 		this.handle(lib.ModListRequest, this.handleModListRequest.bind(this));
 		this.handle(lib.ModSearchRequest, this.handleModSearchRequest.bind(this));
 		this.handle(lib.ModPortalGetAllRequest, this.handleModPortalGetAllRequest.bind(this));
+		this.handle(lib.ModPortalDownloadRequest, this.handleModPortalDownloadRequest.bind(this));
+		this.handle(lib.ModDependencyResolveRequest, this.handleModDependencyResolveRequest.bind(this));
 		this.handle(lib.ModDeleteRequest, this.handleModDeleteRequest.bind(this));
 		this.handle(lib.LogSetSubscriptionsRequest, this.handleLogSetSubscriptionsRequest.bind(this));
 		this.handle(lib.LogQueryRequest, this.handleLogQueryRequest.bind(this));
@@ -124,7 +126,7 @@ export default class ControlConnection extends BaseConnection {
 		this.handle(lib.PluginUpdateRequest, this.handlePluginUpdateRequest.bind(this));
 		this.handle(lib.PluginInstallRequest, this.handlePluginInstallRequest.bind(this));
 		this.handle(lib.DebugDumpWsRequest, this.handleDebugDumpWsRequest.bind(this));
-		this.handle(lib.ModPortalDownloadRequest, this.handleModPortalDownloadRequest.bind(this));
+		this.handle(lib.FactorioVersionsRequest, this.handleFactorioVersionsRequest.bind(this));
 	}
 
 	validateIngress(message: lib.MessageRequest | lib.MessageEvent) {
@@ -564,52 +566,181 @@ export default class ControlConnection extends BaseConnection {
 	 * Handle request to download a mod from the Factorio Mod Portal to the controller.
 	 * @param request - Request object with mod name, version, and factorioVersion.
 	 */
-	async handleModPortalDownloadRequest(request: lib.ModPortalDownloadRequest): Promise<lib.ModInfo> {
-		const { name, version, factorioVersion } = request;
-		const filename = lib.ModInfo.filename(name, version);
+	async handleModPortalDownloadRequest(request: lib.ModPortalDownloadRequest) {
+		const factorioVersion = request.factorioVersion;
+		const toDownload = this._controller.modStore.filterInstalled(request.mods, false);
 
-		// Check if mod already exists
-		if (this._controller.modStore.files.has(filename)) {
-			logger.verbose(`Mod ${filename} already exists, skipping download.`);
-			return this._controller.modStore.files.get(filename)!;
-		}
+		if (toDownload.length > 0) {
+			// Get Factorio credentials from config
+			const username = this._controller.config.get("controller.factorio_username");
+			const token = this._controller.config.get("controller.factorio_token");
 
-		// Get Factorio credentials from config
-		const username = this._controller.config.get("controller.factorio_username");
-		const token = this._controller.config.get("controller.factorio_token");
-
-		if (!username || !token) {
-			throw new lib.RequestError("Factorio credentials (username, token) not configured on the controller.");
-		}
-
-		try {
-			logger.info(`Downloading mod ${filename} for Factorio ${factorioVersion} from portal.`);
-			const modMap = new Map([[name, version]]);
-			await this._controller.modStore.downloadMods(modMap, username || "", token || "", factorioVersion);
-
-			// Verify download and return ModInfo
-			const downloadedMod = this._controller.modStore.files.get(filename);
-			if (!downloadedMod) {
-				throw new lib.RequestError(`Failed to find mod ${filename} in store after download attempt.`);
+			if (!username || username === "" || !token || token === "") {
+				throw new lib.RequestError("Factorio credentials (username, token) not configured on the controller.");
 			}
-			logger.info(`Successfully downloaded mod ${filename}.`);
-			return downloadedMod;
 
-		} catch (error: any) {
-			logger.error(`Error downloading mod ${filename} from portal: ${error.message}`);
-			// Improve error message clarity
-			let errorMessage = `Mod portal download failed for ${name} v${version}`;
-			if (error instanceof lib.RequestError) {
-				errorMessage += `: ${error.message}`;
-			} else if (error.message.includes("401") || error.message.includes("Unauthorized")) {
-				errorMessage += ": Authentication failed. Check Factorio username/token in controller config.";
-			} else if (error.message.includes("404") || error.message.includes("Not Found")) {
-				errorMessage += ": Mod version not found on the portal.";
+			try {
+				logger.info(`Downloading ${toDownload.length} mods for Factorio ${factorioVersion} from portal.`);
+				await this._controller.modStore.downloadMods(toDownload, username, token, factorioVersion);
+
+			} catch (error: any) {
+				logger.error(`Error downloading mods from portal: ${error.message}`);
+				// Improve error message clarity
+				let errorMessage = "Mod portal download failed";
+				if (error instanceof lib.RequestError) {
+					errorMessage += `: ${error.message}`;
+				} else if (error.message.includes("401") || error.message.includes("Unauthorized")) {
+					errorMessage += ": Authentication failed. Check Factorio username/token in controller config.";
+				} else if (error.message.includes("404") || error.message.includes("Not Found")) {
+					errorMessage += ": Mod version not found on the portal.";
+				} else {
+					errorMessage += `: ${error.message}`;
+				}
+				throw new lib.RequestError(errorMessage);
+			}
+		}
+
+		// Verify all mods are present
+		const modInfos = [];
+		const installedMods = [...this._controller.modStore.mods()];
+		for (const mod of request.mods) {
+			const modInfo = installedMods.find(m => m.name === mod.name && mod.version.testVersion(m.version));
+			if (!modInfo) {
+				throw new lib.RequestError(`Failed to find mod ${mod.name} in store after download attempt.`);
+			}
+			modInfos.push(modInfo);
+		}
+
+		return modInfos;
+	}
+
+	async handleModDependencyResolveRequest(request: lib.ModDependencyResolveRequest) {
+		const {factorioVersion, checkForUpdates} = request;
+		const searchQueue = [...request.mods];
+		const localInfos = [...this._controller.modStore.mods()];
+
+		const _builtInModNames = lib.ModPack.getBuiltinModNames(factorioVersion);
+		const builtInModNames = new Set(_builtInModNames);
+		const skipSearch = new Set(_builtInModNames);
+
+		type ModPortalModType = InstanceType<typeof lib.ModPortalGetAllRequest.Response>["mods"][number];
+		type ModPortalReleaseType = NonNullable<ModPortalModType["releases"]>[number];
+		const dependencyRequirements = new Map<string, lib.ModVersionRange>();
+		const optionalRequirements = new Map<string, lib.ModVersionRange>();
+		const candidateReleases = new Map<string, lib.ModInfo>();
+		const incompatible = new Set<string>();
+		const invalid = new Set<string>();
+
+		const _modPortalReleases = new Map<string, ModPortalModType | null>();
+		async function fetchModReleases(modName: string) {
+			let releases = _modPortalReleases.get(modName);
+			if (releases === undefined) {
+				try {
+					releases = await lib.ModStore.fetchModReleases(modName);
+				} catch (error: any) {
+					if (!error.message.includes("404") && !error.message.includes("Not Found")) {
+						logger.error(`Error fetching mod from portal: ${error.message}`);
+						throw new lib.RequestError(`Dependency resolution failed: ${error.message}`);
+					} else {
+						releases = null;
+					}
+				}
+			}
+			_modPortalReleases.set(modName, releases);
+			return releases;
+		}
+
+		while (searchQueue.length > 0) {
+			const mod = searchQueue.shift()!;
+			if (mod.incompatible) {
+				incompatible.add(mod.name);
+				continue;
+			}
+
+			// Get the current version range (optionals are tracked in case they become required)
+			let versionRange = dependencyRequirements.get(mod.name);
+			if (!versionRange) {
+				versionRange = optionalRequirements.get(mod.name) ?? new lib.ModVersionRange();
+				if (mod.required) {
+					dependencyRequirements.set(mod.name, versionRange);
+					optionalRequirements.delete(mod.name);
+				} else {
+					optionalRequirements.set(mod.name, versionRange);
+				}
+			}
+
+			// Update the version range if needed
+			if (mod.version) {
+				versionRange.combineVersion(mod.version);
+				if (!versionRange.valid) {
+					candidateReleases.delete(mod.name);
+					invalid.add(mod.name);
+				}
+			}
+
+			// Do not add dependencies for invalids, optionals, skips, or valid candidates
+			const existingCandidate = candidateReleases.get(mod.name);
+			if (invalid.has(mod.name) || optionalRequirements.has(mod.name) || skipSearch.has(mod.name) || (
+				existingCandidate && versionRange.testVersion(existingCandidate.version)
+			)) {
+				continue;
+			}
+
+			// Check if a local version fits the requirements
+			let candidate = localInfos
+				.filter(info => (info.name === mod.name && versionRange.testVersion(info.version)))
+				.reduce<lib.ModInfo | undefined>((max, cur) => (
+					max && max.integerVersion > cur.integerVersion ? max : cur
+				), undefined);
+
+			// Check if a mod poral version fits the requirements
+			if (!candidate || checkForUpdates) {
+				const modReleases = await fetchModReleases(mod.name);
+				if (modReleases && modReleases.releases) {
+					const release = modReleases.releases
+						.filter(info => (
+							info.info_json.factorio_version === factorioVersion
+							&& versionRange.testVersion(info.version)
+						))
+						.reduce<ModPortalReleaseType | undefined>((max, cur) => (
+							max && lib.integerFullVersion(max.version) > lib.integerFullVersion(cur.version) ? max : cur
+						), undefined);
+
+					// We only select the mod portal release if it is more recent than the local candidate
+					if (release && (!candidate || lib.integerFullVersion(release.version) > candidate.integerVersion)) {
+						candidate = lib.ModInfo.fromJSON({
+							...release.info_json, // Also includes dependences
+							sha1: release.sha1,
+							version: release.version,
+							name: modReleases.name,
+							author: modReleases.owner,
+							title: modReleases.title,
+						});
+					}
+				}
+			}
+
+			// Queue the dependencies of the new candidate
+			if (candidate) {
+				candidateReleases.set(mod.name, candidate);
+				for (const dep of candidate.dependencies) {
+					searchQueue.push(dep);
+				}
 			} else {
-				errorMessage += `: ${error.message}`;
+				candidateReleases.delete(mod.name);
+				skipSearch.add(mod.name);
 			}
-			throw new lib.RequestError(errorMessage);
 		}
+
+		return new lib.ModDependencyResolveRequest.Response(
+			[...candidateReleases.values()],
+			[...invalid.values(), ...[...incompatible.values()].filter(mod => (
+				candidateReleases.has(mod) || builtInModNames.has(mod)
+			))],
+			[...dependencyRequirements.keys()].filter(mod => (
+				!candidateReleases.has(mod) && !incompatible.has(mod) && !invalid.has(mod)
+			)),
+		);
 	}
 
 	async handleModDeleteRequest(request: lib.ModDeleteRequest) {
@@ -1058,7 +1189,7 @@ export default class ControlConnection extends BaseConnection {
 		if (!this._controller.config.get("controller.allow_remote_updates")) {
 			throw new lib.RequestError("Remote updates are disabled on this machine");
 		}
-		return lib.updatePackage("@clusterio/controller");
+		return await lib.updatePackage("@clusterio/controller");
 	}
 
 	async handlePluginUpdateRequest(request: lib.PluginUpdateRequest) {
@@ -1079,9 +1210,7 @@ export default class ControlConnection extends BaseConnection {
 		return this._controller.pluginInfos.map(pluginInfo => lib.PluginDetails.fromNodeEnvInfo(
 			pluginInfo,
 			this._controller.plugins.has(pluginInfo.name),
-			this._controller.config.get(
-				`${pluginInfo.name}.load_plugin` as keyof lib.ControllerConfigFields
-			) as boolean,
+			this._controller.config.get(`${pluginInfo.name}.load_plugin`),
 		));
 	}
 
@@ -1094,6 +1223,10 @@ export default class ControlConnection extends BaseConnection {
 		this.connector._socket!.clusterio_ignore_dump = true;
 		this._controller.debugEvents.on("message", this.ws_dumper);
 	}
+
+	async handleFactorioVersionsRequest(request: lib.FactorioVersionsRequest) {
+		return await this._controller.factorioVersions.get(request.maxAgeMs);
+	}
 }
 
 module.exports = ControlConnection;

packages/controller/src/Controller.ts

@@ -105,6 +105,8 @@ export default class Controller {
 
 	// Cache for mod portal requests
 	modPortalCache = new Map<string, { timestamp: number, data: any[] }>();
+	// Cache for factorio versions
+	factorioVersions = new lib.ValueCache(lib.fetchFactorioVersions);
 
 	static async bootstrap(config: lib.ControllerConfig) {
 		let databaseDirectory = config.get("controller.database_directory");
@@ -135,7 +137,8 @@ export default class Controller {
 
 		const modPacks = new lib.SubscribableDatastore(...await new lib.JsonIdDatastoreProvider(
 			path.join(databaseDirectory, "mod-packs.json"),
-			lib.ModPack.fromJSON.bind(lib.ModPack)
+			lib.ModPack.fromJSON.bind(lib.ModPack),
+			this.migrateModPacks,
 		).bootstrap());
 
 		const roles = new lib.SubscribableDatastore(...await new lib.JsonIdDatastoreProvider(
@@ -549,19 +552,8 @@ export default class Controller {
 				}
 				requests.push(hostConnection.send(new lib.SystemInfoRequest()));
 			}
-			if (!this.config.restartRequired) {
-				// If a restart isn't already required, then test if a new version is installed
-				try {
-					const runningVersion = this.config.get("controller.version");
-					const packageJson = await fs.readJSON(path.join(__dirname, "..", "package.json"));
-					if (runningVersion !== packageJson.version) {
-						this.config.restartRequired = true;
-					}
-				} catch (err: any) {
-					logger.warn(`Failed to read package json:\n${err.stack ?? err.message}`);
-				}
-			}
-			requests.push(lib.gatherSystemInfo("controller", this.canRestart, this.config.restartRequired));
+			const restartRequired = await this.checkRestartRequired();
+			requests.push(lib.gatherSystemInfo("controller", this.canRestart, restartRequired));
 			const newMetrics = await Promise.all(requests);
 			for (const metric of newMetrics) {
 				this.systems.set(metric);
@@ -571,6 +563,46 @@ export default class Controller {
 		}
 	}
 
+	async checkRestartRequired() {
+		if (this.config.restartRequired) {
+			return true;
+		}
+
+		let packageName = "@clusterio/controller";
+		try {
+			// First check the clusterio version
+			const runningVersion = this.config.get("controller.version");
+			const packageJsonPath = require.resolve("@clusterio/controller/package.json");
+			const packageJson = await fs.readJSON(packageJsonPath);
+			if (runningVersion !== packageJson.version) {
+				this.config.restartRequired = true;
+				return true;
+			}
+
+			// Second check plugin versions
+			for (const pluginInfo of this.pluginInfos) {
+				if (
+					!pluginInfo.controllerEntrypoint && !pluginInfo.webEntrypoint
+					|| !this.config.get(`${pluginInfo.name}.load_plugin`)
+				) {
+					continue;
+				}
+
+				packageName = pluginInfo.npmPackage ?? pluginInfo.name;
+				const pluginPackageJsonPath = require.resolve(path.posix.join(pluginInfo.requirePath, "package.json"));
+				const pluginPackageJson = await fs.readJSON(pluginPackageJsonPath);
+				if (pluginInfo.version !== pluginPackageJson.version) {
+					this.config.restartRequired = true;
+					return true;
+				}
+			}
+		} catch (err: any) {
+			logger.warn(`Failed to read package json for ${packageName}:\n${err.stack ?? err.message}`);
+		}
+
+		return false;
+	}
+
 	onAutosaveIntervalChanged() {
 		if (this.autosaveInterval) {
 			clearInterval(this.autosaveInterval);
@@ -673,6 +705,17 @@ export default class Controller {
 		return instance;
 	}
 
+	static migrateModPacks(rawJson: unknown[]): Static<typeof lib.ModPack.jsonSchema>[] {
+		const serialized = rawJson as Static<typeof lib.ModPack.jsonSchema>[];
+		return serialized.map(json => {
+			for (const mod of json.mods) {
+				// migrate: 2.0.0.alpha.22 - json schema now enforces X.Y.Z for mod version, builtins would use X.Y only
+				mod.version = lib.normaliseFullVersion(mod.version);
+			}
+			return json;
+		});
+	}
+
 	static migrateRoles(rawJson: unknown[]): Static<typeof lib.Role.jsonSchema>[] {
 		const serialized = rawJson as Static<typeof lib.Role.jsonSchema>[];
 		return serialized.map(json => {
@@ -1127,7 +1170,7 @@ export default class Controller {
 				logger.warn(`Unable to load dist/web/manifest.json for plugin ${pluginInfo.name}`);
 			}
 
-			if (!this.config.get(`${pluginInfo.name}.load_plugin` as keyof lib.ControllerConfigFields)) {
+			if (!this.config.get(`${pluginInfo.name}.load_plugin`)) {
 				continue;
 			}
 

packages/controller/src/InstanceInfo.ts

@@ -11,7 +11,7 @@ export default class InstanceInfo {
 		public config: lib.InstanceConfig,
 		public status: lib.InstanceStatus,
 		public gamePort?: number,
-		public factorioVersion?: string,
+		public factorioVersion?: lib.TargetVersion,
 		public updatedAtMs = 0,
 	) {
 		this.config = config;
@@ -23,7 +23,7 @@ export default class InstanceInfo {
 		"status": lib.InstanceStatus,
 		"gamePort": Type.Optional(Type.Number()),
 		"updatedAtMs": Type.Optional(Type.Number()),
-		"factorioVersion": Type.Optional(Type.String()),
+		"factorioVersion": Type.Optional(lib.TargetVersionSchema),
 	});
 
 	static fromJSON(json: Static<typeof this.jsonSchema>, location: lib.ConfigLocation) {

packages/controller/src/routes.ts

@@ -109,9 +109,7 @@ function getPlugins(req: Request, res: Response) {
 	for (let pluginInfo of req.app.locals.controller.pluginInfos) {
 		let name = pluginInfo.name;
 		let loaded = req.app.locals.controller.plugins.has(name);
-		let enabled = loaded && req.app.locals.controller.config.get(
-			`${pluginInfo.name}.load_plugin` as keyof lib.ControllerConfigFields,
-		) as unknown as boolean;
+		let enabled = loaded && req.app.locals.controller.config.get(`${pluginInfo.name}.load_plugin`);
 		// Note: Cast through unknown is needed because load_plugin is
 		// defined at runtime and no other fields in the controller config
 		// currently have the boolean type.
@@ -136,6 +134,12 @@ function getPlugins(req: Request, res: Response) {
 	res.send(plugins);
 }
 
+function getClusterName(req: Request, res: Response) {
+	const controller: Controller = req.app.locals.controller;
+	const clusterName = controller.config.get("controller.name");
+	res.json({ name: clusterName });
+}
+
 function validateHostToken(req: Request, res: Response, next: any) {
 	let token = req.header("x-access-token");
 	if (!token) {
@@ -664,6 +668,7 @@ async function uploadMod(req: Request, res: Response) {
 export function addRouteHandlers(app: Application) {
 	app.get("/metrics", (req:Request, res:Response, next:any) => getMetrics(req, res, next).catch(next));
 	app.get("/api/plugins", getPlugins);
+	app.get("/api/cluster-name", getClusterName);
 	app.put("/api/upload-export",
 		validateHostToken,
 		(req:Request, res:Response, next:any) => uploadExport(req, res).catch(next)

packages/create/create.js

@@ -754,8 +754,8 @@ async function inquirerMissingArgs(args) {
 async function downloadLinuxServer() {
 	let res = await fetch("https://factorio.com/get-download/stable/headless/linux64");
 
-	const url = new URL(res.headers.location);
 	// get the filename of the latest factorio archive from redirected url
+	const url = new URL(res.url); // The res is redirects, need final url
 	const filename = path.posix.basename(url.pathname);
 	const match = filename.match(/(?<=factorio_headless_x64_|factorio-headless_linux_)\d+\.\d+\.\d+(?=\.tar\.xz)/);
 	if (!match || !match.length) {
@@ -772,10 +772,7 @@ async function downloadLinuxServer() {
 	if (await fs.pathExists(factorioDir)) {
 		logger.warn(`setting downloadDir to ${factorioDir}, but not downloading because already existing`);
 	} else {
-		await fs.ensureDir(tmpDir);
-
-		// follow the redirect
-		res = await fetch(url.href);
+		await fs.emptyDir(tmpDir);
 
 		logger.info("Downloading latest Factorio server release. This may take a while.");
 		const writeStream = fs.createWriteStream(tmpArchivePath);
@@ -794,8 +791,10 @@ async function downloadLinuxServer() {
 			throw e;
 		}
 
-		await fs.unlink(archivePath);
+		await fs.ensureDir("factorio");
 		await fs.rename(tmpFactorioDir, factorioDir);
+		await fs.unlink(archivePath);
+		await fs.rm(tmpDir);
 	}
 }
 
@@ -821,6 +820,10 @@ async function main() {
 		.option("http-port", {
 			nargs: 1, describe: "HTTP port to listen on [standalone/controller]", type: "number",
 		})
+		.option("download-headless", {
+			describe: "Download the latest headless release [standalone/controller] [linux only]",
+			type: "boolean", nargs: 0,
+		})
 		.option("host-name", {
 			nargs: 1, describe: "Host name [host]", type: "string",
 		})

packages/create/package.json

@@ -3,7 +3,7 @@
 	"description": "Installer for clusterio",
 	"author": "Hornwitser",
 	"license": "MIT",
-	"version": "2.0.0-alpha.21c",
+	"version": "2.0.0-alpha.22b",
 	"main": "create.js",
 	"bin": {
 		"clusteriocreate": "./create.js"
@@ -13,11 +13,11 @@
 		"factorio"
 	],
 	"engines": {
-		"node": ">=18"
+		"node": ">=20"
 	},
 	"dependencies": {
-		"chalk": "^4.1.2",
-		"fs-extra": "^11.3.0",
+		"chalk": "catalog:",
+		"fs-extra": "catalog:",
 		"inquirer": "^8.2.4",
 		"yargs": "^17.7.2"
 	},

packages/create/template.js

@@ -94,8 +94,8 @@ async function copyPluginTemplates(pluginName, templates) {
 	const commonPath = path.resolve(__dirname, "./templates/common");
 
 	// Files included in all templates
-	files.set(".gitignore", path.join(commonPath, ".gitignore"));
-	files.set(".npmignore", path.join(commonPath, ".npmignore"));
+	files.set(".gitignore", path.join(commonPath, "template.gitignore"));
+	files.set(".npmignore", path.join(commonPath, "template.npmignore"));
 	files.set("package.json", path.join(commonPath, "package.json"));
 	files.set(`index.${ext}`, path.join(templatePath, `index.${ext}`));
 

packages/create/templates/common/package.json

@@ -15,6 +15,18 @@
 		"node": "__node_version__"
 	},
 	"peerDependencies": {
+//%if controller
+		"@clusterio/controller": "^__clusterio_version__",
+//%endif
+//%if webpack
+		"@clusterio/web_ui": "^__clusterio_version__",
+//%endif
+//%if host
+		"@clusterio/host": "^__clusterio_version__",
+//%endif
+//%if ctl
+		"@clusterio/ctl": "^__clusterio_version__",
+//%endif
 		"@clusterio/lib": "^__clusterio_version__"
 	},
 	"devDependencies": {
@@ -36,7 +48,18 @@
 		"webpack": "^5.88.2",
 		"webpack-cli": "^5.1.4",
 		"webpack-merge": "^5.9.0",
+//%endif
+//%if controller
+		"@clusterio/controller": "^__clusterio_version__",
+//%endif
+//%if webpack
 		"@clusterio/web_ui": "^__clusterio_version__",
+//%endif
+//%if host
+		"@clusterio/host": "^__clusterio_version__",
+//%endif
+//%if ctl
+		"@clusterio/ctl": "^__clusterio_version__",
 //%endif
 		"@clusterio/lib": "^__clusterio_version__"
 	},

packages/ctl/ctl.ts

@@ -189,6 +189,7 @@ export async function initialize(
 			default: "plugin-list.json",
 			type: "string",
 		})
+		.option("bypass-lock-file", { hidden: true, type: "boolean", nargs: 0, default: false })
 		.command("plugin", "Manage available plugins", lib.pluginCommand)
 		.command("control-config", "Manage Control config", lib.configCommand)
 		.wrap(parser.terminalWidth())
@@ -234,8 +235,14 @@ export async function initialize(
 		.parse(argv) as CtlArguments
 	;
 
-	let controlConfig;
 	const controlConfigPath = args.config;
+	const controlConfigLockPath = `${controlConfigPath}.lock`;
+	if (args.bypassLockFile) {
+		await fs.unlink(controlConfigLockPath).catch(() => {}); // ignore error, file might not exist
+	}
+
+	let controlConfig;
+	const controlConfigLock = new lib.LockFile(controlConfigLockPath);
 	logger.verbose(`Loading config from ${controlConfigPath}`);
 	try {
 		controlConfig = await lib.ControlConfig.fromFile("control", controlConfigPath);
@@ -257,7 +264,7 @@ export async function initialize(
 
 	// Handle the control-config command before trying to connect.
 	if (args._[0] === "control-config") {
-		await lib.handleConfigCommand(args, controlConfig);
+		await lib.handleConfigCommand(args, controlConfig, controlConfigLock);
 		return { args, controlConfig, ctlPlugins, rootCommands, shouldRun: false };
 	}
 

packages/ctl/package.json

@@ -3,7 +3,7 @@
 	"description": "Clusterio command line management tool",
 	"author": "Hornwitser",
 	"license": "MIT",
-	"version": "2.0.0-alpha.21",
+	"version": "2.0.0-alpha.22",
 	"main": "dist/node/index.js",
 	"scripts": {
 		"prepare": "tsc --build",
@@ -17,25 +17,25 @@
 		"factorio"
 	],
 	"engines": {
-		"node": ">=18"
+		"node": ">=20"
 	},
 	"dependencies": {
 		"@clusterio/lib": "workspace:*",
+		"set-blocking": "catalog:",
+		"fs-extra": "catalog:",
+		"winston": "catalog:",
+		"phin": "catalog:",
 		"as-table": "^1.0.55",
-		"fs-extra": "^11.3.0",
-		"phin": "^3.7.0",
-		"set-blocking": "^2.0.0",
-		"winston": "^3.17.0",
 		"yargs": "^17.7.2"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
 	"devDependencies": {
-		"@types/fs-extra": "^11.0.1",
-		"@types/node": "^20.17.19",
-		"@types/set-blocking": "^2.0.0",
+		"@types/fs-extra": "catalog:",
+		"@types/node": "catalog:",
+		"@types/set-blocking": "catalog:",
 		"@types/yargs": "^17.0.33",
-		"typescript": "^5.7.3"
+		"typescript": "catalog:"
 	}
 }

packages/ctl/src/commands.ts

@@ -1362,7 +1362,7 @@ function setModPackMods(modPack: lib.ModPack, mods: string[] | undefined) {
 		if (!version) {
 			throw new lib.CommandError("Added mod must be formatted as name:version or name:version:sha1");
 		}
-		if (!/^\d+\.\d+\.\d+$/.test(version)) {
+		if (!lib.isFullVersion(version)) {
 			throw new lib.CommandError("version must match the format digit.digit.digit");
 		}
 		if (sha1 && !/^[0-9a-f]{40}$/.test(sha1)) {
@@ -1415,8 +1415,8 @@ modPackCommands.add(new lib.Command({
 		modPack.name = args.name;
 		if (args.description) { modPack.description = args.description; }
 		if (args.factorioVersion) {
-			if (!/^\d+\.\d+\.\d+?$/.test(args.factorioVersion)) {
-				throw new lib.CommandError("factorio-version must match the format digit.digit.digit");
+			if (!lib.isPartialVersion(args.factorioVersion)) {
+				throw new lib.CommandError("factorio-version must match the format digit.digit[.digit]");
 			}
 			modPack.factorioVersion = args.factorioVersion;
 		}
@@ -1496,8 +1496,8 @@ modPackCommands.add(new lib.Command({
 		if (args.name) { modPack.name = args.name; }
 		if (args.description) { modPack.description = args.description; }
 		if (args.factorioVersion) {
-			if (!/^\d+\.\d+\.\d+?$/.test(args.factorioVersion)) {
-				throw new lib.CommandError("factorio-version must match the format digit.digit.digit");
+			if (!lib.isPartialVersion(args.factorioVersion)) {
+				throw new lib.CommandError("factorio-version must match the format digit.digit[.digit]");
 			}
 			modPack.factorioVersion = args.factorioVersion;
 		}
@@ -1551,6 +1551,9 @@ modCommands.add(new lib.Command({
 		yargs.positional("mod-version", { describe: "Version of the mod", type: "string" });
 	}],
 	handler: async function(args: { name: string, modVersion: string }, control: Control) {
+		if (!lib.isFullVersion(args.modVersion)) {
+			throw new lib.CommandError("mod-version must match format digit.digit.digit");
+		}
 		let modInfo = await control.send(new lib.ModGetRequest(args.name, args.modVersion));
 		for (let [field, value] of Object.entries(modInfo)) {
 			if (value instanceof Array) {
@@ -1638,7 +1641,7 @@ modCommands.add(new lib.Command({
 	) {
 		let response = await control.send(new lib.ModSearchRequest(
 			args.query,
-			args.factorioVersion,
+			lib.normaliseApiVersion(args.factorioVersion as any),
 			args.page,
 			args.pageSize,
 			args.sort,
@@ -1717,6 +1720,9 @@ modCommands.add(new lib.Command({
 		yargs.positional("mod-version", { describe: "Version of mod to download", type: "string" });
 	}],
 	handler: async function(args: { name: string, modVersion: string }, control: Control) {
+		if (!lib.isFullVersion(args.modVersion)) {
+			throw new lib.CommandError("mod-version must match format digit.digit.digit");
+		}
 		let streamId = await control.send(new lib.ModDownloadRequest(args.name, args.modVersion));
 
 		let url = new URL(control.config.get("control.controller_url")!);
@@ -1757,6 +1763,9 @@ modCommands.add(new lib.Command({
 		yargs.positional("mod-version", { describe: "Version of mod to delete", type: "string" });
 	}],
 	handler: async function(args: { name: string, modVersion: string }, control: Control) {
+		if (!lib.isFullVersion(args.modVersion)) {
+			throw new lib.CommandError("mod-version must match format digit.digit.digit");
+		}
 		await control.send(new lib.ModDeleteRequest(args.name, args.modVersion));
 	},
 }));

packages/host/host.ts

@@ -113,6 +113,7 @@ async function startHost() {
 			default: "plugin-list.json",
 			type: "string",
 		})
+		.option("bypass-lock-file", { hidden: true, type: "boolean", nargs: 0, default: false })
 		.command("plugin", "Manage available plugins", lib.pluginCommand)
 		.command("config", "Manage Host config", lib.configCommand)
 		.command("run", "Run host", yargs => {
@@ -167,8 +168,14 @@ async function startHost() {
 	lib.registerPluginMessages(pluginInfos);
 	lib.addPluginConfigFields(pluginInfos);
 
-	let hostConfig;
 	const hostConfigPath = args.config;
+	const hostConfigLockPath = `${hostConfigPath}.lock`;
+	if (args.bypassLockFile) {
+		await fs.unlink(hostConfigLockPath).catch(() => {}); // ignore error, file might not exist
+	}
+
+	let hostConfig;
+	const hostConfigLock = new lib.LockFile(hostConfigLockPath);
 	logger.info(`Loading config from ${hostConfigPath}`);
 	try {
 		hostConfig = await lib.HostConfig.fromFile("host", hostConfigPath);
@@ -186,10 +193,13 @@ async function startHost() {
 	hostConfig.set("host.version", version); // Allows tracking last loaded version
 
 	if (command === "config") {
-		await lib.handleConfigCommand(args, hostConfig);
+		await lib.handleConfigCommand(args, hostConfig, hostConfigLock);
 		return;
 	}
 
+	// From this point on the host should run
+	await hostConfigLock.acquire();
+
 	// If we get here the command was run
 	await fs.ensureDir(hostConfig.get("host.instances_directory"));
 	await fs.ensureDir(hostConfig.get("host.mods_directory"));

packages/host/modules/clusterio/serialize.lua

@@ -70,7 +70,6 @@ function serialize.serialize_equipment_grid(grid)
 					if equipment.to_be_removed then
 						entry.t = equipment.to_be_removed
 					end
-					log(entry)
 					table.insert(serialized, entry)
 				end
 			end

packages/host/package.json

@@ -3,10 +3,11 @@
 	"description": "Implementation of Clusterio host server",
 	"author": "Hornwitser",
 	"license": "MIT",
-	"version": "2.0.0-alpha.21",
+	"version": "2.0.0-alpha.22b",
 	"main": "dist/node/index.js",
 	"scripts": {
 		"prepare": "tsc --build",
+		"build-mod": "node ../lib/build_mod.js --source-dir ./lua/clusterio_lib",
 		"test": "echo \"Error: no test specified\" && exit 1"
 	},
 	"bin": {
@@ -17,33 +18,33 @@
 		"factorio"
 	],
 	"engines": {
-		"node": ">=18"
+		"node": ">=20"
 	},
 	"dependencies": {
 		"@clusterio/lib": "workspace:*",
-		"@sinclair/typebox": "^0.30.4",
-		"fs-extra": "^11.3.0",
+		"@sinclair/typebox": "catalog:",
+		"set-blocking": "catalog:",
+		"fs-extra": "catalog:",
+		"jszip": "catalog:",
+		"phin": "catalog:",
+		"winston": "catalog:",
+		"winston-daily-rotate-file": "catalog:",
 		"jimp": "^0.22.8",
-		"jszip": "^3.10.1",
-		"phin": "^3.7.0",
 		"pidusage": "^3.0.2",
 		"rcon-client": "^4.2.5",
 		"semver": "^7.7.1",
-		"set-blocking": "^2.0.0",
-		"winston": "^3.17.0",
-		"winston-daily-rotate-file": "^4.7.1",
 		"yargs": "^17.7.2"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
 	"devDependencies": {
-		"@types/fs-extra": "^11.0.1",
-		"@types/node": "^20.17.19",
+		"@types/node": "catalog:",
+		"@types/fs-extra": "catalog:",
+		"@types/set-blocking": "catalog:",
 		"@types/pidusage": "^2.0.2",
 		"@types/semver": "^7.5.0",
-		"@types/set-blocking": "^2.0.0",
 		"@types/yargs": "^17.0.33",
-		"typescript": "^5.7.3"
+		"typescript": "catalog:"
 	}
 }

packages/host/src/Host.ts

@@ -410,7 +410,7 @@ export default class Host extends lib.Link {
 		for (let pluginInfo of this.pluginInfos) {
 			if (
 				!pluginInfo.hostEntrypoint && !pluginInfo.instanceEntrypoint
-				|| !this.config.get(`${pluginInfo.name}.load_plugin` as keyof lib.HostConfigFields)
+				|| !this.config.get(`${pluginInfo.name}.load_plugin`)
 			) {
 				continue;
 			}
@@ -693,7 +693,8 @@ export default class Host extends lib.Link {
 				instanceConnection ? instanceConnection.instance.server.gamePort : this.gamePort(instanceId),
 				instanceConnection
 					? instanceConnection.instance.server.version
-					: instanceInfo.config.get("factorio.version"),
+					// TODO: factorio.version is not validated
+					: instanceInfo.config.get("factorio.version") as lib.TargetVersion,
 			)
 		);
 
@@ -805,19 +806,48 @@ export default class Host extends lib.Link {
 	}
 
 	async handleSystemInfoRequest() {
-		if (!this.config.restartRequired) {
-			// If a restart isn't already required, then test if a new version is installed
-			try {
-				const runningVersion = this.config.get("host.version");
-				const packageJson = await fs.readJSON(path.join(__dirname, "..", "package.json"));
-				if (runningVersion !== packageJson.version) {
-					this.config.restartRequired = true;
-				}
-			} catch (err: any) {
-				logger.warn(`Failed to read package json:\n${err.stack ?? err.message}`);
-			}
+		const restartRequired = await this.checkRestartRequired();
+		return lib.gatherSystemInfo(this.config.get("host.id"), this.canRestart, restartRequired);
+	}
+
+	async checkRestartRequired() {
+		if (this.config.restartRequired) {
+			return true;
 		}
-		return lib.gatherSystemInfo(this.config.get("host.id"), this.canRestart, this.config.restartRequired);
+
+		let packageName = "@clusterio/host";
+		try {
+			// First check the clusterio version
+			const runningVersion = this.config.get("host.version");
+			const packageJsonPath = require.resolve("@clusterio/host/package.json");
+			const packageJson = await fs.readJSON(packageJsonPath);
+			if (runningVersion !== packageJson.version) {
+				this.config.restartRequired = true;
+				return true;
+			}
+
+			// Second check plugin versions
+			for (const pluginInfo of this.pluginInfos) {
+				if (
+					!pluginInfo.hostEntrypoint && !pluginInfo.instanceEntrypoint
+					|| !this.config.get(`${pluginInfo.name}.load_plugin`)
+				) {
+					continue;
+				}
+
+				packageName = pluginInfo.npmPackage ?? pluginInfo.name;
+				const pluginPackageJsonPath = require.resolve(path.posix.join(pluginInfo.requirePath, "package.json"));
+				const pluginPackageJson = await fs.readJSON(pluginPackageJsonPath);
+				if (pluginInfo.version !== pluginPackageJson.version) {
+					this.config.restartRequired = true;
+					return true;
+				}
+			}
+		} catch (err: any) {
+			logger.warn(`Failed to read package json for ${packageName}:\n${err.stack ?? err.message}`);
+		}
+
+		return false;
 	}
 
 	async handleHostMetricsRequest() {
@@ -1066,7 +1096,7 @@ export default class Host extends lib.Link {
 		if (!this.config.get("host.allow_remote_updates")) {
 			throw new lib.RequestError("Remote updates are disabled on this machine");
 		}
-		return lib.updatePackage("@clusterio/host");
+		return await lib.updatePackage("@clusterio/host");
 	}
 
 	async handlePluginUpdateRequest(request: lib.PluginUpdateRequest) {
@@ -1087,7 +1117,7 @@ export default class Host extends lib.Link {
 		return this.pluginInfos.map(pluginInfo => lib.PluginDetails.fromNodeEnvInfo(
 			pluginInfo,
 			this.plugins.has(pluginInfo.name),
-			this.config.get(`${pluginInfo.name}.load_plugin` as keyof lib.HostConfigFields) as boolean,
+			this.config.get(`${pluginInfo.name}.load_plugin`),
 		));
 	}
 

packages/host/src/Instance.ts

@@ -210,7 +210,8 @@ export default class Instance extends lib.Link {
 
 		let serverOptions = {
 			logger: this.logger,
-			version: this.config.get("factorio.version"),
+			// TODO: factorio.version is not validated
+			version: this.config.get("factorio.version") as lib.TargetVersion,
 			executablePath: this.config.get("factorio.executable_path") ?? undefined,
 			gamePort: this.config.get("factorio.game_port") ?? host.assignGamePort(this.id),
 			rconPort: this.config.get("factorio.rcon_port") ?? undefined,
@@ -553,7 +554,8 @@ end`.replace(/\r?\n/g, " ");
 				this.id,
 				status,
 				this.server.gamePort,
-				status === "running"? this.server.version : this.config.get("factorio.version"),
+				// TODO: factorio.version is not validated
+				status === "running" ? this.server.version : this.config.get("factorio.version") as lib.TargetVersion,
 			),
 		);
 	}
@@ -651,7 +653,7 @@ end`.replace(/\r?\n/g, " ");
 			if (
 				!pluginInfo.instanceEntrypoint
 				|| !this._host.serverPlugins.has(pluginInfo.name)
-				|| !this.config.get(`${pluginInfo.name}.load_plugin` as keyof lib.InstanceConfigFields)
+				|| !this.config.get(`${pluginInfo.name}.load_plugin`)
 			) {
 				continue;
 			}
@@ -960,10 +962,15 @@ end`.replace(/\r?\n/g, " ");
 		this._loadedSave = saveName;
 		await this.server.start(saveName);
 
-		if (this.config.get("factorio.enable_save_patching") && this.config.get("factorio.enable_script_commands")) {
+		if (this.config.get("factorio.enable_script_commands")) {
 			await this.server.disableAchievements();
-			await this.updateInstanceData();
+		}
+
+		if (this.config.get("factorio.enable_save_patching")) {
 			this._watchPlayerPromote();
+			if (this.config.get("factorio.enable_script_commands")) {
+				await this.updateInstanceData();
+			}
 		} else {
 			this._watchServerLogActions();
 		}

packages/host/src/server.ts

@@ -79,7 +79,7 @@ function versionOrder(a: string, b: string) {
  * @returns Array with path to data dir and version found.
  * @internal
  */
-async function findVersion(factorioDir: string, targetVersion: string) {
+async function findVersion(factorioDir: string, targetVersion: lib.TargetVersion): Promise<[string, lib.FullVersion]> {
 
 	// There are two supported setups: having the factorio dir be the actual
 	// install directory, and having the factorio dir be a folder containing
@@ -87,8 +87,10 @@ async function findVersion(factorioDir: string, targetVersion: string) {
 
 	let simpleVersion = await getVersion(path.join(factorioDir, "data", "changelog.txt"));
 	if (simpleVersion !== null) {
-		if (simpleVersion === targetVersion || targetVersion === "latest") {
-			return [path.join(factorioDir, "data"), simpleVersion];
+		if (simpleVersion === targetVersion || simpleVersion.startsWith(targetVersion) || targetVersion === "latest") {
+			if (lib.isFullVersion(simpleVersion)) {
+				return [path.join(factorioDir, "data"), simpleVersion];
+			}
 		}
 
 		throw new Error(
@@ -96,14 +98,14 @@ async function findVersion(factorioDir: string, targetVersion: string) {
 		);
 	}
 
-	let versions = new Map();
+	let versions = new Map<lib.FullVersion, string>();
 	for (let entry of await fs.readdir(factorioDir, { withFileTypes: true })) {
 		if (!entry.isDirectory()) {
 			continue;
 		}
 
 		let version = await getVersion(path.join(factorioDir, entry.name, "data", "changelog.txt"));
-		if (version === null) {
+		if (version === null || !lib.isFullVersion(version)) {
 			continue;
 		}
 
@@ -118,9 +120,17 @@ async function findVersion(factorioDir: string, targetVersion: string) {
 		throw new Error(`Unable to find any Factorio install in ${factorioDir}`);
 	}
 
+	if (lib.isPartialVersion(targetVersion)) {
+		const sorted = [...versions.keys()].sort(versionOrder);
+		const latest = sorted.find(version => version.startsWith(targetVersion));
+		if (latest) {
+			return [path.join(factorioDir, versions.get(latest)!, "data"), latest];
+		}
+	}
+
 	if (targetVersion === "latest") {
-		let latest = [...versions.keys()].sort(versionOrder)[0];
-		return [path.join(factorioDir, versions.get(latest), "data"), latest];
+		const latest = [...versions.keys()].sort(versionOrder)[0];
+		return [path.join(factorioDir, versions.get(latest)!, "data"), latest];
 	}
 
 	throw new Error(`Unable to find Factorio version ${targetVersion}`);
@@ -423,7 +433,7 @@ export interface FactorioServerOptions {
 	 * Version of Factorio to use.  Can also be the string "latest" to use
 	 * the latest version found in `factorioDir`.
 	 */
-	version?: string,
+	version?: lib.TargetVersion,
 	/** Path to executable to invoke when starting the server */
 	executablePath?: string;
 	/** UDP port to host game on. */
@@ -523,7 +533,7 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
 	_writeDir: string;
 
 	// Resolved in init
-	_version: string | null = null;
+	_version: lib.FullVersion | null = null;
 	_dataDir: string | null = null;
 
 	// Due to inconsistencies in the factorio api, we must manually watch the whitelist
@@ -532,7 +542,7 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
 	_whitelist = new Set<string>();
 
 	_logger: lib.Logger;
-	_targetVersion: string;
+	_targetVersion: lib.TargetVersion;
 	_state: "new" | "init" | "create" | "running" | "stopping" = "new";
 	_server: child_process.ChildProcessWithoutNullStreams | null = null;
 	_rconClient: Rcon | null= null;
@@ -866,7 +876,7 @@ export class FactorioServer extends events.EventEmitter<FactorioServerEvents> {
 	 * "latest" (the default) was specified as `factorioVersion` to the constructor.
 	 * This will be undefined before the server is initialized, or if init failed.
 	 */
-	get version(): string | undefined {
+	get version(): lib.FullVersion | undefined {
 		return this._version ?? undefined;
 	}
 

packages/lib/browser.ts

@@ -15,3 +15,4 @@ export * from "./src/subscriptions";
 
 export { default as ExponentialBackoff } from "./src/ExponentialBackoff";
 export { default as RateLimiter } from "./src/RateLimiter";
+export { default as ValueCache } from "./src/ValueCache";

packages/lib/build_mod.js

@@ -115,9 +115,21 @@ async function main() {
 			"clean": { describe: "Remove previous builds", type: "boolean", default: false },
 			"build": { describe: "Build mod(s)", type: "boolean", default: true },
 			"pack": { describe: "Pack into zip file", type: "boolean", default: true },
-			"source-dir": { describe: "Path to mod source files", nargs: 1, type: "string", demandOption: true },
-			"output-dir": { describe: "Path to output built mod(s)", nargs: 1, type: "string", default: "dist" },
 			"factorio-version": { describe: "Override factorio_version", type: "string" },
+			"source-dir": {
+				describe: "Path to mod source files",
+				type: "string",
+				nargs: 1,
+				normalize: true,
+				demandOption: true,
+			},
+			"output-dir": {
+				describe: "Path to output built mod(s)",
+				type: "string",
+				nargs: 1,
+				normalize: true,
+				default: "dist/factorio",
+			},
 		})
 		.strict()
 		.argv

packages/lib/index.ts

@@ -9,6 +9,7 @@ export * from "./src/config";
 export * from "./src/data";
 export * from "./src/database";
 export * from "./src/errors";
+export * from "./src/external";
 export * from "./src/factorio";
 export * from "./src/file_ops";
 export * from "./src/hash";
@@ -31,7 +32,9 @@ export * from "./src/subscriptions";
 export * from "./src/datastore";
 export * from "./src/load_plugin_list";
 export * from "./src/rce_ops";
+export * from "./src/LockFile";
 
 export { default as ExponentialBackoff } from "./src/ExponentialBackoff";
 export { default as ModStore } from "./src/ModStore";
 export { default as RateLimiter } from "./src/RateLimiter";
+export { default as ValueCache } from "./src/ValueCache";

packages/lib/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@clusterio/lib",
 	"description": "Shared library for Clusterio",
-	"version": "2.0.0-alpha.21",
+	"version": "2.0.0-alpha.22b",
 	"repository": "https://github.com/clusterio/clusterio",
 	"license": "MIT",
 	"scripts": {
@@ -18,30 +18,30 @@
 		"node": ">=12"
 	},
 	"dependencies": {
-		"@sinclair/typebox": "^0.30.4",
-		"ajv": "^8.17.1",
-		"chalk": "^4.1.2",
+		"@sinclair/typebox": "catalog:",
+		"set-blocking": "catalog:",
+		"fs-extra": "catalog:",
+		"jszip": "catalog:",
+		"chalk": "catalog:",
+		"ws": "catalog:",
+		"winston": "catalog:",
+		"winston-transport": "catalog:",
 		"fast-deep-equal": "^3.1.3",
-		"fs-extra": "^11.3.0",
-		"jszip": "^3.10.1",
-		"klaw": "^4.1.0",
-		"set-blocking": "^2.0.0",
 		"triple-beam": "^1.4.1",
-		"winston": "^3.17.0",
-		"winston-transport": "^4.9.0",
-		"ws": "^8.18.1",
+		"ajv": "^8.17.1",
+		"klaw": "^4.1.0",
 		"yargs": "^17.7.2"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
 	"devDependencies": {
-		"@types/fs-extra": "^11.0.1",
-		"@types/node": "^20.17.19",
-		"@types/set-blocking": "^2.0.0",
+		"@types/fs-extra": "catalog:",
+		"@types/node": "catalog:",
+		"@types/ws": "catalog:",
+		"@types/set-blocking": "catalog:",
 		"@types/triple-beam": "^1.3.2",
-		"@types/ws": "^8.5.14",
 		"@types/yargs": "^17.0.33",
-		"typescript": "^5.7.3"
+		"typescript": "catalog:"
 	}
 }

packages/lib/src/LockFile.ts

@@ -0,0 +1,163 @@
+import { FileHandle, open, unlink, readFile } from "fs/promises";
+import { unlinkSync } from "fs";
+import assert from "assert";
+
+/**
+ * Error thrown when the lock file already exists.
+ */
+export class LockFileExistsError extends Error {
+	constructor(
+		readonly filePath: string
+	) {
+		super(`Cannot acquire lock, a valid lock file exists at ${filePath}`);
+		this.name = "LockFileExistsError";
+	}
+}
+
+/**
+ * Error thrown when the acquire or release called during an invalid state.
+ */
+export class LockFileBusyError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "LockFileBusyError";
+	}
+}
+
+type LockState = "idle" | "acquiring" | "acquired" | "releasing";
+
+/**
+ * Cross-platform lock file utility for Node.js.
+ */
+export class LockFile {
+	private handle: FileHandle | null = null;
+	private state: LockState = "idle";
+
+	constructor(
+		private readonly filePath: string
+	) {}
+
+	/**
+	 * Acquire the lock file.
+	 * Throws LockFileExistsError if already locked.
+	 * Throws LockFileBusyError if not in idle state.
+	 */
+	async acquire(): Promise<void> {
+		if (this.state !== "idle") {
+			throw new LockFileBusyError(`Cannot acquire lock, current state is "${this.state}"`);
+		}
+
+		this.state = "acquiring";
+
+		if (await this.isStale()) {
+			await unlink(this.filePath).catch(() => {}); // ignore errors, may already be removed
+		}
+
+		try {
+			this.handle = await open(this.filePath, "wx");
+			await this.handle.write(`${process.pid}\n`);
+			this.attachExitHandlers();
+			this.state = "acquired";
+		} catch (err: any) {
+			this.state = "idle";
+			if (err?.code === "EEXIST") {
+				throw new LockFileExistsError(this.filePath);
+			}
+			throw err;
+		}
+	}
+
+	/**
+	 * Release the lock file.
+	 * Throws LockFileBusyError if not in acquired state.
+	 */
+	async release(): Promise<void> {
+		if (this.state !== "acquired") {
+			throw new LockFileBusyError(`Cannot release lock, current state is "${this.state}"`);
+		}
+
+		this.state = "releasing";
+		this.detachExitHandlers();
+
+		// Ignored: file may have already been removed by another process
+		try { await this.handle?.close(); } catch {}
+		try { await unlink(this.filePath); } catch {}
+
+		this.handle = null;
+		this.state = "idle";
+	}
+
+	/**
+	 * Check whether the lock is currently held by this process.
+	 * True only if the lock is acquired and the PID in the file
+	 * matches the current process.
+	 */
+	async isHeld(): Promise<boolean> {
+		if (this.state !== "acquired") {
+			return false;
+		}
+
+		try {
+			const pidInLock = Number(await readFile(this.filePath, "utf8"));
+			return pidInLock === process.pid;
+		} catch {
+    		// Ignored: file may not exist or be unreadable, so lock is not held
+			return false;
+		}
+	}
+
+	/**
+	 * Determine whether an existing lock is stale.
+	 */
+	async isStale(): Promise<boolean> {
+		try {
+			const pidInLock = Number(await readFile(this.filePath, "utf8"));
+			if (!Number.isFinite(pidInLock)) { return true; }
+			// signal 0 is a special case to test if a process exists
+			process.kill(pidInLock, 0);
+			return false;
+		} catch {
+			return true;
+		}
+	}
+
+	/**
+	 * Attach process handlers, called when transitioning to "acquired"
+	 */
+	private attachExitHandlers(): void {
+		assert(this.state === "acquiring");
+		process.on("SIGINT", this.handleExit);
+		process.on("SIGTERM", this.handleExit);
+		process.on("SIGHUP", this.handleExit);
+		process.on("uncaughtException", this.handleExit);
+		// eslint-disable-next-line node/no-sync
+		process.on("exit", this.handleExitSync);
+	}
+
+	/**
+	 * Detach process handlers, called when transitioning to "idle"
+	 */
+	private async detachExitHandlers(): Promise<void> {
+		assert(this.state === "releasing");
+		process.off("SIGINT", this.handleExit);
+		process.off("SIGTERM", this.handleExit);
+		process.off("SIGHUP", this.handleExit);
+		process.off("uncaughtException", this.handleExit);
+		// eslint-disable-next-line node/no-sync
+		process.off("exit", this.handleExitSync);
+	}
+
+  	// Event handler for async signals / exceptions
+	private handleExit = async (): Promise<void> => {
+		await this.release();
+	};
+
+  	// Event handler for synchronous process exit
+	private handleExitSync = (): void => {
+		try {
+			unlinkSync(this.filePath);
+		} catch (err) {
+      		// Ignored: file may have already been removed by another process
+		}
+	};
+}

packages/lib/src/ModStore.ts

@@ -3,10 +3,10 @@ import path from "path";
 import events from "events";
 import { Static } from "@sinclair/typebox";
 import { logger } from "./logging";
-import { ModInfo, ModPack } from "./data";
 import { safeOutputFile } from "./file_ops";
 import { Writable } from "stream";
-import { ModPortalReleaseSchema, ModPortalDetailsSchema } from "./data/messages_mod";
+import { ModPortalReleaseSchema, ModPortalDetailsSchema, ModNameVersionPair } from "./data/messages_mod";
+import { ModInfo, ModPack, FullVersion, ApiVersion, ModVersionEquality } from "./data";
 
 export interface ModStoreEvents {
 	/** A stored mod was created, updated or deleted */
@@ -45,7 +45,7 @@ export default class ModStore extends events.EventEmitter<ModStoreEvents> {
 		super();
 	}
 
-	getMod(name: string, version: string, sha1?: string) {
+	getMod(name: string, version: FullVersion, sha1?: string) {
 		const mod = this.files.get(ModInfo.filename(name, version));
 		if (!mod || sha1 && sha1 !== mod.sha1) {
 			return undefined;
@@ -87,11 +87,11 @@ export default class ModStore extends events.EventEmitter<ModStoreEvents> {
 		this.emit("change", modInfo);
 	}
 
-	async loadMod(name: string, version: string) {
+	async loadMod(name: string, version: FullVersion) {
 		return await this.loadFile(ModInfo.filename(name, version));
 	}
 
-	async deleteMod(name: string, version: string) {
+	async deleteMod(name: string, version: FullVersion) {
 		return await this.deleteFile(ModInfo.filename(name, version));
 	}
 
@@ -155,10 +155,46 @@ export default class ModStore extends events.EventEmitter<ModStoreEvents> {
 		return new this(modsDirectory, files);
 	}
 
-	private async downloadModFromReleases(releases: Array<Static<typeof ModPortalReleaseSchema>>, version: string,
+	/**
+	 * Stream a url's content into a file.
+	 *
+	 * @param url - Web path to stream from.
+	 * @param filePath - File path to stream to.
+	 */
+	private static async downloadFile(url: string | URL, filePath: string) {
+		try {
+			const response = await fetch(url);
+
+			if (!response.ok) {
+				throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+			}
+
+			if (!response.body) {
+				throw new Error("Response body is missing.");
+			}
+
+			const fileStream = fs.createWriteStream(filePath);
+			const writer = Writable.toWeb(fileStream);
+			await response.body.pipeTo(writer);
+		} catch (error) {
+			logger.error("Error downloading file:", error);
+			throw error;
+		}
+	}
+
+	/**
+	 * Download a matching version from a selection of available versions.
+	 *
+	 * @param releases - Array of mod releases taken from the mod portal.
+	 * @param version - The required version to install.
+	 * @param username - Factorio username to download using.
+	 * @param token - Factorio token to download using.
+	 */
+	private async downloadModFromReleases(
+		releases: Array<Static<typeof ModPortalReleaseSchema>>, version: ModVersionEquality,
 		username: string, token: string
 	) {
-		const selectedRelease = releases.find(release => release.version === version);
+		const selectedRelease = releases.find(release => version.testVersion(release.version));
 
 		if (selectedRelease === undefined) {
 			logger.warn(`Mod release matching version ${version} not found.`);
@@ -190,96 +226,83 @@ export default class ModStore extends events.EventEmitter<ModStoreEvents> {
 		}
 	}
 
+	/**
+	 * Downloads all provided mods, does not perform chunking or filtering of builtins
+	 *
+	 * @param mods - An array of mods to download
+	 * @param username - Factorio username used for auth to download mods
+	 * @param token - Factorio token used for auth to download mods
+	 * @param factorioVersion - Factorio version to filter for (mods are not guaranteed to work between Middle versions)
+	 */
 	private async downloadModsChunk(
-		modNames: string[], modVersions: string[], username: string, token: string, factorioVersion: string
+		mods: ModNameVersionPair[],
+		username: string, token: string,
+		factorioVersion: ApiVersion,
 	) {
 		const url = new URL("https://mods.factorio.com/api/mods");
 		url.searchParams.set("page_size", "max");
 		url.searchParams.set("version", factorioVersion);
 		const response = await fetch(url, {
 			method: "POST",
-			body: new URLSearchParams({ namelist: modNames.join(",") }),
+			body: new URLSearchParams({ namelist: mods.map(m => m.name).join(",") }),
 		});
+
 		if (response.status !== 200) {
 			throw Error(`Fetch: ${url} returned ${response.status} ${response.statusText}`);
 		}
-		const mods = (await response.json() as ModsInfoResponse).results;
 
-		await Promise.all(mods.map((mod) => {
+		const modReleases = (await response.json() as ModsInfoResponse).results;
+		await Promise.all(modReleases.map((mod) => {
+			const modVersion = mods.find(m => m.name === mod.name)!.version;
 			if (mod.releases) {
-				return this.downloadModFromReleases(mod.releases,
-					modVersions[modNames.indexOf(mod.name)], username, token);
+				return this.downloadModFromReleases(mod.releases, modVersion, username, token);
 			} else if (mod.latest_release) {
-				return this.downloadModFromReleases([mod.latest_release],
-					modVersions[modNames.indexOf(mod.name)], username, token);
+				return this.downloadModFromReleases([mod.latest_release], modVersion, username, token);
 			}
 			throw new Error(`Mod ${mod.name} has no releases or latest_release`);
 		}));
 	}
 
-
 	/**
+	 * Downloads all provided mods to the mod dir.
 	 *
-	 * downloads mods to the mod dir, will not download mods for which are already in the mod directory
-	 *
-	 * @param modMap a map of what mods to download and what version to download
-	 * @param username factorio username used for auth to download mods
-	 * @param token factorio token used for auth to download mods
-	 * @param factorioVersion factorio version to filter for (mods are not guaranteed to work between Middle versions)
+	 * Handles chunking to prevent errors due to URL length.
+	 * Will re-download if mod is already present, if this is undesired use filterInstalled first.
 	 *
+	 * @param mods - An array of mods to download.
+	 * @param username - Factorio username used for auth to download mods.
+	 * @param token - Factorio token used for auth to download mods.
+	 * @param factorioVersion - Factorio version to filter for (mods are not guaranteed to work between Middle versions)
 	 */
-	async downloadMods(modMap: Map<string, string>, username: string, token: string, factorioVersion: string = "1.1") {
+	async downloadMods(
+		mods: ModNameVersionPair[], username: string, token: string, factorioVersion: ApiVersion = "1.1"
+	) {
 		const chunkSize = 500;
-		let futures: Promise<void>[] = [];
-		modMap = new Map(modMap);
-
-		// Truncate factorioVersion to major.minor (e.g., "1.1.100" -> "1.1") for API/builtin checks
-		const versionParts = factorioVersion.split(".");
-		if (versionParts.length > 2) {
-			factorioVersion = versionParts.slice(0, 2).join(".");
-		}
-
+		const futures: Promise<void>[] = [];
 		const builtInMods = new Set(ModPack.getBuiltinModNames(factorioVersion));
+		mods = mods.filter(mod => !(builtInMods.has(mod.name) || mod.name === "core"));
 
-		// get rid of mods already downloaded, built-in, or core
-		modMap.forEach((modVersion, modName, map) => {
-			const filename = `${modName}_${modVersion}.zip`;
-			// Filter existing, built-in from getBuiltinModNames, and explicitly filter "core"
-			if (this.files.has(filename) || builtInMods.has(modName) || modName === "core") {
-				map.delete(modName);
-			}
-		});
-
-		const modNames = Array.from(modMap.keys());
-		const modVersions = Array.from(modMap.values());
-		for (let i = 0; i < modMap.size; i += chunkSize) {
+		for (let i = 0; i < mods.length; i += chunkSize) {
 			futures.push(
-				this.downloadModsChunk(modNames.slice(i, i + chunkSize), modVersions.slice(i, i + chunkSize),
-					username, token, factorioVersion)
+				this.downloadModsChunk(mods.slice(i, i + chunkSize), username, token, factorioVersion)
 			);
 		}
+
 		await Promise.all(futures);
 	}
 
-	static async downloadFile(url: string | URL, filePath: string) {
-		try {
-			const response = await fetch(url);
-
-			if (!response.ok) {
-				throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
-			}
-
-			if (!response.body) {
-				throw new Error("Response body is missing.");
-			}
-
-			const fileStream = fs.createWriteStream(filePath);
-			const writer = Writable.toWeb(fileStream);
-			await response.body.pipeTo(writer);
-		} catch (error) {
-			logger.error("Error downloading file:", error);
-			throw error;
-		}
+	/**
+	 * Filter an array of mods based on if they are installed.
+	 *
+	 * @param mods - Array of mods to filer.
+	 * @param installed - `true` to keep installed mods, `false` to keep uninstalled mods.
+	 * @returns Filtered array of mods based on install state.
+	 */
+	filterInstalled(mods: ModNameVersionPair[], installed: boolean) {
+		const installedMods = Array.from(this.mods());
+		return mods.filter(mod => (
+			installed === installedMods.some(m => mod.name === m.name && mod.version.testVersion(m.version))
+		));
 	}
 
 	/**
@@ -332,4 +355,19 @@ export default class ModStore extends events.EventEmitter<ModStoreEvents> {
 		logger.info(`Successfully fetched ${allMods.length} mods for Factorio version ${factorioVersion}.`);
 		return allMods;
 	}
+
+	/**
+	 * Fetch the full release list for a mod including dependencies.
+	 *
+	 * @param modName - Name of the mod to fetch the releases of
+	 * @returns Mod portal response
+	 */
+	static async fetchModReleases(modName: string) {
+		const url = `https://mods.factorio.com/api/mods/${modName}/full`;
+		const response = await fetch(url);
+		if (!response.ok) {
+			throw Error(`Fetch: ${url} returned ${response.status} ${response.statusText}`);
+		}
+		return await response.json() as ModsInfoResponse["results"][number];
+	}
 }

packages/lib/src/ValueCache.ts

@@ -0,0 +1,64 @@
+
+/**
+ * Represents an async function which can fetch a value for a ValueCache
+ */
+export interface ValueCacheFetch<T> {
+	(): Promise<T>;
+}
+
+/**
+ * In-memory single value cache
+ *
+ * Stores the last time a value was fetched and measures staleness
+ * Concurrent calls will share the same in-flight fetch
+ */
+export default class ValueCache<T> {
+	private ongoingFetch: Promise<T> | null = null;
+	private timestamp: number | null = null;
+	private value: T | null = null; // Only valid when timestamp is not null
+
+	/**
+	 * Create a new in memory single value cache
+	 *
+	 * @param fetch A function that fetches and returns a fresh value
+	 */
+	constructor(
+		private readonly fetch: ValueCacheFetch<T>,
+	) {}
+
+	/**
+	 * Get the cached value, will fetch a fresh value if stale or missing
+	 *
+	 * @param maxAgeMs Maximum allowed cache age in milliseconds.
+	 *                 Defaults to 0, meaning it will always fetch a new value.
+	 * @throws TypeError if maxAgeMs is invalid
+	 * @throws Propagates errors from underlying fetch method
+	 */
+	get(maxAgeMs: number = 0): Promise<T> {
+		if (maxAgeMs < 0) {
+			throw new TypeError("maxAgeMs must be a non-negative number");
+		}
+
+		const now = Date.now();
+
+		if (this.timestamp && now - this.timestamp < maxAgeMs) {
+			return Promise.resolve(this.value as T);
+		}
+
+		if (this.ongoingFetch) {
+			return this.ongoingFetch;
+		}
+
+		this.ongoingFetch = this.fetch()
+			.then(value => {
+				this.timestamp = Date.now();
+				this.value = value;
+				return value;
+			})
+			.finally(() => {
+				this.ongoingFetch = null;
+			});
+
+		return this.ongoingFetch;
+	}
+}

packages/lib/src/config/definitions.ts

@@ -35,6 +35,7 @@ export interface ControllerConfigFields {
 	"controller.allow_remote_updates": boolean;
 	"controller.allow_plugin_updates": boolean;
 	"controller.allow_plugin_install": boolean;
+	[key: `${string}.load_plugin`]: boolean;
 }
 
 /**
@@ -267,6 +268,7 @@ export interface HostConfigFields {
 	"host.allow_remote_updates": boolean;
 	"host.allow_plugin_updates": boolean;
 	"host.allow_plugin_install": boolean;
+	[key: `${string}.load_plugin`]: boolean;
 }
 
 /**
@@ -399,6 +401,7 @@ export interface InstanceConfigFields {
 	"instance.assigned_host": number | null;
 	"instance.auto_start": boolean;
 	"instance.exclude_from_start_all": boolean;
+	[key: `${string}.load_plugin`]: boolean;
 
 	"factorio.version": string;
 	"factorio.executable_path": string | null;
@@ -476,6 +479,7 @@ export class InstanceConfig extends classes.Config<InstanceConfigFields> {
 			restartRequired: true,
 			type: "string",
 			initialValue: "latest",
+			inputComponent: "target_version",
 		},
 		"factorio.executable_path": {
 			description:

packages/lib/src/data/ModInfo.ts

@@ -5,9 +5,128 @@ import { Type, Static } from "@sinclair/typebox";
 import * as libHash from "../hash";
 import * as libSchema from "../schema";
 import { findRoot } from "../zip_ops";
+import { ModRecord } from "./ModPack";
 
-import { integerModVersion, integerFactorioVersion, modVersionRegExp } from "./version";
+import {
+	ApiVersion,
+	ApiVersionSchema,
+	FullVersion, FullVersionSchema, integerFullVersion,
+	integerPartialVersion,
+	ModVersionEquality,
+} from "./version";
 
+type ModDependencyType = "incompatible" | "optional" | "hidden" | "unordered" | "required";
+
+export type ModDependencyUnsatisfiedReason = "incompatible" | "missing_dependency" | "wrong_version";
+const UnsatisfiedSeverity: Record<ModDependencyUnsatisfiedReason, number> = {
+	"incompatible": 1, "missing_dependency": 2, "wrong_version": 3,
+};
+
+const lettersRegex = /^[a-zA-Z]+$/;
+
+export class ModDependency {
+	public type: ModDependencyType;
+	public name: string;
+	public version: ModVersionEquality | undefined;
+
+	static getTypeFromPrefix(prefix: string): ModDependencyType {
+		switch (prefix) {
+			case "!":
+				return "incompatible";
+			case "?":
+				return "optional";
+			case "(?)":
+				return "hidden";
+			case "~":
+				return "unordered";
+			case "":
+				return "required";
+			default:
+				throw new Error(`Invalid dependency prefix: ${prefix}`);
+		}
+	}
+
+	constructor (
+		public specification: string,
+	) {
+		const parts = specification.split(" ");
+
+		// Fix mods which include spaces in their name, joins consecutive words together
+		let index = 0;
+		while (index < parts.length - 1) {
+			const current = parts[index];
+			const next = parts[index + 1];
+			if (lettersRegex.test(current) && lettersRegex.test(next)) {
+				parts[index] = `${current} ${next}`;
+				parts.splice(index + 1, 1);
+			} else {
+				index += 1;
+			}
+		}
+
+		// Parse the dependency specification
+		switch (parts.length) {
+			case 1:
+				this.type = "required";
+				this.name = parts[0];
+				break;
+			case 2:
+				this.type = ModDependency.getTypeFromPrefix(parts[0]);
+				this.name = parts[1];
+				break;
+			case 3:
+				this.type = "required";
+				this.name = parts[0];
+				this.version = ModVersionEquality.fromParts(parts[1], parts[2]);
+				break;
+			case 4:
+				this.type = ModDependency.getTypeFromPrefix(parts[0]);
+				this.name = parts[1];
+				this.version = ModVersionEquality.fromParts(parts[2], parts[3]);
+				break;
+			default:
+				throw new Error(`Invalid dependency specification: ${specification}`);
+		}
+	}
+
+	checkUnsatisfiedReason(mods: (ModInfo | ModRecord)[]): ModDependencyUnsatisfiedReason | undefined {
+		const mod = mods.find(m => m.name === this.name);
+		if (mod === undefined) {
+			return ["unordered", "required"].includes(this.type) ? "missing_dependency" : undefined;
+		} else if (this.type === "incompatible") {
+			return "incompatible";
+		} else if (this.version && !this.version.testVersion(mod.version)) {
+			return "wrong_version";
+		}
+		return undefined;
+	}
+
+	isSatisfied(mods: (ModInfo | ModRecord)[]) {
+		return this.checkUnsatisfiedReason(mods) === undefined;
+	}
+
+	get incompatible() {
+		return this.type === "incompatible";
+	}
+
+	get required() {
+		return this.type === "unordered" || this.type === "required";
+	}
+
+	get optional() {
+		return this.type === "hidden" || this.type === "optional";
+	}
+
+	static jsonSchema = Type.String();
+
+	static fromJSON(json: Static<typeof this.jsonSchema>) {
+		return new this(json);
+	}
+
+	toJSON() {
+		return this.specification;
+	}
+}
 
 /**
  * Info about a mod available on the controller.
@@ -35,13 +154,13 @@ export default class ModInfo {
 	 * Version of the mod.
 	 * Sourced from info.json.
 	 */
-	version = "";
+	version = "0.0.0" as FullVersion;
 
 	/**
 	 * Integer representation of the version
 	 */
 	get integerVersion() {
-		return integerModVersion(this.version);
+		return integerFullVersion(this.version);
 	}
 
 	/**
@@ -78,21 +197,38 @@ export default class ModInfo {
 	 * Major version of Factorio this mod supports.
 	 * Sourced from info.json.
 	 */
-	factorioVersion = "0.12";
+	factorioVersion = "0.12" as "0.12" | ApiVersion;
 
 	/**
 	 * Integer representation of the factorioVersion
 	 * @type {number}
 	 */
 	get integerFactorioVersion() {
-		return integerFactorioVersion(this.factorioVersion);
+		return integerPartialVersion(this.factorioVersion);
 	}
 
 	/**
-	 * Dependiences for this mod.
+	 * Dependencies for this mod.
 	 * Sourced from info.json.
 	 */
-	dependencies = ["base"];
+	dependencies = [new ModDependency("base")];
+
+	/**
+	 * Dependencies for this mod.
+	 * As they would be represented in info.json.
+	 */
+	get dependencySpecifications() {
+		return this.dependencies.map(d => d.specification);
+	}
+
+	checkDependencySatisfaction(mods: (ModInfo | ModRecord)[]) {
+		return this.dependencies
+			.map(d => d.checkUnsatisfiedReason(mods))
+			.filter((v): v is ModDependencyUnsatisfiedReason => Boolean(v))
+			.reduce<ModDependencyUnsatisfiedReason | undefined>((max, current) => (
+				!max || UnsatisfiedSeverity[max] > UnsatisfiedSeverity[current] ? current : max
+			), undefined);
+	}
 
 	/**
 	 * Expected name of zip file containing this mod.
@@ -107,7 +243,7 @@ export default class ModInfo {
 	 * @param version - Mod's version
 	 * @returns string containing {name}_{version}.zip
 	 */
-	static filename(name: string, version: string) {
+	static filename(name: string, version: FullVersion) {
 		return `${name}_${version}.zip`;
 	}
 
@@ -137,13 +273,13 @@ export default class ModInfo {
 	// Content of info.json found in mod files
 	static infoJsonSchema = Type.Object({
 		"name": Type.String(),
-		"version": Type.String(),
+		"version": FullVersionSchema,
 		"title": Type.String(),
 		"author": Type.String(),
 		"contact": Type.Optional(Type.String()),
 		"homepage": Type.Optional(Type.String()),
 		"description": Type.Optional(Type.String()),
-		"factorio_version": Type.Optional(Type.String()),
+		"factorio_version": Type.Optional(ApiVersionSchema),
 		"dependencies": Type.Optional(Type.Array(Type.String())),
 	});
 
@@ -172,7 +308,7 @@ export default class ModInfo {
 		if (json.homepage) { modInfo.homepage = json.homepage; }
 		if (json.description) { modInfo.description = json.description; }
 		if (json.factorio_version) { modInfo.factorioVersion = json.factorio_version; }
-		if (json.dependencies) { modInfo.dependencies = json.dependencies; }
+		if (json.dependencies) { modInfo.dependencies = json.dependencies.map(d => new ModDependency(d)); }
 
 		// Additional data
 		if (json.size) { modInfo.size = json.size; }
@@ -195,8 +331,8 @@ export default class ModInfo {
 		if (this.homepage) { json.homepage = this.homepage; }
 		if (this.description) { json.description = this.description; }
 		if (this.factorioVersion !== "0.12") { json.factorio_version = this.factorioVersion; }
-		if (this.dependencies.length !== 1 || this.dependencies[0] !== "base") {
-			json.dependencies = this.dependencies;
+		if (this.dependencies.length !== 1 || this.dependencies[0].name !== "base") {
+			json.dependencies = this.dependencySpecifications;
 		}
 		if (this.size) { json.size = this.size; }
 		if (this.mtimeMs) { json.mtime_ms = this.mtimeMs; }
@@ -227,10 +363,6 @@ export default class ModInfo {
 			throw new Error("Mod's info.json is not valid");
 		}
 
-		if (!modVersionRegExp.test(modInfo.version)) {
-			throw new Error(`Mod's version (${modInfo.version}) is invalid`);
-		}
-
 		const stat = await fs.stat(modPath);
 		return this.fromJSON({
 			...modInfo,

packages/lib/src/data/ModPack.ts

@@ -5,9 +5,15 @@ import * as libSchema from "../schema";
 import * as libLuaTools from "../lua_tools";
 
 import ExportManifest from "./ExportManifest";
-import { integerFactorioVersion } from "./version";
 import type { Logger } from "../logging";
 
+import ModInfo, { ModDependencyUnsatisfiedReason } from "./ModInfo";
+
+import {
+	PartialVersion, PartialVersionSchema, integerPartialVersion,
+	FullVersion, FullVersionSchema, normaliseFullVersion,
+} from "./version";
+
 
 export const ModSettingColor = Type.Object({
 	r: Type.Number(),
@@ -40,17 +46,21 @@ export interface ModRecord {
 	/** if mod is to be loaded. */
 	enabled: boolean,
 	/** version of the mod. */
-	version: string,
+	version: FullVersion,
 	/** SHA1 hash of the zip file. */
 	sha1?: string,
 	/** Used inside packages\web_ui\src\components\ModPackViewPage.tsx to define an error type. */
-	error?: "missing"|"bad_checksum",
+	error?: "missing" | "bad_checksum",
+	/** Used inside packages\web_ui\src\components\ModPackViewPage.tsx to define an warning type. */
+	warning?: ModDependencyUnsatisfiedReason | "wrong_factorio_version",
+	/** Used inside packages\web_ui\src\components\ModPackViewPage.tsx when there is no error. */
+	info?: ModInfo,
 }
 
 const ModRecordJsonSchema = Type.Object({
 	"name": Type.String(),
 	"enabled": Type.Boolean(),
-	"version": Type.String(),
+	"version": FullVersionSchema,
 	"sha1": Type.Optional(Type.String()),
 });
 
@@ -82,13 +92,13 @@ export default class ModPack {
 	/**
 	 * Version of Factorio this mod pack is for
 	 */
-	factorioVersion = "1.1.0";
+	factorioVersion = "1.1.0" as PartialVersion;
 
 	/**
 	 * Integer representation of the factorioVersion
 	 */
 	get integerFactorioVersion() {
-		return integerFactorioVersion(this.factorioVersion);
+		return integerPartialVersion(this.factorioVersion);
 	}
 
 	/**
@@ -136,7 +146,7 @@ export default class ModPack {
 		"id": Type.Optional(Type.Integer()),
 		"name": Type.String(),
 		"description": Type.String(),
-		"factorio_version": Type.String(),
+		"factorio_version": PartialVersionSchema,
 		"mods": Type.Array(ModRecordJsonSchema),
 		"settings": Type.Object({
 			"startup": ModSettingsJsonSchema,
@@ -385,39 +395,40 @@ export default class ModPack {
 
 	/** Array of default mod packs which should exist on a newly installed cluster */
 	static defaultModPacks = [
-		...["0.17", "0.18", "1.0", "1.1", "2.0"]
+		...(["0.17", "0.18", "1.0", "1.1", "2.0"] as const)
 			.map(version => this.fromJSON({
 				name: `Base Game ${version}`,
 				description: `Factorio ${version} with no extra mods.`,
 				factorio_version: version,
 			} as any)),
-		...["2.0"]
+		...(["2.0"] as const)
 			.map(version => this.fromJSON({
 				name: `Space Age ${version}`,
 				description: `Factorio ${version} with Space Age expansion.`,
 				factorio_version: version,
 				mods: [
-					{ name: "elevated-rails", enabled: true, version },
-					{ name: "quality", enabled: true, version },
-					{ name: "space-age", enabled: true, version },
+					{ name: "elevated-rails", enabled: true, version: normaliseFullVersion(version) },
+					{ name: "quality", enabled: true, version: normaliseFullVersion(version) },
+					{ name: "space-age", enabled: true, version: normaliseFullVersion(version) },
 				],
 			} as any)),
 	];
 
 	/**
-	 * Returns an array of ModInfo containing all mods included in factorio
+	 * Returns an array of ModRecord containing all mods included in factorio
 	 *
 	 * @param factorioVersion - Factorio version to get the default mods for
 	 * @return Built in mods for the given version
 	 */
-	static getBuiltinMods(factorioVersion: string) {
+	static getBuiltinMods(factorioVersion: PartialVersion) {
+		factorioVersion = normaliseFullVersion(factorioVersion);
 		let defaultMods: ModRecord[] = [
 			// "core" not included because core cannot be disabled
 			{ name: "base", enabled: true, version: factorioVersion },
 		];
 
-		const integerVersion = integerFactorioVersion(factorioVersion);
-		if (integerVersion >= integerFactorioVersion("1.2")) {
+		const integerVersion = integerPartialVersion(factorioVersion);
+		if (integerVersion >= integerPartialVersion("1.2")) {
 			defaultMods = defaultMods.concat([
 				{ name: "elevated-rails", enabled: false, version: factorioVersion },
 				{ name: "quality", enabled: false, version: factorioVersion },
@@ -428,7 +439,7 @@ export default class ModPack {
 		return defaultMods;
 	}
 
-	static getBuiltinModNames(factorioVersion: string) {
+	static getBuiltinModNames(factorioVersion: PartialVersion) {
 		return this.getBuiltinMods(factorioVersion).map(builtinMod => builtinMod.name);
 	}
 }

packages/lib/src/data/index.ts

@@ -4,7 +4,7 @@
  * @author Hornwitser
  */
 export { default as ExportManifest } from "./ExportManifest";
-export { default as ModInfo } from "./ModInfo";
+export { default as ModInfo, ModDependency } from "./ModInfo";
 export { ModSettingColor } from "./ModPack";
 export type { ModSetting, ModRecord } from "./ModPack";
 export { default as ModPack } from "./ModPack";

packages/lib/src/data/messages_controller.ts

@@ -2,6 +2,7 @@ import { Type, Static } from "@sinclair/typebox";
 import { JsonString, StringEnum, StringKey, plainJson } from "./composites";
 import { levels } from "../logging";
 import { ControllerConfig, HostConfig } from "../config";
+import { ExternalFactorioVersionSchema } from "../external";
 
 export class ControllerStopRequest {
 	declare ["constructor"]: typeof ControllerStopRequest;
@@ -391,3 +392,25 @@ export class DebugWsMessageEvent {
 		return new this(json.direction, json.content);
 	}
 }
+
+export class FactorioVersionsRequest {
+	declare ["constructor"]: typeof FactorioVersionsRequest;
+	static type = "request" as const;
+	static src = "control" as const;
+	static dst = "controller" as const;
+	static permission = "core.external.get_factorio_versions" as const;
+
+	constructor(
+		public maxAgeMs: number = 5 * 60 * 1000, // Default 5 minutes
+	) {}
+
+	static jsonSchema = Type.Object({
+		"maxAgeMs": Type.Number(),
+	});
+
+	static fromJSON(json: Static<typeof this.jsonSchema>) {
+		return new this(json.maxAgeMs);
+	}
+
+	static Response = plainJson(Type.Array(ExternalFactorioVersionSchema));
+}

packages/lib/src/data/messages_instance.ts

@@ -5,6 +5,7 @@ import { InstanceConfig } from "../config";
 import type { IControllerUser } from "./User";
 import type { MessageRequest } from "./messages_core";
 import { CollectorResultSerialized } from "../prometheus";
+import { TargetVersion, TargetVersionSchema, PartialVersion, PartialVersionSchema } from "./version";
 
 
 export const InstanceStatus = StringEnum([
@@ -42,7 +43,7 @@ export class InstanceDetails {
 		public assignedHost: number | undefined,
 		public gamePort: number | undefined,
 		public status: InstanceStatus,
-		public factorioVersion: string | undefined,
+		public factorioVersion: TargetVersion | undefined,
 		/** Millisecond Unix timestamp this entry was last updated at */
 		public updatedAtMs = 0,
 		public excludeFromStartAll = false,
@@ -57,7 +58,7 @@ export class InstanceDetails {
 			"unknown", "unassigned", "stopped", "starting", "running", "stopping",
 			"creating_save", "exporting_data", "deleted",
 		]),
-		"factorioVersion": Type.Optional(Type.String()),
+		"factorioVersion": Type.Optional(TargetVersionSchema),
 		"updatedAtMs": Type.Optional(Type.Number()),
 		"excludeFromStartAll": Type.Optional(Type.Boolean()),
 	});
@@ -744,8 +745,8 @@ export class HostInstanceUpdate {
 	constructor(
 		public config: Static<typeof InstanceConfig.jsonSchema>,
 		public status: InstanceStatus,
-		public gamePort: undefined | number,
-		public factorioVersion: undefined | string,
+		public gamePort: number | undefined,
+		public factorioVersion: PartialVersion | undefined,
 	) { }
 
 	static jsonSchema = Type.Object({
@@ -754,7 +755,7 @@ export class HostInstanceUpdate {
 			"stopped", "starting", "running", "stopping", "creating_save", "exporting_data",
 		]),
 		"gamePort": Type.Optional(Type.Number()),
-		"factorioVersion": Type.Optional(Type.String()),
+		"factorioVersion": Type.Optional(PartialVersionSchema),
 	});
 
 	static fromJSON(json: Static<typeof this.jsonSchema>) {
@@ -852,7 +853,7 @@ export class InstanceStatusChangedEvent {
 		public instanceId: number,
 		public status: InstanceStatus,
 		public gamePort?: number,
-		public factorioVersion?: string,
+		public factorioVersion?: TargetVersion,
 	) { }
 
 	static jsonSchema = Type.Object({
@@ -861,7 +862,7 @@ export class InstanceStatusChangedEvent {
 			"stopped", "starting", "running", "stopping", "creating_save", "exporting_data",
 		]),
 		"gamePort": Type.Optional(Type.Integer()),
-		"factorioVersion": Type.Optional(Type.String()),
+		"factorioVersion": Type.Optional(TargetVersionSchema),
 	});
 
 	static fromJSON(json: Static<typeof this.jsonSchema>) {

packages/lib/src/data/messages_mod.ts

@@ -1,8 +1,14 @@
 import { Type, Static } from "@sinclair/typebox";
-import ModInfo from "./ModInfo";
+import ModInfo, { ModDependency } from "./ModInfo";
 import ModPack from "./ModPack";
 import { JsonString, jsonArray } from "./composites";
 
+import {
+	FullVersion, FullVersionSchema,
+	ApiVersion, ApiVersionSchema, normaliseApiVersion,
+	ModVersionEquality,
+} from "./version";
+
 
 export class ModPackGetRequest {
 	declare ["constructor"]: typeof ModPackGetRequest;
@@ -113,13 +119,13 @@ export class ModGetRequest {
 
 	constructor(
 		public name: string,
-		public version: string,
+		public version: FullVersion,
 		public sha1?: string,
 	) { }
 
 	static jsonSchema = Type.Object({
 		"name": Type.String(),
-		"version": Type.String(),
+		"version": FullVersionSchema,
 		"sha1": Type.Optional(Type.String()),
 	});
 
@@ -148,7 +154,7 @@ export class ModSearchRequest {
 
 	constructor(
 		public query: string,
-		public factorioVersion: string,
+		public factorioVersion: ApiVersion,
 		public page: number,
 		public pageSize?: number,
 		public sort?: string,
@@ -157,7 +163,7 @@ export class ModSearchRequest {
 
 	static jsonSchema = Type.Object({
 		"query": Type.String(),
-		"factorioVersion": Type.String(),
+		"factorioVersion": ApiVersionSchema,
 		"page": Type.Integer(),
 		"pageSize": Type.Optional(Type.Integer()),
 		"sort": Type.Optional(Type.String()),
@@ -199,9 +205,9 @@ export class ModSearchRequest {
 
 // Define the structure for the latest release info from the portal
 export const ModPortalReleaseSchema = Type.Object({
-	version: Type.String(),
+	version: FullVersionSchema,
 	// Match the structure from ModStore's ModRelease/ModDetails
-	info_json: Type.Object({ factorio_version: Type.String() }),
+	info_json: Type.Object({ factorio_version: ApiVersionSchema }),
 	released_at: Type.String(), // ISO 8601 date string
 	download_url: Type.String(),
 	file_name: Type.String(),
@@ -229,20 +235,13 @@ export class ModPortalGetAllRequest {
 	static dst = "controller" as const;
 	static permission = "core.mod.search_portal" as const;
 
-	// Define allowed Factorio versions
-	static allowedVersions = [
-		Type.Literal("0.13"), Type.Literal("0.14"), Type.Literal("0.15"),
-		Type.Literal("0.16"), Type.Literal("0.17"), Type.Literal("0.18"),
-		Type.Literal("1.0"), Type.Literal("1.1"), Type.Literal("2.0"),
-	] as const;
-
 	constructor(
-		public factorioVersion: Static<typeof ModPortalGetAllRequest.allowedVersions[number]>,
+		public factorioVersion: ApiVersion,
 		public hide_deprecated?: boolean,
 	) { }
 
 	static jsonSchema = Type.Object({
-		"factorioVersion": Type.Union([...this.allowedVersions]), // Use Union for validation
+		"factorioVersion": ApiVersionSchema,
 		"hide_deprecated": Type.Optional(Type.Boolean()),
 	});
 
@@ -277,13 +276,13 @@ export class ModDownloadRequest {
 
 	constructor(
 		public name: string,
-		public version: string,
+		public version: FullVersion,
 		public sha1?: string,
 	) { }
 
 	static jsonSchema = Type.Object({
 		"name": Type.String(),
-		"version": Type.String(),
+		"version": FullVersionSchema,
 		"sha1": Type.Optional(Type.String()),
 	});
 
@@ -303,12 +302,12 @@ export class ModDeleteRequest {
 
 	constructor(
 		public name: string,
-		public version: string,
+		public version: FullVersion,
 	) { }
 
 	static jsonSchema = Type.Object({
 		"name": Type.String(),
-		"version": Type.String(),
+		"version": FullVersionSchema,
 	});
 
 	static fromJSON(json: Static<typeof this.jsonSchema>) {
@@ -356,6 +355,16 @@ export class ModUpdatesEvent {
 	}
 }
 
+export interface ModNameVersionPair {
+	name: string,
+	version: ModVersionEquality,
+}
+
+export const ModNameVersionPairSchema = Type.Object({
+	"name": Type.String(),
+	"version": ModVersionEquality.jsonSchema,
+});
+
 /**
  * Request mods to be downloaded from the Factorio mod portal to the controller.
  *
@@ -363,8 +372,7 @@ export class ModUpdatesEvent {
  * Requires Factorio credentials to be configured on the controller if the portal
  * requires authentication for downloads.
  *
- * @param name - Name of the mod to download.
- * @param version - Version of the mod to download.
+ * @param mods - Array of mods to be downloaded.
  * @param factorioVersion - Factorio version context for the download.
  */
 export class ModPortalDownloadRequest {
@@ -373,21 +381,93 @@ export class ModPortalDownloadRequest {
 	static src = "control" as const;
 	static dst = "controller" as const;
 	static permission = "core.mod.download_from_portal" as const;
-	static Response = ModInfo;
+	static Response = jsonArray(ModInfo);
 
 	constructor(
-		public name: string,
-		public version: string,
-		public factorioVersion: string,
+		public mods: ModNameVersionPair[],
+		public factorioVersion: ApiVersion,
 	) { }
 
 	static jsonSchema = Type.Object({
-		"name": Type.String(),
-		"version": Type.String(),
-		"factorioVersion": Type.String(),
+		"mods": Type.Array(ModNameVersionPairSchema),
+		"factorioVersion": ApiVersionSchema,
 	});
 
 	static fromJSON(json: Static<typeof this.jsonSchema>) {
-		return new this(json.name, json.version, json.factorioVersion);
+		return new this(
+			json.mods.map(mod => ({
+				name: mod.name, version: ModVersionEquality.fromJSON(mod.version),
+			})),
+			json.factorioVersion,
+		);
 	}
 }
+
+/**
+ * Request mods dependencies to be resolved using the Factorio mod portal.
+ *
+ * @param mods - Array of dependencies to resolve.
+ * @param factorioVersion - Factorio version context for resolution.
+ */
+export class ModDependencyResolveRequest {
+	declare ["constructor"]: typeof ModDependencyResolveRequest;
+	static type = "request" as const;
+	static src = "control" as const;
+	static dst = "controller" as const;
+	static permission = "core.mod.search_portal" as const;
+
+	constructor(
+		public mods: ModDependency[],
+		public factorioVersion: ApiVersion,
+		public checkForUpdates: boolean = false,
+	) { }
+
+	static jsonSchema = Type.Object({
+		"mods": Type.Array(ModDependency.jsonSchema),
+		"factorioVersion": ApiVersionSchema,
+		"checkForUpdates": Type.Boolean(),
+	});
+
+	static fromJSON(json: Static<typeof this.jsonSchema>) {
+		return new this(json.mods.map(spec => new ModDependency(spec)), json.factorioVersion, json.checkForUpdates);
+	}
+
+	static fromModPack(modPack: ModPack, checkForUpdates?: boolean) {
+		const equality = checkForUpdates ? ">=" : "=";
+		return new this(
+			[...modPack.mods.values()]
+				.map(mod => new ModDependency(`${mod.name} ${equality} ${mod.version}`)),
+			normaliseApiVersion(modPack.factorioVersion),
+			checkForUpdates,
+		);
+	}
+
+	static fromModPackEnabled(modPack: ModPack, checkForUpdates?: boolean) {
+		const equality = checkForUpdates ? ">=" : "=";
+		return new this(
+			[...modPack.mods.values()]
+				.filter(mod => mod.enabled)
+				.map(mod => new ModDependency(`${mod.name} ${equality} ${mod.version}`)),
+			normaliseApiVersion(modPack.factorioVersion),
+			checkForUpdates,
+		);
+	}
+
+	static Response = class ModDependencyResolveResponse {
+		constructor(
+			public dependencies: ModInfo[],
+			public incompatible: string[],
+			public missing: string[],
+		) {}
+
+		static jsonSchema = Type.Object({
+			"dependencies": Type.Array(ModInfo.jsonSchema),
+			"incompatible": Type.Array(Type.String()),
+			"missing": Type.Array(Type.String()),
+		});
+
+		static fromJSON(json: Static<typeof this.jsonSchema>) {
+			return new this(json.dependencies.map(d => ModInfo.fromJSON(d)), json.incompatible, json.missing);
+		}
+	};
+}

packages/lib/src/data/version.ts

@@ -1,33 +1,241 @@
 // Helper functions for dealing with factorio version numbers
 
+import { Static, Type } from "@sinclair/typebox";
 
 /**
- * Integer representation of a mod version
+ * Integer representation of a version string.
  *
  * Suitable for sorting and comparing version numbers which may have different
  * number of leading zeros in them.
- * @param version - string representation of version.
- * @returns numeric representation.
  */
-export function integerModVersion(version: string) {
+export type IntegerVersion = number & { [integerVersionSymbol]: void };
+declare const integerVersionSymbol: unique symbol;
+
+/**
+ * Allowed version equalities as defined within mod info json
+ * https://lua-api.factorio.com/latest/auxiliary/mod-structure.html#Dependency
+ */
+const versionEqualities = ["<", "<=", "=", ">=", ">"] as const;
+export const VersionEqualitySchema = Type.Union(versionEqualities.map(v => Type.Literal(v)));
+export type VersionEquality = Static<typeof VersionEqualitySchema>;
+
+export function isVersionEquality(input: string): input is VersionEquality {
+	return versionEqualities.includes(input as any);
+}
+
+/**
+ * Matches valid factorio versions accepts by the web API
+ * https://wiki.factorio.com/Mod_portal_API#/api/mods (see version enum)
+ */
+export const ApiVersions = ["0.13", "0.14", "0.15", "0.16", "0.17", "0.18", "1.0", "1.1", "2.0"] as const;
+export const ApiVersionSchema = Type.Union(ApiVersions.map(v => Type.Literal(v)));
+export type ApiVersion = Static<typeof ApiVersionSchema>;
+
+export function isApiVersion(input: string): input is ApiVersion {
+	return ApiVersions.includes(input as any);
+}
+
+export function normaliseApiVersion(version: PartialVersion) {
+	const parts = version.split(".");
+	const apiVersion = `${parts[0]}.${parts[1]}`;
+	if (!isApiVersion(apiVersion)) {
+		throw new Error(`Factorio version not supported by mod portal: ${apiVersion}`);
+	}
+	return apiVersion;
+}
+
+/**
+ * Matches valid mod versions, where all parts are specified.
+ */
+const fullVersionRegExp = /^\d+\.\d+\.\d+$/;
+export type FullVersion = `${number}.${number}.${number}`;
+export const FullVersionSchema = Type.Unsafe<FullVersion>(
+	Type.String({ pattern: fullVersionRegExp.source })
+);
+
+export function isFullVersion(input: string): input is FullVersion {
+	return fullVersionRegExp.test(input);
+}
+
+export function integerFullVersion(version: FullVersion) {
 	const [major, minor, sub] = version.split(".").map(n => Number.parseInt(n, 10));
-	return major * 0x100000000 + minor * 0x10000 + sub; // Can't use bitwise here because this is 48-bits.
+	// Can't use bitwise here because this is 48-bits.
+	return major * 0x100000000 + minor * 0x10000 + sub as IntegerVersion;
+}
+
+export function normaliseFullVersion(version: PartialVersion) {
+	const parts = version.split(".");
+	return (parts.length === 3 ? version : `${version}.0`) as FullVersion;
 }
 
 /**
- * Integer representation of a factorio version
- *
- * Suitable for sorting and comparing version numbers which may have different
- * number of leading zeros in them.
- * @param version - string representation of version.
- * @returns numeric representation.
+ * Matches valid factorio versions and mod dependencies specifications where 2 or 3 parts are specified.
  */
-export function integerFactorioVersion(version: string) {
-	const [main, major, minor] = version.split(".").map(n => Number.parseInt(n, 10));
-	return main * 0x100000000 + major * 0x10000 + (minor || 0); // Can't use bitwise here because this is 48-bits.
+const partialVersionRegExp = /^\d+\.\d+(?:\.\d+)?$/;
+export type PartialVersion = FullVersion | `${number}.${number}`;
+export const PartialVersionSchema = Type.Unsafe<PartialVersion>(
+	Type.String({ pattern: partialVersionRegExp.source })
+);
+
+export function isPartialVersion(input: string): input is PartialVersion {
+	return partialVersionRegExp.test(input);
+}
+
+export function integerPartialVersion(version: PartialVersion) {
+	const [major, minor, sub] = version.split(".").map(n => Number.parseInt(n, 10));
+	// Can't use bitwise here because this is 48-bits. sub is optional and defaults to 0.
+	return major * 0x100000000 + minor * 0x10000 + (sub || 0) as IntegerVersion;
 }
 
 /**
- * Matches valid mod versions.
+ * Matches valid factorio target versions, this is the same as partial but also accepts "latest".
  */
-export const modVersionRegExp = /^\d+\.\d+\.\d+$/;
+export type TargetVersion = PartialVersion | "latest";
+export const TargetVersionSchema = Type.Union([
+	PartialVersionSchema,
+	Type.Literal("latest"),
+]);
+
+export function isTargetVersion(input: string): input is TargetVersion {
+	return input === "latest" || partialVersionRegExp.test(input);
+}
+
+/**
+ * Represents a mod version paired with an equality which can be tested against
+ */
+export class ModVersionEquality {
+	public integerVersion: IntegerVersion;
+
+	constructor(
+		public equality: VersionEquality,
+		public version: PartialVersion,
+	) {
+		this.integerVersion = integerPartialVersion(version);
+		if (!isVersionEquality(this.equality)) {
+			throw new Error("Invalid equality");
+		}
+		if (!isPartialVersion(this.version)) {
+			throw new Error("Invalid version");
+		}
+	}
+
+	testIntegerVersion(other: IntegerVersion) {
+		switch (this.equality) {
+			case "<":
+				return other < this.integerVersion;
+			case "<=":
+				return other <= this.integerVersion;
+			case "=":
+				return other === this.integerVersion;
+			case ">=":
+				return other >= this.integerVersion;
+			case ">":
+				return other > this.integerVersion;
+			default:
+				throw new Error("unreachable");
+		}
+	}
+
+	testVersion(version: PartialVersion) {
+		return this.testIntegerVersion(integerPartialVersion(version));
+	}
+
+	toString() {
+		return `${this.equality} ${this.version}`;
+	}
+
+	static fromString(version: string) {
+		const parts = version.split(" ");
+		return parts.length === 1 ? this.fromParts("=", parts[0]) : this.fromParts(parts[0], parts[1]);
+	}
+
+	static fromParts(equality: string, version: string) {
+		if (!isVersionEquality(equality)) {
+			throw new Error(`Unknown version equality: ${equality}`);
+		}
+		if (!isPartialVersion(version)) {
+			throw new Error(`Malformed version string: ${version}`);
+		}
+		return new this(equality, version);
+	}
+
+	static jsonSchema = Type.String();
+
+	static fromJSON(json: Static<typeof this.jsonSchema>) {
+		return this.fromString(json);
+	}
+
+	toJSON() {
+		return this.toString();
+	}
+}
+
+/**
+ * Represents a range of mod versions which can be tested against
+ */
+export class ModVersionRange {
+	constructor(
+		public minVersion = new ModVersionEquality(">=", "0.0.0"),
+		public maxVersion = new ModVersionEquality("<=", "65535.65535.65535"),
+	) {
+		if (minVersion.equality === "<" || minVersion.equality === "<=") {
+			throw new Error("Minimum version can not use < or <=");
+		}
+		if (maxVersion.equality === ">" || maxVersion.equality === ">=") {
+			throw new Error("Maximum version can not use > or >=");
+		}
+	}
+
+	get valid() {
+		return this.minVersion.testIntegerVersion(this.maxVersion.integerVersion)
+			&& this.maxVersion.testIntegerVersion(this.minVersion.integerVersion);
+	}
+
+	invalidate() {
+		this.maxVersion = new ModVersionEquality(">", "0.0.0");
+	}
+
+	testIntegerVersion(other: IntegerVersion) {
+		return this.minVersion.testIntegerVersion(other) && this.maxVersion.testIntegerVersion(other);
+	}
+
+	testVersion(version: PartialVersion) {
+		return this.testIntegerVersion(integerPartialVersion(version));
+	}
+
+	combineVersion(other: ModVersionEquality) {
+		switch (other.equality) {
+			case "<":
+				if (other.integerVersion <= this.maxVersion.integerVersion) {
+					this.maxVersion = other;
+				}
+				break;
+			case "<=":
+				if (other.integerVersion < this.maxVersion.integerVersion) {
+					this.maxVersion = other;
+				}
+				break;
+			case "=":
+				if (this.testIntegerVersion(other.integerVersion)) {
+					this.minVersion = other;
+					this.maxVersion = other;
+				} else {
+					// Make invalid as it could not be satisfied
+					this.invalidate();
+				}
+				break;
+			case ">=":
+				if (other.integerVersion > this.minVersion.integerVersion) {
+					this.minVersion = other;
+				}
+				break;
+			case ">":
+				if (other.integerVersion >= this.minVersion.integerVersion) {
+					this.minVersion = other;
+				}
+				break;
+			default:
+				throw new Error("unreachable");
+		}
+	}
+}

packages/lib/src/external/FactorioVersions.ts

@@ -0,0 +1,69 @@
+import { Static, Type } from "@sinclair/typebox";
+import { FullVersionSchema, integerFullVersion, isFullVersion } from "../data/version";
+
+const ARCHIVE_URL = "https://factorio.com/download/archive";
+
+/**
+ * Represents the parsed result of a factorio version
+ */
+export const ExternalFactorioVersionSchema = Type.Object({
+	stable: Type.Boolean(),
+	version: FullVersionSchema,
+	headlessUrl: Type.String(),
+});
+
+export type ExternalFactorioVersion = Static<typeof ExternalFactorioVersionSchema>
+
+/**
+ * Fetch all factorio versions that support headless
+ *
+ * @returns A list of all factorio versions and their download URL
+ * @throws Network errors and non-ok status responses
+ */
+export async function fetchFactorioVersions(): Promise<ExternalFactorioVersion[]> {
+	let res;
+
+	try {
+		res = await fetch(ARCHIVE_URL);
+	} catch (err) {
+		throw new Error(`Failed to fetch Factorio versions from ${ARCHIVE_URL}: ${err}`);
+	}
+
+	if (!res.ok) {
+		throw new Error(`Failed to fetch Factorio versions from ${ARCHIVE_URL}: HTTP ${res.status} ${res.statusText}`);
+	}
+
+	const html = await res.text();
+	return parseFactorioVersions(html);
+}
+
+/**
+ * Parse all versions from the factorio archive webpage
+ *
+ * @param html The HTML content of the archive page
+ * @returns A list of all factorio versions and their download URL
+ */
+function parseFactorioVersions(html: string): ExternalFactorioVersion[] {
+	const versions = new Map<string, ExternalFactorioVersion>();
+
+	// Match <a class=" slot-button-inline version-button-stable " href="/download/archive/2.0.72">2.0.72</a>
+	// eslint-disable-next-line max-len
+	const anchorRegex = /<a[^>]*class="[^"]*version-button-(?<kind>stable|experimental)[^"]*"[^>]*href="[^"]*\/download\/archive\/(?<version>\d+\.\d+.\d+)"[^>]*>/g;
+
+	let match: RegExpExecArray | null;
+	const minimumMultiplayerVersion = integerFullVersion("0.12.35");
+	while ((match = anchorRegex.exec(html)) !== null) {
+		const kind = match.groups?.kind;
+		const version = match.groups?.version;
+
+		if (kind && version && isFullVersion(version) && integerFullVersion(version) >= minimumMultiplayerVersion) {
+			versions.set(version, {
+				version: version,
+				stable: kind === "stable",
+				headlessUrl: `www.factorio.com/get-download/${version}/headless/linux64`,
+			});
+		}
+	}
+
+	return [...versions.values()];
+}

packages/lib/src/external/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Library for interfacing with external apis
+ * @module lib/external
+ */
+export * from "./FactorioVersions";

packages/lib/src/link/messages.ts

@@ -35,6 +35,7 @@ export const dataClasses: (RequestClass<unknown, unknown> | EventClass<unknown>)
 	controller.SystemInfoUpdateEvent,
 	controller.DebugDumpWsRequest,
 	controller.DebugWsMessageEvent,
+	controller.FactorioVersionsRequest,
 
 	subscriptions.SubscriptionRequest,
 
@@ -108,6 +109,7 @@ export const dataClasses: (RequestClass<unknown, unknown> | EventClass<unknown>)
 	mod.ModPackUpdatesEvent,
 	mod.ModUpdatesEvent,
 	mod.ModPortalDownloadRequest,
+	mod.ModDependencyResolveRequest,
 
 	role.PermissionListRequest,
 	role.RoleListRequest,

packages/lib/src/permissions.ts

@@ -568,3 +568,9 @@ definePermission({
 	title: "Dump WebSocket",
 	description: "Dump all WebSocket communicatation from the controller.",
 });
+
+definePermission({
+	name: "core.external.get_factorio_versions",
+	title: "Get factorio versions",
+	description: "Get list of all factorio versions from Wube",
+});

packages/lib/src/plugin_loader.ts

@@ -4,6 +4,7 @@
  * @module lib/plugin_loader
  */
 import path from "path";
+import fs from "fs/promises";
 import * as libErrors from "./errors";
 import * as libPlugin from "./plugin";
 import { logger } from "./logging";
@@ -29,8 +30,13 @@ export async function loadPluginInfos(pluginList: Map<string, string>) {
 		// Check if plugin path exists, otherwise remove it
 		try {
 			require.resolve(pluginPath);
-		} catch (err) {
-			logger.error(`Plugin path ${pluginPath} does not exist, not loading ${pluginName}`);
+		} catch {
+			let errMsg = `Plugin path ${pluginPath} does not exist`;
+			try {
+				await fs.access(pluginPath, fs.constants.F_OK);
+				errMsg = `Plugin path ${pluginPath} missing index or main file`;
+			} catch {}
+			logger.error(`${errMsg}, not loading ${pluginName}`);
 			pluginList.delete(pluginName);
 			continue;
 		}

packages/lib/src/prometheus.ts

@@ -275,6 +275,9 @@ function keyToLabels(key: string) {
 	if (key !== "") {
 		for (let pair of key.split(",")) {
 			let [name, value] = pair.split("=", 2);
+			if (!name || value === undefined) {
+				continue;
+			}
 			labels.set(name, value
 				.slice(1, -1)
 				.replace(/\\"/g, "\"")

packages/lib/src/rce_ops.ts

@@ -6,7 +6,7 @@ import { RequestError } from "./errors";
 import { PluginNodeEnvInfo } from "./plugin";
 const execAsync = util.promisify(exec);
 
-async function isDev() {
+function isDev() {
 	//  dev:                 <devRoot>/packages/lib/dist/src/rce_ops.js
 	// prod: <prodRoot>/node_modules/@clusterio/lib/dist/src/rce_ops.js
 	return __dirname.split(path.sep).at(-5) === "packages"; // opposed to "@clusterio"

packages/lib/src/shared_commands.ts

@@ -8,6 +8,7 @@ import * as libConfig from "./config";
 import * as libFileOps from "./file_ops";
 import { logger } from "./logging";
 import * as libHelpers from "./helpers";
+import { LockFile } from "./LockFile";
 
 
 function print(...content: any[]) {
@@ -130,11 +131,12 @@ export function configCommand(yargs: any) {
  *
  * @param args - yargs args object.
  * @param instance - Config instance.
- * @param configPath - Path to configuration file.
+ * @param lockFile - Lockfile required if attempting to write
  */
 export async function handleConfigCommand(
 	args: Record<string, unknown>,
 	instance: libConfig.Config<any>,
+	lockFile: LockFile,
 ) {
 	let command = (args._ as string[])[1];
 
@@ -155,6 +157,8 @@ export async function handleConfigCommand(
 		}
 
 	} else if (command === "set") {
+		await lockFile.acquire();
+
 		if (args.stdin) {
 			args.value = (await libHelpers.readStream(process.stdin)).toString().replace(/\r?\n$/, "");
 
@@ -172,5 +176,7 @@ export async function handleConfigCommand(
 				throw err;
 			}
 		}
+
+		await lockFile.release();
 	}
 }

packages/lib/src/subscriptions.ts

@@ -195,7 +195,6 @@ export class SubscriptionController {
 			throw new Error(`Event ${event.eventName} is not a registered as subscribable`);
 		}
 		if (event.subscribe === false) {
-			// Unsubscribe logic
 			const subscriber = eventData.subscriptions.find(sub => sub.dst.addressedTo(src));
 			if (!subscriber) {
 				return false;

packages/lib/tsconfig.browser.json

@@ -6,6 +6,7 @@
 		"./src/api.ts",
 		"./src/config/*.ts",
 		"./src/data/*.ts",
+		"./src/external/*.ts",
 		"./src/datastore.ts",
 		"./src/errors.ts",
 		"./src/factorio/exchange_string.ts",
@@ -25,6 +26,7 @@
 		"./src/ExponentialBackoff.ts",
 		"./src/RateLimiter.ts",
 		"./src/TypedEventEmitter.ts",
+		"./src/ValueCache.ts",
 	],
 	"compilerOptions": {
 		"rootDir": ".",

packages/web_ui/package.json

@@ -3,7 +3,7 @@
 	"description": "Clusterio web interface implementation",
 	"author": "Hornwitser",
 	"license": "MIT",
-	"version": "2.0.0-alpha.21",
+	"version": "2.0.0-alpha.22b",
 	"browser": "src/index.ts",
 	"main": "dist/browser/src/index.js",
 	"scripts": {

packages/web_ui/src/bootstrap.tsx

@@ -9,6 +9,8 @@ import App from "./components/App";
 import BaseWebPlugin, { InputComponent } from "./BaseWebPlugin";
 import InputRole from "./components/InputRole";
 import InputModPack from "./components/InputModPack";
+import InputTargetVersion from "./components/InputTargetVersion";
+import InputPartialVersion from "./components/InputPartialVersion";
 import { Control, ControlConnector } from "./util/websocket";
 
 const { ConsoleTransport, WebConsoleFormat, logger } = lib;
@@ -109,6 +111,8 @@ async function loadPlugins(pluginInfos: lib.PluginWebpackEnvInfo[], control: Con
 
 function inputComponentsFromPlugins(plugins: Map<string, BaseWebPlugin>) {
 	const inputComponents: Record<string, InputComponent> = {
+		"partial_version": InputPartialVersion,
+		"target_version": InputTargetVersion,
 		"mod_pack": InputModPack,
 		"role": InputRole,
 	};

packages/web_ui/src/components/ControllerPage.tsx

@@ -34,9 +34,10 @@ function ControllerControlButton({ canRestart, restartRequired }: ControllerCont
 		actions.push({
 			key: "restart",
 			label: (
-				<Tooltip title={restartRequired ? "Restart Required" : null}>
-					Restart {restartRequired ? <ExclamationCircleOutlined style={{ color: "yellow" }}/> : undefined}
-				</Tooltip>
+				!restartRequired ? "Restart" : <Tooltip title={"Restart Required"}><Space>
+					<ExclamationCircleOutlined style={{ color: "yellow" }}/>
+					Restart
+				</Space></Tooltip>
 			),
 			onClick: () => {
 				control.send(

packages/web_ui/src/components/HostViewPage.tsx

@@ -37,9 +37,10 @@ function HostControlButton({ hostId, canRestart, restartRequired }: HostControlB
 		actions.push({
 			key: "restart",
 			label: (
-				<Tooltip title={restartRequired ? "Restart Required" : null}>
-					Restart {restartRequired ? <ExclamationCircleOutlined style={{ color: "yellow" }}/> : undefined}
-				</Tooltip>
+				!restartRequired ? "Restart" : <Tooltip title={"Restart Required"}><Space>
+					<ExclamationCircleOutlined style={{ color: "yellow" }}/>
+					Restart
+				</Space></Tooltip>
 			),
 			onClick: () => {
 				control.sendTo(
@@ -105,7 +106,7 @@ export default function HostViewPage() {
 		</PageLayout>;
 	}
 
-	let hostButtons = <Space>
+	let hostButtons = <Space wrap>
 		<HostControlButton hostId={hostId} canRestart={system?.canRestart} restartRequired={system?.restartRequired}/>
 		{
 			account.hasPermission("core.host.revoke_token")

packages/web_ui/src/components/InputPartialVersion.tsx

@@ -0,0 +1,71 @@
+import React, { useContext, useEffect, useState } from "react";
+import { TreeSelect } from "antd";
+
+import * as lib from "@clusterio/lib";
+import type { InputComponentProps } from "../BaseWebPlugin";
+import { useAccount } from "../model/account";
+import ControlContext from "./ControlContext";
+
+const defaultFieldDefinition: lib.FieldDefinition = { type: "string", optional: false };
+
+export default function InputPartialVersion (
+	props: Omit<InputComponentProps, "fieldDefinition"> & {
+		fieldDefinition?: lib.FieldDefinition;
+		className?: string;
+	}
+) {
+	const fieldDefinition = props.fieldDefinition || defaultFieldDefinition;
+	const [versions, setVersions] = useState<readonly lib.PartialVersion[]>(lib.ApiVersions);
+	const control = useContext(ControlContext);
+	const account = useAccount();
+	const hasPermission = account.hasPermission("core.external.get_factorio_versions");
+
+	useEffect(() => {
+		(async () => {
+			if (hasPermission) {
+				const res = await control.factorioVersions.get(5 * 60 * 1000);
+				setVersions(res.map(v => v.version));
+			}
+		})();
+	}, [control, hasPermission]);
+
+	// Split the versions into groups based on major minor
+	const groups = new Map<lib.PartialVersion, lib.PartialVersion[]>();
+
+	for (const version of versions) {
+		const [major, minor] = version.split(".");
+		const key = `${major}.${minor}` as lib.PartialVersion;
+
+		if (!groups.has(key)) {
+			groups.set(key, []);
+		}
+		groups.get(key)!.push(version);
+	}
+
+	// Construct the tree to be disabled
+	const tree = [...groups.entries()].map(([majorMinor, patchVersions]) => {
+		const groupKey = `group-${majorMinor}`;
+
+		return {
+			title: majorMinor,
+			value: majorMinor,
+			key: groupKey,
+			children: patchVersions.map((v) => ({
+				title: v,
+				value: v,
+				key: v,
+			})),
+		};
+	});
+
+	return <TreeSelect
+		showSearch
+		style={{ minWidth: 175 }}
+		onChange={(value) => props.onChange(value ?? null)}
+		value={props.value}
+		treeData={tree}
+		allowClear={fieldDefinition.optional}
+		className={props.className}
+		disabled={props.disabled}
+	/>;
+}

packages/web_ui/src/components/InputTargetVersion.tsx

@@ -0,0 +1,74 @@
+import React, { useContext, useEffect, useState } from "react";
+import { TreeSelect } from "antd";
+
+import * as lib from "@clusterio/lib";
+import type { InputComponentProps } from "../BaseWebPlugin";
+import { useAccount } from "../model/account";
+import ControlContext from "./ControlContext";
+
+const defaultFieldDefinition: lib.FieldDefinition = { type: "string", optional: false };
+
+export default function InputTargetVersion (
+	props: Omit<InputComponentProps, "fieldDefinition"> & {
+		fieldDefinition?: lib.FieldDefinition;
+		className?: string;
+	}
+) {
+	const fieldDefinition = props.fieldDefinition || defaultFieldDefinition;
+	const [versions, setVersions] = useState<readonly lib.TargetVersion[]>(lib.ApiVersions);
+	const control = useContext(ControlContext);
+	const account = useAccount();
+	const hasPermission = account.hasPermission("core.external.get_factorio_versions");
+
+	useEffect(() => {
+		(async () => {
+			if (hasPermission) {
+				const res = await control.factorioVersions.get(5 * 60 * 1000);
+				setVersions(res.map(v => v.version));
+			}
+		})();
+	}, [control, hasPermission]);
+
+	// Split the versions into groups based on major minor
+	const groups = new Map<lib.TargetVersion, lib.TargetVersion[]>();
+
+	for (const version of versions) {
+		const [major, minor] = version.split(".");
+		const key = `${major}.${minor}` as lib.PartialVersion;
+
+		if (!groups.has(key)) {
+			groups.set(key, []);
+		}
+		groups.get(key)!.push(version);
+	}
+
+	// Construct the tree to be disabled
+	const tree = [...groups.entries()].map(([majorMinor, patchVersions]) => {
+		const groupKey = `group-${majorMinor}`;
+
+		return {
+			title: majorMinor,
+			value: majorMinor,
+			key: groupKey,
+			children: patchVersions.map((v) => ({
+				title: v,
+				value: v,
+				key: v,
+			})),
+		};
+	});
+
+	// Add "latest" option for TargetVersion
+	tree.unshift({ title: "latest", value: "latest", key: "latest", children: [] });
+
+	return <TreeSelect
+		showSearch
+		style={{ minWidth: 175 }}
+		onChange={(value) => props.onChange(value ?? null)}
+		value={props.value}
+		treeData={tree}
+		allowClear={fieldDefinition.optional}
+		className={props.className}
+		disabled={props.disabled}
+	/>;
+}

packages/web_ui/src/components/InstanceList.tsx

@@ -1,12 +1,14 @@
 import React from "react";
 import { useNavigate } from "react-router-dom";
-import { message, Button, Table } from "antd";
+import { message, Button, Table, Space } from "antd";
 import CopyOutlined from "@ant-design/icons/CopyOutlined";
 import type { SizeType } from "antd/es/config-provider/SizeContext";
 import type { ColumnsType } from "antd/es/table";
 
 import { useAccount } from "../model/account";
+import { useSystems } from "../model/system";
 import { useHosts } from "../model/host";
+import { RestartRequired } from "./system_metrics";
 import InstanceStatusTag from "./InstanceStatusTag";
 import InstanceControlButton, { InstanceControlButtonPermissions } from "./InstanceControlButton";
 import * as lib from "@clusterio/lib";
@@ -25,6 +27,7 @@ export default function InstanceList(props: InstanceListProps) {
 	let account = useAccount();
 	let navigate = useNavigate();
 	let [hosts] = useHosts();
+	const [systems] = useSystems();
 
 	function hostName(hostId?: number) {
 		if (hostId === undefined) {
@@ -34,10 +37,10 @@ export default function InstanceList(props: InstanceListProps) {
 	}
 
 	function integerFactorioVersionOrDefault(instance: lib.InstanceDetails) {
-		if (instance.factorioVersion === undefined) {
+		if (instance.factorioVersion === undefined || instance.factorioVersion === "latest") {
 			return -1;
 		}
-		return lib.integerFactorioVersion(instance.factorioVersion);
+		return lib.integerPartialVersion(instance.factorioVersion);
 	}
 
 	let columns: ColumnsType<lib.InstanceDetails> = [
@@ -50,12 +53,15 @@ export default function InstanceList(props: InstanceListProps) {
 		{
 			title: "Assigned Host",
 			key: "assignedHost",
-			render: (_, instance) => <Link
-				to={`/hosts/${instance.assignedHost}/view`}
-				onClick={e => e.stopPropagation()}
-			>
-				{hostName(instance.assignedHost)}
-			</Link>,
+			render: (_, instance) => <Space>
+				<Link
+					to={`/hosts/${instance.assignedHost}/view`}
+					onClick={e => e.stopPropagation()}
+				>
+					{hostName(instance.assignedHost)}
+				</Link>
+				<RestartRequired system={instance.assignedHost ? systems.get(instance.assignedHost) : undefined}/>
+			</Space>,
 			sorter: (a, b) => strcmp(hostName(a.assignedHost), hostName(b.assignedHost)),
 			responsive: ["sm"],
 		},

packages/web_ui/src/components/InstanceViewPage.tsx

@@ -141,7 +141,7 @@ function InstanceButtons(props: { instance: lib.InstanceDetails }) {
 			}
 		},
 	};
-	return <Space>
+	return <Space wrap>
 		{
 			account.hasAnyPermission(...InstanceControlButtonPermissions)
 			&& <InstanceControlButton instance={instance} />

packages/web_ui/src/components/LoginForm.tsx

@@ -1,7 +1,8 @@
-import React, { Fragment, useContext } from "react";
+import React, { Fragment, useContext, useEffect, useState } from "react";
 import { Button, Card, Divider, Form, Image, Input, Space, Typography } from "antd";
 import LockOutlined from "@ant-design/icons/LockOutlined";
 
+import notify from "../util/notify";
 import logo from "../images/logo.png";
 import ControlContext from "./ControlContext";
 
@@ -36,6 +37,23 @@ function TokenAuth(props: SetTokenProps) {
 
 export default function LoginForm(props: SetTokenProps) {
 	let plugins = useContext(ControlContext).plugins;
+	const [clusterName, setClusterName] = useState<string>("Clusterio");
+
+	useEffect(() => {
+		(async () => {
+			try {
+				let response = await fetch(`${webRoot}api/cluster-name`);
+				if (response.ok) {
+					let data = await response.json();
+					if (data.name) {
+						setClusterName(data.name);
+					}
+				}
+			} catch (err) {
+				notify("Failed to load cluster name");
+			}
+		})();
+	}, []);
 
 	let loginForms = [];
 	for (let plugin of plugins.values()) {
@@ -50,7 +68,7 @@ export default function LoginForm(props: SetTokenProps) {
 
 	return <Card style={{ maxWidth: "30em" }}>
 		<Space style={{ width: "100%" }} direction="vertical" align="center">
-			<h1>Clusterio</h1>
+			<h1>{clusterName}</h1>
 			<Image width={128} height={123} src={logo} />
 			Log in to the cluster using one of the methods below.
 		</Space>
@@ -60,4 +78,3 @@ export default function LoginForm(props: SetTokenProps) {
 		</Fragment>)}
 	</Card>;
 }
-

packages/web_ui/src/components/ModDetails.tsx

@@ -1,6 +1,9 @@
 import React, { Fragment } from "react";
-import { Descriptions, Grid, Typography } from "antd";
+import { Descriptions, Grid, Tooltip, Typography, Space } from "antd";
 import ExclamationCircleOutlined from "@ant-design/icons/ExclamationCircleOutlined";
+import FileUnknownOutlined from "@ant-design/icons/FileUnknownOutlined";
+import FileExclamationOutlined from "@ant-design/icons/FileExclamationOutlined";
+import FileSyncOutlined from "@ant-design/icons/FileSyncOutlined";
 
 import * as lib from "@clusterio/lib";
 
@@ -8,11 +11,25 @@ const { useBreakpoint } = Grid;
 
 type ModDetailsProps<T> = {
 	mod: T;
+	mods?: lib.ModRecord[];
 	actions?: (mod: T) => React.JSX.Element;
 };
+
 export default function ModDetails<T extends lib.ModInfo | lib.ModRecord>(props: ModDetailsProps<T>) {
 	let screens = useBreakpoint();
-	const mod: Partial<lib.ModInfo> & Partial<lib.ModRecord> = props.mod;
+	let mod: Partial<lib.ModInfo> & Partial<lib.ModRecord> = props.mod;
+
+	if ("info" in mod) {
+		// Add the mod info if present in a mod record
+		mod = { ...mod, ...mod.info };
+	}
+
+	const depWarnings = new Map<string, lib.ModRecord["warning"]>();
+	if (mod.dependencies && props.mods) {
+		for (const dependency of mod.dependencies) {
+			depWarnings.set(dependency.name, dependency.checkUnsatisfiedReason(props.mods));
+		}
+	}
 
 	return <Descriptions
 		className="borderless"
@@ -52,7 +69,14 @@ export default function ModDetails<T extends lib.ModInfo | lib.ModRecord>(props:
 		{Boolean(mod.homepage) && <Descriptions.Item label="Homepage" span={2}>{mod.homepage}</Descriptions.Item>}
 		<Descriptions.Item label="Internal&nbsp;Name" span={mod.factorioVersion ? 1 : 2}>{mod.name}</Descriptions.Item>
 		{Boolean(mod.factorioVersion)
-			&& <Descriptions.Item label="Factorio&nbsp;Version">{mod.factorioVersion}</Descriptions.Item>
+			&& <Descriptions.Item label="Factorio&nbsp;Version">
+				<Space>
+					{mod.warning === "wrong_factorio_version" && <Tooltip title="Wrong factorio version.">
+						<FileSyncOutlined style={{ color: "#dd5e14" }} />{" "}
+					</Tooltip>}
+					{mod.factorioVersion}
+				</Space>
+			</Descriptions.Item>
 		}
 		{Boolean(mod.filename) && <Descriptions.Item label="Filename">{mod.filename}</Descriptions.Item>}
 		{mod.size !== undefined
@@ -62,8 +86,22 @@ export default function ModDetails<T extends lib.ModInfo | lib.ModRecord>(props:
 		{mod.dependencies && mod.dependencies.length
 			&& <Descriptions.Item label="Dependencies" span={2}>
 				{mod.dependencies
-					.filter(e => !e.startsWith("(?)"))
-					.map((e, i) => <Fragment key={i}>{e}<br/></Fragment>)
+					.filter(e => e.type !== "hidden")
+					.map((e, i) => <Fragment key={i}>
+						<Space>
+							{depWarnings.get(e.name) === "incompatible" && <Tooltip title="Incompatible mod added.">
+								<FileExclamationOutlined style={{ color: "#dd5e14" }} />{" "}
+							</Tooltip>}
+							{depWarnings.get(e.name) === "missing_dependency" && <Tooltip title="Dependency missing.">
+								<FileUnknownOutlined style={{ color: "#dd5e14" }} />{" "}
+							</Tooltip>}
+							{depWarnings.get(e.name) === "wrong_version" && <Tooltip title="Wrong version added.">
+								<FileSyncOutlined style={{ color: "#dd5e14" }} />{" "}
+							</Tooltip>}
+							{e.specification}
+						</Space>
+						<br/>
+					</Fragment>)
 				}
 			</Descriptions.Item>
 		}

packages/web_ui/src/components/ModPackViewPage.tsx

@@ -1,19 +1,19 @@
 import React, { Fragment, memo, useCallback, useEffect, useContext, useRef, useState } from "react";
 import { useNavigate, useParams } from "react-router-dom";
+import { FieldData } from "rc-field-form/lib/interface";
+
 import {
 	Button, Card, ColorPicker, Checkbox, Col, ConfigProvider, Descriptions, Form, Input, Pagination,
 	Popconfirm, Row, Table, Tag, Typography, Select, Skeleton, Space, Spin, Switch, Modal, Tooltip,
-	TablePaginationConfig,
+	TablePaginationConfig, Alert, notification,
 } from "antd";
-import { FieldData } from "rc-field-form/lib/interface";
+
+import {
+	ExportOutlined, FileUnknownOutlined, FileExclamationOutlined, FileSyncOutlined,
+	CloseOutlined, DeleteOutlined, ToolOutlined, PlusOutlined, CloudSyncOutlined, CloudDownloadOutlined,
+} from "@ant-design/icons";
 
 import type { SorterResult, FilterValue, TableCurrentDataSource } from "antd/es/table/interface";
-import ExportOutlined from "@ant-design/icons/ExportOutlined";
-import FileUnknownOutlined from "@ant-design/icons/FileUnknownOutlined";
-import FileExclamationOutlined from "@ant-design/icons/FileExclamationOutlined";
-import CloseOutlined from "@ant-design/icons/CloseOutlined";
-import DeleteOutlined from "@ant-design/icons/DeleteOutlined";
-import PlusOutlined from "@ant-design/icons/PlusOutlined";
 
 import * as lib from "@clusterio/lib";
 import ControlContext from "./ControlContext";
@@ -26,18 +26,23 @@ import PageHeader from "./PageHeader";
 import PageLayout from "./PageLayout";
 import SectionHeader from "./SectionHeader";
 import ModDetails from "./ModDetails";
+import InputPartialVersion from "./InputPartialVersion";
 
 const { logger } = lib;
-const { Paragraph, Text } = Typography;
+const { Text } = Typography;
 const strcmp = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" }).compare;
 
-
 type ModChange =
 	{
-		type: "name" | "description" | "factorioVersion",
+		type: "name" | "description"
 		name?: never,
 		scope?: never,
 		value: string,
+	} | {
+		type: "factorioVersion",
+		name?: never,
+		scope?: never,
+		value: lib.PartialVersion,
 	} | {
 		type: "settings.set" | "settings.delete",
 		name: string,
@@ -47,7 +52,7 @@ type ModChange =
 		type: "mods.set" | "mods.delete",
 		name: string,
 		scope?: never,
-		value: lib.ModRecord | lib.ModInfo,
+		value: lib.ModRecord,
 	}
 ;
 
@@ -71,28 +76,38 @@ function SearchModsTable(props: SearchModsTableProps) {
 	const [modResultPageSize, setModResultPageSize] = useState<number>(10);
 	const [modResultCount, setModResultCount] = useState<number>(2);
 	const [modResultSelectedVersion, setModResultSelectedVersion] = useState<Map<string, number>>(new Map());
+	const [factorioVersion, setFactorioVersion] = useState<lib.ApiVersion | null>(null);
 
-	const factorioVersion = props.modPack.factorioVersion.split(".").slice(0, 2).join(".");
+	// Get a valid factorio version
+	useEffect(() => {
+		try {
+			setFactorioVersion(lib.normaliseApiVersion(props.modPack.factorioVersion));
+		} catch (err) {
+			setFactorioVersion(null);
+		}
+	}, [props.modPack.factorioVersion]);
 
 	useEffect(() => {
 		let canceled = false;
-		control.send(new lib.ModSearchRequest(
-			searchText,
-			factorioVersion,
-			modResultPage,
-			modResultPageSize,
-			modResultSort,
-			modResultSortOrder,
-		)).then(response => {
-			if (canceled) {
-				return;
-			}
-			// In React < v18 this causes 3 renders and a partial state necessitating the use
-			// of || 0 on modResultSelectedVersion.get() calls. Remove when updating React.
-			setModResults(response.results);
-			setModResultSelectedVersion(new Map(response.results.map(({ name, versions }) => [name, 0])));
-			setModResultCount(response.resultCount);
-		});
+		if (factorioVersion) {
+			control.send(new lib.ModSearchRequest(
+				searchText,
+				factorioVersion,
+				modResultPage,
+				modResultPageSize,
+				modResultSort,
+				modResultSortOrder,
+			)).then(response => {
+				if (canceled) {
+					return;
+				}
+				// In React < v18 this causes 3 renders and a partial state necessitating the use
+				// of || 0 on modResultSelectedVersion.get() calls. Remove when updating React.
+				setModResults(response.results);
+				setModResultSelectedVersion(new Map(response.results.map(({ name, versions }) => [name, 0])));
+				setModResultCount(response.resultCount);
+			});
+		}
 
 		return () => {
 			canceled = true;
@@ -239,19 +254,260 @@ function SearchModsTable(props: SearchModsTableProps) {
 	</>;
 }
 
+type DownloadDependenciesProps = {
+	disabled?: boolean;
+	checkForUpdates?: boolean;
+	modPack: lib.ModPack;
+	mods: lib.ModRecord[];
+	onChange: (change: ModChange) => void;
+	builtInModNames: string[];
+}
+function DownloadDependenciesButton(props: DownloadDependenciesProps) {
+	const control = useContext(ControlContext);
+	const [modInfos] = useMods();
+
+	// State for the modal and dependencies
+	const [open, setOpen] = useState(false);
+	const [missing, setMissing] = useState<string[]>([]);
+	const [builtins, setBuiltins] = useState<string[]>([]);
+	const [incompatible, setIncompatible] = useState<string[]>([]);
+	const [factorioVersion, setFactorioVersion] = useState<lib.ApiVersion | null>(null);
+
+	// State for all mods fetched from backend
+	const [error, setError] = useState<Error | null>(null);
+	const [loading, setLoading] = useState<boolean>(false);
+	const [allMods, setAllMods] = useState<lib.ModInfo[]>([]);
+	const [mods, setMods] = useState<lib.ModInfo[]>([]);
+
+	// Get a valid factorio version
+	useEffect(() => {
+		try {
+			setFactorioVersion(lib.normaliseApiVersion(props.modPack.factorioVersion));
+		} catch (err) {
+			setError(new Error(`Invalid factorio version: ${props.modPack.factorioVersion}`));
+			setFactorioVersion(null);
+		}
+	}, [props.modPack.factorioVersion]);
+
+	// Fetch all mods from backend when modal opens or version changes
+	useEffect(() => {
+		if (!open || !factorioVersion) {
+			// Clear if closed or no version
+			setMods([]);
+			setAllMods([]);
+			setMissing([]);
+			setBuiltins([]);
+			setIncompatible([]);
+			return;
+		}
+
+		setLoading(true);
+		setError(null);
+		let canceled = false;
+
+		control.send(
+			lib.ModDependencyResolveRequest.fromModPackEnabled(props.modPack, props.checkForUpdates)
+		).then(response => {
+			if (canceled) { return; }
+			setMods(response.dependencies.filter(dep => !modInfos.has(`${dep.name}_${dep.version}`)));
+			setIncompatible(response.incompatible);
+			setAllMods(response.dependencies);
+			setMissing(response.missing.filter(name => !props.builtInModNames.includes(name)));
+			setBuiltins(response.missing.filter(name => props.builtInModNames.includes(name)));
+			setLoading(false);
+		}).catch(err => {
+			if (canceled) { return; }
+			notifyErrorHandler("Error fetching mods dependencies")(err);
+			setError(err);
+			setMods([]);
+			setAllMods([]);
+			setMissing([]);
+			setBuiltins([]);
+			setIncompatible([]);
+			setLoading(false);
+		});
+
+		// eslint-disable-next-line consistent-return
+		return () => {
+			canceled = true;
+		};
+		// Re-fetch when modal opens or factorio version changes
+	}, [open, factorioVersion, control]);
+
+	// Function to handle download from Mod Portal to Controller
+	function handleControllerDownload() {
+		if (!factorioVersion || !mods) {
+			return;
+		}
+
+		// Enable any required builtins
+		for (const name of builtins) {
+			props.onChange({
+				type: "mods.set",
+				name: name,
+				value: { ...props.modPack.mods.get(name)!, enabled: true },
+			});
+		}
+
+		// Disable any incompatible mods present
+		for (const name of incompatible) {
+			const modRecord = props.modPack.mods.get(name);
+			if (modRecord) {
+				props.onChange({
+					type: "mods.set",
+					name: name,
+					value: { ...modRecord, enabled: false },
+				});
+			}
+		}
+
+		// Add all dependencies to the mod pack
+		for (const mod of allMods) {
+			props.onChange({
+				type: "mods.set",
+				name: mod.name,
+				value: {
+					name: mod.name,
+					version: mod.version,
+					sha1: mod.sha1,
+					enabled: true,
+				},
+			});
+		}
+
+		// Download the missing dependencies
+		control.send(
+			new lib.ModPortalDownloadRequest(
+				mods.map(mod => ({
+					name: mod.name, version: new lib.ModVersionEquality("=", mod.version),
+				})),
+				factorioVersion,
+			)
+		).then(() => {
+			notification.success({
+				message: "Download complete",
+				description: `${mods.length} mods have been downloaded to the controller.`,
+			});
+		}).catch(
+			notifyErrorHandler("Error starting mod download")
+		);
+	};
+
+	return <>
+		{props.checkForUpdates && <Button
+			disabled={props.disabled}
+			icon={<CloudSyncOutlined />}
+			onClick={() => { setOpen(true); }}
+		>Check for Updates</Button> || <Button
+			disabled={props.disabled}
+			icon={<CloudDownloadOutlined />}
+			onClick={() => { setOpen(true); }}
+		>Download Dependencies</Button>}
+		<Modal
+			title={props.checkForUpdates ? "Download Updates" : "Download Dependencies"}
+			open={open}
+			onCancel={() => { setOpen(false); }}
+			width={1000}
+			footer={[
+				<Button key="close" onClick={() => { setOpen(false); }}>
+					Close
+				</Button>,
+				<Button
+					key="start"
+					type="primary"
+					disabled={loading || mods.length === 0}
+					onClick={() => { setOpen(false); handleControllerDownload(); }}
+				>Start Download</Button>,
+			]}
+		>
+			{/* Display error message if fetching failed */}
+			{error && <Alert
+				message="Error Fetching Mods"
+				description={error.message}
+				type="error"
+				showIcon
+				style={{ marginBottom: 16 }}
+			/>}
+
+			{/* Display warning message if dependencies could not be found */}
+			{!loading && missing.length > 0 && <Alert
+				message="Failed to Find Dependencies:"
+				description={<ul>
+					{missing.map(name => <li>{name}</li>)}
+				</ul>}
+				type="warning"
+				showIcon
+				style={{ marginBottom: 16 }}
+			/>}
+
+			{/* Display warning message if dependencies are incompatible */}
+			{!loading && incompatible.length > 0 && <Alert
+				message="Incompatible Dependencies Found:"
+				description={<ul>
+					{incompatible.map(name => <li>{name}</li>)}
+				</ul>}
+				type="warning"
+				showIcon
+				style={{ marginBottom: 16 }}
+			/>}
+
+			<Table
+				dataSource={mods}
+				rowKey={record => record.name}
+				loading={loading}
+				pagination={{
+					defaultPageSize: 10,
+					showSizeChanger: true,
+					pageSizeOptions: ["10", "20", "50", "100"],
+					showTotal: (total: number) => (
+						props.checkForUpdates ? `${total} Updates` : `${total} Missing Dependencies`
+					),
+				}}
+				columns={[
+					{
+						title: "Name",
+						dataIndex: "name",
+						key: "name",
+						sorter: true,
+					},
+					{
+						title: "Title",
+						dataIndex: "title",
+						key: "title",
+						sorter: true,
+					},
+					{
+						title: "Author",
+						dataIndex: "author",
+						key: "author",
+						sorter: true,
+					},
+					{
+						title: "Selected Version",
+						dataIndex: "version",
+						key: "version",
+					},
+				]}
+			/>
+		</Modal>
+	</>;
+}
+
 type ModsTableProps = {
 	modPack: lib.ModPack;
 	changes: ModChange[];
 	onChange: (change: ModChange) => void;
 	onRevert: (change: ModChange) => void;
-	builtInMods: string[];
+	builtInModNames: string[];
 };
 function ModsTable(props: ModsTableProps) {
-	const [showAddMods, setShowAddMods] = useState(false);
-	const [modsMap] = useMods();
+	const account = useAccount();
+	const [modInfos] = useMods();
 
-	const deletedMods: Map<string, lib.ModRecord|lib.ModInfo> = new Map();
-	const changedMods: Map<string, lib.ModRecord|lib.ModInfo> = new Map();
+	const [showAddMods, setShowAddMods] = useState(false);
+
+	const deletedMods: Map<string, lib.ModRecord> = new Map();
+	const changedMods: Map<string, lib.ModRecord> = new Map();
 	for (let change of props.changes) {
 		if (change.name) {
 			if (props.modPack.mods.has(change.name)) {
@@ -265,34 +521,119 @@ function ModsTable(props: ModsTableProps) {
 	}
 
 	const mods = [...props.modPack.mods.values(), ...deletedMods.values()].map(
-		(mod: lib.ModRecord|lib.ModInfo): lib.ModInfo|lib.ModRecord => {
-			if (props.builtInMods.includes(mod.name)) {
+		(mod: lib.ModRecord): lib.ModRecord => {
+			if (props.builtInModNames.includes(mod.name)) {
 				return {
 					...mod,
-					enabled: (mod as any).enabled ?? false,
+					enabled: mod.enabled ?? false,
 				};
 			}
-			const candidate = modsMap.get(`${mod.name}_${mod.version}`);
-			if (!candidate) {
+			const modInfo = modInfos.get(`${mod.name}_${mod.version}`);
+			if (!modInfo) {
 				return {
 					...mod,
-					enabled: (mod as any).enabled ?? false,
+					enabled: mod.enabled ?? false,
 					error: "missing",
 				};
-			} else if (mod.sha1 && candidate.sha1 !== mod.sha1) {
+			} else if (mod.sha1 && modInfo.sha1 !== mod.sha1) {
 				return {
 					...mod,
-					enabled: (mod as any).enabled ?? false,
+					enabled: mod.enabled ?? false,
 					error: "bad_checksum",
 				};
 			}
-			return candidate;
+			return {
+				...mod,
+				enabled: mod.enabled ?? false,
+				info: modInfo,
+			};
 		}
 	);
 
-	function actions(mod: lib.ModRecord|lib.ModInfo) {
+	for (const mod of mods) {
+		if (mod.enabled && mod.info) {
+			mod.warning = mod.info.checkDependencySatisfaction(mods.filter(m => m.enabled));
+			try {
+				const packFactorioVersion = lib.normaliseApiVersion(props.modPack.factorioVersion);
+				const modFactorioVersion = lib.normaliseApiVersion(mod.info.factorioVersion);
+				if (packFactorioVersion !== modFactorioVersion) {
+					mod.warning = "wrong_factorio_version";
+				}
+			} catch {
+				// Hit if the mod or mod pack version is not a valid api version
+				mod.warning = "wrong_factorio_version";
+			}
+		}
+	}
+
+	async function fixDependencyIssues(mod: lib.ModRecord) {
+		if (!mod.info) {
+			throw new Error("Mod record has no info"); // Should be unreachable
+		}
+		if (mod.info.factorioVersion === "0.12") {
+			throw new Error("Factorio version 0.12 not supported by mod portal");
+		}
+
+		let hasFailure = false;
+		const enabledMods = mods.filter(m => m.enabled);
+		const modInfoArray = [...modInfos.values()];
+		for (const dependency of mod.info.dependencies) {
+			const reason = dependency.checkUnsatisfiedReason(enabledMods);
+			if (reason === undefined) {
+				continue; // No issues for this dependency
+			}
+
+			if (reason === "incompatible") {
+				// Disable the incompatible mod
+				props.onChange({
+					type: "mods.set",
+					name: dependency.name,
+					value: { ...props.modPack.mods.get(dependency.name)!, enabled: false },
+				});
+				continue;
+			}
+
+			if (props.builtInModNames.includes(dependency.name)) {
+				// If builtin mod then enable it
+				props.onChange({
+					type: "mods.set",
+					name: dependency.name,
+					value: { ...props.modPack.mods.get(dependency.name)!, enabled: true },
+				});
+				continue;
+			}
+
+			// Find a suitable version to add
+			const candidate = modInfoArray
+				.filter(info => (info.name === dependency.name && info.factorioVersion === mod.info!.factorioVersion
+					&& (!dependency.version || dependency.version.testVersion(info.version))
+				))
+				.reduce<lib.ModInfo | undefined>((max, cur) => (
+					max && max.integerVersion > cur.integerVersion ? max : cur
+				), undefined);
+
+			if (candidate) {
+				props.onChange({
+					type: "mods.set",
+					name: candidate.name,
+					value: {
+						name: candidate.name,
+						version: candidate.version,
+						sha1: candidate.sha1,
+						enabled: true,
+					},
+				});
+			} else {
+				hasFailure = true;
+			}
+		}
+
+		return hasFailure;
+	}
+
+	function actions(mod: lib.ModRecord) {
 		return <Space>
-			{!deletedMods.has(mod.name) && !props.builtInMods.includes(mod.name) && <Typography.Link
+			{!deletedMods.has(mod.name) && !props.builtInModNames.includes(mod.name) && <Typography.Link
 				type="danger"
 				onClick={() => {
 					props.onChange({
@@ -311,13 +652,52 @@ function ModsTable(props: ModsTableProps) {
 					});
 				}}
 			>revert</Typography.Link>}
+			{(mod.warning && mod.warning !== "wrong_factorio_version") && <Typography.Link
+				onClick={async () => {
+					if (await fixDependencyIssues(mod)) {
+						notify("Failed to automatically fix all issues", "warning");
+					}
+				}}
+			>fix issues</Typography.Link>}
 		</Space>;
 	}
 
 	return <>
 		<SectionHeader
 			title="Mods"
-			extra={<Space>
+			extra={<Space wrap>
+				<Button
+					icon={<ToolOutlined />}
+					disabled={!mods.some(m => m.enabled && m.warning && m.warning !== "wrong_factorio_version")}
+					onClick={async () => {
+						const hasFailure = await Promise.all(mods
+							.filter(m => m.enabled && m.warning && m.warning !== "wrong_factorio_version")
+							.map(m => fixDependencyIssues(m))
+						);
+						if (hasFailure.some(v => v)) {
+							notify("Failed to automatically fix all issues", "warning");
+						}
+					}}
+				>Fix Issues</Button>
+				{account.hasAllPermission("core.mod.search_portal", "core.mod.download_from_portal")
+					&& <DownloadDependenciesButton
+						mods={mods}
+						modPack={props.modPack}
+						onChange={props.onChange}
+						builtInModNames={props.builtInModNames}
+						disabled={!mods.some(
+							m => m.enabled
+							&& (m.error || m.warning && ["wrong_version", "missing_dependency"].includes(m.warning))
+						)}
+					/>}
+				{account.hasAllPermission("core.mod.search_portal", "core.mod.download_from_portal")
+					&& <DownloadDependenciesButton
+						mods={mods}
+						modPack={props.modPack}
+						onChange={props.onChange}
+						builtInModNames={props.builtInModNames}
+						checkForUpdates
+					/>}
 				<Button icon={<PlusOutlined />} onClick={() => setShowAddMods(true)}>Add</Button>
 			</Space>}
 		/>
@@ -361,14 +741,26 @@ function ModsTable(props: ModsTableProps) {
 				{
 					title: "Name",
 					key: "name",
-					render: (_, mod: any) => <>
+					render: (_, mod: lib.ModRecord) => <>
 						{mod.error === "missing" && <Tooltip title="Mod is missing from storage.">
 							<FileUnknownOutlined style={{ color: "#a61d24" }} />{" "}
 						</Tooltip>}
-						{mod.error === "bad_checksum" && <Tooltip title="Mod checksum missmatch.">
+						{mod.error === "bad_checksum" && <Tooltip title="Mod checksum mismatch.">
 							<FileExclamationOutlined style={{ color: "#a61d24" }} />{" "}
 						</Tooltip>}
-						{mod.title || mod.name}
+						{mod.warning === "incompatible" && <Tooltip title="Mod is incompatible with another.">
+							<FileExclamationOutlined style={{ color: "#dd5e14" }} />{" "}
+						</Tooltip>}
+						{mod.warning === "missing_dependency" && <Tooltip title="Mod is missing a dependency.">
+							<FileUnknownOutlined style={{ color: "#dd5e14" }} />{" "}
+						</Tooltip>}
+						{mod.warning === "wrong_version" && <Tooltip title="Mod has wrong dependency version added.">
+							<FileSyncOutlined style={{ color: "#dd5e14" }} />{" "}
+						</Tooltip>}
+						{mod.warning === "wrong_factorio_version" && <Tooltip title="Mod has wrong factorio version.">
+							<FileSyncOutlined style={{ color: "#dd5e14" }} />{" "}
+						</Tooltip>}
+						{mod.info?.title || mod.name}
 					</>,
 					defaultSortOrder: "ascend",
 					sorter: (a, b) => strcmp(a.name, b.name),
@@ -386,7 +778,7 @@ function ModsTable(props: ModsTableProps) {
 				},
 			]}
 			expandable={{
-				expandedRowRender: mod => <ModDetails mod={mod} actions={actions} />,
+				expandedRowRender: mod => <ModDetails mod={mod} mods={mods.filter(m => m.enabled)} actions={actions} />,
 				expandedRowClassName: () => "no-expanded-padding",
 			}}
 			dataSource={mods}
@@ -897,7 +1289,9 @@ export default function ModPackViewPage() {
 							message: "Must be an a.b or a.b.c version number.",
 						}]}
 					>
-						<Input
+						<InputPartialVersion
+							value={form.getFieldValue("factorioVersion")}
+							onChange={(value: any) => form.setFieldValue("factorioVersion", value)}
 							className={hasChange(changes, { type: "factorioVersion" }) ? "changed" : ""}
 						/>
 					</Form.Item>
@@ -908,9 +1302,7 @@ export default function ModPackViewPage() {
 				changes={changes}
 				onChange={pushChange}
 				onRevert={revertChange}
-				builtInMods={
-					lib.ModPack.getBuiltinMods(modifiedModPack.factorioVersion).map(builtinMod => builtinMod.name)
-				}
+				builtInModNames={lib.ModPack.getBuiltinModNames(modifiedModPack.factorioVersion)}
 			/>
 			<SettingsTable
 				modPack={modifiedModPack}

packages/web_ui/src/components/ModsPage.tsx

@@ -6,7 +6,6 @@ import {
 import {
 	ImportOutlined, PlusOutlined, SearchOutlined, DownloadOutlined,
 } from "@ant-design/icons";
-import { Static } from "@sinclair/typebox";
 
 import * as lib from "@clusterio/lib";
 
@@ -22,12 +21,10 @@ import SectionHeader from "./SectionHeader";
 import ModDetails from "./ModDetails";
 import { Dropzone } from "./Dropzone";
 import UploadButton from "./UploadButton";
+import InputPartialVersion from "./InputPartialVersion";
 
 const strcmp = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" }).compare;
 
-// Define the allowed Factorio versions based on the lib schema
-type FactorioVersion = Static<(typeof lib.ModPortalGetAllRequest)["allowedVersions"][number]>;
-
 // Type alias for the mod structure derived from the library response
 type ModPortalModType = InstanceType<typeof lib.ModPortalGetAllRequest.Response>["mods"][number];
 
@@ -132,7 +129,10 @@ function CreateModPackButton() {
 						message: "Must be an a.b or a.b.c version number.",
 					}]}
 				>
-					<Input />
+					<InputPartialVersion
+						value={form.getFieldValue("factorioVersion")}
+						onChange={(value) => form.setFieldValue("factorioVersion", value)}
+					/>
 				</Form.Item>
 			</Form>
 		</Modal>
@@ -145,7 +145,7 @@ function SearchModsButton() {
 	const [open, setOpen] = useState(false);
 	const [form] = Form.useForm();
 	const [searchText, setSearchText] = useState("");
-	const [factorioVersion, setFactorioVersion] = useState<FactorioVersion>("2.0");
+	const [factorioVersion, setFactorioVersion] = useState<lib.ApiVersion>("2.0");
 
 	// State for all mods fetched from backend
 	const [allMods, setAllMods] = useState<ModPortalModType[]>([]);
@@ -162,22 +162,21 @@ function SearchModsButton() {
 	const handleControllerDownload = (
 		modName: string,
 		modTitle: string | undefined,
-		modVersion: string | undefined,
-		portalFactorioVersion: FactorioVersion,
+		modVersion: lib.FullVersion | undefined,
+		portalFactorioVersion: lib.ApiVersion,
 	) => {
 		if (modVersion) {
 			control.send(
 				new lib.ModPortalDownloadRequest(
-					modName,
-					modVersion,
+					[{ name: modName, version: new lib.ModVersionEquality("=", modVersion)}],
 					portalFactorioVersion
 				)
 			).then(() => {
 				notification.success({
-					message: "Download started",
+					message: "Download complete",
 					description: `${modTitle || modName} v${
 						modVersion
-					} is being downloaded to the controller.`,
+					} has been downloaded to the controller.`,
 				});
 			}).catch(
 				notifyErrorHandler("Error starting mod download")
@@ -270,7 +269,7 @@ function SearchModsButton() {
 	// Update search text and factorio version from form
 	const handleSearch = (changedValues: any, allValues: any) => {
 		const nameValue = allValues.name;
-		const versionValue = allValues.factorioVersion as FactorioVersion | undefined;
+		const versionValue = allValues.factorioVersion as lib.ApiVersion | undefined;
 
 		// Only trigger state updates if values actually changed
 		if (nameValue !== searchText) {
@@ -351,12 +350,9 @@ function SearchModsButton() {
 					label="Factorio Version"
 				>
 					<Select>
-						{lib.ModPortalGetAllRequest.allowedVersions.map((literalSchema: any) => (
-							<Select.Option
-								key={literalSchema.const}
-								value={literalSchema.const}
-							>
-								{literalSchema.const}
+						{lib.ApiVersions.map(version => (
+							<Select.Option key={version} value={version}>
+								{version}
 							</Select.Option>
 						)).reverse()}
 					</Select>
@@ -569,7 +565,7 @@ export default function ModsPage() {
 		<PageHeader title="Mods" />
 		<SectionHeader
 			title="Mod Packs"
-			extra={<Space>
+			extra={<Space wrap>
 				{account.hasPermission("core.mod_pack.create") && <ImportModPackButton />}
 				{account.hasPermission("core.mod_pack.create") && <CreateModPackButton />}
 			</Space>}
@@ -602,7 +598,7 @@ export default function ModsPage() {
 				},
 			})}
 		/>
-		<SectionHeader title="Stored Mods" extra={<Space>
+		<SectionHeader title="Stored Mods" extra={<Space wrap>
 			<SearchModsButton />
 			{uploadButton}
 		</Space>} />

packages/web_ui/src/components/NpmButton.tsx

@@ -187,7 +187,7 @@ export function NpmButton(props: { target: lib.AddressShorthand, canRestart?: bo
 				{
 					formAction !== undefined
 					&& account.hasPermission(`core.${props.target === "controller" ? "controller" : "host"}.restart`)
-					&& <Form.Item label="Restart on completion" name="restart">
+					&& <Form.Item label="Restart on completion" name="restart" valuePropName="checked">
 						<Checkbox disabled={props.canRestart === false}/>
 					</Form.Item>
 				}

packages/web_ui/src/components/RoleViewPage.tsx

@@ -1,6 +1,6 @@
 import React, { useEffect, useContext, useState } from "react";
 import { useNavigate, useParams } from "react-router-dom";
-import { Button, Checkbox, Form, Input, Popconfirm, Spin } from "antd";
+import { Button, Checkbox, Form, Input, Popconfirm, Space, Spin } from "antd";
 import DeleteOutlined from "@ant-design/icons/DeleteOutlined";
 
 import * as lib from "@clusterio/lib";
@@ -71,7 +71,7 @@ export default function RoleViewPage() {
 		>
 			<PageHeader
 				title={role.name}
-				extra={<>
+				extra={<Space wrap>
 					{canUpdate && <Button type={edited ? "primary" : "default"} htmlType="submit">Apply</Button>}
 					{account.hasPermission("core.role.delete") && <Popconfirm
 						title="Delete role?"
@@ -90,7 +90,7 @@ export default function RoleViewPage() {
 							<DeleteOutlined />
 						</Button>
 					</Popconfirm>}
-				</>}
+				</Space>}
 			/>
 			<Form.Item name="name" label="Name">
 				<Input disabled={!canUpdate}/>

packages/web_ui/src/components/SavesList.tsx

@@ -345,7 +345,7 @@ export default function SavesList(props: { instance: lib.InstanceDetails }) {
 	};
 
 	return <div>
-		<SectionHeader title="Saves" extra={<Space>
+		<SectionHeader title="Saves" extra={<Space wrap>
 			{account.hasPermission("core.instance.save.upload") && <Upload {...uploadProps} >
 				<UploadButton disabled={hostOffline}>
 					Upload save

packages/web_ui/src/components/UserViewPage.tsx

@@ -106,7 +106,7 @@ export default function UserViewPage() {
 					{user.isBanned && <Tag color="red">Banned</Tag>}
 				</span>
 			</Space>}
-			extra={<>
+			extra={<Space wrap>
 				{account.hasPermission("core.user.revoke_token") && (
 					account.name === userName || account.hasPermission("core.user.revoke_other_token")
 				) && <Button
@@ -146,7 +146,7 @@ export default function UserViewPage() {
 						<DeleteOutlined />
 					</Button>
 				</Popconfirm>}
-			</>}
+			</Space>}
 		/>
 		<Form
 			form={form}

packages/web_ui/src/components/UsersTable.tsx

@@ -249,6 +249,7 @@ export default function UsersTable({ instanceId, onlyOnline = false, pagination,
 			rowKey={(user) => user.name}
 			pagination={defaultPagination}
 			size={size}
+			scroll={{ x: "max-content" }}
 			onRow={(user) => ({
 				onClick: (event) => {
 					if ((event.target as HTMLElement).closest("a")) {

packages/web_ui/src/util/websocket.ts

@@ -69,6 +69,9 @@ export class Control extends lib.Link {
 	users = new lib.EventSubscriber(lib.UserUpdatesEvent, this);
 	roles = new lib.EventSubscriber(lib.RoleUpdatesEvent, this);
 
+	/** Cache for factorio versions to avoid repeat calls to the controller */
+	factorioVersions = new lib.ValueCache(this.requestFactorioVersions.bind(this));
+
 	declare connector: ControlConnector;
 
 	constructor(
@@ -105,6 +108,10 @@ export class Control extends lib.Link {
 		this.handle(lib.DebugWsMessageEvent, this.handleDebugWsMessageEvent.bind(this));
 	}
 
+	requestFactorioVersions() {
+		return this.send(new lib.FactorioVersionsRequest());
+	}
+
 	async handleAccountUpdateEvent(event: lib.AccountUpdateEvent) {
 		this.accountRoles = event.roles??null;
 		this.emitAccountUpdate();

plugins/global_chat/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@clusterio/plugin-global_chat",
-	"version": "2.0.0-alpha.21",
+	"version": "2.0.0-alpha.22b",
 	"description": "Clusterio plugin forwarding between Factorio servers",
 	"author": "Hornwitser <github@hornwitser.no>",
 	"homepage": "https://github.com/clusterio/clusterio#readme",
@@ -20,25 +20,30 @@
 		"url": "https://github.com/clusterio/clusterio/issues"
 	},
 	"engines": {
-		"node": ">=18"
+		"node": ">=20"
 	},
 	"peerDependencies": {
+		"@clusterio/web_ui": "workspace:*",
+		"@clusterio/host": "workspace:*",
+		"@clusterio/ctl": "workspace:*",
 		"@clusterio/lib": "workspace:*"
 	},
+	"dependencies": {
+		"@sinclair/typebox": "catalog:"
+	},
 	"devDependencies": {
-		"@clusterio/lib": "workspace:*",
 		"@clusterio/web_ui": "workspace:*",
-		"@types/node": "^20.17.19",
-		"@types/react": "^18.3.18",
-		"typescript": "^5.7.3",
-		"webpack": "^5.98.0",
-		"webpack-cli": "^5.1.4",
-		"webpack-merge": "^5.9.0"
+		"@clusterio/host": "workspace:*",
+		"@clusterio/ctl": "workspace:*",
+		"@clusterio/lib": "workspace:*",
+		"@types/node": "catalog:",
+		"@types/react": "catalog:",
+		"typescript": "catalog:",
+		"webpack": "catalog:",
+		"webpack-cli": "catalog:",
+		"webpack-merge": "catalog:"
 	},
 	"publishConfig": {
 		"access": "public"
-	},
-	"dependencies": {
-		"@sinclair/typebox": "^0.30.4"
 	}
 }

plugins/global_chat/tsconfig.node.json

@@ -2,6 +2,8 @@
 	"extends": "../../tsconfig.node.json",
 	"references": [
 		{ "path": "../../packages/lib/tsconfig.node.json" },
+		{ "path": "../../packages/host/tsconfig.node.json" },
+		{ "path": "../../packages/ctl/tsconfig.node.json" },
 	],
 	"include": ["./**/*.ts"],
 	"exclude": ["test/*", "./dist/*"],

plugins/inventory_sync/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@clusterio/plugin-inventory_sync",
-	"version": "2.0.0-alpha.21",
+	"version": "2.0.0-alpha.22b",
 	"description": "Clusterio plugin forwarding between Factorio servers",
 	"author": "Danielv <danielv@danielv.no>",
 	"homepage": "https://github.com/clusterio/factorioClusterio#readme",
@@ -20,28 +20,33 @@
 		"url": "https://github.com/clusterio/factorioClusterio/issues"
 	},
 	"engines": {
-		"node": ">=18"
+		"node": ">=20"
 	},
 	"peerDependencies": {
+		"@clusterio/controller": "workspace:*",
+		"@clusterio/web_ui": "workspace:*",
+		"@clusterio/host": "workspace:*",
 		"@clusterio/lib": "workspace:*"
 	},
 	"dependencies": {
-		"@sinclair/typebox": "^0.30.4",
-		"fs-extra": "^8.1.0"
+		"@sinclair/typebox": "catalog:",
+		"fs-extra": "catalog:"
 	},
 	"devDependencies": {
-		"@clusterio/lib": "workspace:*",
+		"@clusterio/controller": "workspace:*",
 		"@clusterio/web_ui": "workspace:*",
-		"@types/fs-extra": "^11.0.1",
-		"@types/node": "^20.17.19",
-		"@types/react": "^18.3.18",
-		"antd": "^5.24.2",
-		"react": "^18.2.0",
-		"react-dom": "^18.2.0",
-		"typescript": "^5.7.3",
-		"webpack": "^5.98.0",
-		"webpack-cli": "^5.1.4",
-		"webpack-merge": "^5.9.0"
+		"@clusterio/host": "workspace:*",
+		"@clusterio/lib": "workspace:*",
+		"@types/fs-extra": "catalog:",
+		"@types/node": "catalog:",
+		"@types/react": "catalog:",
+		"antd": "catalog:",
+		"react": "catalog:",
+		"react-dom": "catalog:",
+		"typescript": "catalog:",
+		"webpack": "catalog:",
+		"webpack-cli": "catalog:",
+		"webpack-merge": "catalog:"
 	},
 	"publishConfig": {
 		"access": "public"

plugins/inventory_sync/tsconfig.node.json

@@ -2,6 +2,8 @@
 	"extends": "../../tsconfig.node.json",
 	"references": [
 		{ "path": "../../packages/lib/tsconfig.node.json" },
+		{ "path": "../../packages/host/tsconfig.node.json" },
+		{ "path": "../../packages/controller/tsconfig.node.json" },
 	],
 	"include": ["./**/*.ts"],
 	"exclude": ["test/*", "./dist/*"],

plugins/minimap/.npmignore

@@ -0,0 +1,3 @@
+node_modules/
+*.ts
+!*.d.ts 

plugins/minimap/README.md

@@ -0,0 +1,40 @@
+# Clusterio Minimap Plugin
+
+A Clusterio plugin that provides interactive minimaps of Factorio instances with real-time tile and entity data visualization.
+
+## Features
+- Live updating terrain map in web UI
+- Recipe overlay showing active crafting machines
+- Timelapse mode for viewing historical changes
+- Chart tag visualization and management
+- Per instance, force and surface support
+- Works when instances are offline
+
+## Documentation
+
+- **[Tile Data Storage](./docs/tile_data_storage.md)** - Binary format for terrain visualization data
+- **[Recipe Overlay](./docs/minimap_recipe_overlay.md)** - Compact storage for crafting machine recipes
+
+## Architecture Overview
+
+The plugin consists of three main data streams:
+
+### Terrain Data
+- Factorio sends RGB565 data for 32×32 chunks  
+- Controller queues chunks and generates incremental pixel changes
+- Data stored in append-only `.bin` files for efficient timelapse replay
+- Web UI renders live updates and historical data
+
+### Recipe Data  
+- Tracks which recipe each crafting machine is running
+- Compact binary format with per-tile dictionaries (~8x smaller than JSON)
+- Live streaming of recipe changes with timeline support
+
+### Chart Tags
+- User-created map markers with text and icons
+- JSONL storage format for simplicity
+- Real-time synchronization across all connected clients
+
+## Usage
+
+Access the minimap through the Clusterio web interface. Select an instance to view its terrain, toggle recipe overlays, enable chart tags, or switch to timelapse mode to review historical changes.

plugins/minimap/docs/minimap_recipe_overlay.md

@@ -0,0 +1,88 @@
+# Crafting-Recipe Overlay for Minimap & Timelapse
+
+## Overview
+Records which recipe every crafting machine is running, streams live changes to web clients, and replays them frame-perfectly in timelapse mode. The solution:
+
+* Works for all forces & surfaces
+* Scales to millions of events using compact binary storage
+* Allows cheap frustum-culling using 256×256 map tiles
+* Uses append-only storage so historical data is never rewritten
+
+## Architecture
+
+### Event Flow
+```mermaid
+sequenceDiagram
+    participant Lua as Factorio Lua (minimap.lua)
+    participant Host as Host/Instance plugin (instance.ts)
+    participant Ctl as Controller plugin (controller.ts)
+    participant UI as Web clients
+
+    Lua->>Host: ipc-minimap:recipe_data (JSON)
+    Host->>Ctl: RecipeDataEvent
+    Ctl-->>UI: RecipeDataEvent (broadcast)
+    UI->>Ctl: GetRawRecipeTileRequest (HTTP / cluster bus)
+    Ctl-->>UI: Raw recipe tile (.recipes)
+```
+
+### Messages
+| Message                            | Direction                   | Purpose                     |
+| ---------------------------------- | --------------------------- | --------------------------- |
+| `RecipeDataEvent`                  | instance → controller → web | Single recipe change (live) |
+| `GetRawRecipeTileRequest/Response` | web → controller            | Fetches binary recipe tile  |
+
+## Storage Format
+
+### Tile Organization
+Uses same 256×256 world-unit tiles as terrain data. 
+Filename: `<instance>_<surface>_<force>_<tileX>_<tileY>.recipes`
+Stored in: `database_directory/minimap_recipe_tiles/`
+
+### Binary Record Format (append-only)
+All numbers **big-endian**.
+
+| Bytes               | Field            | Description                                   |
+| ------------------- | ---------------- | --------------------------------------------- |
+| 1                   | `type`           | `0=DictEntry`, `1=SetRecipe`, `2=ClearRecipe` |
+| **DictEntry (0)**   |                  |
+| 2                   | `index` (uint16) | Dictionary ID (0-65535)                       |
+| 1                   | `len` (uint8)    | UTF-8 byte length                             |
+| n                   | name bytes       | Recipe name string                            |
+| **SetRecipe (1)**   |                  |
+| 4                   | `sec` (uint32)   | ⌊tick / 60⌋ timestamp                         |
+| 1                   | `px` (uint8)     | X position in tile (0-255)                    |
+| 1                   | `py` (uint8)     | Y position in tile (0-255)                    |
+| 2                   | `index` (uint16) | Dictionary ID                                 |
+| **ClearRecipe (2)** |                  |
+| 4                   | `sec` (uint32)   | ⌊tick / 60⌋ timestamp                         |
+| 1                   | `px` (uint8)     | X position in tile (0-255)                    |
+| 1                   | `py` (uint8)     | Y position in tile (0-255)                    |
+
+Dictionary entries are written only when a previously unseen recipe name is required for that tile.
+
+### Space Efficiency
+- ~8x more compact than JSON format
+- Dictionary compression eliminates recipe name repetition
+- Per-tile dictionaries keep indices small (uint16 sufficient)
+
+## Playback
+
+### Live Mode
+- `RecipeDataEvent` broadcasts like `TileDataEvent`
+- Web UI maintains `Map<posKey, recipeName>` for instant icon updates
+- Icons render using Factorio sprite metadata
+
+### Timelapse Mode
+- Downloads `.recipes` files via `GetRawRecipeTileRequest`
+- Parses binary format using shared `parseRecipeTileBinary()` utility
+- Applies Set/Clear records up to selected timeline tick
+- Integrates with existing terrain timelapse system
+
+## Scalability
+| Metric                         | Estimate                      |
+| ------------------------------ | ----------------------------- |
+| Assemblers per large factory   | ~50,000                       |
+| Avg recipe changes per machine | ~5 lifetime                   |
+| Bytes per Set/Clear record     | 8 bytes                       |
+| Total storage per instance     | ~2 MB                         |
+| Max recipes per tile           | <1,000 (well under 65K limit) |

plugins/minimap/docs/player_position_tracking.md

@@ -0,0 +1,111 @@
+# Player Position Tracking
+
+## Overview
+Tracks player positions across the map, streams live movements to web clients, and stores compressed historical data for timeline playback.
+
+## Architecture
+
+### Event Flow
+```mermaid
+sequenceDiagram
+    participant Lua as Factorio Lua (minimap.lua)
+    participant Host as Host/Instance plugin (instance.ts)
+    participant Ctl as Controller plugin (controller.ts)
+    participant UI as Web clients
+
+    Lua->>Host: ipc-minimap:player_position (JSON)
+    Host->>Ctl: PlayerPositionEvent
+    Ctl-->>UI: PlayerPositionEvent (broadcast)
+    UI->>Ctl: GetPlayerPathRequest (HTTP / cluster bus)
+    Ctl-->>UI: compressed path data (.positions)
+```
+
+### Messages
+| Message                         | Direction                   | Purpose                 |
+| ------------------------------- | --------------------------- | ----------------------- |
+| `PlayerPositionEvent`           | instance → controller → web | Live position update    |
+| `GetPlayerPathRequest/Response` | web → controller            | Fetches historical path |
+
+## Storage Format
+
+### Coordinate Encoding
+- **Map size**: 2m × 2m (2 000 000 × 2 000 000 tiles)
+- **Resolution**: 1 tile
+- **Encoding**: 24-bit signed integers per coordinate (±8,388,608 tiles)
+- **Storage**: 3 bytes per coordinate (x_tiles, y_tiles) (24 bits)
+
+### Binary Record Format (append-only)
+
+| Bytes                | Field                | Description                                    |
+| -------------------- | -------------------- | ---------------------------------------------- |
+| 1                    | `type`               | `0=Position`, `1=SessionStart`, `2=SessionEnd` |
+| **Position (0)**     |                      |                                                |
+| 4                    | `t_sec` (uint32)     | Seconds since epoch                            |
+| 4                    | `sec` (uint32)       | Seconds since map started (ticks / 60⌋)        |
+| 3                    | `x_tiles` (int24)    | X coordinate in tiles                          |
+| 3                    | `y_tiles` (int24)    | Y coordinate in tiles                          |
+| 2                    | `player_id` (uint16) | Player dictionary ID                           |
+| **SessionStart (1)** |                      |                                                |
+| 4                    | `t_ms` (uint32)      | Session start time                             |
+| 2                    | `player_id` (uint16) | Player dictionary ID                           |
+| 1                    | `name_len` (uint8)   | UTF-8 byte length of player name               |
+| n                    | `name` bytes         | Player name string                             |
+| **SessionEnd (2)**   |                      |                                                |
+| 4                    | `t_ms` (uint32)      | Session end time                               |
+| 2                    | `player_id` (uint16) | Player dictionary ID                           |
+
+### File Organization
+- Filename: `<instance>_<surface>.positions`
+- Location: `database_directory/minimap_player_positions/`
+- Format: Append-only binary records
+
+### Compression Strategy
+1. **Dictionary compression**: Player names stored once per session
+2. **Temporal compression**: Modified Ramer-Douglas-Peucker algorithm
+   - ε = 15cm maximum deviation
+   - Min Δt = 5s when stationary
+   - Linear interpolation for playback
+3. **Coordinate packing**: 24-bit integers instead of 32-bit floats
+
+## Streaming Protocol
+
+### Live Updates
+- **Trigger**: Position change ≥1 tile OR 250ms timeout
+
+### Message Format (WebSocket)
+```typescript
+interface PlayerPositionEvent {
+  playerId: string;
+  instanceId: string;
+  surface: string;
+  x: number;  // tiles
+  y: number;  // tiles
+  sec: number;  // seconds since map started (⌊tick / 60⌋)
+}
+```
+
+## Playback System
+
+### Live Mode
+- Web UI maintains per-player tween buffer (last 2 points)
+- Canvas interpolation every animation frame
+- Smooth movement without server round-trips
+
+### Timeline Mode
+- When opening the timeline, the client downloads the compressed path data for the player
+- The client then interpolates the path for display
+
+## Implementation Notes
+
+### Saving Process
+```
+1. Queue position updates in positionBuffer
+2. Every 250ms, process queued positions:
+   - Check movement threshold
+   - Broadcast live updates
+   - Buffer for compression
+3. After session end:
+   - Run RDP downsampling
+   - Write compressed records
+   - Update session metadata
+```

plugins/minimap/docs/tile_data_storage.md

@@ -0,0 +1,118 @@
+# Minimap Tile Data Storage Format
+
+## Overview
+The minimap plugin stores terrain visualization data in a compact binary format optimized for both live updates and historical timelapse playback. The system uses append-only tiles that capture pixel changes over time.
+
+## Architecture
+
+### Data Flow
+```mermaid
+sequenceDiagram
+    participant L as Factorio Lua
+    participant H as Host Plugin  
+    participant C as Controller
+    participant W as Web UI
+
+    L->>H: chart_data (32x32 chunk)
+    H->>C: TileDataEvent
+    C->>W: TileDataEvent (broadcast)
+    W->>C: GetRawTileRequest
+    C->>W: tile data (.bin)
+```
+
+### Storage Organization
+- **Tile size**: 256×256 pixels (8×8 chunks of 32×32 each)
+- **Filename**: `<instance>_<surface>_<force>_<tileX>_<tileY>.bin`
+- **Location**: `database_directory/minimap_tiles/`
+- **Format**: Append-only binary records
+
+## Binary Format
+
+### Color Encoding
+Map colors use **RGB565** format (Factorio's internal representation):
+- 5 bits red, 6 bits green, 5 bits blue
+- 16 bits (2 bytes) per pixel
+
+### Record Types
+All timestamps use `⌊tick / 60⌋` (seconds) as uint32.
+
+| Bytes | Field  | Description                 |
+| ----- | ------ | --------------------------- |
+| 1     | `type` | `1=Chunk`, `2=PixelChanges` |
+
+#### Chunk Record (Type 1)
+Initial exploration data for a 32×32 area.
+
+| Bytes | Field             | Description                      |
+| ----- | ----------------- | -------------------------------- |
+| 4     | `tick` (uint32)   | ⌊tick / 60⌋ timestamp            |
+| 1     | `coords` (uint8)  | `(chunkX << 4) \| chunkY`        |
+| 2     | `length` (uint16) | Compressed data length           |
+| n     | `data`            | Deflate-compressed RGB565 pixels |
+
+- **Chunk coordinates**: 4-bit X and Y (0-7 within tile)
+- **Data**: 32×32×2 bytes (2048 bytes uncompressed)
+- **Compression**: Deflate (zlib)
+
+#### Pixel Changes Record (Type 2)  
+Incremental updates for pixels sharing the same color transition.
+
+| Bytes | Field               | Description                 |
+| ----- | ------------------- | --------------------------- |
+| 4     | `tick` (uint32)     | ⌊tick / 60⌋ timestamp       |
+| 2     | `count` (uint16)    | Number of pixels changed    |
+| 2     | `new_color` (uint16)| New RGB565 value            |
+| 2     | `old_color` (uint16)| Previous RGB565 value       |
+
+**Per pixel coordinate (2 bytes each):**
+| Bytes | Field       | Description                  |
+| ----- | ----------- | ---------------------------- |
+| 1     | `x` (uint8) | X coordinate in tile (0-255) |
+| 1     | `y` (uint8) | Y coordinate in tile (0-255) |
+
+**Note**: Multiple Type 2 records may be generated for a single tick if pixels have different color transitions. Each record groups pixels that share the same `old_color` -> `new_color` transition.
+
+## Processing Strategy
+
+### Live Updates
+1. **Exploration**: New chunks sent as Type 1 records
+2. **Changes**: Individual pixel updates grouped by color transition as Type 2 records  
+3. **Optimization**: Pixels with identical color changes are batched together
+
+### Storage Efficiency
+- **Chunks**: ~100-500 bytes after compression (vs 2048 uncompressed)
+- **Pixels**: 2 bytes per coordinate + 11-byte header per color group (vs 6 bytes per pixel in old format)
+- **Timeline**: Old color values enable fast rewind without recalculation
+- **Compression**: Grouping by color transitions provides significant space savings when many pixels change to the same colors
+
+### Timelapse Playback
+1. **Forward**: Apply chunks and pixel changes up to target tick
+2. **Backward**: Revert pixel changes using old_color values
+3. **Chunks**: Revert to black when rewinding past exploration time
+
+## Implementation Notes
+
+### Saving Process
+```
+1. Queue chunk data in chunkSavingQueue
+2. Every 5 seconds, process queued chunks:
+   - Load existing tile (if exists)
+   - Compare new chunk pixels with current tile state  
+   - Group pixel differences by color transition
+   - Generate compressed pixel change records
+   - Append new data to tile file (never modify existing)
+```
+
+### Web Client Rendering
+```
+1. Request tile data with optional maxTick parameter
+2. Parse binary records sequentially 
+3. Apply chunks and pixel changes up to target time
+4. Convert RGB565 to RGBA for Canvas rendering
+5. Overlay live broadcasts for real-time updates
+```
+
+### Cross-Platform Compatibility
+- **Node.js**: Uses Buffer with native endian operations
+- **Browser**: Uses Uint8Array with manual bit manipulation
+- **Shared utilities**: `tile-utils.ts` handles platform differences

plugins/minimap/index.ts

@@ -0,0 +1,52 @@
+import * as lib from "@clusterio/lib";
+
+import {
+	TileDataEvent,
+	ChartTagDataEvent,
+	PlayerPositionEvent,
+	PlayerSessionEndEvent,
+	GetRawTileRequest,
+	GetChartTagsRequest,
+	GetPlayerPathRequest,
+	RecipeDataEvent,
+	GetRawRecipeTileRequest,
+	ClearMinimapSurfaceDataRequest,
+	ClearMinimapDataRequest,
+} from "./messages";
+
+// Define permissions
+lib.definePermission({
+	name: "minimap.view",
+	title: "View Minimap",
+	description: "View the interactive minimap of Factorio instances.",
+	grantByDefault: true,
+});
+lib.definePermission({
+	name: "minimap.manage",
+	title: "Manage Minimap Data",
+	description: "Delete cached minimap data through the web interface.",
+});
+
+export const plugin: lib.PluginDeclaration = {
+	name: "minimap",
+	title: "Minimap",
+	description: "Provides interactive minimaps of Factorio instances with real-time tile and entity data.",
+	instanceEntrypoint: "dist/node/instance",
+	controllerEntrypoint: "dist/node/controller",
+	webEntrypoint: "./web",
+
+	messages: [
+		TileDataEvent,
+		ChartTagDataEvent,
+		PlayerPositionEvent,
+		PlayerSessionEndEvent,
+		RecipeDataEvent,
+		GetRawTileRequest,
+		GetChartTagsRequest,
+		GetPlayerPathRequest,
+		GetRawRecipeTileRequest,
+		ClearMinimapSurfaceDataRequest,
+		ClearMinimapDataRequest,
+	],
+	routes: ["/minimap"],
+};

plugins/minimap/instance.ts

@@ -0,0 +1,227 @@
+import * as lib from "@clusterio/lib";
+import { BaseInstancePlugin } from "@clusterio/host";
+import {
+	TileDataEvent,
+	ChartData,
+	ChartTagDataEvent,
+	ChartTagData,
+	RecipeDataEvent,
+	RecipeData,
+	PlayerPositionEvent,
+	PlayerData,
+	PlayerSessionEndEvent,
+} from "./messages";
+
+interface TileDataIpc {
+	type: "chart";
+	data: ChartData[];
+	position: [number, number];
+	tick: number;
+}
+
+interface ChartTagDataIpc {
+	tag_number: number;
+	start_tick: number | null;
+	end_tick: number | null;
+	force: string;
+	surface: string;
+	position: [number, number];
+	text: string;
+	icon: string | null;
+	last_user: string | null;
+}
+
+interface RecipeDataIpc {
+	tag_number?: number
+	start_tick: number | null
+	end_tick: number | null
+	surface: string
+	force: string
+	position: [number, number]
+	recipe: string | null
+	icon?: { type?: string, name?: string, quality?: string }
+}
+
+interface PlayerPositionIpc {
+	player_name: string;
+	surface: string;
+	x: number;
+	y: number;
+	sec: number;
+}
+
+interface PlayerSessionEndIpc {
+	player_name: string;
+	surface: string;
+}
+
+export class InstancePlugin extends BaseInstancePlugin {
+	pendingTileUpdates = new Map<string, Set<[number, number, [number, number, number, number]]>>();
+
+	async init() {
+		if (!this.instance.config.get("factorio.enable_script_commands")) {
+			throw new Error("minimap plugin requires script commands to be enabled.");
+		}
+
+		// Listen for tile data from the Lua module
+		this.instance.server.on("ipc-minimap:tile_data", (data: TileDataIpc) => {
+			this.handleTileDataFromLua(data).catch(err => this.logger.error(
+				`Error handling tile data from Lua:\n${err}`
+			));
+		});
+
+		// Listen for chart tag data from the Lua module
+		this.instance.server.on("ipc-minimap:chart_tag_data", (data: ChartTagDataIpc) => {
+			this.handleChartTagDataFromLua(data).catch(err => this.logger.error(
+				`Error handling chart tag data from Lua:\n${err}`
+			));
+		});
+
+		// Listen for recipe data from Lua module
+		this.instance.server.on("ipc-minimap:recipe_data", (data: RecipeDataIpc) => {
+			this.handleRecipeDataFromLua(data).catch(err => this.logger.error(
+				`Error handling recipe data from Lua:\n${err}`
+			));
+		});
+
+		// Listen for player position data from Lua module
+		this.instance.server.on("ipc-minimap:player_position", (data: PlayerPositionIpc) => {
+			this.handlePlayerPositionFromLua(data).catch(err => this.logger.error(
+				`Error handling player position data from Lua:\n${err}`
+			));
+		});
+
+		// Listen for player session end data from Lua module
+		this.instance.server.on("ipc-minimap:player_session_end", (data: PlayerSessionEndIpc) => {
+			this.handlePlayerSessionEndFromLua(data).catch(err => this.logger.error(
+				`Error handling player session end data from Lua:\n${err}`
+			));
+		});
+	}
+
+	async handleTileDataFromLua(data: TileDataIpc) {
+		try {
+			const { type, data: rawData, position, tick } = data;
+
+			if (type === "chart") {
+				// Handle new chart data format
+				const chartData = rawData as ChartData[];
+
+				if (!chartData || !Array.isArray(chartData)) {
+					this.logger.error("Invalid chart data received");
+					return;
+				}
+
+				// Send chart data to controller
+				const TileDataEvents = chartData.map(chart => new TileDataEvent(
+					this.instance.config.get("instance.id"),
+					chart.surface,
+					chart.force,
+					position[0],
+					position[1],
+					tick,
+					chart
+				));
+
+				TileDataEvents.map(event => this.instance.sendTo("controller", event));
+			}
+
+		} catch (err) {
+			this.logger.error(`Failed to process tile data from Lua: ${err}`);
+		}
+	}
+
+	async handleChartTagDataFromLua(data: ChartTagDataIpc) {
+		try {
+			// Validate the chart tag data
+			if (!data || typeof data.tag_number !== "number") {
+				this.logger.error("Invalid chart tag data received");
+				return;
+			}
+
+			// Create chart tag data event
+			const chartTagEvent = new ChartTagDataEvent(
+				this.instance.config.get("instance.id"),
+				data as ChartTagData
+			);
+
+			// Send to controller
+			this.instance.sendTo("controller", chartTagEvent);
+		} catch (err) {
+			this.logger.error(`Failed to process chart tag data from Lua: ${err}`);
+		}
+	}
+
+	async handleRecipeDataFromLua(data: RecipeDataIpc) {
+		try {
+			if (!data) {
+				this.logger.error("Invalid recipe data received");
+				return;
+			}
+
+			const recipeData: RecipeData = {
+				start_tick: data.start_tick ?? undefined,
+				end_tick: data.end_tick ?? undefined,
+				surface: data.surface,
+				force: data.force,
+				position: data.position,
+				recipe: data.recipe ?? undefined,
+				icon: data.icon ?? undefined,
+			};
+
+			const event = new RecipeDataEvent(
+				this.instance.config.get("instance.id"),
+				recipeData
+			);
+
+			this.instance.sendTo("controller", event);
+		} catch (err: unknown) {
+			this.logger.error(`Failed to process recipe data from Lua: ${err}`);
+		}
+	}
+
+	async handlePlayerPositionFromLua(data: PlayerPositionIpc) {
+		try {
+			if (!data) {
+				this.logger.error("Invalid player position data received");
+				return;
+			}
+
+			const playerData: PlayerData = {
+				player_name: data.player_name,
+				surface: data.surface,
+				x: data.x,
+				y: data.y,
+				sec: data.sec,
+			};
+
+			const event = new PlayerPositionEvent(
+				this.instance.config.get("instance.id"),
+				playerData
+			);
+			this.instance.sendTo("controller", event);
+		} catch (err: unknown) {
+			this.logger.error(`Failed to process player position data from Lua: ${err}`);
+		}
+	}
+
+	async handlePlayerSessionEndFromLua(data: PlayerSessionEndIpc) {
+		try {
+			if (!data) {
+				this.logger.error("Invalid player session end data received");
+				return;
+			}
+
+			const event = new PlayerSessionEndEvent(
+				this.instance.config.get("instance.id"),
+				{
+					player_name: data.player_name,
+					surface: data.surface,
+				}
+			);
+			this.instance.sendTo("controller", event);
+		} catch (err: unknown) {
+			this.logger.error(`Failed to process player session end data from Lua: ${err}`);
+		}
+	}
+}

plugins/minimap/messages.ts

@@ -0,0 +1,464 @@
+import { Type, Static } from "@sinclair/typebox";
+import * as lib from "@clusterio/lib";
+
+// Define the chart data structure
+export const ChartDataSchema = Type.Object({
+	surface: Type.String(),
+	force: Type.String(),
+	chart_data: Type.String(),
+});
+
+export type ChartData = Static<typeof ChartDataSchema>;
+
+// Define the SignalID structure (based on Factorio API)
+export const SignalIDSchema = Type.Object({
+	type: Type.Optional(Type.String()), // SignalIDType, nil when reading for "item" type
+	name: Type.Optional(Type.String()), // Name of the prototype
+	quality: Type.Optional(Type.String()), // Quality name, defaults to "normal"
+});
+
+export type SignalID = Static<typeof SignalIDSchema>;
+
+// Define the chart tag data structure
+export const ChartTagDataSchema = Type.Object({
+	tag_number: Type.Number(),
+	start_tick: Type.Optional(Type.Number()),
+	end_tick: Type.Optional(Type.Number()),
+	force: Type.String(),
+	surface: Type.String(),
+	position: Type.Tuple([Type.Number(), Type.Number()]),
+	text: Type.String(),
+	icon: Type.Optional(SignalIDSchema),
+	last_user: Type.Optional(Type.String()),
+});
+
+export type ChartTagData = Static<typeof ChartTagDataSchema>;
+
+export const RecipeDataSchema = Type.Object({
+	start_tick: Type.Optional(Type.Number()),
+	end_tick: Type.Optional(Type.Number()),
+	surface: Type.String(),
+	force: Type.String(),
+	position: Type.Tuple([Type.Number(), Type.Number()]),
+	recipe: Type.Optional(Type.String()),
+	icon: Type.Optional(SignalIDSchema),
+});
+
+export type RecipeData = Static<typeof RecipeDataSchema>;
+
+export const PlayerDataSchema = Type.Object({
+	player_name: Type.String(),
+	surface: Type.String(),
+	x: Type.Number(), // tiles
+	y: Type.Number(), // tiles
+	sec: Type.Number(), // seconds since map started (⌊tick / 60⌋)
+});
+
+export type PlayerData = Static<typeof PlayerDataSchema>;
+
+export const PlayerSessionEndDataSchema = Type.Object({
+	player_name: Type.String(),
+	surface: Type.String(),
+});
+
+export type PlayerSessionEndData = Static<typeof PlayerSessionEndDataSchema>;
+
+/**
+ * PlayerPositionEvent: Used for both Factorio Instance -> Controller and Controller -> Web Clients
+ *
+ * Contains real-time player position data for live tracking and movement visualization.
+ * When sent from instance to controller: triggers storage in compressed binary format.
+ * When sent from controller to web clients: enables real-time player position updates.
+ *
+ * Data flow:
+ * - Lua module -> Instance plugin -> Controller plugin (for persistence)
+ * - Controller plugin -> Web UI plugin -> Canvas renderer (for live updates)
+ */
+export class PlayerPositionEvent {
+	declare ["constructor"]: typeof PlayerPositionEvent;
+	static type = "event" as const;
+	static src = ["instance", "controller"] as const;
+	static dst = ["controller", "control"] as const;
+	static plugin = "minimap" as const;
+	static permission = null;
+
+	constructor(
+		public instance_id: number,
+		public player_data: PlayerData,
+	) { }
+
+	static jsonSchema = Type.Object({
+		"instance_id": Type.Number(),
+		"player_data": PlayerDataSchema,
+	});
+
+	static fromJSON(json: Static<typeof PlayerPositionEvent.jsonSchema>) {
+		return new this(
+			json.instance_id,
+			json.player_data
+		);
+	}
+}
+
+/**
+ * PlayerSessionEndEvent: Instance -> Controller
+ *
+ * Notifies controller that a player session has ended (disconnect).
+ */
+export class PlayerSessionEndEvent {
+	declare ["constructor"]: typeof PlayerSessionEndEvent;
+	static type = "event" as const;
+	static src = ["instance"] as const;
+	static dst = ["controller"] as const;
+	static plugin = "minimap" as const;
+	static permission = null;
+
+	constructor(
+		public instance_id: number,
+		public session_data: PlayerSessionEndData,
+	) { }
+
+	static jsonSchema = Type.Object({
+		"instance_id": Type.Number(),
+		"session_data": PlayerSessionEndDataSchema,
+	});
+
+	static fromJSON(json: Static<typeof PlayerSessionEndEvent.jsonSchema>) {
+		return new this(
+			json.instance_id,
+			json.session_data
+		);
+	}
+}
+
+/**
+ * TileDataEvent: Used for both Factorio Instance -> Controller and Controller -> Web Clients
+ *
+ * Contains compressed RGB565 chart data from Factorio's internal mapping system.
+ * When sent from instance to controller: triggers storage in persistent tile files.
+ * When sent from controller to web clients: enables real-time minimap updates.
+ *
+ * Data flow:
+ * - Lua module -> Instance plugin -> Controller plugin (for persistence)
+ * - Controller plugin -> Web UI plugin -> Canvas renderer (for live updates)
+ */
+export class TileDataEvent {
+	declare ["constructor"]: typeof TileDataEvent;
+	static type = "event" as const;
+	static src = ["instance", "controller"] as const;
+	static dst = ["controller", "control"] as const;
+	static plugin = "minimap" as const;
+	static permission = null;
+
+	constructor(
+		public instance_id: number,
+		public surface: string,
+		public force: string,
+		public x: number,
+		public y: number,
+		public tick: number,
+		public chunk: ChartData,
+	) { }
+
+	static jsonSchema = Type.Object({
+		"instance_id": Type.Number(),
+		"surface": Type.String(),
+		"force": Type.String(),
+		"x": Type.Number(),
+		"y": Type.Number(),
+		"tick": Type.Number(),
+		"chunk": ChartDataSchema,
+	});
+
+	static fromJSON(json: Static<typeof TileDataEvent.jsonSchema>) {
+		return new this(
+			json.instance_id,
+			json.surface,
+			json.force,
+			json.x,
+			json.y,
+			json.tick,
+			json.chunk
+		);
+	}
+}
+
+/**
+ * ChartTagDataEvent: Used for both Factorio Instance -> Controller and Controller -> Web Clients
+ *
+ * Contains chart tag information from Factorio's map tags.
+ * When sent from instance to controller: triggers storage for tag history and timelapse.
+ * When sent from controller to web clients: enables real-time tag updates.
+ *
+ * Data flow:
+ * - Lua module -> Instance plugin -> Controller plugin (for persistence)
+ * - Controller plugin -> Web UI plugin -> Tag renderer (for live updates)
+ */
+export class ChartTagDataEvent {
+	declare ["constructor"]: typeof ChartTagDataEvent;
+	static type = "event" as const;
+	static src = ["instance", "controller"] as const;
+	static dst = ["controller", "control"] as const;
+	static plugin = "minimap" as const;
+	static permission = null;
+
+	constructor(
+		public instance_id: number,
+		public tag_data: ChartTagData,
+	) { }
+
+	static jsonSchema = Type.Object({
+		"instance_id": Type.Number(),
+		"tag_data": ChartTagDataSchema,
+	});
+
+	static fromJSON(json: Static<typeof ChartTagDataEvent.jsonSchema>) {
+		return new this(
+			json.instance_id,
+			json.tag_data
+		);
+	}
+}
+
+export class RecipeDataEvent {
+	declare ["constructor"]: typeof RecipeDataEvent;
+	static type = "event" as const;
+	static src = ["instance", "controller"] as const;
+	static dst = ["controller", "control"] as const;
+	static plugin = "minimap" as const;
+	static permission = null;
+
+	constructor(
+		public instance_id: number,
+		public recipe_data: RecipeData,
+	) { }
+
+	static jsonSchema = Type.Object({
+		"instance_id": Type.Number(),
+		"recipe_data": RecipeDataSchema,
+	});
+
+	static fromJSON(json: Static<typeof RecipeDataEvent.jsonSchema>) {
+		return new this(
+			json.instance_id,
+			json.recipe_data
+		);
+	}
+}
+
+/**
+ * GetRawTileRequest: Request raw tile data from controller storage
+ *
+ * Returns base64-encoded tile data that can be processed in timelapse mode
+ * or for initial tile loading when canvas minimap starts up.
+ */
+export class GetRawTileRequest {
+	declare ["constructor"]: typeof GetRawTileRequest;
+	static type = "request" as const;
+	static src = "control" as const;
+	static dst = "controller" as const;
+	static plugin = "minimap" as const;
+	static permission = "minimap.view";
+
+	constructor(
+		public instance_id: number,
+		public surface: string,
+		public force: string,
+		public tile_x: number,
+		public tile_y: number,
+		public tick?: number,
+	) { }
+
+	static jsonSchema = Type.Object({
+		"instance_id": Type.Number(),
+		"surface": Type.String(),
+		"force": Type.String(),
+		"tile_x": Type.Number(),
+		"tile_y": Type.Number(),
+		"tick": Type.Optional(Type.Number()),
+	});
+
+	static fromJSON(json: Static<typeof GetRawTileRequest.jsonSchema>) {
+		return new this(
+			json.instance_id,
+			json.surface,
+			json.force,
+			json.tile_x,
+			json.tile_y,
+			json.tick
+		);
+	}
+
+	static Response = lib.plainJson(Type.Object({
+		"tile_data": Type.Union([Type.String(), Type.Null()]), // Base64 encoded tile file or null if not found
+	}));
+}
+
+export class ClearMinimapSurfaceDataRequest {
+	declare ["constructor"]: typeof ClearMinimapSurfaceDataRequest;
+	static type = "request" as const;
+	static src = "control" as const;
+	static dst = "controller" as const;
+	static plugin = "minimap" as const;
+	static permission = "minimap.manage";
+
+	constructor(
+		public instance_id: number,
+		public surface: string,
+		public force?: string,
+	) { }
+
+	static jsonSchema = Type.Object({
+		"instance_id": Type.Number(),
+		"surface": Type.String(),
+		"force": Type.Optional(Type.String()),
+	});
+
+	static fromJSON(json: Static<typeof ClearMinimapSurfaceDataRequest.jsonSchema>) {
+		return new this(
+			json.instance_id,
+			json.surface,
+			json.force
+		);
+	}
+
+	static Response = lib.plainJson(Type.Object({
+		"success": Type.Boolean(),
+	}));
+}
+
+export class ClearMinimapDataRequest {
+	declare ["constructor"]: typeof ClearMinimapDataRequest;
+	static type = "request" as const;
+	static src = "control" as const;
+	static dst = "controller" as const;
+	static plugin = "minimap" as const;
+	static permission = "minimap.manage";
+
+	static jsonSchema = Type.Object({});
+
+	static fromJSON(_: Static<typeof ClearMinimapDataRequest.jsonSchema>) {
+		return new this();
+	}
+
+	static Response = lib.plainJson(Type.Object({
+		"success": Type.Boolean(),
+	}));
+}
+
+/**
+ * GetChartTagsRequest: Request existing chart tags from controller storage
+ *
+ * Returns all saved chart tags for a specific instance/surface/force combination.
+ * Used to load existing chart tags when the web UI starts up or selection changes.
+ */
+export class GetChartTagsRequest {
+	declare ["constructor"]: typeof GetChartTagsRequest;
+	static type = "request" as const;
+	static src = "control" as const;
+	static dst = "controller" as const;
+	static plugin = "minimap" as const;
+	static permission = "minimap.view";
+
+	constructor(
+		public instance_id: number,
+		public surface: string,
+		public force: string,
+	) { }
+
+	static jsonSchema = Type.Object({
+		"instance_id": Type.Number(),
+		"surface": Type.String(),
+		"force": Type.String(),
+	});
+
+	static fromJSON(json: Static<typeof GetChartTagsRequest.jsonSchema>) {
+		return new this(
+			json.instance_id,
+			json.surface,
+			json.force
+		);
+	}
+
+	static Response = lib.plainJson(Type.Object({
+		"chart_tags": Type.Array(ChartTagDataSchema),
+	}));
+}
+
+export class GetRawRecipeTileRequest {
+	declare ["constructor"]: typeof GetRawRecipeTileRequest;
+	static type = "request" as const;
+	static src = "control" as const;
+	static dst = "controller" as const;
+	static plugin = "minimap" as const;
+	static permission = "minimap.view";
+
+	constructor(
+		public instance_id: number,
+		public surface: string,
+		public force: string,
+		public tile_x: number,
+		public tile_y: number,
+		public tick?: number,
+	) { }
+
+	static jsonSchema = Type.Object({
+		"instance_id": Type.Number(),
+		"surface": Type.String(),
+		"force": Type.String(),
+		"tile_x": Type.Number(),
+		"tile_y": Type.Number(),
+		"tick": Type.Optional(Type.Number()),
+	});
+
+	static fromJSON(json: Static<typeof GetRawRecipeTileRequest.jsonSchema>) {
+		return new this(
+			json.instance_id,
+			json.surface,
+			json.force,
+			json.tile_x,
+			json.tile_y,
+			json.tick
+		);
+	}
+
+	static Response = lib.plainJson(Type.Object({
+		"recipe_tile": Type.Union([Type.String(), Type.Null()]),
+	}));
+}
+
+/**
+ * GetPlayerPathRequest: Request compressed historical player path data from controller storage
+ *
+ * Returns binary compressed player position data for timeline playback.
+ * Used to load player movement history when opening timeline or specific player tracking.
+ */
+export class GetPlayerPathRequest {
+	declare ["constructor"]: typeof GetPlayerPathRequest;
+	static type = "request" as const;
+	static src = "control" as const;
+	static dst = "controller" as const;
+	static plugin = "minimap" as const;
+	static permission = "minimap.view";
+
+	constructor(
+		public instance_id: number,
+		public surface: string,
+	) { }
+
+	static jsonSchema = Type.Object({
+		"instance_id": Type.Number(),
+		"surface": Type.String(),
+	});
+
+	static fromJSON(json: Static<typeof GetPlayerPathRequest.jsonSchema>) {
+		return new this(
+			json.instance_id,
+			json.surface,
+		);
+	}
+
+	static Response = lib.plainJson(Type.Object({
+		"positions": Type.Union([Type.String(), Type.Null()]),
+	}));
+}

plugins/minimap/module/minimap.lua

@@ -0,0 +1,591 @@
+local clusterio_api = require("modules/clusterio/api")
+local compat = require("modules/clusterio/compat")
+
+-- Hot-loop local references for performance
+local math_floor = math.floor
+local bit32_rshift = bit32.rshift
+local table_insert = table.insert
+
+local minimap = {}
+
+-- Convert RGB565 to RGB888 values
+local function rgb565_to_rgb888(rgb565_value)
+	local r = math_floor(bit32_rshift(rgb565_value, 11) * 255 / 31)
+	local g = math_floor(bit32_rshift(bit32.band(rgb565_value, 0x07E0), 5) * 255 / 63)
+	local b = math_floor(bit32.band(rgb565_value, 0x001F) * 255 / 31)
+	return r, g, b
+end
+
+-- Queue a chunk for update
+local function queue_chunk_for_update(chunk_position)
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+
+	-- If the chunk isn't already in the queue, add it
+	for _, queued_chunk in pairs(storage.minimap.chunk_update_queue) do
+		if queued_chunk.x == chunk_position.x and queued_chunk.y == chunk_position.y then
+			return
+		end
+	end
+
+	table.insert(storage.minimap.chunk_update_queue, chunk_position)
+end
+
+-- Send chart tag data to plugin
+local function send_chart_tag_data(tag_data)
+	clusterio_api.send_json("minimap:chart_tag_data", tag_data)
+end
+
+-- Send recipe data to plugin
+local function send_recipe_data(recipe_data)
+	clusterio_api.send_json("minimap:recipe_data", recipe_data)
+end
+
+-- Send player position data to plugin
+local function send_player_position_data(player_data)
+	clusterio_api.send_json("minimap:player_position", player_data)
+end
+
+-- Send player session end data to plugin
+local function send_player_session_end(session_data)
+	clusterio_api.send_json("minimap:player_session_end", session_data)
+end
+
+-- Check if a position has moved significantly (≥1 tile)
+local function has_moved_significantly(old_pos, new_pos)
+	if not old_pos then
+		return true
+	end
+	local dx = math.abs(new_pos.x - old_pos.x)
+	local dy = math.abs(new_pos.y - old_pos.y)
+	return dx >= 1 or dy >= 1
+end
+
+-- Process and send player position updates
+local function process_player_positions()
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+
+	for _, player in pairs(game.connected_players) do
+		if player.valid and player.character and player.character.valid then
+			-- Use physical controller position for accurate tracking when in vehicles/remotes
+			local surface = player.physical_surface
+			local position = player.physical_position
+			local player_key = player.index
+
+			-- Initialize player tracking data if needed
+			if not storage.minimap.player_positions then
+				storage.minimap.player_positions = {}
+			end
+
+		local last_position = storage.minimap.player_positions[player_key]
+		local current_sec = math_floor(game.tick / 60)
+
+			-- Check if position changed significantly or timeout elapsed
+			local should_update = false
+			if not last_position then
+				-- First position for this player
+				should_update = true
+			elseif has_moved_significantly(last_position.position, position) then
+				should_update = true
+			elseif (current_sec - last_position.last_update_sec) >= 5 then
+				-- Send update every 5 seconds even if not moving (for timeout)
+				should_update = true
+			end
+
+			if should_update then
+				local player_data = {
+					player_name = player.name,
+					surface = surface.name,
+					x = position.x,
+					y = position.y,
+					sec = current_sec,
+				}
+
+				send_player_position_data(player_data)
+
+				-- Update tracking data
+				storage.minimap.player_positions[player_key] = {
+					position = { x = position.x, y = position.y },
+					last_update_sec = current_sec,
+				}
+			end
+		end
+	end
+end
+
+-- Handle player session start
+local function on_player_joined_game(event)
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+
+	local player = game.get_player(event.player_index)
+	if not player or not player.valid then
+		return
+	end
+
+	-- Emit session start immediately when player joins using existing player_position channel
+	local surface = player.physical_surface or player.surface
+	local position = player.physical_position or player.position
+	local player_data = {
+		player_name = player.name,
+		surface = surface.name,
+		x = position.x,
+		y = position.y,
+		sec = math_floor(game.tick / 60),
+	}
+	send_player_position_data(player_data)
+
+	-- Clear any existing position data for this player to ensure fresh tracking
+	if storage.minimap.player_positions then
+		storage.minimap.player_positions[player.index] = nil
+	end
+end
+
+-- Handle player session end
+local function on_player_left_game(event)
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+
+	local player = game.get_player(event.player_index)
+	if not player or not player.valid then
+		return
+	end
+
+	send_player_session_end({
+		player_name = player.name,
+		surface = player.surface.name,
+	})
+
+	-- Clean up position tracking data
+	if storage.minimap.player_positions then
+		storage.minimap.player_positions[event.player_index] = nil
+	end
+end
+
+-- Helper for creating and sending recipe start/stop events
+local function update_entity_recipe(entity)
+	if not entity or not entity.valid then
+		return
+	end
+
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+
+	-- Only consider entities that can have recipes
+	local recipe = nil
+	if entity.type == "assembling-machine" then
+		local rec_obj = entity.get_recipe()
+		if rec_obj then
+			recipe = rec_obj.name
+		end
+	elseif entity.type == "furnace" then
+		local prev = entity.previous_recipe
+		if prev and prev.name then
+			-- Factorio furnaces expose previous_recipe with the id nested at previous_recipe.name.name.
+			recipe = prev.name.name
+		end
+	end
+
+	local cache = storage.minimap.recipe_cache
+	local unit_number = entity.unit_number
+	if not unit_number then
+		return -- Cannot track entities without persistent ID
+	end
+
+	local previous = cache[unit_number]
+	if previous and previous.recipe_name == recipe then
+		return -- No change
+	end
+
+	local position = entity.position
+	local data_common = {
+		position = { position.x, position.y },
+		surface = entity.surface.name,
+		force = entity.force.name,
+	}
+
+	-- Close previous recipe if it existed
+	if previous and previous.recipe_name then
+		local end_data = {
+			position = data_common.position,
+			surface = data_common.surface,
+			force = data_common.force,
+			tick = game.tick,
+			recipe = nil,
+		}
+		send_recipe_data(end_data)
+	end
+
+	-- Open new recipe interval if recipe now set
+	if recipe then
+		local icon_signal = nil
+		local recipe_proto = prototypes.recipe[recipe]
+		if recipe_proto and recipe_proto.main_product then
+			icon_signal = { type = recipe_proto.main_product.type, name = recipe_proto.main_product.name }
+		end
+		local start_data = {
+			position = data_common.position,
+			surface = data_common.surface,
+			force = data_common.force,
+			tick = game.tick,
+			recipe = recipe,
+			icon = icon_signal,
+		}
+		send_recipe_data(start_data)
+		cache[unit_number] = { recipe_name = recipe }
+	else
+		-- Recipe cleared
+		cache[unit_number] = nil
+	end
+end
+
+-- Create tag data structure
+local function create_tag_data(tag, start_tick, end_tick)
+	return {
+		tag_number = tag.tag_number,
+		start_tick = start_tick,
+		end_tick = end_tick,
+		force = tag.force.name,
+		surface = tag.surface.name,
+		position = {tag.position.x, tag.position.y},
+		text = tag.text,
+		icon = tag.icon or nil,
+		last_user = tag.last_user and tag.last_user.name or nil
+	}
+end
+
+local function dump_chunk_chart(chunk_position)
+	local data = {}
+	local surfaces = game.surfaces
+	local forces = game.forces
+	for _, force in pairs(forces) do
+		for _, surface in pairs(surfaces) do
+			local chart_data = force.get_chunk_chart(surface, chunk_position)
+			if chart_data then
+				-- Use Factorio's built-in deflate compression and base64 encoding
+				local encoded_data = helpers.encode_string(chart_data)
+				table_insert(data, {surface = surface.name, force = force.name, chart_data = encoded_data})
+			end
+		end
+	end
+
+	-- Calculate world position from chunk position
+	local world_x = chunk_position.x * 32
+	local world_y = chunk_position.y * 32
+
+	-- Send tile data to the plugin
+	clusterio_api.send_json("minimap:tile_data", {
+		type = "chart",
+		position = {world_x, world_y},
+		tick = game.tick,
+		data = data,
+	})
+end
+
+-- Chart tag event handlers
+local function on_chart_tag_added(event)
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+
+	local tag = event.tag
+	if not tag or not tag.valid then
+		return
+	end
+
+	local start_tick = game.tick
+	local tag_data = create_tag_data(tag, start_tick, nil)
+
+	-- Send to plugin
+	send_chart_tag_data(tag_data)
+end
+
+local function on_chart_tag_modified(event)
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+
+	local tag = event.tag
+	if not tag or not tag.valid then
+		return
+	end
+
+	-- End the old version at current tick
+	local end_tick = game.tick
+	local old_tag_data = create_tag_data(tag, nil, end_tick)
+	send_chart_tag_data(old_tag_data)
+
+	-- Create new tag entry starting at next tick
+	local start_tick = game.tick + 1
+	local tag_data = create_tag_data(tag, start_tick, nil)
+
+	-- Send to plugin
+	send_chart_tag_data(tag_data)
+end
+
+local function on_chart_tag_removed(event)
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+
+	local tag = event.tag
+	if not tag or not tag.valid then
+		return
+	end
+
+	-- End the tag
+	local end_tick = game.tick
+	local tag_data = create_tag_data(tag, nil, end_tick)
+	send_chart_tag_data(tag_data)
+end
+
+-- Event handlers
+local function on_chunk_charted(event)
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+
+	-- Convert area to chunk position
+	local chunk_x = math_floor(event.area.left_top.x / 32)
+	local chunk_y = math_floor(event.area.left_top.y / 32)
+
+	queue_chunk_for_update({x = chunk_x, y = chunk_y})
+end
+
+local function on_entity_built(event)
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+
+	if event.created_entity and event.created_entity.valid then
+		local entity = event.created_entity
+		local position = entity.position
+		local chunk_x = math_floor(position.x / 32)
+		local chunk_y = math_floor(position.y / 32)
+
+		queue_chunk_for_update({x = chunk_x, y = chunk_y})
+		-- Track recipe for newly built crafting entities
+		update_entity_recipe(entity)
+	end
+end
+
+local function on_entity_removed(event)
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+
+	if event.entity and event.entity.position then
+		local entity = event.entity
+		local position = entity.position
+		local chunk_x = math_floor(position.x / 32)
+		local chunk_y = math_floor(position.y / 32)
+
+		queue_chunk_for_update({x = chunk_x, y = chunk_y})
+		-- End recipe interval for removed entity
+		update_entity_recipe(entity)
+	end
+end
+
+local function on_tile_changed(event)
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+
+	-- Get unique chunks that were affected
+	local affected_chunks = {}
+	for _, tile in pairs(event.tiles) do
+		local chunk_x = math_floor(tile.position.x / 32)
+		local chunk_y = math_floor(tile.position.y / 32)
+		local chunk_key = chunk_x .. "," .. chunk_y
+
+		if not affected_chunks[chunk_key] then
+			affected_chunks[chunk_key] = {x = chunk_x, y = chunk_y}
+		end
+	end
+
+	-- Update each affected chunk
+	for _, chunk_pos in pairs(affected_chunks) do
+		queue_chunk_for_update(chunk_pos)
+	end
+end
+
+-- Handle recipe change via settings paste
+local function on_entity_settings_pasted(event)
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+	if event.destination and event.destination.valid then
+		update_entity_recipe(event.destination)
+	end
+end
+
+local function on_gui_closed(event)
+    if not storage.minimap or not storage.minimap.enabled then
+        return
+    end
+
+    -- We're only interested in entity GUIs
+    if event.gui_type ~= defines.gui_type.entity then
+        return
+    end
+
+    local entity = event.entity
+    if entity and entity.valid and (entity.type == "assembling-machine" or entity.type == "furnace") then
+        update_entity_recipe(entity)
+    end
+end
+
+-- Initialize the module
+local function init()
+	if not storage.minimap then
+		storage.minimap = {
+			enabled = true,
+			chunk_update_queue = {},
+			recipe_cache = {},
+			player_positions = {}
+		}
+	end
+
+	if not storage.minimap.enabled then
+		return
+	end
+
+	-- Ensure all required fields exist
+	if not storage.minimap.chunk_update_queue then
+		storage.minimap.chunk_update_queue = {}
+	end
+	if not storage.minimap.recipe_cache then
+		storage.minimap.recipe_cache = {}
+	end
+	if not storage.minimap.player_positions then
+		storage.minimap.player_positions = {}
+	end
+
+	-- Clear chunk queue before rebuilding
+	storage.minimap.chunk_update_queue = {}
+
+	-- Queue all existing charted chunks for update
+	local chunks_queued = 0
+
+	for _, force in pairs(game.forces) do
+		for _, surface in pairs(game.surfaces) do
+			-- Iterate through all generated chunks on this surface
+			for chunk in surface.get_chunks() do
+				local chunk_position = {x = chunk.x, y = chunk.y}
+
+				-- Check if this chunk is charted for this force
+				if force.is_chunk_charted(surface, chunk_position) then
+					table_insert(storage.minimap.chunk_update_queue, chunk_position)
+					chunks_queued = chunks_queued + 1
+				end
+			end
+
+		-- Initialize existing chart tags
+		local existing_tags = force.find_chart_tags(surface)
+		for _, tag in pairs(existing_tags) do
+			local start_tick = game.tick
+			local tag_data = create_tag_data(tag, start_tick, nil)
+
+			-- Send to plugin
+			send_chart_tag_data(tag_data)
+		end
+
+			-- Initialize existing crafting recipes on this surface and force
+			local crafting_entities = surface.find_entities_filtered{
+				type = {
+					"assembling-machine",
+					"furnace",
+				}
+			}
+			for _, entity in pairs(crafting_entities) do
+				if entity.valid and entity.force == force then
+					local recipe
+					if entity.type == "assembling-machine" then
+						recipe = entity.get_recipe()
+					elseif entity.type == "furnace" then
+						local prev = entity.previous_recipe
+						if prev and prev.name then
+							recipe = { name = prev.name.name }
+						end
+					end
+					if recipe then
+						local recipe_proto = prototypes.recipe[recipe.name]
+						local icon_signal = nil
+						if recipe_proto and recipe_proto.main_product then
+							icon_signal = { type = recipe_proto.main_product.type, name = recipe_proto.main_product.name }
+						end
+						
+						local data = {
+							position = { entity.position.x, entity.position.y },
+							surface = surface.name,
+							force = force.name,
+							tick = game.tick,
+							recipe = recipe.name,
+							icon = icon_signal,
+						}
+						send_recipe_data(data)
+
+						-- Cache for tracking
+						storage.minimap.recipe_cache[entity.unit_number] = { recipe_name = recipe.name }
+					end
+				end
+			end
+		end
+	end
+end
+
+local function on_tick(event)
+	if not storage.minimap or not storage.minimap.enabled then
+		return
+	end
+
+	-- Process the chunk update queue
+	if #storage.minimap.chunk_update_queue > 0 then
+		local chunk_position = table.remove(storage.minimap.chunk_update_queue, 1)
+		dump_chunk_chart(chunk_position)
+	end
+
+	-- Process player position updates every 250ms (15 ticks at 60 UPS)
+	if game.tick % 15 == 0 then
+		process_player_positions()
+	end
+end
+
+-- Export functions
+minimap.dump_chunk_chart = dump_chunk_chart
+
+minimap.events = {}
+
+-- Ensure this module only loads on Factorio 2.0 or later
+if not compat.version_ge("2.0") then
+	log("[minimap] Minimap plugin disabled - requires Factorio 2.0 or later, current version: " .. (script.active_mods and script.active_mods.base or "unknown"))
+else
+	minimap.events[clusterio_api.events.on_server_startup] = init
+	minimap.events[defines.events.on_tick] = on_tick
+	minimap.events[defines.events.on_chunk_charted] = on_chunk_charted
+	minimap.events[defines.events.on_built_entity] = on_entity_built
+	minimap.events[defines.events.on_robot_built_entity] = on_entity_built
+	minimap.events[defines.events.on_entity_died] = on_entity_removed
+	minimap.events[defines.events.on_player_mined_entity] = on_entity_removed
+	minimap.events[defines.events.on_robot_mined_entity] = on_entity_removed
+	minimap.events[defines.events.on_player_built_tile] = on_tile_changed
+	minimap.events[defines.events.on_robot_built_tile] = on_tile_changed
+	minimap.events[defines.events.on_player_mined_tile] = on_tile_changed
+	minimap.events[defines.events.on_robot_mined_tile] = on_tile_changed
+	minimap.events[defines.events.script_raised_set_tiles] = on_tile_changed
+	minimap.events[defines.events.on_chart_tag_added] = on_chart_tag_added
+	minimap.events[defines.events.on_chart_tag_modified] = on_chart_tag_modified
+	minimap.events[defines.events.on_chart_tag_removed] = on_chart_tag_removed
+	minimap.events[defines.events.on_entity_settings_pasted] = on_entity_settings_pasted
+	minimap.events[defines.events.on_gui_closed] = on_gui_closed
+	minimap.events[defines.events.on_player_joined_game] = on_player_joined_game
+	minimap.events[defines.events.on_player_left_game] = on_player_left_game
+end
+
+return minimap

plugins/minimap/module/module.json

@@ -0,0 +1,4 @@
+{
+	"name": "minimap",
+	"load": ["minimap.lua"]
+} 

plugins/minimap/package.json

@@ -0,0 +1,62 @@
+{
+	"name": "@clusterio/plugin-minimap",
+	"version": "2.0.0-alpha.22b",
+	"description": "Clusterio plugin for displaying interactive minimaps of Factorio instances",
+	"author": "Clusterio Team",
+	"homepage": "https://github.com/clusterio/clusterio#readme",
+	"license": "MIT",
+	"repository": "clusterio/clusterio",
+	"main": "dist/node/index.js",
+	"keywords": [
+		"clusterio",
+		"clusterio-plugin",
+		"factorio",
+		"minimap"
+	],
+	"scripts": {
+		"prepare": "tsc --build && webpack-cli --env production",
+		"watch": "tsc --build --watch",
+		"watch-web": "webpack-cli --env development --watch",
+		"test": "echo \"Error: run tests from root\" && exit 1"
+	},
+	"bugs": {
+		"url": "https://github.com/clusterio/clusterio/issues"
+	},
+	"engines": {
+		"node": ">=20"
+	},
+	"peerDependencies": {
+		"@clusterio/controller": "workspace:*",
+		"@clusterio/web_ui": "workspace:*",
+		"@clusterio/host": "workspace:*",
+		"@clusterio/lib": "workspace:*"
+	},
+	"devDependencies": {
+		"@clusterio/controller": "workspace:*",
+		"@clusterio/lib": "workspace:*",
+		"@clusterio/host": "workspace:*",
+		"@clusterio/web_ui": "workspace:*",
+		"@types/fs-extra": "catalog:",
+		"@types/leaflet": "^1.9.8",
+		"@types/node": "catalog:",
+		"@types/react": "catalog:",
+		"antd": "catalog:",
+		"leaflet": "^1.9.4",
+		"react": "catalog:",
+		"react-dom": "catalog:",
+		"react-leaflet": "^4.2.1",
+		"typescript": "catalog:",
+		"webpack": "catalog:",
+		"webpack-cli": "catalog:",
+		"webpack-merge": "catalog:"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"dependencies": {
+		"@ant-design/icons": "catalog:",
+		"@sinclair/typebox": "catalog:",
+		"fs-extra": "catalog:",
+		"sharp": "^0.33.5"
+	}
+}

plugins/minimap/tsconfig.browser.json

@@ -0,0 +1,16 @@
+{
+	"extends": "../../tsconfig.browser.json",
+	"compilerOptions": {
+		"outDir": "dist/browser"
+	},
+	"include": [
+		"web/**/*",
+		"messages.ts",
+		"utils/tile-utils.ts",
+		"utils/player-utils.ts",
+		"utils/parsing-utils.ts"
+	],
+	"exclude": [
+		"dist/**/*"
+	]
+} 

plugins/minimap/tsconfig.json

@@ -0,0 +1,7 @@
+{
+	"files": [],
+	"references": [
+		{ "path": "./tsconfig.node.json" },
+		{ "path": "./tsconfig.browser.json" }
+	]
+} 

plugins/minimap/tsconfig.node.json

@@ -0,0 +1,10 @@
+{
+	"extends": "../../tsconfig.node.json",
+	"compilerOptions": {
+		"outDir": "dist/node"
+	},
+	"exclude": [
+		"web/**/*",
+		"dist/**/*"
+	]
+} 

plugins/minimap/utils/parsing-utils.ts

@@ -0,0 +1,41 @@
+// Environment detection
+export const isNode = typeof Buffer !== "undefined" && typeof process !== "undefined" && process.versions?.node;
+
+// Cross-platform type for binary data
+export type BinaryData = Buffer | Uint8Array;
+
+// Cross-platform helper functions for reading integers
+export function readUInt8(data: BinaryData, offset: number): number {
+	if (isNode && data instanceof Buffer) {
+		return data.readUInt8(offset);
+	}
+	return (data as Uint8Array)[offset];
+}
+
+export function readUInt16LE(data: BinaryData, offset: number): number {
+	if (isNode && data instanceof Buffer) {
+		return data.readUInt16LE(offset);
+	}
+	const bytes = data as Uint8Array;
+	return bytes[offset] | (bytes[offset + 1] << 8);
+}
+
+export function readUInt16BE(data: BinaryData, offset: number): number {
+	if (isNode && data instanceof Buffer) {
+		return data.readUInt16BE(offset);
+	}
+	const bytes = data as Uint8Array;
+	return (bytes[offset] << 8) | bytes[offset + 1];
+}
+
+export function readUInt32BE(data: BinaryData, offset: number): number {
+	if (isNode && data instanceof Buffer) {
+		return data.readUInt32BE(offset);
+	}
+	const bytes = data as Uint8Array;
+	return (bytes[offset] << 24) | (bytes[offset + 1] << 16) | (bytes[offset + 2] << 8) | bytes[offset + 3];
+}
+
+export function sliceData(data: BinaryData, start: number, end: number): BinaryData {
+	return data.slice(start, end);
+}

plugins/minimap/utils/player-utils.ts

@@ -0,0 +1,315 @@
+import { BinaryData, sliceData, readUInt8, readUInt16BE, readUInt32BE, isNode } from "./parsing-utils";
+
+/**
+ * Parsed player position file data
+ */
+export interface ParsedPlayerPositions {
+    /** Player name -> player ID mappings from SessionStart records */
+	playerSessions: Map<string, number>;
+    /** Maximum player ID found in the file */
+	maxPlayerId: number;
+    /** All position records in the file */
+	positions: PlayerPositionRecord[];
+}
+
+export type PlayerPositionRecord =
+	| PlayerPositionRecordType0
+	| PlayerPositionRecordType1
+	| PlayerPositionRecordType2;
+
+export interface PlayerPositionRecordType0 {
+	type: 0;
+	playerId: number;
+	tSec: number;
+	sec: number;
+	xTiles: number;
+	yTiles: number;
+}
+
+export interface PlayerPositionRecordType1 {
+	type: 1;
+	playerId: number;
+	tMs: number;
+	playerName: string;
+}
+
+export interface PlayerPositionRecordType2 {
+	type: 2;
+	playerId: number;
+	tMs: number;
+}
+
+export interface ParsedPlayerPos {
+	name: string;
+	x: number;
+	y: number;
+	sec: number;
+}
+
+/**
+ * Read a signed 24-bit big-endian integer from binary data
+ * @param buf The binary data buffer
+ * @param offset Offset in the buffer to read from
+ * @returns Signed 24-bit integer value
+ */
+function readSignedInt24(buf: BinaryData, offset: number): number {
+	const unsigned = (readUInt8(buf, offset) << 16) | (readUInt8(buf, offset + 1) << 8) | readUInt8(buf, offset + 2);
+	return unsigned > 0x7FFFFF ? unsigned - 0x1000000 : unsigned;
+}
+
+/**
+ * Parse binary player position file data
+ * @param buf Binary player position data
+ * @returns Parsed player position data with sessions and records
+ */
+export function parsePlayerPositionsBinary(buf: BinaryData): ParsedPlayerPositions {
+	const playerSessions = new Map<string, number>();
+	const positions: PlayerPositionRecord[] = [];
+	let maxPlayerId = 0;
+	let offset = 0;
+
+	while (offset < buf.length) {
+		if (offset + 1 > buf.length) { break; }
+
+		const type = readUInt8(buf, offset);
+		offset += 1;
+
+		if (type === 0) {
+			// Position record
+			const result = parsePositionRecord(buf, offset);
+			if (!result.success) { break; }
+
+			const record: PlayerPositionRecordType0 = {
+				type: 0,
+				...result.record,
+			};
+
+			positions.push(record);
+			if (result.record.playerId > maxPlayerId) {
+				maxPlayerId = result.record.playerId;
+			}
+			offset = result.newOffset;
+
+		} else if (type === 1) {
+			// SessionStart record
+			const result = parseSessionStartRecord(buf, offset);
+			if (!result.success) { break; }
+
+			const record: PlayerPositionRecordType1 = {
+				type: 1,
+				...result.record,
+			};
+
+			positions.push(record);
+			playerSessions.set(result.record.playerName, result.record.playerId);
+			if (result.record.playerId > maxPlayerId) {
+				maxPlayerId = result.record.playerId;
+			}
+			offset = result.newOffset;
+
+		} else if (type === 2) {
+			// SessionEnd record
+			const result = parseSessionEndRecord(buf, offset);
+			if (!result.success) { break; }
+
+			const record: PlayerPositionRecordType2 = {
+				type: 2,
+				...result.record,
+			};
+
+			positions.push(record);
+			if (result.record.playerId > maxPlayerId) {
+				maxPlayerId = result.record.playerId;
+			}
+			offset = result.newOffset;
+
+		} else {
+			// Unknown record type, can't continue parsing safely
+			break;
+		}
+	}
+
+	return { playerSessions, maxPlayerId, positions };
+}
+
+type PositionRecordParseResult =
+	| { success: false; newOffset: number }
+	| { success: true; newOffset: number; record: Omit<PlayerPositionRecordType0, "type"> };
+
+/**
+ * Parse position record from player position file
+ * @param buf The binary player position data
+ * @param offset Current offset in the data
+ * @returns Processing result with position data and new offset
+ */
+function parsePositionRecord(buf: BinaryData, offset: number): PositionRecordParseResult {
+	// Position record: 4 + 4 + 3 + 3 + 2 = 16 bytes
+	if (offset + 16 > buf.length) {
+		return { success: false, newOffset: offset };
+	}
+
+	const tSec = readUInt32BE(buf, offset);
+	offset += 4;
+	const sec = readUInt32BE(buf, offset);
+	offset += 4;
+
+	const xTiles = readSignedInt24(buf, offset);
+	offset += 3;
+
+	const yTiles = readSignedInt24(buf, offset);
+	offset += 3;
+
+	const playerId = readUInt16BE(buf, offset);
+	offset += 2;
+
+	return { success: true, newOffset: offset, record: { playerId, tSec, sec, xTiles, yTiles } };
+}
+
+type SessionStartRecordParseResult =
+	| { success: false; newOffset: number }
+	| { success: true; newOffset: number; record: Omit<PlayerPositionRecordType1, "type"> };
+
+/**
+ * Parse SessionStart record from player position file
+ * @param buf The binary player position data
+ * @param offset Current offset in the data
+ * @returns Processing result with session data and new offset
+ */
+function parseSessionStartRecord(
+	buf: BinaryData,
+	offset: number
+): SessionStartRecordParseResult {
+	// SessionStart record: 4 + 2 + 1 + n = 7 + n bytes minimum
+	if (offset + 7 > buf.length) {
+		return { success: false, newOffset: offset };
+	}
+
+	const tMs = readUInt32BE(buf, offset);
+	offset += 4;
+	const playerId = readUInt16BE(buf, offset);
+	offset += 2;
+	const nameLen = readUInt8(buf, offset);
+	offset += 1;
+
+	if (offset + nameLen > buf.length) {
+		return { success: false, newOffset: offset };
+	}
+
+	const nameBytes = sliceData(buf, offset, offset + nameLen);
+	offset += nameLen;
+
+	// Convert to string using cross-platform method
+	let playerName: string;
+	if (isNode && nameBytes instanceof Buffer) {
+		playerName = nameBytes.toString("utf-8");
+	} else {
+		playerName = new TextDecoder().decode(nameBytes as Uint8Array);
+	}
+
+	return { success: true, newOffset: offset, record: { playerId, tMs, playerName } };
+}
+
+type SessionEndRecordParseResult =
+	| { success: false; newOffset: number }
+	| { success: true; newOffset: number; record: Omit<PlayerPositionRecordType2, "type"> };
+
+/**
+ * Parse SessionEnd record from player position file
+ * @param buf The binary player position data
+ * @param offset Current offset in the data
+ * @returns Processing result with session data and new offset
+ */
+function parseSessionEndRecord(
+	buf: BinaryData,
+	offset: number
+): SessionEndRecordParseResult {
+	// SessionEnd record: 4 + 2 = 6 bytes
+	if (offset + 6 > buf.length) {
+		return { success: false, newOffset: offset };
+	}
+
+	const tMs = readUInt32BE(buf, offset);
+	offset += 4;
+	const playerId = readUInt16BE(buf, offset);
+	offset += 2;
+
+	return { success: true, newOffset: offset, record: { playerId, tMs } };
+}
+
+/**
+ * Parse and deduplicate player positions from binary data
+ * @param buf Binary player position data
+ * @returns Map of player ID to deduplicated position timeline
+ */
+export function parseAndDeduplicatePlayerPositions(buf: BinaryData): Map<number, ParsedPlayerPos[]> {
+	// Use the utility function to parse the binary data
+	const parsed: ParsedPlayerPositions = parsePlayerPositionsBinary(buf);
+
+	// Build player timelines from the parsed data
+	const playerTimelines = new Map<number, ParsedPlayerPos[]>();
+	const playerNameById = new Map<number, string>();
+	for (const [name, id] of parsed.playerSessions) {
+		playerNameById.set(id, name);
+	}
+
+	// Process all records in order
+	for (const record of parsed.positions) {
+		if (record.type === 0) {
+			// Position record - convert tile coordinates to world coordinates
+			const name = playerNameById.get(record.playerId);
+			if (!name) {
+				continue;
+			}
+
+			if (!playerTimelines.has(record.playerId)) {
+				playerTimelines.set(record.playerId, []);
+			}
+
+			// Convert from tiles to world coordinates (tiles are 32x32 world coordinates)
+			const x = record.xTiles * 32;
+			const y = record.yTiles * 32;
+
+			playerTimelines.get(record.playerId)!.push({
+				name,
+				x,
+				y,
+				sec: record.sec,
+			});
+		}
+	}
+
+	// Deduplicate consecutive identical positions for each player
+	const deduplicatedTimelines = new Map<number, ParsedPlayerPos[]>();
+
+	for (const [playerId, timeline] of playerTimelines) {
+		if (timeline.length === 0) { continue; }
+
+		const deduplicated: ParsedPlayerPos[] = [];
+		let lastPos = timeline[0];
+		deduplicated.push(lastPos);
+
+		for (let i = 1; i < timeline.length; i++) {
+			const currentPos = timeline[i];
+
+			// Check if position changed (with small tolerance for floating point)
+			const deltaX = Math.abs(currentPos.x - lastPos.x);
+			const deltaY = Math.abs(currentPos.y - lastPos.y);
+
+			if (deltaX > 4 || deltaY > 4) {
+				// Position changed significantly, keep this point
+				deduplicated.push(currentPos);
+				lastPos = currentPos;
+			}
+			// If position is the same, skip this point (deduplication)
+		}
+
+		// Always keep the last position to ensure timeline ends correctly
+		if (timeline.length > 1 && deduplicated[deduplicated.length - 1] !== timeline[timeline.length - 1]) {
+			deduplicated.push(timeline[timeline.length - 1]);
+		}
+
+		deduplicatedTimelines.set(playerId, deduplicated);
+	}
+
+	return deduplicatedTimelines;
+}

plugins/minimap/utils/tile-utils.ts

@@ -0,0 +1,871 @@
+import { BinaryData, sliceData, readUInt8, readUInt16LE, readUInt16BE, readUInt32BE, isNode } from "./parsing-utils";
+import * as zlib from "zlib";
+
+// Cross-platform decompression
+async function inflateData(data: BinaryData): Promise<Buffer | Uint8Array> {
+	if (isNode) {
+		// Node.js environment - use promisified inflate
+		const { promisify } = await import("util");
+		const inflateAsync = promisify(zlib.inflate);
+		return inflateAsync(data as Buffer);
+	}
+	// Browser environment - use promisified inflate
+	return new Promise((resolve, reject) => {
+		try {
+			const buffer = data instanceof Buffer ? data : Buffer.from(data);
+			zlib.inflate(buffer, (err, result) => {
+				if (err) {
+					reject(err);
+				} else {
+					resolve(result);
+				}
+			});
+		} catch (err) {
+			reject(err);
+		}
+	});
+}
+
+/**
+ * Convert RGB565 to RGB888 values using Factorio's exact method
+ * @param rgb565Value The RGB565 color value to convert
+ * @returns Tuple of RGB values [r, g, b]
+ */
+export function rgb565ToRgb888(rgb565Value: number): [number, number, number] {
+	// This matches ByteColor(uint16_t rgb5) constructor in Factorio source
+	const r = ((rgb565Value >> 11) & 0x1F) << 3; // 5 bits -> 8 bits
+	const g = ((rgb565Value >> 5) & 0x3F) << 2; // 6 bits -> 8 bits
+	const b = (rgb565Value & 0x1F) << 3; // 5 bits -> 8 bits
+	return [r, g, b];
+}
+
+/**
+ * Render chunk data to get RGB565 pixel array
+ * @param chunkData The compressed chunk data to render
+ * @returns RGB565 pixel array for 32x32 chunk
+ */
+export async function renderChunkToPixels(chunkData: BinaryData): Promise<Uint16Array> {
+	try {
+		const decompressed = await inflateData(chunkData);
+		const pixels = new Uint16Array(32 * 32);
+
+		// Ensure we don't read beyond available data
+		const maxPixels = Math.min(decompressed.length / 2, 32 * 32);
+
+		for (let i = 0; i < maxPixels; i++) {
+			pixels[i] = readUInt16LE(decompressed, i * 2);
+		}
+
+		// Fill remaining pixels with black (0) if we have less data than expected
+		for (let i = maxPixels; i < 32 * 32; i++) {
+			pixels[i] = 0;
+		}
+
+		return pixels;
+	} catch (decompressError) {
+		// Log warning before falling back to black pixels
+		console.warn(`Failed to decompress chunk data: ${decompressError}`);
+		// Return black pixels on error
+		return new Uint16Array(32 * 32);
+	}
+}
+
+/**
+ * Extract a 32x32 chunk area from a 256x256 tile
+ * @param tilePixels The full tile pixel data
+ * @param chunkX Chunk X coordinate within tile
+ * @param chunkY Chunk Y coordinate within tile
+ * @returns RGB565 pixel array for 32x32 chunk
+ */
+export function extractChunkFromTile(tilePixels: Uint16Array, chunkX: number, chunkY: number): Uint16Array {
+	const chunkPixels = new Uint16Array(32 * 32);
+
+	for (let y = 0; y < 32; y++) {
+		for (let x = 0; x < 32; x++) {
+			const tileX = chunkX * 32 + x;
+			const tileY = chunkY * 32 + y;
+			const tileIndex = tileY * 256 + tileX;
+			const chunkIndex = y * 32 + x;
+			chunkPixels[chunkIndex] = tilePixels[tileIndex];
+		}
+	}
+
+	return chunkPixels;
+}
+
+/**
+ * Render tile data to RGB565 pixel array (256x256)
+ * Supports rendering up to a specific tick for timelapse functionality
+ * @param tileData The binary tile data to render
+ * @param maxTick Optional maximum tick to render up to
+ * @returns RGB565 pixel array for 256x256 tile
+ */
+export async function renderTileToPixels(tileData: BinaryData, maxTick?: number): Promise<Uint16Array> {
+	const currentPixels = new Uint16Array(256 * 256); // 256x256 tile
+
+	let offset = 0;
+	while (offset < tileData.length) {
+		if (offset + 1 > tileData.length) {
+			break;
+		}
+
+		const type = readUInt8(tileData, offset);
+		offset += 1;
+
+		if (type === 1) { // Chunk
+			const chunkResult = await processChunkData(
+				tileData, offset, currentPixels, maxTick
+			);
+			if (!chunkResult.success) {
+				break;
+			}
+			offset = chunkResult.newOffset;
+		} else if (type === 2) { // Pixels
+			const pixelResult = processPixelData(tileData, offset, currentPixels, maxTick);
+			if (!pixelResult.success) {
+				break;
+			}
+			offset = pixelResult.newOffset;
+		} else {
+			break;
+		}
+	}
+
+	return currentPixels;
+}
+
+/**
+ * Process chunk data during tile rendering
+ * @param tileData The binary tile data being processed
+ * @param offset Current offset in the tile data
+ * @param currentPixels The pixel array to update
+ * @param maxTick Optional maximum tick to render up to
+ * @returns Processing result with success status and new offset
+ */
+async function processChunkData(
+	tileData: BinaryData,
+	offset: number,
+	currentPixels: Uint16Array,
+	maxTick?: number
+): Promise<{ success: boolean; newOffset: number }> {
+	if (offset + 7 > tileData.length) {
+		return { success: false, newOffset: offset };
+	}
+
+	const tick = readUInt32BE(tileData, offset) * 60; // Convert back to actual tick
+	offset += 4;
+
+	// Break early if this record is beyond our target tick (append-only optimization)
+	if (maxTick !== undefined && tick > maxTick) {
+		return { success: false, newOffset: offset - 4 };
+	}
+
+	const chunkCoordsByte = readUInt8(tileData, offset);
+	offset += 1;
+	const length = readUInt16BE(tileData, offset);
+	offset += 2;
+
+	if (offset + length > tileData.length) {
+		return { success: false, newOffset: offset };
+	}
+
+	const chunkX = chunkCoordsByte >> 4;
+	const chunkY = chunkCoordsByte & 0x0F;
+	const chunkData = sliceData(tileData, offset, offset + length);
+
+	try {
+		const chunkPixels = await renderChunkToPixels(chunkData);
+
+		// Update current pixel state
+		updateTilePixelsWithChunk(currentPixels, chunkPixels, chunkX, chunkY);
+	} catch (decompressError) {
+		// Continue processing other chunks on error
+	}
+
+	return { success: true, newOffset: offset + length };
+}
+
+/**
+ * Process pixel data during tile rendering
+ * @param tileData The binary tile data being processed
+ * @param offset Current offset in the tile data
+ * @param currentPixels The pixel array to update
+ * @param maxTick Optional maximum tick to render up to
+ * @returns Processing result with success status and new offset
+ */
+function processPixelData(
+	tileData: BinaryData,
+	offset: number,
+	currentPixels: Uint16Array,
+	maxTick?: number
+): { success: boolean; newOffset: number } {
+	if (offset + 10 > tileData.length) {
+		return { success: false, newOffset: offset };
+	}
+
+	const tick = readUInt32BE(tileData, offset) * 60; // Convert back to actual tick
+	offset += 4;
+	const pixelCount = readUInt16BE(tileData, offset);
+	offset += 2;
+	const newColor = readUInt16BE(tileData, offset);
+	offset += 2;
+	const oldColor = readUInt16BE(tileData, offset);
+	offset += 2;
+
+	const expectedDataLength = pixelCount * 2; // x,y per pixel
+	if (offset + expectedDataLength > tileData.length) {
+		return { success: false, newOffset: offset };
+	}
+
+	// Break early if this record is beyond our target tick (append-only optimization)
+	if (maxTick !== undefined && tick > maxTick) {
+		return { success: false, newOffset: offset - 4 };
+	}
+
+	for (let i = 0; i < pixelCount; i++) {
+		const pixelOffset = offset + i * 2;
+		const x = readUInt8(tileData, pixelOffset);
+		const y = readUInt8(tileData, pixelOffset + 1);
+		if (x < 256 && y < 256) {
+			currentPixels[y * 256 + x] = newColor;
+		}
+	}
+
+	return { success: true, newOffset: offset + expectedDataLength };
+}
+
+/**
+ * Update tile pixels with chunk data
+ * @param currentPixels The tile pixel array to update
+ * @param chunkPixels The chunk pixel data to apply
+ * @param chunkX Chunk X coordinate within tile
+ * @param chunkY Chunk Y coordinate within tile
+ */
+function updateTilePixelsWithChunk(
+	currentPixels: Uint16Array,
+	chunkPixels: Uint16Array,
+	chunkX: number,
+	chunkY: number
+): void {
+	for (let y = 0; y < 32; y++) {
+		for (let x = 0; x < 32; x++) {
+			const chunkIndex = y * 32 + x;
+			const tileX = chunkX * 32 + x;
+			const tileY = chunkY * 32 + y;
+			const tileIndex = tileY * 256 + tileX;
+			currentPixels[tileIndex] = chunkPixels[chunkIndex];
+		}
+	}
+}
+
+/**
+ * Convert RGB565 pixel array to RGBA pixel data for canvas rendering
+ * Returns Uint8ClampedArray that can be used to create ImageData in browser
+ * @param pixels The RGB565 pixel array to convert
+ * @returns RGBA pixel data as Uint8ClampedArray
+ */
+export function pixelsToRGBA(pixels: Uint16Array): Uint8ClampedArray {
+	const imageData = new Uint8ClampedArray(256 * 256 * 4);
+
+	for (let i = 0; i < 256 * 256; i++) {
+		const rgb565Value = pixels[i];
+		const [r, g, b] = rgb565ToRgb888(rgb565Value);
+		const bufferIndex = i * 4;
+
+		imageData[bufferIndex] = r;
+		imageData[bufferIndex + 1] = g;
+		imageData[bufferIndex + 2] = b;
+		imageData[bufferIndex + 3] = 255; // Alpha
+	}
+
+	return imageData;
+}
+
+/**
+ * Convert RGB565 pixel array to ImageData for canvas rendering (browser only)
+ * @param pixels The RGB565 pixel array to convert
+ * @returns ImageData object for canvas rendering
+ */
+export function pixelsToImageData(pixels: Uint16Array): any {
+	if (typeof (globalThis as any).ImageData === "undefined") {
+		throw new Error("ImageData is not available in this environment. Use pixelsToRGBA() instead.");
+	}
+	const rgbaData = pixelsToRGBA(pixels);
+	return new (globalThis as any).ImageData(rgbaData, 256, 256);
+}
+
+/**
+ * Parse tile data and extract all available ticks for timelapse functionality
+ * @param tileData The binary tile data to parse
+ * @returns Array of available ticks sorted in ascending order
+ */
+export function extractAvailableTicks(tileData: BinaryData): number[] {
+	const ticks = new Set<number>();
+
+	let offset = 0;
+	while (offset < tileData.length) {
+		if (offset + 1 > tileData.length) {
+			break;
+		}
+
+		const type = readUInt8(tileData, offset);
+		offset += 1;
+
+		if (type === 1) { // Chunk
+			if (offset + 7 > tileData.length) {
+				break;
+			}
+
+			const tick = readUInt32BE(tileData, offset) * 60; // Convert back to actual tick
+			ticks.add(tick);
+			offset += 4;
+
+			const chunkCoordsByte = readUInt8(tileData, offset);
+			offset += 1;
+			const length = readUInt16BE(tileData, offset);
+			offset += 2;
+			if (offset + length > tileData.length) {
+				break;
+			}
+			offset += length; // Skip chunk data
+		} else if (type === 2) { // Pixels
+			if (offset + 10 > tileData.length) {
+				break;
+			}
+
+			const tick = readUInt32BE(tileData, offset) * 60; // Convert back to actual tick
+			ticks.add(tick);
+			offset += 4;
+
+			const pixelCount = readUInt16BE(tileData, offset);
+			offset += 2 + 2 + 2; // skip newColor oldColor too
+			const expectedDataLength = pixelCount * 2;
+			if (offset + expectedDataLength > tileData.length) {
+				break;
+			}
+
+			offset += expectedDataLength;
+		} else {
+			break;
+		}
+	}
+
+	return Array.from(ticks).sort((a, b) => a - b);
+}
+
+/**
+ * Interface for tracking pixel changes in timelapse data
+ */
+export interface PixelChange {
+	x: number;
+	y: number;
+	newColor: number;
+	oldColor: number;
+}
+
+/**
+ * Interface for chunk records in timelapse data
+ */
+export interface ChunkRecord {
+	tick: number;
+	chunkX: number;
+	chunkY: number;
+	data: BinaryData;
+}
+
+/**
+ * Interface for pixel change records in timelapse data
+ */
+export interface PixelChangeRecord {
+	tick: number;
+	changes: PixelChange[];
+}
+
+/**
+ * Interface for parsed tile data with all change records
+ */
+export interface ParsedTileData {
+	chunks: ChunkRecord[];
+	pixelChanges: PixelChangeRecord[];
+	allTicks: number[];
+}
+
+/**
+ * Parse tile data into structured change records for efficient timelapse navigation
+ * @param tileData The binary tile data to parse
+ * @returns Parsed tile data with chunks, pixel changes, and all ticks
+ */
+export function parseTileData(tileData: BinaryData): ParsedTileData {
+	const chunks: ChunkRecord[] = [];
+	const pixelChanges: PixelChangeRecord[] = [];
+	const ticks = new Set<number>();
+
+	let offset = 0;
+	while (offset < tileData.length) {
+		if (offset + 1 > tileData.length) {
+			break;
+		}
+
+		const type = readUInt8(tileData, offset);
+		offset += 1;
+
+		if (type === 1) { // Chunk
+			const result = parseChunkRecord(tileData, offset, chunks, ticks);
+			if (!result.success) {
+				break;
+			}
+			offset = result.newOffset;
+		} else if (type === 2) { // Pixels
+			const result = parsePixelChangeRecord(tileData, offset, pixelChanges, ticks);
+			if (!result.success) {
+				break;
+			}
+			offset = result.newOffset;
+		} else {
+			break;
+		}
+	}
+
+	return {
+		chunks,
+		pixelChanges,
+		allTicks: Array.from(ticks).sort((a, b) => a - b),
+	};
+}
+
+export interface ParsedChunkDataRecord {
+	tick: number;
+	chunkX: number;
+	chunkY: number;
+	data: BinaryData;
+}
+
+export interface ParsedPixelDataRecord {
+	tick: number;
+	pixelCount: number;
+	newColor: number;
+	oldColor: number;
+	pixelDataOffset: number;
+}
+
+export type ParseRecordResult<T> =
+	| { success: false; newOffset: number }
+	| { success: true; newOffset: number; record: T };
+
+export function parseChunkDataRecord(
+	tileData: BinaryData,
+	offset: number
+): ParseRecordResult<ParsedChunkDataRecord> {
+	if (offset + 7 > tileData.length) {
+		return { success: false, newOffset: offset };
+	}
+
+	const tick = readUInt32BE(tileData, offset);
+	offset += 4;
+	const chunkCoordsByte = readUInt8(tileData, offset);
+	offset += 1;
+	const length = readUInt16BE(tileData, offset);
+	offset += 2;
+
+	if (offset + length > tileData.length) {
+		return { success: false, newOffset: offset };
+	}
+
+	const chunkX = chunkCoordsByte >> 4;
+	const chunkY = chunkCoordsByte & 0x0F;
+	const data = sliceData(tileData, offset, offset + length);
+
+	return {
+		success: true,
+		newOffset: offset + length,
+		record: { tick, chunkX, chunkY, data },
+	};
+}
+
+export function parsePixelDataRecord(
+	tileData: BinaryData,
+	offset: number
+): ParseRecordResult<ParsedPixelDataRecord> {
+	if (offset + 10 > tileData.length) {
+		return { success: false, newOffset: offset };
+	}
+
+	const tick = readUInt32BE(tileData, offset);
+	offset += 4;
+	const pixelCount = readUInt16BE(tileData, offset);
+	offset += 2;
+	const newColor = readUInt16BE(tileData, offset);
+	offset += 2;
+	const oldColor = readUInt16BE(tileData, offset);
+	offset += 2;
+
+	const pixelDataLength = pixelCount * 2;
+	if (offset + pixelDataLength > tileData.length) {
+		return { success: false, newOffset: offset };
+	}
+
+	return {
+		success: true,
+		newOffset: offset + pixelDataLength,
+		record: {
+			tick,
+			pixelCount,
+			newColor,
+			oldColor,
+			pixelDataOffset: offset,
+		},
+	};
+}
+
+/**
+ * Parse chunk record from tile data
+ * @param tileData The binary tile data being processed
+ * @param offset Current offset in the tile data
+ * @param chunks Array to add the parsed chunk to
+ * @param ticks Set to add the chunk tick to
+ * @returns Processing result with success status and new offset
+ */
+function parseChunkRecord(
+	tileData: BinaryData,
+	offset: number,
+	chunks: ChunkRecord[],
+	ticks: Set<number>
+): { success: boolean; newOffset: number } {
+	const parsed = parseChunkDataRecord(tileData, offset);
+	if (!parsed.success) {
+		return parsed;
+	}
+
+	const tick = parsed.record.tick * 60; // Convert back to actual tick
+	ticks.add(tick);
+
+	chunks.push({
+		tick,
+		chunkX: parsed.record.chunkX,
+		chunkY: parsed.record.chunkY,
+		data: parsed.record.data,
+	});
+
+	return { success: true, newOffset: parsed.newOffset };
+}
+
+/**
+ * Parse pixel change record from tile data
+ * @param tileData The binary tile data being processed
+ * @param offset Current offset in the tile data
+ * @param pixelChanges Array to add the parsed pixel changes to
+ * @param ticks Set to add the pixel change tick to
+ * @returns Processing result with success status and new offset
+ */
+function parsePixelChangeRecord(
+	tileData: BinaryData,
+	offset: number,
+	pixelChanges: PixelChangeRecord[],
+	ticks: Set<number>
+): { success: boolean; newOffset: number } {
+	const parsed = parsePixelDataRecord(tileData, offset);
+	if (!parsed.success) {
+		return parsed;
+	}
+
+	const tick = parsed.record.tick * 60; // Convert back to actual tick
+	ticks.add(tick);
+
+	const changes: PixelChange[] = [];
+	for (let i = 0; i < parsed.record.pixelCount; i++) {
+		const pixelOffset = parsed.record.pixelDataOffset + i * 2;
+		const x = readUInt8(tileData, pixelOffset);
+		const y = readUInt8(tileData, pixelOffset + 1);
+		changes.push({ x, y, newColor: parsed.record.newColor, oldColor: parsed.record.oldColor });
+	}
+
+	pixelChanges.push({ tick, changes });
+	return { success: true, newOffset: parsed.newOffset };
+}
+
+/**
+ * Apply chunk data to RGB565 pixel array
+ * @param pixels The tile pixel array to update
+ * @param chunkRecord The chunk record to apply
+ */
+export async function applyChunkToPixels(pixels: Uint16Array, chunkRecord: ChunkRecord): Promise<void> {
+	try {
+		const chunkPixels = await renderChunkToPixels(chunkRecord.data);
+		updateTilePixelsWithChunk(pixels, chunkPixels, chunkRecord.chunkX, chunkRecord.chunkY);
+	} catch (err) {
+		// Error applying chunk - continue without this chunk
+	}
+}
+
+/**
+ * Clear chunk area to black (for rewinding past chunk creation)
+ * @param pixels The tile pixel array to update
+ * @param chunkRecord The chunk record to clear
+ */
+export function clearChunkInPixels(pixels: Uint16Array, chunkRecord: ChunkRecord): void {
+	for (let y = 0; y < 32; y++) {
+		for (let x = 0; x < 32; x++) {
+			const tileX = chunkRecord.chunkX * 32 + x;
+			const tileY = chunkRecord.chunkY * 32 + y;
+			const tileIndex = tileY * 256 + tileX;
+			pixels[tileIndex] = 0; // Black
+		}
+	}
+}
+
+/**
+ * Apply pixel changes to RGB565 pixel array (forward direction)
+ * @param pixels The tile pixel array to update
+ * @param changes Array of pixel changes to apply
+ */
+export function applyPixelChanges(pixels: Uint16Array, changes: PixelChange[]): void {
+	for (const change of changes) {
+		const tileIndex = change.y * 256 + change.x;
+		pixels[tileIndex] = change.newColor;
+	}
+}
+
+/**
+ * Revert pixel changes from RGB565 pixel array (backward direction)
+ * @param pixels The tile pixel array to update
+ * @param changes Array of pixel changes to revert
+ */
+export function revertPixelChanges(pixels: Uint16Array, changes: PixelChange[]): void {
+	for (const change of changes) {
+		const tileIndex = change.y * 256 + change.x;
+		pixels[tileIndex] = change.oldColor;
+	}
+}
+
+/**
+ * Render tile data incrementally from one tick to another
+ * Much more efficient than re-rendering from scratch
+ * @param parsedData The parsed tile data
+ * @param currentPixels The current pixel state
+ * @param fromTick The starting tick
+ * @param toTick The target tick
+ */
+export async function renderTileIncremental(
+	parsedData: ParsedTileData,
+	currentPixels: Uint16Array,
+	fromTick: number,
+	toTick: number
+): Promise<void> {
+	const { chunks, pixelChanges } = parsedData;
+
+	if (fromTick === toTick) {
+		return; // No changes needed
+	}
+
+	const forward = toTick > fromTick;
+
+	if (forward) {
+		await applyChangesForward(chunks, pixelChanges, currentPixels, fromTick, toTick);
+	} else {
+		await applyChangesBackward(chunks, pixelChanges, currentPixels, fromTick, toTick);
+	}
+}
+
+/**
+ * Apply changes in forward direction
+ * @param chunks Array of chunk records to process
+ * @param pixelChanges Array of pixel change records to process
+ * @param currentPixels The pixel array to update
+ * @param fromTick The starting tick
+ * @param toTick The target tick
+ */
+async function applyChangesForward(
+	chunks: ChunkRecord[],
+	pixelChanges: PixelChangeRecord[],
+	currentPixels: Uint16Array,
+	fromTick: number,
+	toTick: number
+): Promise<void> {
+	// Apply chunks that occur in this range
+	for (const chunk of chunks) {
+		if (chunk.tick > fromTick && chunk.tick <= toTick) {
+			await applyChunkToPixels(currentPixels, chunk);
+		}
+	}
+
+	// Apply pixel changes that occur in this range
+	for (const record of pixelChanges) {
+		if (record.tick > fromTick && record.tick <= toTick) {
+			applyPixelChanges(currentPixels, record.changes);
+		}
+	}
+}
+
+/**
+ * Apply changes in backward direction
+ * @param chunks Array of chunk records to process
+ * @param pixelChanges Array of pixel change records to process
+ * @param currentPixels The pixel array to update
+ * @param fromTick The starting tick
+ * @param toTick The target tick
+ */
+async function applyChangesBackward(
+	chunks: ChunkRecord[],
+	pixelChanges: PixelChangeRecord[],
+	currentPixels: Uint16Array,
+	fromTick: number,
+	toTick: number
+): Promise<void> {
+	// Revert pixel changes in reverse order
+	for (let i = pixelChanges.length - 1; i >= 0; i--) {
+		const record = pixelChanges[i];
+		if (record.tick <= fromTick && record.tick > toTick) {
+			revertPixelChanges(currentPixels, record.changes);
+		}
+	}
+
+	// Revert chunks (clear to black if we're going before their creation time)
+	for (let i = chunks.length - 1; i >= 0; i--) {
+		const chunk = chunks[i];
+		if (chunk.tick <= fromTick && chunk.tick > toTick) {
+			clearChunkInPixels(currentPixels, chunk);
+		}
+	}
+}
+
+/**
+ * Interface for parsed recipe tile data
+ */
+export interface ParsedRecipeTile {
+	ticks: number[]; // ticks present in this tile
+	activeRecipes: Map<string, string>; // posKey -> recipeName
+	dictionary: Map<number, string>; // id -> recipeName
+}
+
+/**
+ * Parse binary recipe tile data and return timeline ticks and active recipes at target tick
+ * @param tileX Tile X coordinate for world position calculation
+ * @param tileY Tile Y coordinate for world position calculation
+ * @param buf Binary recipe tile data
+ * @param targetTick Target tick for filtering (null = latest state)
+ * @returns Parsed recipe data with ticks and active recipes
+ */
+export function parseRecipeTileBinary(
+	tileX: number,
+	tileY: number,
+	buf: BinaryData,
+	targetTick: number | null
+): ParsedRecipeTile {
+	const ticks: number[] = [];
+	const dict = new Map<number, string>();
+	const active = new Map<string, string>();
+	const targetSec = targetTick !== null ? Math.floor(targetTick / 60) : Infinity;
+
+	let offset = 0;
+	while (offset < buf.length) {
+		const type = readUInt8(buf, offset);
+		offset += 1;
+
+		if (type === 0) { // Dictionary entry
+			const result = parseDictionaryEntry(buf, offset, dict);
+			offset = result.newOffset;
+		} else if (type === 1 || type === 2) { // Set recipe (1) or Clear recipe (2)
+			const result = parseRecipeEntry(
+				buf, offset, type, tileX, tileY, ticks, active, targetSec, dict
+			);
+			offset = result.newOffset;
+		} else {
+			// Unknown recipe record type - stop parsing
+			break;
+		}
+	}
+
+	return { ticks, activeRecipes: active, dictionary: dict };
+}
+
+/**
+ * Parse dictionary entry from recipe tile
+ * @param buf The binary recipe tile data
+ * @param offset Current offset in the data
+ * @param dict Dictionary map to add the entry to
+ * @returns Processing result with new offset
+ */
+function parseDictionaryEntry(
+	buf: BinaryData,
+	offset: number,
+	dict: Map<number, string>
+): { newOffset: number } {
+	const idx = readUInt16BE(buf, offset);
+	offset += 2;
+	const len = readUInt8(buf, offset);
+	offset += 1;
+	const nameBytes = sliceData(buf, offset, offset + len);
+	offset += len;
+
+	// Convert to string using cross-platform method
+	let recipeName: string;
+	if (isNode && nameBytes instanceof Buffer) {
+		recipeName = nameBytes.toString("utf-8");
+	} else {
+		recipeName = new TextDecoder().decode(nameBytes as Uint8Array);
+	}
+
+	dict.set(idx, recipeName);
+	return { newOffset: offset };
+}
+
+/**
+ * Parse recipe entry from recipe tile
+ * @param buf The binary recipe tile data
+ * @param offset Current offset in the data
+ * @param type Entry type (1 = set recipe, 2 = clear recipe)
+ * @param tileX Tile X coordinate for world position calculation
+ * @param tileY Tile Y coordinate for world position calculation
+ * @param ticks Array to add the entry tick to
+ * @param active Map of active recipes to update
+ * @param targetSec Target second for filtering
+ * @param dict Dictionary map for recipe name lookup
+ * @returns Processing result with new offset
+ */
+function parseRecipeEntry(
+	buf: BinaryData,
+	offset: number,
+	type: number,
+	tileX: number,
+	tileY: number,
+	ticks: number[],
+	active: Map<string, string>,
+	targetSec: number,
+	dict: Map<number, string>
+): { newOffset: number } {
+	const sec = readUInt32BE(buf, offset);
+	offset += 4;
+	const px = readUInt8(buf, offset);
+	offset += 1;
+	const py = readUInt8(buf, offset);
+	offset += 1;
+
+	let idx: number | undefined;
+	if (type === 1) {
+		idx = readUInt16BE(buf, offset);
+		offset += 2;
+	}
+
+	const tickVal = sec * 60;
+	ticks.push(tickVal);
+
+	if (sec > targetSec) {
+		// Future to target time – skip without applying
+		return { newOffset: offset };
+	}
+
+	const worldX = tileX * 256 + px;
+	const worldY = tileY * 256 + py;
+	const posKey = `${worldX},${worldY}`;
+
+	if (type === 1 && idx !== undefined) {
+		const name = dict.get(idx);
+		if (name) {
+			active.set(posKey, name);
+		}
+	} else if (type === 2) {
+		active.delete(posKey);
+	}
+
+	return { newOffset: offset };
+}

plugins/minimap/web/dataSources/SingleInstanceDataSource.ts

@@ -0,0 +1,199 @@
+import type { Control } from "@clusterio/web_ui";
+import {
+	GetChartTagsRequest,
+	GetPlayerPathRequest,
+	GetRawRecipeTileRequest,
+	GetRawTileRequest,
+	type TileDataEvent,
+	type ChartTagDataEvent,
+	type RecipeDataEvent,
+	type PlayerPositionEvent,
+} from "../../messages";
+import type {
+	ChartTagDataWithInstance,
+	MinimapActiveView,
+	MinimapDataSource,
+	MinimapViewBounds,
+} from "../minimap-data-source";
+
+interface MinimapWebPlugin {
+	// Dual filter API: plural version accepts array (flexible), singular version is a convenience wrapper.
+	// Both exist for backward compatibility with different plugin implementations (check plural first, then singular).
+	setInstanceSurfaceFilters?(filters: Array<{ instanceId: number; surface: string }> | null): Promise<void> | void;
+	setInstanceSurfaceFilter?(instanceId: number | null, surface: string | null): Promise<void> | void;
+	onTileUpdate(callback: (event: TileDataEvent) => void): void;
+	offTileUpdate(callback: (event: TileDataEvent) => void): void;
+	onChartTagUpdate(callback: (event: ChartTagDataEvent) => void): void;
+	offChartTagUpdate(callback: (event: ChartTagDataEvent) => void): void;
+	onRecipeUpdate(callback: (event: RecipeDataEvent) => void): void;
+	offRecipeUpdate(callback: (event: RecipeDataEvent) => void): void;
+	onPlayerPositionUpdate(callback: (event: PlayerPositionEvent) => void): void;
+	offPlayerPositionUpdate(callback: (event: PlayerPositionEvent) => void): void;
+}
+
+const decodeBase64ToBytes = (base64: string): Uint8Array => {
+	const binary = atob(base64);
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) {
+		bytes[i] = binary.charCodeAt(i);
+	}
+	return bytes;
+};
+
+export class SingleInstanceDataSource implements MinimapDataSource {
+	private control: Control;
+	private plugin: MinimapWebPlugin | null = null;
+	private instanceId: number | null = null;
+	private surface = "nauvis";
+	private force = "player";
+	private activeInstances: number[] = [];
+
+	/**
+	 * Data source for the canvas renderer that reads minimap data for a single selected instance.
+	 *
+	 * This bridges selection state to the minimap web plugin and keeps subscription filters in sync.
+	 */
+	constructor(control: Control) {
+		this.control = control;
+		this.plugin = control.plugins.get("minimap") as MinimapWebPlugin | undefined ?? null;
+	}
+
+	setInstance(instanceId: number | null): void {
+		this.instanceId = instanceId;
+		this.updateFilters();
+	}
+
+	setSurfaceForce(surface: string, force: string): void {
+		this.surface = surface;
+		this.force = force;
+		this.updateFilters();
+	}
+
+	setActiveView(_bounds: MinimapViewBounds): MinimapActiveView {
+		const nextActive = this.instanceId !== null ? [this.instanceId] : [];
+		const changed = nextActive.length !== this.activeInstances.length
+			|| nextActive.some((id, index) => id !== this.activeInstances[index]);
+		if (changed) {
+			this.activeInstances = nextActive;
+		}
+		return { changed, activeInstanceIds: [...this.activeInstances] };
+	}
+
+	isReady(): boolean {
+		return this.instanceId !== null;
+	}
+
+	async getTileData(tileX: number, tileY: number, tick?: number | null): Promise<Uint8Array | null> {
+		if (this.instanceId === null) {
+			return null;
+		}
+		const response = await this.control.send(new GetRawTileRequest(
+			this.instanceId,
+			this.surface,
+			this.force,
+			tileX,
+			tileY,
+			tick ?? undefined,
+		));
+		if (!response.tile_data) {
+			return null;
+		}
+		return decodeBase64ToBytes(response.tile_data);
+	}
+
+	async getRecipeTileData(tileX: number, tileY: number, tick?: number | null): Promise<Uint8Array | null> {
+		if (this.instanceId === null) {
+			return null;
+		}
+		const response = await this.control.send(new GetRawRecipeTileRequest(
+			this.instanceId,
+			this.surface,
+			this.force,
+			tileX,
+			tileY,
+			tick ?? undefined,
+		));
+		if (!response.recipe_tile) {
+			return null;
+		}
+		return decodeBase64ToBytes(response.recipe_tile);
+	}
+
+	async getChartTags(): Promise<ChartTagDataWithInstance[]> {
+		if (this.instanceId === null) {
+			return [];
+		}
+		const response = await this.control.send(new GetChartTagsRequest(
+			this.instanceId,
+			this.surface,
+			this.force,
+		));
+		return response.chart_tags.map(tag => ({
+			...tag,
+			instance_id: this.instanceId as number,
+		}));
+	}
+
+	async getPlayerPaths(): Promise<Array<{ instanceId: number; data: Uint8Array }>> {
+		if (this.instanceId === null) {
+			return [];
+		}
+		const response = await this.control.send(new GetPlayerPathRequest(
+			this.instanceId,
+			this.surface,
+		));
+		if (!response.positions) {
+			return [];
+		}
+		return [{ instanceId: this.instanceId, data: decodeBase64ToBytes(response.positions) }];
+	}
+
+	onTileUpdate(callback: (event: TileDataEvent) => void): () => void {
+		this.plugin?.onTileUpdate(callback);
+		return () => {
+			this.plugin?.offTileUpdate(callback);
+		};
+	}
+
+	onChartTagUpdate(callback: (event: ChartTagDataEvent) => void): () => void {
+		this.plugin?.onChartTagUpdate(callback);
+		return () => {
+			this.plugin?.offChartTagUpdate(callback);
+		};
+	}
+
+	onRecipeUpdate(callback: (event: RecipeDataEvent) => void): () => void {
+		this.plugin?.onRecipeUpdate(callback);
+		return () => {
+			this.plugin?.offRecipeUpdate(callback);
+		};
+	}
+
+	onPlayerPositionUpdate(callback: (event: PlayerPositionEvent) => void): () => void {
+		this.plugin?.onPlayerPositionUpdate(callback);
+		return () => {
+			this.plugin?.offPlayerPositionUpdate(callback);
+		};
+	}
+
+	private updateFilters() {
+		if (!this.plugin) {
+			return;
+		}
+		if (this.instanceId === null) {
+			if (this.plugin.setInstanceSurfaceFilters) {
+				this.plugin.setInstanceSurfaceFilters(null);
+			} else if (this.plugin.setInstanceSurfaceFilter) {
+				this.plugin.setInstanceSurfaceFilter(null, null);
+			}
+			return;
+		}
+		const filters = [{ instanceId: this.instanceId, surface: this.surface }];
+		// Support both the newer multi-filter API and the legacy single-filter API.
+		if (this.plugin.setInstanceSurfaceFilters) {
+			this.plugin.setInstanceSurfaceFilters(filters);
+		} else if (this.plugin.setInstanceSurfaceFilter) {
+			this.plugin.setInstanceSurfaceFilter(this.instanceId, this.surface);
+		}
+	}
+}

plugins/minimap/web/index.tsx

@@ -0,0 +1,221 @@
+import React from "react";
+import { BaseWebPlugin } from "@clusterio/web_ui";
+import * as lib from "@clusterio/lib";
+import CanvasMinimapPage from "./CanvasMinimapPage";
+export { default as CanvasMinimapPage } from "./CanvasMinimapPage";
+export { SingleInstanceDataSource } from "./dataSources/SingleInstanceDataSource";
+export type {
+	ChartTagDataWithInstance,
+	MinimapActiveView,
+	MinimapDataSource,
+	MinimapViewBounds,
+} from "./minimap-data-source";
+export {
+	GetRawTileRequest,
+	GetRawRecipeTileRequest,
+	GetChartTagsRequest,
+	GetPlayerPathRequest,
+} from "../messages";
+import { TileDataEvent, ChartTagDataEvent, RecipeDataEvent, PlayerPositionEvent } from "../messages";
+
+export class WebPlugin extends BaseWebPlugin {
+	// Callback arrays for minimap updates
+	tileUpdateCallbacks: Array<(event: TileDataEvent) => void> = [];
+	chartTagUpdateCallbacks: Array<(event: ChartTagDataEvent) => void> = [];
+	recipeUpdateCallbacks: Array<(event: RecipeDataEvent) => void> = [];
+	playerPositionUpdateCallbacks: Array<(event: PlayerPositionEvent) => void> = [];
+
+	// Track subscription state
+	private subscribed = false;
+	private currentFilters: string[] | undefined = undefined;
+
+	async init() {
+		this.pages = [
+			{
+				path: "/minimap",
+				sidebarName: "Minimap",
+				permission: "minimap.view",
+				content: <CanvasMinimapPage />,
+			},
+		];
+
+		// Handle minimap events from the controller
+		this.control.handle(TileDataEvent, this.handleTileDataEvent.bind(this));
+		this.control.handle(ChartTagDataEvent, this.handleChartTagDataEvent.bind(this));
+		this.control.handle(RecipeDataEvent, this.handleRecipeDataEvent.bind(this));
+		this.control.handle(PlayerPositionEvent, this.handlePlayerPositionEvent.bind(this));
+	}
+
+	onControllerConnectionEvent(event: "connect" | "drop" | "resume" | "close") {
+		if (event === "connect" || event === "resume") {
+			this.updateSubscriptions();
+		}
+	}
+
+	// Update instance/surface filters used for subscriptions.
+	async setInstanceSurfaceFilters(filters: Array<{ instanceId: number; surface: string }> | null) {
+		const newFilters = filters && filters.length > 0
+			? filters.map(filter => `${filter.instanceId}:${filter.surface}`)
+			: undefined;
+
+		// No change
+		const prev = this.currentFilters;
+		const same = (
+			(prev === undefined && newFilters === undefined)
+			|| (Array.isArray(prev) && Array.isArray(newFilters)
+				&& prev.length === newFilters.length
+				&& prev.every((v, i) => v === newFilters[i]))
+		);
+		if (same) { return; }
+
+		// If we had previous filters and callbacks active, remove those filters first
+		if (this.hasActiveCallbacks() && prev && prev.length > 0) {
+			try {
+				await this.control.send(new lib.SubscriptionRequest("minimap:TileDataEvent", false, 0, prev));
+				await this.control.send(new lib.SubscriptionRequest("minimap:ChartTagDataEvent", false, 0, prev));
+				await this.control.send(new lib.SubscriptionRequest("minimap:RecipeDataEvent", false, 0, prev));
+				await this.control.send(new lib.SubscriptionRequest("minimap:PlayerPositionEvent", false, 0, prev));
+			} catch (err) {
+				this.logger.error(`Failed to remove previous minimap filters: ${err}`);
+			}
+		}
+
+		this.currentFilters = newFilters;
+
+		// Apply new filters if we have active callbacks
+		if (this.hasActiveCallbacks()) {
+			await this.updateSubscriptions();
+		}
+	}
+
+	// Update instance/surface filter used for subscriptions.
+	async setInstanceSurfaceFilter(instanceId: number | null, surface: string | null) {
+		await this.setInstanceSurfaceFilters(
+			instanceId !== null && surface
+				? [{ instanceId, surface }]
+				: null,
+		);
+	}
+
+	private async updateSubscriptions() {
+		if (!this.control.connector.connected) {
+			return;
+		}
+
+		const shouldSubscribe = this.hasActiveCallbacks();
+
+		// Only subscribe if we both have active callbacks and a specific filter set
+		if (shouldSubscribe && this.currentFilters && this.currentFilters.length > 0) {
+			// Always (re)send with current filters when we have active callbacks
+			const filters = this.currentFilters;
+			try {
+				await this.control.send(new lib.SubscriptionRequest("minimap:TileDataEvent", true, 0, filters));
+				await this.control.send(new lib.SubscriptionRequest("minimap:ChartTagDataEvent", true, 0, filters));
+				await this.control.send(new lib.SubscriptionRequest("minimap:RecipeDataEvent", true, 0, filters));
+				await this.control.send(new lib.SubscriptionRequest("minimap:PlayerPositionEvent", true, 0, filters));
+				this.subscribed = true;
+			} catch (err) {
+				this.logger.error(`Failed to subscribe to minimap events: ${err}`);
+			}
+		} else if ((!shouldSubscribe || !this.currentFilters || this.currentFilters.length === 0) && this.subscribed) {
+			// Unsubscribe from all minimap events
+			try {
+				await this.control.send(new lib.SubscriptionRequest("minimap:TileDataEvent", false));
+				await this.control.send(new lib.SubscriptionRequest("minimap:ChartTagDataEvent", false));
+				await this.control.send(new lib.SubscriptionRequest("minimap:RecipeDataEvent", false));
+				await this.control.send(new lib.SubscriptionRequest("minimap:PlayerPositionEvent", false));
+				this.subscribed = false;
+			} catch (err) {
+				this.logger.error(`Failed to unsubscribe from minimap events: ${err}`);
+			}
+		}
+	}
+
+	private hasActiveCallbacks(): boolean {
+		return this.tileUpdateCallbacks.length > 0
+			|| this.chartTagUpdateCallbacks.length > 0
+			|| this.recipeUpdateCallbacks.length > 0
+			|| this.playerPositionUpdateCallbacks.length > 0;
+	}
+
+	async handleTileDataEvent(event: TileDataEvent) {
+		// Notify all registered callbacks
+		for (let callback of this.tileUpdateCallbacks) {
+			callback(event);
+		}
+	}
+
+	async handleChartTagDataEvent(event: ChartTagDataEvent) {
+		for (let callback of this.chartTagUpdateCallbacks) {
+			callback(event);
+		}
+	}
+
+	async handleRecipeDataEvent(event: RecipeDataEvent) {
+		for (let callback of this.recipeUpdateCallbacks) {
+			callback(event);
+		}
+	}
+
+	async handlePlayerPositionEvent(event: PlayerPositionEvent) {
+		for (let callback of this.playerPositionUpdateCallbacks) {
+			callback(event);
+		}
+	}
+
+	onTileUpdate(callback: (event: TileDataEvent) => void) {
+		this.tileUpdateCallbacks.push(callback);
+		this.updateSubscriptions();
+	}
+
+	offTileUpdate(callback: (event: TileDataEvent) => void) {
+		let index = this.tileUpdateCallbacks.lastIndexOf(callback);
+		if (index === -1) {
+			throw new Error("callback is not registered");
+		}
+		this.tileUpdateCallbacks.splice(index, 1);
+		this.updateSubscriptions();
+	}
+
+	onChartTagUpdate(callback: (event: ChartTagDataEvent) => void) {
+		this.chartTagUpdateCallbacks.push(callback);
+		this.updateSubscriptions();
+	}
+
+	offChartTagUpdate(callback: (event: ChartTagDataEvent) => void) {
+		let index = this.chartTagUpdateCallbacks.lastIndexOf(callback);
+		if (index === -1) {
+			throw new Error("callback is not registered");
+		}
+		this.chartTagUpdateCallbacks.splice(index, 1);
+		this.updateSubscriptions();
+	}
+
+	onRecipeUpdate(callback: (event: RecipeDataEvent) => void) {
+		this.recipeUpdateCallbacks.push(callback);
+		this.updateSubscriptions();
+	}
+
+	offRecipeUpdate(callback: (event: RecipeDataEvent) => void) {
+		const index = this.recipeUpdateCallbacks.lastIndexOf(callback);
+		if (index === -1) {
+			throw new Error("callback is not registered");
+		}
+		this.recipeUpdateCallbacks.splice(index, 1);
+		this.updateSubscriptions();
+	}
+
+	onPlayerPositionUpdate(callback: (event: PlayerPositionEvent) => void) {
+		this.playerPositionUpdateCallbacks.push(callback);
+		this.updateSubscriptions();
+	}
+
+	offPlayerPositionUpdate(callback: (event: PlayerPositionEvent) => void) {
+		const index = this.playerPositionUpdateCallbacks.lastIndexOf(callback);
+		if (index === -1) {
+			throw new Error("callback is not registered");
+		}
+		this.playerPositionUpdateCallbacks.splice(index, 1);
+		this.updateSubscriptions();
+	}
+}

plugins/minimap/web/minimap-data-source.ts

@@ -0,0 +1,38 @@
+import type {
+	ChartTagData,
+	ChartTagDataEvent,
+	PlayerPositionEvent,
+	RecipeDataEvent,
+	TileDataEvent,
+} from "../messages";
+
+export interface ChartTagDataWithInstance extends ChartTagData {
+	instance_id: number;
+}
+
+export interface MinimapViewBounds {
+	worldLeft: number;
+	worldTop: number;
+	worldRight: number;
+	worldBottom: number;
+}
+
+export interface MinimapActiveView {
+	changed: boolean;
+	activeInstanceIds: number[];
+}
+
+export interface MinimapDataSource {
+	setInstance?(instanceId: number | null): void;
+	setSurfaceForce(surface: string, force: string): void;
+	setActiveView(bounds: MinimapViewBounds): MinimapActiveView;
+	isReady(): boolean;
+	getTileData(tileX: number, tileY: number, tick?: number | null): Promise<Uint8Array | null>;
+	getRecipeTileData(tileX: number, tileY: number, tick?: number | null): Promise<Uint8Array | null>;
+	getChartTags(): Promise<ChartTagDataWithInstance[]>;
+	getPlayerPaths(): Promise<Array<{ instanceId: number; data: Uint8Array }>>;
+	onTileUpdate(callback: (event: TileDataEvent) => void): () => void;
+	onChartTagUpdate(callback: (event: ChartTagDataEvent) => void): () => void;
+	onRecipeUpdate(callback: (event: RecipeDataEvent) => void): () => void;
+	onPlayerPositionUpdate(callback: (event: PlayerPositionEvent) => void): () => void;
+}

plugins/minimap/webpack.config.js

@@ -0,0 +1,36 @@
+"use strict";
+const path = require("path");
+const webpack = require("webpack");
+const { merge } = require("webpack-merge");
+
+
+const common = require("@clusterio/web_ui/webpack.common");
+
+module.exports = (env = {}) => merge(common(env), {
+	context: __dirname,
+	entry: "./web/index.tsx",
+	output: {
+		path: path.resolve(__dirname, "dist", "web"),
+	},
+	plugins: [
+		new webpack.container.ModuleFederationPlugin({
+			name: "minimap",
+			library: { type: "var", name: "plugin_minimap" },
+			exposes: {
+				"./": "./index.ts",
+				"./package.json": "./package.json",
+				"./web": "./web/index.tsx",
+			},
+			shared: {
+				"@clusterio/lib": { import: false },
+				"@clusterio/web_ui": { import: false },
+				"antd": { import: false },
+				"react": { import: false },
+				"react-dom": { import: false },
+			},
+		}),
+	],
+	optimization: {
+		chunkIds: "named",
+	},
+});