# Moderation Bookshelf includes a full moderation system with infractions, vanish, social spy, and alt detection. All infractions are stored persistently and can optionally sync across servers via MongoDB and Redis. --- ## Infractions Overview An infraction is a moderation action taken against a player. Bookshelf supports five types: | Type | Persists After Rejoin | Has Duration | Acknowledgment | |---|---|---|---| | **Ban** | Yes — blocks login | Permanent or temporary | None | | **IP Ban** | Yes — blocks login by IP | Permanent or temporary | None | | **Mute** | Yes — blocks chat | Permanent or temporary | None | | **Warn** | Yes — blocks chat until acknowledged | Until acknowledged | Player must type "I understand" | | **Kick** | No — one-time removal | Instant | None | --- ## Bans ### Permanent Ban ``` /ban <player> [reason] ``` The player is immediately kicked and cannot rejoin until unbanned. ### Temporary Ban ``` /ban <player> [reason] -d <duration> /tempban <player> [reason] -d <duration> ``` The player is kicked and cannot rejoin until the duration expires or they are unbanned. ### Unban ``` /unban <player> ``` ### What Happens on Join When a player attempts to connect, Bookshelf checks (in order): 1. Direct ban on the player's UUID 2. IP ban on the player's current IP 3. Historical IP bans across all IPs the player has ever used (MongoDB only) 4. Alt bans — if `dupe-ip` is enabled, checks if any connected alt account is banned If any check fails, the player is disconnected with a message showing the ban reason and remaining duration. --- ## IP Bans ``` /banip <player_or_ip> [reason] -d <duration> /unbanip <player_or_ip> ``` IP bans block all connections from a specific IP address. When an IP is banned: - All currently online players on that IP are kicked immediately - New connections from that IP are blocked at login - With MongoDB, historical IP tracking prevents VPN bypass by checking all IPs a player has ever used --- ## Mutes ### Permanent Mute ``` /mute <player> [reason] ``` ### Temporary Mute ``` /mute <player> [reason] -d <duration> /tempmute <player> [reason] -d <duration> ``` ### Unmute ``` /unmute <player> ``` When muted, the player: - Cannot send chat messages - Cannot use commands listed in the `mute_commands` config (e.g., `/msg`, `/tell`, `/whisper`) - Sees a notification with the mute reason and remaining duration (shown every 10 seconds) --- ## Warns ``` /warn <player> <reason> ``` Warns block the player from chatting until they acknowledge the warning by typing **"I understand"** in chat. The warning message is displayed every 10 seconds while they attempt to chat. Once acknowledged, the warn is removed and the player can chat normally again. ### Delete a Warning ``` /delwarn <player> ``` --- ## Kicks ``` /kick <player> [reason] ``` Immediately removes the player from the server. Kicks are logged in the infraction history but do not prevent the player from rejoining. ### Kick All ``` /kickall ``` Kicks all players from the server (except the sender). Useful for maintenance. --- ## Duration Format Temporary infractions accept human-readable durations: | Unit | Example | |---|---| | Days | `1d` | | Hours | `2h` | | Minutes | `30m` | | Seconds | `45s` | | Combined | `1d 2h 30m` | Pass the duration with the `-d` flag: ``` /ban Player1 Griefing -d 7d /mute Player1 Spam -d 1h 30m ``` --- ## Infraction History ``` /history <player> [page] ``` Shows all past infractions for a player with 5 entries per page. Each entry shows: - Infraction type (color-coded: bans in red, kicks in yellow, mutes in gold, warns in yellow) - Whether it's currently active (green dot) or expired (gray dot) - Issuer name and how long ago it was issued - Hover for full details: reason, expiration status > [!info] > Full infraction history with IP tracking requires MongoDB. Local storage mode stores basic infraction records only. --- ## Infraction Lists | Command | Aliases | Description | |---|---|---| | `/banlist` | `/bans` | List all active bans | | `/banlistip` | | List all active IP bans | | `/mutelist` | `/mutes` | List all active mutes | | `/warnlist` | `/warns` | List all active warnings | --- ## Alt Detection ``` /alts <player> [page] ``` Shows all alt accounts connected to a player through shared IP addresses. Accounts are color-coded: - **Green** — Online - **Red** — Banned - **Dark Purple** — Muted - **Yellow** — IP Banned - **Gray** — Offline > [!important] > Alt detection requires **MongoDB**. The system tracks all IPs a player has ever connected from and finds accounts that share those IPs — including transitive connections (alts of alts). ### Auto-Ban Alts When `dupe-ip` is enabled in `managers/infractions.yml`, banning a player automatically bans all detected alt accounts. Alt bans show the reason prefixed with `[ALT]`. --- ## Vanish ``` /vanish [player] [true/false] /unvanish [player] ``` When vanished, the player is completely hidden from non-vanished players. Vanished players can see each other. ### What Vanish Hides | Behavior | Details | |---|---| | **Player visibility** | Hidden from all non-vanished players | | **Join/quit messages** | Suppressed | | **Server list** | Removed from player count and sample | | **Item pickup** | Blocked unless sneaking | | **XP orb pickup** | Blocked entirely | | **Mob targeting** | Monsters cannot target vanished players | | **Advancements** | Not granted while vanished (prevents notifications) | | **Death messages** | Killer identity hidden if vanished | | **Container animations** | Chest/barrel open/close animations blocked (via PacketEvents) | | **Container sounds** | Chest/barrel open/close sounds blocked | Vanished players receive a **glow effect** for visual feedback that they are in vanish mode. --- ## Social Spy ``` /socialspy [on/off] ``` When enabled, the player can see all private messages (`/msg`, `/whisper`, `/reply`) sent between other players. Useful for monitoring player communications. --- ## Global Chat Mute ``` /muteglobalchat /unmuteglobalchat ``` Mutes the entire server chat. When active: - Non-operator players without `lodestone.bookshelf.chat.bypass` cannot send messages - Operators can always chat - The mute state persists across restarts --- ## PvP Toggle ``` /pvp [on/off] ``` Toggles server-wide player-vs-player combat. When disabled: - Direct player damage is prevented - Projectile damage between players is prevented - The state persists across restarts --- ## Infractions Configuration ### managers/infractions.yml ```yaml # Auto-ban alt accounts when a player is banned (requires MongoDB) dupe-ip: true # Whether reason/duration arguments are optional optional: reasons: ban: true unban: true kick: true warn: true mute: true unmute: true durations: ban: true mute: true # Default duration for infractions (-1 = permanent) default-ban-duration: -1 default-mute-duration: -1 ``` ### config.yml (infraction-related settings) ```yaml # Maximum allowed duration for temporary bans/mutes (-1 = unlimited) max_tempban_time: -1 max_mute_time: -1 # Commands blocked when a player is muted mute_commands: - msg - tell - whisper ``` --- ## Cross-Server Sync With MongoDB and Redis enabled, infractions sync automatically across all connected servers: - **MongoDB** stores all infraction records, player data, and alt tracking persistently - **Redis** broadcasts infraction changes in real time so other servers apply them immediately - Banning a player on one server kicks them from all servers - Unbanning a player on one server removes the ban network-wide - Alt detection works across all servers sharing the same MongoDB database See [[Bookshelf/Server Owners/Configuration]] for network setup. --- ## Permissions ### Infraction Commands | Permission | Commands | |---|---| | `lodestone.bookshelf.commands.infractions.ban` | `/ban`, `/tempban` | | `lodestone.bookshelf.commands.infractions.banip` | `/banip` | | `lodestone.bookshelf.commands.infractions.unbanip` | `/unbanip` | | `lodestone.bookshelf.commands.infractions.kick` | `/kick` | | `lodestone.bookshelf.commands.infractions.infractions` | `/history` | | `lodestone.bookshelf.commands.infractions.alts` | `/alts` | | `lodestone.bookshelf.commands.infractions.banlist` | `/banlist` | | `lodestone.bookshelf.commands.moderation.unban` | `/unban` | | `lodestone.bookshelf.commands.moderation.mute` | `/mute`, `/tempmute` | | `lodestone.bookshelf.commands.moderation.unmute` | `/unmute` | | `lodestone.bookshelf.commands.moderation.warn` | `/warn` | | `lodestone.bookshelf.commands.moderation.delwarn` | `/delwarn` | | `lodestone.bookshelf.commands.infractions.mutelist` | `/mutelist` | | `lodestone.bookshelf.commands.infractions.warnlist` | `/warnlist` | ### Moderation Commands | Permission | Commands | |---|---| | `lodestone.bookshelf.commands.moderation.vanish` | `/vanish` (self) | | `lodestone.bookshelf.commands.moderation.vanish.target` | `/vanish <player>` | | `lodestone.bookshelf.commands.moderation.socialspy` | `/socialspy` | | `lodestone.bookshelf.commands.moderation.muteglobalchat` | `/muteglobalchat` | | `lodestone.bookshelf.commands.moderation.unmuteglobalchat` | `/unmuteglobalchat` | | `lodestone.bookshelf.commands.moderation.pvp` | `/pvp` | | `lodestone.bookshelf.commands.moderation.kickall` | `/kickall` | | `lodestone.bookshelf.commands.moderation.announce` | `/announce`, `/broadcast` | ### Bypass Permissions | Permission | Effect | |---|---| | `lodestone.bookshelf.moderation.bypass` | Immune to all infractions | | `lodestone.bookshelf.infractions.bypass` | Skip reason/duration requirements | | `lodestone.bookshelf.chat.bypass` | Bypass chat moderation (cooldowns, spam, banned words) | | `lodestone.bookshelf.alerts` | Receive staff alerts for moderation violations | --- ## Related Pages - [[Bookshelf/Server Owners/Features/Chat System]] - Chat moderation details (banned words, spam, cooldowns) - [[Bookshelf/Server Owners/Configuration]] - Network setup for cross-server sync - [[Bookshelf/Server Owners/Commands]] - Quick command reference