Skip to content

Roles

Roles in the Network are a network-wide role and access layer which lets you manage ranks and permissions in a powerful way.

Creating Roles

Navigate to:

Staff Network Panel
└─ Roles
   └─ New Role

Options:

  • Key
  • Display Name
  • Lane
    • RANK, MODERATION, or CUSTOM
  • Priority and behavior flags
    • staffRole - auto-manages staff chat membership.
    • opRole - drives network-wide OP sync/bootstrap behavior.
    • purchasable
    • useDefaultTextFormatting - enables built-in chat prefix formatting.
  • Chat formatting fields
    • chatPrefix
    • prefixHexColor (for example #FF5555)
  • Metadata map
    • Arbitrary key/value tags for extra data.
    • Example: season=2026, department=moderation, perk.multiplier=1.25.

Roles tab - create role Creating a new role from the Staff Network Panel.

Granting Roles

Via Staff Network Panel

In the Player Manager tab:

  1. Lookup a player.
  2. Set Action Mode to Role Grant/Revoke.
  3. Set Grant Role or Revoke Role to the desired role.
  4. Click Grant Role or Revoke Role to apply.

Player Manager - grant revoke roles Granting and revoking roles for a player.

Timed Grants/Revoke (API)

For timed role grants, use the Role API:

RoleService timed grant/revoke example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
UUID playerId = /* target player UUID */;
UUID actorId = /* admin UUID */;

// Timed grant: 7 days
roleService.grantRoleDetailed(
    playerId,
    "mod",
    RoleGrantOptions.timed(actorId, 7L * 24L * 60L * 60L * 1000L, "Trial moderator")
);

// Revoke role
roleService.revokeRoleDetailed(
    playerId,
    "mod",
    RoleRevokeOptions.of(actorId, "Trial ended")
);

Roles are per-player and granted with:

  • who granted it
  • reason
  • duration
  • idempotency support

Expired temporary roles are removed automatically when profiles are resolved.

Role Stacking

Each player gets a resolved role profile with:

  • active roles
  • primary rank
  • primary moderation role
  • display role (configurable by policy: MODERATION_FIRST, RANK_FIRST, CUSTOM)
  • merged tags

Don't be afraid of giving multiple roles to a player!

Permissions and Roles

Any native, network, or plugin-sourced permission access level can be set via minimum role. Access is allowed for roles of equal or higher priority than the minimum role.

Optional Chat Formatting

When useDefaultTextFormatting is enabled, for players whose highest priority role is that role, the system prefixes their username with the colored rank prefix.

Example:

chatPrefix=[Mod]
prefixHexColor=#0384fc
Role prefix formatting example

OP Synchronization

opRole=true roles are managed network-wide, granting players holding these roles operator across all network servers, and properly managing de-op behavior when an opRole is removed.

Staff Chat Synchronization

Holding a staffRole=true role auto-manages staff chat membership.

Events and Moddability

Role events provided:

  • RoleGrantedEvent
  • RoleRevokedEvent
  • RoleExpiredEvent
  • RoleProfileChangedEvent
  • RoleDefinitionCreatedEvent
  • RoleDefinitionUpdatedEvent
  • RoleDefinitionDeletedEvent

Important RoleService API methods:

  • getPlayerRoleProfileNetwork(...)
  • listPlayerRoleGrants(...)
  • listRoleDefinitions(...)
  • grantRoleDetailed(...)
  • revokeRoleDetailed(...)
  • upsertRoleDefinition(...)
  • deleteRoleDefinition(...)
  • resolveRoleDisplayInfo(...)
  • registerRoleTypedEventListener(...)