Simple Waypoint Documentation

Simple Waypoint 2.0.0
CelestiaDominance
Unreal Engine 5.7 and 5.8 | Windows (Win64)

PURPOSE
Simple Waypoint adds a screen-space marker to an actor using your own User Widget. The marker follows the actor plus a world-space offset, can clamp to the edge of the selected local player's screen, and can fade with camera distance. It is a visual marker system, not pathfinding, navigation, radar scanning or an interaction system.

QUICK USE
1. Create a Widget Blueprint for your marker, for example WBP_ObjectiveMarker. Use an Image, Text or an Overlay inside a Size Box with a useful desired size, such as 64 x 64.
2. Add a Waypoint Component to the actor you want to mark.
3. Assign your Widget Blueprint to Widget Class.
4. Adjust World Offset so the marker appears above or beside that actor.
5. Play. The component creates and positions the widget for local player 0 by default.

The plugin owns this widget's viewport attachment, position, desired slot size, alignment, visibility and opacity. Do not also Add to Viewport or reparent the same widget in your UI. Style and animate children inside it instead. All marker artwork is supplied by your project; no Blueprint assets, textures or demonstration map are required or included.

CUSTOM WIDGET EVENTS
In the Widget Blueprint's Class Settings, add Waypoint Widget Interface.
Implement Event On Waypoint Initialized. Store its Waypoint Component parameter in a variable. This event runs once for each widget instance created by the component.
Implement Event On Waypoint Updated to update your distance text, arrow or other visual elements using that component. This event runs after a valid camera/projection update, including updates where distance or disabled clamping hides the marker. You do not need a separate widget Tick for these visuals.
Keep these events presentation-focused. Widget/player changes are applied on the next component update. A replacement widget receives a fresh initialization event. No update event is dispatched when the component is inactive, explicitly hidden, has no valid player/view, or has ended play.

ARROW EXAMPLE
Use arrow artwork that points LEFT at zero render rotation. This preserves the original release's convention.
On Waypoint Updated:
- If Is Clamped is true, show the child arrow image.
- Set that image's Render Transform Angle to Get Target Angle.
- Set that image's Render Transform Translation to Get Arrow Offset.
- Otherwise, collapse only the child arrow image.
For artwork that points RIGHT at zero rotation, add 180 degrees to Get Target Angle. Rotation can be negative; its range is -180 to 180 degrees.
Get Arrow Offset points outward from the marker center and uses Arrow Distance in Slate units. It returns zero when not clamped. Directly behind the camera, where there is no unique left/right cue, the marker uses the bottom edge consistently.
Leave enough room in the widget's desired layout size or increase Edge Padding for an arrow orbiting outside its bounds. Child render transforms and shadows can extend past measured layout bounds; the plugin does not automatically reserve those extra pixels.

DISTANCE TEXT EXAMPLE
Read Get Distance To Player, divide by 100 and format the result as meters, for example 42 m. Despite its legacy name, this getter measures from the selected camera to the actor location plus World Offset, not from the pawn's feet.

SETTINGS
Widget Class: your concrete User Widget class. A missing or abstract class displays nothing. Classes assigned after BeginPlay are supported.
World Offset: a world-space offset in Unreal centimeters. It does not rotate with the owner.
Visible: requests marker visibility. Actual display also requires an active component, a valid local player/view, a valid widget and a visible result within the configured range.
Local Player Index: local-player ordinal, starting at 0. This is not a network player ID or controller ID. One component displays one widget for one local player. For multiple local players, use separate Waypoint Components with different indices. An unavailable player hides/removes the marker until that player becomes available.
Z Order: draw order within the chosen player's UI. Higher values draw above lower values. Changing it recreates the marker widget.
Custom Camera: optional Camera Component whose location, rotation and projection settings determine the marker projection. Perspective and orthographic cameras are supported. A destroyed camera falls back to the normal player view. This does not switch the rendered game camera and is not a render-target/minimap widget integration; normally use a camera that matches the view your player sees. Invalid custom camera parameters hide the marker.
Clamp To Screen: off-screen and behind-camera targets appear on the safe edge when enabled; they hide when disabled.
Edge Padding: physical pixels between the measured marker bounds and the edge of the chosen view. Desired widget size is converted from Slate units using the viewport DPI scale. Bounds use the local player's view, including split-screen and aspect-ratio bars. If the widget/padding is larger than the view, that axis is centered; an oversized widget cannot fit entirely on screen.
Arrow Distance: outward child-arrow offset in Slate units. Negative values are treated as zero.
Max Distance: camera-to-marker distance in centimeters; 0 or a negative value means unlimited range. At the exact positive maximum, the marker is hidden.
Fade Distance: fade length before Max Distance, in centimeters. Zero or a negative value gives a hard cutoff. Values larger than Max Distance are capped to that range. It has no effect with unlimited range.

