diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..157d93df --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,58 @@ +# AGENTS.md + +Guidance for AI coding assistants working in this repository. +This file is the entry point — read it first. Topic-specific +detail lives under [`Skills/`](Skills/) and is linked from the relevant section below. + +## What this project is + +Fling Engine is a cross-platform Vulkan game engine in C++, currently built as one +CMake project with a `FlingEngine` library, a `Sandbox` game/editor, and a `FlingTests` +Catch2 test target. See the root [README.md](README.md) for the project pitch and +platform setup (Vulkan SDK, GLFW, etc.). + +## Build + +- First time in a fresh clone: `./Init.sh` (Linux) / `Init.bat` (Windows). This pulls + git submodules, builds/installs Catch2 locally, and configures CMake into `build/`. +- Day to day: `./build-debug.sh`, `./build-release.sh`, or `./build-shipping.sh`, then + build with your generator (e.g. `cmake --build build --parallel`). +- `-DDEFINE_SHIPPING=ON` strips dev-only code gated behind `#ifdef FLING_SHIPPING`. +- Full detail: [`Skills/building.md`](Skills/building.md). + +## Tests + +- Tests use Catch2 3, target `FlingTests`, source under `FlingTests/src`. +- Run the built binary directly, e.g. `./build/FlingTests/bin/FlingTests` on Linux + (see `.github/workflows/build.yml` for the exact per-platform paths). +- Full detail, including how to add a new test file: [`Skills/testing.md`](Skills/testing.md). + +## Coding style + +- Canonical style doc: [`docs/CodingStyle.md`](docs/CodingStyle.md) — documentation + comment conventions (no `@brief`, no `/*!`), enforced by + `python3 scripts/check_comment_style.py`. +- Layout/formatting is enforced by `.clang-format` at the repo root (run + `clang-format`, not manual formatting judgment). +- Applies to first-party code only (`FlingEngine/`, `Sandbox/`, `FlingTests/`). + **Never edit code under `external/`** — it's vendored third-party code. +- AI-assistant-focused summary and common pitfalls: [`Skills/coding-style.md`](Skills/coding-style.md). + +## Architecture / module layout + +- Current folder layout and the in-progress module split (Core, Graphics, Gameplay, + Resources, Editor) are documented in [`docs/BuildModules.md`](docs/BuildModules.md) — + read it before restructuring includes or CMake targets, it records locked decisions. +- Orientation for where things live today: [`Skills/architecture.md`](Skills/architecture.md). + +## Contribution conventions + +- Branching: feature branches off `main`, PR back into `main` when done and tested. +- CI (`.github/workflows/build.yml`) builds on Linux (GCC/Clang) and Windows + (MSVC/MinGW) and runs `FlingTests` plus the comment-style check on every PR — + make sure changes pass locally first. + +## For Claude Code specifically + +`CLAUDE.md` at the repo root imports this file directly (`@AGENTS.md`), so there is +nothing Claude-specific to duplicate here. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..51b0448c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +See @AGENTS.md for project guidance (build, tests, coding style, architecture). diff --git a/FlingEngine/Resources/inc/JsonArchive.h b/FlingEngine/Resources/inc/JsonArchive.h index f94c5442..e38b8396 100644 --- a/FlingEngine/Resources/inc/JsonArchive.h +++ b/FlingEngine/Resources/inc/JsonArchive.h @@ -15,6 +15,9 @@ namespace Fling T& Value; }; + /** + * Makes a Name Value Pair (NVP) which can be used to serialize as a JSON key/value. + */ template NamedRef MakeNVP(const char* name, T& value) { diff --git a/README.md b/README.md index 7e968e69..ad324983 100644 --- a/README.md +++ b/README.md @@ -69,15 +69,15 @@ Notice the `-DDEFINE_SHIPPING` option is set to `ON`. This sets a definiton that #endif ``` -### Wanna contribute? - -If you have any contributions or fixes that you want to contribute, then feel free to open -an issue or a pull request! I'm happy to talk about the project, so feel free to reach out -to me on [Twitter](https://twitter.com/BenjaFriend?lang=en) or here on GitHub. - See [docs/CodingStyle.md](docs/CodingStyle.md) for documentation-comment conventions and how to run the comment-style check / clang-format. +## AI coding assistants + +If you're using Claude Code, Cursor, Copilot, or another AI coding assistant on this +project, start at [AGENTS.md](AGENTS.md) — it covers build/test commands, coding +style, and architecture, and links into [Skills/](Skills/) for topic-specific detail. + ## Branching Strategy We use a pretty basic branching strategy. Make a feature branch off of `Main` for something like "add-support-for-x", and then that feature is done and tested create a pull request to get it into Main. diff --git a/Skills/README.md b/Skills/README.md new file mode 100644 index 00000000..0360870f --- /dev/null +++ b/Skills/README.md @@ -0,0 +1,16 @@ +# Skills + +Topic-specific guidance for AI coding assistants working in Fling Engine. Start at +[`AGENTS.md`](../AGENTS.md) in the repo root — it links into the files here for +detail on a given topic. These files are meant to be read on demand, not all at once. + +| File | Covers | +|------|--------| +| [`building.md`](building.md) | Init scripts, build modes, CMake flags, per-platform setup | +| [`testing.md`](testing.md) | Running FlingTests, adding new Catch2 tests | +| [`coding-style.md`](coding-style.md) | Doc-comment conventions, formatting, what not to touch | +| [`architecture.md`](architecture.md) | Current folder/module layout, where new code belongs | + +These are supplementary to, not a replacement for, the canonical docs they +reference (`docs/CodingStyle.md`, `docs/BuildModules.md`) — when in doubt, the +canonical doc wins. diff --git a/Skills/architecture.md b/Skills/architecture.md new file mode 100644 index 00000000..4041e116 --- /dev/null +++ b/Skills/architecture.md @@ -0,0 +1,41 @@ +# Architecture / where things live + +This is orientation for today's layout, not a design doc. For the in-progress +module split (Core/Resources/Gameplay/Graphics/Editor as separate CMake targets) +and its locked decisions, read [`docs/BuildModules.md`](../docs/BuildModules.md) +before touching CMake targets, `FLING_ENGINE_INC()`, or cross-folder includes — +several things that look like cleanups are explicitly deferred or ruled out there. + +## Today + +- `FlingEngine/` — the engine, currently one CMake library (`FlingEngine`) built + from almost every source file under this tree via glob. Subfolders already hint + at future module boundaries (`Core`, `Graphics`, `Gameplay`, `Resources`, `Utils`, + `Platform`, `Editor`, `Foundation`) but CMake/includes still treat it as one target + — `FLING_ENGINE_INC()` adds every engine `inc/` dir to consumers, so folder + location doesn't currently enforce isolation. +- `Sandbox/` — the sample game + editor, one executable today (editor support is + toggled by a project-wide `WITH_EDITOR` define, which `docs/BuildModules.md` + plans to remove in favor of two separate executables). +- `FlingTests/` — Catch2 tests, links the full `FlingEngine` library. See + [`testing.md`](testing.md). +- `external/` — vendored third-party dependencies (submodules). Never modified. +- `docs/` — human-facing docs; `docs/CodingStyle.md` and `docs/BuildModules.md` + are the two that matter for day-to-day work. (Most other files in `docs/` are + generated Doxygen HTML output, not hand-maintained.) +- `scripts/` — repo tooling (`check_comment_style.py`, the one-time + `migrate_doxygen_comments.py` migration). +- `CMake/` — CMake helper modules (e.g. `FlingEngineInc.cmake`). + +## Rules that hold regardless of the module-split's progress + +- Gameplay code (`Transform`, `Camera`, `World`, `Game`) must not include Graphics + headers (`MeshRenderer.h`, Vulkan-facing types). Graphics may include Gameplay. +- Editor is a leaf: `Engine` and `Graphics` must not include `BaseEditor` or any + Editor header. If you find yourself adding such an include, that's the bug + `docs/BuildModules.md` calls out explicitly — look for the debug-UI hook pattern + it describes instead. +- Don't add a new module folder or CMake target without reading the "Locked + decisions" section of `docs/BuildModules.md` first — several plausible-looking + approaches (per-module PCH, merging Foundation into something else, git + submodules per system) are explicitly rejected there. diff --git a/Skills/building.md b/Skills/building.md new file mode 100644 index 00000000..73e27b7e --- /dev/null +++ b/Skills/building.md @@ -0,0 +1,60 @@ +# Building Fling Engine + +## First-time setup + +Run once per fresh clone (or after `external/` submodule updates): + +```bash +./Init.sh # Linux/macOS +Init.bat # Windows +``` + +This does three things: + +1. `git submodule update --init --recursive` — pulls all vendored deps under `external/`. +2. Builds and installs Catch2 locally to `external/Catch2/install` (no `sudo` needed; + `find_package(Catch2 3 REQUIRED)` in `FlingTests/CMakeLists.txt` needs this). +3. Configures CMake into `build/` with default settings. + +Linux also needs system packages before this will configure cleanly (GLFW, Vulkan +headers, X11/Wayland dev libs) — see the root [README.md](../README.md) for the +`apt-get` list, or `.github/workflows/build.yml` for the CI package list. + +## Day-to-day builds + +Three convenience scripts reconfigure CMake for a given mode (they do **not** +build — build separately): + +```bash +./build-debug.sh # -DCMAKE_BUILD_TYPE=Debug +./build-release.sh # -DCMAKE_BUILD_TYPE=Release +./build-shipping.sh # -DCMAKE_BUILD_TYPE=Release -DDEFINE_SHIPPING=ON +``` + +Then build with your generator, e.g.: + +```bash +cmake --build build --parallel +``` + +## `DEFINE_SHIPPING` + +`-DDEFINE_SHIPPING=ON` sets `FLING_SHIPPING`, used in first-party code to strip +dev-only paths: + +```cpp +#ifdef FLING_SHIPPING +// shipping-only behavior +#else +// dev behavior, verbose logging, etc. +#endif +``` + +It also switches Asset paths from absolute (convenient for iterating without +reconfiguring) to relative, so a shipped executable is portable. + +## CI reference + +`.github/workflows/build.yml` is the ground truth for exactly what gets built and +with which flags across Linux GCC, Linux Clang, Windows MSVC (Debug + Release), and +Windows MinGW64 — check it if a build works locally but fails in CI, or vice versa. diff --git a/Skills/coding-style.md b/Skills/coding-style.md new file mode 100644 index 00000000..da461fea --- /dev/null +++ b/Skills/coding-style.md @@ -0,0 +1,56 @@ +# Coding Style + +The canonical reference is [`docs/CodingStyle.md`](../docs/CodingStyle.md) — read +that first. This file is a quick-reference summary plus the pitfalls an AI assistant +is most likely to hit. + +Scope: first-party code only — `FlingEngine/`, `Sandbox/`, `FlingTests/`. +**Never reformat, refactor, or "clean up" anything under `external/`** — it's +vendored third-party code and is left alone, full stop. + +## Documentation comments + +- Modern Doxygen-style blocks, plain description first, no `@brief` line. +- Never use `/*!` — always `/**`. +- Only add `@param` / `@return` / `@see` when they say something the signature + doesn't already make obvious. Don't generate `@return float GetTimef`-style noise. + +```cpp +/** + * Holds onto the command line arguments passed to this application. + * + * @param Argc Number of arguments + * @param ArgV Argument values + * @return True if successfully initialized + */ +bool Init(const int32 Argc, const char* ArgV[]); +``` + +Trivial members/accessors can use a one-line `/** ... */`. + +## Enforcement — check before considering work done + +- **Comment content**: `python3 scripts/check_comment_style.py` — rejects leftover + `@brief` / `/*!` in first-party sources. Run this after adding or editing any + doc comment. +- **Layout/formatting**: `.clang-format` at the repo root. Run `clang-format` + rather than hand-formatting: + + ```bash + find FlingEngine Sandbox FlingTests -type f \( -name '*.h' -o -name '*.hpp' -o -name '*.cpp' \) \ + | xargs clang-format -i + ``` + + clang-format handles layout only — it does not check comment *content*, that's + what `check_comment_style.py` is for. Both checks run in CI + (`.github/workflows/build.yml`, `comment-style` job runs the Python script; + formatting is expected to already be clean going in). + +## Naming / conventions to preserve + +- Flat include names (`#include "Logger.h"`, not `#include "Core/Logger.h"`) are + intentional, even across the module split described in + [`docs/BuildModules.md`](../docs/BuildModules.md). Don't "fix" these to + path-qualified includes. +- `pch.h` is being deleted per the module-split plan — don't add new `#include "pch.h"` + to public headers, and don't rely on it as a kitchen-sink include. diff --git a/Skills/testing.md b/Skills/testing.md new file mode 100644 index 00000000..a682e253 --- /dev/null +++ b/Skills/testing.md @@ -0,0 +1,44 @@ +# Testing + +Fling Engine uses [Catch2 3](https://github.com/catchorg/Catch2) for first-party +tests. The test target is `FlingTests`, built from `FlingTests/src`, and links the +full `FlingEngine` library (plus `Foundation`), so tests can exercise real engine +code, not just isolated units. + +## Running tests + +Build the `FlingTests` target as part of a normal build, then run the resulting +binary directly: + +```bash +# Linux +./build/FlingTests/bin/FlingTests + +# Windows (path includes the build config) +build\FlingTests\bin\\FlingTests.exe +``` + +Catch2's CLI flags work as usual, e.g. `./build/FlingTests/bin/FlingTests "[tag]"` +to filter, or `--list-tests` to see everything. + +`Logs/` should exist before running (CI does `mkdir -p Logs` first) — the engine +writes runtime logs there. + +## Adding a new test + +- Add a new `.cpp` under `FlingTests/src` (see existing files like + `ResourceTests.cpp`, `UtilsTests.cpp`, `RendererTests.cpp` for structure/naming). + `FlingTests/CMakeLists.txt` globs sources, so a new file is picked up automatically — + no CMake edit needed for a new test file, just re-run CMake configure if it doesn't + show up. +- Use Catch2's `TEST_CASE` / `SECTION` macros; follow the coding-style rules in + [`coding-style.md`](coding-style.md) for any doc comments you add. +- Prefer testing first-party engine code (`FlingEngine/`). Do not add tests that + exercise `external/` internals directly. + +## CI + +Every PR runs `FlingTests` on Linux (GCC + Clang) and Windows (MSVC Debug/Release + +MinGW64) via `.github/workflows/build.yml`. A test that only passes on one platform +is not done — check for platform-specific assumptions (path separators, endianness, +float precision) before considering a new test finished.