- FrameLedger.ProcessStats.dll (C++20, loaded by the Agent, never into a game): the game process's dedicated and shared
GPU memory from the documented `GPU Process Memory` performance counters (no handle to the game, every instance of the
pid summed) and its private working set / working set / commit from GetProcessMemoryInfo (EX2, falling back to EX)
through PROCESS_QUERY_LIMITED_INFORMATION only (a sentinel refuses an EX2 answer whose private working set was not
filled). Not D3DKMTQueryStatistics ("Reserved for system use").
ctest fl_process_stats (GPU_INSTANCE on a hardware adapter, NO_GPU_INSTANCE on CI) and fl-probe-processstats.
- Measured first, decision table in spike-notes §16 written before the runs: +512.0 MiB for a 512 MiB buffer,
private working set equal to Windows' own counter, 0.1 ms per read, nothing leaked over 600 reads; dedicated reads a
constant 4.5 MiB above DXGI's local usage, so it is never compared with a budget.
- NativeProcessStats (third facade), GameMemoryReader: a pinned session reads through its held handle; an unpinned
Tier-2 hold opens each process of the executable for the read, refuses a reused pid, sums. CaptureSession tells the
observer which process (ICaptureObserver.Measuring), the recorder forwards it to the poller (ITelemetryPoller.Follow).
- TelemetrySample.Game; five sensor series; schema 0018 (game_vram_dedicated_*, game_ram_private_*, ..., sensor_stats_json);
SeriesAggregates gains Median and Min; a wide .partial sensors chunk (type 8) with type 4 still read; SessionProgress
and SessionHeld carry the game's memory live.
- notice-check accepts a contributor's own copyright line in the same form.
- Tests: the two classes that open a LibreHardwareMonitor Computer run one at a time - GenericCpu.Update threw a
NullReferenceException in the local gate when they ran in parallel (the Agent's own read is already contained).
- Docs corrected in place: 03_METRICS, 18_GPU_VENDOR_APIS, 17_HOOK_ENGINE, 20_OPEN_QUESTIONS (§M7, §H10, new §M11),
04_CAPTURE, 19_SAFETY, 06_DATA_MODEL, 07_IPC, 02_SPEC, 01_ARCHITECTURE, 12_BUILD, CLAUDE.md; the accuracy block and
LIMITATIONS.md.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
3.9 KiB
Contributing to FrameLedger
Thank you for looking. FrameLedger is a small project with strict rules, because it loads code into games and a mistake can cost a user their account. This page says how to build it, what a change has to bring with it, what will not be merged, and under what licence your contribution is accepted.
Before you start
- Read
CLAUDE.md's Non-negotiable rules anddocs/19_SAFETY_AND_ANTICHEAT.mdfirst. They constrain everything that touches a game. - Open an issue before anything larger than a fix, so the approach can be agreed before the work is done.
- A game with anti-cheat that FrameLedger fails to detect is a safety bug: use the Safety gap issue form.
- A vulnerability in FrameLedger itself goes the private route in
SECURITY.md, never a public issue. - Everyone who takes part follows the
CODE_OF_CONDUCT.md.
Building
You need Windows 10 22H2 or later (x64), Visual Studio 2022 with the C++ workload (MSVC v143), CMake 3.28 or later,
PowerShell 7, and the .NET SDK that global.json pins. Then:
./build.ps1 check
That is the whole quality gate, and continuous integration runs the identical script: the native build and its tests,
clang-format, the managed build with warnings as errors, dotnet format, every test project, and the repository's own
checks (licences, the accuracy blocks, the licence headers, the changelog rules, …). docs/12_BUILD.md describes each
step and the build profiles. Run it in your main checkout: a fresh git worktree cannot configure the native build.
What a pull request brings with it
The definition of done is the one in CLAUDE.md:
- it builds without warnings (C# and C++), the tests are green, and
dotnet formatandclang-formatare clean; - a change to the hook path states its measured overhead in the PR (
docs/14_TESTING.md§Hook overhead); - a new hook is listed in
docs/17_HOOK_ENGINE.md§Hook inventory and justified against rule 4; - every new user-visible string exists in
en,viandja(docs/09_I18N.md); - a change that makes a document wrong updates that document in the same PR;
- a change under
src/adds an entry under## [Unreleased]inCHANGELOG.md; - every new source file carries the licence header —
./tools/notice-check.ps1 -Fixwrites it. A file you wrote yourself may name you in its second line instead, in the same form:Copyright (C) <year> <your name> - additional terms under GPLv3 section 7: see NOTICE.
The pull-request template lists the safety checks for changes to the capture layer.
What will not be merged
Whatever its other merits, a change that
- adds any way to override, weaken or skip the anti-cheat guard (rule 2);
- makes FrameLedger harder to detect — manual mapping, header erasure, thread hiding, unlinking modules, obfuscation, renamed binaries (rules 3 and 9);
- reads or writes game memory outside the hooked calls (rule 4), or makes a hook able to crash a game (rule 5);
- adds telemetry, analytics or any network request beyond the ones
legal/PRIVACY_POLICY.mdlists (rule 8); - turns injection on for a game the user did not individually enable (rule 1).
Licensing of contributions
FrameLedger is licensed under the GNU GPL, version 3 only, with the additional terms in NOTICE. By opening a pull
request you confirm that you have the right to submit the change, and you license it under GPL-3.0-only, with the
additional terms in NOTICE (GPLv3 §7 (b), (c) and (e)) applying to it as they apply to the rest of FrameLedger's own
material. There is no contributor licence agreement and no copyright assignment: you keep the copyright in your
contribution. Code from elsewhere must come with a licence compatible with GPL-3.0-only and be listed in
legal/THIRD_PARTY_NOTICES.md.
Changes written with AI assistance are welcome on the same terms — you are responsible for what you submit, as for any other change.
Questions
Open an issue, or write to contact@poli0981.dev.