# DayZ Memory C++ Overlay

Windows C++20 DayZ DMA reader with an ImGui/DirectX 11 overlay and a browser-based web radar.

The application attaches to `DayZ_x64.exe` through VolkDMA, resolves the current DayZ runtime structures, reads entities in the background, and publishes the same live snapshot to two frontends:

- A transparent desktop overlay for ESP, skeletons, loot, bullet trails, and aim-assist visualizations.
- A local HTTP/SSE web radar with map tiles, filters, player lists, bullet paths, and remote browser support.

Use this only on systems and servers where you are allowed to inspect the target process. The built-in web server is plain HTTP; set a password before exposing it outside localhost or your trusted LAN.

## Features

- External DMA-backed memory access through VolkDMA.
- Runtime signature scanning and static offsets for DayZ structures.
- Automatic reconnect behavior when the process/session drops.
- High-frequency camera reads decoupled from entity scans.
- Player, infected, animal, vehicle, loot, corpse, and bullet snapshots.
- Player skeleton rendering with cached bone pointer chains and gap filling.
- Health, held weapon, worn items, names, boxes, head circles, and configurable draw distances.
- Ballistic aim dot using local weapon ammo velocity and drag values.
- Bullet trail visualization for active, completed, and phantom bullet tracks.
- Configurable item category filters from `config/item_filters.json`.
- DirectX 11 transparent overlay with a Lumin/ImGui menu.
- Built-in HTTP server with:
  - `GET /` static radar UI
  - `GET /api/bootstrap`
  - `GET /api/state`
  - `GET /events` server-sent events
  - `GET /tile`
  - `GET /map-image`
  - `GET /api/debug`
- CORS support for serving the web UI from a different origin.
- Optional `Caddyfile` for static webroot hosting and API proxying.
- Embedded map support for known maps, with runtime disk PNG overrides.
- DMA throughput stats shown in the overlay info panel.

## Requirements

### Platform

- Windows x64.
- Visual Studio 2022 Build Tools or full Visual Studio with the MSVC x64 toolchain.
- Windows SDK with DirectX 11 headers/libraries.
- CMake 3.20 or newer.
- Git.
- Internet access during the first CMake configure, unless dependencies are already cached.

### External dependency: VolkDMA

`CMakeLists.txt` expects VolkDMA at this sibling path:

```text
../dayz-dma/dma-dayz-cpp-master/VolkDMA
```

That directory must contain:

- `src/dma.cpp`
- `src/process.cpp`
- `src/inputstate.cpp`
- `include/VolkDMA/...`
- `external/vmm`
- `external/leechcore`
- `dlls/vmm.dll`
- `dlls/leechcore.dll`
- `dlls/FTD3XX.dll`

If your VolkDMA checkout lives somewhere else, update `VOLKDMA_ROOT` near the top of `CMakeLists.txt`.

### Fetched dependencies

CMake downloads these with `FetchContent`:

- `nlohmann/json` v3.11.3
- `spdlog` v1.14.1
- `cpp-httplib` v0.18.1
- `stb` from upstream master

The ImGui/Lumin/FreeType pieces are vendored under `external/lumin`.

## Repository Layout

```text
.
|-- CMakeLists.txt
|-- Caddyfile
|-- config/
|   |-- config.cfg
|   `-- item_filters.json
|-- external/lumin/
|-- maps/                  # optional, git-ignored map PNGs
|-- src/
|   |-- Core/              # shared runtime models
|   |-- Memory/            # VolkDMA/VMM access wrapper
|   |-- Overlay/           # DirectX/ImGui overlay and menu bridge
|   |-- Readers/           # entity, item, bullet, scoreboard readers
|   |-- Resolvers/         # world/local player/network metadata resolvers
|   |-- Runtime/           # service loop and snapshot orchestration
|   |-- SigScanner/        # signature scanner
|   `-- Web/               # web radar server, snapshots, maps, bullet cache
`-- webroot/               # browser radar UI
```

Build output is normally placed under `build/<config>/`. Post-build steps copy runtime DLLs, `config/`, `webroot/`, `maps/`, and icon font assets next to the executable.

## Quick Start

From a Developer PowerShell or a shell with MSVC available:

```powershell
cmake -S . -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release
```

Run from the output directory so relative paths resolve to the copied assets:

```powershell
cd .\build\Release
.\dayz-memory-cpp.exe
```

Typical launch flow:

1. Start DayZ and join a server.
2. Start `dayz-memory-cpp.exe`.
3. Watch the console or `logs/dayz-memory.log` for attach/status messages.
4. Press `INSERT` to open or close the overlay menu.
5. Open `http://localhost:7777` for the web radar.

