Repository navigation
Discord Integration
ServerGuard supports two independent Discord webhooks: a public channel and an admin channel. Either, both, or neither may be set.
Player-facing events only. Safe to share with your whole community.
| Event | Example |
|---|---|
| Player joined | β
Erik (76561198064360681) joined |
| Player left | π Erik (76561198064360681) left |
| Player kicked | πͺ Erik (76561198064360681) was kicked β wrong password |
| Player auto-banned | β Erik (76561198064360681) was auto-banned β too many strikes |
| Player died | π Erik (76561198064360681) died at [-1234, 567] β killed by a Troll |
| Player shouted | π£ **Erik** shouted: they're at the docks! |
| Raid started | βοΈ **The Horde Is Attacking** has started! Location: X:123, Z:-456 |
| Raid paused / resumed | βΈοΈ **The Horde Is Attacking** is paused β no players in the event area. |
| Raid ended | β
**The Horde Is Attacking** is over! |
| Server starting | β³ **Server is starting...** |
| Server ready | β
**The server has started, you may now login.** |
| Server stopping | π **Server is shutting down.** |
| First boss kill (2.1) |
βοΈ Alice and Bob defeated **The Elder** for the first time! (real bosses only; staff left out) |
The three server-lifecycle messages have no on/off setting β like raid alerts, they follow discordWebhookUrl.
"Starting" and "started" are two separate messages on purpose. The plugin loads long before the world does, so "starting" fires immediately on boot, and "you may now login" only once the world is loaded and location generation has finished β which on a brand-new seed can be several minutes later. Players who join on the first message would just be refused.
If world generation somehow never completes, no public "started" message is sent; a timeout warning goes to the admin channel instead after 15 minutes.
The shutdown message needs a graceful stop (console stop, service stop, window close). A SIGKILL, power loss, or host crash gives the plugin no chance to post.
Admins are hidden from this channel. Their joins, leaves, deaths, and kicks all route to the admin channel instead. Players never see admins coming and going.
To show staff logins publicly, set discordPublicStaffLogins: true (2.5). Owners' and moderators' joins (joined as owner, joined as moderator) and leaves then go to both channels. Their deaths and kicks still go to the admin channel only.
Curated moderation events. Use a private channel that only moderators can see.
| Event | Example |
|---|---|
| Server boot | π ServerGuard online v2.5.0 enforce=ON requireHmac=ON req/allow/ban=1/29/0 modset=8ce8906e |
| Staff dev command run server-side (2.0) |
π§ **Erik (765β¦)** (owner) ran server command \skiptime 1800`` |
| Cheat-flagged items reported (2.0) | π§ͺ **Erik (765β¦)** is carrying **3** cheat-flagged item(s): SwordIron, Wood x64 |
| Debug fly detected (2.0) |
ποΈ Erik (765β¦) is using debug fly (public channel) |
| Moderator tried an unlisted dev command (2.0) |
π« **Erik (765β¦)** (moderator) tried dev command \spawn` β not in `moderatorDevcommands`` |
| Hot-reload | π allowed_mods.yaml reloaded β req=1 allow=29 ban=0 |
| Counted violation | β οΈ Erik (765β¦) violated DevcommandAttempt (1/3) β fly |
| Informational rule | π Erik (765β¦) triggered HashMismatch (informational β not counted) β Jotunn |
| Auto-ban | β Auto-banned Erik (765β¦) (threshold reached) |
| Manual kick | πͺ Disconnected Erik (765β¦) β Kicked by admin. |
| Admin command | π Erik (765β¦) ran sg kick someone |
| Admin player events | π‘ Erik (765β¦) joined as admin |
| First ping (if enabled) | π° Erik (765β¦) first ping: 42 ms |
| Session avg ping | π° Erik (765β¦) session ping avg: 38 ms (24 samples) |
| Daily summary | A one-paragraph digest at the configured UTC hour |
| Progress credited (2.1) | π **The Elder** credited to Alice (765β¦), Bob (765β¦) β nearby without damage: Carl |
| Progress the server never granted (2.1) | β οΈ **Erik (765β¦)** arrived carrying progress this server never granted (Eikthyr) |
| Progress reset by a mod (2.2) | β»οΈ Progress reset (BlΓ³t RagnarΓΆk): cleared 42 entries on 9 characters. |
| Inventory sealed / unsealed / expired (2.2) |
π Sealed the inventories of 3 account(s) β¦ / π Unsealed β¦
|
| Sealed player brought items from elsewhere (2.2) | π **Erik (765β¦)** (Erik) arrived with 2 item type(s) from another world - removed (β¦): SwordIron x1, Wood x30 |
| Watch page (2.3) |
π°οΈ Watch page opened by **Erik (765β¦)** (key ab12cd) from 1.2.3.4 Β· π β¦ created watch-page key Β· π οΈ β¦ ran sg kick β¦ (watch page) Β· π¨ Watch page: 10 wrong keys from 1.2.3.4 - blocked
|
API test listener (2.2, sg test listen)
|
π§ͺ API event ProgressCredited(765β¦, **Erik**, defeated_eikthyr) |
See Personal Progression for when progress posts appear (progressionDiscordPosts).
Forwards every ServerGuard log line to the admin channel. Very noisy β debug only.
In Discord:
- Open your server settings β Integrations β Webhooks.
- Create a new webhook in the channel where you want events to appear.
- Copy the URL.
- Paste into
settings.yaml:
discordWebhookUrl: 'https://discord.com/api/webhooks/...' # public
discordWebhookUrlAdmin: 'https://discord.com/api/webhooks/...' # admin- Save. Hot-reload picks it up β no restart needed.
If only one URL is configured, all events that would route to the other channel are silently suppressed.
A coroutine fires once per UTC day and posts a digest:
π Daily summary
2026-05-29 00:00 UTC β 2026-05-30 00:00 UTC
β’ Joins: 14
β’ Leaves: 12
β’ Kicks: 3
β’ Auto-bans: 1
Top kick reasons:
β wrong password (2)
β had a mod that isn't allowed (BiggerBackpack) (1)
Configure:
dailySummaryEnabled: true
dailySummaryHourUtc: 0 # 0..23 - hour at which the post fires
dailySummaryChannel: admin # public | admin | bothIf no events occurred, the scheduled post is silently skipped (no spam).
The public channel uses non-technical language. Internal rule names like HmacInvalid, DisallowedMod, ChallengeMismatch are translated:
-
HmacInvalidβ "wrong password" -
CompanionMissingβ "missing the required companion mod" -
RequiredModMissingβ "missing a required mod (Name)" -
DisallowedModβ "had a mod that isn't allowed (Name)" -
BannedModβ "had a banned mod (Name)" -
HashMismatchβ "mod file doesn't match the server's copy (Name)" -
CharacterNameLimitExceededβ "tried to use too many characters"
The admin channel keeps the technical rule name so moderators can correlate to log lines.
If you accidentally point both URLs at the same channel and don't want duplicates: set dailySummaryChannel: admin (or public) instead of both, and don't enable discordVerboseMirror.
- Configuration β all webhook settings.
- Anti-Cheat Features β rules that fire Discord events.
-
Admin Commands β
sgevents that post to admin channel.