NEON-29: Walk gravity when is_on_floor but feet probe finds void

Jolt + floor snap could keep is_on_floor true over open space toward a
lower click target, so vy stayed 0 until arrival. Add a short downward
ray under the capsule feet (WALK_SUPPORT_PROBE_DEPTH) and apply gravity
when no upward-facing hit is close, only on fairly level floor normals.

client/README.md

@@ -55,7 +55,7 @@ Elevated walkables use **distinct albedo tints** in `scenes/main.tscn` so screen
 
 With the game server running ([`server/README.md`](../server/README.md)), each valid floor click sends a **`MoveCommand`** (**`POST`**) and a follow-up **`GET`** for **`PositionState`**. The server still **snaps** authority to the target (NEON-4/19); the client **moves** toward that verified position using **`NavigationAgent3D`** + a **baked mesh** instead of teleporting on the **`GET`** (NEON-8). **Boot** `sync_from_server()` **snaps** once so spawn matches the server.
 
-**Tradeoff (prototype):** Horizontal motion is a **direct XZ bee-line** toward the server’s verified target. The baked **`NavigationMesh`** is still used when **vertical routing** is active (goal surface clearly above/below the feet, with Schmitt latch) **and** the capsule is inside the **nav column** hysteresis band (`NAV_COLUMN_STEER_ENTER_DIST` / `EXIT`) — so terraces / steps steer via **`NavigationAgent3D.get_next_path_position()`** toward the next waypoint. (A prior **manual** path scan with a **5 cm** “skip near waypoints” threshold caused **180° velocity flips** each physics tick; **`get_next_path_position()`** is **not** used as the **default** bee-line steer for all walking — that still regressed under **Jolt** at **120 Hz** when it was global.) **No descend bypass** for gravity while on an upper deck (same as before). **Automatic routing around tall obstacles on one click is still not guaranteed** — use **several clicks** to go around e.g. the gray **`Obstacle`** when needed.
+**Tradeoff (prototype):** Horizontal motion is a **direct XZ bee-line** toward the server’s verified target. The baked **`NavigationMesh`** is still used when **vertical routing** is active (goal surface clearly above/below the feet, with Schmitt latch) **and** the capsule is inside the **nav column** hysteresis band (`NAV_COLUMN_STEER_ENTER_DIST` / `EXIT`) — so terraces / steps steer via **`NavigationAgent3D.get_next_path_position()`** toward the next waypoint. (A prior **manual** path scan with a **5 cm** “skip near waypoints” threshold caused **180° velocity flips** each physics tick; **`get_next_path_position()`** is **not** used as the **default** bee-line steer for all walking — that still regressed under **Jolt** at **120 Hz** when it was global.) **No descend bypass** for gravity while on an upper deck (same as before). While walking, **gravity** still runs when **`is_on_floor()`** is false; if **snap / lip contacts** keep **`is_on_floor()`** true over open space (e.g. gold deck → gray floor), a short **down probe** under the feet (`WALK_SUPPORT_PROBE_DEPTH` in **`player.gd`**) forces **airborne gravity** when no **upward-facing** hit is that close — without tying gravity to “goal below feet” on the whole upper pad. **Automatic routing around tall obstacles on one click is still not guaranteed** — use **several clicks** to go around e.g. the gray **`Obstacle`** when needed.
 
 **NEON-7 / movement QA bumps:** On **run**, **`spawn_short_random_bumps`** adds **two** green cylinders, each on its own **`StaticBody3D`** **sibling** of **`Floor`** under **`NavigationRegion3D`** (**`walkable`** on bump roots — avoids compound **internal-edge** jitter vs floor+cylinder on one body). Bump meshes use Godot group **`random_floor_bump_mesh`**. **Collision radius** = mesh **+ `COLLISION_RADIUS_EXTRA`** (see **`scripts/random_floor_bump_collision_constants.gd`**, capped by **`COLLISION_RADIUS_MAX`**). **`bake_navigation_mesh(false)`** after spawn.
 

client/scripts/player.gd

