navigation_table

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

hasTarget()Check whether the nav table has resolved a live target.
getTargetType()Get the registry id of the held nav-table item type.
getTargetMetadata()Get item-specific metadata for the held nav-table item.
getRelativeAngle()Get the raw relative angle to the target, in degrees.
getRelativeAngleRad()Get the raw relative angle to the target, in radians.
getBearing()Get the forward-error bearing to the target.
getBearingRad()Get the forward-error bearing to the target, in radians.
getDistanceToTarget()Get the distance to the resolved target.
getClosureRate()Get the rate at which the table is closing on the target.
getVerticalOffsetToTarget()Get the vertical offset between target and the table's projected position.
getOrientation()Get the host sub-level's orientation as a quaternion.
getHeading()Get the host sub-level's heading in degrees.
getHeadingRad()Get the host sub-level's heading in radians.
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 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.
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()`KeysNotes
`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.
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.