About GroupLink
GroupLink is a lightweight Rust plugin designed for the Oxide modding framework, created to manage group relationships between leader (parent) groups and their associated subgroups. Its primary function is to automatically remove players from specified subgroups when they are no longer part of their corresponding leader group, ensuring that subgroup permissions are tied to leader group membership. This is particularly useful for servers using timed or subscription-based group systems, such as those managed by the TimedPermissions plugin.
When a player loses membership in a leader group (either through manual removal or expiration via TimedPermissions), GroupLink checks for and removes them from all linked subgroups defined in its configuration. Upon each subgroup removal, it sends a private, customizable chat message to the affected player, informing them of the change. The plugin uses a periodic check system to ensure compatibility with external group management plugins, making it efficient with minimal server performance impact.
Key features:
Automatically removes players from subgroups when their leader group membership ends
Sends private, styled chat messages (configurable size and color) to affected players
Lightweight design with deferred operations using NextTick to reduce resource usage
Configurable leader groups, subgroups, message format, and check interval
Admin commands for testing and debugging group status
Configuration Explanation
The plugin generates a configuration file named GroupLink in the oxide/config directory. Below is the default configuration with an explanation of each field:
json
{ "LeaderGroups": [ "vipplus", "mvp", "fanatic" ], "SubGroups": { "vipplus": [ "cvipplusbuilders", "cvipplusfarmers", "cvipplusindustrial" ], "mvp": [ "bmvpbuilders", "bmvpfarmers", "bmvpindustrial" ], "fanatic": [ "afanaticbuilders", "afanaticfarmers", "afanaticindustrial" ] }, "MessageFormat": "{0} you have left group {1} as your {2} subscription has ended", "MessageSize": 24, "MessageColor": "green", "CheckInterval": 60.0 }
LeaderGroups: An array of strings listing the parent group names (e.g., "vipplus", "mvp", "fanatic"). These are the primary groups that, when removed from a player, trigger subgroup removal.
SubGroups: A dictionary mapping each leader group to an array of its associated subgroups. For example, "vipplus" is linked to "cvipplusbuilders", "cvipplusfarmers", and "cvipplusindustrial". When a player loses the leader group, they are removed from all listed subgroups.
MessageFormat: A string defining the chat message sent to players upon subgroup removal. It uses indexed placeholders:
{0}: Player's username
{1}: Subgroup name
{2}: Leader group name
Example output: "UrbanViking you have left group bmvpbuilders as your mvp subscription has ended"
MessageSize: An integer setting the font size of the chat message (default: 24).
MessageColor: A string defining the color of the chat message in HTML color format (default: "green"). Can be changed to other colors like "red", "#FF0000", etc.
CheckInterval: A float specifying how often (in seconds) the plugin checks all connected players for leader group status (default: 60.0). Adjust this to balance responsiveness and server load.
Adding/Removing Groups from the Config
To modify the groups in the config, edit oxide/config/GroupLink.json and reload the plugin using oxide.reload GroupLink or /grouplink reload. Here's how to add or remove groups:
Adding a New Leader Group and Subgroups
Open GroupLink.json.
In the "LeaderGroups" array, add the new leader group name:
json
"LeaderGroups": [ "vipplus", "mvp", "fanatic", "elite" // Added new leader group ]
In the "SubGroups" dictionary, add a new entry for the leader group with its subgroups:
json
"SubGroups": { "vipplus": ["cvipplusbuilders", "cvipplusfarmers", "cvipplusindustrial"], "mvp": ["bmvpbuilders", "bmvpfarmers", "bmvpindustrial"], "fanatic": ["afanaticbuilders", "afanaticfarmers", "afanaticindustrial"], "elite": ["elitebuilders", "elitefarmers", "eliteindustrial"] // Added subgroups for "elite" }
Save the file and reload the plugin.
Removing a Leader Group and Its Subgroups
Open GroupLink.json.
In the "LeaderGroups" array, remove the leader group name:
"LeaderGroups": [ "vipplus", "fanatic" // Removed "mvp" ]
In the "SubGroups" dictionary, remove the corresponding entry:
"SubGroups": { "vipplus": ["cvipplusbuilders", "cvipplusfarmers", "cvipplusindustrial"], "fanatic": ["afanaticbuilders", "afanaticfarmers", "afanaticindustrial"] // Removed "mvp" entry }
Save the file and reload the plugin.
Adding/Removing Subgroups for an Existing Leader Group
To add a subgroup, append it to the array under the leader group in "SubGroups":
"mvp": ["bmvpbuilders", "bmvpfarmers", "bmvpindustrial", "mvpraiders"] // Added "mvpraiders"
To remove a subgroup, delete it from the array:
"mvp": ["bmvpbuilders", "bmvpfarmers"] // Removed "bmvpindustrial"
Save and reload the plugin.
Hooks Needed by Other Plugins
GroupLink uses the following Oxide hook, which other plugins might need to interact with or be aware of:
OnUserGroupRemoved(BasePlayer player, string group):
Called when a player is removed from a group via Oxide's permission system.
GroupLink uses this as a fallback to catch manual group removals, though its primary mechanism is a periodic check for TimedPermissions compatibility.
Other plugins can call this hook to trigger GroupLink's removal logic if they remove players from leader groups manually.
