Add exp_roles plugin and scenario permissions

[bbassie]

Replaces the role storage half of exp_legacy/expcore/roles.lua with clusterio's own roles and permissions. Clusterio already stores roles, the permissions they grant, and which user holds which role, plus a web UI for all three — so this adds only what it is missing, rather than reimplementing any of it.

This does not yet move the call sites off expcore.roles; nothing depends on the new plugin. That is deliberate, see "What is left" below.

exp_scenario: permissions for the in game actions

The role config held 105 action strings and 7 flags that only existed as bare strings in lua. Each is now a real clusterio permission, so it appears on the role page and can be granted like any other.

Names come from a deterministic transform, exported so the lua side derives exactly the same name and existing call sites keep working untouched:

command/kill                   -> exp_scenario.command.kill
gui/warp-list/bypass-proximity -> exp_scenario.gui.warp_list.bypass_proximity
fast-tree-decon                -> exp_scenario.action.fast_tree_decon
report-immune          (flag)  -> exp_scenario.flag.report_immune

Flags become permissions too — player_has_flag and player_allowed are the same lookup, the only difference being that flags have change triggers, which stay in lua.

Command descriptions are taken from the existing locale entries rather than written fresh, so they match what players already see in /commands. Two permissions were referenced in code but missing from the role config (command/give-warning, command/collectdata); both are now defined.

The 21 actions the Guest role granted are marked grantByDefault, since the in game default role and clusterio's default role are the same concept.

Three actions have no scenario permission — they map onto core ones instead:

Legacy action	Replaced by
command/assign-role	core.user.update_roles
command/unassign-role	core.user.update_roles
command/get-roles	core.role.list

exp_roles: the sync plugin

RoleUpdatesEvent and UserUpdatesEvent are both dst: "control", so instances cannot subscribe to them. The controller plugin rebroadcasts on its own events, the same shape exp_groups uses.

It stores one record per role for the properties clusterio's role does not carry — order, priority, short hand, tag, colour, auto assign threshold, block auto assign — created automatically for any role without one and removed when the role is deleted. These are edited on the core role page through a componentExtra, so there is no second place to manage roles.

There is no default_role_id or root_role_id setting: the default role is controller.default_role_id, and root is core.admin, which already short circuits every permission check.

exp_roles.sync_mode is disabled / enabled / bidirectional, matching exp_groups.

Priority replaces disallow

Only the roles with the highest priority a player holds are considered, and those union as normal. Jail sits above everything else, so holding it suppresses every other role including the implicit default — which is what disallow(default.allowed) was reaching for. It never worked, as the field is allowed_actions, not allowed, so it was passing nil.

This means jail lives on the cluster like any other role, and Jail.old_roles is no longer needed: jailing becomes "add one role", unjailing "remove one role", with no stashing and restoring.

Local assignments

Assignments made in game are applied locally first and then sent up, so assign_player stays synchronous for callers and nothing downstream has to learn about the round trip. Once the controller confirms, the role moves out of the local overlay. If it is refused, the instance rolls the change back.

The same overlay carries assignments which should never leave the map — assign_player_local, for roles earned from time on this map.

Auto assign

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. Per map conditions stay in lua as local assignments. This drops the legacy MapsPlayed / AfkTime conditions in favour of online time alone.

Verification

No factorio server was involved, so the lua was exercised directly under a stubbed environment:

• The transform was compared against the TypeScript across all 114 names (104 actions, 3 core mapped, 7 flags) — no mismatches. This is the one invariant that silently breaks every permission check if it drifts.
• 28 behavioural assertions over the real module covering priority suppression, the implicit default role, the local overlay, pending confirmation, rejection rollback, the server bypass, ordering, and the legacy config.players view.
• Message records round trip through their own typebox schemas.
• Types, the web bundle, and lua parsing all clean.

What is left

Follow ups, kept separate because they are the risky part and deserve their own review:

• Move the ~40 files off require("modules.exp_legacy.expcore.roles"), simplify jail, delete the legacy module and config.
• Seed the existing roles on first run.

override_player_roles is not migrated, and there is no automatic export of live save data — Storage.register keys on debug.getinfo short_src and asserts it is not at runtime, so an rcon helper would register under the wrong name. A manual _export taking the table as an argument can be added if it turns out to be wanted.

Also

One unrelated one line fix: exp-commands_unjail.description was a copy of the /jail text.

🤖 Generated with Claude Code

[bbassie]

On the red lint check: it is pre-existing, not from this branch. main at a07be7b — the commit this branches from — already fails it (run), and the job fails on any finding at all.

The repo currently reports 279 findings across 51 files. This branch contributes zero — I ran the same LuaLS 3.18.2 and FMTK factorio library the workflow uses and fixed all 17 the new module initially had.

Happy to leave it, or to fix the pre-existing ones in a separate PR if that would be useful — exp_scenario/module/commands/home.lua (47) and exp_commands/module/module_exports.lua (30) account for a large share of them.

[Cooldude2606]

We should not use new custom permissions here. Instead we should be using core.roles

exp_roles.assignment is not required as we do not need to make assignments visible to control. This is an implimentation detail for allowing instances to interact with the core role and user models.

[Cooldude2606]

We also need to ensure there are no orpahns as the datastore file might have exist from a previous install of the plugin. In effect we are running all of rolesUpdated on init so it might be useful to have ensureRoleMeta sweepRoleMeta and applyAutoAssign which are all called by rolesUpdated and init

[Cooldude2606]

We should use a switch statement here like we do in instance.ts

[Cooldude2606]

Don't we also need to clean up local_players as some of the pending assignments may now be confirmed and no longer need to be held within local_players as synced_players now holds it.

[Cooldude2606]

Do we need to mutate emit_updates here? The sync param is false which means we never check emit_updates

[Cooldude2606]

If possible, can we benchmark this command. We have recently found that commands containing a large number of string literals can harm performance. In our case it would be the permission strings. Two alternatives would be a permission array to convert an index to string value allowing reuse between roles; another would be a nested structure e.g. { "core": { "roles": [ "list", "subscribe" ] } }. The goal is better time performance. Include your results in your reply and any chalanges you faced in the implimention, commiting the best one. Feel free to explore other alternatives to stay away from custom binary formats that require base64 encoding. If the gains are minimal, then keep this simpler method.

[Cooldude2606]

Can we arrange this is a columed format, or other alterntive that is nicer presented. Currently this takes up a lot of room and it is not clear what the apply button does or that it is specific to the in game properties. Also the "block auto assign" should have a tooltip explaining that it blocks other roles from being autoassigned.