Waypoint Behavior

Client-side displays

TypicalWaypoint uses PacketEvents and EntityLib to send client-side item display entities. These displays are visible to selected players without creating normal persistent Bukkit entities in the world.

The displayed item is leather horse armor with an ITEM_MODEL component in the typicalwaypoint namespace. The default model id is waypoint_circle. Custom texture filenames become model ids after lowercasing and sanitizing to letters, numbers, dot, underscore, and dash.

Following indicator

Outside the arrival radius, the display is mounted as a passenger on the player. The display’s translation points from the player’s eye location toward the waypoint location. indicator-distance controls how far along that direction the indicator sits.

Movement packet handling drives updates. The plugin listens for player movement packets through PacketEvents and schedules display updates on the player’s entity thread through FoliaLib. update-interval-ticks controls the throttle; values below 1 are treated as 1.

Arrival behavior

arrival-radius-blocks defines when a player has reached a waypoint. Inside that radius, the mounted display is replaced with a placed display at the waypoint location. When the player leaves the radius, the placed display is removed and the following indicator returns.

Visibility model

Waypoint data is global. Visibility is per player and controlled by staff:

• /waypoint show <name> <target> makes a waypoint visible to one player.
• /waypoint hide <name> <target> removes that player’s display.
• Removing or clearing waypoints removes active displays.

Visibility state is in memory. Saved waypoint definitions persist through data/waypoint-data-config.yml.