Skip to content

Fix OfflinePlayer name handling on Paper 1.20+ and improve Geyser/Floodgate compatibility#76

Merged
BenCodez merged 1 commit intoBenCodez:mainfrom
jamjet3:fix/offlineplayer-names-paper-1-21
Nov 25, 2025
Merged

Fix OfflinePlayer name handling on Paper 1.20+ and improve Geyser/Floodgate compatibility#76
BenCodez merged 1 commit intoBenCodez:mainfrom
jamjet3:fix/offlineplayer-names-paper-1-21

Conversation

@jamjet3
Copy link
Copy Markdown
Contributor

@jamjet3 jamjet3 commented Nov 25, 2025

Summary

This PR fixes several issues related to OfflinePlayer#getName() on modern
Paper versions (1.20.5+ / 1.21.x) and improves compatibility with
Geyser/Floodgate setups where some UUIDs do not have a cached name.

The main goals:

  • Prevent NPEs and "An internal error occurred while attempting to tab-complete"
    in /plot and /vrplot commands.
  • Stop GUIs from breaking or showing null for members and owners.
  • Make name display robust even when OfflinePlayer#getName() is null or stale.
  • Keep behaviour identical for normal Java players and Spigot/Bukkit servers.

Key Changes

1. New PlayerLookupUtil

Added com.modnmetl.virtualrealty.util.PlayerLookupUtil as a central,
null-safe player name resolver:

Lookup order:

  1. In-memory cache (to avoid repeated lookups)
  2. Online Player#getName()
  3. OfflinePlayer#getName() (if present)
  4. Short UUID string (first 8 characters) as a stable fallback

This is safe on Paper 1.20.5+ where usercache / OfflinePlayer behaviour changed,
and on Geyser/Floodgate networks where some UUIDs never get a "real" Bukkit name.

2. Command fixes (/plot and /vrplot)

Patched commands to use UUIDs + PlayerLookupUtil instead of relying on
OfflinePlayer#getName() directly:

  • CommandManager
  • commands/plot/subcommand/AddSubCommand
  • commands/plot/subcommand/KickSubCommand
  • commands/plot/subcommand/InfoSubCommand
  • commands/vrplot/subcommand/AssignSubCommand
  • commands/vrplot/subcommand/SetSubCommand
  • commands/vrplot/subcommand/InfoSubCommand

Highlights:

  • /plot add works for:
    • online Java players
    • offline players with cached UUIDs
    • players whose name is not present in usercache
  • /plot kick and tab-completion no longer throw errors when some members
    have missing names.
  • /vrplot assign and set owner accept either UUID or username and
    will not fail if the OfflinePlayer has no name.

3. GUI fixes (Panel system)

Updated the premium panel system to avoid OfflinePlayer#getName() issues:

  • listener/premium/PanelListener
  • util/PanelUtil

Changes:

  • Member GUIs now sort and display using PlayerLookupUtil.getBestName(...).
  • Member skulls use a safe skull owner (real Bukkit name if available, otherwise
    a fallback string) so they do not break on Bedrock/Floodgate players.
  • All user-visible names in panel messages are resolved via PlayerLookupUtil,
    so there are no NPEs or null names in chat or inventory titles.

4. Plot entrance and gamemode handling

  • listener/PlotEntranceListener updated to be more defensive around
    player/plot lookups and game mode switching on Paper 1.20+.

Why this is needed

On Paper 1.20.5+ and 1.21.x, plus on Geyser/Floodgate networks, it is
increasingly common for Bukkit.getOfflinePlayer(...) to return profiles
with getName() == null, especially when:

  • the player has never joined the backend Paper server directly
  • usercache.json has been cleared
  • names have changed or were never cached

VirtualRealty currently assumes OfflinePlayer#getName() is always non-null
in many places, which leads to:

  • NPEs in commands
  • tab-completion errors
  • panels showing "null" or breaking
  • difficulty managing plots for long-term or Bedrock players

@BenCodez BenCodez merged commit 12d21e7 into BenCodez:main Nov 25, 2025
@jamjet3 jamjet3 deleted the fix/offlineplayer-names-paper-1-21 branch December 1, 2025 18:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants