Takes the project from docs-only to a state where the P0 spike can begin.
Everything here was verified to run, not just written.
Managed
global.json pins the SDK band. Without it `dotnet --version` on this
machine resolved to an 11.0 preview, which silently changes analyzer
behaviour under TreatWarningsAsErrors and makes local and CI disagree
for reasons invisible in a diff. Not mentioned in any doc; added to
12_BUILD.
TargetFramework net10.0-windows10.0.22621.0 with
SupportedOSPlatformVersion 10.0.19045.0. The plan called for a 19041
target, but the SDK rejects SupportedOSPlatformVersion above
TargetPlatformVersion (NETSDK1135), and 19045 is not a targeting-pack
version — the packs are cut at 19041/20348/22000/22621/26100.
12_BUILD already requires the Windows 11 SDK >= 22621, so targeting it
costs nothing while CA1416 still enforces the 22H2 floor from NFR-8.
Solution is FrameLedger.slnx: the XML format is what `dotnet new sln`
produces on .NET 10, and it diffs far better than the classic format.
Six projects plus three test projects, wired to the dependency
direction CLAUDE.md specifies. Builds warning-free under
TreatWarningsAsErrors + AnalysisLevel=latest-all; the only analyzer
suppressions are three WPF codegen constraints, scoped to
src/FrameLedger.App and each explained in .editorconfig.
Pinned SQLitePCLRaw forward: Microsoft.Data.Sqlite 10.0.10 resolves
lib.e_sqlite3 2.1.11, which carries GHSA-2m69-gcr7-jv3q. The build
failed on it, correctly.
Pinned FluentAssertions to the 7.x line. 8.0.0 moved from Apache-2.0
to Xceed's Community Licence, which is not OSI and carries
field-of-use restrictions — exactly what 18_GPU_VENDOR_APIS's vendor
checklist rejects. Dependabot is configured not to major-bump it.
Native
fl_shm.h is the valuable artifact: the corrected four-region layout,
with static_asserts on every size and offset. Compile-verified — all
four structs are exactly 64 bytes with no implicit holes, and the
mapping is 512 KiB + 192 B of header. fl-layout-dump emits those
offsets as JSON for the C# mirror test to consume.
/guard:cf and -D_HAS_EXCEPTIONS=0 are deliberately NOT applied to the
Overlay target yet. Both are unresolved (20_OPEN_QUESTIONS H1, H3);
applying them now would mean meeting the problem as a crash in a real
game rather than as a decision.
Not compiled: this machine has no MSVC C++ workload, so the CMake
targets are unverified. The headers were checked with g++ instead.
Gates
build.ps1 check runs the nine gates, and CI runs that same script.
Gates skip loudly — the run ends "PASSED WITH N SKIPPED GATE(S)"
rather than a clean pass, because a gate that silently passes because
its tool is missing reads as "checked" when nothing was checked.
license-check and rules-validate are real, and were proven red-green
before being wired in: a planted IGCL header fails the licence gate,
and an emptied anticheat.modules list (or a dropped BattlEye entry, or
malformed JSON) fails the rules gate. A safety gate only ever observed
passing has not been tested.
Added a placeholder guard: any {{ token other than {{RELEASE_DATE}}
surviving in README.md or legal/*.md fails the build. Those documents
are displayed for acceptance under FR-11.
rules/detection-rules.json is seeded with a non-empty anticheat block.
An empty one is a fail-closed fixture, not a ship state.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
FrameLedger
A local-first game performance ledger for Windows. FrameLedger records frame times, FPS metrics, hardware telemetry, and — crucially — the settings your game is actually rendering with, every time you play. Then it turns your history into charts, so you can see exactly how a patch, a driver update, or a settings change affected performance.
No telemetry. No accounts. All data stays on your machine.
What makes it different
Most tools tell you your frame rate. FrameLedger tells you what produced that frame rate:
- Real render resolution vs output resolution — the actual internal resolution, not the one in the settings menu.
- Which upscaler is running, at which quality preset — DLSS / FSR / XeSS, read from the API the game calls, not guessed from files on disk.
- Frame Generation, measured — native and generated frames counted separately. Always shown as
62 → 118 FPS (×1.9 FG), never as one inflated number. - Ray tracing, actually detected — including inline ray tracing (DXR 1.1
RayQuery), which frame-counting tools miss entirely. - Per-process VRAM and whether the driver was exceeding its budget (a real stutter explanation).
- Shader-compilation stutter attribution — which frame spikes were pipeline compiles.
- PC latency when the game uses Reflex.
Plus the usual: Avg / Min / Max / Median FPS, 1% Low, 0.1% Low, frametime distributions, stutter metrics, CPU/GPU temperatures, session history, cross-session comparison, and Steam/GOG/Epic/itch.io library import. UI in English / Tiếng Việt / 日本語.
How it works — and the trade-off, stated plainly
None of the settings data above is visible from outside a game process. To read it, FrameLedger loads a component into the game and observes the calls the game makes to graphics APIs — the same class of technique used by frame-rate overlays, recording software, and post-processing injectors. Vulkan titles use a standard Vulkan layer instead.
That carries a real risk: anti-cheat systems can detect injected code and may ban accounts.
FrameLedger is built to keep that risk small and to be honest about it:
| Safeguard | |
|---|---|
| Off by default | Injection is disabled for every game until you enable it individually, after a consent prompt |
| Hard refusal | Known anti-cheat/anti-tamper components are detected before injection and every 30 s during a session. Detected ⇒ FrameLedger refuses, or unhooks at the next scan — so up to 30 s can pass before it reacts to anti-cheat that loads mid-session. There is no override — not in settings, not in a config file, not on the command line |
| No evasion, ever | FrameLedger does not hide, rename, obfuscate, or disguise itself. It keeps its real name, real exports, and version info. It is meant to be plainly visible to any security software that looks. This is an architectural rule, not a setting |
| Read-only | It never reads or writes game memory, never modifies game behavior, never touches saves or input, and never changes GPU clocks, fans, or power limits |
| Always a way out | A no-injection mode (ETW-based) is the default for anything the software is unsure about. It needs the Agent running elevated, because Windows restricts the trace sessions it uses — FrameLedger tells you when that applies rather than silently recording less |
FrameLedger is for offline and single-player games. If you enable it for anything with an online or competitive component, that is your call and your responsibility. The developer cannot reverse a ban. Please read legal/DISCLAIMER.md and docs/19_SAFETY_AND_ANTICHEAT.md before enabling it for anything.
Capture tiers
| Tier | How | What you get |
|---|---|---|
| 1 | Injected hooks (opt-in, per game) | Everything above |
| 2 | ETW / Intel PresentMon, no injection (needs an elevated Agent) | Frame times, FPS, lows, present mode, coarse frame-generation inference |
| 3 | None | Session duration + hardware telemetry |
The tier is recorded on every session and shown in the UI. Metrics unavailable at a session's tier read N/A — FrameLedger never substitutes an estimate for a measurement.
Architecture
| Component | Runs as | Role |
|---|---|---|
FrameLedger.exe |
Standard user | Fluent desktop UI (WPF + WPF UI), charts, library, settings |
FrameLedger.Agent.exe |
Standard user (elevation optional) | Injection control, safety guard, data collection, GPU telemetry, storage |
FrameLedger.Overlay.dll |
Inside the game | C++20 hooks + lock-free shared-memory writer. Records only; never analyzes, allocates, or blocks |
FrameLedger.VkLayer.dll |
Inside the game | Vulkan implicit layer (Vulkan titles use this instead of injection) |
Elevation is optional for Tier-1 hooked capture — that is the normal path and it runs as a standard user. It unlocks CPU temperature sensors, attaching to games that themselves run elevated, and the Tier-2 ETW fallback. If you expect to rely on Tier 2, run the Agent elevated.
Requirements
- Windows 10 (22H2) or Windows 11, 64-bit
- A 64-bit DirectX 11/12, Vulkan, or OpenGL game for full (Tier-1) capture. 32-bit games — including most DirectX 9 titles — are supported at Tier 2 only
- Optional: PawnIO for CPU temperature (GPU telemetry works without it, through your graphics driver's own libraries)
Install
- Download the latest
FrameLedger-win-Setup.exefrom Releases. - SmartScreen may warn — releases are not code-signed (free, open-source project). Verify the SHA-256 checksum published with each release, then More info → Run anyway.
- Follow the first-run Legal Gate and Agent setup. Nothing is injected until you enable it for a specific game.
Privacy
Everything lives locally in %LOCALAPPDATA%\FrameLedger. The only network calls: update checks against GitHub Releases, detection-rules updates from this repository, and optional, opt-in store metadata lookups. Bug reports are always built locally, shown to you, and submitted by you. Full policy: legal/PRIVACY_POLICY.md.
License
GPL-3.0-only. See LICENSE. Third-party components: legal/THIRD_PARTY_NOTICES.md.
GPU telemetry is layered so the project never depends on a proprietary vendor licence: a vendor-neutral DXGI/performance-counter baseline, LibreHardwareMonitor (MPL-2.0) for sensors on all vendors, and NVIDIA's NVAPI SDK (MIT) for NVIDIA-only extras such as Reflex latency. No Intel or AMD GPU SDK is bundled — see docs/18_GPU_VENDOR_APIS.md for why.
Documentation
Developer/AI-facing docs in docs/. Start with CLAUDE.md, then docs/19_SAFETY_AND_ANTICHEAT.md (which constrains everything else), then docs/01_ARCHITECTURE.md.
Reporting a safety gap
If you find a game with anti-cheat that FrameLedger fails to detect, please open an issue — that is a safety bug and is treated with the same priority as a security report. Blocklist entries ship as data and can be updated without a new release.
Status: pre-alpha, under active development. Roadmap: docs/15_ROADMAP.md.