## Running From an IDE

Use the `dayz-memory-cpp` CMake target.

Recommended debug/run settings:

- Generator/platform: x64 MSVC.
- Working directory: `$<TARGET_FILE_DIR:dayz-memory-cpp>` or the concrete output folder such as `build/Debug`.
- Configuration: `Release` for normal use, `Debug` for development.

Running from the repository root can work for some files, but the executable also needs the copied DLLs and data directories. The output directory is the least surprising working directory.

## Runtime Controls

- `INSERT`: toggle the overlay menu.
- `Config -> Save Config`: writes overlay settings to `config/overlay.json`.
- `Config -> Exit`: closes the overlay and stops the process.
- `Ctrl+C` in the console: requests shutdown.

Menu tabs:

- `Aim`: ballistic dot and bullet trail toggles.
- `Visuals`: player/world ESP toggles and draw distances.
- `Loot`: item category filters sourced from `config/item_filters.json`.
- `Info`: connection status, entity counts, local position, DMA stats, web radar info.
- `Config`: monitor/render resolution overrides, save, and exit.

## Configuration

There are two config files:

- `config/config.cfg`: INI-style runtime reader settings.
- `config/overlay.json`: JSON overlay/web settings, created or updated by the menu.

Both paths are resolved relative to the process working directory. Post-build copies the repository `config/` directory next to the executable.

### `config/config.cfg`

The parser accepts `key = value` lines and ignores `#` comments. Missing keys keep the code defaults.

Supported runtime keys:

| Key | Default if omitted | Purpose |
| --- | --- | --- |
| `processName` | `DayZ_x64.exe` | Target process name. |
| `useMemoryMap` | `true` | Enables VolkDMA memory map usage. |
| `networkMetadataRefreshMs` | `30000` | Server name/version/map refresh interval. |
| `scoreboardRefreshMs` | `30000` | Scoreboard refresh interval. |
| `nearEntityRefreshMs` | `20` | Near entity list refresh interval. |
| `farEntityRefreshMs` | `50` | Far entity list refresh interval. |
| `slowEntityRefreshMs` | `100` | Slow entity list refresh interval. |
| `bulletRefreshMs` | `50` | Bullet table refresh interval. |
| `itemRefreshMs` | `200` | Item scan refresh interval. |
| `playersRefreshMs` | `16` | Player projection/update interval. |
| `boneRefreshMs` | `4` | Bone scatter refresh interval. |
| `liveLoopIdleMs` | `1` | Main loop idle sleep. Lower is more responsive and more CPU-heavy. |
| `reconnectThreshold` | `5` | Consecutive failures before reconnect. |
| `reconnectGracePeriodMs` | `5000` | Delay after session loss before reconnect. |
| `farEntityBatchSize` | `64` | Far entity batch size per tick. |
| `slowEntityBatchSize` | `64` | Slow entity batch size per tick. |
| `itemBatchSize` | `64` | Item batch size per tick. |
| `bonePlayerMaxDist` | `500.0` | Max player distance for skeleton reads. |
| `boneZombieMaxDist` | `250.0` | Max infected distance for skeleton reads. |
| `vmmRefreshMs` | `30000` | VMMDLL cache refresh cadence. |
| `itemSpatialFilterRadius` | `300.0` | Max item distance from local player published to overlay/web. |

The checked-in file intentionally keeps conservative refresh rates. Reduce intervals only when you have enough DMA/CPU headroom.

### `config/overlay.json`

If the file does not exist, defaults from `OverlayConfig` are used. Saving from the menu creates it.

Example:

```json
{
  "showPlayers": true,
  "showAnimals": true,
  "showZombies": true,
  "showItems": true,
  "showBox": true,
  "showSkeleton": true,
  "showHeadDot": false,
  "showCorpses": false,
  "showWeapon": true,
  "showHealthBar": true,
  "showHealthNumber": false,
  "playerMaxDist": 1000.0,
  "animalMaxDist": 1000.0,
  "zombieMaxDist": 500.0,
  "itemMaxDist": 200.0,
  "overlayWidth": 0,
  "overlayHeight": 0,
  "renderWidth": 0,
  "renderHeight": 0,
  "stretchToFill": true,
  "webBindAddress": "0.0.0.0",
  "webPort": 7777,
  "webPassword": ""
}
```

