Add claude docs
This commit is contained in:
@@ -1,4 +1,73 @@
|
||||
# Dusk — Claude Code rules
|
||||
# Dusk -- Claude Code rules
|
||||
|
||||
## About Dusk
|
||||
|
||||
Dusk is a pure C game and game engine. There is no C++ anywhere in the
|
||||
codebase. The engine is built around a data-oriented Entity Component
|
||||
System (ECS) and is designed for heavy optimization across a wide range
|
||||
of hardware targets, including platforms with very limited RAM and CPU.
|
||||
|
||||
**Current and planned platforms:** Linux, Windows, macOS, Sony PSP,
|
||||
PlayStation Vita, Nintendo GameCube, Nintendo Wii. Additional platforms
|
||||
will be added over time. GameCube and Wii are collectively referred to
|
||||
as the **Dolphin** targets throughout the codebase and docs.
|
||||
|
||||
**Build system:** CMake exclusively. Every source subdirectory owns its
|
||||
own `CMakeLists.txt`.
|
||||
|
||||
**Architecture:** Entity Component System (ECS) as the primary pattern.
|
||||
All game objects are entities; behaviour and state are attached via
|
||||
components. No inheritance hierarchies -- favour composition.
|
||||
|
||||
**Optimization:** Performance is a first-class constraint, not an
|
||||
afterthought. The engine must run well on hardware as constrained as
|
||||
the GameCube (16 MB main RAM, 485 MHz PowerPC) and PSP (32 MB RAM,
|
||||
333 MHz MIPS). Every design and implementation decision should consider
|
||||
the most constrained target.
|
||||
|
||||
**Coding style:** All C code must strictly follow the project style
|
||||
rules documented in the [Coding style](#coding-style) section below.
|
||||
Deviations are not acceptable.
|
||||
|
||||
### Further reading
|
||||
|
||||
Detailed documentation on specific topics lives in `.claude/`:
|
||||
|
||||
| Topic | File |
|
||||
|-------|------|
|
||||
| Platform overview, capability macros, quick comparison | `.claude/platforms.md` |
|
||||
| Platform -- Linux and Knulli | `.claude/platform-linux.md` |
|
||||
| Platform -- Sony PSP | `.claude/platform-psp.md` |
|
||||
| Platform -- PlayStation Vita | `.claude/platform-vita.md` |
|
||||
| Platform -- GameCube and Wii (Dolphin) | `.claude/platform-dolphin.md` |
|
||||
| Platform -- Windows (planned) | `.claude/platform-windows.md` |
|
||||
| Platform -- macOS (planned) | `.claude/platform-macos.md` |
|
||||
| ECS architecture and conventions | `.claude/ecs.md` |
|
||||
| CMake build system and toolchain setup | `.claude/build.md` |
|
||||
| Optimization guidelines and platform budgets | `.claude/optimization.md` |
|
||||
| Test infrastructure and assertion macros | `.claude/tests.md` |
|
||||
| Error handling system (`errorret_t`, macros) | `.claude/errors.md` |
|
||||
| Asset system (loading, caching, loaders) | `.claude/assets.md` |
|
||||
| Threading (`thread_t`, mutex, thread-local) | `.claude/threading.md` |
|
||||
| Input system (actions, buttons, platforms) | `.claude/input.md` |
|
||||
| Physics simulation and collision shapes | `.claude/physics.md` |
|
||||
| Event system (pub/sub) | `.claude/events.md` |
|
||||
| Locale / localisation system | `.claude/locale.md` |
|
||||
| Time system (fixed/dynamic, epoch) | `.claude/time.md` |
|
||||
| Network system (per-platform status) | `.claude/network.md` |
|
||||
| Utility library (memory, string, math, endian, ref) | `.claude/util.md` |
|
||||
| Script system (JerryScript, module proto API) | `.claude/script.md` |
|
||||
| Script async promises (`scriptpromisepend_t`) | `.claude/script-promises.md` |
|
||||
| Engine main loop, system platform API, log | `.claude/engine.md` |
|
||||
| Save system (multi-slot, platform storage) | `.claude/save.md` |
|
||||
| Animation (keyframes, easing functions) | `.claude/animation.md` |
|
||||
| Display (index) | `.claude/display.md` |
|
||||
| Display -- screen, framebuffer, size modes | `.claude/display-core.md` |
|
||||
| Display -- texture, tileset, font | `.claude/display-texture.md` |
|
||||
| Display -- shader, material, display state | `.claude/display-shader.md` |
|
||||
| Scene system (lifecycle, render pipeline, JS hooks) | `.claude/scene.md` |
|
||||
|
||||
---
|
||||
|
||||
## File headers
|
||||
Every C, H, and JS file starts with:
|
||||
@@ -101,6 +170,10 @@ assertIsMainThread("msg");
|
||||
---
|
||||
|
||||
## Build system
|
||||
|
||||
See `.claude/build.md` for extended CMake conventions, platform
|
||||
toolchain setup, and adding platform-conditional sources.
|
||||
|
||||
Each subdirectory has its own `CMakeLists.txt` that adds sources with:
|
||||
|
||||
```cmake
|
||||
@@ -116,6 +189,10 @@ Never add source files to the root `CMakeLists.txt` directly.
|
||||
|
||||
## Platform support
|
||||
|
||||
See `.claude/platforms.md` for the full platform table (including
|
||||
planned Windows / macOS targets), capability macros, toolchain setup,
|
||||
and endianness notes.
|
||||
|
||||
### Targets
|
||||
Set `DUSK_TARGET_SYSTEM` at CMake configure time to select a platform:
|
||||
|
||||
@@ -175,19 +252,11 @@ simply left undefined — the core guards calls with `#ifdef`.
|
||||
|
||||
---
|
||||
|
||||
## Adding a new asset loader type
|
||||
1. Add an enum value to `assetloadertype_t` (before `_COUNT`) in
|
||||
`src/dusk/asset/loader/assetloader.h`.
|
||||
2. Add fields to the input/loading/output unions in `assetloader.h`.
|
||||
3. Implement `assetXxxLoaderSync`, `assetXxxLoaderAsync`, and
|
||||
`assetXxxDispose` in a new `src/dusk/asset/loader/xxx/` directory.
|
||||
4. Register the three callbacks in `ASSET_LOADER_CALLBACKS[]` in
|
||||
`src/dusk/asset/loader/assetloader.c`.
|
||||
5. If user-facing, create a JS module (see below) and a `.d.ts` file.
|
||||
|
||||
---
|
||||
|
||||
## Adding a new entity component
|
||||
|
||||
See `.claude/ecs.md` for ECS design rules, component categories, and
|
||||
entity lifecycle details.
|
||||
|
||||
1. Create `src/dusk/entity/component/<category>/entityMyComp.h/.c` with
|
||||
struct `entityMyComp_t`, `entityMyCompInit()`, and optionally
|
||||
`entityMyCompDispose()`.
|
||||
@@ -201,6 +270,18 @@ simply left undefined — the core guards calls with `#ifdef`.
|
||||
|
||||
---
|
||||
|
||||
## Adding a new asset loader type
|
||||
1. Add an enum value to `assetloadertype_t` (before `_COUNT`) in
|
||||
`src/dusk/asset/loader/assetloader.h`.
|
||||
2. Add fields to the input/loading/output unions in `assetloader.h`.
|
||||
3. Implement `assetXxxLoaderSync`, `assetXxxLoaderAsync`, and
|
||||
`assetXxxDispose` in a new `src/dusk/asset/loader/xxx/` directory.
|
||||
4. Register the three callbacks in `ASSET_LOADER_CALLBACKS[]` in
|
||||
`src/dusk/asset/loader/assetloader.c`.
|
||||
5. If user-facing, create a JS module (see below) and a `.d.ts` file.
|
||||
|
||||
---
|
||||
|
||||
## Adding a new script (JS) module
|
||||
1. Create `src/dusk/script/module/<category>/moduleMyMod.h/.c`.
|
||||
- Declare `extern scriptproto_t MODULE_MYMOD_PROTO;` in the header.
|
||||
|
||||
Reference in New Issue
Block a user