BLUEPRINT NODES
Set Waypoint Visible: hide immediately or request a fresh update when showing.
Set Waypoint Widget Class: remove the old widget and create the new class on the next eligible update. Passing None removes it.
Set Waypoint Local Player Index: remove the old player's widget and recreate for the new local player on the next eligible update.
Get Widget: current component-owned User Widget, or None before creation/after removal. Always check validity when storing this reference; it can change.
Is Waypoint Displayed: whether the marker is currently displayed by this component.
Get Waypoint Opacity: current distance fade, from 0 to 1; zero when hidden or no view is available.
Is On Screen: target fits inside the safe view without clamping. This is geometric state, so it can be true even when distance fading hides the marker. Use Is Waypoint Displayed for final visibility.
Is Behind Camera: target lies behind the selected camera.
Is Clamped: the marker's current position is constrained to an edge.
Get Screen Position: widget center in physical pixels relative to the selected player screen, not desktop coordinates or UMG Slate units. For a Slate coordinate, divide by viewport DPI scale. Invalid/hidden projection results use zero.
Get Distance To Player: selected-camera distance in centimeters.
Get Target Angle / Get Arrow Offset: arrow values described above.
Activate / Deactivate: the standard Actor Component nodes resume updates or hide the marker. Prefer Deactivate over disabling Tick alone when you want to hide it immediately.

LIFECYCLE AND LOCAL PLAYERS
If the local player, viewport or widget class is not ready at BeginPlay, the component retries during subsequent active/visible updates. Changing class/player, losing the selected player, unregistering or ending play removes the old widget. Explicit hiding and deactivation clear display state. If another system removes the widget from the viewport, the component recreates it on the next eligible update.
Widgets are non-interactive (Hit Test Invisible), so they do not consume mouse input.
Dedicated servers create no marker UI. This component does not replicate objectives, visibility settings or UI state. Your gameplay code decides which client-side actors have markers and which local players receive them. Network replication and target discovery remain your project's responsibility.

TROUBLESHOOTING
Nothing appears: verify Widget Class, its desired size/content, component activation, Visible, the local-player index and distance settings. Test in Play; editor viewport preview is not provided.
Distance text or arrow does not update: implement the interface events on the assigned Widget Blueprint, and use the component reference supplied by the event.
Marker clips: ensure the widget reports a useful desired size. A full-screen Canvas or child render offsets can make the intended marker bounds misleading. Use a compact Size Box/Overlay and reserve room for arrow artwork.
Arrow faces away: use left-facing artwork, or add 180 degrees for a right-facing image.
Wrong view: leave Custom Camera empty for the normal player view, or assign the camera whose projection you intend to use. The component cannot make an unrelated rendered view match a custom camera.
Different player receives it: Local Player Index refers to local players, not remote player/controller IDs.

COMPATIBILITY AND LIMITS
Windows (Win64), Unreal Engine 5.7 and 5.8. Runtime module: SimpleWaypoint. Descriptor: SimpleWaypoint.uplugin. Required plugins: none. Uses Unreal's built-in Engine, UMG and Slate modules; no third-party libraries.
No occlusion tracing: a marker can show through walls. No built-in marker clustering, objective replication, UI art or navigation. VR/stereo-specific eye projection, custom viewport managers and non-Windows platforms are not validated. Each active marker updates every frame, so profile your own marker counts and widget complexity. There is no promised unlimited-performance marker count.

Support: https://discord.gg/9Zc4wbwqG9