# Configuration
Bookshelf uses `config.yml` for core server settings and generates a separate `managers/chat.yml` at runtime for chat-specific configuration. The main config controls announcement formatting, gameplay toggles, command registration, and network connectivity.
---
## Config Version
| Field | Type | Default | Description |
|---|---|---|---|
| `version` | Integer | `2` | Internal config version. Do not modify. |
---
## General Settings
### Announcement Prefix
| Field | Type | Default | Description |
|---|---|---|---|
| `announcement_prefix` | String | `<bold><red>BROADCAST <reset><dark_gray>» ` | The prefix displayed before `/announce` and `/broadcast` messages. Supports MiniMessage formatting. |
### Unsafe Enchantments
| Field | Type | Default | Description |
|---|---|---|---|
| `unsafe_enchantments` | Boolean | `false` | When `true`, players can apply any enchantment to any item at any level using the `/enchant` command. |
### PvP
| Field | Type | Default | Description |
|---|---|---|---|
| `is_pvp_enabled` | Boolean | `true` | Controls whether players can damage other players. This value is cached locally and persists across restarts. Toggle in-game with `/pvp`. |
### God Mode
| Field | Type | Default | Description |
|---|---|---|---|
| `allow_hitting_in_god_mode` | Boolean | `true` | When `true`, players can still hit players who have god mode enabled (damage is negated). When `false`, god mode players cannot be targeted at all. |
---
## Command Management
The `commands` section controls which Bookshelf commands are registered on startup. Setting a command to `false` prevents Bookshelf from registering it, allowing other plugins to claim that command name.
| Field | Type | Default | Description |
|---|---|---|---|
| `commands.disabled` | Boolean | `false` | Master switch. When `true`, disables ALL Bookshelf commands from registering. |
| `commands.clearpack` | Boolean | `true` | Enables or disables the `/clearpack` command. |
| `commands.ping` | Boolean | `true` | Enables or disables the `/ping` command. |
Commands are organized by category. Each category and command is auto-populated in the config when the command first registers. The format follows:
```yaml
commands:
disabled: false
clearpack: true
ping: true
moderation:
ban: true
kick: true
mute: true
utility:
fly: true
heal: true
gamemode:
gms: true
gmc: true
attributes:
scale: true
vanilla:
enchant: true
```
To disable a specific command, set its value to `false`. Bookshelf will not register that command, freeing it for other plugins.
---
## Teleportation
| Field | Type | Default | Description |
|---|---|---|---|
| `teleport_delay` | Integer | `0` | Seconds before `/spawn` and `/back` teleports execute. Player must not move during the delay. |
| `teleport_cooldown` | Integer | `0` | Seconds between teleport command uses. |
| `warp_delay` | Integer | `0` | Seconds before `/warp` teleports execute. |
Players with `lodestone.bookshelf.teleport.bypass` skip all delays and cooldowns. Set values to `0` to disable.
> For details on how warps, back locations, and offline teleportation work, see [[Bookshelf/Server Owners/Features/Teleportation]].
---
## Infractions
Bookshelf generates `managers/infractions.yml` for infraction-specific settings.
| Field | Type | Default | Description |
|---|---|---|---|
| `dupe-ip` | Boolean | `true` | Auto-ban alt accounts when a player is banned (requires MongoDB). |
| `optional.reasons.*` | Boolean | `true` | Whether the reason argument is optional for each infraction type. |
| `optional.durations.*` | Boolean | `true` | Whether the duration argument is optional for bans and mutes. |
| `default-ban-duration` | Integer | `-1` | Default ban duration in milliseconds. `-1` is permanent. |
| `default-mute-duration` | Integer | `-1` | Default mute duration in milliseconds. `-1` is permanent. |
Additional infraction settings in `config.yml`:
| Field | Type | Default | Description |
|---|---|---|---|
| `max_tempban_time` | Integer | `-1` | Maximum allowed temporary ban duration in seconds. `-1` is unlimited. |
| `max_mute_time` | Integer | `-1` | Maximum allowed mute duration in seconds. `-1` is unlimited. |
| `mute_commands` | String List | `[]` | Commands blocked when a player is muted (e.g., `msg`, `tell`, `whisper`). |
> For details on how the infraction system works, see [[Bookshelf/Server Owners/Features/Moderation]].
---
## Chat System
Bookshelf generates a separate `managers/chat.yml` file at runtime for chat-specific settings. This file is auto-created when the plugin first loads and can be edited by server owners.
| Field | Type | Default | Description |
|---|---|---|---|
| `enabled` | Boolean | `true` | Enables Bookshelf's chat system. When `false`, vanilla chat is used. |
| `muted` | Boolean | `false` | When `true`, global chat is muted for non-bypass players. Toggled in-game with `/muteglobalchat`. |
| `distinguishable_operators` | Boolean | `false` | When `true`, operators get a `STAFF` prefix and white name/message colors. Set to `false` when using LuckPerms. |
| `chat_cooldown` | Integer | `3` | Seconds between allowed messages. Can be overridden per-group via LuckPerms (`chat_cooldown.<seconds>`). |
| `banned_words` | String List | *(pre-populated)* | List of blacklisted words or regex patterns. Messages containing these are blocked. |
| `channels` | String List | `["STAFF"]` | Custom chat channels. Each requires permission `lodestone.bookshelf.chat.<channel>`. |
### LuckPerms Chat Nodes
When LuckPerms is installed, Bookshelf reads the following permission nodes from the player's primary group:
| Node | Purpose | Example |
|---|---|---|
| `prefix.<weight>.<value>` | Chat prefix | `prefix.10.<red><bold>ADMIN` |
| `suffix.<weight>.<value>` | Chat suffix | `suffix.10.<gray>[Staff]` |
| `chat_color.<color>` | Message text color | `chat_color.#ffffff` |
| `rank_color.<color>` | Player name color | `rank_color.#ff00ff` |
| `chat_cooldown.<seconds>` | Group cooldown override | `chat_cooldown.1` |
> For a complete guide on setting up chat formatting, LuckPerms integration, chat features, moderation, and channels, see [[Bookshelf/Server Owners/Features/Chat System]].
---
## Networking
Bookshelf supports optional MongoDB and Redis connections for multi-server networks. The behavior depends on which services are enabled.
### Connection Matrix
| MongoDB | Redis | Behavior |
|---|---|---|
| Disabled | Disabled | Standalone mode. All data stored locally. |
| Disabled | Enabled | Redis synchronizes data locally and enables network actions. |
| Enabled | Enabled | Full network mode. Redis synchronizes through MongoDB. |
| Enabled | Disabled | Invalid configuration. Falls back to standalone mode. Redis is required when MongoDB is enabled. |
### MongoDB Configuration
MongoDB provides persistent storage for infractions, player data, and alt tracking across servers.
| Field | Type | Default | Description |
|---|---|---|---|
| `networking.mongodb.enabled` | Boolean | `false` | Enables MongoDB connectivity. |
| `networking.mongodb.uri` | String | `mongodb://localhost:27017` | MongoDB connection URI. Supports authentication and replica sets. |
| `networking.mongodb.database` | String | `bookshelf` | The database name to use. |
| `networking.mongodb.collections.infractions` | String | `infractions` | Collection name for player infractions (bans, mutes, warns, kicks). |
| `networking.mongodb.collections.players` | String | `players` | Collection name for player data (vanish history, social tracking). |
| `networking.mongodb.collections.alts` | String | `alts` | Collection name for player alt tracking (IP, UUID correlation). |
**MongoDB supports:**
- Infraction history
- Vanish history
- Player alt tracking
- Player social tracking (whisper, blocking)
### Redis Configuration
Redis provides real-time synchronization and event notification between servers.
| Field | Type | Default | Description |
|---|---|---|---|
| `networking.redis.enabled` | Boolean | `false` | Enables Redis connectivity. |
| `networking.redis.host` | String | `localhost` | Redis server hostname or IP. |
| `networking.redis.port` | Integer | `6379` | Redis server port. |
| `networking.redis.password` | String | `""` | Redis authentication password. Leave empty for no authentication. |
**Redis supports:**
- Infraction synchronization
- Global infraction notifications
- Player social spy notifications
- Cross-server whisper delivery
- Network chat channels
---
## Example Configuration
```yaml
version: 2
announcement_prefix: "<bold><red>BROADCAST <reset><dark_gray>» "
unsafe_enchantments: false
is_pvp_enabled: true
allow_hitting_in_god_mode: true
teleport_delay: 0
teleport_cooldown: 0
warp_delay: 0
max_tempban_time: -1
max_mute_time: -1
mute_commands: []
commands:
disabled: false
clearpack: true
ping: true
networking:
mongodb:
enabled: false
uri: "mongodb://localhost:27017"
database: "bookshelf"
collections:
infractions: "infractions"
players: "players"
alts: "alts"
redis:
enabled: false
host: "localhost"
port: 6379
password: ""
```
---
## Related Pages
- [[Bookshelf/Server Owners/Overview]] - Plugin features and dependencies
- [[Bookshelf/Server Owners/Features/Chat System]] - Chat formatting, LuckPerms, moderation, and channels
- [[Bookshelf/Server Owners/Features/Moderation]] - Infraction system details
- [[Bookshelf/Server Owners/Features/Teleportation]] - Teleportation system details
- [[Bookshelf/Server Owners/Commands]] - Complete command reference