Resolution notes:

- `overlayWidth` and `overlayHeight` should be the monitor resolution.
- `renderWidth` and `renderHeight` should be the resolution DayZ actually renders at.
- Leave render dimensions at `0` when the game render resolution matches the monitor.
- Set `stretchToFill` to `false` if the game is letterboxed or pillarboxed instead of stretched.

### `config/item_filters.json`

Loot categories are data-driven. Each top-level key is a category and can match by:

- `Name`
- `TypeName`
- `ConfigName`
- `ModelName`

Values may be a string or an array of strings. Matching is case-insensitive substring matching after normalization.

Example:

```json
{
  "isWeapon": {
    "desc": "Weapons",
    "Color": "#f43f5e",
    "TypeName": "weapon"
  },
  "isFood": {
    "desc": "Food and drinks",
    "Color": "#22c55e",
    "ModelName": ["\\food\\", "\\drinks\\"]
  }
}
```

If `item_filters.json` is missing, `ItemFilterCatalog` writes a default file.

## Web Radar

When the app starts, it launches an HTTP server using settings from `config/overlay.json`.

Default URL:

```text
http://localhost:7777
```

LAN access:

```text
http://<overlay-pc-ip>:7777
```

The overlay `Info` tab lists detected local URLs.

### Authentication

Set `webPassword` in `config/overlay.json` before exposing the radar beyond localhost:

```json
{
  "webPassword": "change-me"
}
```

Remote clients append the password as a query parameter:

```text
http://<host>:7777/?password=change-me
```

Loopback requests are allowed without a password. An empty password disables password checks.

### API Endpoints

| Endpoint | Description |
| --- | --- |
| `/` | Serves `webroot/index.html`. |
| `/api/bootstrap` | Initial map/filter/server metadata. |
| `/api/state` | Latest full JSON state for polling clients. |
| `/events` | Server-sent events stream for live updates. |
| `/tile` | Serves 512x512 map tiles. |
| `/map-image` | Serves the full map image when available. |
| `/api/debug` | Debug information for paths and runtime state. |

Cross-origin `GET` and `OPTIONS` requests are supported so the UI can be hosted separately from the C++ backend.

### Static Hosting With Caddy

The included `Caddyfile` serves `webroot/` on port `8080` and proxies API/data endpoints to the C++ backend on `7777`.

From the repository root:

```powershell
caddy run
```

Open:

```text
http://localhost:8080
```

This mode keeps browser requests same-origin on `:8080` while Caddy proxies `/api/*`, `/tile`, `/map-image`, and `/events` to the backend.

### Static Host With `server=` Parameter

The web UI can also be hosted somewhere else and pointed at the backend:

```text
http://static-host/index.html?server=http://192.168.1.25:7777&password=change-me
```

The `server` value is stripped of a trailing slash in `webroot/app.js`.

## Map Images

Map PNGs are loaded from:

```text
maps/<map-id>.png
```

The folder is resolved relative to the executable directory. The repository `maps/` directory is git-ignored because map images are large/user-supplied.

Supported map IDs:

| File | Map |
| --- | --- |
| `chernarusplus.png` | ChernarusPlus |
| `livonia.png` | Livonia / Enoch |
| `namalsk.png` | Namalsk |
| `banov.png` | Banov |
| `deadfall.png` | Deadfall |
| `deerisle.png` | Deer Isle |
| `esseker.png` | Esseker |
| `lux.png` | Lux |
| `sakhal.png` | Sakhal |
| `takistan.png` | Takistan |
| `alteria.png` | Alteria |

Runtime disk files take priority. CMake can also embed map PNGs that exist under repository `maps/` at configure time. Re-run CMake after adding new map images if you want them embedded into the executable.

The tile server cuts maps into 512x512 PNG tiles and caches encoded tile bytes in memory after first request.

## Architecture

### Startup

`src/main.cpp` performs startup:

