init

name	init
type	python
description	Initialize navigation state by normalizing agent pose to block center, cardinal yaw, and pitch zero.
schema_hint	{"value":"ignored","out":"$variable"}
examples	["{\"type\":\"init\",\"out\":\"$init_result\"}","{\"type\":\"init\"}"]

Minecraft Initialization Tool

Skill: INIT

Level

Level 1 — Initialization primitive

Purpose

Initialize navigation state by normalizing the agent's current pose to block center, cardinal yaw (0, 90, 180, or 270 degrees), and pitch zero. This tool is automatically executed during executor initialization if present in the tool catalog.

Primitives Used

• mc-status: Get current position, yaw, and pitch
• nav-turn: Normalize orientation to cardinal direction and snap to block center
• executor.set_world_state: Update navigation state in world state

Input

• value: ignored
• No parameters required

Output

• Uniform return format dict:
  • status: 'success' or 'failed' (execution status)
  • value: Summary text describing the normalized pose
  • data: structured data dict containing:
    • success: Boolean indicating if initialization succeeded
    • pose: Normalized pose dict {"x": float, "y": float, "z": float, "yaw": float}
    • normalized_from: Original pose before normalization {"x": float, "y": float, "z": float, "yaw": float, "pitch": float} (only present if success=True)
    • failure_reason: One of "status_failed", "turn_failed", "turn_failed_<reason>", "normalized_status_failed" (only present if success=False)
  • resource_id: None (no resource created)

Success Outcomes

When success=True:

• success: True
• pose: Normalized pose with block-centered position (x, z at block center ±0.5), cardinal yaw (0, 90, 180, or 270), and pitch 0
• normalized_from: Original pose before normalization

Failure Outcomes

When success=False:

• success: False
• failure_reason: Specific reason for failure

Failure Reasons:

• "status_failed": Failed to get initial status from mc-status
• "turn_failed": nav-turn execution failed
• "turn_failed_<reason>": nav-turn failed with specific reason (e.g., "turn_failed_status_failed", "turn_failed_snapto_failed")
• "normalized_status_failed": Failed to get normalized status after nav-turn

Post-Conditions

After successful initialization:

• Agent is positioned at block center (x, z coordinates at block center ±0.5)
• Agent yaw is a cardinal direction (0°, 90°, 180°, or 270°)
• Agent pitch is 0° (horizontal)
• Navigation state is initialized in world_state.nav with normalized pose

Invariants

• Always normalizes pose before initializing state
• Always verifies normalization with second mc-status call
• Navigation state structure is consistent (pose, support_here, fell, history)
• Block-centered positioning ensures predictable navigation starting point

Notes

• This tool is automatically executed during executor initialization if present in the tool catalog
• The tool name must be init or <world_name>-init (e.g., minecraft-init) to be auto-executed
• Normalization ensures consistent starting state for navigation operations
• Support assessment (support_here) is left as "unknown" and should be updated by first navigation operation
• Navigation history starts empty and is populated by nav-move, nav-climb, and nav-descend tools

Common Workflow

This tool is typically executed automatically during system initialization:

{"type":"init"}

• No manual invocation needed if tool is present in world-tools/<world_name>/init/
• Executor automatically runs init tool after full tool catalog is loaded
• Higher-level planners can assume navigation state is initialized after executor startup

Cognitive Contract

• INITIALIZATION-FOCUSED: Establishes consistent starting state for navigation
• NORMALIZATION-BASED: Ensures predictable pose (block-centered, cardinal yaw, zero pitch)
• STATE-MANAGEMENT: Initializes world state structure for navigation tracking
• AUTOMATIC: Executes during executor initialization if present
• VERIFICATION-BASED: Confirms normalization before reporting success