Hua Shi LeiProjects

Guild-Albion-Bot

Guild-Albion-Bot is a Discord bot for Albion Online guilds. It checks that members really are in the guild, hands out roles over time, and runs the guild's bank, group content, regears and applications from Discord.

Sole developer · In use by a live guild · 188 commits, feature-branch pull requests

Guild officers had no automatic way to verify members or manage registration, a bank, tickets and regears. I built a bot on Node.js and Discord.js 14 with an Express interactions webhook. It verifies members against the Albion Online API and grants tenure-based roles automatically, and it can be rebranded through one setting.

It also has a virtual guild bank, tickets, content signup and regear threads, and temporary voice channels. GitHub Actions publishes a Docker image; the repository has 180+ commits and uses feature-branch pull requests.

Registration and roles

A member registers with a guided panel: choose Guild or Alliance, then enter the in-game name in a form. The bot looks that character up in Albion Online's own game-info API and only continues if the player really belongs, showing buttons to pick the right one when several players share a name. It then gives the member the registered role and sets their nickname from a template such as the guild tag and the in-game name. Alliance membership is checked against the guild's current alliance each time, not a saved list.

Roles then follow tenure. An admin adds tiers, each a role and a number of days, and the bot grants the role once a registration is that old. Tiers are cumulative, so tiers at 30 and 60 days give the second role at day 60. The clock starts at registration and resets if the member unregisters, is removed or is purged and then registers again. The bot checks on start, every 15 minutes and straight after a tier is added, and a role an admin removes by hand stays removed. A purge re-verifies every registered member and removes anyone no longer in the guild, including people who hold the role but never registered, and a paged list of members with a CSV export and a tenure view keeps officers informed.

Running guild content

An officer starts a content callout with a short wizard: a content type such as ROA, CTA, GCAMPS, FF, Tracking or Avadungeon, a size, and roles from presets for tank, heal, support and DPS groups or a custom list. Members sign up with buttons or by typing "x tank", "x fill" or "x cancel" in the thread, and fill players are assigned to open slots at random. Several callouts can run at once, each in its own thread. Afterwards a regear command opens a thread that pings the registered role, and closing it marks it done and locks it. Applications work the same way: an Apply button creates a post in a forum channel, staff can claim and close it, and a transcript goes to a log channel.

The guild also keeps a virtual bank. Members check their balance or list who holds money, and admins deposit, withdraw and clear balances with public receipts; which roles may manage it is configurable. For content that needs specific builds, a comp roster is a web page that members open from Discord. They sign in with Discord and claim an open build under their registered Albion name, one build per player per roster, while admins edit builds on the same page. It has a catalog of item icons, a starter roster of 20 builds, and refreshes every 15 seconds so claims show up without a reload.

The bot listing active bank users with their balances in a Discord embed

Commands and rebranding

Every feature is a slash command, and most also work with a prefix that each server can change. Help is paged and only shows the commands the person can use. A Member Hub panel adds one-click buttons for registering, unregistering, checking a balance and opening help, and smaller features include a welcome message with a GIF when someone joins and join-to-create voice channels. Nothing about one guild is baked in: the bot's display name is a single setting, so another guild can run it under its own name. The screenshots here show it running under one guild's name.

The bot's profile in Discord with a list of its recent and popular slash commands
The bot's help message listing user, bank admin, regear and administrator commands

How it is built

The bot is Node.js with Discord.js 14 and an Express server. Slash commands, buttons, selects and forms arrive as signed webhook requests at an interactions endpoint, checked against the application's public key, and the gateway connection is kept only for messages and the member cache. Commands re-register themselves on start whenever the definitions change, so deploying is enough. There is no database: each guild's data is a set of JSON files, written to a temporary file and then renamed, so a crash cannot leave a half-written file. Admin commands need the Administrator permission, and the bank, content and regear features can each be delegated to a role.

The comp roster page checks everything on the server: item ids against the catalog, slot limits for each equipment type, the request origin, and JSON-only bodies. Admin edits are field-level patches, so they never overwrite a player's claim made at the same moment. GitHub Actions builds a Docker image on every push to main and publishes it to Docker Hub, the live server pulls that image, and Renovate keeps dependencies current.

Known gaps

There is no automated test suite or linter; the comp roster feature was checked with a scripted run of 56 checks and the rest by hand. Slash and prefix commands duplicate each other, so the prefix file has grown to about 1,200 lines. The ticket system supports one panel per server with its questions written into the code, and a few defaults, such as the bot's name and its custom emoji ids, still belong to the first guild that used it.