2077-gps-mod/docs/gps-routing-research.md

GPS Routing Research Notes

Current date: 2026-06-27.

This note summarizes the research pass prompted by the realization that "prefer highways" is a proxy, not the goal. The actual player-facing goal is a route that feels fast and drivable in Cyberpunk 2077, especially when the player is driving aggressively and ignoring normal traffic rules.

The conclusion is that the next patch should not be another broad highway multiplier. Production route engines and routing papers treat route quality as multi-criteria: edge traversal cost, transition/turn cost, road hierarchy, intersection delay, and user preferences are separate signals. For manual Cyberpunk driving, the best analogue is a momentum/corridor model: prefer routes that preserve speed and minimize decision points, sharp turns, short-segment churn, and awkward ramp transitions.

Sources Reviewed

• Bast et al., "Route Planning in Transportation Networks": https://arxiv.org/abs/1504.05140
• Jiang and Liu, "Computing the Fewest-turn Map Directions based on the Connectivity of Natural Roads": https://arxiv.org/abs/1003.3536
• Sacharidis and Bouros, "Routing Directions: Keeping it Fast and Simple": https://arxiv.org/abs/1309.4396
• Hlineny and Moris, "Generalized Maneuvers in Route Planning": https://arxiv.org/abs/1107.0798
• Dibbelt, Strasser, and Wagner, "Fast Exact Shortest Path and Distance Queries on Road Networks with Parametrized Costs": https://arxiv.org/abs/1509.03165
• OSRM profile docs: https://github.com/Project-OSRM/osrm-backend/blob/master/docs/profiles.md
• OSRM car profile: https://github.com/Project-OSRM/osrm-backend/blob/master/profiles/car.lua
• GraphHopper profile docs: https://github.com/graphhopper/graphhopper/blob/master/docs/core/profiles.md
• Valhalla turn-by-turn API costing docs: https://valhalla.github.io/valhalla/api/turn-by-turn/api-reference/
• Valhalla auto costing implementation: https://github.com/valhalla/valhalla/blob/master/src/sif/autocost.cc
• RoutingKit README: https://github.com/RoutingKit/RoutingKit
• OSRM license: https://github.com/Project-OSRM/osrm-backend/blob/master/LICENSE.TXT
• Valhalla license: https://github.com/valhalla/valhalla/blob/master/COPYING
• GraphHopper license: https://github.com/graphhopper/graphhopper/blob/master/LICENSE.txt

High-Level Findings

There Is No Single "Good GPS" Objective

The route-planning survey by Bast et al. frames road routing as shortest-path search over nonnegative edge weights, then shows that most practical complexity comes from speed, preprocessing, traffic, and multiple criteria. It explicitly notes there is no single best route-planning method because systems are judged by different tradeoffs: query time, preprocessing effort, space, robustness to changing inputs, and model quality.

For our mod, that means "shortest distance" and "prefer highways" are both too thin. A better route is the minimum of a cost function we choose. The game already appears to run an A*/Dijkstra-style solver with a geometric heuristic and nonnegative edge costs. Our task is not to replace that algorithm; it is to feed it a better cost surface.

Production Engines Separate Edge Cost From Transition Cost

OSRM profiles define way speed/rate/weight separately from turn processing. The docs say speed should estimate actual travel time, while rate or weight should encode preference; changing speed to express preference skews duration estimates. OSRM also has a process_turn stage that can assign turn penalties by angle, traffic signals, obstacles, U-turns, road classes, and intersection context.

Valhalla does the same separation. Its auto costing computes edge cost from time, distance preference, density, surface, tolls, alley/service/track factors, and highway preference. Transition cost then adds turn/intersection behavior: OSRM-style turn duration, stop impact, turn type, ramp transition cost, roundabout cost, and U-turn penalties. This is exactly the split we should mirror: road class is only one part of the edge cost; turn and transition costs are a separate part of the route's feel.

GraphHopper's profile model reinforces this. It exposes road prioritization, turn costs, speed, priority, and distance_influence as separate tuning surfaces. Its docs also warn that reusing preprocessed heuristic data can require new weights to be greater than or equal to base weights to preserve correctness. That maps to our A* concern: negative bonuses and broad discounts can make a geometric heuristic less trustworthy. Nonnegative additive penalties are safer than "make good edges cheaper" as a first serious patch.

