Skip to content

Parallel Luau Evaluation (Client NPV AI + NodegraphPathfinder)

Scope

  • Client pursuit vehicle AI in src/client/controllers/AI/ (PoliceCarController, NPVCore, and states).
  • Shared nodegraph pathing in src/shared/modules/NodegraphPathfinder.lua.

External Research Summary

  • Parallel Luau is most useful when work is isolated in Actors and communicated via messages.
  • task.desynchronize()/task.synchronize() require strict thread-safety boundaries.
  • DataModel writes and many API members remain unsafe in parallel contexts.

System Evaluation

1) Client NPV AI

Current NPV tick work mixes: - Frequent DataModel reads (PrimaryPart, attributes, physics velocity, workspace queries). - DataModel writes (collision groups, body movers, attributes/sounds in states/setters). - Tight per-entity state machine transitions and mutable entity state.

Parallelizing this path today would require splitting pure compute from world interaction and moving compute into Actor workers with message passing. That is a large architectural change for a tick loop that currently depends on immediate synchronous state transitions.

2) NodegraphPathfinder

NodegraphPathfinder currently mutates shared node state (F, G, H, Parent, ParentEdge) during FindPath, then resets it. This design is not safe for concurrent path solves over the same graph object.

Making it parallel-safe would require a rework to per-search local state (no shared node mutation), then async integration at call sites. Several call sites currently expect immediate results.

Decision

No Parallel Luau implementation is applied in this PR.

Reason: - No low-risk, minimal-change path showed clear noticeable gains without high desync/thread-safety risk. - Introducing Actors and async messaging across these systems would significantly increase complexity and maintenance cost. - Current architecture is optimized around synchronous path/state decisions per tick.

  1. Add profiling traces around DrivePath.CalculatePath and NodegraphPathfinder:FindPath in live scenarios.
  2. Refactor NodegraphPathfinder to be re-entrant (local per-search A* state only).
  3. Isolate a pure path solve worker behind an async API.
  4. Move only pure math/path solve into Actor workers; keep all DataModel writes synchronized on the main thread.
  5. A/B test frame time and chase quality before rollout.