RefugeBot Docs

This guide covers everything you can do from the player side (chat commands, the web shop, bazaars, donor perks) and — if you're signed in as an admin — everything you can do from the admin side too.

Getting started

First time on the server? Join the game once so RefugeBot registers your account. Once you're in, type /help in chat to see commands available to you, or hit the highlights below.

Your first 5 minutes

1. Type /starterkit to claim a one-time starter pack (yucca juice, bacon, bone knife, etc.).
2. Type /balance to see your coin and gold totals. Coins accrue passively while you're online.
3. Type /daily to claim your first daily reward.
4. Sign into the web shop with Steam to browse items and set up a bazaar.
5. Save a teleport at your base: /settp base, then jump back any time with /tp base.

Economy basics

The server runs two currencies:

• Coins — the main currency. Earned passively every minute of playtime, for every zombie kill, for surviving bloodmoons, from daily and vote rewards, and from slot machine wins.
• Gold — the premium currency. Earned only through daily rewards (small amounts) and donor tiers.

Donor tiers multiply your coin earnings (1.25x Bronze → 2.0x Platinum) and grant a one-time coin + gold bonus.

Install & first-boot setup

End-to-end walkthrough: drop the mod in, boot your server, pick a role (standalone / controller / periphery), create an admin account, optionally link Steam. Add peripheries any time after. The screens below are pixel-faithful mockups of the real install overlay — what you see in the browser will look the same.

What you'll end up with