Human-Friendly Routes Minimize Turns And Decision Points

Jiang and Liu's fewest-turn paper is directly relevant even though Cyberpunk is not normal driving. The paper argues that people often choose routes by road continuity rather than segment-by-segment geometric distance. It highlights fewer turns as lower cognitive burden and explicitly connects fewer turns to fewer slow-down/speed-up events.

The important concept is "natural roads": sequences of segments joined by good continuity. A curve along a ring road is not necessarily a "turn" in the human navigation sense; changing from one road/corridor to another is the turn. The paper used a 45-degree deflection threshold when generating natural roads, but the exact threshold is less important than the idea: penalize route changes and poor continuity, not curvature by itself.

Sacharidis and Bouros extend this into a useful tradeoff model. They define route length and route complexity separately, with complexity as turn/road-change cost. They then discuss near-fastest routes that are as simple as possible and near-simplest routes that are as fast as possible. This is a good conceptual target for us: do not minimize turns at all costs, and do not minimize distance at all costs. Prefer a near-fast route that is much simpler and smoother.

Maneuvers Are State-Dependent

Hlineny and Moris model maneuvers such as turn prohibitions, traffic light delays, roundabouts, and multi-edge restrictions. Their important point for us is that a maneuver depends on how a vertex was reached, not only the current vertex. A plain Dijkstra state of "best cost to node" is insufficient when cost depends on a sequence of prior edges. Their M-Dijkstra expands state to vertex-plus-context.

We probably should not implement a full context-expanded solver inside a game binary patch. But the paper explains why our next hook needs predecessor or incoming-direction information. A turn penalty computed only from the current node flags is inadequate. The local RE already found the game keeps predecessor state at solver-state +0x1e, and the relax call receives current state, neighbor state, and candidate state. That is enough for a practical one-step turn/corridor approximation without redesigning the whole solver.

Speedups Are Mostly Not The Problem Here

Modern routing engines use A*, bidirectional search, contraction hierarchies, landmarks, arc flags, and related preprocessing to answer large road-network queries quickly. This matters academically, but not as the primary mod target. Night City's graph is small enough that the game already computes paths during play. The player's complaint is not "the route takes too long to compute"; it is "the route is dumb."

That said, we should respect solver assumptions. The game uses a straight-line heuristic in the full async solver. If we add only nonnegative penalties to g and to the candidate f = g + h, the heuristic remains conservative relative to the original distance-like base. If we add negative bonuses or deep highway discounts, we may make the heuristic too optimistic or otherwise distort ordering. The proof highway multiplier worked, but the 0.55/0.35 tests already showed how quickly discounts become pathological.

Open-Source Routing Engines

It is viable to use open-source routing software, but there are three different levels of "use":

• Use an engine's ideas and cost model.
• Use an engine offline to preprocess or classify Night City.
• Link or run an engine as the actual in-game route planner.

The first two are practical. The last one is possible, but much more invasive than patching the native solver.

Candidate Engines And Libraries

RoutingKit is the most interesting native-library candidate. It is a C++ route planning library under a BSD-2-Clause license. Its README emphasizes customizable contraction hierarchy support, flexible arc weights, and millisecond-or-better queries on continental-scale data. It exposes direct graph, index, and query APIs. If we wanted a true replacement solver inside a RED4ext DLL, RoutingKit is the most plausible starting point.

OSRM is a high-performance C++ routing engine and service under a permissive BSD-style license. It has excellent production lessons: profile-based cost modeling, turn processing, road classes, and CH/MLD preprocessing. However, it is built around its own extraction/preprocessing pipeline and OpenStreetMap-like data. Embedding OSRM directly would likely mean generating OSRM-compatible data from Cyberpunk resources, running preprocessing, shipping those artifacts, then calling libosrm or a local service.

Valhalla is a C++ routing engine under the MIT license. Its costing model is especially useful because auto routing separates edge cost from transition cost, includes highway preference as a mild factor, and explicitly handles ramps, U-turns, stop impact, density, alleys, service roads, surfaces, and closures. Direct embedding has the same issue as OSRM: Valhalla expects its own graph tiles and attribution model.

GraphHopper is Apache-2.0 and has a strong custom model/profile system, but it is Java. It is useful as a design reference and potentially as an offline analysis tool, but bundling a JVM or running a Java service beside Cyberpunk is not a good first mod architecture.