@@ -63,6 +63,14 @@ const WALK_STEP_ASSIST_SNAP: float = 0.09
 ## two-level climb in one click (e.g. floor → **TerracePlatformB** violet deck at ~0.6 m — use
 ## **TerraceStepB** gold first, or a second click after standing on the step).
 const WALK_STEP_ASSIST_MAX_SURFACE_DELTA: float = 0.35
+## Ray below capsule feet while walking: if [method CharacterBody3D.is_on_floor] stays true off a
+## ledge (snap + lip contacts), we still need gravity toward the lower floor — without re-applying
+## gravity for every “goal below feet” tick on a whole upper deck (see [member _apply_walk_air_gravity]).
+const WALK_SUPPORT_PROBE_DEPTH: float = 0.22
+const WALK_SUPPORT_PROBE_MIN_UP_DOT: float = 0.42
+## Only second-guess [code]is_on_floor()[/code] when the reported floor is fairly level (skip
+## stair risers / seam normals where a down ray often hits vertical mesh).
+const WALK_LEDGE_PROBE_MAX_FLOOR_UP_DOT: float = 0.92
 ## CapsuleShape3D in scene: height = 1.0 (cylinder portion), radius = 0.4.
 ## Total half-height from body origin to physical bottom = 0.5 + 0.4 = 0.9
 ## (`CAPSULE_HALF_HEIGHT + PLAYER_CAPSULE_RADIUS`).
