Move the seed into exp_scenario and seed the permission groups (#457)

The seed roles were owned by exp_roles, but they describe the scenario, so
they now live in exp_scenario/seed.ts next to the permissions they grant.
Each seed role names the permission group its holders belong to, and the
five groups the legacy config defined (Admin, Trusted, Standard, Guest,
Restricted) are seeded through exp_groups along with one role mapping per
role. Mapping priorities follow how exp_roles ranks a player's highest
role, so Jail lands in Restricted regardless of other roles.

SeedRolesRequest becomes exp_scenario's SeedRequest behind a new
exp_scenario.seed permission, and the button moves to the scenario's web
plugin, which gets a web entrypoint for it. exp_roles no longer depends on
exp_scenario, and exp_scenario gains controller tests around the seed.

With groups seeded from the controller the legacy expcore.permission_groups
module and its config are removed, along with the Group rcon static.

exp_scenario/controller.ts

@@ -1,6 +1,157 @@
 import * as lib from "@clusterio/lib";
 import { BaseControllerPlugin } from "@clusterio/controller";
+import type { ControllerPlugin as RolesPlugin } from "@expcluster/roles/dist/node/controller";
+import type { ControllerPlugin as GroupsPlugin } from "@expcluster/permission-groups/dist/node/controller";
+import { RoleMetaRecord } from "@expcluster/roles/dist/node/messages";
+import { GroupRecord, GroupPermissions, RoleMappingRecord } from "@expcluster/permission-groups/dist/node/messages";
+import * as messages from "./messages";
+import { SeedRole, SeedGroup, seedRoles, seedGroups, flattenSeedPermissions } from "./seed";
 
 export class ControllerPlugin extends BaseControllerPlugin {
+	async init() {
+		this.controller.handle(messages.SeedRequest, this.handleSeedRequest.bind(this));
+	}
 
+	/**
+	 * Create the roles and permission groups the scenario shipped with.
+	 *
+	 * Roles which already exist by name are reused and only gain the seed
+	 * permissions, groups which already exist by name are reset to the seed.
+	 */
+	async handleSeedRequest() {
+		const rolesPlugin = this.controller.plugins.get("exp_roles") as RolesPlugin | undefined;
+		const groupsPlugin = this.controller.plugins.get("exp_groups") as GroupsPlugin | undefined;
+		if (!rolesPlugin || !groupsPlugin) {
+			throw new lib.RequestError("Seeding requires the exp_roles and exp_groups plugins");
+		}
+
+		const roleIds = new Map<string, number>();
+		for (const [index, seedRole] of seedRoles.entries()) {
+			const role = this.seedRole(seedRole);
+			if (!role) {
+				continue;
+			}
+
+			roleIds.set(seedRole.name, role.id);
+			rolesPlugin.roleMeta.set(new RoleMetaRecord(
+				role.id,
+				index + 1,
+				seedRole.priority ?? 0,
+				seedRole.shortHand,
+				"",
+				seedRole.color,
+				seedRole.autoAssignHours === undefined ? null : seedRole.autoAssignHours * 3600000,
+				seedRole.blockAutoAssign ?? false,
+			));
+		}
+
+		const groupIds = new Map<string, number>();
+		for (const seedGroup of seedGroups) {
+			groupIds.set(seedGroup.name, this.seedGroup(groupsPlugin, seedGroup).id);
+		}
+
+		this.seedRoleMappings(groupsPlugin, roleIds, groupIds);
+		this.logger.info(`Seeded ${roleIds.size} roles and ${groupIds.size} permission groups`);
+	}
+
+	/** Find or create the clusterio role for a seed role, returns undefined if it has no role to use. */
+	seedRole(seedRole: SeedRole) {
+		const roles = this.controller.roles;
+		if (seedRole.isAdmin) {
+			return roles.get(lib.Role.DefaultAdminRoleId);
+		}
+		if (seedRole.isDefault) {
+			const defaultRoleId = this.controller.config.get("controller.default_role_id");
+			return defaultRoleId !== null ? roles.get(defaultRoleId) : undefined;
+		}
+
+		const permissions = flattenSeedPermissions(seedRole);
+		for (const permission of permissions) {
+			if (!lib.permissions.has(permission)) {
+				this.logger.warn(`Seed role ${seedRole.name} grants unknown permission ${permission}`);
+			}
+		}
+
+		let role = [...roles.valuesMutable()].find(other => other.name === seedRole.name);
+		if (role) {
+			for (const permission of permissions) {
+				role.permissions.add(permission);
+			}
+		} else {
+			const id = Math.max(5, ...[...roles.keys()].map(other => other + 1));
+			role = new lib.Role(id, seedRole.name, "", permissions);
+			this.logger.info(`Created role ${seedRole.name}`);
+		}
+		roles.set(role);
+		return role;
+	}
+
+	/** Find or create the permission group for a seed group. */
+	seedGroup(groupsPlugin: GroupsPlugin, seedGroup: SeedGroup) {
+		const permissions = new GroupPermissions(seedGroup.isBlacklist, [...seedGroup.inputActions]);
+		const existing = [...groupsPlugin.groups.values()].find(other => other.name === seedGroup.name);
+		const group = new GroupRecord(existing?.id ?? newId(groupsPlugin.groups), seedGroup.name, permissions);
+		if (!existing) {
+			this.logger.info(`Created permission group ${seedGroup.name}`);
+		}
+		groupsPlugin.groups.set(group);
+		return group;
+	}
+
+	/**
+	 * Map each seed role onto its seed group.
+	 *
+	 * The mapping with the highest priority decides a player's group, so the
+	 * priorities follow how exp_roles picks a player's highest role: role
+	 * priority first, then the role order.
+	 */
+	seedRoleMappings(groupsPlugin: GroupsPlugin, roleIds: Map<string, number>, groupIds: Map<string, number>) {
+		// Lowest role first, so the mapping priority rises with the role
+		const ranked = seedRoles
+			.filter(seedRole => seedRole.group !== undefined && roleIds.has(seedRole.name))
+			.reverse()
+			.sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+		const seededRoleIds = new Set(ranked.map(seedRole => roleIds.get(seedRole.name)!));
+
+		// A mapping of a single seed role is reused, every other mapping keeps its priority
+		const existing = new Map<number, RoleMappingRecord>();
+		const taken = new Set<number>();
+		for (const mapping of groupsPlugin.roleMappings.values()) {
+			const [roleId] = mapping.roleIds;
+			if (mapping.roleIds.size === 1 && seededRoleIds.has(roleId)) {
+				existing.set(roleId, mapping);
+			} else {
+				taken.add(mapping.priority);
+			}
+		}
+
+		const mappings = [];
+		let priority = 0;
+		for (const seedRole of ranked) {
+			priority += 1;
+			while (taken.has(priority)) {
+				priority += 1;
+			}
+
+			const roleId = roleIds.get(seedRole.name)!;
+			mappings.push(new RoleMappingRecord(
+				existing.get(roleId)?.id ?? newId(groupsPlugin.roleMappings),
+				new Set([roleId]),
+				groupIds.get(seedRole.group!)!,
+				priority,
+				true,
+			));
+		}
+
+		groupsPlugin.roleMappings.setMany(mappings);
+		return mappings;
+	}
+}
+
+function newId(datastore: { has(id: number): boolean }) {
+	let id = Math.random() * 2 ** 31 | 0;
+	while (datastore.has(id)) {
+		id = Math.random() * 2 ** 31 | 0;
+	}
+	return id;
 }

exp_scenario/index.ts

@@ -1,5 +1,5 @@
 import * as lib from "@clusterio/lib";
-// import * as Messages from "./messages";
+import * as messages from "./messages";
 
 // Defines a permission for every in game action and role flag used by the scenario
 import "./permissions";
@@ -16,6 +16,12 @@ lib.definePermission({
 	description: "Edit the config for all submodules of ExpScenario",
 });
 
+lib.definePermission({
+	name: "exp_scenario.seed",
+	title: "Seed ExpScenario roles and groups",
+	description: "Create the roles and permission groups the scenario shipped with",
+});
+
 declare module "@clusterio/lib" {
 
 }
@@ -27,13 +33,9 @@ export const plugin: lib.PluginDeclaration = {
 	controllerEntrypoint: "./dist/node/controller",
 	instanceEntrypoint: "./dist/node/instance",
 
-	/*
 	messages: [
+		messages.SeedRequest,
 	],
 
 	webEntrypoint: "./web",
-	routes: [
-		"/exp_scenario",
-	],
-	*/
 };

exp_scenario/messages.ts

@@ -1,95 +1,11 @@
-import { plainJson, jsonArray, JsonBoolean, JsonNumber, JsonString, StringEnum } from "@clusterio/lib";
-import { Type, Static } from "@sinclair/typebox";
-
-export class PluginExampleEvent {
-	declare ["constructor"]: typeof PluginExampleEvent;
-	static type = "event" as const;
-	static src = ["host", "control"] as const;
-	static dst = ["controller", "host", "instance"] as const;
+/** Create the roles and permission groups the scenario shipped with, see seed.ts. */
+export class SeedRequest {
+	declare ["constructor"]: typeof SeedRequest;
 	static plugin = "exp_scenario" as const;
-	static permission = "exp_scenario.example.permission.event";
-
-	constructor(
-		public myString: string,
-		public myNumberArray: number[],
-	) {
-	}
-
-	static jsonSchema = Type.Object({
-		"myString": Type.String(),
-		"myNumberArray": Type.Array(Type.Number()),
-	});
-
-	static fromJSON(json: Static<typeof PluginExampleEvent.jsonSchema>) {
-		return new PluginExampleEvent(json.myString, json.myNumberArray);
-	}
-}
-
-export class PluginExampleRequest {
-	declare ["constructor"]: typeof PluginExampleRequest;
 	static type = "request" as const;
-	static src = ["host", "control"] as const;
-	static dst = ["controller", "host", "instance"] as const;
-	static plugin = "exp_scenario" as const;
-	static permission = "exp_scenario.example.permission.request";
+	static src = "control" as const;
+	static dst = "controller" as const;
+	static permission = "exp_scenario.seed" as const;
 
-	constructor(
-		public myString: string,
-		public myNumberArray: number[],
-	) {
-	}
-
-	static jsonSchema = Type.Object({
-		"myString": Type.String(),
-		"myNumberArray": Type.Array(Type.Number()),
-	});
-
-	static fromJSON(json: Static<typeof PluginExampleRequest.jsonSchema>) {
-		return new PluginExampleRequest(json.myString, json.myNumberArray);
-	}
-
-	static Response = plainJson(Type.Object({
-		"myResponseString": Type.String(),
-		"myResponseNumbers": Type.Array(Type.Number()),
-	}));
-}
-
-export class ExampleSubscribableValue {
-	constructor(
-		public id: string,
-		public updatedAtMs: number,
-		public isDeleted: boolean,
-	) {
-	}
-
-	static jsonSchema = Type.Object({
-		id: Type.String(),
-		updatedAtMs: Type.Number(),
-		isDeleted: Type.Boolean(),
-	});
-
-	static fromJSON(json: Static<typeof this.jsonSchema>) {
-		return new this(json.id, json.updatedAtMs, json.isDeleted);
-	}
-}
-
-export class ExampleSubscribableUpdate {
-	declare ["constructor"]: typeof ExampleSubscribableUpdate;
-	static type = "event" as const;
-	static src = "controller" as const;
-	static dst = "control" as const;
-	static plugin = "exp_scenario" as const;
-	static permission = "exp_scenario.example.permission.subscribe";
-
-	constructor(
-		public updates: ExampleSubscribableValue[],
-	) { }
-
-	static jsonSchema = Type.Object({
-		"updates": Type.Array(ExampleSubscribableValue.jsonSchema),
-	});
-
-	static fromJSON(json: Static<typeof this.jsonSchema>) {
-		return new this(json.updates.map(update => ExampleSubscribableValue.fromJSON(update)));
-	}
+	constructor() {}
 }

exp_scenario/module/commands/_rcon.lua

@@ -7,7 +7,6 @@ local add_static, add_dynamic = Commands.add_rcon_static, Commands.add_rcon_dyna
 
 add_static("Gui", require("modules/exp_gui"))
 
-add_static("Group", require("modules.exp_legacy.expcore.permission_groups"))
 add_static("Roles", require("modules/exp_roles"))
 add_static("Datastore", require("modules.exp_legacy.expcore.datastore"))
 add_static("External", require("modules.exp_legacy.expcore.external"))

exp_scenario/package.json

@@ -7,15 +7,19 @@
 	"repository": "explosivegaming/ExpCluster",
 	"main": "dist/node/index.js",
 	"scripts": {
-		"prepare": "tsc --build && webpack-cli --env production"
+		"prepare": "tsc --build && webpack-cli --env production",
+		"test": "tap --disable-coverage --allow-empty-coverage test/*.test.js",
+		"coverage": "tap --coverage-report=text test/*.test.js"
 	},
 	"engines": {
 		"node": ">=18"
 	},
 	"peerDependencies": {
+		"@clusterio/controller": "workspace:^",
 		"@clusterio/lib": "workspace:^"
 	},
 	"devDependencies": {
+		"@clusterio/controller": "workspace:^",
 		"@clusterio/lib": "workspace:^",
 		"@clusterio/web_ui": "workspace:^",
 		"@types/node": "catalog:",
@@ -23,6 +27,7 @@
 		"antd": "catalog:",
 		"react": "catalog:",
 		"react-dom": "catalog:",
+		"tap": "^21.1.0",
 		"typescript": "catalog:",
 		"webpack": "catalog:",
 		"webpack-cli": "catalog:",
@@ -32,6 +37,8 @@
 		"@expcluster/lib_commands": "workspace:^",
 		"@expcluster/lib_util": "workspace:^",
 		"@expcluster/lib_gui": "workspace:^",
+		"@expcluster/permission-groups": "workspace:^",
+		"@expcluster/roles": "workspace:^",
 		"@sinclair/typebox": "catalog:"
 	},
 	"publishConfig": {

exp_scenario/seed.ts

@@ -0,0 +1,343 @@
+import { RoleColor } from "@expcluster/roles/dist/node/messages";
+
+/**
+ * A role created by the seed, as the scenario defined it before roles moved to
+ * the controller. `parent` stands in for the inheritance
+ * the old config had and is flattened by the seed. The default and admin roles
+ * already exist, so those entries only provide the in game properties.
+ */
+export interface SeedRole {
+	name: string;
+	shortHand: string;
+	color: RoleColor | null;
+	priority?: number;
+	autoAssignHours?: number;
+	blockAutoAssign?: boolean;
+	/** Uses the controller's default role rather than creating one. */
+	isDefault?: boolean;
+	/** Uses the controller's admin role rather than creating one. */
+	isAdmin?: boolean;
+	/** Name of the role whose permissions are also granted, applied recursively. */
+	parent?: string;
+	permissions: string[];
+	/**
+	 * Name of the seed group holders are placed in by their highest role.
+	 * Without one the holders stay in Factorio's Default group.
+	 */
+	group?: string;
+}
+
+/**
+ * A Factorio permission group created by the seed, as the scenario defined it
+ * before groups moved to the controller.
+ */
+export interface SeedGroup {
+	name: string;
+	/** When true the input actions are the only ones disallowed, otherwise the only ones allowed. */
+	isBlacklist: boolean;
+	inputActions: string[];
+}
+
+export const seedRoles: SeedRole[] = [
+	{
+		name: "System",
+		shortHand: "SYS",
+		color: null,
+		isAdmin: true,
+		permissions: [],
+	},
+	{
+		name: "Senior Administrator",
+		group: "Admin",
+		shortHand: "SAdmin",
+		color: new RoleColor(233, 63, 233),
+		parent: "Administrator",
+		permissions: [
+			"exp_scenario.command._rcon",
+			"exp_scenario.command.debug",
+			"exp_scenario.command.set_cheat_mode",
+			"exp_scenario.command.research_all",
+		],
+	},
+	{
+		name: "Administrator",
+		group: "Admin",
+		shortHand: "Admin",
+		color: new RoleColor(233, 63, 233),
+		parent: "Moderator",
+		permissions: [
+			"exp_scenario.gui.warp_list.bypass_proximity",
+			"exp_scenario.gui.warp_list.bypass_cooldown",
+			"exp_scenario.command.connect_all",
+		],
+	},
+	{
+		name: "Moderator",
+		group: "Admin",
+		shortHand: "Mod",
+		color: new RoleColor(0, 170, 0),
+		parent: "Trainee",
+		permissions: [
+			"exp_scenario.player.instant_respawn",
+			"exp_scenario.command.assign_role",
+			"exp_scenario.command.unassign_role",
+			"exp_scenario.command.repair",
+			"exp_scenario.command.kill.always",
+			"exp_scenario.command.tag_clear.always",
+			"exp_scenario.command.spawn.always",
+			"exp_scenario.command.clear_reports",
+			"exp_scenario.command.clear_inventory",
+			"exp_scenario.command.kill_enemies",
+			"exp_scenario.command.remove_enemies",
+			"exp_scenario.command.home",
+			"exp_scenario.command.set_home",
+			"exp_scenario.command.get_home",
+			"exp_scenario.command.return",
+			"exp_scenario.command.connect_player",
+			"exp_scenario.command.set_bot_queue",
+			"exp_scenario.command.set_game_speed",
+			"exp_scenario.command.set_friendly_fire",
+			"exp_scenario.command.set_always_day",
+			"exp_scenario.command.set_pollution_enabled",
+			"exp_scenario.command.clear_pollution",
+			"exp_scenario.gui.rocket_info.toggle_active",
+			"exp_scenario.gui.rocket_info.remote_launch",
+			"exp_scenario.gui.bonus",
+			"exp_scenario.decon.fast_trees",
+		],
+	},
+	{
+		name: "Trainee",
+		group: "Admin",
+		shortHand: "TrMod",
+		color: new RoleColor(0, 170, 0),
+		parent: "Veteran",
+		permissions: [
+			"exp_scenario.player.admin",
+			"exp_scenario.player.spectator",
+			"exp_scenario.bypass.reports",
+			"exp_scenario.command.admin_chat",
+			"exp_scenario.command.goto",
+			"exp_scenario.command.teleport",
+			"exp_scenario.command.bring",
+			"exp_scenario.command.get_reports",
+			"exp_scenario.command.protect_entity",
+			"exp_scenario.command.protect_area",
+			"exp_scenario.command.protect_tag",
+			"exp_scenario.command.jail",
+			"exp_scenario.command.unjail",
+			"exp_scenario.gui.player_list.kick",
+			"exp_scenario.gui.player_list.ban",
+			"exp_scenario.command.spectate",
+			"exp_scenario.command.follow",
+			"exp_scenario.command.search",
+			"exp_scenario.command.search_online",
+			"exp_scenario.command.search_amount",
+			"exp_scenario.command.search_recent",
+			"exp_scenario.command.clear_blueprints_surface",
+			"exp_scenario.gui.playerdata",
+		],
+	},
+	{
+		name: "Board Member",
+		group: "Trusted",
+		shortHand: "Board",
+		color: new RoleColor(247, 246, 54),
+		parent: "Sponsor",
+		permissions: [
+			"exp_scenario.command.goto",
+			"exp_scenario.command.repair",
+			"exp_scenario.command.spectate",
+			"exp_scenario.command.follow",
+			"exp_scenario.gui.playerdata",
+		],
+	},
+	{
+		name: "Senior Backer",
+		group: "Trusted",
+		shortHand: "Backer",
+		color: new RoleColor(238, 172, 44),
+		parent: "Sponsor",
+		permissions: [],
+	},
+	{
+		name: "Sponsor",
+		group: "Trusted",
+		shortHand: "Spon",
+		color: new RoleColor(238, 172, 44),
+		parent: "Supporter",
+		permissions: [
+			"exp_scenario.bypass.reports",
+			"exp_scenario.player.instant_respawn",
+			"exp_scenario.gui.rocket_info.toggle_active",
+			"exp_scenario.gui.rocket_info.remote_launch",
+			"exp_scenario.gui.bonus",
+			"exp_scenario.command.home",
+			"exp_scenario.command.set_home",
+			"exp_scenario.command.get_home",
+			"exp_scenario.command.return",
+			"exp_scenario.decon.fast_trees",
+		],
+	},
+	{
+		name: "Supporter",
+		group: "Trusted",
+		shortHand: "Sup",
+		color: new RoleColor(230, 99, 34),
+		parent: "Veteran",
+		permissions: [
+			"exp_scenario.player.spectator",
+			"exp_scenario.command.tag_color",
+			"exp_scenario.command.jail",
+			"exp_scenario.command.unjail",
+			"exp_scenario.command.set_join_message",
+			"exp_scenario.command.remove_join_message",
+		],
+	},
+	{
+		name: "Partner",
+		group: "Trusted",
+		shortHand: "Part",
+		color: new RoleColor(140, 120, 200),
+		parent: "Veteran",
+		permissions: [
+			"exp_scenario.player.spectator",
+			"exp_scenario.command.jail",
+			"exp_scenario.command.unjail",
+		],
+	},
+	{
+		name: "Veteran",
+		group: "Trusted",
+		shortHand: "Vet",
+		color: new RoleColor(140, 120, 200),
+		parent: "Member",
+		autoAssignHours: 10,
+		permissions: [
+			"exp_scenario.chat.commands",
+			"exp_scenario.command.clear_ground_items",
+			"exp_scenario.command.clear_blueprints",
+			"exp_scenario.command.set_trains_to_automatic",
+		],
+	},
+	{
+		name: "Member",
+		group: "Standard",
+		shortHand: "Mem",
+		color: new RoleColor(24, 172, 188),
+		parent: "Regular",
+		permissions: [
+			"exp_scenario.bypass.deconstruction_log",
+			"exp_scenario.gui.task_list.add",
+			"exp_scenario.gui.task_list.edit",
+			"exp_scenario.gui.warp_list.add",
+			"exp_scenario.gui.warp_list.edit",
+			"exp_scenario.gui.surveillance",
+			"exp_scenario.gui.vlayer_edit",
+			"exp_scenario.gui.tool",
+			"exp_scenario.command.save_quickbar",
+			"exp_scenario.command.vlayer_info",
+			"exp_scenario.command.lawnmower",
+			"exp_scenario.command.waterfill",
+			"exp_scenario.command.artillery",
+		],
+	},
+	{
+		name: "Regular",
+		group: "Standard",
+		shortHand: "Reg",
+		color: new RoleColor(79, 155, 163),
+		autoAssignHours: 3,
+		permissions: [
+			"exp_scenario.command.kill",
+			"exp_scenario.command.rainbow",
+			"exp_scenario.command.spawn",
+			"exp_scenario.command.me",
+			"exp_scenario.decon.standard",
+			"exp_scenario.bypass.entity_protection",
+			"exp_scenario.bypass.nuke_protection",
+		],
+	},
+	{
+		name: "Jail",
+		group: "Restricted",
+		shortHand: "Jail",
+		color: new RoleColor(50, 50, 50),
+		priority: 1,
+		blockAutoAssign: true,
+		permissions: [],
+	},
+	{
+		name: "Guest",
+		group: "Guest",
+		shortHand: "",
+		color: new RoleColor(185, 187, 160),
+		isDefault: true,
+		permissions: [],
+	},
+];
+
+const adminDisallowed = [
+	"add_permission_group",
+	"delete_permission_group",
+	"edit_permission_group",
+	"import_permissions_string",
+	"map_editor_action",
+	"toggle_map_editor",
+	"change_multiplayer_config",
+	"set_heat_interface_mode",
+	"set_heat_interface_temperature",
+	"set_infinity_container_filter_item",
+	"set_infinity_container_remove_unfiltered_items",
+	"set_infinity_pipe_filter",
+];
+
+const trustedDisallowed = [
+	...adminDisallowed,
+	"admin_action",
+];
+
+const standardDisallowed = [
+	...trustedDisallowed,
+	"change_programmable_speaker_alert_parameters",
+	"drop_item",
+	"open_new_platform_button_from_rocket_silo",
+	"set_rocket_silo_send_to_orbit_automated_mode",
+];
+
+const guestDisallowed = [
+	...standardDisallowed,
+	"change_programmable_speaker_parameters",
+	"change_train_stop_station",
+	"remove_cables",
+	"remove_train_station",
+	"reset_assembling_machine",
+	"rotate_entity",
+	"launch_rocket",
+	"cancel_research",
+	"flush_opened_entity_fluid",
+	"flush_opened_entity_specific_fluid",
+];
+
+export const seedGroups: SeedGroup[] = [
+	{ name: "Admin", isBlacklist: true, inputActions: adminDisallowed },
+	{ name: "Trusted", isBlacklist: true, inputActions: trustedDisallowed },
+	{ name: "Standard", isBlacklist: true, inputActions: standardDisallowed },
+	{ name: "Guest", isBlacklist: true, inputActions: guestDisallowed },
+	{ name: "Restricted", isBlacklist: false, inputActions: ["write_to_console"] },
+];
+
+/** The permissions a seed role grants, including those of its parents. */
+export function flattenSeedPermissions(role: SeedRole, roles = seedRoles) {
+	const permissions = new Set<string>();
+	const seen = new Set<string>();
+	let current: SeedRole | undefined = role;
+	while (current && !seen.has(current.name)) {
+		seen.add(current.name);
+		for (const permission of current.permissions) {
+			permissions.add(permission);
+		}
+		current = roles.find(other => other.name === current!.parent);
+	}
+	return permissions;
+}

exp_scenario/test/controller.test.js

@@ -0,0 +1,139 @@
+"use strict";
+const t = require("tap");
+const lib = require("@clusterio/lib");
+const { Controller } = require("@clusterio/controller");
+const { ControllerPlugin } = require("../dist/node/controller");
+const messages = require("../dist/node/messages");
+const { seedRoles, seedGroups } = require("../dist/node/seed");
+const roles = require("@expcluster/roles/dist/node");
+const groups = require("@expcluster/permission-groups/dist/node");
+const { ControllerPlugin: RolesPlugin } = require("@expcluster/roles/dist/node/controller");
+const { ControllerPlugin: GroupsPlugin } = require("@expcluster/permission-groups/dist/node/controller");
+const { GroupRecord, GroupPermissions, RoleMappingRecord } = require("@expcluster/permission-groups/dist/node/messages");
+
+// Importing this defines the permissions the seed grants
+require("../dist/node/permissions");
+
+// The controller validates message classes against the link registry
+for (const Message of [messages.SeedRequest, ...roles.plugin.messages, ...groups.plugin.messages]) {
+	lib.Link.register(Message);
+}
+
+const logger = { child: () => logger, info: () => {}, warn: () => {}, error: () => {}, verbose: () => {} };
+
+// Silence the singleton logger to avoid polluting the test output
+lib.logger.silent = true;
+t.after(() => {
+	lib.logger.silent = false;
+});
+
+/** Build the plugin around a real controller, which is side effect free while not started. */
+async function startPlugin(t2, { withPlugins = true } = {}) {
+	const controllerConfig = new lib.ControllerConfig("controller", {
+		"controller.database_directory": t2.testdir(),
+		"controller.default_role_id": lib.Role.DefaultPlayerRoleId,
+	});
+	const controller = new Controller(logger, [], controllerConfig);
+	controller.roles.set(new lib.Role(0, "Cluster Admin", "", new Set(["core.admin"])));
+	controller.roles.set(new lib.Role(1, "Player", "", new Set()));
+
+	if (withPlugins) {
+		for (const [name, Plugin] of [["exp_roles", RolesPlugin], ["exp_groups", GroupsPlugin]]) {
+			const plugin = new Plugin({ name }, controller, undefined, logger);
+			await plugin.init();
+			controller.plugins.set(name, plugin);
+		}
+	}
+
+	const plugin = new ControllerPlugin({ name: "exp_scenario" }, controller, undefined, logger);
+	await plugin.init();
+	return { plugin, controller };
+}
+
+const byName = (datastore, name) => [...datastore.values()].find(other => other.name === name);
+
+t.test("class ControllerPlugin", t2 => {
+	t2.test(".handleSeedRequest() throws when the seeded plugins are missing", async t3 => {
+		const { plugin } = await startPlugin(t3, { withPlugins: false });
+		await t3.rejects(
+			plugin.handleSeedRequest(),
+			{ message: "Seeding requires the exp_roles and exp_groups plugins" },
+			"the request is rejected",
+		);
+	});
+
+	t2.test(".handleSeedRequest() creates the roles and reuses them by name", async t3 => {
+		const { plugin, controller } = await startPlugin(t3);
+		const rolesPlugin = controller.plugins.get("exp_roles");
+
+		await plugin.handleSeedRequest();
+		t3.strictSame(controller.roles.size, seedRoles.length, "every seed role exists");
+
+		const moderator = byName(controller.roles, "Moderator");
+		t3.ok(moderator.permissions.has("exp_scenario.command.jail"), "parent permissions are flattened in");
+		t3.strictSame(rolesPlugin.roleMeta.get(moderator.id).shortHand, "Mod", "the role properties match the seed");
+
+		await plugin.handleSeedRequest();
+		t3.strictSame(controller.roles.size, seedRoles.length, "seeding again reuses the roles");
+	});
+
+	t2.test(".handleSeedRequest() creates the groups and resets them by name", async t3 => {
+		const { plugin, controller } = await startPlugin(t3);
+		const groupsPlugin = controller.plugins.get("exp_groups");
+
+		await plugin.handleSeedRequest();
+		t3.strictSame(groupsPlugin.groups.size, seedGroups.length, "every seed group exists");
+
+		const restricted = byName(groupsPlugin.groups, "Restricted");
+		t3.strictSame(restricted.permissions.isBlacklist, false, "the group only allows the listed actions");
+		t3.strictSame(restricted.permissions.permissions, ["write_to_console"], "the actions match the seed");
+
+		const admin = byName(groupsPlugin.groups, "Admin");
+		groupsPlugin.groups.set(new GroupRecord(admin.id, admin.name, new GroupPermissions(true, [])));
+		await plugin.handleSeedRequest();
+		t3.strictSame(groupsPlugin.groups.size, seedGroups.length, "seeding again reuses the groups");
+		t3.ok(
+			byName(groupsPlugin.groups, "Admin").permissions.permissions.includes("toggle_map_editor"),
+			"seeding again resets the actions",
+		);
+	});
+
+	t2.test(".handleSeedRequest() maps each role onto its group by rank", async t3 => {
+		const { plugin, controller } = await startPlugin(t3);
+		const groupsPlugin = controller.plugins.get("exp_groups");
+
+		await plugin.handleSeedRequest();
+		const mapped = seedRoles.filter(role => role.group !== undefined);
+		t3.strictSame(groupsPlugin.roleMappings.size, mapped.length, "every role with a group is mapped");
+
+		const mappingOf = name => [...groupsPlugin.roleMappings.values()]
+			.find(mapping => mapping.roleIds.has(byName(controller.roles, name).id));
+		const groupOf = name => groupsPlugin.groups.get(mappingOf(name).groupId).name;
+		t3.strictSame(groupOf("Player"), "Guest", "the default role maps to the guest group");
+		t3.strictSame(groupOf("Jail"), "Restricted", "jail maps to the restricted group");
+		t3.ok(mappingOf("Jail").priority > mappingOf("Senior Administrator").priority, "jail outranks every role");
+		t3.ok(mappingOf("Moderator").priority > mappingOf("Veteran").priority, "the role order sets the rank");
+		t3.ok(mappingOf("Veteran").priority > mappingOf("Player").priority, "the default role ranks lowest");
+		t3.strictSame(mappingOf("Cluster Admin"), undefined, "the admin role keeps the factorio default group");
+
+		const priorities = [...groupsPlugin.roleMappings.values()].map(mapping => mapping.priority);
+		t3.strictSame(priorities.length, new Set(priorities).size, "priorities are unique");
+	});
+
+	t2.test(".handleSeedRequest() reuses mappings and keeps clear of other mappings", async t3 => {
+		const { plugin, controller } = await startPlugin(t3);
+		const groupsPlugin = controller.plugins.get("exp_groups");
+
+		groupsPlugin.roleMappings.set(new RoleMappingRecord(99, new Set([0, 1]), 5, 2, true));
+		await plugin.handleSeedRequest();
+		const first = new Map([...groupsPlugin.roleMappings.values()].map(mapping => [mapping.id, mapping.priority]));
+
+		await plugin.handleSeedRequest();
+		const second = new Map([...groupsPlugin.roleMappings.values()].map(mapping => [mapping.id, mapping.priority]));
+		t3.strictSame(second, first, "seeding again reuses the mappings");
+		t3.strictSame(groupsPlugin.roleMappings.get(99).priority, 2, "other mappings are left alone");
+		t3.notOk([...first.values()].filter(priority => priority === 2).length > 1, "seed priorities skip taken ones");
+	});
+
+	t2.end();
+});

exp_scenario/test/seed.test.js

@@ -0,0 +1,85 @@
+"use strict";
+const t = require("tap");
+const lib = require("@clusterio/lib");
+const { seedRoles, seedGroups, flattenSeedPermissions } = require("../dist/node/seed");
+
+// Importing this defines the permissions the seed grants
+require("../dist/node/permissions");
+
+t.test("seedRoles[] grant only defined permissions", t2 => {
+	for (const role of seedRoles) {
+		for (const permission of role.permissions) {
+			t2.ok(lib.permissions.has(permission), `${role.name} grants defined permission ${permission}`);
+		}
+	}
+	t2.end();
+});
+
+t.test("seedRoles[] are unique with one default and one admin", t2 => {
+	const names = seedRoles.map(role => role.name);
+	t2.strictSame(names.length, new Set(names).size, "names are unique");
+	t2.strictSame(seedRoles.filter(role => role.isDefault).length, 1, "one default role");
+	t2.strictSame(seedRoles.filter(role => role.isAdmin).length, 1, "one admin role");
+	t2.end();
+});
+
+t.test("seedRoles[] are placed in defined groups", t2 => {
+	const groupNames = new Set(seedGroups.map(group => group.name));
+	for (const role of seedRoles) {
+		if (role.group !== undefined) {
+			t2.ok(groupNames.has(role.group), `${role.name} is placed in defined group ${role.group}`);
+		}
+	}
+	t2.end();
+});
+
+t.test("seedGroups[] are unique", t2 => {
+	const names = seedGroups.map(group => group.name);
+	t2.strictSame(names.length, new Set(names).size, "names are unique");
+	for (const group of seedGroups) {
+		t2.strictSame(
+			group.inputActions.length,
+			new Set(group.inputActions).size,
+			`${group.name} lists each input action once`,
+		);
+	}
+	t2.end();
+});
+
+t.test("flattenSeedPermissions() inherits permissions from parent roles", t2 => {
+	const byName = new Map(seedRoles.map(role => [role.name, role]));
+	for (const role of seedRoles) {
+		if (role.parent === undefined) {
+			continue;
+		}
+
+		const parent = byName.get(role.parent);
+		t2.ok(parent, `${role.name} has parent ${role.parent}`);
+
+		const flattened = flattenSeedPermissions(role);
+		for (const permission of flattenSeedPermissions(parent)) {
+			t2.ok(flattened.has(permission), `${role.name} inherits ${permission}`);
+		}
+	}
+	t2.end();
+});
+
+t.test("flattenSeedPermissions() does not inherit permissions when parent is undefined", t2 => {
+	for (const role of seedRoles) {
+		if (role.parent !== undefined) {
+			continue;
+		}
+
+		const flattened = flattenSeedPermissions(role);
+		for (const permission of role.permissions) {
+			t2.ok(flattened.has(permission), `${role.name} contains ${permission}`);
+		}
+
+		t2.equal(
+			flattened.size,
+			role.permissions.length,
+			`${role.name} has no inherited permissions`,
+		);
+	}
+	t2.end();
+});

exp_scenario/web/components/Seed.tsx

@@ -0,0 +1,33 @@
+import React, { useContext, useState } from "react";
+import { Button, Popconfirm } from "antd";
+
+import { ControlContext, SectionHeader, useAccount, notifyErrorHandler } from "@clusterio/web_ui";
+
+import { SeedRequest } from "../../messages";
+
+/** Button on the roles page which creates the roles and permission groups the scenario shipped with. */
+export default function Seed() {
+	const control = useContext(ControlContext);
+	const account = useAccount();
+	const [seeding, setSeeding] = useState(false);
+
+	if (!account.hasPermission("exp_scenario.seed")) {
+		return null;
+	}
+
+	return <SectionHeader
+		title="ExpGaming Roles"
+		extra={<Popconfirm
+			title="Create the ExpGaming roles and permission groups?"
+			description="Roles which already exist by name only gain permissions, groups are reset to the defaults."
+			onConfirm={() => {
+				setSeeding(true);
+				control.send(new SeedRequest())
+					.catch(notifyErrorHandler("Error seeding roles and groups"))
+					.finally(() => setSeeding(false));
+			}}
+		>
+			<Button loading={seeding}>Seed roles and groups</Button>
+		</Popconfirm>}
+	/>;
+}

exp_scenario/web/index.tsx

@@ -0,0 +1,11 @@
+import { BaseWebPlugin } from "@clusterio/web_ui";
+
+import Seed from "./components/Seed";
+
+export class WebPlugin extends BaseWebPlugin {
+	async init() {
+		this.componentExtra = {
+			RolesPage: Seed,
+		};
+	}
+}