Generic graph libraries such as Boost.Graph or LEMON are options if we only need Dijkstra/A* and want to own the data model ourselves. They are lighter than OSRM/Valhalla but do not bring road-routing domain logic; we would still write the road/corridor cost model.

Integration Problem

External engines need a graph they own. Cyberpunk's GPS solver operates on internal route/node records, packed handles, and final route records. Linking an engine does not solve either boundary.

To replace the solver, we need:

• Extract or observe the full drivable graph: directed edges, coordinates, flags/classes, turn/intersection topology.
• Convert that graph into the engine or custom graph format.
• Map live start and target positions to graph nodes.
• Compute a route.
• Convert the chosen path back into handles/records the game expects, or hook late enough to draw and consume a custom route.
• Keep manual GPS, AutoDrive, pedestrian, quest-pin, and custom-pin behavior sane.

This is a bigger RE surface than modifying native edge relaxation. It may be worth it if the native solver proves too rigid, but it is not the cheapest next step.

Practical Ways To Use Engines

Best near-term:

• Use Valhalla, OSRM, and GraphHopper as cost-model references.
• Implement their proven split inside the native solver hook: edge cost plus transition cost plus mode/user preference.
• Use additive nonnegative penalties first.

Best offline/precompute:

• Extract VAND/navigation and traffic companion data.
• Build a standalone graph in the repo.
• Use RoutingKit or a small custom A* to experiment rapidly outside the game.
• Generate baked labels: corridor id, natural-road id, intersection complexity, ramp/connector classification, slope/airtime risk, and road-class confidence.
• Feed those labels back into the RED4ext patch as compact lookup tables.

Possible long-term replacement:

• Use RoutingKit or a custom solver in-game.
• Hook full solver output building around 0x818ba8 or later result materialization.
• Emit game-native route records from our computed node/handle path.

This replacement path is feasible only after we can round-trip a native route: decode a vanilla route into graph handles, reproduce it externally, then inject the same route back without changing behavior.

Recommendation

Do not link a full production engine yet. Use RoutingKit or a small custom graph runner offline to prototype and validate the cost function, then patch the native solver relaxation/cost surface. The native patch has hard game integration for free: target selection, start projection, route output, minimap/world-map drawing, and AutoDrive consumers.

Revisit full engine integration if:

• Predecessor/current/neighbor geometry is inaccessible.
• Native route output cannot express the desired route.
• The cost model requires expanded solver state that the game's one-label node state cannot support.

Implications For Cyberpunk 2077

Manual Player GPS Should Optimize Momentum

A real GPS assumes legal speed, stop signs, lights, congestion, safety, and human compliance. A Cyberpunk player in a Caliburn does not. The manual-driving cost model should assume:

• Posted speed is weak evidence. The player can exceed it.
• Traffic simulation metadata is useful but secondary. The player often cuts through or around traffic.
• Highway classification is useful but not decisive. Short freeway hops can be worse than a straight arterial or side-street corridor.
• Route smoothness matters because every hard turn, ramp dive, or intersection chain costs player speed and control.
• Roads with good continuity should be preferred even if they are not highways.

AutoDrive Should Remain More Traffic-Like

AutoDrive behaves more like an NPC/legal driver than the player does. It should benefit more from road hierarchy, speed limits, traffic-sim classes, and avoiding odd local shortcuts. Manual drive and AutoDrive probably should share the same hook site if possible, but they may need different parameter presets.

The previous warning still stands: do not accidentally apply a manual-only surface to AutoDrive while leaving manual GPS on another surface, or vice versa, unless the mode split is deliberate and documented.

Recommended Cost Model

The next prototype should use additive penalties at the solver edge-relaxation site rather than more highway discounts.

Base:

candidate_g =
  vanilla_g
  + short_segment_penalty
  + turn_or_continuity_penalty
  + intersection_complexity_penalty
  + ramp_transition_penalty
  + grade_or_airtime_risk_penalty
  + optional_road_class_penalty

Where:

