Readme

Admin Spectator Mod (Fabric)

The Admin Spectator Mod is a server-side moderation tool that lets authorized staff spectate a player using the target player's POV, then instantly return to their exact position and gamemode. It is built for survival servers and avoids freecam abuse by enforcing a configurable distance limit.

---

Key Features

• Direct spectate command: /spectate <player> immediately switches you to the target player's POV.
• Accurate restore: Position, gamemode, and dimension are restored when spectate ends.
• Freecam distance limit: Configurable boundary (default 30 blocks) with automatic snap-back and warnings.
• Cooldown: Configurable cooldown between spectate sessions (default 30 seconds).
• Combat safety: Optional block when in combat or near hostile mobs.
• Player-only POV: Camera is forced back to the target player if it switches to mobs or other entities.
• Disconnect handling: Spectating ends automatically if the target leaves the server.
• Jail Mod compatibility: Jailed players cannot spectate.
• Crash recovery: Spectate sessions are persisted to disk.
• Auto-patching config: New config fields are added automatically on update.

How to use:

1. Install the mod and Fabric API on the server.
2. Start the server once to generate configuration files.
3. Run /spectate <player> to start spectating.
4. Use /spectate stop to return to your saved position.
5. Use /spectate reload after editing the config.

Requirements

• Minecraft 1.21.11
• Fabric Loader
• Fabric API
• Java 21

Installation

1. Place the mod's .jar file in the server mods folder.
2. Start the server to generate configuration files.

Available Commands

1. /spectate player

• Description: Spectate a specific player immediately.
• Who can use it: Only admins or server operators.
• Syntax: /spectate player_name
• Example: /spectate Steve

2. /spectate stop

• Description: Stop spectating and return to your original position.
• Who can use it: Only admins or server operators.
• Example: /spectate stop

3. /spectate reload

• Description: Reloads the configuration without restarting the server.
• Who can use it: Only admins or server operators.
• Example: /spectate reload

Spectate Rules

While spectating, the following rules apply:

• You can only use the target player's POV (no mob POV).
• Freecam distance is limited by freecam_distance_limit.
• If you push the limit repeatedly, you are snapped back to the target POV.
• If the target leaves the server, spectating ends automatically.

Jail Mod Compatibility

If Jail Mod is installed, jailed players cannot use /spectate.

Configuration file

config/spectatemod/config.json

This file is automatically generated and updated. Here are the options you can find:

• admin_roles: Comma-separated list of roles or tags that grant /spectate access. Use "op" to include operators.
• spectate_cooldown: Cooldown in seconds between spectate sessions.
• prevent_combat_spectate: If true, prevents spectating while in combat or near hostile mobs.
• combat_check_radius: Radius in blocks to check for hostile mobs.
• save_spectate_positions: If true, saves spectate state to disk for crash recovery.
• freecam_distance_limit: Max distance (in blocks) from the target player while in freecam. Use 0 to disable.

Example configuration:

{
  "_config_guide": "SpectateMod Configuration Guide: \n- admin_roles: Comma-separated list of roles or tags that grant /spectate access. Use 'op' to include server operators.\n- spectate_cooldown: Cooldown time in seconds before an admin can spectate again after stopping.\n- prevent_combat_spectate: If true, prevents spectating when the admin is in combat or near hostile mobs.\n- combat_check_radius: Radius in blocks to check for hostile mobs when prevent_combat_spectate is enabled.\n- save_spectate_positions: If true, saves spectate positions to disk to prevent data loss on crashes.\n- freecam_distance_limit: Max distance (in blocks) you can move away from the spectated player while in freecam.",
  "admin_roles": "op",
  "spectate_cooldown": 30,
  "prevent_combat_spectate": true,
  "combat_check_radius": 16.0,
  "save_spectate_positions": true,
  "freecam_distance_limit": 30.0
}

Data persistence

Active spectate sessions are saved to:

config/spectatemod/spectate_data.json

This allows the server to restore admins to their correct position after crashes or restarts (when enabled in config).

Usage Tips

Use the /spectate reload command after changing configuration. If you use custom roles, add tags like:

/tag @p add admin