Fixing bugs with pathfinding, bump version

This commit is contained in:
Vladislav Khorev committed 2026-11-15 21:46:30 +06:00
1 parent 8e2b019c92
commit f1cc28ab31
22 files changed
+1119 -759

No files matched your search

+224 -225
View File
@@ -1,296 +1,295 @@
# Pathfinding System
# Pathfinding and Character Avoidance
This document describes the grid-based pathfinding used for the player and all NPCs, including the collision avoidance and movement quality improvements.
This document describes the current authoritative navigation and movement
system. The old grid-based implementation is no longer used. Static routes are
computed on a triangulated navigation mesh, while moving characters avoid each
other with a fixed-point ORCA solver.
---
## 1. Authoritative update flow
## Table of Contents
Navigation belongs to the game state, not the renderer:
1. [Grid Representation](#1-grid-representation)
2. [Building the Walkable Grid](#2-building-the-walkable-grid)
3. [A\* Path Search](#3-a-path-search)
4. [Path Smoothing](#4-path-smoothing)
5. [Approaching Unreachable Destinations](#5-approaching-unreachable-destinations)
6. [Dynamic Obstacles](#6-dynamic-obstacles)
7. [Path Following](#7-path-following)
8. [Character Movement Guard](#8-character-movement-guard)
9. [Dynamic Replanning](#9-dynamic-replanning)
10. [Key Constants Reference](#10-key-constants-reference)
1. A destination command is applied before a fixed 100 ms simulation tick.
2. `CharacterState::setTarget()` asks the active `PathFinder` for a route.
3. `CharacterState::update()` follows the current waypoint and computes
`preferredVelocity`.
4. `LocationGameState::update()` gathers all enabled characters in stable ID
order and runs one ORCA step.
5. ORCA writes the accepted position and velocity back to each
`CharacterState`.
6. Navigation requests produced by NPC logic are applied by
`InternalGameServer` as deterministic simulation consequences.
7. A new immutable snapshot is published for rendering.
---
Rendering interpolates between completed snapshots in `Character.cpp`. That
interpolation uses each client's wall clock and can look slightly different
between clients; it never changes authoritative positions.
## 1. Grid Representation
## 2. Fixed-point math
The world is divided into a uniform 2D grid in the XZ plane (Y is ignored during pathfinding; all characters walk on a flat floor at `floorY`).
Gameplay navigation uses:
Each cell is either **walkable** (`1`) or **blocked** (`0`). The grid is stored as a flat `std::vector<unsigned char>` indexed by `z * gridWidth + x`.
**Parameters** (all configurable in the JSON config file):
| Parameter | Default | Description |
|---|---|---|
| `cellSize` | 0.4 m | Width and depth of one cell |
| `agentRadius` | 0.45 m | Half-width of a character — used to erode free space |
| `objectPadding` | 0.25 m | Extra clearance added around obstacle polygons |
| `boundaryPadding` | 0.0 m | Inward erosion from the edges of navigation areas |
| `floorY` | 0.0 | Y coordinate placed on every path waypoint |
**Grid bounds** are computed from the union of all navigation area polygons plus a padding margin of `cellSize * 2 + agentRadius + objectPadding` on every side.
**Cell coordinate conversion:**
```
cell.x = floor((worldX - minX) / cellSize)
cell.z = floor((worldZ - minZ) / cellSize)
cellCenter.x = minX + (cell.x + 0.5) * cellSize
cellCenter.z = minZ + (cell.z + 0.5) * cellSize
```cpp
using fp = fpm::fixed<std::int32_t, std::int64_t, 12>;
```
---
`Vec2fp` is used for XZ navigation and velocity. `Vec3fp` is used for world
positions and waypoints. With 12 fractional bits, one raw unit is 1/4096.
## 2. Building the Walkable Grid
Path following, waypoint tests, ORCA constraints, collision correction,
movement displacement, and facing calculations use fixed-point operations.
Floating-point conversions remain at content and presentation boundaries.
The grid can be loaded in two ways.
The navigation-mesh build is not fully fixed-point:
### 2a. Pre-computed grid (`.txt` file)
- Input JSON numbers are converted to fixed point.
- Polygon clipping uses scaled `int64_t` coordinates.
- CDT triangulation temporarily uses `double`.
- Triangle vertices and centers are converted back to fixed point before path
queries.
A plain-text file with a small header followed by rows of `1`/`0` characters:
Multiplayer therefore requires matching executable and content builds.
```
cellSize 0.4
agentRadius 0.45
floorY 0.0
...
minX -5.0
minZ -5.0
gridWidth 50
gridDepth 50
11111111...
10000001...
```
## 3. Navigation configuration
This format is generated by `PathFinder::saveGrid()` after building from polygons and can be loaded much faster than recomputing from geometry.
### 2b. Polygon-based config (`.json` file)
The JSON file lists **navigation areas** (convex or concave walkable regions) and **obstacle polygons** (impassable zones within those regions):
Each navigation JSON contains:
```json
{
"cellSize": 0.4,
"areas": [
{ "name": "main_room", "available": true, "polygon": [[x,z], ...] }
{
"name": "main",
"available": true,
"polygon": [[-10, -10], [10, -10], [10, 10], [-10, 10]]
}
],
"obstacles": [
{ "name": "table", "polygon": [[x,z], ...] }
]
{
"name": "wall",
"polygon": [[1, 1], [2, 1], [2, 4], [1, 4]]
}
],
"floorY": 0
}
```
**Build steps:**
Only the first navigation area is currently loaded. A location may list
multiple navigation JSON files; `LocationNetworkState::activeNavigationIndex`
selects the active map.
1. **Mark available areas walkable** — every cell whose center lies inside any `available` navigation area polygon gets `walkable = 1`. If `boundaryPadding > 0`, cells too close to the outer edge of the area are left blocked.
2. **Mark obstacle polygons blocked** — cells whose center lies inside an obstacle polygon, or within `agentRadius + objectPadding` of its edges, are set to `0`.
The shared character radius is:
Navigation areas can be toggled at runtime via `PathFinder::setAreaAvailable()`, which rebuilds the entire grid. This is used to open or close doors, gated areas, etc.
---
## 3. A\* Path Search
`PathFinder::findPath(start, end)` runs a standard A\* on the walkable grid.
**Neighbor connectivity:** 8-directional (cardinal + diagonal). Diagonal moves are blocked if either of the two adjacent cardinal cells is unwalkable (no corner-cutting).
**Step costs:** integer `10` for cardinal and `14` for diagonal.
**Heuristic:** octile distance using the same `10`/`14` scale. Queue entries
compare priority, accumulated cost, then linear cell index; stale entries are
rejected. This avoids floating-point route-order differences.
**Start/end snapping:** If the exact cell for `start` or `end` is not walkable, `findNearestWalkableCell` expands a square ring outward (up to radius 8 m) to find the nearest walkable cell. This makes clicking slightly outside the nav mesh still produce a valid path.
**Path reconstruction:** After A\* completes, the cell chain is walked via `cameFrom[]` from `end` back to `start`, reversed, then smoothed (see §4).
**First-waypoint trimming:** If the first waypoint is within `cellSize × 0.75` of `start`, it is dropped (the character is already close enough).
**Last-waypoint precision:** If the requested `end` maps to the same cell as the snapped end cell, the last waypoint is replaced with the exact `end` world position rather than the cell centre.
---
## 4. Path Smoothing
Raw A\* paths follow the grid diagonals and produce staircase-shaped routes. A **string-pulling** (line-of-sight) pass compresses them:
```
anchor = path[0]
result = [anchor]
while anchor is not the last cell:
find the furthest cell 'next' from anchor with unobstructed line of sight
result.append(next)
anchor = next
```cpp
kCharacterAgentRadius = 0.42f
```
Line-of-sight uses deterministic integer grid traversal and applies the same
no-corner-cutting rule as A*. The result is a minimal set of waypoints connected
by straight, obstacle-free segments.
## 4. Building the navigation mesh
---
`PathFinder::generateNavMesh()` performs these steps:
## 5. Approaching Unreachable Destinations
1. Convert area and obstacle vertices to Clipper2 `int64_t` coordinates using
`CLIPPER_SCALE = 10000`.
2. Subtract obstacle polygons from the outer walkable polygon.
3. Erode the result inward by `kCharacterAgentRadius`.
4. Rebuild polygon and hole hierarchy with `PolyTree64`.
5. Run constrained Delaunay triangulation with CDT.
6. Convert generated triangles to fixed-point `NavTriangle` records.
7. Store edge neighbors and mark connected components with deterministic BFS.
When a player clicks on a point in a disconnected region (e.g., across a thin wall), the original `findPath` returns an empty path and the character does not move. This is surprising — a click on a solid wall sensibly moves the character to the nearest reachable point, but a click into an inaccessible room does nothing.
Each triangle contains three vertices, a fixed-point center, three neighbor
indices, and a connected-component ID.
**`findPathToNearest`** runs one A\* search against the requested static and
dynamic occupancy. If the destination is unreachable, the same search returns
the reachable cell geometrically closest to it. It never retries without
dynamic obstacles.
## 5. Route queries
- While processing cells, it tracks `bestIndex` — the visited cell with the
smallest squared grid distance to the end cell. Equal distances use the
lower linear cell index.
- If A\* exhausts all reachable space without finding `end`, it reconstructs and returns a path to `bestIndex`.
- If `bestIndex` is still the start cell (character is completely isolated), an empty path is returned and the character stays put.
`PathFinder::findPathToNearest(start, end)`:
The net effect: clicking anywhere in the world always moves the character as close as possible to the target, matching the behaviour of clicking on a solid wall.
1. Finds the triangle containing the start.
2. If necessary, clamps the start to the closest navigation-mesh boundary.
3. Finds the destination triangle.
4. If the destination is outside the mesh or on another connected component,
clamps it to the closest boundary of the start component.
5. Runs A* through adjacent triangles.
6. Applies the funnel algorithm to the triangle corridor.
7. Returns fixed-point 3D waypoints at `floorY`.
`LocationGameState` applies this behavior to players and NPCs.
If start and destination are in the same triangle, the route is a direct
segment. If no valid start or corridor exists, the result keeps the character
at its current position.
---
### A* ordering
## 6. Dynamic Obstacles
A* uses fixed-point distances between triangle centers. Queue records compare:
When a path is planned, other characters can temporarily mark cells as blocked to make the character walk around them rather than through them.
1. total estimated cost (`fScore`);
2. triangle ID.
**How it works:**
Neighbor edges are visited in stored edge order. The explicit triangle-ID tie
break prevents priority-queue ordering from depending on allocation addresses.
`LocationGameState::collectPathObstacles` creates a stable-ID-sorted snapshot
from authoritative players and NPCs. `PathFinder` stamps circles into a
generation-tagged overlay and reuses A\* buffers; it does not copy or mutate the
static walkability grid per query.
### Funnel smoothing
**Which characters become obstacles:**
The corridor's shared edges become left/right portals. The Simple Stupid
Funnel Algorithm emits only the corners needed to stay inside the corridor,
plus the exact clamped destination.
A character is added as a dynamic obstacle only when **all** of these are true:
## 6. Path following
- It is not the character currently planning the path (`self`).
- It is alive and enabled.
- It did not physically move during the previous simulation tick, unless it
just blocked this requester and is promoted for a forced replan. An active
path alone does not make a stalled character transparent.
`CharacterState` stores:
**Obstacle radius:** the character's full `collisionRadius`, inflated by the
navigation map's `agentRadius` and one cell half-diagonal for conservative
rasterization. There is no obstacle-dropping fallback; an occupied destination
resolves to a nearby reachable cell.
- `requestedWalkTarget`: the original destination intent;
- `walkTarget`: the reachable route endpoint;
- `pathWaypoints`: the current smoothed route;
- `currentWaypointIndex`: the active waypoint;
- `velocity`: the previous accepted ORCA velocity;
- `preferredVelocity`: the velocity requested for the current tick.
---
`CharacterState::update()` advances waypoints within
`kWalkThreshold = 0.05 m`. The desired speed is the smaller of `walkSpeed` and
the speed needed to reach the waypoint in the current tick. Reaching the final
waypoint clears the path and produces the optional arrival event.
## 7. Path Following
Destination requests within 0.25 m of the existing request are deduplicated.
NPC navigation retries use a stable-ID-shuffled sequence of cooldown ticks.
`CharacterState::setTarget(destination, onArrived)` sets a new walk target. It
calls the centralized location planner to generate a waypoint list. The result
is stored in `pathWaypoints`; the reachable endpoint is stored in `walkTarget`
and the original command destination in `requestedWalkTarget`.
`stopInPlace()` clears the route and callback, targets the current position,
resets blockage and retry state, and clears both movement velocities.
Each fixed simulation tick in `CharacterState::update`:
## 7. Character avoidance with ORCA
1. **Active target** — if `pathWaypoints` is non-empty, the character moves toward `pathWaypoints[currentWaypointIndex]`; otherwise it moves toward `walkTarget`.
2. **Movement** — the character advances along the XZ direction at `walkSpeed` m/s and rotates smoothly toward the movement direction at `rotationSpeed` rad/s.
3. **Waypoint advance** — when the character is within `WALK_THRESHOLD = 0.05 m` of the current waypoint, it advances to the next one. When the last waypoint is reached, `pathWaypoints` is cleared and the optional `onArrived` callback is fired.
4. **State machine** — the animation state switches between `STAND` and `WALK` based on whether the character is moving.
Static routing does not insert moving characters into the navigation mesh.
Instead, `LocationGameState` creates one `OrcaAgent` per enabled, living
character after every character has computed its preferred velocity.
`CharacterState::isMoving()` reports whether navigation remains active.
`movedLastTick` separately records actual displacement and controls dynamic
obstacle filtering.
Agents are sorted by stable character ID before solving. Each agent stores:
**Stopping in place:** `CharacterState::stopInPlace()` sets `walkTarget` and
`requestedWalkTarget` to the current position, clears the path and callback, and
resets blockage state. It is used to cancel player/bot movement after a
persistent contact and by other explicit stop actions.
- current XZ position;
- previous accepted velocity;
- preferred velocity;
- collision radius and maximum speed;
- stationary/combat state;
- player/hostile avoidance policy.
---
Current ORCA constants:
## 8. Character Movement Guard
| Setting | Value |
|---|---:|
| Simulation step | 0.1 s |
| Time horizon | 0.6 s |
| Neighbor distance | 4.0 m |
| Avoidance radius factor | 0.85 |
| Parallel-line tolerance | 0.001 |
| Constant-speed validity tolerance | 0.1 m/s |
Pathfinding steers around stationary characters. A second authoritative guard
checks each proposed movement segment against stable-ID-ordered reservations
initialized from tick-start circles. An accepted step updates that character's
reservation before later characters advance. A step that approaches or sweeps
through another circle is rejected rather than pushing either character.
For each nearby character, ORCA constructs a permitted velocity half-plane.
Constraints are solved with the standard three-stage linear program. Exact
overlap uses the agents' stable sorted indices to choose a fallback direction.
Characters that moved during the previous tick are transparent during planning
but remain solid to the movement guard. Planning uses the full
`collisionRadius` (default 0.45 m); contact checks use the smaller
`movementContactRadius` (default 0.32 m). NPC JSON can override these as
`navigationAvoidanceRadius` and `movementContactRadius`. This tolerance avoids
false bumps from grid discretization while still preventing stacking.
### Character policies
When moving characters remain blocked head-on or while crossing for three
ticks, both stop. Player and bot destinations are cancelled; the user or bot
may issue another command. NPCs retain `requestedWalkTarget` and retry later.
Characters following in the same direction simply wait for spacing and do not
accumulate stuck ticks. A rejected movement step uses the standing animation.
- Hostile attacking NPCs are treated as ghosts for avoidance policy.
- Non-ghost characters do not add braking constraints for ghosts.
- Ghosts take 95% of avoidance responsibility around non-ghost characters.
- A moving character takes full responsibility around a stationary character.
- Non-ghost characters try deterministic candidate angles from 0 through
±90 degrees while preserving preferred speed; if none is valid, they stop.
---
### Hard-overlap correction
## 9. Dynamic Replanning
After applying velocities, `resolveHardCollisions()` runs two stable pairwise
passes. Overlapping characters are separated along their fixed-point normal.
Non-ghost characters push ghosts completely; other pairs split correction
according to stationary weights.
Rejected non-following movement increments serialized `movementBlockedTicks`.
After three blocked ticks an NPC stops and schedules a retry. When its cooldown
expires, `InternalGameServer` promotes the blocker to a hard obstacle and
replans to `requestedWalkTarget`.
Finally, any character outside the active navigation mesh is clamped back to
its closest boundary.
Each NPC has `navigationRetryCooldownTicks`, normally ten distinct values.
`LocationDefinition` deterministically shuffles the sequence from the stable NPC
ID, and every retry consumes the next value. The sequence and cursor are
serialized, preventing synchronized retry loops while preserving lockstep.
NPC JSON can override it with `navigationRetryCooldownTicks` or
`navigationRetryCooldownMs`.
## 8. Movement and animation state
Example NPC tuning:
After ORCA:
```json
{
"navigationAvoidanceRadius": 0.45,
"movementContactRadius": 0.32,
"navigationRetryCooldownMs": [
200, 300, 400, 500, 600, 700, 800, 900, 1000, 1100
]
}
- accepted position and `newVel` become authoritative state;
- `movedLastTick` is set from actual displacement;
- `movementBlockedTicks` is reset after movement or incremented when a desired
move produced no displacement;
- walking/standing animation state follows actual movement;
- facing follows the accepted ORCA velocity.
`facingAngle` and `targetFacingAngle` are explicitly initialized. This is
important because the underlying fixed-point library's default constructor does
not initialize its raw integer.
## 9. Deterministic lockstep requirements
All clients must begin a tick with identical state. The following movement
history is serialized in schema version 6:
- exact raw fixed-point `velocity` components;
- path targets, waypoints, and waypoint index;
- `movedLastTick` and blocked/retry counters;
- deterministic retry sequence and cursor;
- animation frame, state, `resetAnim`, and attack phase;
- facing and target-facing angles.
Velocity is stored as raw fixed-point integers rather than decimal floats. It
must be present in late-join and reconnect snapshots because the next ORCA step
uses previous velocity directly. `resetAnim` and `attack` are also persisted
because they affect the next animation/combat update after a snapshot.
Character and interactive-object maps may use `unordered_map`, but simulation
collects and sorts stable IDs before order-sensitive updates. ORCA sorts agents
again defensively.
## 10. Compatibility and divergence diagnostics
The manual campaign compatibility label is combined with:
- deterministic simulation version;
- campaign and multiplayer slot metadata;
- ordered location/navigation configuration;
- authoritative configuration and start-state bytes;
- referenced animation bytes.
The resulting fingerprint is logged by server and client. Connections are
rejected when fingerprints differ, preventing two Release directories with
different navigation resources from entering lockstep.
After every server tick, the server sends a canonical authoritative-state hash.
Each client computes the same hash after applying that tick and logs:
```text
[network] Lockstep divergence at tick N: server=..., client=...
```
The configured values are clamped to positive tick counts and shuffled
deterministically per NPC ID. Supplying different ten-value sets gives explicit
control for unusually dense locations.
The hash excludes the persistence timestamp but includes serialized movement
history. Compare authoritative raw positions at the same completed tick ID;
do not compare interpolated render-frame positions.
Navigation map switches, area availability changes, and added static obstacle
polygons also force centralized replanning.
## 11. Known constraints
Opposing traffic in a one-character-wide corridor can wait until one route or
blocker changes; this policy intentionally does not implement space-time
cooperative reservations.
- Navigation-mesh generation still depends on Clipper2/CDT and temporary
`double` values, so cross-toolchain identity is not guaranteed.
- Triangle IDs are taken from CDT output and are used as A* tie breakers.
- Only one navigation area from each JSON file is currently loaded.
- ORCA is local collision avoidance, not cooperative space-time planning.
Dense opposing traffic can still stop temporarily.
- Runtime area and obstacle changes rebuild or mutate local navigation state
and must be applied identically on every lockstep replica.
---
## 12. Main files and tests
## 10. Key Constants Reference
- `src/navigation/PathFinder.h/.cpp`: navmesh generation, A*, clamping, funnel.
- `src/navigation/fpmutils.h/.cpp`: fixed-point vectors and conversions.
- `src/CharacterState.h/.cpp`: path state, waypoint following, serialization.
- `src/OrcaSolver.h`: deterministic local avoidance and overlap correction.
- `src/LocationGameState.h/.cpp`: stable character collection and ORCA update.
- `src/game_server/InternalGameServer.cpp`: authoritative tick consequences.
- `src/game_server/NetworkProtocol.cpp`: tick messages and canonical hashes.
- `src/game_server/WebsocketGameClient.cpp`: replica advancement and hash check.
| Constant | Location | Value | Description |
|---|---|---|---|
| `cellSize` | `PathFinder` config | 0.4 m | Grid cell size |
| `agentRadius` | `PathFinder` config | 0.45 m | Character half-width for grid erosion |
| `objectPadding` | `PathFinder` config | 0.25 m | Extra clearance around obstacles |
| `movementContactRadius` | `CharacterState` / NPC config | 0.32 m | Smaller movement-guard radius |
| `kWalkThreshold` | `CharacterState.h` | 0.05 m | Distance below which a waypoint is considered reached |
| `TARGET_REPLAN_THRESHOLD` | `CharacterState.cpp` | 0.25 m | Deduplication threshold in `setTarget` |
| `BLOCKED_REPLAN_TICKS` | `CharacterState.cpp` | 3 ticks | Blocked steps before stopping |
| default retry sequence | `CharacterState.cpp` | 2–11 ticks | Ten ID-shuffled NPC retry cooldowns |
| `NPC_TALK_DISTANCE` | `Location.cpp` | 1.35 m | Distance at which walking-to-NPC interaction fires |
Release regression coverage includes:
### Reference benchmark
`GameServerPathFinderTests --benchmark` is non-gating. On the development
Windows Release build with an 80×80 grid, the current implementation completed
100 obstacle-aware queries in 15 ms and 1000 queries in 176 ms. Treat these as
comparative measurements rather than cross-machine budgets.
- fixed-point velocity round-trip;
- compatibility fingerprint sensitivity to navigation-map order;
- two-client late join after ORCA movement has already started;
- exact raw position and velocity equality across server and both replicas;
- pathfinder, state, protocol, lockstep, and server smoke tests.