1. Creates `logs/`.
2. Initializes spdlog.
3. Loads `config/config.cfg` into `RuntimeConfig`.
4. Loads `config/overlay.json` into `OverlayConfig`.
5. Starts `WebRadarServer`.
6. Starts `DayZRuntimeService`.
7. Creates the overlay and enters the DirectX/ImGui render loop.

### Memory Layer

`src/Memory/VmmAccessor.*` wraps VolkDMA process access:

- Initializes DMA/VMM.
- Finds and attaches to `DayZ_x64.exe`.
- Applies `fix_cr3`.
- Performs typed reads, raw reads, string reads, and scatter reads.
- Tracks total bytes and scatter calls for DMA stats.
- Re-applies CR3 after `ForceRefresh()`.

### Runtime Service

`src/Runtime/DayZRuntimeService.*` owns the background reader threads.

The main live loop:

- Waits for a valid process/session.
- Resolves base objects and runtime offsets.
- Refreshes near/far/slow entity lists at configured intervals.
- Refreshes scoreboard and network metadata.
- Reads local player and camera data.
- Reads bullets and items.
- Projects raw entities into typed player/animal/zombie/vehicle/loot snapshots.
- Refreshes bones using scatter reads.
- Publishes a `RuntimeUpdate` snapshot to overlay and web server consumers.

A separate camera loop keeps projection data fresher than the heavier entity scans.

### Readers and Resolvers

- `Resolvers/BaseObjectResolver.*`: resolves core world/network pointers.
- `Resolvers/LocalPlayerResolver.*`: resolves local player data.
- `Resolvers/NetworkMetadataReader.*`: reads server metadata.
- `Readers/NearEntityListReader.*`: near entity list.
- `Readers/FarEntityListReader.*`: far entity list.
- `Readers/SlowEntityListReader.*`: slow entity list.
- `Readers/ItemListReader.*`: loot/item extraction.
- `Readers/BulletTableReader.*`: active bullet reads and direction inference.
- `Readers/ClientScoreboardReader.*`: scoreboard player entries.
- `Readers/EntityCategoryProjector.*`: classifies raw entities into typed output lists.
- `Readers/ItemFilterCatalog.*`: loads and applies loot filter rules.

### Signature and Offset Handling

- `src/SigScanner/SigScanner.*` scans the module with page-sized scatter reads.
- `src/Offsets.h` contains known static offsets.
- `src/RuntimeOffsets.h` stores runtime-resolved addresses/offsets used by readers.

After a DayZ update, signature patterns and offsets are the first places to check if attach succeeds but data is wrong.

### Overlay

- `src/Overlay/OverlayWindow.*`: Win32 window, DirectX 11 device, swap chain, ImGui backend, font setup.
- `src/Overlay/GameOverlay.*`: ESP rendering, projection, menu state, smoothing, bullet trails, ballistic dot.
- `src/Overlay/MenuBridge.h`: pointer bridge between project state and the vendored Lumin menu.
- `external/lumin/framework/gui.cpp`: actual menu layout.

### Web Radar

- `src/Web/WebRadarServer.*`: HTTP routes, SSE broadcast, auth, CORS.
- `src/Web/WebSnapshotService.*`: converts `RuntimeUpdate` into JSON.
- `src/Web/BulletTrackCache.*`: keeps bullet path history for web and overlay visualizations.
- `src/Web/MapRegistry.*`: known maps, aliases, world-to-map coordinate transforms.
- `src/Web/MapTileService.*`: map image loading, tile generation, PNG caching.
- `webroot/`: static browser UI.

## Logs

Logs are written to:

```text
logs/dayz-memory.log
```

The file sink logs at trace level and is truncated on each run. The console sink defaults to info level.

Useful messages to look for:

- Process attach and reconnect events.
- Signature scan results.
- Base object/session readiness.
- Skeleton loss diagnostics.
- Ammo chain diagnostics for ballistic prediction.
- Periodic live heartbeat with player/zombie counts.

## Build Notes

- The project is Windows-only and intentionally fails CMake configure on non-Windows platforms.
- The target is `dayz-memory-cpp`.
- C++ standard is C++20.
- MSVC builds with `/W4`, `/permissive-`, `/utf-8`, and warnings not treated as errors.
- `NOMINMAX`, `IMGUI_ENABLE_FREETYPE`, and `IMGUI_DEFINE_MATH_OPERATORS` are set for the target.
- Runtime DLLs are copied from `${VOLKDMA_ROOT}/dlls` after build.
- `webroot/`, `config/`, `maps/`, and Lumin icon fonts are copied after build.

