From 89bb2c3e38862f86793a04b35c81061a82817930 Mon Sep 17 00:00:00 2001 From: 67 <67@67.sigma> Date: Fri, 19 Jun 2026 21:04:09 +0800 Subject: [PATCH] add readme --- README.md | 615 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 615 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..c673eee --- /dev/null +++ b/README.md @@ -0,0 +1,615 @@ +# 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//`. 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: `$` 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://: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://: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/.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/.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.