Role badges

Declare badges to show small badges next to names in communities. Your plugin maps a community’s roles to badges; FluxPlugs finds who has those roles and draws them.

Register a provider

cleanup.push(
  await api.badges.registerRoleBadgeProvider(
    (request) => ({
      badges: request.roles
        .filter((role) => !role.isDefault && /\bmods?\b/i.test(role.name))
        .map((role) => ({
          roleId: role.id,
          label: "MOD",
          icon: "hammer",
          color: "#3498db",
          tooltip: "Moderator · " + role.name,
          priority: 300,
        })),
      owner: { label: "OWNER", icon: "crown", color: "#f0b232", priority: 500 },
    }),
    { maxPerUser: 2 },
  ),
);

The host calls the provider with { guildId, roles } when it first shows a community and again whenever that community’s roles change. Each role has id, name, color (an integer, 0 for none), position, isDefault (true for @everyone) and, when known, permissions as a decimal bitfield string.

Return one badge per role at most. Badges for role ids the request didn’t contain are ignored. The optional owner style is shown for the community owner, who the host identifies.

A plugin has one provider. Registering again fails with badge_provider_exists until the first is disposed.

Options

Option	Default	Effect
maxPerUser	1	Most of this plugin’s badges per person, 1 to 5, highest priority then role position
surfaces	all on except replies	messages, memberList, memberGroups, profiles, roleSettings, replies
memberLookup	true	Whether the host may look up the roles of people on screen with the user’s account

Badges appear after names in chat messages, member-list rows, member-list role group headers, profiles and reply previews, and after role names in a community’s role settings. Mentions, typing indicators and voice lists don’t show which user they are, so they get no badges.

Where the roles come from

The plugin never sees members, only role lists. The host works out each person’s roles:

1. From Fluxer’s member endpoint, when memberLookup is on. Lookups cover people on screen only, run one at a time, are capped per community, and stop when Fluxer rate-limits or refuses them.
2. From a profile’s role list, when the user opens one.
3. Otherwise from the page: the member-list group a person appears under, and their name colour, which is the colour of their highest coloured role. A colour counts only when every role of that colour gets the same badge.

So a badge can appear a moment after the name while its lookup finishes.

Limits

Labels are 1 to 12 letters, digits, spaces or . & + # -. Labels that read as Fluxer’s own tags, such as BOT, SYSTEM or anything containing Fluxer, are refused. Colours are #rrggbb, tooltips up to 100 characters, priorities 0 to 1000, and icons one of shield, hammer, star, wrench, crown, code, heart or sparkle.

The provider has one second to answer. A result that fails validation is dropped as a whole and retried after 30 seconds, so check your labels and colours before returning them.

Each badge’s tooltip ends with the plugin that added it. At most six badges are shown per name across all plugins, and identical badges from different plugins are shown once. A plugin with patcher can reorder or drop the final list through the badges.merge hook.