navigation_table

A navigation table. Reports the resolved target's bearing, distance, closure rate, vertical offset, the held item's identity and name, and the host sub-level's orientation/heading.

hasTarget()Source

Check whether the nav table has resolved a live target. hasTarget reports whether the nav table has resolved a live target (currentTarget). getTargetType / getTargetMetadata / getTargetName describe the held nav-table item itself — these can be populated even when no target is locked yet, so hasTarget() == false does not imply getTargetType() == nil.

Returns

1. boolean True if a live target is resolved.

getTargetType()Source

Get the registry id of the held nav-table item type.

Returns

1. string The target type id, or nil if no item is held.

getTargetName()Source

Get the custom name of the held nav-table item. This is the name a player gave the item on an anvil, and it is the only human-readable identity a waypoint has. It matters for the items that carry a per-item destination: a lodestone-bound compass otherwise identifies itself only by a tracker UUID and a marked map only by a numeric id (getTargetMetadata), while the Explorer's/Nature's Compass compat targets expose no metadata at all. The remaining types resolve to one fixed place — an unbound compass always points at world spawn — so a name on those is decoration. Nil for an item that was never renamed, so a display can fall back to getTargetDisplayName or getTargetType.

Returns

1. string The custom name as plain text, or nil if the item is unnamed or nothing is held.

getTargetDisplayName()Source

Get the display name of the held nav-table item. The custom name when the item has one, otherwise the item's own name — so this is never nil while something is held. The fallback is resolved against whatever language table the server has loaded, which for a dedicated server is vanilla English only: a modded item with no custom name can come back as its raw translation key (e.g. item.simulated.magnet). Use getTargetName when only a player-chosen label will do.

Returns

1. string The display name as plain text, or nil if nothing is held.

getTargetMetadata()Source

Get item-specific metadata for the held nav-table item.

Each nav-target type decides its own keys and value types — there is no fixed schema, and what's in the map depends entirely on which item is held. Use getTargetType to branch before reading keys. Returns {} (empty map, not nil) when no item is held or the held item's type exposes no metadata.

Built-in target types and the keys they expose:

Per-target metadata schema

`getTargetType()`	Keys	Notes
`simulated:compass`	`kind` ("lodestone" | "spawn"), `sublevel_id` (string, lodestone only)	"spawn" is the fallback used when the compass isn't bound to a tracked sub-level; `sublevel_id` is the tracker UUID.
`simulated:recovery_compass`	`placer_uuid` (string, optional)	UUID of the player whose death location the compass tracks. Absent until a player has placed the compass into the table.
`simulated:map`	`map_id` (number, optional)	Numeric id of the underlying map item. Absent if the held stack carries no MAP_ID data component (e.g. a blank map).
`simulated:magnet`	—	Static target (10 blocks north of the table); no useful metadata, returns `{}`.

Compat target types from upstream Simulated (e.g. simulated:explorers_compass, simulated:natures_compass) register only when their host mod is present and currently expose no metadata. Third-party NavigationTarget implementations can publish their own keys by implementing NavigationTargetExt#getPeripheralMetadata via mixin.

Returns

1. { [string] = any } A map of target-type-specific metadata, or an empty map.

getRelativeAngle()Source

Get the raw relative angle to the target, in degrees.

Returns

1. number The relative angle in degrees.

getRelativeAngleRad()Source

Get the raw relative angle to the target, in radians.

Returns

1. number The relative angle in radians.

getBearing()Source

Get the forward-error bearing to the target. Forward-error bearing: 0 = target straight ahead of the block's arrow, +90 = target to the right, -90 = to the left, ±180 = behind. The block's arrow points along local +Z, which the raw relativeAngle (atan2(z, x)) encodes as 90°; this method subtracts that offset and wraps to ±180.

Returns

1. number The bearing in degrees, in [-180, 180].

getBearingRad()Source

Get the forward-error bearing to the target, in radians.

Returns

1. number The bearing in radians.

getMaxRange()Source

Get the range beyond which the held item's signal cuts off. Past this range the block stops emitting on every side and the needle carries no information -- which reads identically to being parked on the target, so a program that steers on bearing without checking range can chase a dead needle. Upstream spells "no limit" as a max range of zero; this reports math.huge for that case instead, so the value is always directly comparable against a distance.

The two most common items are the unlimited ones: both simulated:compass and simulated:map declare no cutoff, while everything else takes the 200-block default. So neither "always 200" nor "always unlimited" is a safe assumption to hardcode.

The cutoff upstream applies is measured in the plane perpendicular to the block's facing, not along the 3D distance getDistanceToTarget reports, so treat this as the target type's declared limit rather than an exact predictor of the block's redstone.

Returns

1. number The range limit in blocks, math.huge if the type has none, or nil if no item is held.

getBearingRate()Source

Get the rate at which the bearing to the target is changing. Positive = the target is drifting to the right of the block's arrow. This is the intercept signal: with the target ahead and closing, a bearing rate near zero means the current course arrives at it, while a steady non-zero rate means the course misses by a margin that only grows as range falls. Differenced once per server tick, which is the cadence at which the table itself recomputes the angle, and wrapped across the +/-180 seam so a needle sweeping past dead astern does not read as a full turn the other way.

Zero when no target is resolved, and for one tick after the held item changes -- a swap re-aims the needle instantly, and that jump is not motion of the vehicle. The value grows without bound as range goes to zero (bearing is undefined at the target itself), so gate on getDistanceToTarget before steering on it near arrival.

Returns

1. number The bearing rate in degrees/sec.

getBearingRateRad()Source

Get the rate at which the bearing to the target is changing, in radians.

Returns

1. number The bearing rate in radians/sec.

getDistanceToTarget()Source

Get the distance to the resolved target. Computed in world frame between the table's projected world position and the target's world position.

Returns

1. number The distance in blocks (= meters in Minecraft units).

getClosureRate()Source

Get the rate at which the table is closing on the target. Nav table samples distance every 11 ticks (0.55s); closure rate reflects that cadence — short-window jitter is dominated by the sampling granularity.

Returns

1. number The closure rate in blocks/sec (positive = approaching).

getVerticalOffsetToTarget()Source

Get the vertical offset between target and the table's projected position. Both positions are in world frame (after projecting the table out of any sub-level), so this gives the signed altitude difference regardless of contraption orientation.

Returns

1. number The signed vertical offset target.y - self.y in blocks.

getOrientation()Source

Get the host sub-level's orientation as a quaternion. Quaternion components in {x, y, z, w} order, matching JOML's constructor and the convention used by CC quaternion libraries (e.g. TechTastic/Advanced-Math).

Returns

1. { number... } A four-element list {x, y, z, w}.

getHeading()Source

Get the host sub-level's heading in degrees. Heading: ship's +Z axis rotated into world frame, yaw measured as atan2(x, z). 0° = facing world +Z (Minecraft south), matches player-yaw convention.

Returns

1. number The heading in degrees.

getHeadingRad()Source

Get the host sub-level's heading in radians.

Returns

1. number The heading in radians.