nav-climb

name	nav-climb
type	python
description	Attempt exactly ONE adjacent climb (+1Y) forward. Atomic navigation operation suitable for composition. nav-climb does not build, it traverses *existing* terrain
schema_hint	{"value":"ignored","step_duration":"float seconds for the move attempt (default: 0.6)","allow_walkable_landing":"boolean, if True accepts walkable landings (default: True)","min_delta_y":"float minimum Y gain to count as climb (default: 0.9)","out":"$variable"}
examples	["{\"type\":\"nav-climb\",\"step_duration\":0.6,\"out\":\"$climb\"}"]

nav-climb

Attempt exactly ONE adjacent climb forward: move into a neighbor cell ~+1 block higher. Tries walk-up first, then jump-up if needed.

Input

• step_duration: Float seconds for each move attempt (default: 0.6)
• allow_walkable_landing: Boolean, accepts walkable landings like snow (default: True)
• min_delta_y: Float minimum Y gain to count as climb (default: 0.9)

Output

Success (status: "success"):

• value: Summary text
• extra.from: Starting position {x, y, z}
• extra.to: Ending position {x, y, z}
• extra.delta_y: Vertical displacement (≥ min_delta_y)
• extra.mode: "walk" or "jump"
• extra.support_here: Support type at destination

Failure (status: "failed"):

• reason: One of "status_failed", "collision", "fell", "observation_failed", "support_ambiguous", "not_elevated"
• extra.diagnostics: When reason="collision", contains clearance data:
  • up_block: Block directly overhead (use dirs.up.blk, NOT nav_surface.cover_block)
  • clear_fwd_head, clear_up_head: Head clearance flags
  • fwd_block: Block forward

Clearance Requirements

For nav-climb to succeed, BOTH source and destination must satisfy clearance:

Source (current position):

• Grid cell above head (real y+2) must be clear
• No adjacent overhangs at (x±1, z±1, y+1) or (x±1, z±1, y+2)

Destination (forward, y+1):

• Body space at (fwd+1, y+1) and head space at (fwd+1, y+2) must be clear
• Supporting block at (fwd+1, y) must be walkable.

Verification: Use dirs.up.blk to check overhead (NOT nav_surface.cover_block - those are offset cells).

Invariants

• Automatically aligns agent to block center and cardinal yaw before climb attempt
• Exactly one elevation gain attempt per call (always forward, relative to current yaw)
• Tries walk-up first, then jump-up if walk-up insufficient
• Elevation gain must be ≥ min_delta_y to succeed
• Snaps to block center after any position change
• Updates world_state("nav") history

Cannot climb straight up: Requires forward movement. A block at [0,1,0] (purely above) is not climbable unless there's a forward elevated landing. nav-turn changes forward direction but cannot make vertical become forward.

Alignment

Before climb attempt, agent is automatically aligned:

• Position: Block center (x+0.5, y, z+0.5) - eliminates fractional offsets
• Yaw: Nearest cardinal (0°=South, 90°=West, 180°=North, 270°=East)
• Pitch: 0°

This prevents collisions from fractional offsets and ensures predictable forward direction.

Collision Recovery

When reason="collision", check extra.diagnostics:

• up_block=null but collision → likely overhang (adjacent cell blocks jump arc)
• clear_fwd_head=false → destination head space blocked
• clear_up_head=false → overhead clearance insufficient

Recovery strategies (after 1 failed climb + 1 failed dig → change topology):

1. Lateral escape: Move sideways to fully open column (dirs.up.blk=null)
2. Overhang removal: Dig forward+up with absolute coordinates (floor(x), y+2, floor(z))
3. Pillar up: Use mc-place-until-supported to build upward

Planning Notes

• Does not handle multi-block climbs; compose multiple calls for that
• Use nav-turn before climbing to change direction (yaw determines forward direction)
• Alignment to block center and cardinal yaw happens automatically (no manual alignment needed)
• Default step_duration (0.6s) is longer than nav-move (0.2s) for step-up mechanics
• After repeated failures, switch strategy rather than retry

Example Workflow

{"type":"nav-turn","direction":"right","out":"$t"}
{"type":"nav-climb","out":"$climb1"}
{"type":"nav-climb","out":"$climb2"}