From c9d74ef49bc8370a6e316b6062be03cad43c2b29 Mon Sep 17 00:00:00 2001
From: popertots <popertots@gmail.com>
Date: Sat, 4 Apr 2026 12:29:03 +0100
Subject: [PATCH] Update z-level context: not underground, perlin terrain,
 check working pathfinding

---
 NEXT_SESSION_PROMPT.md | 29 +++++++++++++++++++++--------
 1 file changed, 21 insertions(+), 8 deletions(-)

diff --git a/NEXT_SESSION_PROMPT.md b/NEXT_SESSION_PROMPT.md
index 12a12c8..dc493e2 100644
--- a/NEXT_SESSION_PROMPT.md
+++ b/NEXT_SESSION_PROMPT.md
@@ -146,14 +146,27 @@ grep -E "target=None" output.log | head -10
 grep -E "setting target" output.log
 ```
 
-## Critical Context: The Z-Level Problem
+## Critical Context: The Z-Level System
 
-The world has multiple Z-levels (not flat). A tree at position (32, 32, 16) has z=16. The trunk might be at surface level while nearby standable tiles could be at z=0, z=16, or z=32.
+**IMPORTANT: READ `src/world/generation/terrain.rs` AND `src/entities/shared_systems/pathfinding.rs` FIRST.**
 
-The `find_all_standable_adjacent` BFS (in executor.rs) searches for standable tiles at the cargo's z-level. This works for 2D but may fail for 3D if:
-1. Cargo is on z=16 surface
-2. Approach tile found at z=16
-3. But the dorf is at z=0 underground
-4. Pathfinding z=0 → z=16 might fail or not exist
+The world is NOT flat. The terrain is generated using Perlin noise:
+- The surface height varies - z is NOT "underground" or "surface", it's HEIGHT
+- A tile at z=0 might be surface at one location and underground/void at another
+- Trees, rocks, items can spawn at various z-levels based on terrain
+- Dorfs walk on the surface at whatever z-level that happens to be
 
-**IF dorfs still freeze after the current fix, the z-level is the next place to investigate.**
\ No newline at end of file
+The existing entity pathfinding system (in `src/entities/shared_systems/pathfinding.rs`) WORKS. It correctly handles z-levels. Study it to understand:
+1. How `is_standable()` works across z-levels
+2. How `ALLOWED_MOVES` includes diagonal 3D movement
+3. How entities navigate from z=0 to z=16 or vice versa
+
+**The HaulCargo approach finding BFS (in executor.rs) only searches at cargo's z-level.** This may be correct OR may need to search 3D-adjacent tiles like the entity pathfinding does.
+
+**If dorfs freeze after the current fix:**
+1. Compare `find_all_standable_adjacent()` in executor.rs with the working pathfinding
+2. Check if approach tiles found are actually reachable from the dorf's position
+3. Look at `job_pathfinding.rs: find_all_standable_adjacent()` - does it search 3D?
+4. The job_pathfinding system calls `calculate_traversal_distance()` which uses full A* - if this returns `Err(())`, the job stays Unclaimed
+
+**Key question**: The traversal distance calculation in `src/entities/shared_systems/pathfinding.rs` uses the same pathfinding as entity movement. If that works for movement, why wouldn't it work for job assignment?**
\ No newline at end of file