Class WorldMarkerManager

Namespace

LansMap.Markers.World

Manages marker GameObjects positioned on the map.

public sealed class WorldMarkerManager : MonoBehaviour

Inheritance

object

Object

Component

Behaviour

MonoBehaviour

WorldMarkerManager

Remarks

This is the only prefab-tier GameObject store. Map is a BaseMapView (screen or surface). BindView(BaseMapView, TabletopContentView) reparents the same instances and handles onto a table or back.

Fields

CaptionFont

[FormerlySerializedAs("FontOverride")]
[Tooltip("Caption font; empty = the map's global LabelFont.")]
public Font CaptionFont

Field Value

Font

CaptionFontSize

[Tooltip("Caption font size.")]
public int CaptionFontSize

Field Value

int

CaptionTextColor

[Tooltip("Caption text color. Alpha 0 (the default) means no inline color: the on-map USS class's var(--text) and text-shadow show through unchanged.")]
public Color CaptionTextColor

Field Value

Color

ClickSlopPx

[Tooltip("Pointer travel in pixels that turns a press-on-a-marker into a miss instead of Clicked/LongPressed.")]
public float ClickSlopPx

Field Value

float

DrawLabels

[Tooltip("Show Label text under markers and HoverText near the cursor.")]
public bool DrawLabels

Field Value

bool

HideOffscreenMarkers

[Tooltip("Deactivate marker GameObjects while outside the viewport.")]
public bool HideOffscreenMarkers

Field Value

bool

HoverBackground

[FormerlySerializedAs("DefaultBackground")]
[Tooltip("Hover card background color.")]
public Color HoverBackground

Field Value

Color

HoverFont

[Tooltip("Hover card font; empty = the map's global LabelFont.")]
public Font HoverFont

Field Value

Font

HoverFontSize

[FormerlySerializedAs("DefaultFontSize")]
[Tooltip("Hover card font size.")]
public int HoverFontSize

Field Value

int

HoverRadiusPx

[Tooltip("Hover radius in pixels when the prefab has no collider. Colliders win.")]
public float HoverRadiusPx

Field Value

float

HoverRaycastMask

[Tooltip("Layers hover raycasts test. Default everything. Excluded layers are not hoverable.")]
public LayerMask HoverRaycastMask

Field Value

LayerMask

HoverScale

[Tooltip("Hovered marker grows by this factor (parity with the 2D tier).")]
public float HoverScale

Field Value

float

HoverTextColor

[FormerlySerializedAs("DefaultTextColor")]
[Tooltip("Hover card text color.")]
public Color HoverTextColor

Field Value

Color

LockToMapRotation

[Tooltip("Rotate markers with the map bearing and pitch so they stay glued to the world instead of the screen.")]
public bool LockToMapRotation

Field Value

bool

LongPressSeconds

[Tooltip("Hold this long on a marker (without moving past Click Slop Px) for LongPressed instead of Clicked.")]
public float LongPressSeconds

Field Value

float

Map

View this manager poses markers against (screen or surface).

public BaseMapView Map

Field Value

BaseMapView

MaxPrefabGeneration

Reuses of one slot before it is retired.

public const int MaxPrefabGeneration = 524287

Field Value

int

MaxPrefabSlots

Slots this manager can ever hand out.

public const int MaxPrefabSlots = 4096

Field Value

int

ModelUpIsY

[Tooltip("Stand models upright: local +Y points out of the map plane (toward the viewer at pitch 0).")]
public bool ModelUpIsY

Field Value

bool

OffscreenMarginPx

[Tooltip("Extra pixels around the screen still counted as visible.")]
public float OffscreenMarginPx

Field Value

float

OverlayWFloor

[Tooltip("Overlay markers, labels and trails stop rising once their perspective W reaches this floor, so a marker passing eye level slides off the top edge instead of vanishing mid-screen. Negative means compute it from the camera, which is the recommended setting. 0 disables the floor.")]
public float OverlayWFloor

Field Value

float

PlaneDistance

[Tooltip("Distance from camera at which markers are placed.")]
public float PlaneDistance

Field Value

float

Tabletop

Table this manager poses onto; empty poses on the screen camera plane.

[Tooltip("Table to pose markers on. Empty poses on the screen camera plane.")]
public TabletopContentView Tabletop

Field Value

TabletopContentView

