Development

Source layoutCopy Anchor Link

Start with Project layout to find the owning module. Most runtime changes belong in src/app, src/overlay, src/renderer, src/menu, or src/vpk. Keep shared packet types in src/overlay/game_reader.hpp and keep their packed size assertions synchronized with the C++ harness.

Build loopCopy Anchor Link

Configure and compile the main application:

cmake -B build -S .
make -j"$(nproc)" -C build

The Build helper wraps this workflow and can run tests or launch after building.

Enable the C++ unit-test target when you change math, parsing, configuration, input, or packet handling:

cmake -B build -S . -DCHUDCS2_BUILD_TESTS=ON
make -j"$(nproc)" -C build
ctest --test-dir build --output-on-failure

The live overlay and tests have different privilege needs. Unit tests that only exercise parsing or math do not need root, while live memory reads and /dev/uinput access may.

Adding a featureCopy Anchor Link

1. Add the feature state to OverlayConfig only when it needs persistence.
2. Add serialization and default values through the existing config field mechanism.
3. Keep frame input and frame state boundaries explicit in src/app/FrameInput.hpp and src/app/FrameState.hpp.
4. Add the feature's UI in the matching menu tab and hide dependent controls when its master switch is disabled.
5. Use VirtualInput for simulated input and respect focus gating.
6. Add a C++ regression case only for non-obvious behavior that needs one. Follow the opt-in policy in Testing.

Packet changesCopy Anchor Link

When changing ShmPacket, PlayerData, or another packed structure, update all of these together:

• C++ definitions in src/overlay/game_reader.hpp.
• C++ static_assert size checks in tests/cpp/test_main.cpp.
• Producers and consumers of the changed fields.

See Packet layout for the layout rules.

Repository workflowCopy Anchor Link

The project keeps architecture and build notes in .claude/. Existing changes in the worktree may be unrelated to your task, so inspect git status before editing. After source changes, update the local code graph with graphify update . when graphify is available.

Documentation siteCopy Anchor Link

The site lives in docs/ and requires Bun 1.3 or newer. From the repository root:

cd docs
bun install
bun dev

Create pages in content/docs with title and description frontmatter. Add each page to its folder's meta.json so it appears in the sidebar. Use absolute internal links beginning with /docs and keep navigation in content/docs/index.mdx and llms.txt current.

Run these checks from docs/, one at a time:

bun run check
bun run typecheck
bun test
bun run build

The build checks internal links and compiles MDX. typecheck regenerates Fumadocs collections and Next.js route declarations before running TypeScript with strict enabled.

Run and edit the docsCopy Anchor Link

This deployment is temporary. The documentation app lives in docs/ in the repository. From the repository root, run:

cd docs
bun install
bun dev

Use the local URL printed by the server. To edit the launch guide, open docs/content/docs/quick-start.mdx in your editor. For example, add this section below its frontmatter:

## Before launching

Start Counter-Strike 2 and load a map before starting the overlay.

Save the file and check the result at /docs/quick-start on the local server. Keep the existing title and description frontmatter. Existing pages already have sidebar entries. For a new page, also add its filename without .mdx to the folder's meta.json.

Before sharing the change, run bun run check, bun run typecheck, bun test and bun run build from docs/.

Editor supportCopy Anchor Link

Open docs/ as a workspace folder for site work. In VS Code, select TypeScript: Select TypeScript Version, then Use Workspace Version. This loads the installed compiler and Next.js TypeScript plugin. Install an MDX language extension for page syntax and component completion.

Run bun run typecheck after installing dependencies or changing the content schema. Generated .source modules provide collection types for collections/* imports. Keep @/* imports aligned with src/* in tsconfig.json. Do not edit generated route types, .source or next-env.d.ts.

For TypeScript examples, add twoslash to a ts or tsx fence when hover types help explain the API. The existing compiler validates these examples during the site build. Shell, JSON and C++ examples should use their own language fences.