mirror of
https://github.com/PHIDIAS0303/ExpCluster.git
synced 2026-11-11 15:54:52 +09:00
BastiaanandClaude Opus 5.5
8d7d5ff10f
Commands, Permission Groups, Player Statistics, Reports, Roles, Scenario, Server UPS and Module Utilities get a readme covering their config, permissions, commands, web pages and Lua and Node API. The existing readmes are brought up to date: Auto Restart now that clusterio marks a restart after a plugin install, Discord Auth gets the code timeout, command aliases and its Lua API, and the GUI guide says what the plugin is and has its toolbar examples and an iterator name fixed. The main readme gets a Plugins section listing each plugin by name and package with a one line description. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
74 lines
4.3 KiB
Markdown
74 lines
4.3 KiB
Markdown
# ExpGaming - Roles
|
|
|
|
Mirrors clusterio roles into the game. Each clusterio role is a role in game with the same id, name and permissions, and a player holds the roles of the clusterio user with the same name. Permission checks in game use clusterio permission names, so `exp_scenario.command.kill` is granted in game by the same role that grants it in the web UI.
|
|
|
|
The controller is the source of truth. It stores the in game properties of each role in `database/exp_roles/role_meta.json`, keyed by role id, and creates them for any role that has none. New roles go after every existing role in the order. On start the instance fetches every role and assignment and replaces the state in the save. After that it gets updates as roles and users change. The default role, `controller.default_role_id`, is held by every player and is not stored per player.
|
|
|
|
Only the roles with the highest priority a player holds apply. A Jail role with a higher priority than the rest suppresses every other role, the default role included.
|
|
|
|
The controller grants roles by online time across the cluster. It checks on start, when a role or user changes, and when a player leaves an instance. Roles granted this way are never taken away. Players holding a role with block auto assign set are never granted roles this way.
|
|
|
|
## Config
|
|
|
|
On the instance:
|
|
|
|
| Field | Default | Description |
|
|
|---|---|---|
|
|
| `exp_roles.sync_mode` | bidirectional | `disabled` does not sync. `enabled` applies roles from the controller. `bidirectional` also sends roles assigned or unassigned in game to the controller. |
|
|
|
|
A role assigned in game applies right away. If the controller refuses it the instance takes it back off the player. Changing the mode from `disabled` applies on the next instance start.
|
|
|
|
## Permissions
|
|
|
|
The plugin has no permissions of its own. Listing roles needs `core.role.list`, subscribing to role updates needs `core.role.subscribe`, and editing the in game properties needs `core.role.update`.
|
|
|
|
## Web
|
|
|
|
The role page gets an In Game Properties section with these fields:
|
|
|
|
| Field | Default | Description |
|
|
|---|---|---|
|
|
| Order | after the last role | A lower value is a more privileged role. Ties go to the lower id. |
|
|
| Priority | 0 | Only the roles with the highest priority a player holds apply. |
|
|
| Short hand | | Short form of the name, the name when empty. |
|
|
| Tag | | Shown next to the names of players with this role. |
|
|
| Colour | | Used for the role name and tag in game. |
|
|
| Auto assign after (hours) | | Online time after which the role is granted, never when empty. |
|
|
| Block auto assign | false | Holders of this role are never granted roles automatically. |
|
|
|
|
## Lua
|
|
|
|
```lua
|
|
local ExpRoles = require("modules/exp_roles")
|
|
|
|
ExpRoles.get_role(role_id) -- Roles are looked up by clusterio id
|
|
ExpRoles.get_role_by_name("Moderator")
|
|
ExpRoles.get_roles() -- In no particular order
|
|
ExpRoles.get_ordered_roles() -- Most privileged first
|
|
ExpRoles.get_default_role()
|
|
ExpRoles.get_higher_roles(role) -- The role and those above it, default role excluded
|
|
ExpRoles.get_lower_roles(role) -- The role and those below it, default role excluded
|
|
ExpRoles.get_player_roles(player) -- Roles that apply, nil is the server which has core.admin
|
|
ExpRoles.get_player_highest_role(player)
|
|
ExpRoles.player_has_permission(player, "exp_scenario.command.kill")
|
|
ExpRoles.player_has_any_permission(player, ...)
|
|
ExpRoles.player_has_all_permission(player, ...)
|
|
ExpRoles.player_outranks(player, other)
|
|
ExpRoles.define_permission_trigger(permission, function(player, state) end) -- Run on join and role changes
|
|
|
|
role:has_permission(permission) -- core.admin grants every permission
|
|
role:is_higher_than(other)
|
|
role:has_player(player) -- Ignores priority
|
|
role:get_player_names() -- Includes players who never joined this map
|
|
role:get_players(online)
|
|
role:print(message) -- Returns how many online players got it
|
|
role:assign(player, { by_player_name, silent, local_only }) -- local_only keeps it to this map
|
|
role:unassign(player, { by_player_name, silent, local_only })
|
|
|
|
[ExpRoles.events.on_player_roles_changed] = function(event) end, -- { player_index, by_player_index, assigned, unassigned }
|
|
```
|
|
|
|
## Node
|
|
|
|
`RoleListRequest` returns every role combined with its in game properties. Control connections can subscribe to `RoleUpdatedEvent`. `RoleMetaUpdateRequest` sets the in game properties of a role.
|