Files
frameledger/CONTRIBUTING.md
T
poli0981andClaude Opus 5.5 2ce8251d31 feat: the game's own memory, measured from outside the game in every session - a C++ reader of the GPU Process Memory counters and GetProcessMemoryInfo, median and mean, schema 0018 (D43, beta.12 PR-2) (#254)
- 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>
2026-10-03 23:21:45 +07:00

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 and docs/19_SAFETY_AND_ANTICHEAT.md first. 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 format and clang-format are 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, vi and ja (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] in CHANGELOG.md;
  • every new source file carries the licence header — ./tools/notice-check.ps1 -Fix writes 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.md lists (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.