Prototype local world-worker obstacle avoidance

[SimGamerJen]

Summary

Builds directly on the validated obstacle-awareness checkpoint (PR #25) and adds the first automatic local avoidance behaviour for FOLLOW.

Behaviour

• adds HP_WorldLocalAvoidance.lua
• waits ~450 ms after a direct walking corridor remains blocked before planning
• samples short candidate corridors at ±45°, ±70°, and ±95° around the direct player heading
• uses the same full walking-speed obstacle corridor as the validated awareness stack
• prefers a candidate whose endpoint also exposes a clear next leg toward the player
• otherwise favours stronger lateral progress and preserves the chosen side across chained bypass steps to reduce zig-zagging
• creates a short ~1.65 m temporary waypoint, inside the validated walking look-ahead
• keeps that waypoint fixed while moving so normal FOLLOW retargeting cannot overwrite it
• after reaching the waypoint, immediately reacquires the live player target
• if the bypass segment itself becomes blocked, the existing obstacle detector stops safely and the avoidance layer replans
• after ~2 s of uninterrupted normal direct following, the local avoidance chain/side preference resets
• maximum 10 chained local bypass segments before falling back to the existing blocked/hold behaviour

Architecture

The existing locomotion, obstacle awareness, turn-in-place escape, and FOLLOW state machines remain authoritative. This layer only chooses temporary local waypoints; it does not introduce another movement/animation controller.

Scope

This is deliberately local avoidance, not global pathfinding. There is no navmesh, obstacle geometry reconstruction, route graph, doorway search, or guarantee of escaping a large/concave enclosure.

Initial test focus

1. Confirm [WorldAvoidance] Loaded 2.2.0.0-alpha4-local-avoidance-1 ... appears without Lua errors.
2. Reuse the validated cultivator test: place the implement directly between A and the player and run hpWorld follow A.
3. Expect the normal OBSTACLE STOP/blocked state, followed after a short delay by one AVOID PROBE and AVOID START.
4. Rhys should turn/walk toward the chosen short side waypoint rather than simply waiting for the player to clear the direct line.
5. Expect AVOID WAYPOINT REACHED ...; reacquiring player, followed either by direct FOLLOW or another local bypass segment if the implement still blocks the route.
6. Verify the existing obstacle detector can still stop an unsafe bypass segment.
7. Verify hpWorld unfollow A still cancels cleanly during avoidance.
8. If the cultivator works, repeat with a parked tractor/vehicle and a building corner or fence end.

[SimGamerJen]

Live test — mechanical PASS (visual verdict pending)

Tested hpWorld follow A with the John Deere 980 cultivator directly between Rhys and the player.

Observed behaviour:

• local avoidance module loaded successfully (2.2.0.0-alpha4-local-avoidance-1)
• Rhys detected cultivator980_main_component1 and stopped safely
• after the planning delay, candidate probes were evaluated and a RIGHT-side bypass chain was selected
• segment 1: RIGHT 95°, waypoint reached successfully; direct reacquire then encountered cultivator980_back_component4
• segment 2: RIGHT 70°, waypoint reached successfully; direct reacquire still intersected cultivator980_main_component1
• segment 3: RIGHT 45°, waypoint reached successfully; direct route then remained clear
• Rhys reacquired the live player and completed FOLLOW to the normal 1.80 m stand-off
• existing obstacle turn-in-place and walking-corridor safety checks remained active throughout
• no HelperProfiles Lua error observed during the avoidance sequence

This is a mechanical PASS for chained local obstacle avoidance around the cultivator. Visual/naturalness verdict remains to be confirmed separately.

[SimGamerJen]

Visual validation follow-up: mechanical local avoidance succeeded around the cultivator, but the on-screen execution did not yet look natural. User observed slight stuttering during direction changes and wants a more deliberate stop -> adjust -> move -> adjust -> move cadence.

Refinement added on the same draft PR:

• new HP_WorldAvoidancePhases.lua
• every local bypass waypoint now forces stationary yaw alignment through the already validated obstacle turn-escape path before forward motion is allowed
• clean waypoint completion now holds an idle settle for ~220 ms before FOLLOW reacquires/replans
• planner/candidate selection is unchanged
• safety obstacle stops remain authoritative

Expected visual sequence: blocked/hold -> AVOID TURN -> AVOID MOVE -> smooth waypoint stop -> AVOID SETTLE -> reassess/next turn. Treat the earlier mechanical result as planner PASS but visual FAIL; this refinement needs a fresh visual check.

[SimGamerJen]

Visual refinement: anticipatory continuous steering

The first local-avoidance implementation passed mechanically but failed the visual-naturalness test: chained stop/turn/waypoint phases looked robotic and introduced visible turn stutter.

New approach added on the same experimental branch:

• HP_WorldAnticipatorySteering.lua
• ~3.8 m read-only anticipatory sensing corridor
• far sensor bends the live FOLLOW target before the short-range safety detector fires
• samples ±30°, ±45°, ±60°, ±72° candidate headings
• prefers the smallest clear correction and preserves side preference to reduce oscillation
• steering offset ramps in gradually (~0.72 rad/s) and recovers gradually (~0.52 rad/s)
• worker remains in one continuous locomotion/animation session; no normal-case waypoint stop is required
• direct FOLLOW target is restored smoothly once the route remains clear
• validated short-range obstacle stop/hold, turn-escape, and waypoint planner remain unchanged as safety fallback if no anticipatory corridor is available

Visual acceptance target: Rhys should begin arcing around the cultivator before reaching the emergency stop distance, remain walking through the manoeuvre, and blend back toward the player without discrete stop-turn-move transitions.

[SimGamerJen]

Live test after anticipatory-steering-1 exposed a controller-arbitration loop in a tight obstacle pocket (cultivator + MT655). The smooth steering layer would fall back to the local planner, then immediately re-enter after each short bypass waypoint, causing repeated AVOID -> STEER -> STOP hand-offs and revisiting the same small area until the 10-segment guard exhausted.

Patch e5ffb7e changes anticipatory steering to sticky fallback ownership:

• once STEER FALLBACK / emergency obstacle blocking occurs, anticipatory steering is suppressed for the full local-escape episode;
• the local obstacle/waypoint planner gets exclusive navigation ownership while escaping;
• anticipation is restored only after the local chain has cleared/reset and a 3.8 m direct corridor has remained clear for a sustained interval;
• hard-stop safety remains unchanged.

Expected log markers for retest:
STEER SUPPRESS A ...
(no repeated STEER START between local bypass segments)
then, once truly clear,
STEER RESTORE A ...

This is intended to remove the controller hand-off loop without weakening collision safety or the smooth anticipatory path in normal open-space avoidance.

[SimGamerJen]

Parking this PR as experimental research rather than a release candidate. Live testing proved local obstacle avoidance can mechanically route around machinery, but the current controller arbitration/fallback path sacrifices the smooth, human-looking motion that made straight/curved/follow locomotion successful. Preserve this branch intact for future navigation work; do not merge into the active development line. Continue new world-worker development from the validated obstacle-awareness checkpoint (PR #25) unless/until we deliberately resume navigation research.