👻 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.