# 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`.