@@ -316,11 +324,43 @@ func _set_horizontal_velocity_toward(
 	velocity.y = 0.0
 
 
+func _walk_has_close_floor_probe_below() -> bool:
+	var w3d := get_world_3d()
+	if w3d == null:
+		return true
+	var space := w3d.direct_space_state
+	var feet: Vector3 = global_position - Vector3(0.0, CAPSULE_HALF_HEIGHT + PLAYER_CAPSULE_RADIUS, 0.0)
+	# Start slightly above the foot line so the ray is not born inside the deck collider after snap.
+	var probe_from: Vector3 = feet + Vector3.UP * 0.04
+	var probe_end: Vector3 = feet + Vector3.DOWN * WALK_SUPPORT_PROBE_DEPTH
+	var q := PhysicsRayQueryParameters3D.create(probe_from, probe_end)
+	q.collision_mask = collision_mask
+	q.exclude = [get_rid()]
+	var res: Dictionary = space.intersect_ray(q)
+	if res.is_empty():
+		return false
+	if not res.has("normal"):
+		return false
+	var n: Vector3 = res["normal"]
+	return n.dot(Vector3.UP) > WALK_SUPPORT_PROBE_MIN_UP_DOT
+
+
 ## Airborne walk ticks only. Do **not** add gravity just because the nav goal is below the
 ## feet — that stays true for the whole cross of a raised pad (e.g. TerracePlatformA / B)
 ## toward a floor click and poisons horizontal motion / slide resolution.
+## Do apply gravity when [code]is_on_floor()[/code] is still true but there is no walkable surface
+## within [member WALK_SUPPORT_PROBE_DEPTH] under the feet (ledge / void while moving).
 func _apply_walk_air_gravity(delta: float) -> void:
-	if not is_on_floor():
+	var apply_gravity: bool = not is_on_floor()
+	if (
+		not apply_gravity
+		and _has_walk_goal
+		and is_on_floor()
+		and get_floor_normal().dot(Vector3.UP) > WALK_LEDGE_PROBE_MAX_FLOOR_UP_DOT
+		and not _walk_has_close_floor_probe_below()
+	):
+		apply_gravity = true
+	if apply_gravity:
 		velocity += get_gravity() * delta
 
 

docs/plans/NEON-29-implementation-plan.md

@@ -113,6 +113,7 @@ No new automated GDScript tests are added for this story — there is no new GDS
 - **Lip stuck (floor→platform / platform→floor):** QA screenshots for this were on **`TerracePlatformA`** (10 × 10 large SE pad, **0.3 m** single step — not the NW **Terrace B** step/platform pair). Step assist required **`vel_h.dot(want) ≤ 0.52`**, so a **head-on** push into the vertical face (dot ≈ 1) **never** triggered the lift. **Removed** that gate. For **platform→floor**, **`floor_block_on_wall = false`** only when the nav goal is **below** the feet **and** **`is_on_wall()`** or a **wall-ish slide normal** exists, so open deck walking stays stable.
 - **Teal pad still stuck (follow-up):** Step assist used **slide normals only**; Jolt often exposes the lip via **`is_on_wall()`** / **`get_wall_normal()`** instead — re-added a **directional** wall check (`wnh.dot(want) < -0.02`). Descend relax now also triggers on **shallow floor normal** (`get_floor_normal().dot(UP) < 0.992`) and slightly wider vertical-ish slide band. **`TerracePlatformA`** root **Y = 0.012 m** breaks **coplanarity** with the main floor without the larger gap that hurt **TerraceStepB** approach.
 - **Nav waypoint steering dropped (movement):** Following **`get_next_path_position()`** by default caused **near-zero** horizontal progress under **Jolt** + **120 Hz** (waypoint advance / finished edge cases), read as universal **stuck** movement even with the server up. **`player.gd`** now **bee-lines in XZ** toward **`_auth_walk_goal`** and uses path-based steer only when **`needs_vertical_routing`** (Schmitt **`WALK_VERT_ROUTE_LATCH_*`**) **and** **`NAV_COLUMN_STEER_*`** hysteresis. **`_set_horizontal_velocity_from_nav_path_or_goal`** uses **`get_next_path_position()`**; a prior **5 cm** path-point scan caused **180° velocity flips** when Jolt nudged the capsule across the threshold each tick.
+- **Walk ledge / void gravity (resolved):** **`_apply_walk_air_gravity`** only ran when **`not is_on_floor()`**. **`floor_snap_length`** + edge contacts could keep **`is_on_floor()`** true while moving horizontally over a gap to a **lower** floor (purple → gold → gray), so **`velocity.y`** stayed **0** from steering until arrival — capsule **coasted at deck height**. **Fix:** short **physics ray** under the feet (**`WALK_SUPPORT_PROBE_DEPTH`**) with upward-facing normal test; if no close hit while the reported floor is still fairly level, apply gravity anyway during **`_has_walk_goal`** (does **not** reintroduce global “goal below feet” gravity on a whole terrace deck).
 - **Step assist vs `agent_max_climb`:** Nav **`agent_max_climb = 0.35`** only constrained mesh links; **bee-line + chained step assist** could still climb **TerracePlatformB** (~**0.6 m** from floor) in one click. **`_try_walk_step_assist`** now returns false when **`_auth_walk_goal.y > feet + WALK_STEP_ASSIST_MAX_SURFACE_DELTA`** (**0.35**, same as the mesh).
 - **Teal cardinal / tread shake (rollback):** Aggressive tweaks (**0.16** lift, **1**-tick cooldown, **`descending_stall`** toggling **`floor_block_on_wall`**, **seam-based** step-assist clear, **walk-stall nav replan**) caused **oscillation** on the small approach treads. **Reverted** to **`WALK_STEP_ASSIST_DELTA = 0.11`**, **`WALK_STEP_ASSIST_COOLDOWN_TICKS = 8`**, **no** stall replan, **no** `descending_stall` branch, **no** seam-based assist clear — only the original clear (clean floor without wall, or airborne with no slides). **Climb** wallish snap cap applies only when **`goal.y > feet_y + 0.12`** so shallow tread-to-tread motion is not capped to assist snap every frame.
 - **Teal pad — geometry wins:** Script-only mitigations still failed in practice; **`TerracePlatformA_Approach`** adds **twelve** `walkable` **`StaticBody3D`** treads (three per cardinal) with **~0.104 m** rise each, **darker teal** albedo, flush to the platform lip — nav + `CharacterBody3D` use **sloped contact** instead of fighting a **single vertical face**. **Follow-up:** tread **run** was **0.45 m** along the climb axis while the capsule **diameter is 0.8 m** — the body was wider than each tread, causing straddle / stuck motion when **entering** and blocking horizontal progress toward the lip when **exiting**. Treads widened to **1.0 m** run with positions re-centered. **`NavigationAgent3D`** `path_desired_distance` / `target_desired_distance` were briefly lowered to **0.22** but that caused **floor** movement to **stall**; **reverted to 0.35**.