# Development (/docs/guides/development)

Build, inspect and extend CHUDCS2 without losing the runtime boundaries.

## Source layout [#source-layout]

Start with [Project layout](/docs/reference/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 loop [#build-loop]

Configure and compile the main application:

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

The [Build helper](/docs/reference/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:

```bash
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 feature [#adding-a-feature]

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](/docs/guides/testing).

## Packet changes [#packet-changes]

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](/docs/reference/shared-memory) for the layout rules.

## Repository workflow [#repository-workflow]

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 site [#documentation-site]

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

```bash
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:

```bash
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 docs [#run-and-edit-the-docs]

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

```bash
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:

```mdx
## 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 support [#editor-support]

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.