# MomentumGPS

Cyberpunk 2077 RED4ext plugin that improves player GPS routing by penalizing
short-segment churn in the native GPS solver. The validated default pushes the
GPS toward smoother, higher-momentum driving corridors without globally forcing
every route onto highways.

## Current Status

Working RED4ext plugin, validated in-game.

- Route scoring patch: enabled.
- Current fixed ordinary-edge penalty: `80.0`.
- Live tuning: removed from the release build.
- Highway multiplier/class weighting experiments: not part of the playable
  default.

The active package is a RED4ext plugin only:

```text
red4ext/plugins/MomentumGPS/MomentumGPS.dll
red4ext/plugins/MomentumGPS/README.txt
```

## What It Patches

Reverse engineering found the player GPS route search loop around the native
solver relaxation cluster. The useful patch surface is not the script-facing
`RunGPSQuery`/`UpdateGPSQuery` helpers and not generated traffic `maxSpeed`
fields. The playable hook patches the two ordinary adjacency expansion sites
feeding the native relax/update routine at `0x40ba58`.

The plugin adds a fixed cost to ordinary edge expansion. In practice, this makes
many tiny street segments and repeated 90-degree stair-steps less attractive,
while still allowing local roads when they are the right path.

This is an inline native patch against tested Cyberpunk 2077 executable RVAs. A
future game update may require fresh verification.

## Validation Summary

The default `80.0` penalty was selected after live A/B testing:

- `0.0`: vanilla behavior; visibly stair-stepped in highlighted routes.
- `40.0`: partial improvement, but still missed useful smoother corridors.
- `80.0`: best observed result; selected smoother high-speed corridors and
  passed drive testing.
- `160.0`: too high; caused bad hairpins/local access and one fallback-style
  route.

Drive validation at `80.0`:

- The Dogtown route used a smoother highway corridor and drove cleanly at high
  speed.
- Live minimap recalculation still worked after a deliberate detour.
- Claire/Westbrook route also drove cleanly; one blind hill/ramp surprise was
  driver unfamiliarity, not a route failure.

See [docs/gps-momentum-field-tests.md](docs/gps-momentum-field-tests.md) for
the detailed test notes, screenshots, and log references.

## Build

Build in the Fedora toolbox:

```bash
toolbox run -c 2077 ./tools/build_red4ext_shim.sh
```

This writes:

```text
build/red4ext/MomentumGPS-mingw64/MomentumGPS.dll
```

## Install Locally

Only install while the game is cold.

```bash
toolbox run -c 2077 ./tools/install_red4ext_shim.sh
```

The install script builds the DLL and installs it into the Flatpak Steam
Cyberpunk 2077 folder. Override the game directory with
`CYBERPUNK2077_GAME_DIR` if needed.

## Package

Create a redistributable RED4ext zip:

```bash
toolbox run -c 2077 ./tools/package_red4ext_mod.sh
```

The package is written under `dist/` and contains the `red4ext/` folder layout
expected by the game.

## Repository Notes

This repository also contains older experiments and reverse-engineering tools:

- REDmod/archive traffic resource patchers.
- Traffic lane and connection probability patchers.
- Static disassembly helpers.
- RED4ext logging probes.
- Earlier live-tuning helpers and presets.

Those tools are retained because they explain the route-finding system and
document failed approaches, but they are not part of the current playable
package. The important debriefs are:

- [docs/traffic-system-debrief.md](docs/traffic-system-debrief.md)
- [docs/red4ext-logging-shim.md](docs/red4ext-logging-shim.md)
- [docs/gps-routing-research.md](docs/gps-routing-research.md)