Documentation · Guild Rank Sync

Synchronize Tibia ranks with managed Discord roles.

This guide explains rank mappings, automatic promotions and demotions, Guest access for registered outsiders, restriction behavior, role hierarchy and the exact boundary between Luminox-managed roles and unrelated Discord roles.

Before mapping roles

Verify the guild and place Luminox above managed roles.

EditionCommunity Edition and Founder; available on Community Free.
Guild sourceA verified guild and world configured through /guild set.
Identity sourceAt least one character registered through the Registration panel.
Bot permissionManage Roles in Discord.
HierarchyThe Luminox role must sit above every mapped rank role and the Guest role.
What is managed

Luminox manages only configured rank roles, exact-name guild rank roles it recognizes and the configured Guest role. It does not remove unrelated community, cosmetic or staff roles.

Administrator commands

Connect every Tibia rank to its Discord role.

/ranks map rank:Vice Leader role:@Vice Leader

Run the command once for every guild rank that should grant a Discord role. Rank comparison is case-insensitive, but the configured Tibia rank should match the wording used by the verified guild.

Explicit mappingThe selected role ID is the source of truth even if its Discord name changes later.
Exact-name fallbackWithout an explicit mapping, Luminox can use a Discord role whose name matches the Tibia rank.
Inspection/ranks overview returns all mappings, Guest configuration and role availability privately.
Prefer explicit mappings

The fallback is useful during first setup, but mapping IDs deliberately is safer when Discord role names differ from Tibia or may be renamed.

Registered outsiders

Use one Guest role without pretending the account is a guild member.

/ranks guest role:@Guests

A Discord account with a valid registered character but no eligible character in the configured guild can receive the Guest role. This keeps verified identity and guest-channel access separate from guild membership.

Account stateManaged result
Registered and in the configured guildCorrect mapped rank role; Guest is removed.
Registered but outside the guildGuest role; managed rank roles are removed.
No registered charactersManaged rank and Guest roles are removed.
Several registered charactersThe account remains guild-eligible while at least one registered character belongs to the guild.

Promotion and demotion flow

One synchronization outcome replaces the old managed state.

  1. 01
    Refresh verified character data

    Luminox confirms current guild membership and rank from the Community identity flow.

  2. 02
    Resolve the target role

    An explicit mapping is preferred; exact-name fallback is used only when appropriate.

  3. 03
    Remove obsolete managed roles

    Old guild-rank roles and an inapplicable Guest role are removed when editable.

  4. 04
    Apply the current role

    The correct rank or Guest role is added without changing unrelated roles.

  5. 05
    Record important changes

    The configured moderation log can explain guild departures and managed-role transitions.

A member can run /update to refresh their own current main, nickname and managed guild role without starting a full server scan. Administrators use /update-all only when a complete registered-account synchronization is deliberately required.

Ban List and Blacklist

Registration remains, but guild access does not.

When an account becomes restricted through a connected Ban List or Blacklist record, Luminox removes configured guild-rank roles. The registered characters remain stored, and a configured Guest role can still identify the account as a registered outsider.

  • Restrictions do not delete character registrations.
  • Configured guild roles are removed even if the character still appears in the Tibia guild.
  • Guest can remain or be applied while the account still has a valid registration.
  • Removing the last registration also removes the managed Guest role.
  • Unrelated Discord roles remain outside this synchronization.

Discord hierarchy

Every managed role must be editable by Luminox.

Role above LuminoxDiscord blocks the edit; Luminox reports the blocked role instead of claiming success.
Missing mapped roleThe synchronization returns a clear configuration error for that Tibia rank.
Server ownerRole hierarchy and Discord ownership rules still apply normally.
Administrator rolesThey are not inferred as guild ranks and are not removed by rank synchronization.

Troubleshooting

Inspect mappings before forcing a full refresh.

SymptomCheckSafest action
Wrong rank role/ranks overview, current verified guild rank and selected main.Correct the explicit mapping, then run /update for the affected member.
Role not addedManage Roles permission and whether the target sits below Luminox.Fix Discord hierarchy before retrying.
Guest not appliedGuest mapping and whether the account still has a valid registration.Configure /ranks guest or restore the valid registration.
Old guild role remainsWhether the role is part of the configured or recognized managed set.Map it explicitly if it represents a guild rank; unrelated roles are intentionally preserved.
Member left one characterWhether another registered character still belongs to the guild.No removal is needed while the account remains legitimately guild-eligible.
Review RegistrationReview managed-role logs