## Troubleshooting

### CMake cannot find VolkDMA files

Confirm this path exists:

```text
../dayz-dma/dma-dayz-cpp-master/VolkDMA
```

If your checkout is elsewhere, edit `VOLKDMA_ROOT` in `CMakeLists.txt`.

### Dependency download fails during configure

The first configure fetches dependencies from GitHub. Check network/proxy access or use a CMake dependency cache with the packages already populated.

### Executable exits immediately with `0xC0000135`

That status usually means a DLL is missing. Confirm these files are next to `dayz-memory-cpp.exe`:

- `vmm.dll`
- `leechcore.dll`
- `FTD3XX.dll`

Rebuild the target or manually verify `${VOLKDMA_ROOT}/dlls` contains those DLLs.

### Overlay opens but ESP alignment is wrong

Open `Config` and set:

- Monitor resolution in `overlayWidth` / `overlayHeight`.
- Game render resolution in `renderWidth` / `renderHeight` if DayZ renders at a different resolution.
- `stretchToFill` according to your GPU/display scaling mode.

Save config and restart if needed.

### Web radar is blank

Check:

- The app is attached and `Info` shows connected.
- The browser URL points to the correct host/port.
- `webPassword` matches the `?password=` parameter for remote clients.
- `webBindAddress` is not restricted to `127.0.0.1` when using another device.
- Firewall allows the configured port.

### Map background is missing

Place a supported PNG at:

```text
maps/<map-id>.png
```

Example:

```text
maps/chernarusplus.png
```

If you added the PNG to the repository `maps/` folder and want it embedded, re-run CMake configure and rebuild.

### Caddy serves 404s

Run `caddy run` from the repository root so `root * ./webroot` resolves correctly, or adjust the `root` path in `Caddyfile`.

### Port is already in use

Change `webPort` in `config/overlay.json`, then restart. If using Caddy, also update the upstream port in `Caddyfile`.

### Attach succeeds but entity data is wrong

DayZ offsets or signatures may be stale. Check:

- `src/Offsets.h`
- `src/RuntimeOffsets.h`
- `src/SigScanner/SigScanner.cpp`
- `logs/dayz-memory.log`

Runtime structures can change after a DayZ update even when the process name and module still resolve.

## Development Workflow

### Add a new memory field

1. Add or update the offset in `src/Offsets.h` or runtime scanner logic.
2. Read the value in the appropriate resolver/reader.
3. Add fields to `src/Core/Models.h` or `RuntimeUpdate` if the value must cross module boundaries.
4. Publish the field to overlay or web code.
5. Add diagnostics around pointer-chain failures if the chain is fragile.

### Add an overlay option

1. Add the value to `OverlayConfig` if it should be configurable.
2. Load/save it in `src/Config.cpp`.
3. Add a member in `GameOverlay`.
4. Sync it in `GameOverlay::SyncConfig()`.
5. Expose it through `MenuBridge`.
6. Add the control in `external/lumin/framework/gui.cpp`.
7. Use the toggle in the draw path.

### Add a web radar field

1. Add it to the relevant runtime model.
2. Serialize it in `WebSnapshotService`.
3. Consume it in `webroot/app.js`.
4. Style it in `webroot/style.css` when needed.
5. Update bootstrap data if the frontend needs metadata or filter definitions.

## Known Limitations

- Windows-only.
- Offsets/signatures must match the current DayZ build.
- Built-in web server is HTTP only; use Caddy, a tunnel, or another reverse proxy for TLS.
- Web auth is a simple query-parameter password, not a full user/session system.
- Map recognition depends on server map metadata and the known map alias table.
- Browser map images require correctly named PNGs unless embedded at build time.
- Overlay projection depends on correct monitor/render resolution configuration.

## License and Third-Party Code

This repository vendors or fetches third-party components. Check their upstream licenses before redistributing binaries:

- Dear ImGui under `external/lumin/thirdparty/imgui`.
- FreeType under `external/lumin/thirdparty/freetype`.
- Lumin framework under `external/lumin/framework`.
- nlohmann/json, spdlog, cpp-httplib, and stb through CMake `FetchContent`.
- VolkDMA and its bundled VMM/LeechCore dependencies from the sibling checkout.