TargetCamera

public Camera TargetCamera

Field Value

Camera

TieBiasDepthFraction

How much real view depth, as a fraction of PlaneDistance, the 2D overlay tier is nudged toward the viewer so it wins an exact depth tie against 3D models.

public const double TieBiasDepthFraction = 0.001

Field Value

double

Properties

HiddenByCluster

public bool HiddenByCluster { get; set; }

Property Value

bool

HoveredMarker

public WorldMarkerInstance HoveredMarker { get; }

Property Value

WorldMarkerInstance

Markers

public IReadOnlyList<WorldMarkerInstance> Markers { get; }

Property Value

IReadOnlyList<WorldMarkerInstance>

MercatorRecomputeCount

public int MercatorRecomputeCount { get; }

Property Value

int

ProjectionRefreshCount

public int ProjectionRefreshCount { get; }

Property Value

int

Methods

Adopt(GameObject, double, double, double, MarkerAltitudeMode)

Adopts an existing GameObject as a prefab-tier marker without instantiating and reparents it onto the table PrefabAnchor or this manager's Root.

public WorldMarkerInstance Adopt(GameObject go, double lat, double lon, double altitudeMeters, MarkerAltitudeMode altitudeMode = MarkerAltitudeMode.RelativeToGround)

Parameters

go GameObject

Existing GameObject to adopt; reparented onto the table PrefabAnchor or this manager's Root.

lat double

Latitude in degrees WGS84.

lon double

Longitude in degrees WGS84.

altitudeMeters double

Authored altitude in meters; meaning depends on altitudeMode.

altitudeMode MarkerAltitudeMode

How altitudeMeters is resolved against sampled ground. Default RelativeToGround.

Returns

WorldMarkerInstance

Handle this manager repositions on every view change.

Remarks

This manager overwrites the adopted GameObject's transform every frame to keep it map-anchored. Do not drive its position or rotation with a Rigidbody or other physics motion; that motion is overwritten every frame by the reprojection.

BindView(BaseMapView, TabletopContentView)

Points this manager at a screen or surface view and reparents every spawned GameObject onto the table PrefabAnchor or back onto this manager's Root.

public void BindView(BaseMapView map, TabletopContentView table)

Parameters

map BaseMapView

View this manager poses against (screen or surface).

table TabletopContentView

Table to pose onto; null poses on the screen camera plane.

Remarks

Same instances and same handles; this is the only prefab store.

Despawn(WorldMarkerInstance)

Destroys the marker GameObject and frees its prefab-tier id.

public void Despawn(WorldMarkerInstance marker)

Parameters

marker WorldMarkerInstance

Instance previously returned by Spawn or Adopt.

EffectiveCaptionFont(WorldMarkerInstance)

Effective caption font for m; the marker override, else this manager's font, else the map's LabelFont.

