# 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.
---
## 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 | `false` | 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. |
| `chat_cooldown` | Integer | `3` | Seconds between allowed messages. Can be overridden per-group via LuckPerms (`chat_cooldown.<seconds>`). |
| `banned_words` | String List | `[]` | List of blacklisted words or regex patterns. Messages containing these are blocked. |
### Chat Feature Permissions
These permissions control access to inline chat features. Players without the respective permission see raw text with no formatting.
| Permission | Description |
|---|---|
| `lodestone.bookshelf.chat.links` | Allows clickable URLs in chat. |
| `lodestone.bookshelf.chat.mentions` | Allows `@PlayerName` mentions. |
| `lodestone.bookshelf.chat.item` | Allows `@item` display in chat. |
| `lodestone.bookshelf.chat.bypass` | Bypasses chat cooldown, spam, and mute restrictions. |
| `lodestone.bookshelf.chat.<channel>` | Access to a specific chat channel. |
| `lodestone.bookshelf.alerts` | Receives staff alerts for banned words, spam, and duplicate messages. |
---
## 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
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/Commands]] - Complete command reference