Class PrefabMarkerManager

Namespace

LansMap.Markers.World

Assembly

LansMap.Runtime.dll

Manages marker GameObjects positioned on the map.

public sealed class PrefabMarkerManager : MonoBehaviour

Inheritance

object

Object

Component

Behaviour

MonoBehaviour

PrefabMarkerManager

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("Obsolete: set BaseMapView.PlaneDistance instead. Kept one minor release for existing serialized data.")]
[Obsolete("use BaseMapView.PlaneDistance", false)]
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 PrefabMarkerInstance HoveredMarker { get; }

Property Value

PrefabMarkerInstance

IsDraggingMarker

Whether this manager currently captures the pointer for a marker drag.

public bool IsDraggingMarker { get; }

Property Value

bool

IsMarkerPressed

Whether a marker press is in progress and has not been travel-disqualified. Inside ClickSlopPx it may still resolve as Clicked or LongPressed while the map pans underneath it; it stays true for the whole marker drag.

public bool IsMarkerPressed { get; }

Property Value

bool

Markers

public IReadOnlyList<PrefabMarkerInstance> Markers { get; }

Property Value

IReadOnlyList<PrefabMarkerInstance>

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 PrefabMarkerInstance 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

PrefabMarkerInstance

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(PrefabMarkerInstance)

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

public void Despawn(PrefabMarkerInstance marker)

Parameters

marker PrefabMarkerInstance

Instance previously returned by Spawn or Adopt.

EffectiveCaptionFont(PrefabMarkerInstance)

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

public Font EffectiveCaptionFont(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

Marker whose override is consulted.

Returns

Font

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

EffectiveCaptionFontSize(PrefabMarkerInstance)

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

public int EffectiveCaptionFontSize(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

Marker whose override is consulted.

Returns

int

Caption font size in panel px.

EffectiveCaptionTextColor(PrefabMarkerInstance)

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

public Color EffectiveCaptionTextColor(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

Marker whose override is consulted.

Returns

Color

Caption RGBA; alpha 0 means no inline color.

EffectiveDrawLabels(PrefabMarkerInstance)

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

public bool EffectiveDrawLabels(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

Marker whose override is consulted.

Returns

bool

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

EffectiveHideOffscreenMarkers(PrefabMarkerInstance)

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

public bool EffectiveHideOffscreenMarkers(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

Marker whose override is consulted.

Returns

bool

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

EffectiveHoverBackground(PrefabMarkerInstance)

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

public Color EffectiveHoverBackground(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

Marker whose override is consulted.

Returns

Color

Hover-card background RGBA.

EffectiveHoverFont(PrefabMarkerInstance)

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

public Font EffectiveHoverFont(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

Marker whose override is consulted.

Returns

Font

Font used to draw the hover card, or null.

EffectiveHoverFontSize(PrefabMarkerInstance)

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

public int EffectiveHoverFontSize(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

Marker whose override is consulted.

Returns

int

Hover-card font size in panel px.

EffectiveHoverRadiusPx(PrefabMarkerInstance)

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

public float EffectiveHoverRadiusPx(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

Marker whose override is consulted.

Returns

float

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

EffectiveHoverScale(PrefabMarkerInstance)

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

public float EffectiveHoverScale(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

Marker whose override is consulted.

Returns

float

Unitless factor the hovered marker grows by.

EffectiveHoverTextColor(PrefabMarkerInstance)

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

public Color EffectiveHoverTextColor(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

Marker whose override is consulted.

Returns

Color

Hover-card text RGBA.

EffectiveLockToMapRotation(PrefabMarkerInstance)

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

public bool EffectiveLockToMapRotation(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

Marker whose override is consulted.

Returns

bool

True when the marker rotates with map bearing and pitch.

EffectiveModelUpIsY(PrefabMarkerInstance)

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

public bool EffectiveModelUpIsY(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

Marker whose override is consulted.

Returns

bool

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

EffectiveOffscreenMarginPx(PrefabMarkerInstance)

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

public float EffectiveOffscreenMarginPx(PrefabMarkerInstance m)

Parameters

m PrefabMarkerInstance

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(PrefabMarkerInstance, ScreenPoint)

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

public bool IsWithinScreenMargin(PrefabMarkerInstance m, ScreenPoint s)

Parameters

m PrefabMarkerInstance

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 PrefabMarkerInstance 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

PrefabMarkerInstance

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(PrefabMarkerInstance, PrefabMarkerInstance)

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

public static bool ShouldFireHoverEnter(PrefabMarkerInstance previous, PrefabMarkerInstance current)

Parameters

previous PrefabMarkerInstance

Marker hovered last frame, or null.

current PrefabMarkerInstance

Marker hovered this frame, or null.

Returns

bool

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

ShouldFireHoverExit(PrefabMarkerInstance, PrefabMarkerInstance)

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

public static bool ShouldFireHoverExit(PrefabMarkerInstance previous, PrefabMarkerInstance current)

Parameters

previous PrefabMarkerInstance

Marker hovered last frame, or null.

current PrefabMarkerInstance

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 PrefabMarkerInstance 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

PrefabMarkerInstance

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 PrefabMarkerInstance)

Resolves a MarkerRef to the prefab instance it names.

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

Parameters

markerRef MarkerRef

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

marker PrefabMarkerInstance

The live instance, or null when this returns false.

Returns

bool

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

TryGet(int, out PrefabMarkerInstance)

Resolves a prefab handle from Id.

public bool TryGet(int handle, out PrefabMarkerInstance marker)

Parameters

handle int

Slot+generation id this manager handed out.

marker PrefabMarkerInstance

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<PrefabMarkerInstance> Clicked

Event Type

Action<PrefabMarkerInstance>

DragEnded

Fires once when drag capture ends. Instance-level DragEnded fires first. No revert; no cancelled flag.

public event Action<PrefabMarkerInstance, LatLon> DragEnded

Event Type

Action<PrefabMarkerInstance, LatLon>

DragMoved

Fires on every drag frame the pointer has a position. Instance-level DragMoved fires first.

public event Action<PrefabMarkerInstance, LatLon> DragMoved

Event Type

Action<PrefabMarkerInstance, LatLon>

DragStarted

Fires the frame drag capture begins. Instance-level DragStarted fires first.

public event Action<PrefabMarkerInstance> DragStarted

Event Type

Action<PrefabMarkerInstance>

EnteredView

Fires the frame a marker's projected position enters the offscreen margin. See LeftView for the exact test.

public event Action<PrefabMarkerInstance> EnteredView

Event Type

Action<PrefabMarkerInstance>

HoverEntered

public event Action<PrefabMarkerInstance> HoverEntered

Event Type

Action<PrefabMarkerInstance>

HoverExited

public event Action<PrefabMarkerInstance> HoverExited

Event Type

Action<PrefabMarkerInstance>

LeftView

Fires the frame a marker's projected position leaves the offscreen margin, is disabled, or is despawned while in view. A despawn-raised instance has IsLive false; check it before dereferencing.

public event Action<PrefabMarkerInstance> LeftView

Event Type

Action<PrefabMarkerInstance>

LongPressed

public event Action<PrefabMarkerInstance> LongPressed

Event Type

Action<PrefabMarkerInstance>

PositionChanged

Mirrors every PositionChanged from a marker this manager owns, whether the move came from game code or drag capture.

public event Action<PrefabMarkerInstance, LatLon> PositionChanged

Event Type

Action<PrefabMarkerInstance, LatLon>