• vanilla_g is the game's current current.g + delta * nodeMultiplier * directionMultiplier.
• short_segment_penalty discourages stair-stepping through many tiny edges.
• turn_or_continuity_penalty is based on predecessor/current/neighbor angle, not on road class alone.
• intersection_complexity_penalty approximates stop-start risk and decision points, probably from node degree, flags, or short connector density.
• ramp_transition_penalty applies when moving highway <-> non-highway through a short/angled connector.
• grade_or_airtime_risk_penalty applies when vertical delta or local shape indicates a steep launch/drop. This is lower priority until we prove the height fields are stable.
• optional_road_class_penalty can still mildly prefer highways/arterials, but should be subordinate to continuity.

Avoid negative "bonuses" in the first real version. If a road is desirable, make its alternatives pay an added cost. This preserves a safer A*/Dijkstra-style cost surface and avoids the pathological over-attraction seen with highway discounts.

Candidate Patch Sites

The proven but blunt hook:

• 0x40bb98: road-tail multiplier block in 0x40bb40.
• It sees solver and node and can inspect flags such as Highway.
• It cannot see predecessor/current/neighbor geometry, so it cannot distinguish a good corridor from a bad ramp hairpin.

The better next hook:

• 0x40b304 and 0x40b540: neighbor expansion helpers.
• They compute vanilla tentative g, straight-line heuristic h, and then call 0x40ba58.
• At the 0x40ba58 callsites, the live context includes solver pointer, current state, neighbor state, current node, neighbor node, candidate state, route mode, progress/delta, and enough vector data for one-step geometry.

The likely patch shape:

• Inline patch at the relax path, not a C detour on a tiny helper.
• Adjust candidate g and candidate f by the same nonnegative penalty before vanilla 0x40ba58 compares against neighbor_state+0x14 and writes neighbor_state+0x10.
• Keep the first build low-noise. Logging every edge expansion is pathological; route-window sampling or aggregate counters are enough.

First Prototype Parameters

Start conservative. The goal is to prove the model changes routes in the right direction without causing highway hairpins or search blowups.

Suggested first-pass terms:

• Short segment churn:
  • If edge distance/progress delta is under roughly 25-40 meters, add a small fixed penalty or a penalty proportional to the missing length.
• Turn continuity:
  • If predecessor position is available, compute normalized vectors prev -> current and current -> neighbor.
  • No penalty for very straight movement.
  • Mild penalty for shallow deflection.
  • Stronger penalty for 60-120 degree turns.
  • Very strong penalty for U-turn-like reversals unless near origin/destination.
• Corridor continuation:
  • Treat same-road or good-continuity transitions as neutral, not discounted.
  • A curved ring/highway should stay cheap if it is continuous.
• Ramp churn:
  • Penalize highway/non-highway transitions when the connector is short and the turn angle is high.
  • Do not penalize a long smooth ramp the same way.
• Intersection complexity:
  • Penalize nodes with many outgoing options or multiple short connectors if the relevant fields can be identified.
• Slope/airtime:
  • Start as logging-only unless height deltas clearly correlate with known bad places. Add as a later penalty.

Testing Plan

Keep the route set from previous testing:

• El Coyote / city-center custom pin, because it exposed the bad hairpin.
• Side job, Sinnerman, and Claire from the fixed car save.
• Violence / No-Tell Motel cross-city routes.
• The Gig / Cassius Rider long Watson route.
• Aldecaldo / Badlands routes.
• Cyberpsycho sighting on the unfinished highway.

Add tests targeted at the new model:

• A straight long side-street corridor in Heywood vs a short freeway hop.
• A route with several 90-degree stair-step alternatives.
• A known suspended-highway offramp or hilly road that causes airtime at speed.
• AutoDrive on the same destination, to check whether its behavior remains sane.

Practical Next Step

Before coding the full patch, do one static pass to finish the field map around 0x40b304, 0x40b540, and 0x40ba58:

• Confirm candidate vector layout at 0x40b8f0/state allocation.
• Confirm predecessor state pointer/index path from state+0x1e.
• Confirm route-mode values at solver+0xc4 for manual driving vs AutoDrive.
• Identify a cheap way to detect road-class transition from current/neighbor node flags.
• Decide whether the first prototype patches only the two main relax callsites (0x40b4ac, 0x40b6d5) or also the special/helper relax paths (0x40b175, 0x40bca7).

After that, implement the smallest live-tunable prototype with additive penalties only. Keep highway multiplier support available as a diagnostic knob, but do not use it as the primary default behavior.