From 1f4e3c49f640a6692d2cd2567806c5c422838758 Mon Sep 17 00:00:00 2001 From: VinPropane Date: Sun, 5 Apr 2026 00:14:37 -0400 Subject: [PATCH] NS-23: Resolve agent tuning and nav sync risks in implementation plan --- docs/plans/NS-23-implementation-plan.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/plans/NS-23-implementation-plan.md b/docs/plans/NS-23-implementation-plan.md index ce159be..447141b 100644 --- a/docs/plans/NS-23-implementation-plan.md +++ b/docs/plans/NS-23-implementation-plan.md @@ -63,6 +63,27 @@ - **`client/README.md`:** Update movement section: navmesh path-follow + server authority one-liner. - **`server/README.md`:** One short subsection or bullet: server validates **end target** and **step**; **client** nav is **presentational** for obstacle following in this slice. +## Resolved — agent shape vs capsule (was risk) + +Prototype player collider in [`main.tscn`](../../client/scenes/main.tscn): **`CapsuleShape3D_player`** — **`radius = 0.4`**, **`height = 1.0`**. + +| Setting | Locked choice | +|--------|----------------| +| **`NavigationAgent3D.radius` / `height`** | Match the **physics** capsule (**0.4** / **1.0**) so nav clearance matches what `move_and_slide` actually sweeps. | +| **Navmesh bake agent** | In **`NavigationRegion3D`** bake settings, use the **same** radius/height (or Godot’s equivalent **agent** parameters) so baked polygons match runtime pathfinding. | +| **Corner clipping vs “stuck”** | If the mesh clips into box corners, **increase** agent radius slightly and **rebake** (wider corridor on the mesh) before shrinking physics. Do not silently shrink the capsule without an explicit design change. | +| **Vertical alignment** | Keep **`path_height_offset`** (or equivalent) at **0** unless the capsule foot position and floor snap misalign; the pick already supplies floor **`Y`**. | +| **Arrival** | Align **`target_desired_distance`** (and related agent tolerances) with existing player **`ARRIVE_EPS`** (~**0.35** m) so stop distance matches prior steering feel unless QA says otherwise. | + +## Resolved — navigation sync / frame order (was risk) + +| Topic | Locked choice | +|--------|----------------| +| **Where motion runs** | Path queries (`get_next_path_position`, velocity toward next point) and **`move_and_slide`** run only in **`Player._physics_process`**, not in `_process` or UI thread. | +| **When `target_position` is set** | `main.gd` (or signal handler) may set the agent target in response to **`target_chosen`** / authority callbacks; the **first** consumable segment appears after the navigation map updates. | +| **First frame after new target** | If **`NavigationAgent3D.is_navigation_finished()`** or a zero-length first step appears on the **same** frame as `target_position` assignment, **defer** one tick: `await get_tree().physics_frame` **once** after setting target **or** simply rely on **next** `_physics_process` (preferred — avoid await in hot path). **Do not** poll path from `_input` without deferral. | +| **Map readiness** | After adding **`NavigationRegion3D`**, ensure the region is **baked** and enabled before F5; startup **`sync_from_server`** snap does not need a path. | + ## Files to add (expected) | Path | Purpose | @@ -90,8 +111,7 @@ ## Open questions / risks -- **Agent radius / height** vs capsule: mis-tuning causes clipping or “stuck”; match **`CollisionShape3D`** to agent parameters. -- **Frame ordering:** `NavigationServer` sync — follow Godot docs (`await get_tree().physics_frame` if required before first path query). +None — agent/bake alignment and physics-frame path consumption are locked in **Resolved — agent shape vs capsule** and **Resolved — navigation sync / frame order** above. Reopen only if the scene scale or avatar collider changes materially. ## PR / review