👻 GuestMode — Visible Spectators for Your World

GuestMode is a lightweight plugin for Folia (Minecraft 1.21+) that lets your friends join your world as visible spectators — exploring freely without affecting gameplay.

Players in guest mode are completely isolated from the world around them:

• ❌ Cannot break or place blocks
• ❌ Cannot use doors, chests, beds, crafting tables, or any interactive blocks
• ❌ Cannot attack, take damage, pick up items, or collect XP
• ❌ Cannot interact with mobs, ride entities, or throw potions and projectiles
• 👁️‍🗨️ Are ignored by all mobs (but mobs can still look at them)
• 🧊 Cannot push or move any entities — including players (but normal players can still nudge guests)
• 🕊️ Can fly freely for complete exploration freedom (future updates may add per-player settings)

Guests remain visible and can explore the world freely, but they cannot influence it in any way.

🆕 New in 1.3

• You can now change guest permissions directly in the config file — the full configuration is included at the bottom of this page.

🆕 New in 1.2

• 💤 Guests are not counted for sleeping – only real players need to sleep to accelerate the night.
• 👻 Phantom targeting fixed – phantoms no longer spawn based on guest players.
• ⏸️ World pause logic – the world is automatically paused when only guests (or no one) are online (future updates may allow disabling this setting in the config)

🤝 Compatibility

✅ Fully compatible with RealisticSleep (Folia) — guest players are automatically ignored by sleep checks, so only real players are required to sleep for the night to pass.

⚙️ Commands

/guest <player>

Toggle guest mode for any player instantly.

/guest

Show the GuestMode help menu.

🧩 Configuration

# ===============================
#  GuestMode configuration guide
# ===============================
#
# === PLAYER LISTS ===
# Two lists control who is a GUEST and who is NORMAL:
#
#   - guests: players treated as GUESTS.
#   - except: players treated as NORMAL (never guests).
#
# Special token:
#   - "[all]" (must be quoted!) — a global switch.
#
# Modes
# -----
# 1) Individual mode (no "[all]" anywhere)
#    - Only players listed under `guests` are guests.
#    - Players in `except` are always normal.
#
# 2) Global guests mode (put "[all]" in `guests`)
#    - Everyone is a guest EXCEPT the names listed in `except`.
#    - `except` is the allow-list for being normal in this mode.
#
# 3) Global except mode (put "[all]" in `except`)
#    - Everyone is normal EXCEPT the names listed in `guests`, who become guests.
#    - `guests` is the allow-list for being a guest in this mode.
#

# === PLAYER MODE LISTS ===
except:
  - Player1
guests:
  - '[all]'
  - Player2

# ===============================
#  GUEST ABILITIES & RESTRICTIONS
# ===============================

# === MOVEMENT & PHYSICS ===
# Auto-enable flight for guests
auto_flight: true

# === ANTI-PUSH SYSTEM ===
# Prevents guests from pushing other players/entities
# Guests phase through collisions without affecting normal players
anti_push:
  enabled: true # tested
  
  # AABB padding - safety margin around hitboxes (in blocks)
  # Larger = more separation, but may feel "floaty"
  aabb_padding: 0.10 # Set to 0.65 so that guests are always one block apart from players and other entities (the player can dig without restrictions)

  # Top epsilon - gap when landing on entities (in blocks)
  top_epsilon: 0.05
  
  # Detection radius - how far to check for nearby entities (in blocks)
  detection_radius: 3.0
  
  # Safe gap - minimum space maintained between hitboxes after push (in blocks)
  safe_gap: 0.05
  
  # Max resolution iterations - attempts to resolve complex overlaps
  max_iterations: 5

# === WORLD FREEZING ===
# When only guests (or no players) are in a world, freeze it to save resources
world_freeze:
  
  # What to freeze when no normal players are present:
  freeze_daylight_cycle: true    # Stop time progression
  freeze_weather_cycle: true     # Stop weather changes
  freeze_mob_spawning: true      # Prevent new mob spawns
  freeze_random_ticks: true      # Stop crop growth, leaf decay, etc.
  freeze_mob_ai: true            # Stop mob movement and targeting
  freeze_mob_gravity: true       # Make mobs float in place
  make_mobs_invulnerable: true   # Prevent damage to frozen mobs
  enabled: false # tested; toggling unstable—if world hangs, set true and restart

# === EXPERIENCE ORBS ===
experience_orbs:
  freeze_for_guests: true
  freeze_radius: 10.0
  position_tolerance: 0.25

# === GUEST INVISIBILITY ===
# Make guests invisible to mobs (and glow for players)
invisibility:
  enabled: true # tested
  mob_attention_radius: 8.0
  glow_for_players: true
  glow_radius: 32.0

# ===============================
#  GUEST INTERACTION PERMISSIONS
# ===============================

# What guests CAN do (set to true to allow, false to deny):
permissions:
  # World interaction
  break_blocks: false # tested — Set the player's gamemode accordingly
  place_blocks: false # tested
  damage_blocks: false # tested (keep equal to break_blocks)
  interact_blocks: false # tested (buttons, levers, doors, etc.)

  # Items & inventory
  drop_items: false # tested
  pickup_experience: false # tested
  change_held_item: false # tested — BUG: can still change via middle-click (Pick Block)
  swap_hands: true # tested
  consume_items: false # tested — splash/lingering potions are controlled by launch_projectiles
  open_inventory: true # tested — requires interact_blocks; currently useless if interact_blocks is false.
                       # Future updates: per-block interaction allowlist will be added.

  # Containers & storage
  use_buckets: false # tested — pouring works; filling (milk/fish/powdered snow) blocked; can allow via interact_entities or targeted exceptions
  edit_books: false # tested
  edit_signs: false # tested

  # Entities
  damage_entities: false # tested
  interact_entities: false # tested
  damage_vehicles: false # tested
  destroy_vehicles: false # tested
  place_hanging_entities: false # tested # Item frames, paintings
  break_hanging_entities: false # tested
  manipulate_armor_stands: false # tested

  # Animals & breeding
  tame_animals: false # tested
  breed_animals: false # tested
  shear_entities: false # tested
  use_leash: false # tested

  # Beds & respawn
  use_beds: false # tested — BUG: sleep blocked, but spawn still sets

  # Combat & projectiles
  launch_projectiles: false # tested
  use_fishing_rod: false # tested

  # Fire & explosions
  ignite_blocks: false # tested — bug: only ignites TNT, no explosion if cause_explosions: false, requires interact_blocks: true
  cause_explosions: false # tested

  # Progression
  earn_advancements: false # tested — consider showing a notice to guests

Invite your friends to join, watch, and explore — without ever interfering in your adventure.