# Configuration Guide

SpectatorPlusPlus offers comprehensive configuration options to customize your spectator experience. This guide explains all available settings in the `config.yml` file.

## Configuration Structure

### Basic Configuration
After first run, the plugin generates a `config.yml` file in `plugins/SpectatorPlusPlus/`. You can edit this file and reload the plugin with:
/spectator reload


---

## 📍 Spectator Lobby Settings

Configure the main spectator lobby world where players return after leaving spectator mode.

```yaml
spectator-lobby:
  world: "spectator_lobby"
  can-see-all-worlds: true
  show-all-players-in-tab: true
  teleport-to-on-leave: true
```
**Settings:**

- `world`: Name of your spectator lobby world
- `can-see-all-worlds`: Players in lobby can see all worlds on compass GUI
- `show-all-players-in-tab`: Show all online players in tablist
- `teleport-to-on-leave`: Teleport players here when leaving spectator mode

## 🏠 Default Lobby Location
Coordinates for the spectator lobby (automatically set when using /spectator lobby set).

```yaml
lobby:
  world: spectator_lobby
  x: 0.5
  y: 64.0
  z: 0.5
  yaw: 0.0
  pitch: 0.0
```
## 👁️ Spectator Mode Settings
Core settings for spectator mode behavior and player experience.

### Flight & Movement
```yaml
spectator:
  fly-speed: 0.1
  walk-speed: 0.2
  can-fly: true
  double-jump-to-fly: true
```
**Flight Settings:**
- `fly-speed`: Flight speed (0.1 = normal creative flight)
- `walk-speed`: Walking speed multiplier
- `can-fly`: Allow flying in spectator mode
- `double-jump-to-fly`: Double spacebar toggles flight

## Visibility
```yaml
  invisible-to-others: true
  can-see-other-spectators: true
  can-see-normal-players: true
```
**Visibility Settings:**
- `invisible-to-others`: Spectators are invisible to regular players
- `can-see-other-spectators`: Spectators can see each other
- `can-see-normal-players`: Spectators can see regular players

## Interactions & Behavior
```yaml
  pass-through-entities: true
  normal-walking: true
  lock-spectator-items: true
  restore-original-gamemode: true
  chat-visible-to-spectators-only: true
```
**Interaction Settings:**
- `pass-through-entities`: Walk through entities
- `normal-walking`: Walk normally (no noclip mode)
- `lock-spectator-items`: Prevent moving/dropping spectator GUI items
- `restore-original-gamemode`: Return to original gamemode after leaving
- `chat-visible-to-spectators-only`: Spectator chat only visible to other spectators

## 🔍 First-Person Spectating
Configure the first-person spectating feature (right-click players to see through their eyes).

```yaml
first-person-spectating:
  enabled: true
  camera-inside-body: true
  sync-inventory: true
  stop-on-sneak: true
  right-click-to-spectate: true
```
**Settings:**
- `enabled`: Enable/disable first-person spectating
- `camera-inside-body`: Camera positioned inside target's body
- `sync-inventory`: Show target's inventory view
- `stop-on-sneak`: Sneak to stop spectating
- `right-click-to-spectate`: Right-click players to spectate them

## 🌍 World Set Detection
Automatically group related worlds (Overworld, Nether, End) for easier navigation.

```yaml
world-sets:
  auto-detect: true
  suffix-nethers: "_nether"
  suffix-ends: "_the_end"
  ignore-worlds:
    - "spectator_lobby"
    - "lobby"
    - "hub"
```
**Settings:**
- `auto-detect`: Auto-detect world relationships
- `suffix-nethers`: Nether world suffix pattern
- `suffix-ends`: End world suffix pattern
- `ignore-worlds`: Worlds to exclude from auto-detection

## 🧭 Compass GUI Settings
Customize the player selection compass GUI.

```yaml
compass-gui:
  title: "&6Spectate Players"
  rows: 6
  show-spectators: false
  show-health: true
  show-gamemode: true
  show-world: true
```
**GUI Settings:**
- `title`: GUI window title (supports color codes with `&`)
- `rows`: Number of GUI rows (1-6 = 9-54 slots)
- `show-spectators`: Show other spectators in the GUI
- `show-health`: Display player health
- `show-gamemode`: Display player gamemode
- `show-world`: Display player's current world

##🎯 Hotbar Item Slots
Configure which hotbar slots contain spectator items.

```yaml
hotbar-items:
  compass-slot: 0
  visibility-toggle-slot: 2
  chat-toggle-slot: 4
  leave-slot: 8
```
**Slot Assignments:**
- `0`: Compass (Open player selection GUI)
- `2`: Visibility Toggle (Show/hide other spectators)
- `4`: Chat Toggle (Enable/disable spectator chat)
- `8`: Leave Spectator (Exit spectator mode)

## 💬 Messages
Customize all plugin messages. Use & for color codes.

```yaml
messages:
  # General
  enter-spectator: "&aYou are now in spectator mode!"
  leave-spectator: "&cYou have left spectator mode!"
  
  # Admin
  lobby-set: "&aLobby location set!"
  
  # Spectating
  now-spectating: "&aNow spectating &e{player}&a! Sneak to stop."
  
  # Full message list available in config.yml
```
**Available Placeholders:**
- `{player}`: Target player name
- `{world}`: World name
- `{gamemode}`: Player gamemode

## 🔗 Multiverse Integration
Settings for Multiverse-Core compatibility.

```yaml
multiverse:
  enabled: true
  use-mv-teleport: true
  respect-mv-inventories: true
```
**Settings:**
- `enabled`: Enable Multiverse integration
- `use-mv-teleport`: Use Multiverse teleport methods
- `respect-mv-inventories`: Work with Multiverse-Inventories

## 🐛 Debug Settings
Enable debugging for troubleshooting.

```yaml
debug:
  enabled: false
  log-spectator-events: false
  log-spectating-events: false
```
**Debug Options:**
- `enabled`: Enable debug console messages
- `log-spectator-events`: Log spectator mode entries/exits
- `log-spectating-events`: Log first-person spectating events

---

## Configuration Tips

1. **Backup First**: Always backup your `config.yml` before making changes
2. **Reload Changes**: Use `/spectator reload` after editing
3. **Color Codes**: Use `&` for colors (e.g., `&a` for green, `&c` for red)
4. **Test Changes**: Test configuration changes in a development environment first
5. **World Names**: Ensure world names match exactly (case-sensitive)