Add exp_roles plugin to sync roles from the controller

Clusterio already stores roles, the permissions they grant, and which user holds
which role, along with a web UI for all three. What it does not have is the
properties a role only needs in game, or a way for an instance to learn about
any of it, since role and user updates are only sent to control connections.

This plugin fills both gaps. The controller keeps a record per role holding the
order, priority, short hand, tag, colour and auto assign threshold, created
automatically for any role which does not have one. It then rebroadcasts roles
and assignments on its own events so instances can follow them.

The lua module presents the same interface the legacy expcore.roles module did,
so the call sites can be moved over without being rewritten. Permission checks
translate the legacy action strings using the same mapping exp_scenario defines.

Two things replace features the legacy system had:

- Priority replaces disallow. Only the roles with the highest priority a player
  holds are considered, so Jail can suppress every other role including the
  default one, without needing to take roles away first.
- Assignments made in game are applied locally and then sent to the controller,
  which keeps assign_player synchronous for callers. A role which should never
  leave this map, such as one earned from time on the map, is assigned with
  assign_player_local instead.

Roles earned from online time across the cluster are granted by the controller
from the threshold on the role, using the online time clusterio already tracks.

Nothing requires this plugin yet; moving the call sites off expcore.roles and
removing the legacy config is left for a follow up.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

exp_roles/instance.ts

@@ -0,0 +1,104 @@
+import { BaseInstancePlugin } from "@clusterio/host";
+import * as lib from "@clusterio/lib";
+import * as messages from "./messages";
+
+/** Sent by the lua side when roles are changed in game. */
+export type IpcAssignmentUpdate = {
+	name: string,
+	assign: number[] | undefined,
+	unassign: number[] | undefined,
+};
+
+export class InstancePlugin extends BaseInstancePlugin {
+	async init() {
+		this.instance.handle(messages.RoleUpdatedEvent, this.handleRoleUpdatedEvent.bind(this));
+		this.instance.handle(messages.AssignmentUpdatedEvent, this.handleAssignmentUpdatedEvent.bind(this));
+		this.instance.server.handle("exp_roles:assignment_update", this.handleAssignmentUpdateIPC.bind(this));
+	}
+
+	get syncMode() {
+		return this.instance.config.get("exp_roles.sync_mode");
+	}
+
+	async onInstanceConfigFieldChanged(field: string, curr: unknown, prev: unknown) {
+		switch (field) {
+			case "exp_roles.sync_mode":
+				await this.luaSetEmitEvents(curr === "bidirectional");
+				break;
+		}
+	}
+
+	async onStart() {
+		if (this.syncMode === "disabled") {
+			return;
+		}
+
+		// Date.now() is used because the lua state is initialised from the full
+		// list below, so only updates made after this point are of interest
+		const subscribedAtMs = Date.now();
+		await this.instance.sendTo("controller", new lib.SubscriptionRequest(
+			`exp_roles:${messages.RoleUpdatedEvent.name}`, true, subscribedAtMs
+		));
+		await this.instance.sendTo("controller", new lib.SubscriptionRequest(
+			`exp_roles:${messages.AssignmentUpdatedEvent.name}`, true, subscribedAtMs
+		));
+
+		const [roles, assignments] = await Promise.all([
+			this.instance.sendTo("controller", new messages.RoleListRequest()),
+			this.instance.sendTo("controller", new messages.AssignmentListRequest()),
+		]);
+
+		await this.luaSend("initialise", {
+			roles: roles.map(role => role.toJSON()),
+			assignments: assignments.map(assignment => assignment.toJSON()),
+		});
+		await this.luaSetEmitEvents(this.syncMode === "bidirectional");
+	}
+
+	async handleRoleUpdatedEvent(event: messages.RoleUpdatedEvent) {
+		if (this.syncMode === "disabled") {
+			return;
+		}
+
+		await this.luaSend("receive_role_updates", event.updates.map(role => role.toJSON()));
+	}
+
+	async handleAssignmentUpdatedEvent(event: messages.AssignmentUpdatedEvent) {
+		if (this.syncMode === "disabled") {
+			return;
+		}
+
+		await this.luaSend("receive_assignment_updates", event.updates.map(a => a.toJSON()));
+	}
+
+	async handleAssignmentUpdateIPC(event: IpcAssignmentUpdate) {
+		if (this.syncMode !== "bidirectional") {
+			return;
+		}
+
+		const assign = event.assign ?? [];
+		try {
+			await this.instance.sendTo("controller", new messages.AssignmentUpdateRequest(
+				event.name, assign, event.unassign ?? [],
+			));
+		} catch (err: any) {
+			// The roles were already applied in game, so they have to be taken
+			// back off again now that the controller has refused them
+			this.logger.warn(`Role change for ${event.name} was rejected: ${err.message}`);
+			if (assign.length) {
+				await this.luaSend("reject_assignment", { name: event.name, role_ids: assign });
+			}
+			return;
+		}
+	}
+
+	async luaSetEmitEvents(emitEvents: boolean) {
+		await this.luaSend("set_emit_events", emitEvents);
+	}
+
+	async luaSend(receiver: string, json: any) {
+		await this.instance.sendRcon(
+			`/sc exp_roles.${receiver}(helpers.json_to_table[=[${JSON.stringify(json)}]=])`, true
+		);
+	}
+}