Unfugwart
Unfugwart starts mapped PufferPanel games when humans join configured Discord voice channels and gracefully stops them ten minutes after the last confirmed human leaves.
Setup
Copy config.example.json to ignored config.json and replace credential placeholders.
Use https://games.bugabinga.net as panelUrl.
Create a dedicated non-admin PufferPanel bot user with only the intended game-server permissions, then create its OAuth2 client.
Required permissions for every game are server.status, server.start, and server.stop.
The Valheim telemetry profile additionally needs server.console; generic servers do not read console logs.
Inspected PufferPanel authorization follows the client owner's permissions; do not rely on an administrator-owned client as a narrow security boundary.
Do not grant a client access to PufferPanel server 61b39066 because configuration rejects that self-target.
Invite bot with View Channels, Send Messages, Embed Links, and Read Message History for each status text channel.
For configured voice-channel status, grant Set Voice Channel Status and Manage Channels; bot does not join voice channels.
No Administrator permission or privileged Discord gateway intents required; bot code enables Guilds and Guild Voice States intents.
Install app-owned emojis on the Discord application for sleeping, starting, ready, saving, stopping, and valheim (or adventurer).
Missing or unavailable emojis fall back to Unicode without breaking controls.
Application-owned emojis require neither Nitro nor Use External Emojis.
Optional top-level emojiNames maps semantic slots to exact custom names.
Use /server with aktion:setup and ziel:valheim1 to refresh uploaded emojis and diagnose configuration.
Optional mapping field connectAddress must be a plain hostname/IP with optional port; never enter a password.
Keep config.json private with restrictive panel-file permissions because it contains Discord and OAuth credentials.
Discord setup
Each mapping uses displayName, statusChannelId, and controlRoleName; config.example.json includes these plus optional connectAddress.
Configured mapping status text channel: 1561151440205119508.
Create exactly one human role named Unfugwart per configured guild and assign it to members allowed to control mapped servers; role itself needs no special permissions.
A bot-managed role with that name does not count.
Set controlRoleName explicitly when retaining a different existing caretaker role.
Controls and slash commands: status refreshes observation; start requests start; 1 h wach halten holds server awake for at most one hour; stop requires requester-bound confirmation within one minute.
setup diagnoses Discord channels, effective permissions, human role, and app-owned emojis.
orakel returns harmless goblin wisdom without touching gameservers.
Status cards stay in one edited message; state and shutdown countdown come before the join address.
status returns the actual card privately rather than an update acknowledgement.
Setup, confirmations, outcomes, errors, and oracle replies share the same compact embed layout.
Existing technical-footer cards migrate in place without creating a duplicate.
Voice status includes a coarse idle countdown and keep-awake hint.
Start and hold cancel a pending idle shutdown; hold expiry returns to voice-based automation.
Stop overrides automatic start until the channel becomes empty and subsequently occupied again, or a caretaker explicitly starts the server.
Confirmed stop means stop request accepted, not process termination confirmed.
Controls are unavailable during startup, update, shutdown, or an active startup deadline.
Failed requests remain retryable; reported player counts never gate shutdown because log observations may be stale.
Game profiles
Every mapping controls its own server independently.
Set "game": "valheim" in the current Valheim mapping to enable readiness, save stages, SteamCMD progress, and last observed players.
The default "game": "generic" works with other PufferPanel servers using process status only.
Generic servers never interpret Valheim log lines or claim game readiness.
Neither server IDs nor display names select a game profile automatically.
Other game-specific telemetry profiles can be added to the small parser registry in telemetry.js.
Unknown profile names are rejected rather than silently using the wrong parser.
Generic presentation and default icons do not mention Valheim.
Optional mapping field gameEmojiName selects a game-specific application emoji by exact name; missing icons fall back to the generic adventurer.
Behaviour
Only confirmed non-bot voice states count as occupants.
A cached voice state lacking its member or user is unknown, never empty.
A cached available guild and mapped voice channel with no matching voice states is empty.
Unavailable guilds, missing or deleted channels, shard reconnects, shard disconnects, and unknown state cancel pending shutdowns synchronously.
ClientReady bootstraps cached mappings, while later ShardReady, ShardResume, GuildAvailable, and GuildCreate re-identify mappings from cache.
An occupied channel checks status then starts its stopped mapped server.
An empty channel starts one ten-minute grace timer and its callback checks status then invokes PufferPanel's graceful /stop endpoint.
Repeated empty updates preserve that timer, while any occupied or unknown transition invalidates it and a later empty transition gets a full new delay.
Lifecycle work remains serialized per mapping, with generation checks before and after status requests.
Stop dispatch rechecks validity after token acquisition and before every retry attempt.
A request already handed to HTTP transport cannot be retracted.
PufferPanel requests use bounded ten-second timeouts plus bounded retries.
Only one voice channel may map to a PufferPanel server, preventing independent shutdown timers from conflicting.
Displayed server player counts, when available, are last observed telemetry, not live occupancy; Discord voice occupancy is separate observation.
No game-player query exists, so no guarantee of player-empty shutdown; the existing ten-minute Discord voice-empty shutdown remains unchanged.
PufferPanel deployment
Paste complete settings.json into bot server 61b39066.
Upgrading from initial 37c2be7 requires repasting complete regenerated settings once to include dashboard modules.
The emoji polish uses the same installer as 5d13d2f; no further template change is required.
Update private deployed config.json by adding mapping fields displayName, statusChannelId, and controlRoleName from config.example.json; retain private credentials and do not publish them.
Before each install, stop bot, then select Install to download trunk archive and Start.
Install preserves config.json plus unrelated files.
If dependency installation fails, bot remains stopped; retry Install after correcting failure.
Bot container uses bridge networking with normal outbound HTTPS/WSS.
Relay already provides ingress, so no ports or firewall changes are needed.
settings.json is generated from embedded installer.js source.
Run node scripts/generate-settings.js after changing installer source; run node scripts/generate-settings.js --check to verify synchronization.
Tests
Run npm test.