# NEON-2 — Implementation plan

## Story reference

| Field | Value |
|--------|--------|
| **Key** | NEON-2 |
| **Title** | E1.M1: Click-to-move prototype (client-only) |
| **Jira** | [NEON-2](https://neon-sprawl.atlassian.net/browse/NEON-2) |
| **Parent context** | [NEON-9 — E1.M1 InputAndMovementRuntime](https://neon-sprawl.atlassian.net/browse/NEON-9) |

## Goal, scope, and out-of-scope

**Goal:** On the Godot client only, prove click-to-move locomotion and the input → world-target path before any networking or server authority.

**In scope**

- Placeholder avatar in the prototype scene (`main.tscn` or a dedicated movement test scene; default choice: extend `main.tscn` so F5 still runs the prototype).
- Ground pick via camera raycast; on valid hit, command movement to that point.
- Flat prototype terrain and simple obstacles sufficient to validate stopping behavior.
- Brief note in README and/or scene that this is **temporary** until authoritative movement sync exists.

**Out of scope (per Jira)**

- Game server, persistence, `MoveCommand` / wire protocol, Protobuf contracts.

## Acceptance criteria checklist

- [ ] Clicking walkable ground moves the avatar to the destination without requiring WASD (mouse-only locomotion for this prototype).
- [ ] Movement stops at obstacles when using navigation; **or** if using a direct move-to approach instead, the limitation is documented (README and/or plan).
- [ ] README or an in-editor scene note states this behavior is provisional until authoritative sync lands.

## Technical approach

1. **Scene setup (`main.tscn`)**  
   - Add a **Camera3D** suitable for ground picking (angled downward at a `StaticBody3D` floor with collision).  
   - Add a **CharacterBody3D** placeholder (e.g. `CapsuleMesh` + `CollisionShape3D`) as the avatar.  
   - Add at least one **obstacle** (`StaticBody3D`) so “stop at obstacles” is observable.  
   - Add a **NavigationRegion3D** covering the walkable floor; bake a navigation mesh from the floor (and subtract or exclude obstacles per Godot 4 workflow).

2. **Movement model**  
   - Prefer **NavigationAgent3D** on the avatar: set `target_position` from the raycast hit on the ground; each frame move the body toward the agent’s next path position (e.g. `velocity` + `move_and_slide`, or equivalent Godot 4 pattern). This satisfies the AC path that expects stopping at obstacles via navigation.  
   - Fallback only if navigation proves unnecessarily heavy for the first slice: direct `move_toward` / velocity toward the click point with `move_and_slide` and document that there is no pathfinding.

3. **Input**  
   - `_unhandled_input` or `_input`: on left mouse button, raycast from camera through cursor into the physics world; if the collider is the ground (or a dedicated “walkable” layer/mask), set the navigation target.

4. **Documentation**  
   - Update `client/README.md` with a short “Movement prototype (NEON-2)” subsection: mouse click-to-move, navigation-based obstacle avoidance, **not** server-authoritative.  
   - Optional: `Editable Children` note on root node in scene or a comment in `main.gd` pointing to NEON-2 / temporariness.

## Files to add

| Path | Purpose |
|------|--------|
| None required initially | If `main.gd` grows unwieldy, optionally extract `scripts/player_navigation.gd` (or similar) attached to the avatar—only if it keeps the scene readable. |

*(Default: implement in existing `scripts/main.gd` + scene edits unless script size forces a split.)*

## Files to modify

| Path | Rationale |
|------|-----------|
| `client/scenes/main.tscn` | Add camera, terrain, obstacles, navigation region, avatar, and wire scripts. |
| `client/scripts/main.gd` | Raycast-on-click, navigation target updates, and any per-frame movement driver if kept on root. |
| `client/README.md` | Document prototype movement, temporary nature, and manual verification steps. |
| `client/project.godot` | Only if needed (e.g. input map, layer names, or feature flags)—prefer minimal diffs. |

## Tests

- **Automated:** None for this story; the repo has no Godot test harness yet ([testing expectations](../../.cursor/rules/testing-expectations.md)).
- **Manual verification:**  
  1. Open `client/` in Godot 4.2+, run main scene.  
  2. Click on the floor: avatar moves to the point without using WASD.  
  3. Click a destination behind an obstacle: avatar path avoids or stops appropriately per navigation behavior.  
  4. Confirm README/scene note mentions provisional client-only movement.

## Open questions / risks

- **Navigation baking:** First-time contributors need to bake the navigation mesh in the editor after pulling scene changes; document that in README if it is not obvious.  
- **Isometric later:** Camera rig may be replaced for isometric; keep movement logic independent of camera style where possible (raycast from current camera).  
- **Performance:** Single-agent prototype is sufficient; no need to optimize for crowds in NEON-2.