Content generated with AI — it may contain mistakes.

ExyliaClans/ReferenceUpdated in v1.4.0

Database

The nineteen tables, what keys them, how ExyliaLib wipes and resets them, running several servers on one database, and what to know before touching them by hand.

Page 21 of 298 min read

Run ExyliaClans on one server with no setup, or point several servers at one database so they share every clan. Storage is ExyliaLib's: choose the engine and set up Redis as described in Database, and the plugin creates and migrates its nineteen tables from its record definitions, so there is no schema file to apply. database.yml is written on first start and defaults to H2.

Most owners only need Several servers. The rest of this page is for people who query the tables.

The nineteen tables#

The nineteen tables

This page names clan_player_stats for the per-player stats; servers upgraded from 1.4.0 or earlier had it as player_stats, and the rows carry over.

TableKeyHolds
clansid (UUID text)Name, styled name, leader, balance, open, friendly fire, home, banned list, DTR, DTR freeze, last regeneration, EXP, extra member slots
clan_membersuuidThe player's clan and their rank
clan_rolesidEvery rank of every clan: name, weight, permissions, whether it is the default
clan_relationsclanId:targetClanIdOne directional opinion, ALLY or RIVAL
clan_invitesplayerUuid:clanIdA standing invitation and when it was sent
clan_alliance_requestsrequestingClanId:targetClanIdA pending alliance request and when it was sent
clan_claimsid(scoped by claims-scope) One rectangle: world, minX, minZ, maxX, maxZ, baseY
clan_statsclanIdKills, deaths, playtime seconds
clan_player_statsplayerUuid:clanIdThe same per player per clan, plus the last name seen
clan_logsidAction, actor, target, detail, timestamp
clan_mailsidType, sender, recipient, subject, body, sent, expires, read list, deleted list, pinned
clan_webhooksclanIdThe webhook URL, its name in Discord, the events switched off, whether Discord deleted it
lfc_profilesplayerUuidStatus, posted, last posted, expires, the answers
lfp_postingsclanIdStatus, posted, last posted, expires, description, the answers
lfp_applicationsplayerUuid:clanIdStatus, applied, decided, message
clan_war_arenasid(scoped by war-arenas-scope) A war arena's spawns, spectator spawn, corners, and whether it is enabled
clan_war_kitsidA war kit's icon and items
clan_war_recordsclanIdWar wins, losses and draws
clan_war_returnsplayerIdWhere a real-loss war fighter came from, and their game mode

Wiping and resetting#

There is no clan wipe or reset command of its own. Every table declares what it holds for ExyliaLib, so /exylialib wipe and /exylialib resetplayer cover the plugin:

KindTables
World (clans and everything they own)clans, clan_members, clan_roles, clan_relations, clan_invites, clan_alliance_requests, clan_claims, clan_stats, clan_mails, clan_webhooks, lfc_profiles, lfp_postings, lfp_applications, clan_war_records
Progressclan_player_stats
Historyclan_logs
Setup (kept by a season wipe)clan_war_arenas, clan_war_kits
Cacheclan_war_returns
/exylialib wipe ExyliaClans all               every table
/exylialib wipe ExyliaClans clan_logs         one table
/exylialib resetplayer Steve ExyliaClans      one player's rows

Each first run prints what would go and a six-digit code; the same line with the code runs it.

A player reset removes the rows keyed by that player: their membership (clan_members), their stats (clan_player_stats), their invites, LFC profile, LFP applications and pending war return. The running server lets go of them at once, without a restart. If the player led a clan, the member with the heaviest rank becomes leader; if nobody is left, the clan is disbanded.

What the keys buy you#

What the keys buy you

Several rules that would otherwise need enforcing are enforced by the key itself:

  • A player is in one clan. clan_members is keyed by the player's UUID, so a second membership row cannot exist.
  • A clan has one claim, one LFP posting. Both are keyed by the clan id.
  • A player has one LFC profile, and one application per clan.
  • An invitation is unique per pair, and so is a relation.

Two indexes#

Indexes
IndexOnFor
idx_cl_clan_tsclan_logs (clanId, timestamp DESC)The logs menu: filter by clan, newest first, take a page
idx_cm_clan_sentclan_mails (clanId, sentAt DESC)The inbox, the same way

