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. By default, the mounted display becomes a placed display at the waypoint location and returns to following when the player leaves.

For waypoint entries with hide-when-nearby: true, entering the radius removes the display, sends the waypoint-arrived action bar, and removes that waypoint from the player’s visibility. It stays hidden after the player leaves. Staff can show it again with /waypoint show <name> <target>.

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.