public Font EffectiveCaptionFont(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

Font

Font used to draw the on-map caption, or null.

EffectiveCaptionFontSize(WorldMarkerInstance)

Effective caption font size for m; the marker override if set, otherwise this manager's value.

public int EffectiveCaptionFontSize(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

int

Caption font size in panel px.

EffectiveCaptionTextColor(WorldMarkerInstance)

Effective caption text color for m; the marker override if set, otherwise this manager's value.

public Color EffectiveCaptionTextColor(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

Color

Caption RGBA; alpha 0 means no inline color.

EffectiveDrawLabels(WorldMarkerInstance)

Effective draw-labels for m; the marker override if set, otherwise this manager's value.

public bool EffectiveDrawLabels(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

bool

True when the on-map caption may draw for this marker.

EffectiveHideOffscreenMarkers(WorldMarkerInstance)

Effective hide-offscreen for m; the marker override if set, otherwise this manager's value.

public bool EffectiveHideOffscreenMarkers(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

bool

True when the marker deactivates while outside the viewport plus margin.

EffectiveHoverBackground(WorldMarkerInstance)

Effective hover-card background for m; the marker override if set, otherwise this manager's value.

public Color EffectiveHoverBackground(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

Color

Hover-card background RGBA.

EffectiveHoverFont(WorldMarkerInstance)

Effective hover-card font for m; the marker override, else this manager's font, else the map's LabelFont.

public Font EffectiveHoverFont(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

Font

Font used to draw the hover card, or null.

EffectiveHoverFontSize(WorldMarkerInstance)

Effective hover-card font size for m; the marker override if set, otherwise this manager's value.

public int EffectiveHoverFontSize(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

int

Hover-card font size in panel px.

EffectiveHoverRadiusPx(WorldMarkerInstance)

Effective hover radius for m; the marker override if set, otherwise this manager's value.

public float EffectiveHoverRadiusPx(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

float

Anchor-pick radius in screen px when the prefab has no collider.

EffectiveHoverScale(WorldMarkerInstance)

Effective hover scale for m; the marker override if set, otherwise this manager's value.

public float EffectiveHoverScale(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

float

Unitless factor the hovered marker grows by.

EffectiveHoverTextColor(WorldMarkerInstance)

Effective hover-card text color for m; the marker override if set, otherwise this manager's value.

public Color EffectiveHoverTextColor(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

Color

Hover-card text RGBA.

EffectiveLockToMapRotation(WorldMarkerInstance)

Effective lock-to-map-rotation for m; the marker override if set, otherwise this manager's value.

public bool EffectiveLockToMapRotation(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

bool

True when the marker rotates with map bearing and pitch.

EffectiveModelUpIsY(WorldMarkerInstance)

Effective model-up-is-Y for m; the marker override if set, otherwise this manager's value.

public bool EffectiveModelUpIsY(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

bool

True when local +Y points out of the map plane.

EffectiveOffscreenMarginPx(WorldMarkerInstance)

Effective offscreen margin for m; the marker override if set, otherwise this manager's value.

public float EffectiveOffscreenMarginPx(WorldMarkerInstance m)

Parameters

m WorldMarkerInstance

Marker whose override is consulted.

Returns

float

Extra screen px around the viewport still counted as visible.

IsLive(int)

Whether handle still names a spawned prefab marker on this manager.

public bool IsLive(int handle)

Parameters

handle int

Slot+generation id from Id.

Returns

bool

True while the marker is still in this manager's live list.

IsWithinClickSlop(Vector3, Vector3, float)

Whether pointer travel since press still counts as a click rather than a drag.

public static bool IsWithinClickSlop(Vector3 currentPos, Vector3 downPos, float slopPx)

Parameters

currentPos Vector3

Current pointer position in screen px.

downPos Vector3

Press position in screen px.

slopPx float

Allowed travel in screen px.

Returns

bool

True when the squared distance is at most slopPx squared.

IsWithinScreenMargin(WorldMarkerInstance, ScreenPoint)

Whether the projected point still counts as on-screen given m's offscreen margin.

public bool IsWithinScreenMargin(WorldMarkerInstance m, ScreenPoint s)

Parameters

m WorldMarkerInstance

Marker whose OffscreenMarginPx override is consulted.

s ScreenPoint

Projected position in screen px, origin top-left.

Returns

bool

True when s lies within the viewport plus that margin in screen px.

LongPressElapsed(double, double, double)

Whether a held press has reached the long-press threshold.

public static bool LongPressElapsed(double downTime, double now, double longPressSeconds)

Parameters

downTime double

Press time in seconds (realtime).

now double

Current time in seconds (realtime).

longPressSeconds double

Hold duration in seconds that becomes LongPressed.

Returns

bool

True when now minus downTime is at least longPressSeconds.

NeedsProjectionRefresh(MapViewTransform, MapViewTransform, bool, int, int, IElevationSampler, IElevationSampler)

Whether the shared projection cache must be recomputed for this view and store version.

public static bool NeedsProjectionRefresh(MapViewTransform view, MapViewTransform lastView, bool hasLastView, int storeVersion, int lastStoreVersion, IElevationSampler sampler, IElevationSampler lastSampler)

Parameters

view MapViewTransform

Current map view transform.

lastView MapViewTransform

View used when the cache was last filled.

hasLastView bool

False on the first call, when no prior fill exists.

storeVersion int

Current spawn, despawn, or move generation.

lastStoreVersion int

Generation at the last fill.

sampler IElevationSampler

Current elevation sampler instance (Map's), or null for flat.

lastSampler IElevationSampler

Sampler instance the last fill resolved against.

Returns

bool

True when the cache is empty, the view moved, a marker was added, removed, or moved, or the sampler instance itself swapped. The sampler is compared directly (not only through the view) because a surface-hosted view is deliberately built without a terrain argument and would otherwise never report a sampler swap.

PickAt(MapViewTransform, Ray, ScreenPoint, out double)

Prefab-tier pick at a ray and screen point: collider hit if the prefab has one, otherwise nearest projected-anchor within hover radius.

public WorldMarkerInstance PickAt(MapViewTransform view, Ray ray, ScreenPoint screen, out double distanceSq)

Parameters

view MapViewTransform

View whose projection the anchor fallback uses.

ray Ray

World ray to test against prefab colliders.

screen ScreenPoint

Cursor in top-left-origin screen px, matching MapViewTransform output.

distanceSq double

0 for a collider hit or a miss; otherwise squared screen-px distance to the winning anchor.

Returns

WorldMarkerInstance

The hit marker, or null.

ShouldEmitHover(int)

Whether HoverEntered and HoverExited may fire this frame.

public static bool ShouldEmitHover(int touchCount)

Parameters

touchCount int

Active touch count; 0 means no touch.

Returns

bool

True only when no touch is active, so a tap is not reported as a hover.

ShouldFireHoverEnter(WorldMarkerInstance, WorldMarkerInstance)

Whether HoverEntered should fire for this previous-to-current hover transition.

public static bool ShouldFireHoverEnter(WorldMarkerInstance previous, WorldMarkerInstance current)

Parameters

previous WorldMarkerInstance

Marker hovered last frame, or null.

current WorldMarkerInstance

Marker hovered this frame, or null.

Returns

bool

True when a marker is hovered that was not hovered last frame.

ShouldFireHoverExit(WorldMarkerInstance, WorldMarkerInstance)

Whether HoverExited should fire for this previous-to-current hover transition.

public static bool ShouldFireHoverExit(WorldMarkerInstance previous, WorldMarkerInstance current)

Parameters

previous WorldMarkerInstance

Marker hovered last frame, or null.

current WorldMarkerInstance

Marker hovered this frame, or null.

Returns

bool

True when a marker was hovered and the hover moved off it.

Spawn(GameObject, double, double, double, MarkerAltitudeMode)

Instantiates prefab as a prefab-tier marker at a geographic position.

public WorldMarkerInstance Spawn(GameObject prefab, double lat, double lon, double altitudeMeters, MarkerAltitudeMode altitudeMode = MarkerAltitudeMode.RelativeToGround)

Parameters

prefab GameObject

Prefab to instantiate; parented onto the table PrefabAnchor or this manager's Root.

lat double

Latitude in degrees WGS84.

lon double

Longitude in degrees WGS84.

altitudeMeters double

Authored altitude in meters; meaning depends on altitudeMode.

altitudeMode MarkerAltitudeMode

How altitudeMeters is resolved against sampled ground. Default RelativeToGround.

Returns

WorldMarkerInstance

Handle this manager repositions on every view change.

Remarks

This manager overwrites the spawned GameObject's transform every frame to keep it map-anchored. Do not drive its position or rotation with a Rigidbody or other physics motion; that motion is overwritten every frame by the reprojection.

TryGet(in MarkerRef, out WorldMarkerInstance)

Resolves a MarkerRef to the prefab instance it names.

public bool TryGet(in MarkerRef markerRef, out WorldMarkerInstance marker)

Parameters

markerRef MarkerRef

Cross-tier ref; must be Prefab and not none.

marker WorldMarkerInstance

The live instance, or null when this returns false.

Returns

bool

False when the ref is none, not Prefab, or stale.

TryGet(int, out WorldMarkerInstance)

Resolves a prefab handle from Id.

public bool TryGet(int handle, out WorldMarkerInstance marker)

Parameters

handle int

Slot+generation id this manager handed out.

marker WorldMarkerInstance

The live instance, or null when this returns false.

Returns

bool

False when the id is stale after Despawn and reuse, or was never live here.

Events

Clicked

public event Action<WorldMarkerInstance> Clicked

Event Type

Action<WorldMarkerInstance>

HoverEntered

public event Action<WorldMarkerInstance> HoverEntered

Event Type

Action<WorldMarkerInstance>

HoverExited

public event Action<WorldMarkerInstance> HoverExited

Event Type

Action<WorldMarkerInstance>

LongPressed

public event Action<WorldMarkerInstance> LongPressed

Event Type

Action<WorldMarkerInstance>