• Standalone — one 7DTD server running the whole thing. Nothing fancy; the admin panel and the game server live in the same process.
• Controller + Peripheries — multi-server cluster. The controller (we call it Hybrid in the role picker since it's also a game server) owns the admin panel, wallets, shop, plugins, and admin list. Each periphery is another 7DTD server that polls the controller every 3 s for config, replicates admin / shop / plugin state, and ships its own chat bridge. Admins log into the controller's URL, use a server switcher in the sidebar to act on any periphery remotely.

The install flow below is the same regardless of which path you want — the role picker on screen 2 is where you branch.

Step 1 · Drop the mod in place

RefugeBot ships as a single folder: zzzzzzzRefugeBot/. The zzzz prefix ensures it loads after TFP and third-party mods so it can hook their events. Drop it into the server's Mods/ directory:

/path/to/7DaysToDieServer/
└── Mods/
    ├── 0_TFP_Harmony/          ← ships with 7DTD
    ├── TFP_MapRendering/       ← required (or Allocs equivalents)
    ├── TFP_WebServer/          ← required (or Allocs equivalents)
    ├── zzzzzzzPrismaCore/      ← required — install separately
    └── zzzzzzzRefugeBot/       ← RefugeBot — this one

Start the server. On first boot RefugeBot notices it's a fresh install (no RefugeBotData/refugebot.json or an empty one) and takes over the admin panel with the install overlay.

Step 2 · First boot & the boot password

On a brand-new install, RefugeBot generates a one-time 12-character boot password and prints it to the console. This is the only way to unlock the install overlay — without it, anyone hitting your admin URL could complete install as themselves and lock you out. It rotates on every restart until the install flow completes.

Port hunting

If port 8484 is already taken (say, a different RefugeBot install on the same host) the boot banner will show the hunted port it landed on — anywhere in 8484–8504. It persists to refugebot.json, so subsequent boots come up on the same port.

Step 3 · Open the admin URL

Paste the URL from the banner into your browser. You'll land on the install overlay immediately — login is locked until install finishes.

Install · 1 / 5
Welcome screen

First screen on the overlay. Paste the boot password here.

Install · 2 / 5
Pick the node's role

This is the key branch point. Pick the one that describes what THIS specific server is going to do:

Install · 3 / 5
Name this server

Give your server a display name (appears in the admin panel header, Discord embeds, the Hub page, in-game chat prefixes) and set the currency names. Everything here is free-form and editable later from Settings.

Install · 4 / 5
Admin account

Set an admin password AND/OR link your Steam account. You need at least one or you'll lock yourself out of the admin panel after install.

Install · 5 / 5
Done

Success screen. You're in.

Adding a periphery

Peripheries are secondary 7DTD servers that share admin list + wallets + shop + plugin state with a controller. They don't have their own admin panel; admins log into the controller and use the sidebar server-switcher to manage them remotely.

Flow at a glance:

1. Drop the mod into the periphery's Mods/ (same as step 1 of the controller).
2. Boot. Grab the periphery's own one-time boot password from its console.
3. Open the periphery's admin URL, complete install overlay screens 1 & 2 (pick Periphery).
4. Enter the controller's URL. Periphery sends you to the controller's browser page.
5. Controller admin approves. Periphery finalises itself automatically — no copy-paste of enrollment codes.

Periphery install · 3 / 5
Point at the controller

Replaces the Server identity screen on a periphery install. You enter the controller's URL, periphery does port-hunt detection + bounces you to the controller.

When you click Open controller, the periphery saves your choice in node.json, then redirects your browser to the controller's URL with a deep-link (#action=join-periphery&pin=XXXXXX). Your Steam session survives the OAuth bounce if you're already signed in on the controller.

On the controller
Approve the pending periphery

You arrive at the controller's browser with a prompt to approve the incoming periphery. What you see:

Click Approve. The controller signs an enrollment code with its shared secret and POSTs it back to the periphery's /api/install/accept-enrollment. No copy-paste.

Back on the periphery
Auto-finalise

Once the controller approves, the periphery's own install overlay flips to the success screen — same visual as screen 5 of the controller install, but with the periphery's identity:

Verify the link

On the controller's Nodes page, your new periphery shows up with a 🟢 online dot, its display name, its nodeId, AdminPort, and last seen timestamp that updates every 3 s. In the sidebar server-switcher dropdown, the periphery joins the list with a matching 🟢/🔴 status indicator.

What to do if…

… the boot password isn't printing

Install's already been completed and RefugeBot is in normal mode. Look at your admin panel — if it shows a login form (not the install overlay) then you don't need a boot password, you need the admin password or a Steam sign-in. To force a re-install: stop the server, delete RefugeBotData/refugebot.json, restart. A fresh boot password will print.

… I can't reach the admin URL

• Search the console for Web UI started on port. The number after port is what you want, not assume 8484.
• Docker bind-mount missing? docker exec <container> ls /AMP/…/Mods/zzzzzzzRefugeBot should list RefugeBot.dll. Empty = the mount didn't land.
• Firewall. 8484 (or the hunted port) needs to be open.

… the periphery says "Can't reach controller"

• Ping from the periphery's host to the controller's address first. curl http://<controller>:8484/api/refugebot-probe should return a JSON blob.
• Docker-on-Linux: 127.0.0.1 inside the container is not the host. Use the LAN IP or the Docker bridge IP (172.17.0.1 on default Linux setups).
• If the controller's port-hunted off 8484, the periphery tries ±20 around that number automatically. But it tries the BASE port first, then fans out — if you're on a very non-default port, put the full URL including port in the field.

… approval never shows up on the controller

The periphery's dial-in hits the controller's /api/install/request-enrollment. Check the controller's log for [RefugeBot] Periphery dial-in lines. No line = periphery can't reach the controller; firewall/port issue. Line present but no UI row = hard refresh the controller browser (Ctrl+Shift+R) — the Nodes page polls every 15 s but the approvals list is eager.

… I picked the wrong role

Nodes → This Node → change role. Converting Hybrid ↔ Periphery requires a restart to re-wire the service (the periphery polling thread and the controller approval listener are exclusive), but the data's preserved.

… I forgot my admin password

If you have Steam linked, just sign in that way and reset via Settings → Admin password. If neither works, SSH into the server and run sqlite3 RefugeBotData/refugebot.db "DELETE FROM admins WHERE role='owner'", delete RefugeBotData/refugebot.json, restart. Install flow re-arms.

Economy commands

Shop commands

You can also browse and purchase from the web shop — the in-game commands below are the classic way.

Teleport commands

Personal teleports let you save locations and jump to them with a short delay. Your slot count depends on donor tier.

Fight Arena

A 5-zombie survival challenge. Pay 50 coins to enter; survive five zombies (screamer, spider, cop, lumberjack, dog) in a 25-block radius arena to win 150 coins. Dying puts you on a 1-hour cooldown.

Slots

A simple slot machine with seven symbols. 3-of-a-kind pays out based on rarity (1.5x up to 50x for the jackpot). 2-of-a-kind pushes your bet back. Anything else is a loss.

Vehicle finders

Dropped your bike off a cliff? Use these to jump to your last-placed vehicle.

Donor commands

Role commands

Special roles (assigned by admins) grant supply drop commands that players of that role can run for themselves a few times per day.

Discord linking

Link your 7DTD character to your Discord account so the bot can sync donor roles and attribute bridged chat.

Utility commands

Web shop

The player web shop lives at /shop on this same server. It's themed to match the game and uses Steam OpenID to sign you in.

Signing in

1. Join the game at least once so RefugeBot knows your Steam ID.
2. Visit /shop. Click Sign in through Steam.
3. Steam asks you to approve access. Once you do, you're redirected back signed in.

Balance & profile

The default Player tab shows:

• Your character portrait (based on archetype + gender, sourced from character_portraits/)
• Current coin and gold balance
• Donor tier + multiplier
• Role (if any)
• Playtime, zombie kills, bloodmoons survived

Buying items

On the Shop tab you'll see coin-shop items up top and gold-shop items below. Each item shows its icon, name, quantity, and price.

Click Buy. The server deducts the price and queues the item for delivery. If you're online, it lands in your inventory via giveplus within a second. If you're offline, the purchase is stored as a pending delivery and arrives the next time you spawn in.

Cross-server shop

If the server you're on is part of a cluster (a Controller plus one or more Peripheries), the Shop tab gains a “Shopping for” dropdown. Pick any sibling server and browse its catalog right from here — icons and prices come from the target server over the cluster's proxy bearer.

When you click Buy on a cross-server item:

1. Your wallet on this server is debited at the remote server's authoritative price (the Controller probes the target's catalog live, so an out-of-date UI can't cheat the price).
2. The target server queues the item for you. If you happen to be online there right now, it delivers immediately. Otherwise the next time you log into that server it lands in your inventory.
3. If the target refuses the handoff for any reason, the full amount refunds automatically.

Cross-server icons are cached in RAM on the Controller (24 h TTL, 500-entry LRU) so repeated browsing doesn't hammer the target's file pipeline.

Pending deliveries

Items bought while offline (or bought for another server) queue up in your Pending Deliveries card. It lives in two places:

• Profile tab: a full card with each queued item, quantity, quality badge, “queued <time>” line, and a pill showing which server it's going to (cyan pill = this server, amber pill = another server).
• Server Shop tab: a one-line strip above the shop grid summarising up to 3 items with their target server. Click the strip to jump to Profile for the full list.

Each row shows the item, quantity/quality, when it was queued, and the target server so you know where to log in to claim it. Delivery happens automatically on your next login to that server.

Your bazaar

A bazaar is your personal player-run shop where other players can buy items from you. Set one up in the My Bazaar tab.

Setting up

1. Give it a name and description.
2. Optionally upload a banner (recommended ~16:7 aspect ratio). Banners render at the top of your bazaar listing.
3. Choose whether you accept coins, gold, or both.
4. Toggle it active when you're ready for customers.

Listing items

To list an item you own:

1. Pick the item from your inventory list.
2. Set quantity and price (coins and/or gold).
3. The server kicks you briefly so it can remove the items from your inventory safely (via PrismaCore's rii command). Rejoin and you'll see the listing live.

When someone buys

The item is delivered to the buyer immediately (or queued if offline). The coin/gold price lands in your bazaar's pending payouts queue. You receive it automatically the next time you spawn in.

Browsing bazaars

The Bazaar tab shows every active player bazaar on the server. Each tile shows the banner (or placeholder) plus the owner's name. Click one to see listings.

From the detail page you can buy items directly. Prices are shown in whatever currencies the seller accepts.

The tab hides itself if the server admin has disabled bazaars (Economy plugin → bazaar_enabled).

Teleports tab

Lists your saved in-game teleports. You can:

• Go — queues an in-game /tp (takes effect next time you're in game)
• Delete — removes the teleport
• Add — set a new teleport by coordinates

Slot limits match the in-game limits based on your donor tier.

Notifications

The notifications feed shows server-level announcements, admin messages sent directly to you, bazaar sale confirmations, and any other player-relevant events. Read notifications are remembered per-device.

Themes & appearance

Click the palette icon in the top-right of the Hub hero (next to Guide / Sign-out) to open the theme drawer. Ten structural themes ship by default — not just colour swaps, each one changes geometry, borders, shadows, typography:

• Cyan Glass (default) — deep-space + cyan glow + ember accent, glass-morphism panels.
• Ember — warm amber on dark walnut, softer edges.
• Forest / Violet / Crimson — palette variants.
• Obsidian — solid black with sharper lines.
• Industrial — scanline overlay, blocky panels.
• Frostglass — heavy blur, translucent surfaces.
• Cyberdeck — clip-path bevels, neon.
• Vaporwave — pink/teal gradient, retro grid.

The choice persists per browser (localStorage.hub.theme) so players on their own devices can pick whatever matches their vibe without affecting anyone else.

Donor tiers

Four tiers unlock increasing perks:

Perks & pack

Donor tier grants:

• Coin multiplier applied to all sources — playtime, zombie kills, daily, gimme, slots, bloodmoon.
• One-time coin + gold bonus delivered instantly on activation.
• Donor pack claimable once via /donor: Sarah's treasure map, Taylor's treasure map, wood bundle, skill magazine bundle ×2, 9mm ammo ×300, 7.62 ammo ×300, first aid kit ×2.
• Extra teleport slots (6/9/12/15 vs. 3 base).
• Custom chat color via /chatcolor and /pickcolor.

Activating your donation

If you donate through Refuge's Donorbox, your donation sits in a pending queue keyed by your Steam ID (if you included it in the donation comment) or your in-game name.

Run /donoractivate in-game. RefugeBot checks the pending queue, matches your account, and promotes you to the matching tier with an announcement in global chat and Discord.

Alternatively, admins can set your tier directly with /adddonor <you> <tier>.

Discord bridge

If the Discord plugin is connected, a specific Discord channel (the "bridge channel") is tied to in-game chat two ways:

• Anything you say in game gets posted to the bridge channel as <name>: <message>.
• Anything anyone says in the bridge channel appears in game as [Discord] <name>: <message>.

Server events (joins, leaves, deaths, fight arena, bloodmoon survival, boot-up, shutdowns) post as rich embeds to the admin channel.

Discord slash commands

Authorized Discord users (set by the admin) can control the server from Discord using slash commands:

Role sync (Officer / Moderator / Donor)

If your Steam account is linked to your Discord via /linkdiscord, RefugeBot can keep your Discord roles and your RefugeBot permissions in sync bidirectionally. The mapping is configured by the server admin in the Discord plugin settings; each sync runs automatically every 5 minutes plus the first time you spawn in after an admin change.

What syncs

• Donor tier — holding a Bronze / Silver / Gold / Platinum role on Discord auto-grants the matching donor tier in-game. Gets removed if the Discord role does.
• Admin tier — holding the server's configured Officer role auto-grants RefugeBot admin. Holding the Moderator role auto-grants moderator. Highest mapped role wins.
• Reverse direction — when a staff member grants you admin/moderator in the web panel, the bot adds the corresponding Discord role to your account; revoking removes it. Same applies to donor tiers (admin panel → Discord mirror).

The labels “Officer” and “Moderator” are just defaults — your server's staff hierarchy might use Captain, Sergeant, Crew Lead, whatever. The admin can rename the labels in Discord plugin settings; the rename is cosmetic (toast/log messages) and doesn't change the underlying behaviour.

Admin panel Admin

The admin panel is served at / on the same port as this guide (default 8484). It's protected by either the master password or Steam sign-in (if your Steam ID is on the admin list).

Signing in

1. Visit the root URL of the server. The login card appears.
2. Either enter the master password (default refuge2024, changeable in Settings → Web UI) or click Sign in with Steam.
3. Steam login only works if your Steam ID is already in the admins table — run /addadmin <you> in-game once as master-password admin to add yourself.

Dashboard

The landing page after sign-in. Surfaces:

• Hero row: Server FPS, players online, world entities (zombies + animals). Each includes a 2-minute sparkline.
• Server & System info: server name, public IP, game mode, world, version, host OS, CPU cores, current process RAM, runtime, uptime.
• Performance: CPU Load + Process RAM KPIs with short sparklines.
• Discord admin chat card: live two-way chat with the Discord channel you selected for admin chat. Type here → message posts to Discord as an embed with your Steam name.
• Online now: table of players currently online with a quick link into their detail page.
• Leaderboard: top 10 players by coins.

The page refreshes every 2.5 seconds. The Discord chat is rendered outside that refresh cycle so typing isn't interrupted.

Players

Full player database. Filter by name or Steam ID, click View on any row to open the detail page.

The detail page shows:

• Character card (portrait, archetype, gender). Live read when online, DB cache or .ttp parse when offline.
• KPI row: coins, gold, multiplier, kills, bloodmoons, playtime. Level shown when online.
• Identity: Steam ID, EOS ID, entity ID, IP (when online).
• Economy controls: grant/remove coins and gold, set donor tier, set role, clear pack usage, clear fight arena state.
• Activity feed: recent commands, shop purchases, bazaar sales.
• Inventory viewer: live snapshot of belt / bag / equipment (auto-refreshed every ~3 minutes, or force-refresh button).
• Staff actions: kick, ban, unban, mute, kill, set chat name, send PM.

Online

Real-time list of players currently connected. Useful when you want to act on an online-only player (kick, teleport, give item) without searching the full database.

Admins

Manage admin Steam IDs. Add, remove, or view the list. Adding yourself via in-game /addadmin <steamId> works too (and is how you bootstrap once you've set the master password).

Commands

History of every chat command executed on the server: timestamp, player, command name, args. Searchable. Useful for auditing who ran what when.

Console

Execute raw server console commands from the web. Output streams back in real time. History is scrollable. Autoscroll is toggleable.

Files

File browser rooted at the server save game directory. Navigate, upload, download, or delete files. Useful for grabbing region files manually, copying player .ttp files, or editing configs.

Prefabs

Browse the POI prefab library. Search/filter by name, narrow by tier (1 through 5 plus unknown), toggle whether test/dev prefabs are included.

Each prefab has a preview image (if found in prefab_images/). Click one to:

• View full metadata (size, tier, tags)
• Place it at coordinates you specify, with optional rotation, "no sleepers", and "add to RWG" flags
• Undo a placement (rolls the chunks back to pre-placement state)
• Review placement history

Items

Master list of every item in the game. Useful for building shop entries, figuring out the exact item name for a /give command, or looking up icons.

In-game Panel editor

The in-game ESC panel (the info panel players see when they hit ESC) has four tabs. Shops (tabs 2 & 3) auto-generate from your shop items. Tabs 1 (Welcome / Rules) and 4 (Links) are free-form.

Edit header title, motto, subtitle bar, tab button text, tab header title, and the free-form content for tabs 1 and 4. Use \n for newlines and 7DTD color codes ([ff0000]red[-]) for colors.

Shop editor

Edit the coin shop (22 items) and gold shop (3 items). Add/remove items, set prices, update descriptions. Changes live immediately.

Items you add here are automatically included in the in-game Panel tabs 2/3 at next regeneration.

Settings

Edit refugebot.json live. Sections:

• General: server name, coin/gold display names, master password, vote API key.
• Web UI: public base URL (for reverse proxy), port, password, enable/disable password & Steam login independently.
• Server Dependencies: PrismaCore and Allocs Fixes detection + install buttons.
• Region Fix: Off / Notify / AutoFix mode (see Region Fixer). Includes a "Scan Regions Now" button.
• Data Storage: read-only display of where refugebot.db and refugebot.json live.
• User Preferences: per-browser settings — theme, accent color, console follow default, compact layout.

Changes are saved to disk and applied immediately. Discord bot fields live in the Discord plugin's "Bot Connection" section to keep related config together.

Map & region tools Admin

The Map page renders your world using TFP's MapRendering data (tiles) plus an overlay for 7DTD's region files (each .7rg covers 512×512 blocks).

At a glance:

• Center viewport shows rendered tiles; pan with mouse drag, zoom with wheel.
• Toolbar: Uncover Map (full visitmap), Refresh, Zoom ± buttons, Center, Region Grid, Select Mode, Backups, region search.
• Legend: toggle Players / Vehicles layers.

Region grid

Toggle Region Grid on the toolbar. Each cell covers a 512×512 world-block region. Cells are clamped to the bounding box of regions that actually exist on disk (+ 1-cell padding) so the grid doesn't extend past the playable map.

Colors:

• Copper fill — region file exists
• Muted bronze — region file missing (unexplored)
• Amber — highlighted from search
• Blue — selected in select-mode

Hovering shows the filename (r.X.Z.7rg). Labels on each cell show the full filename when cells are large enough to read.

Search & download

The search input accepts:

• r.3.-2 or r.3.-2.7rg — exact region filename
• 3,-2 or 3 -2 — world-block coordinates that resolve to a region

A popup shows the matched region with a Download button that hands you the raw .7rg file. The grid highlights the matched region in amber so you can see where it sits on the map.

Select mode

Toggle Select Mode to click region cells on the grid. Selected cells turn blue. Use this to pick a batch of regions for:

• Download as ZIP — hands you a zip of all selected .7rg files.
• Save as backup set — gives the selection a name and creates a named set the backup system uses (see next section).

Region backup sets

A backup set is a named group of regions. You tell RefugeBot which regions you care about (your base, spawn, a trader POI) and it manages snapshots of them.

Each set has:

• Name (your chosen label)
• List of regions (by rx,rz)
• Auto-backup toggle (default on)
• Snapshot history

Create a set from the Map page: select regions in Select Mode → click Save as backup set → name it. Manage existing sets from the Backups button in the map toolbar.

Hourly auto-backup

Every 60 minutes, RefugeBot snapshots every auto-enabled set. Snapshots land in {DataDir}/region_backups/{setName}/snapshot_{timestamp}/.

Retention is 5 days — older snapshots are pruned automatically. Manual snapshots (triggered from the UI) are also pruned.

Snapshot safety: the copier captures the file mtime before and after each copy. If the game wrote to the file mid-copy (races with world saves), the copy is retried once. This avoids snapshotting half-written regions.

Restoring

From the Backups panel, pick a set, pick a snapshot, click Restore. RefugeBot copies the snapshot's .7rg files back into the live Region/ folder, overwriting existing files.

Restore reports a summary: regions restored, regions missing from the snapshot (not in the set at that time), any files that failed to copy.

Region Fixer

7DTD occasionally corrupts region files ("Incorrect region file header!" in the console). The fixer detects this and — depending on mode — alerts you or auto-fixes.

Modes (Settings → Region Fix → Mode):

• Off — no detection, no fixing.
• Notify — console watcher logs an alert banner with manual fix buttons. You decide when to act.
• AutoFix — detects, backs up the broken file, rewrites the header, and initiates a graceful shutdown (7DTD needs a restart to reload a fixed region).

Scan Regions Now button triggers a one-shot scan: reports scanned count, healthy, corrupted, auto-fix success/failure.

Boot scan runs on server start if mode is Notify or AutoFix. The result can be included in the Server Ready Discord embed.

Plugins Admin

RefugeBot's features are split across plugins that can be individually enabled/disabled and configured. The Plugins page lists each one, shows its description, and exposes a gear icon that opens its settings modal.

Toggling a plugin off while the server is running:

• Calls the plugin's OnDisable() hook (stops timers, closes connections)
• Disables the commands the plugin owns (they respond with "This feature is disabled")
• Sometimes sends a Discord notice (e.g. Discord plugin itself announces its state change)

Toggling back on calls OnEnable(). Neither toggle requires a server restart.

Discord plugin

Owns all Discord integration: bot connection, two-way chat bridge, slash commands, donor + admin role sync, channel-assign notices, per-periphery bridges, server event embeds.

See the dedicated Discord setup sub-sections below for step-by-step bot creation, intents, invite permissions, channel mapping, and role sync — it's broken out so you can link a staff member straight to whichever piece they need.

Event embed toggles

• attach_boot_log — include a boot log .txt on the Server Ready embed
• send_ready_embed — post the Server Ready embed
• send_shutdown_embed — post a Server Shutdown embed
• send_join_leave — post player join/leave embeds
• send_deaths — post death embeds
• send_region_scan — include region-scan results in Server Ready

Discord setup Admin

1 · Create the application & bot

1. Go to discord.com/developers/applications → New Application. Name it anything (“RefugeBot” is fine).
2. Under the Bot tab, the bot identity is created automatically. Upload an avatar if you like.
3. Click Reset Token and copy the token. Paste it into Plugins → Discord → Bot Token and hit Save connection & channels.

2 · Privileged Gateway Intents Required

Most-common missed step. In the Developer Portal, under Bot → Privileged Gateway Intents, flip ON:

Save at the bottom of the Developer Portal page. No restart needed on Discord's side; the bot picks up the new intents on its next connect.

3 · Invite & permissions

OAuth2 → URL Generator in the Developer Portal.

Under Scopes check:

• bot
• applications.commands

Under Bot Permissions check:

• View Channel
• Send Messages
• Embed Links
• Read Message History
• Manage Roles — required for donor + admin role push
• Use Application Commands
• Attach Files (optional — used for boot-log attachments)

Copy the generated URL, open it, pick your guild, authorise.

4 · Channel mapping & embed notices

Once the bot token is saved and the guild is picked, four dropdowns populate in the top half of the Discord settings modal:

• Admin Channel — server events, death feed, fight arena outcomes, admin notices.
• Bridge Channel — two-way in-game ↔ Discord chat bridge for this server.
• Status Channel — public server status (keeps admin noise out of public view).
• Admin Chat Channel — the channel that powers the Dashboard's Discord chat card.

Click the “Save connection & channels” button under the Admin Chat dropdown. This performs a partial save of just this section — the modal's bottom Save-settings button still works for saving all Discord sub-settings in one shot.

Channel-assigned confirmation embed

Any time you change one of these four channel assignments and save, the bot posts a one-time confirmation embed to the newly-assigned channel:

✅ Channel assigned: Admin Channel
This channel is now the Admin Channel for <Server name>.

Re-saving with unchanged channels is silent. Fires only on actual change — this is how you verify the bot can actually reach a channel without digging through logs. If you save a channel and no embed appears, check View Channel + Send Messages + Embed Links on the bot's role in that channel.

5 · Per-periphery bridge channels (Controller only)

In a cluster, each periphery gets its own Discord bridge channel so chat from different game servers doesn't fuse into one wall. On the Controller's Discord settings modal, scroll to the Per-Server bridge channels section. One row per connected periphery:

Pick a channel from the dropdown (populated from the same guild) and hit Save. Same change-detected embed notice fires to the new channel:

✅ Channel assigned: Bridge Channel
This channel is now the Bridge Channel for Day 8.

The periphery picks up the new assignment on its next cluster poll (≤3 s). Clearing the channel (empty selection) disables the bridge for that server — no notification fires on clear.

6 · Admin & donor role mapping

Two sections in the Discord modal, one per tier family. Each maps a Discord role ID to a RefugeBot role.

Donor role mapping (4 tiers)

Bronze / Silver / Gold / Platinum dropdowns. Holding the mapped Discord role auto-grants the matching donor tier in-game every 5 min. Removing the role removes the tier (donor sync is fully bidirectional).

Admin role mapping (2 tiers)

Two dropdowns + two editable label fields:

• Admin-tier label (default “Officer”) + Discord role → RefugeBot admin
• Moderator-tier label (default “Moderator”) + Discord role → RefugeBot moderator

Rename the labels to match whatever your server calls its staff tiers (Captain / Sergeant / Crew Lead / whatever). Labels are cosmetic — they show up in admin-panel toast messages and server logs (e.g. “Captain role granted on Discord”). The actual sync is role-ID-based.

What triggers a sync

• Discord → RefugeBot: periodic 5-min poll + on every player login. Grants only (losing the role does not auto-revoke admin — see safety rail in Role sync).
• RefugeBot → Discord: any web-panel admin action (Make admin, Revoke admin, change role). Donor-tier changes from /adddonor / /removedonor. Both immediately push the Discord role change.

Highest mapped Discord role wins — a user with both Officer and Moderator ends up as RefugeBot admin, not moderator.

Cluster ops Admin

Controller & periphery model

A cluster is a Controller (Hybrid role — both admin panel and a game server) plus zero or more Peripheries (Periphery role — game servers that dial into the controller every 3 s). The controller is authoritative for:

• Admin list + role assignments
• Shop items + pack definitions
• Plugin on/off state
• Wallet balances in SharedWallet mode (config-dependent)

Peripheries replicate those via POST /api/node/pull-config every 3 s. They keep their own server name, WebUiPort, Discord bot token, and Discord bridge channel — those are intentionally node-local so different servers can have different chat-bridge channels, different ports, etc.

Admins sign into the controller's admin panel. A server switcher in the top-left sidebar picks which server's data you're viewing — proxy requests forward through the controller via a per-connection ProxyBearer so peripheries don't need individual sign-ins.

Cluster-wide admin XML sync

7DTD has its own serveradmin.xml at <UserDataFolder>/Saves/ — separate from RefugeBot's admin table. Each server keeps its own file; you want them in sync across the cluster so an in-game admin on the controller is also an in-game admin on every periphery.

RefugeBot handles this automatically now. Anytime an admin action changes the RefugeBot admin list:

• Make admin (web panel or /addadmin) → runs admin add <steamId> 0 "<name>" on the local game server, and fans out via ProxyBearer to every connected periphery to run it there too. Each server rewrites its own serveradmin.xml live — no restart needed.
• Revoke admin (Admins page) → symmetric: admin remove <steamId> on every node.

The admin-panel toast surfaces a per-server breakdown so you can see exactly which nodes succeeded:

Sync Geckoz: 2/2 server(s) OK
✓ Season 8 — added (level 0)
✓ Day 8 — added (level 0)

Cross-cluster shop routing

Two endpoints power the player-facing cross-server shop:

• GET /api/shop/items-cluster?server=<nodeId> — cookie-authed on the Controller. Self → local catalog; other → Controller fetches the target's public /api/shop/items via ProxyBearer and streams it back.
• POST /api/shop/buy-cluster?server=<nodeId> — Controller resolves authoritative price via a live probe (not the body), debits the wallet locally, POSTs a signed enqueue to the target's /api/shop/cluster-enqueue. Refunds on any post-debit failure.
• GET /api/shop/pending-cluster — aggregated undelivered purchases for the signed-in player across every periphery. Fans out in parallel, 60s staleness cutoff per node.

Icon caching lives on the Controller: 500-entry LRU, 24 h TTL, 512 KB body cap per icon. Saves the target's file pipeline from being hammered when a busy Hub tab switches between server catalogs.

HasCustomItems flag per-periphery — surfaced in the admin UI and as an amber "runs a different item set" banner on the player's cross-server catalog. Signals an overhaul mod or custom items that may not exist on the originating server.

Sidebar server switcher

Top-left dropdown in the admin panel sidebar (Controller only). Options:

• This server — direct, no proxy (fastest).
• Each connected periphery — selecting routes every admin-panel call through /api/proxy/<nodeId>/* using the per-connection ProxyBearer. You see the target's data as if logged in there.

Each entry has a status dot — 🟢 online (seen <15 s ago), 🔴 offline/stale. The list auto-refreshes every 15 s. Selecting a periphery only rewrites the proxy target for subsequent API calls — no page reload, no auth bounce.

Icons in the cross-server shop are always served from the Controller (a deliberate choice: proxying thousands of tiny icons saturates the host). Admin JSON calls + map-tile data fetches go through the proxy.

Master transfer (promote a periphery)

The ⭐ icon on the Nodes page next to any connected periphery is a live promote-to-controller button (owner-only).

1. Owner clicks ⭐ on a periphery row → confirm.
2. Controller exports cluster state, signs a handover packet with the cluster's shared secret, POSTs to the target periphery.
3. Target periphery imports the state, promotes itself to Hybrid.
4. Controller broadcasts a reroute to every OTHER periphery — they redial the new controller using their existing bearers (the shared secret matches).
5. Old controller self-demotes to Periphery on a background thread ~6.5 s after approval.

Zero-downtime handover: no periphery loses its connection for more than one polling cycle. Safe to use for planned maintenance (rolling the previous controller onto new hardware, etc.).

Economy plugin

Coins, gold, daily rewards, gimme, starter kits, voting, playtime tracking, shop command handlers, and player bazaars.

Settings:

• coins_per_minute (default 2)
• zombie_kill_coins (default 1)
• bloodmoon_bonus (default 500)
• daily_min / daily_max (defaults 50 / 150)
• daily_cooldown_hours (default 24)
• gimme_cooldown_hours (default 6)
• bazaar_enabled (default true) — flipping this off hides bazaars for players and returns 503 on all bazaar endpoints

Teleport plugin

Settings: delay seconds, adventure X/Z bounds, adventure Y (altitude), per-tier slot limits (base / T1 / T2 / T3 / T4). Tier slot limits are enforced server-side in /settp; the web shop's Teleports tab reflects them in the add-teleport UI.

Announcements plugin

Rotating server messages posted on a timer.

Each announcement has a Game version (uses 7DTD color codes) and a Discord version (Markdown). Leave one side blank to skip that channel for that message.

Settings:

• interval_minutes — minutes between cycles (default 5)
• mirror_to_discord — whether Discord versions post (default true)
• Announcements list — edited through a dedicated editor with per-row "split mode" (when Game and Discord differ)

Voting plugin

Grants coins to players who vote for the server on 7daystodie-servers.com.

Settings:

• api_key — your vote API key from 7daystodie-servers.com
• coins_reward — coins per confirmed vote
• vote_url — public voting URL shown to players

Fight Arena plugin

Settings: entry cost, win reward, kills needed (default 5), arena radius, cooldown on death, confirmation TTL. Arena zombies and chat announcements are hardcoded for now.

Slots plugin

No settings panel — the 7-symbol payout table is baked in. Toggle the plugin off to disable the /slots command entirely.

Vehicle Finder plugin

Tracks vehicle placement and provides /findbike, /find4x4, /findgyro, /finddrone. No settings.

Lua scripting plugins

Drop .lua files into {DataDir}/LuaPlugins/ and they're picked up at boot (and can be rescanned from the Plugins page). Each Lua plugin runs in a sandboxed MoonSharp interpreter with a limited API surface:

• setting(key, default) — read a setting declared in the plugin's settings table
• say(msg), broadcast(msg), announce(text), player:pm(msg) — broadcast / PM
• find_player(query), list_online(), search_players(query) — player lookup
• get_leaderboard(kind, n), get_shop_items(type), get_bazaar(steam_id), get_inventory(steam_id) — read server state
• get_discord_id(steam_id), is_discord_linked(steam_id), discord_send(channel, msg) — Discord integration
• queue_purchase(steam_id, item, qty, quality), player:queue_wipe(section), player:set_role(role) — offline-safe writes
• Event hooks: on_player_join, on_player_disconnect, on_chat_message, on_zombie_kill, on_player_death, on_bloodmoon_end, on_shop_purchase, on_discord_link, on_command
• Full API reference lives in the admin panel → Plugins → Lua API Reference button.

Lua plugins appear in the Plugins page the same as built-in ones once installed. The editor (in the admin panel) lets you view and edit the source, plus an AI-assist panel for writing new ones.

Dependencies Admin

RefugeBot leans on two third-party mods for functionality we don't want to reimplement. The Settings page auto-detects both and offers one-click install.

PrismaCore

Provides the console commands rii (remove items from inventory), wi (wipe inventory), and showinventory / si. We use these for the bazaar (removing items from seller's inventory when they list), inventory snapshots, and admin "wipe inventory" actions.

Detection tolerates renamed folders — admins often prefix Prisma's folder with zzzz to control load order. RefugeBot scans every folder in Mods/ and accepts a hit if it contains a PrismaCore*.dll OR its ModInfo.xml Name field mentions "Prisma".

Source: github.com/Prisma501/PrismaCore/releases

Allocs Fixes

Bundle of three mods: Allocs_CommandExtensions, Allocs_WebAndMapRendering, Alloc_XmlPatch. Provides extra console commands used by many other mods, plus an older version of the map renderer.

If TFP's own TFP_MapRendering and TFP_WebServer mods are installed, the detection surfaces a conflict warning — Allocs's web/map components can clash with TFP's newer versions.

Source: illy.bz/fi/7dtd/server_fixes.tar.gz (always latest)

Auto-install flow

From Settings → Server Dependencies, each card shows:

• Current status (Installed / Missing)
• Detected version (parsed from ModInfo.xml)
• Install path (so you know where it actually lives, renamed or not)
• Install or Reinstall latest button

Clicking install:

1. Backs up any existing matching folder to <name>.bak-<timestamp>
2. Downloads the latest archive (GitHub API for PrismaCore, fixed URL for Allocs)
3. Validates magic bytes (never unpack a 404 HTML page)
4. Extracts (ZipFile for .zip, system tar for .tar.gz)
5. Reports success and prompts for a server restart (DLLs can't hot-reload)

Operations Admin

Config files

RefugeBot stores everything in one directory, resolved from the mod DLL's location: walk up two levels to find the game root, then {GameRoot}/RefugeBotData/.

Contents:

• refugebot.json — all live configuration (server name, Discord, economy, etc). Edited via the Settings page or directly on disk.
• refugebot.db — SQLite database: players, teleports, bazaars, banners (BLOB), notifications, admin list, transaction log, vote history, panel settings.
• region_backups/ — hourly + manual region snapshots.
• LuaPlugins/ — user-installed Lua scripts.

On first boot, RefugeBot checks for legacy refugebot.json / refugebot.db in the Mods folder and copies them into RefugeBotData/ (for upgrades from older layouts).

Data directory layout

{GameRoot}/
├─ 7DaysToDieServer.x86_64  (or 7DaysToDie.exe on client)
├─ Mods/
│  ├─ 0_TFP_Harmony/         ← required (TFP ships it)
│  ├─ TFP_MapRendering/      ← required on dedicated server
│  ├─ TFP_WebServer/         ← required on dedicated server
│  ├─ zzzzzzzPrismaCore/     ← third-party (zzzz prefix for load order)
│  ├─ zzzzzzzAllocs_*/       ← third-party Allocs bundle
│  └─ zzzzzzzRefugeBot/      ← RefugeBot lives here
│     ├─ RefugeBot.dll
│     ├─ MoonSharp.Interpreter.dll
│     ├─ ModInfo.xml
│     ├─ Config/
│     │  ├─ XUi/xui.xml
│     │  ├─ XUi/windows.xml
│     │  └─ Localization.txt
│     ├─ character_portraits/*.png
│     └─ (banner, wallpaper, button images)
└─ RefugeBotData/            ← writable data
   ├─ refugebot.json
   ├─ refugebot.db
   ├─ LuaPlugins/*.lua
   └─ region_backups/{set}/snapshot_{ts}/

Troubleshooting

Web UI won't load

• Check the console for [RefugeBot] Web UI started on port 8484 at boot.
• If the port is in use, change it in Settings → Web UI → Port and restart.
• Firewall: make sure 8484 is open.

Login page flashes or looks weird

If the Steam login button is missing: check Settings → Web UI → "Allow Steam login" is on. The admin panel now prints a small hint beneath the password form when Steam is disabled.

Bazaar banner upload fails silently

This was caused by an old SQLite binding bug (bytes were stringified); fixed in the current build. If you're on an older build, update.

PrismaCore commands report "unknown command"

Your PrismaCore version is older than 2.2 (which introduced rii). Update via Settings → Server Dependencies → Reinstall latest.

Discord bot events aren't posting

• Verify the bot token is correct (Settings → Plugins → Discord → Bot Connection → the status line).
• Verify the bot has Send Messages + Embed Links in the target channels.
• Toggle the Discord plugin off and back on — this forces a reconfigure.

Connection-lost overlay keeps appearing

If the overlay shows repeatedly, the server is probably restarting or the process crashed. Check the server console logs. The web UI recovers automatically once /api/status responds again.