Both make a page a bounded read rather than a scan.

Columns worth knowing about#

Columns worth knowing about
ColumnFormat
clans.bannedPlayersComma-separated UUIDs
clan_roles.permissionsComma-separated permission names. An unknown name is skipped when read
clans.homeLocationA serialised location that carries the server it was set on — server,world,x,y,z,yaw,pitch. null when unset. A home saved under a previous server-id is read as this server's
clans.styled_nameThe name as /clan style draws it, up to 1024 characters. null when the clan has no style
clans.balanceHeld in the currency bank-currency names; changing that key later does not convert it
clans.extraSlotsMember slots granted with /clanadmin setslots, on top of max-members and the level bonus
clans.dtrRegenAtWhen the DTR last regenerated, epoch millis — what keeps several servers from each regenerating it
clan_invites.sentAt / clan_alliance_requests.sentAtEpoch millis. 0 on an invite written before 1.2.0, which counts as sent at the update
clan_webhooks.urlThe full webhook URL, token included. Treat the table as a secret; it is never shown in game
clan_webhooks.disabledEventsComma-separated event names the clan switched off: JOIN, LEAVE, KICK, BAN, INVITE, RANK, LEADER, RENAME, ALLIANCE, RIVALRY, BANK, DISBAND
clan_mails.readByPlayers / deletedByPlayersComma-separated UUIDs — which is how read and deleted are per member off one row
lfc_profiles.data / lfp_postings.dataThe serialised answers
*.statusACTIVE / EXPIRED for postings and profiles; PENDING / ACCEPTED / REJECTED for applications

What is not in the database#

  • Chat channels. Per session; everybody is back on global after a restart.
  • Kill streaks. Per session, and reset by dying.
  • Camp, rally, focus and regroup markers. All in memory. A regroup point and a kick truce are shared with the other servers of a network, never stored.
  • The anti-spam waits. Create, invite, mail, rival-notice and webhook waits are in memory, per server.
  • The clan level. Derived from clans.exp on every read, never stored.
  • Claim ownership of members. Derived from clan_members; the claim row names only the clan.

Caches#

Clans, members, ranks, relations, claims, invitations, alliance requests and webhooks are held in memory and written through on change, so the hot path never touches the database. Two things are cached with a TTL instead:

CacheTTLWhy
Each leaderboard ranking30 sA scoreboard asks four times a second
The online roster per clan and per alliance1 sThirty slots × several viewers × four times a second
Editing rows by hand needs a restart

The caches are loaded at enable and kept in step by the plugin's own writes — and, on a network, by the other servers' writes. A row changed directly in the database is not noticed, and will be overwritten the next time that clan changes. Use /clanadmin where it covers what you need, and stop the servers where it does not.

Several servers#

Servers that share one database act as one clan system once every one of them enables Redis in database.yml (the redis block, with a different server-id on each). Nothing else is configured.

WhatHow
Every table: clans, members, ranks, relations, invites, alliance requests, mail, stats, claims, webhooks, LFC and LFPEach server keeps its copy and re-reads a row the moment another server writes or deletes it. A join, a kick, a promotion or an alliance made on one server is seen on all of them within milliseconds.
Clan chat, ally chat, every clan notice, invitations, kicks, promotions, mail noticesPublished once and delivered by each server to the members it holds, so a line is never sent twice and never only where it happened.
/clan regroupThe point names its server; a clanmate elsewhere is handed over to it.
Kick truceFollows the kicked player to whichever server they move to.
DTR regenerationOnce per interval for the whole network, however many servers run the timer.
Online counts (%exyliaclans_clan_online%, the online roster, menus, the leaderboard)Count members on any server.

What stays on the server it was made on: the camp and rally markers and the focus outline (they are drawn on one server's map), the anti-spam waits, and which chat channel a player has toggled. A claim is drawn only where its world is loaded.

Without Redis everything behaves as on one server.

Startup#

The repositories are read asynchronously, so the plugin finishes enabling before the tables have answered. Until they do, every lookup says no clan — the safe way to be wrong for a moment. Once the caches are true, anybody already online has their join replayed, so a player who logged in during that window is not left invisible to their own clan.

If the read fails outright, the console says so and the plugin stays idle rather than starting to write against caches it knows are empty.

Something missing on this page? Tell us on Discord