YourWishes/dusk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

merge into: YourWishes/dusk:segment
Branches Tags
YourWishes/dusk:main YourWishes/dusk:segment YourWishes/dusk:scriptentity YourWishes/dusk:tools
..
pull from: YourWishes/dusk:main
Branches Tags
YourWishes/dusk:segment YourWishes/dusk:main YourWishes/dusk:scriptentity YourWishes/dusk:tools

4 Commits
segment .. main

Author SHA1 Message Date
YourWishes 857c6b3d47 Fuck 2026-06-16 09:18:13 -05:00
YourWishes e1498f538d Optimize chunk tile mesh 2026-06-11 14:45:53 -05:00
YourWishes aa246eff94 RPG stuff 2026-06-11 12:18:13 -05:00
YourWishes 5be21a21d5 prog 2026-06-10 19:06:19 -05:00
262 changed files with 2526 additions and 17376 deletions
Expand all files Collapse all files
.claude/animation.md
-88
View File
@@ -1,88 +0,0 @@
# Animation System
Source: `src/dusk/animation/`
## Overview
The animation system provides time-based keyframe interpolation with
pluggable easing functions. It is intentionally minimal -- no skeleton,
no blending, no state machine. Animations produce a single `float_t`
value at a given time, which callers apply to whatever property they
are animating.
## Keyframes (`keyframe.h`)
```c
typedef struct {
float_t time; // time in seconds this keyframe is at
float_t value; // the value at this keyframe
easingtype_t easing; // easing applied between this frame and the next
} keyframe_t;
```
## Animation (`animation.h`)
```c
typedef struct {
keyframe_t *keyframes; // caller-owned array
uint16_t keyframeCount;
} animation_t;
void animationInit(
animation_t *anim,
keyframe_t *keyframes,
uint16_t keyframeCount
);
float_t animationGetValue(animation_t *anim, float_t time);
// Returns the interpolated value at the given time.
// Before the first keyframe: returns the first keyframe's value.
// After the last keyframe: returns the last keyframe's value.
```
## Easing functions (`easing.h`)
```c
typedef float_t (*easingfn_t)(float_t t); // t in [0, 1], out in [0, 1]
extern const easingfn_t EASING_FUNCTIONS[EASING_COUNT];
float_t easingApply(easingtype_t type, float_t t);
```
Available easing types:
```
EASING_LINEAR
EASING_IN_SINE EASING_OUT_SINE EASING_IN_OUT_SINE
EASING_IN_QUAD EASING_OUT_QUAD EASING_IN_OUT_QUAD
EASING_IN_CUBIC EASING_OUT_CUBIC EASING_IN_OUT_CUBIC
EASING_IN_QUART EASING_OUT_QUART EASING_IN_OUT_QUART
EASING_IN_BACK EASING_OUT_BACK EASING_IN_OUT_BACK
```
## Usage pattern
```c
// Declare keyframes statically (no allocation):
static keyframe_t kfs[] = {
{ .time = 0.0f, .value = 0.0f, .easing = EASING_OUT_CUBIC },
{ .time = 1.0f, .value = 1.0f, .easing = EASING_LINEAR },
};
animation_t anim;
animationInit(&anim, kfs, 2);
// In update loop:
float_t alpha = animationGetValue(&anim, TIME.time);
// Apply alpha to whatever is being animated.
```
## Design notes
- Keyframe arrays are caller-owned and not copied. Use static or
long-lived arrays; do not allocate per-frame.
- The system has no notion of looping -- wrap `time` with `fmodf` if
you need a repeating animation.
- For multi-property animations, use multiple `animation_t` instances
sharing the same time source.
.claude/assets.md
-125
View File
@@ -1,125 +0,0 @@
# Asset System
Source: `src/dusk/asset/`
## Overview
All game assets are packed into a single ZIP archive named `dusk.dsk`
(`ASSET_FILE_NAME`). The asset system loads entries from this archive
asynchronously on a background thread, caches them, and provides
synchronous blocking access when an asset is required immediately.
## Key limits
| Constant | Value | Meaning |
|----------|-------|---------|
| `ASSET_LOADING_COUNT_MAX` | 4 | Concurrent in-flight loads |
| `ASSET_ENTRY_COUNT_MAX` | 128 | Cached entries |
## Top-level API (`asset.h`)
```c
errorret_t assetInit(); // Open dusk.dsk, start background thread
void assetUpdate(); // Dispatch completed-load callbacks (main thread)
errorret_t assetDispose(); // Wait for loads, close archive
assetentry_t *assetGetEntry(
const char_t *path,
assetloadertype_t type,
assetloaderinput_t *input
); // Get (or create) a cache entry; does NOT start loading
errorret_t assetRequireLoaded(assetentry_t *entry);
// Block the calling thread until this entry is fully loaded.
// Only safe to call from the main thread.
void assetLock(assetentry_t *entry);
void assetUnlock(assetentry_t *entry);
// Reference counting. Lock before using loaded data; unlock when done.
// The entry will not be evicted while locked.
```
## Asset entry states
Each cache entry goes through a state machine:
```
IDLE -> QUEUED -> READING (async) -> PROCESSING (sync, main thread) -> LOADED
-> ERROR
```
- **READING** runs on the background loader thread (file I/O).
- **PROCESSING** runs on the main thread (GPU uploads, parsing finalization).
- Once LOADED, data is available in `entry->data`.
## Loader types
Loader types are registered in the `ASSET_LOADER_CALLBACKS[]` table.
Each type implements three callbacks: `loadSync`, `loadAsync`, `dispose`.
| `assetloadertype_t` | Data read | Description |
|---------------------|-----------|-------------|
| `ASSET_LOADER_TYPE_TEXTURE` | STB image | Loads image bytes async, creates GPU texture sync |
| `ASSET_LOADER_TYPE_TILESET` | `.dtf` binary | Custom tile format (magic, version, grid, UVs) |
| `ASSET_LOADER_TYPE_MESH` | `.stl` | STL mesh with configurable axis orientation |
| `ASSET_LOADER_TYPE_JSON` | yyjson | Up to 256 KB; parsed async |
| `ASSET_LOADER_TYPE_LOCALE` | Gettext `.po` | PO parser with plural-form expression evaluation |
| `ASSET_LOADER_TYPE_SCRIPT` | JS source | JerryScript module |
## Adding a new loader type
1. Add an enum value before `_COUNT` in `assetloadertype_t`
(`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 `src/dusk/asset/loader/xxx/`.
4. Register the three callbacks in `ASSET_LOADER_CALLBACKS[]` in
`src/dusk/asset/loader/assetloader.c`.
5. If user-facing, create a JS module and a `.d.ts` file (see `CLAUDE.md`).
## Asset batch (`assetbatch.h`)
`assetbatch_t` groups multiple asset requests into a single logical
load. All entries in the batch start loading concurrently. The batch
fires a completion callback once every entry has reached LOADED (or
ERROR).
```c
assetbatch_t batch;
assetBatchInit(&batch, entries, count, onComplete, user);
assetBatchStart(&batch);
// ... later, after assetUpdate() fires the callback ...
assetBatchDispose(&batch);
```
## Usage pattern
```c
// 1. Get or create the cache entry (no I/O yet).
assetentry_t *tex = assetGetEntry(
"textures/hero.png",
ASSET_LOADER_TYPE_TEXTURE,
NULL
);
assetLock(tex);
// 2. Option A -- non-blocking: check tex->state each frame.
// Option B -- blocking (main thread only):
errorChain(assetRequireLoaded(tex));
// 3. Use the loaded data.
texture_t *t = &tex->data.texture;
// 4. Release when done.
assetUnlock(tex);
```
## Error macros (inside loader implementations)
```c
assetLoaderErrorThrow("msg %d", val); // errorThrow equivalent
assetLoaderErrorChain(someCall()); // errorChain equivalent
```
Use these instead of the bare error macros inside loader callbacks so
that failures include the loader context in the stack trace.
.claude/build.md
-116
View File
@@ -1,116 +0,0 @@
# Build System
Dusk uses CMake exclusively. Every source subdirectory owns its own
`CMakeLists.txt`; the root file only wires them together.
## Golden rule
**Never add source files to the root `CMakeLists.txt` directly.**
Every `.c` file is registered in the `CMakeLists.txt` that lives in
the same directory (or a direct parent within the same module):
```cmake
target_sources(${DUSK_LIBRARY_TARGET_NAME}
PUBLIC
myfile.c
)
```
## Configuration variables
| Variable | Purpose |
|------------------------|----------------------------------------------|
| `DUSK_TARGET_SYSTEM` | Selects the platform (see `.claude/platforms.md`) |
| `DUSK_BUILD_TESTS` | Enables the test suite (`ON` / `OFF`) |
| `CMAKE_TOOLCHAIN_FILE` | Cross-compiler toolchain for console targets |
| `CMAKE_BUILD_TYPE` | `Debug` / `Release` / `RelWithDebInfo` |
## Typical configure + build
```sh
# Linux debug build
cmake -B build -DDUSK_TARGET_SYSTEM=linux -DCMAKE_BUILD_TYPE=Debug
cmake --build build
# Linux with tests
cmake -B build \
-DDUSK_TARGET_SYSTEM=linux \
-DDUSK_BUILD_TESTS=ON \
-DCMAKE_BUILD_TYPE=Debug
cmake --build build
ctest --test-dir build
```
## Module layout convention
Each logical module under `src/` gets its own directory:
```
src/dusk/ Platform-agnostic core
src/dusk<platform>/ Platform-specific impl (one dir per target)
```
Within a module, subdirectories mirror subsystem boundaries
(`asset/`, `entity/`, `script/`, etc.). Each subdirectory has its own
`CMakeLists.txt` that is `add_subdirectory()`-included by its parent.
## Adding a new source file
1. Create `src/.../myfile.c` (and `myfile.h` if needed).
2. Open the `CMakeLists.txt` in the same directory.
3. Add `myfile.c` to the `target_sources(...)` block.
4. Do **not** touch any parent or root `CMakeLists.txt`.
## Platform-conditional sources
Wrap platform-only files in a generator expression or `if()` block:
```cmake
if(DUSK_TARGET_SYSTEM STREQUAL "psp")
target_sources(${DUSK_LIBRARY_TARGET_NAME}
PUBLIC
mypspfile.c
)
endif()
```
## Embedding JS files (`dusk_embed_js`)
Source: `cmake/modules/duskjs2c.cmake`
The `dusk_embed_js()` CMake function embeds a `.js` source file as a
C string constant in a generated header. It is used to ship script
module code alongside the engine binary without a separate file load.
```cmake
dusk_embed_js(
TARGET ${DUSK_LIBRARY_TARGET_NAME}
JS_FILE path/to/mymodule.js
# NAME is optional; defaults to uppercase stem + "_JS"
# e.g. "mymodule.js" -> "MYMODULE_JS"
NAME MY_CUSTOM_NAME
)
```
The generated header is placed in
`${DUSK_GENERATED_HEADERS_DIR}/<stem>_js.h` and defines:
```c
static const char MY_CUSTOM_NAME[] = "... js source ...";
static const size_t MY_CUSTOM_NAME_SIZE = sizeof(MY_CUSTOM_NAME) - 1;
```
Under the hood it calls `python -m tools.js2c` from the repo root.
The header is generated at build time; include it in the `.c` file
that registers the JS module, then pass `NAME` and `NAME_SIZE` to
`jerry_eval()` (or the equivalent module load helper).
## Tests
- Test files live in `test/` mirroring the `src/dusk/` structure.
- Enable with `-DDUSK_BUILD_TESTS=ON`.
- Uses cmocka; include `dusktest.h` in every test file.
- Every test must assert `memoryGetAllocatedCount() == 0` at teardown
to catch allocator leaks.
- Test function signature: `static void test_something(void **state)`
.claude/console.md
-92
View File
@@ -1,92 +0,0 @@
# Console
Source: `src/dusk/console/`
---
## Overview
The console is a lightweight in-engine debug overlay. It maintains a
fixed-size ring buffer of text lines and can render them to the screen
as an overlay. On Linux (where `DUSK_CONSOLE_POSIX` is defined), it
also reads commands from stdin on a background thread, allowing
interactive input during development without pausing the game loop.
---
## Limits
| Constant | Value |
|----------|-------|
| `CONSOLE_LINE_MAX` | 512 chars per line |
| `CONSOLE_HISTORY_MAX` | 16 lines in the ring buffer |
| `CONSOLE_EXEC_BUFFER_MAX` | 32 pending execution slots |
---
## Global state
```c
typedef struct {
char_t line[CONSOLE_HISTORY_MAX][CONSOLE_LINE_MAX]; // ring buffer
bool_t visible;
#ifdef DUSK_CONSOLE_POSIX
threadmutex_t printMutex; // guards ring buffer on POSIX targets
#endif
} console_t;
extern console_t CONSOLE;
```
---
## API
```c
void consoleInit(void);
// printf-style print into the ring buffer.
// Thread-safe on POSIX (uses printMutex).
void consolePrint(const char_t *message, ...);
// Process any queued script input lines. Must be called from the
// main thread once per frame.
void consoleUpdate(void);
// Draw the ring buffer as an overlay in UI space.
errorret_t consoleDraw(void);
void consoleDispose(void);
```
---
## POSIX stdin mode (`DUSK_CONSOLE_POSIX`)
On Linux only (`DUSK_CONSOLE_POSIX`), the console launches a background
thread that polls stdin using `poll()` at 75 ms intervals
(`CONSOLE_POSIX_POLL_RATE`). Lines typed at the terminal are queued
and dispatched on the main thread by `consoleUpdate()`.
This allows typing commands or JS expressions into the running game
without blocking the render loop. The ring buffer is protected by
`CONSOLE.printMutex` so `consolePrint` is safe to call from either
thread.
POSIX mode is not available on PSP, Vita, or Dolphin targets.
---
## Notes
- `CONSOLE.visible` controls whether `consoleDraw` renders anything.
Toggle it from a debug keybind or always set it to `true` in
development builds.
- `consolePrint` wraps lines at `CONSOLE_LINE_MAX` -- long messages are
truncated. Use multiple calls for long output.
- The console is distinct from the error system (`errorThrow` /
`errorPrint`). Use `consolePrint` for diagnostic output; use
`errorThrow` for recoverable failures.
- Log calls (`logDebug`, `logError`) go to the platform's debug output
(stdout/stderr), not to the console ring buffer.
.claude/display-color.md
-88
View File
@@ -1,88 +0,0 @@
# Display -- Color
Source: `build/generated/display/color.h` (generated at build time)
---
## Overview
`color.h` is a generated header. It is not hand-edited -- the source
lives in the CMake generator that produces it from platform configuration.
Include it via `"display/color.h"`.
---
## Types
```c
typedef float_t colorchannelf_t; // float channel [0.0, 1.0]
typedef uint8_t colorchannel8_t; // 8-bit channel [0, 255]
typedef struct { colorchannelf_t r, g, b; } color3f_t;
typedef struct { colorchannelf_t r, g, b, a; } color4f_t;
typedef struct { colorchannel8_t r, g, b; } color3b_t;
typedef struct { colorchannel8_t r, g, b, a; } color4b_t;
typedef color4b_t color_t; // default: RGBA uint8
```
`color_t` is always `color4b_t` -- four `uint8_t` channels.
Most engine APIs (text rendering, UI, mesh vertices) take `color_t`.
---
## Constructors
```c
color3f(r, g, b) // float RGB
color4f(r, g, b, a) // float RGBA
color3b(r, g, b) // uint8 RGB
color4b(r, g, b, a) // uint8 RGBA
color(r, g, b, a) // alias for color4b
colorHex(0xRRGGBBAA) // unpack 32-bit hex into color4b
```
---
## Predefined constants
Each named colour comes in four variants: `_4B` (uint8 RGBA, default),
`_3B` (uint8 RGB), `_4F` (float RGBA), `_3F` (float RGB). The bare
name (e.g. `COLOR_BLACK`) always resolves to the `_4B` variant.
| Constant | RGBA (uint8) |
|----------|-------------|
| `COLOR_BLACK` | 0, 0, 0, 255 |
| `COLOR_WHITE` | 255, 255, 255, 255 |
| `COLOR_RED` | 255, 0, 0, 255 |
| `COLOR_GREEN` | 0, 255, 0, 255 |
| `COLOR_BLUE` | 0, 0, 255, 255 |
| `COLOR_YELLOW` | 255, 255, 0, 255 |
| `COLOR_CYAN` | 0, 255, 255, 255 |
| `COLOR_MAGENTA` | 255, 0, 255, 255 |
| `COLOR_ORANGE` | 255, 165, 0, 255 |
| `COLOR_PURPLE` | 127, 0, 127, 255 |
| `COLOR_GRAY` | 127, 127, 127, 255 |
| `COLOR_LIGHT_GRAY` | 191, 191, 191, 255 |
| `COLOR_DARK_GRAY` | 63, 63, 63, 255 |
| `COLOR_BROWN` | 153, 102, 51, 255 |
| `COLOR_PINK` | 255, 191, 204, 255 |
| `COLOR_LIME` | 191, 255, 0, 255 |
| `COLOR_NAVY` | 0, 0, 127, 255 |
| `COLOR_TEAL` | 0, 127, 127, 255 |
| `COLOR_CORNFLOWER_BLUE` | 99, 147, 237, 255 |
| `COLOR_TRANSPARENT` | 0, 0, 0, 0 |
| `COLOR_TRANSPARENT_WHITE` | 255, 255, 255, 0 |
| `COLOR_TRANSPARENT_BLACK` | 0, 0, 0, 0 |
---
## Notes
- `color_t` uses premultiplied-friendly `uint8_t` channels for
compatibility with both OpenGL texture uploads and GX on Dolphin.
- For shader uniforms that expect float colours, convert manually:
`(float_t)col.r / 255.0f` etc.
- The `COLOR_SCRIPT` macro is a C string containing the JS Color class
static methods. It is concatenated into the embedded JS runtime
during module init (see `.claude/script.md`).
.claude/display-core.md
-81
View File
@@ -1,81 +0,0 @@
# Display -- Screen, Framebuffer, and Size Modes
Source: `src/dusk/display/`
See also: `.claude/display-texture.md`, `.claude/display-shader.md`
---
## Display size modes
Two compile-time configurations exist:
### Fixed size (`DUSK_DISPLAY_WIDTH` + `DUSK_DISPLAY_HEIGHT`)
The render resolution is constant. Set both defines at CMake configure
time. `SCREEN.width` and `SCREEN.height` are compile-time constants.
### Dynamic size (`DUSK_DISPLAY_SIZE_DYNAMIC`)
The window can be resized (desktop targets). Instead of fixed defines,
set `DUSK_DISPLAY_WIDTH_DEFAULT` and `DUSK_DISPLAY_HEIGHT_DEFAULT`.
The screen system renders to an internal framebuffer at a logical
resolution and scales/letterboxes to the actual window.
Screen modes available only with `DUSK_DISPLAY_SIZE_DYNAMIC`:
| Mode | Behaviour |
|------|-----------|
| `SCREEN_MODE_BACKBUFFER` | Render directly to the window backbuffer |
| `SCREEN_MODE_FIXED_SIZE` | Fixed pixel dimensions; letterboxed |
| `SCREEN_MODE_ASPECT_RATIO` | Maintain aspect ratio at all cost |
| `SCREEN_MODE_FIXED_HEIGHT` | Fixed height; width expands/contracts |
| `SCREEN_MODE_FIXED_WIDTH` | Fixed width; height expands/contracts |
| `SCREEN_MODE_FIXED_VIEWPORT_HEIGHT` | Fixed height at higher resolution |
Configure via `SCREEN.mode` and the corresponding union field before
calling `screenInit()`.
---
## Framebuffer (`framebuffer.h`)
```c
extern framebuffer_t FRAMEBUFFER_BACKBUFFER;
extern const framebuffer_t *FRAMEBUFFER_BOUND;
// Bind/unbind:
frameBufferBind(fb);
frameBufferUnbind();
// Clear (pass flag combination):
frameBufferClear(fb, FRAMEBUFFER_CLEAR_COLOR | FRAMEBUFFER_CLEAR_DEPTH);
// Dimensions of the currently bound framebuffer:
int32_t w = frameBufferGetWidth();
int32_t h = frameBufferGetHeight();
```
`FRAMEBUFFER_BACKBUFFER` is the window surface. Off-screen framebuffers
are used by the screen system when `DUSK_DISPLAY_SIZE_DYNAMIC` is on.
---
## Screen (`screen.h`)
```c
extern screen_t SCREEN;
// SCREEN.width, SCREEN.height -- logical render dimensions
// SCREEN.aspect -- width / height
// SCREEN.background -- clear colour
errorret_t screenInit();
errorret_t screenBind(); // call before rendering game content
errorret_t screenUnbind(); // call after game content, before UI
errorret_t screenRender(); // blit the internal framebuffer to the window
errorret_t screenDispose();
```
`screenBind` / `screenUnbind` / `screenRender` are called by the scene
system automatically each frame. Game code normally does not call them
directly -- use the JS `render()` hook instead.
.claude/display-mesh.md
-240
View File
@@ -1,240 +0,0 @@
# Display -- Mesh
Source: `src/dusk/display/mesh/`
See also: `.claude/display-spritebatch.md`, `.claude/display-shader.md`
---
## Overview
The mesh system wraps platform-specific GPU geometry buffers behind a
common `mesh_t` type. Geometry is described as an array of
`meshvertex_t` values and a primitive type. The platform layer
(`meshplatform.h`) provides the concrete buffer and draw implementation
(VBO on OpenGL, display list or immediate-mode on Dolphin GX).
---
## Vertex format (`meshvertex.h`)
```c
typedef struct {
#if MESH_ENABLE_COLOR
color_t color; // optional per-vertex colour (disabled by default)
#endif
float_t uv[2]; // texture coordinates (U, V)
float_t pos[3]; // position (X, Y, Z)
} meshvertex_t;
```
`MESH_ENABLE_COLOR` is a compile-time flag (default 0). Enable it with
`-DMESH_ENABLE_COLOR=1` at CMake configure time if per-vertex colouring
is needed; be aware this changes the struct size and breaks binary
compatibility with pre-built mesh data.
---
## Core API (`mesh.h`)
```c
// Platform alias -- do not use meshplatform_t directly.
typedef meshplatform_t mesh_t;
typedef meshprimitivetypeplatform_t meshprimitivetype_t;
// Upload vertices to the GPU. Must be called from the main thread.
errorret_t meshInit(
mesh_t *mesh,
const meshprimitivetype_t primitiveType,
const int32_t vertexCount,
const meshvertex_t *vertices
);
// Flush a range of updated vertices to the GPU (modern targets only).
// vertexCount == -1 flushes all vertices.
errorret_t meshFlush(
mesh_t *mesh,
const int32_t vertexOffset,
const int32_t vertexCount
);
// Draw the mesh. vertexCount == -1 draws all vertices.
errorret_t meshDraw(
const mesh_t *mesh,
const int32_t vertexOffset,
const int32_t vertexCount
);
// Compute the axis-aligned bounding box.
void meshGetBounds(const mesh_t *mesh, vec3 outMin, vec3 outMax);
int32_t meshGetVertexCount(const mesh_t *mesh);
errorret_t meshDispose(mesh_t *mesh);
```
On constrained targets (GameCube/Wii) `meshFlush` is a no-op -- the
hardware reads vertices from main memory directly. Always call it on
desktop/mobile targets after modifying vertex data.
---
## Primitive generators
Each generator provides:
- A `*Buffer(vertices, ...)` function that writes into a caller-supplied
`meshvertex_t` array (no allocation).
- A global pre-built `*_MESH_SIMPLE` singleton + `*_MESH_SIMPLE_VERTICES`
array initialised at engine startup (for common one-off uses).
All generators use CCW winding and `MESH_PRIMITIVE_TYPE_TRIANGLES`.
### Quad (`quad.h`)
```c
#define QUAD_VERTEX_COUNT 6 // two triangles
// 2D quad in XY plane:
void quadBuffer(
meshvertex_t *vertices,
const float_t minX, const float_t minY,
const float_t maxX, const float_t maxY,
const float_t u0, const float_t v0,
const float_t u1, const float_t v1
);
// 3D quad using full vec3 min/max:
void quadBuffer3D(
meshvertex_t *vertices,
const vec3 min, const vec3 max,
const vec2 uvMin, const vec2 uvMax
);
extern mesh_t QUAD_MESH_SIMPLE;
```
The SpriteBatch is built on `quadBuffer3D` internally.
### Cube (`cube.h`)
```c
#define CUBE_VERTEX_COUNT 36 // 6 faces x 6 vertices
// Axis-aligned box from min to max:
void cubeBuffer(
meshvertex_t *vertices,
const vec3 min, const vec3 max
);
extern mesh_t CUBE_MESH_SIMPLE; // unit cube (0,0,0) to (1,1,1)
```
### Plane (`plane.h`)
```c
#define PLANE_VERTEX_COUNT 6
typedef enum {
PLANE_AXIS_XY, // flat in XY, normal along +Z (billboard / wall face)
PLANE_AXIS_XZ, // flat in XZ, normal along +Y (ground / floor)
PLANE_AXIS_YZ, // flat in YZ, normal along +X (side wall)
} planeaxis_t;
void planeBuffer(
meshvertex_t *vertices,
const planeaxis_t axis,
const vec3 min, const vec3 max,
const vec2 uvMin, const vec2 uvMax
);
extern mesh_t PLANE_MESH_SIMPLE; // unit XZ plane (0,0,0) to (1,0,1)
```
### Sphere (`sphere.h`)
```c
#define SPHERE_STACKS 8
#define SPHERE_SECTORS 16
#define SPHERE_VERTEX_COUNT (SPHERE_STACKS * SPHERE_SECTORS * 6)
void sphereBuffer(
meshvertex_t *vertices,
const vec3 center,
const float_t radius,
const int32_t stacks,
const int32_t sectors
);
extern mesh_t SPHERE_MESH_SIMPLE; // unit sphere centered at (0,0,0), r=0.5
```
### Capsule (`capsule.h`)
```c
#define CAPSULE_CAP_RINGS 4
#define CAPSULE_SECTORS 16
// Total vertex count = (2 * capRings + 1) * sectors * 6
void capsuleBuffer(
meshvertex_t *vertices,
const vec3 center,
const float_t radius,
const float_t halfHeight, // half-height of the cylindrical section only
const int32_t capRings,
const int32_t sectors
);
extern mesh_t CAPSULE_MESH_SIMPLE; // r=0.5, halfHeight=0.5 (total h=2.0)
```
The long axis is always Y. This mirrors the physics capsule body (see
`.claude/physics.md`).
### Triangular prism (`triprism.h`)
```c
#define TRIPRISM_VERTEX_COUNT 24
// Cross-section triangle defined by three 2D points in XY;
// extruded along Z from minZ to maxZ.
void triPrismBuffer(
meshvertex_t *vertices,
const float_t x0, const float_t y0,
const float_t x1, const float_t y1,
const float_t x2, const float_t y2,
const float_t minZ, const float_t maxZ
);
extern mesh_t TRIPRISM_MESH_SIMPLE;
// Unit prism: triangle (0,0),(1,0),(0.5,1) extruded z=0 to z=1.
```
---
## Custom dynamic mesh
If you need to update geometry each frame (e.g. a procedural mesh):
```c
static meshvertex_t myVerts[MY_VERT_COUNT];
static mesh_t myMesh;
// On init:
// Fill myVerts, then:
errorChain(meshInit(&myMesh, MESH_PRIMITIVE_TYPE_TRIANGLES,
MY_VERT_COUNT, myVerts));
// Each frame (after modifying myVerts):
errorChain(meshFlush(&myMesh, 0, -1));
errorChain(meshDraw(&myMesh, 0, -1));
```
---
## Notes
- `meshInit` must be called on the **main thread** (GPU upload).
- `meshFlush` is required on OpenGL targets when vertices change
after init. It is a no-op on Dolphin.
- All `_MESH_SIMPLE` globals are initialised during engine startup --
do not call `meshInit` on them manually.
.claude/display-shader.md
-86
View File
@@ -1,86 +0,0 @@
# Display -- Shader, Material, and Display State
Source: `src/dusk/display/`
See also: `.claude/display-core.md`, `.claude/display-texture.md`
---
## Shader (`shader.h` + `shaderlist.h`)
Shaders are platform-abstracted. The current shader list is defined
in `shaderlist.h`. Currently only one shader is implemented:
| Enum | Description |
|------|-------------|
| `SHADER_LIST_SHADER_UNLIT` | Unlit / flat colour + texture shader |
```c
extern shaderlistdef_t SHADER_LIST_DEFS[SHADER_LIST_SHADER_COUNT];
// SHADER_LIST_DEFS[n].shader is the platform shader object.
// Bind a shader before drawing:
errorret_t shaderBind(shader_t *shader);
// Upload a mat4 uniform by name:
errorret_t shaderSetMatrix(shader_t *shader, const char_t *name, mat4 m);
```
Adding a new shader means adding an entry to `shaderlist.h`, providing
platform-specific vertex/fragment sources, and implementing the
corresponding material type in `shadermaterial_t`.
---
## Shader material (`shadermaterial.h`)
`shadermaterial_t` is a union over per-shader material structs.
Currently contains only the unlit material:
```c
typedef union shadermaterial_u {
shaderunlitmaterial_t unlit;
} shadermaterial_t;
```
`shaderunlitmaterial_t` fields:
```c
typedef struct {
color_t color; // tint colour (multiplied with the texture sample)
texture_t *texture; // NULL uses TEXTURE_WHITE (solid colour draw)
} shaderunlitmaterial_t;
```
The shader exposes uniforms `u_Proj`, `u_View`, `u_Model` (mat4),
`u_Texture` (sampler), and `u_Color` (vec4). They are uploaded via
`shaderUnlitSetMaterial(shader, material)`.
A global singleton `SHADER_UNLIT` is the live shader object;
`SHADER_UNLIT_DEFINITION` is its platform definition descriptor.
To use a shader material on a renderable entity:
1. Set `renderable.type = ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL`.
2. Set `renderable.data.material.shaderType` to the desired
`shaderlistshadertype_t` value (e.g. `SHADER_LIST_SHADER_UNLIT`).
3. Fill in the corresponding union field:
`renderable.data.material.material.unlit`.
4. Set `renderable.data.material.state.flags` for rasterizer state.
---
## Display state (`displaystate.h`)
`displaystate_t` controls per-draw rasterizer state flags:
```c
DISPLAY_STATE_FLAG_CULL // back-face culling
DISPLAY_STATE_FLAG_DEPTH_TEST // depth testing
DISPLAY_STATE_FLAG_BLEND // alpha blending
```
Set flags via `data.material.state.flags` on the renderable's material.
The default for an uninitialised state is all flags clear (no culling,
no depth test, no blending). Most opaque geometry should set at least
`CULL | DEPTH_TEST`.
.claude/display-spritebatch.md
-133
View File
@@ -1,133 +0,0 @@
# Display -- SpriteBatch
Source: `src/dusk/display/spritebatch/`
See also: `.claude/display-mesh.md`, `.claude/display-texture.md`
---
## Overview
The SpriteBatch is the primary 2D rendering primitive. It accumulates
axis-aligned quads (sprites) into a shared vertex buffer and draws them
in batches. All 2D rendering in the engine -- UI frames, text, tilemaps,
HUD -- goes through the global `SPRITEBATCH`.
The batch flushes automatically when the per-flush limit is reached, or
explicitly via `spriteBatchFlush()`.
---
## Limits
| Constant | Value | Meaning |
|----------|-------|---------|
| `SPRITEBATCH_SPRITES_MAX` | 512 | Total sprites in the vertex buffer |
| `SPRITEBATCH_FLUSH_COUNT` | 16 | Number of auto-flush segments |
| `SPRITEBATCH_SPRITES_MAX_PER_FLUSH` | 32 | Sprites per auto-flush segment |
| `SPRITEBATCH_VERTEX_COUNT` | 3072 | Total vertices (512 * QUAD_VERTEX_COUNT) |
---
## Sprite structure
```c
typedef struct {
vec3 min; // minimum XYZ corner of the quad in world/screen space
vec3 max; // maximum XYZ corner of the quad in world/screen space
vec2 uvMin; // minimum UV (top-left in [0,1] texture space)
vec2 uvMax; // maximum UV (bottom-right in [0,1] texture space)
} spritebatchsprite_t;
```
Z in `min` and `max` controls draw depth (further from camera = higher Z
in a typical orthographic setup). For flat 2D, set `min.z = max.z = 0`.
---
## SpriteBatch struct
```c
typedef struct {
mesh_t mesh;
int32_t spriteCount;
int32_t spriteFlush;
shader_t *shader;
shadermaterial_t material;
} spritebatch_t;
extern spritebatch_t SPRITEBATCH;
extern meshvertex_t SPRITEBATCH_VERTICES[SPRITEBATCH_VERTEX_COUNT];
```
`SPRITEBATCH_VERTICES` is a separate global (not embedded in the struct)
for platform alignment requirements.
---
## API
```c
errorret_t spriteBatchInit();
errorret_t spriteBatchDispose();
// Clear the buffer and reset state. Call before starting a new batch.
void spriteBatchClear();
// Append sprites to the buffer. Flushes automatically when the per-flush
// segment fills. shader + material are used on the next flush.
errorret_t spriteBatchBuffer(
const spritebatchsprite_t *sprites,
const uint32_t count,
shader_t *shader,
const shadermaterial_t material
);
// Upload and draw all buffered sprites. Binds shader and applies
// material if set. No-op if the buffer is empty.
errorret_t spriteBatchFlush();
```
---
## Typical usage
```c
// Beginning of a 2D render pass:
spriteBatchClear();
// Build sprites (e.g. via tilesetTileGetUV, then fill spritebatchsprite_t):
spritebatchsprite_t s;
glm_vec3_copy((vec3){ x, y, 0 }, s.min);
glm_vec3_copy((vec3){ x + w, y + h, 0 }, s.max);
glm_vec2_copy(uvMin, s.uvMin);
glm_vec2_copy(uvMax, s.uvMax);
shadermaterial_t mat = { .unlit = { .texture = myTexture } };
spriteBatchBuffer(&s, 1, myShader, mat);
// End of pass -- flush remaining sprites:
spriteBatchFlush();
```
---
## Relationship to other systems
- **Text rendering** (`textDraw`) internally calls `spriteBatchBuffer`
for each glyph and requires a final `spriteBatchFlush()` after drawing.
- **UI frames** (`uiFrameDraw`) push 9 quads to the batch without
flushing -- the caller or `uitextboxDraw` is responsible for the flush.
- **ECS renderables** of type `ENTITY_RENDERABLE_TYPE_SPRITEBATCH` are
drawn via the spritebatch in the scene render pipeline.
---
## Notes
- `spriteBatchBuffer` changes the batch's `shader` and `material` fields.
If you mix different shaders or textures in one batch, add an explicit
`spriteBatchFlush()` call between groups to avoid draws with the wrong
material.
- The vertex buffer is a static global -- `SPRITEBATCH_VERTICES` must
not be written from multiple threads.
.claude/display-text.md
-115
View File
@@ -1,115 +0,0 @@
# Display -- Text Rendering
Source: `src/dusk/display/text/`
See also: `.claude/display-spritebatch.md`, `.claude/display-texture.md`
---
## Overview
Text rendering is layered on top of the SpriteBatch. Each character
maps to a glyph tile in a bitmap font atlas; `textDraw` builds the
corresponding `spritebatchsprite_t` values and pushes them to the
global `SPRITEBATCH`. The caller is responsible for flushing the batch.
---
## Font type (`font.h`)
```c
typedef struct {
texture_t *texture; // glyph atlas texture
tileset_t *tileset; // grid describing glyph size + UV layout
} font_t;
```
Both pointers are caller-owned. The text system does not allocate or
free them.
```c
extern font_t FONT_DEFAULT;
```
`FONT_DEFAULT` is the engine's built-in bitmap font. It is initialised
during `textInit()` and available for the engine lifetime.
---
## Character range
```c
#define TEXT_CHAR_START '!' // ASCII 33
```
The glyph atlas begins at `'!'` (ASCII 33). Characters below this value
-- space, control characters -- are handled specially:
- `' '` (space) advances the cursor by one tile width without drawing.
- Characters below `TEXT_CHAR_START` other than space are skipped.
---
## API (`text.h`)
```c
// Initialises the text system and FONT_DEFAULT.
errorret_t textInit(void);
// Disposes of the text system.
errorret_t textDispose(void);
// Draw a null-terminated string at (x, y) in screen/world space.
// Pushes sprites to SPRITEBATCH. Caller must call spriteBatchFlush()
// after all text has been drawn.
errorret_t textDraw(
const float_t x,
const float_t y,
const char_t *text,
const color_t color,
font_t *font
);
// Measure the bounding box of a string without drawing it.
void textMeasure(
const char_t *text,
const font_t *font,
int32_t *outWidth,
int32_t *outHeight
);
// Low-level: build a single glyph sprite at position pos.
// Returns a spritebatchsprite_t ready for spriteBatchBuffer.
spritebatchsprite_t textGetSprite(
const vec2 pos,
const char_t c,
const font_t *font
);
```
---
## Typical usage
```c
// Inside a render callback:
errorChain(textDraw(10.0f, 10.0f, "Hello", COLOR_WHITE, &FONT_DEFAULT));
errorChain(spriteBatchFlush());
```
If you are also drawing UI frames or other sprites in the same pass,
batch all the `textDraw` and `spriteBatchBuffer` calls first, then call
`spriteBatchFlush()` once at the end.
---
## Notes
- Text coordinates are in the same space as the scene render (screen
space for UI, or world space if placed in the scene).
- `textMeasure` returns pixel dimensions based on the font's
`tileset.tileWidth` and `tileset.tileHeight`. Use it to centre or
right-align text before drawing.
- For UI-attached text (dialogue, labels), prefer the `uitextbox_t`
system which handles word-wrap and paging automatically
(see `.claude/ui.md`).
.claude/display-texture.md
-86
View File
@@ -1,86 +0,0 @@
# Display -- Texture, Tileset, and Font
Source: `src/dusk/display/`
See also: `.claude/display-core.md`, `.claude/display-shader.md`
---
## Texture (`texture.h`)
```c
extern texture_t TEXTURE_WHITE; // 4x4 opaque white; always available
errorret_t textureInit(
texture_t *texture,
int32_t width,
int32_t height,
textureformat_t format,
texturedata_t data
);
errorret_t textureDispose(texture_t *texture);
```
`textureformat_t` and `texture_t` are platform aliases
(`textureformatplatform_t`, `textureplatform_t`). On OpenGL targets
the format maps to GL texture format constants.
`texturedata_t` is a union:
- `.paletted.indices` + `.paletted.palette` -- for paletted formats
- `.rgbaColors` -- for RGBA formats
### Texture rules
- Dimensions must be powers of two on PSP and GameCube/Wii. Use
`mathNextPowTwo` from `util/math.h` if needed.
- Texture upload must happen on the main thread. In the asset loader,
this means `loadSync` (not `loadAsync`).
- `TEXTURE_WHITE` is always available without loading; use it as a
placeholder or for untextured geometry.
---
## Tileset (`tileset.h`)
A tileset subdivides a texture into a uniform grid of tiles.
```c
typedef struct {
uint16_t tileWidth, tileHeight;
uint16_t tileCount;
uint16_t columns, rows;
vec2 uv; // UV size per tile (pre-computed from grid dimensions)
} tileset_t;
// Get UV rect for a tile by index:
void tilesetTileGetUV(
const tileset_t *ts, uint16_t tileIndex, vec4 outUV
);
// Get UV rect for a tile by grid position:
void tilesetPositionGetUV(
const tileset_t *ts, uint16_t column, uint16_t row, vec4 outUV
);
```
`outUV` is `{u, v, u2, v2}` in normalised [0, 1] texture space.
Tilesets are loaded from `.dtf` binary files via
`ASSET_LOADER_TYPE_TILESET`. The DTF format stores tile width/height,
grid dimensions, and per-tile UV offsets (magic + version header).
---
## Font (`font.h`)
```c
typedef struct {
texture_t *texture;
tileset_t *tileset;
} font_t;
```
A font is a tileset-backed texture atlas where each tile is a character
glyph. No heap allocation -- both pointers are owned by the caller.
Character lookup is by glyph index into the tileset grid. Rendering is
handled by the spritebatch system using the tileset UV helpers.
.claude/display.md
-23
View File
@@ -1,23 +0,0 @@
# Display System
Source: `src/dusk/display/`
## Overview
The display system is a platform-abstracted rendering layer. Each
subsystem (texture, shader, framebuffer, screen) is defined by a core
header that requires the platform layer to provide concrete types and
hook macros. The OpenGL implementation lives in `src/duskgl/`; the
Dolphin (GX) implementation in `src/duskdolphin/`.
## Subsystem documentation
| Subsystem | Reference |
|-----------|-----------|
| Screen size modes, framebuffer, screen | `.claude/display-core.md` |
| Texture, tileset, font | `.claude/display-texture.md` |
| Shader, shader material, display state | `.claude/display-shader.md` |
| Mesh, vertex format, primitive generators | `.claude/display-mesh.md` |
| SpriteBatch (2D quad renderer) | `.claude/display-spritebatch.md` |
| Text rendering, font, FONT_DEFAULT | `.claude/display-text.md` |
| Color types, macros, named constants | `.claude/display-color.md` |
.claude/ecs.md
-179
View File
@@ -1,179 +0,0 @@
# Entity Component System (ECS)
Source: `src/dusk/entity/`
## Core concepts
- **Entity** (`entityid_t` = `uint8_t`) -- a numeric ID. No data of
its own; just an index into the entity manager pool.
- **Component** -- a plain data struct registered in `componentlist.h`.
Stores state; no behaviour.
- **System** -- functions that query all entities with a given component
type and act on them each tick.
## Hard limits
| Constant | Value |
|----------|-------|
| `ENTITY_COUNT_MAX` | 64 |
| `ENTITY_COMPONENT_COUNT_MAX` | 16 per entity |
| Total component slots | 1024 (64 x 16) |
| Update callbacks per entity | 5 |
| Dispose callbacks per entity | 5 |
`ENTITY_ID_INVALID = 0xFF`, `COMPONENT_ID_INVALID = 0xFF`.
## Global state
```c
extern entitymanager_t ENTITY_MANAGER;
// .entities[64] -- entity structs
// .components[1024] -- all component data (entity * 16 + comp)
// .entitiesWithComponent -- O(1) lookup indexed by [type * 64 + entityId]
```
## Entity lifecycle
```c
entityid_t id = entityManagerAdd(); // reserve first inactive slot
entityInit(id); // zero the entity, mark active
componentid_t posId = entityAddComponent(id, COMPONENT_TYPE_POSITION);
componentid_t rendId = entityAddComponent(id, COMPONENT_TYPE_RENDERABLE);
// Per-frame update (called by entityManagerUpdate):
entityUpdate(id);
// Cleanup:
entityDispose(id); // dispose components, mark inactive
entityDisposeDeep(id); // dispose self + entire position hierarchy
```
## Component registration (X-macro)
All component types are declared in a single table in
`src/dusk/entity/componentlist.h`:
```c
X(NAME, type_t, fieldName, initFn, disposeFn, renderFn)
```
This generates:
- `COMPONENT_TYPE_NAME` enum value
- Union field `fieldName` in `componentdata_t`
- Entry in `COMPONENT_DEFINITIONS[]` with `init` / `dispose` /
`render` function pointers (any may be `NULL`)
Current registered components:
| Enum suffix | Struct | Notes |
|-------------|--------|-------|
| `POSITION` | `entityposition_t` | Transform + parent/child hierarchy |
| `CAMERA` | `entitycamera_t` | View matrix setup |
| `RENDERABLE` | `entityrenderable_t` | Sprite batch, shader material, or custom draw |
| `PHYSICS` | `entityphysics_t` | Physics body (see `.claude/physics.md`) |
| `TRIGGER` | `entitytrigger_t` | Collision trigger zone |
## Accessing component data
```c
void *componentGetData(
entityid_t entityId,
componentid_t componentId,
componenttype_t type
);
// Returns pointer into the preallocated components pool.
// Never NULL for a valid (id, type) pair.
```
Querying all entities with a given type:
```c
entityid_t ids[ENTITY_COUNT_MAX];
componentid_t comps[ENTITY_COUNT_MAX];
entityid_t count = componentGetEntitiesWithComponent(
COMPONENT_TYPE_PHYSICS, ids, comps
);
```
## Adding a new component -- checklist
1. Create `src/dusk/entity/component/<category>/entity<Name>.h/.c`.
- Struct: `entity<Name>_t`
- `entity<Name>Init(entityid_t, componentid_t)` (required)
- `entity<Name>Dispose(entityid_t, componentid_t)` (if needed)
2. `#include` the new header in the header block of `componentlist.h`.
3. Add an `X(...)` row in `componentlist.h`.
4. If JS-facing, add a script module (see `CLAUDE.md`).
## Position component (`entityposition_t`)
The position component implements the transform hierarchy and uses lazy
evaluation with dirty flags to avoid redundant matrix rebuilds.
**Dirty flags:**
| Flag | Meaning |
|------|---------|
| `ENTITY_POSITION_FLAG_PRS_DIRTY` | Cached position/rotation/scale stale vs localTransform |
| `ENTITY_POSITION_FLAG_ROTATION_DIRTY` | Rotation columns of localTransform stale |
| `ENTITY_POSITION_FLAG_POSITION_DIRTY` | Position column of localTransform stale |
| `ENTITY_POSITION_FLAG_WORLD_DIRTY` | World matrix stale |
**Hierarchy:** up to 8 children per entity. `entityPositionSetParent()`
reparents and maintains the child list. `entityDisposeDeep()` /
`entityPositionDisposeDeep()` recursively disposes the entire subtree.
**Key functions:**
```c
// Local space getters/setters (mark local dirty):
entityPositionGetLocalPosition / SetLocalPosition
entityPositionGetLocalRotation / SetLocalRotation
entityPositionGetLocalScale / SetLocalScale
// World space getters/setters (ensure world updated):
entityPositionGetWorldPosition / SetWorldPosition
entityPositionGetWorldRotation / SetWorldRotation
entityPositionGetWorldScale / SetWorldScale
entityPositionSetParent(entityId, parentEntityId, parentComponentId);
entityPositionLookAt(entityId, componentId, eye, target, up);
entityPositionRebuild(pos); // force immediate matrix rebuild
```
## Renderable component (`entityrenderable_t`)
Three rendering modes selected via `entityrenderabletype_t`:
| Mode | Description |
|------|-------------|
| `ENTITY_RENDERABLE_TYPE_CUSTOM` | User-supplied `draw` callback |
| `ENTITY_RENDERABLE_TYPE_SPRITEBATCH` | Up to 64 sprites + texture |
| `ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL` | Up to 8 meshes, shader, material, display state |
Default on init: shader material (white, unlit, depth-tested cube).
`priority` (int8_t) controls render order; 0 = automatic.
## Callback hooks on entities
Entities support up to 5 registered update callbacks and 5 dispose
callbacks. These are used by systems that need per-entity ticks without
building a full query loop every frame:
```c
entityUpdateAdd(entityId, updateFn, componentId, user);
entityUpdateRemove(entityId, updateFn);
entityDisposeAdd(entityId, disposeFn, componentId, user);
entityDisposeRemove(entityId, disposeFn);
```
## Design rules
- Components store **data only**. No logic in a component struct or
its init beyond setting default values.
- Keep components small and focused.
- Cross-component access is fine from a system, but a component must
never hold a pointer to another component -- use entity IDs.
- Systems must not assume component ordering. Use `componentGetEntitiesWithComponent`.
.claude/engine.md
-95
View File
@@ -1,95 +0,0 @@
# Engine, System, and Log
Sources: `src/dusk/engine/`, `src/dusk/system/`, `src/dusk/log/`
---
## Engine (`engine.h`)
The engine owns the top-level init / update / dispose loop. Every
platform's `main()` calls these three functions in order.
```c
extern engine_t ENGINE;
// ENGINE.running -- false causes the main loop to exit
// ENGINE.argc / ENGINE.argv -- passed from main()
// ENGINE.version -- version string
errorret_t engineInit(int32_t argc, const char_t **argv);
errorret_t engineUpdate(void); // called once per tick
errorret_t engineDispose(void);
```
`engineInit` initialises subsystems in order: system, log, assert,
display, time, asset, input, physics, script, etc.
`engineUpdate` steps each subsystem: time, input, physics, script, ECS
entities, rendering, audio, network, asset completion callbacks.
`engineDispose` shuts everything down in reverse order.
**To exit gracefully:** set `ENGINE.running = false` -- the platform
main loop checks this each tick and calls `engineDispose` before
returning.
---
## System (`system.h`)
The system module is initialised very early (before most other
subsystems) and provides two things:
### Platform identity
```c
typedef enum { SYSTEM_PLATFORM_LIST } systemplatform_t;
systemplatform_t systemGetPlatform(void);
```
Platform names come from `systemplatformlist.h` via an X-macro. This
lets game code query the runtime platform when compile-time guards are
not sufficient (e.g. serializing platform name to a log).
### Dialog blocking
Some platforms (PSP, Wii) show OS-level dialogs (Wi-Fi setup, save
management) that block the normal game loop. The system module exposes
the current dialog state so the engine main loop can adjust:
```c
typedef enum {
SYSTEM_DIALOG_TYPE_NONE,
SYSTEM_DIALOG_TYPE_RENDER_BLOCKING, // skip render but still tick
SYSTEM_DIALOG_TYPE_TICK_BLOCKING, // skip both render and tick
} systemdialogtype_t;
systemdialogtype_t systemGetActiveDialogType(void);
```
`engineUpdate` checks this before calling render / update code.
Most platforms always return `SYSTEM_DIALOG_TYPE_NONE`.
---
## Log (`log.h`)
Simple printf-style logging with two levels. Always use these instead
of `printf` / `fprintf`.
```c
void logDebug(const char_t *message, ...);
// Writes to the debug output (stdout on desktop, platform console
// on handhelds). No-op in release builds on some platforms.
void logError(const char_t *message, ...);
// Writes to the error output. On some platforms (PSP) this may
// pause execution to ensure the message is visible before continuing.
```
**Do not** use `logDebug` / `logError` for structured error handling --
that is what `errorThrow` / `errorChain` are for. Log calls are for
human-readable diagnostics only.
The error system calls `logError` internally when printing a caught
error via `errorPrint()`.
.claude/errors.md
-133
View File
@@ -1,133 +0,0 @@
# Error Handling System
Source: `src/dusk/error/`
## Philosophy
Error handling is return-value based. Functions that can fail return
`errorret_t`. There are no exceptions, `errno`, `setjmp`, or global
error codes. Each thread has its own isolated error state.
## Types
```c
typedef uint8_t errorcode_t;
typedef struct {
errorcode_t code;
char_t *message; // allocated; freed by errorCatch
char_t *lines; // call-stack trace; allocated; freed by errorCatch
} errorstate_t;
typedef struct {
errorcode_t code;
errorstate_t *state; // NULL on success
} errorret_t;
```
**Constants:** `ERROR_OK = 0`, `ERROR_NOT_OK = 1`.
Error state is thread-local:
```c
extern THREAD_LOCAL errorstate_t ERROR_STATE;
```
Each thread has its own `ERROR_STATE` so concurrent errors never
interfere.
## Macros
### Throwing an error
```c
errorThrow("message %d", value);
// Throws with ERROR_NOT_OK, captures __FILE__ / __func__ / __LINE__.
errorThrowWithCode(code, "message %d", value);
// Same but with a specific error code.
```
Both macros **return from the current function** with an `errorret_t`.
Do not call them in void functions.
### Propagating up the call stack
```c
errorChain(someCall());
```
If `someCall()` returned an error, appends the current location to the
stack trace and **returns** that error from the current function.
If `someCall()` returned success, execution continues normally.
### Returning success
```c
errorOk();
```
Returns `errorret_t` with `code == ERROR_OK` and asserts the thread's
`ERROR_STATE` is clean (no leftover error). Must be the last statement
in a fallible function.
### Inspecting a result
```c
if(errorIsOk(ret)) { ... }
if(errorIsNotOk(ret)) { ... }
```
### Cleaning up
```c
errorCatch(ret);
```
Frees `ret.state->message` and `ret.state->lines`, resets the thread's
`ERROR_STATE.code` to `ERROR_OK`. Safe to call on a success return
(no-op). **Always call `errorCatch` on errors you are handling** --
otherwise the allocated message and stack-trace leak.
### Logging
```c
errorPrint(ret); // prints code + message + stack trace, returns ret
```
## Typical patterns
### Fallible function
```c
errorret_t myFunction(int_t x) {
if(x < 0) errorThrow("x must be non-negative, got %d", x);
errorChain(someOtherFallibleCall(x));
errorOk();
}
```
### Caller that handles errors
```c
errorret_t ret = myFunction(-1);
if(errorIsNotOk(ret)) {
errorCatch(errorPrint(ret));
// ... fallback logic ...
}
```
### Stack trace accumulation
Each `errorChain()` call appends a line to `ret.state->lines` in the
format ` at file:line in function\n`. A deeply chained error produces
a full call path readable from `ret.state->lines`.
## What NOT to do
- Do not use raw `errno` for in-engine errors.
- Do not return an error code integer -- always return `errorret_t`.
- Do not ignore an error return without calling `errorCatch` on it if
you are not propagating it.
- Do not mix assertions with error handling. Assertions are for
programmer mistakes; `errorThrow` is for expected failure paths.
.claude/events.md
-109
View File
@@ -1,109 +0,0 @@
# Event System
Source: `src/dusk/event/`
## Overview
The event system is a simple publish-subscribe mechanism backed by
caller-owned static arrays. There is no heap allocation in the event
system itself -- the caller provides the backing storage.
## API
```c
typedef void (*eventcallback_t)(void *params, void *user);
typedef struct {
eventcallback_t *callbacks;
void **users;
size_t size;
uint32_t count;
} event_t;
```
### Initialise
```c
void eventInit(
event_t *event,
eventcallback_t *callbacks,
void **users,
size_t size
);
```
`callbacks` and `users` are caller-owned arrays of length `size`. Both
are zeroed by `eventInit`. `users` may be `NULL` if no subscriber needs
a user pointer.
### Subscribe / unsubscribe
```c
void eventSubscribe(event_t *event, eventcallback_t callback, void *user);
void eventUnsubscribe(event_t *event, eventcallback_t callback);
```
The same `(callback, user)` pair may only be subscribed once --
`eventSubscribe` asserts on a duplicate. `eventUnsubscribe` is a no-op
if the pair is not found. Unsubscribing uses swap-with-last to keep the
array packed; ordering is not preserved.
### Fire
```c
void eventInvoke(const event_t *event, void *params);
```
Calls every subscriber in registration order, passing `params` and
each subscriber's `user` pointer.
## Usage pattern
Declare the backing arrays alongside the event struct, typically as
struct fields or static variables:
```c
#define MY_EVENT_CAPACITY 4
typedef struct {
event_t onComplete;
eventcallback_t _completeCbs[MY_EVENT_CAPACITY];
void *_completeUsers[MY_EVENT_CAPACITY];
} mystate_t;
// Init:
eventInit(
&state.onComplete,
state._completeCbs,
state._completeUsers,
MY_EVENT_CAPACITY
);
// Publish:
eventInvoke(&state.onComplete, &someParams);
// Subscribe from outside:
eventSubscribe(&state.onComplete, myHandler, myUserPtr);
```
## Constraints
- Capacity is fixed at init time. Exceeding it is a runtime assertion.
- Subscriber order is not stable after an unsubscribe.
- `eventInvoke` is synchronous -- all callbacks run on the calling
thread before it returns.
- Do not subscribe or unsubscribe from inside a callback -- the array
may shift during iteration.
## Where events are used
| Subsystem | Event | Fires when |
|-----------|-------|-----------|
| `inputactiondata_t` | `onPressed`, `onReleased` | Action button state changes |
| `uitextbox_t` | `onPageComplete` | Typewriter scroll reveals the full page |
| `uitextbox_t` | `onLastPage` | Last page is fully scrolled |
| `uifullbox_t` | `onTransitionEnd` | Colour transition animation completes |
| `uiloading_t` | `onShow` / `onHide` | Loading indicator fade completes |
| Asset system | `assetbatch_t` callback | All entries in a batch reach LOADED/ERROR |
See `.claude/ui.md` for the UI event details.
.claude/input.md
-187
View File
@@ -1,187 +0,0 @@
# Input System
Source: `src/dusk/input/`, platform layers in `src/dusk<platform>/input/`
## Architecture
The input system has two layers:
1. **Action layer** (`inputaction_t`) -- named gameplay inputs, e.g.
UP, DOWN, ACCEPT, CANCEL. This is what game code reads.
2. **Button layer** (`inputbutton_t`) -- physical hardware inputs, e.g.
keyboard key, gamepad button, analog axis, mouse axis. Multiple
buttons can bind to the same action (the highest value wins).
The platform layer implements two hooks:
- `inputUpdatePlatform()` -- read hardware state once per frame
- `inputButtonGetValuePlatform()` -- return the analog value [0.0, 1.0]
for a given button
## Defined actions
Actions are defined in `src/dusk/input/input.csv` and code-generated
into the `inputaction_t` enum. Current values:
| Constant | Meaning |
|----------|---------|
| `INPUT_ACTION_NULL` | Invalid / sentinel (0) |
| `INPUT_ACTION_UP` | Up direction |
| `INPUT_ACTION_DOWN` | Down direction |
| `INPUT_ACTION_LEFT` | Left direction |
| `INPUT_ACTION_RIGHT` | Right direction |
| `INPUT_ACTION_ACCEPT` | Confirm / primary action |
| `INPUT_ACTION_CANCEL` | Back / secondary action |
| `INPUT_ACTION_RAGEQUIT` | Quit the application |
| `INPUT_ACTION_CONSOLE` | Toggle debug console |
| `INPUT_ACTION_POINTERX` | Mouse / pointer X axis |
| `INPUT_ACTION_POINTERY` | Mouse / pointer Y axis |
| `INPUT_ACTION_COUNT` | Total count (not a valid action) |
## Global state
```c
extern input_t INPUT;
// INPUT.actions[INPUT_ACTION_COUNT] -- all action states
// INPUT.platform -- platform-specific data
```
## Reading actions (game code)
```c
// Analog value this frame (0.0 - 1.0)
float_t inputGetCurrentValue(inputaction_t action);
// Analog value last frame
float_t inputGetLastValue(inputaction_t action);
// Boolean helpers (built on current/last values)
bool_t inputIsDown(inputaction_t action);
bool_t inputWasDown(inputaction_t action);
bool_t inputPressed(inputaction_t action); // was up, now down
bool_t inputReleased(inputaction_t action); // was down, now up
// Single axis from a neg + pos pair of actions (returns [-1, 1]):
float_t inputAxis(inputaction_t neg, inputaction_t pos);
// 2D axis from four actions (negX/posX/negY/posY):
void inputAxis2D(
inputaction_t negX, inputaction_t posX,
inputaction_t negY, inputaction_t posY,
vec2 result
);
// Same four-action axis, normalized to a unit vector via atan2:
void inputAngle2D(
inputaction_t negX, inputaction_t posX,
inputaction_t negY, inputaction_t posY,
vec2 result
);
// Deadzone filter (applied to raw axis values)
float_t inputDeadzone(float_t value, float_t deadzone);
```
## Binding buttons to actions
```c
void inputBind(inputaction_t action, inputbutton_t button);
```
Each platform's init function calls `inputBind` to wire its hardware
buttons to the standard action IDs. Game code should never need to call
`inputBind` -- it is set up once during platform init.
## Button types
```c
INPUT_BUTTON_TYPE_KEYBOARD // SDL scancode (SDL2 targets only)
INPUT_BUTTON_TYPE_POINTER // Mouse axes: X, Y, Z, WHEEL_X, WHEEL_Y
INPUT_BUTTON_TYPE_TOUCH // Touch (defined, not fully implemented)
INPUT_BUTTON_TYPE_GAMEPAD // Digital gamepad buttons
INPUT_BUTTON_TYPE_GAMEPAD_AXIS // Analog axes (-1.0 to 1.0 internally)
```
## Events
Each action has `onPressed` and `onReleased` event callbacks. Subscribe
via the event system (see `.claude/events.md`):
```c
eventSubscribe(&INPUT.actions[ACTION_ACCEPT].onPressed, myCallback, NULL);
```
## Platform implementations
### SDL2 (`src/dusksdl2/input/`)
Handles Linux, Knulli, and PSP (PSP adds its own button mapping layer
on top of SDL2).
- Keyboard: SDL scancode array from `SDL_GetKeyboardState()`
- Pointer: normalized mouse position (0.0-1.0), scroll axes
- Gamepad: first available `SDL_GameController`; axis values normalized
to [-1.0, 1.0] with deadzone (default 0.2f via `inputGetDeadzoneSDL2`)
### Dolphin -- GameCube / Wii (`src/duskdolphin/input/`)
Uses `libogc` PAD API. No keyboard or pointer input -- trying to use
those button types is a compile-time `#error`.
- Gamepad: `PAD_ScanPads()` + `PAD_ButtonsHeld()` for pad 0
- Axes: left stick X/Y, C-stick X/Y, L/R triggers (6 total)
- Deadzone: hardcoded 0.2f
- Default bindings set at init: D-pad/L-stick = directional actions,
A = ACCEPT, B = CANCEL, X = CONSOLE, Start = RAGEQUIT
### PSP (`src/duskpsp/input/`)
Layered on top of SDL2. `inputInitPSP()` remaps SDL2 controller button
constants to PSP button names, then calls `inputBind` to wire them:
| PSP button | SDL2 constant |
|------------|---------------|
| Cross | `SDL_CONTROLLER_BUTTON_A` |
| Circle | `SDL_CONTROLLER_BUTTON_B` |
| Triangle | `SDL_CONTROLLER_BUTTON_Y` |
| Square | `SDL_CONTROLLER_BUTTON_X` |
| L / R | `SDL_CONTROLLER_BUTTON_LEFTSHOULDER` / `RIGHTSHOULDER` |
| L-Stick | `SDL_CONTROLLER_AXIS_LEFTX/Y` |
### Vita (`src/duskvita/input/`)
Layered on top of SDL2 (via vitaSDL2). Behaviour is similar to PSP --
no keyboard, no pointer, gamepad only.
## JS module (`Input`)
The input system is exposed to JS as the global `Input` object with
static methods. Action constants are pre-defined as numeric properties
on the `Input` object (e.g. `Input.ACCEPT`, `Input.UP`):
```js
// Check if the accept button is held this frame:
if(Input.isDown(Input.ACCEPT)) { ... }
// Was the cancel button just pressed?
if(Input.pressed(Input.CANCEL)) { ... }
// Analog value for the right trigger:
var val = Input.getValue(Input.RIGHT);
// Single axis (-1 to 1) from a neg/pos pair:
var h = Input.axis(Input.LEFT, Input.RIGHT);
```
All `Input.*` action constants match the `INPUT_ACTION_*` enum values
from the C layer (UP, DOWN, LEFT, RIGHT, ACCEPT, CANCEL, RAGEQUIT,
CONSOLE, POINTERX, POINTERY).
## Platform capability notes
| Feature | Linux/Knulli | PSP | Vita | GameCube/Wii |
|---------|-------------|-----|------|--------------|
| Keyboard | Yes (SDL2) | No | No | No |
| Pointer/Mouse | Yes (SDL2) | No | No | No |
| Gamepad | Yes (SDL2) | Yes (SDL2) | Yes (SDL2) | Yes (PAD) |
| Analog axes | Yes | L-Stick only | L-Stick, R-Stick | L-Stick, C-Stick, Triggers |
| Touch | Defined, not implemented | -- | -- | -- |
.claude/locale.md
-90
View File
@@ -1,90 +0,0 @@
# Locale System
Source: `src/dusk/locale/`, asset loader at
`src/dusk/asset/loader/locale/`
## Overview
The locale system loads Gettext PO files from the asset archive and
provides string lookup with plural-form support and printf-style
argument substitution. Locale files live in `locale/` inside `dusk.dsk`.
## Global state
```c
extern localemanager_t LOCALE;
// LOCALE.locale -- currently active localeinfo_t
// LOCALE.entry -- locked assetentry_t for the current PO file
```
## Initialise and switch locale
```c
errorret_t localeManagerInit();
// Defaults to LOCALE_EN_US (locale/en_US.po).
errorret_t localeManagerSetLocale(const localeinfo_t *locale);
// Unlocks the old entry, loads and locks the new one.
// Blocks until the new PO file is fully parsed.
void localeManagerDispose();
```
## Getting a localised string
```c
// Variadic (printf-style args):
localeManagerGetText(id, buffer, bufferSize, plural, ...);
// With a pre-built args array:
localeManagerGetTextArgs(id, buffer, bufferSize, plural, args, argCount);
```
Both are macros that delegate to `assetLocaleGetStringWithVA` /
`assetLocaleGetStringWithArgs`.
- `id` -- message ID string (the English key in the PO file)
- `plural` -- plural index (0 for singular, 1+ per PO plural rules)
- `buffer` -- destination `char_t` array
- `bufferSize` -- size of the destination buffer
- `...` -- format arguments matching `%s`, `%d`, `%f` placeholders
## Locale descriptors (`localeinfo_t`)
```c
typedef struct {
const char_t *name; // e.g. "en-US"
const char_t *file; // path inside dusk.dsk, e.g. "locale/en_US.po"
} localeinfo_t;
```
The built-in descriptor is:
```c
static const localeinfo_t LOCALE_EN_US = {
.name = "en-US",
.file = "locale/en_US.po",
};
```
Add new locales by declaring another `localeinfo_t` constant and
shipping the corresponding `.po` file in the asset archive.
## PO file format notes
The loader (`assetlocaleloader`) parses standard Gettext PO syntax:
- `msgid` / `msgstr` pairs
- `msgid_plural` / `msgstr[n]` for plural forms
- The `Plural-Forms:` header (e.g. `nplurals=2; plural=(n != 1);`)
is parsed and evaluated at lookup time
Argument substitution uses `%s`, `%d`, `%f` placeholders (not
standard Gettext `%1` positional args).
## Adding a new locale
1. Create `locale/<lang_COUNTRY>.po` with a valid `Plural-Forms:`
header and the translated `msgid`/`msgstr` entries.
2. Pack it into `dusk.dsk`.
3. Add a `localeinfo_t` constant in `localeinfo.h`.
4. Call `localeManagerSetLocale()` with the new descriptor to activate.
.claude/network.md
-132
View File
@@ -1,132 +0,0 @@
# Network System
Source: `src/dusk/network/`, platform layers in
`src/dusk<platform>/network/`
## Overview
The network system provides a platform-agnostic API for detecting and
managing a network connection. Higher-level functionality (HTTP, sockets)
is not yet implemented in any platform. The system handles the
connection lifecycle -- connect, detect disconnect, disconnect -- and
reports the current IP address.
## Implementation status by platform
| Platform | Connection | IP info | HTTP/Requests | Notes |
|----------|-----------|---------|--------------|-------|
| **Linux** | Auto (OS) | IPv4 + IPv6 | Not implemented | `getifaddrs()` |
| **Knulli** | Auto (OS) | IPv4 + IPv6 | Not implemented | same as Linux |
| **PSP** | Manual dialog | IPv4 only | Not implemented | `sceUtilityNetconf`; SSL/HTTP modules commented out |
| **GameCube** | Manual DHCP | IPv4 only | Not implemented | `if_config()` stubbed; `net_init()` commented out |
| **Wii** | Manual DHCP | IPv4 only | Not implemented | blocking `if_config()` via System Menu Wi-Fi settings |
## Connection states
```c
typedef enum {
NETWORK_STATE_DISCONNECTED,
NETWORK_STATE_CONNECTING,
NETWORK_STATE_CONNECTED,
NETWORK_STATE_DISCONNECTING,
} networkstate_t;
```
## Global state
```c
extern network_t NETWORK;
// NETWORK.state -- current connection state
// NETWORK.platform -- platform-specific data
// NETWORK.onDisconnect -- callback fired on unexpected disconnect
```
## Core API (`network.h`)
```c
errorret_t networkInit();
errorret_t networkUpdate(); // call each frame; detects dropped connections
errorret_t networkDispose();
bool_t networkIsConnected();
void networkRequestConnection(
void (*onConnected)(void *user),
void (*onFailed)(errorret_t error, void *user),
void (*onDisconnect)(errorret_t error, void *user),
void *user
);
void networkRequestDisconnection(
void (*onComplete)(void *user),
void *user
);
```
On platforms that manage their own connection (Linux, macOS, Windows),
`networkRequestConnection` immediately calls `onConnected` if a network
interface is up, or `onFailed` if not. No `networkPlatformRequestConnection`
macro is needed.
On platforms that require explicit connection (PSP, Wii), the platform
implements `networkPlatformRequestConnection` and
`networkPlatformRequestDisconnection`.
## Network info
```c
networkinfo_t networkGetInfo();
// Only valid when NETWORK.state == NETWORK_STATE_CONNECTED.
```
```c
typedef struct {
networktype_t type; // NETWORK_TYPE_IPV4 or (ifdef) NETWORK_TYPE_IPV6
union {
networkinfoipv4_t ipv4; // uint8_t ip[4]
networkinfoipv6_t ipv6; // uint8_t ip[16] (requires DUSK_NETWORK_IPV6)
};
} networkinfo_t;
```
IPv6 support requires the `DUSK_NETWORK_IPV6` compile-time define.
## Platform-specific notes
### Linux / Knulli
Fully functional for connection detection and IP querying. No explicit
connect/disconnect step needed -- the OS manages the interface. Uses
`getifaddrs()` to find the first non-loopback running interface.
### PSP
Connection is asynchronous and driven by a state machine in
`networkPSPUpdate()`. The PSP shows the built-in network configuration
dialog (`sceUtilityNetconfInitStart`) to let the user pick a Wi-Fi
access point.
HTTP/SSL modules (`psphttp`, `pspssl`) are loaded in commented-out code
-- the infrastructure for HTTP exists but is disabled.
### GameCube
`net_init()` is commented out. Networking on GameCube is non-functional
in the current build.
### Wii
Uses `if_config()` (DHCP via libogc) to connect using the Wi-Fi settings
stored in Wii System Menu. This call **blocks** the main thread. The
connection only works when `DUSK_WII` is defined; the GameCube path
always fails.
## Adding a new platform implementation
1. Create `src/dusk<platform>/network/network<platform>.h/.c`.
2. Implement the five required functions:
`Init`, `Update`, `Dispose`, `IsConnected`, `GetInfo`.
3. Optionally implement `RequestConnection` and `RequestDisconnection`
if the platform requires an explicit connection step.
4. Create `networkplatform.h` mapping each `networkPlatform*` macro to
your functions, and defining `networkplatform_t`.
.claude/optimization.md
-83
View File
@@ -1,83 +0,0 @@
# Optimization Guidelines
Dusk must run well on severely resource-constrained hardware. The PSP
has 32 MB of RAM and a 333 MHz MIPS CPU. The GameCube has 24 MB of RAM
and a 485 MHz PowerPC CPU with no FPU for integer paths. Optimization
is not an afterthought -- it is a first-class design constraint.
## General principles
- **Measure before optimizing.** Don't guess where bottlenecks are.
Profile on the actual target hardware when possible.
- **Data-oriented design.** The ECS exists to enable cache-friendly
iteration over components. Keep hot data tightly packed (SoA over
AoS where it matters).
- **Minimize allocations.** Dynamic allocation at runtime is expensive
and causes fragmentation. Prefer fixed-size pools, arenas, and
pre-allocated arrays.
- **Avoid per-frame allocations.** Anything allocated and freed every
tick is a red flag. Use scratch buffers or static pools.
- **Avoid recursion** on constrained targets -- stack is small.
## Memory
| Platform | Total RAM | Notes |
|------------|-------------|-----------------------------------|
| GameCube | 24 MB | 16 MB main + 8 MB "Aram" (audio) |
| Wii | 88 MB | 24 MB MEM1 + 64 MB MEM2 |
| PSP | 32 MB | 4 MB reserved for OS |
| Vita | 512 MB | Much more headroom |
| Linux | Host RAM | Effectively unlimited |
Treat the GameCube 16 MB main RAM as the worst-case constraint when
designing data structures and budgets.
Always use `memoryAllocate` / `memoryFree` -- never `malloc` / `free`.
The engine allocator tracks usage and can enforce budgets per platform.
## Math
- Prefer integer math over floating-point on platforms without an FPU.
- Use fixed-point arithmetic (`int32_t` with a known scale) for physics
and animation on PSP/GameCube where FPU throughput is limited.
- SIMD / VFPU (PSP) and paired-singles (GameCube) are available but
require platform-guarded code paths under `#ifdef DUSK_PSP` etc.
- Avoid `double` entirely -- use `float_t` (32-bit) throughout.
## Rendering
- Batch draw calls aggressively. Every draw call has overhead on all
platforms; consoles are especially sensitive.
- Minimize state changes (texture binds, shader switches, etc.).
- Use display lists (GameCube/Wii) and vertex buffer objects (OpenGL)
to offload geometry to GPU memory.
- Keep texture sizes powers of two. Non-PoT textures are unsupported
or have penalties on PSP and GameCube.
## Asset loading
- Assets are loaded asynchronously via the asset loader system. Do not
block the game loop waiting for assets.
- Compress textures to the native format for each platform at build
time, not at runtime.
- Stream large assets from the filesystem rather than loading them all
at startup.
## Platform-specific notes
### PSP
- The Media Engine (ME) is a second CPU core -- use it for audio and
background decompression, not general logic.
- VFPU gives 4-wide SIMD floats; use it for matrix and vector math.
- Keep the uncached scratchpad (4 KB at 0x00010000) in mind for hot
temporary data.
### GameCube / Wii
- The GX display list pipeline is the primary rendering path; avoid
immediate-mode GX calls in the hot path.
- Texture Compression (CMPR / S3TC equivalent) halves texture memory.
- Wii: prefer MEM1 for GPU-accessed data; MEM2 for CPU-only buffers.
### PSP / Vita
- OpenGL ES has a subset of desktop OpenGL. Avoid extensions and
features that are not in the ES 1.1 / ES 2.0 core.
.claude/physics.md
-127
View File
@@ -1,127 +0,0 @@
# Physics System
Source: `src/dusk/physics/`, entity component at
`src/dusk/entity/component/physics/entityphysics.h/.c`
## Overview
Dusk uses a lightweight, custom 3D physics simulation with no external
library dependency. It is integrated with the ECS: only entities that
have both a `COMPONENT_TYPE_PHYSICS` and a `COMPONENT_TYPE_POSITION`
component participate in the simulation.
## Shapes
```c
typedef enum {
PHYSICS_SHAPE_CUBE, // Axis-aligned bounding box (AABB)
PHYSICS_SHAPE_SPHERE,
PHYSICS_SHAPE_CAPSULE, // Y-axis aligned; radius + halfHeight
PHYSICS_SHAPE_PLANE, // Infinite plane; normal + distance
} physicshapetype_t;
```
All shape pairs are supported by the collision dispatch
(`physicsTestShapeVsShape`). See `physicstest.h` for the individual
test functions.
## Body types
```c
typedef enum {
PHYSICS_BODY_STATIC, // Never moves; immovable collision surface
PHYSICS_BODY_DYNAMIC, // Driven by gravity, velocity, collisions
PHYSICS_BODY_KINEMATIC, // Moved programmatically; collides but not
// driven by the simulation (e.g. player)
} physicsbodytype_t;
```
## World and gravity
```c
extern physicsworld_t PHYSICS_WORLD;
// PHYSICS_WORLD.gravity -- default {0, -9.81, 0}
```
The simulation step is driven by `physicsManagerUpdate()`, which is
called each fixed-timestep game loop tick. It skips dynamic-timestep
sub-steps (`DUSK_TIME_DYNAMIC`).
## Simulation phases (each step)
1. **Integrate dynamics** -- apply gravity scaled by `gravityScale`,
advance velocity, update position.
2. **Dynamic vs static/kinematic** -- resolve penetration and cancel
the normal velocity component.
3. **Dynamic vs dynamic** -- split penetration 50/50; exchange
relative normal velocity.
4. **Rebuild transforms** -- call `entityPositionRebuild()` for all
affected dynamic bodies.
`PHYSICS_GROUND_THRESHOLD = 0.707f` -- a collision normal with a Y
component above this value sets `onGround = true` on the dynamic body.
## Entity component (`entityphysics_t`)
```c
typedef struct {
physicsbodytype_t type;
physicsshape_t shape;
vec3 velocity;
float_t gravityScale; // default 1.0
bool_t onGround; // set by the solver each step
} entityphysics_t;
```
Default on init: DYNAMIC body, 0.5m half-extents AABB cube,
`gravityScale = 1.0f`.
### Component API
```c
entityphysics_t *entityPhysicsGet(entityid_t, componentid_t);
void entityPhysicsSetShape(entityid_t, componentid_t, physicsshape_t);
physicsshape_t entityPhysicsGetShape(entityid_t, componentid_t);
void entityPhysicsSetVelocity(entityid_t, componentid_t, vec3);
void entityPhysicsGetVelocity(entityid_t, componentid_t, vec3 dest);
void entityPhysicsApplyImpulse(entityid_t, componentid_t, vec3);
// No-op on STATIC bodies.
bool_t entityPhysicsIsOnGround(entityid_t, componentid_t);
void entityPhysicsSetBodyType(entityid_t, componentid_t, physicsbodytype_t);
physicsbodytype_t entityPhysicsGetBodyType(entityid_t, componentid_t);
```
## Collision detection primitives (`physicstest.h`)
Each function returns `true` if overlapping and writes the push-out
normal (pointing from B toward A) and penetration depth.
| Function | Shapes |
|----------|--------|
| `physicsTestAabbVsAabb` | CUBE vs CUBE |
| `physicsTestSphereVsSphere` | SPHERE vs SPHERE |
| `physicsTestSphereVsAabb` | SPHERE vs CUBE |
| `physicsTestSphereVsPlane` | SPHERE vs PLANE |
| `physicsTestAabbVsPlane` | CUBE vs PLANE |
| `physicsTestCapsuleVsSphere` | CAPSULE vs SPHERE |
| `physicsTestCapsuleVsAabb` | CAPSULE vs CUBE |
| `physicsTestCapsuleVsPlane` | CAPSULE vs PLANE |
| `physicsTestCapsuleVsCapsule` | CAPSULE vs CAPSULE |
| `physicsTestShapeVsShape` | Any pair via dispatch |
Capsules are always Y-axis aligned. Planes are infinite (not half-spaces).
## Limitations and known gaps
- No rotation simulation -- bodies do not rotate from collisions.
- No friction or damping model yet.
- No sleeping / deactivation for resting bodies.
- No broad-phase culling: the solver is O(n^2) per phase.
This is acceptable up to the ECS entity limit (64 entities) but must
be revisited if the entity count grows.
- Capsule vs plane uses the bottom/top hemisphere centers as a
degenerate approximation -- accurate for large planes but
not for thin surfaces.
.claude/platform-dolphin.md
-288
View File
@@ -1,288 +0,0 @@
# Platform -- Dolphin (GameCube and Wii)
`DUSK_TARGET_SYSTEM`: `gamecube` / `wii`
Source layer: `src/duskdolphin/`
Renderer: libogc GX (native Nintendo hardware)
---
## Overview
GameCube and Wii are collectively called the **Dolphin** targets. They
share a single source layer (`src/duskdolphin/`) and a shared CMake base
(`cmake/targets/dolphin.cmake`). Individual targets add `DUSK_GAMECUBE`
or `DUSK_WII` on top.
Both are **big-endian** PowerPC platforms. They do **not** use SDL2 or
OpenGL -- rendering and input go through `libogc` (the open-source
GameCube/Wii SDK) and the GX hardware API directly.
---
## Hardware
| Attribute | GameCube | Wii |
|-----------|---------|-----|
| CPU | IBM PowerPC 750CL (Gekko), 485 MHz | IBM Broadway (Wii CPU), 729 MHz |
| RAM | 24 MB (16 MB MEM1 + 8 MB ARAM) | 88 MB (24 MB MEM1 + 64 MB MEM2) |
| GPU | ATI Flipper (GX) | ATI Hollywood (GX) |
| Display | 640x480 (480p max) | 640x480 (480p/576i), 480p/1080i via component |
| Storage | Memory Card (slots A/B), SD Gecko | SD card, USB, NAND |
| Endian | Big-endian | Big-endian |
Treat the **GameCube 16 MB MEM1** as the worst-case RAM budget for data
structures shared between both targets.
---
## Compile-time macros
| Macro | GameCube | Wii | Notes |
|-------|---------|-----|-------|
| `DUSK_DOLPHIN` | yes | yes | Set by `dolphin.cmake` |
| `DUSK_GAMECUBE` | yes | no | |
| `DUSK_WII` | no | yes | |
| `DUSK_INPUT_GAMEPAD` | yes | yes | |
| `DUSK_DISPLAY_WIDTH` | 640 | 640 | |
| `DUSK_DISPLAY_HEIGHT` | 480 | 480 | |
| `DUSK_THREAD_PTHREAD` | yes | yes | devkitPPC pthreads |
| `DUSK_PLATFORM_ENDIAN_BIG` | yes | yes | Not set by cmake -- apply manually |
| `DOL` | 1 | 1 | Build type token |
| `ISO` | 2 | 2 | Build type token |
| `DUSK_DOLPHIN_BUILD_TYPE` | `DOL` or `ISO` | `DOL` or `ISO` | |
| `DUSK_DOLPHIN_BUILD_ISO` | if ISO mode | if ISO mode | |
No `DUSK_SDL2`, no `DUSK_OPENGL`, no `DUSK_INPUT_KEYBOARD`,
no `DUSK_INPUT_POINTER`, no `DUSK_TIME_DYNAMIC`.
Attempting to use `DUSK_INPUT_KEYBOARD` or `DUSK_INPUT_POINTER` causes
a compile-time `#error` in `inputdolphin.h`.
---
## Endianness
**Both GameCube and Wii are big-endian.** This is the most critical
platform difference from all other targets.
- All binary asset data (`.dtf` tilesets, STL meshes, DTF headers, etc.)
must be byte-swapped when read on Dolphin.
- Use `endianLittleToHost32` / `endianLittleToHost16` etc. from
`util/endian.h` when reading any multi-byte value from a file.
- Save files are stored in little-endian order; the save stream handles
this transparently via the `saveFile*` macros.
- Network data likewise needs endian conversion.
See `.claude/util.md` (Endian section) for the full API.
---
## Display
- Fixed 640x480 resolution, driven by GX (the hardware rasteriser).
- Uses double-buffered framebuffers:
```c
typedef struct {
void *frameBuffer[2]; // double-buffered
int_t whichFrameBuffer;
GXRModeObj *screenMode;
void *fifoBuffer; // GX command FIFO, 256 KB
} displaydolphin_t;
```
- The GX pipeline uses display lists for efficient draw call batching --
avoid immediate-mode GX calls in the hot path.
- `CONF_GetAspectRatio()` returns `CONF_ASPECT_4_3` on GameCube (always)
and the user's setting on Wii. Use `systemGetAspectRatioDolphin()`.
---
## Asset loading
Two modes are selected at CMake configure time via
`DUSK_DOLPHIN_BUILD_TYPE`:
### DOL mode (default -- `DUSK_DOLPHIN_BUILD_TYPE=DOL`)
Assets are loaded from `dusk.dsk` on a FAT filesystem -- SD card on Wii
(via SD slot), or SD Gecko / SD adapter on GameCube. The loader searches
these paths in order:
```c
"/", "/Dusk", "/dusk", "/DUSK",
"/apps", "/apps/Dusk", "/apps/dusk", "/apps/DUSK",
".", "./Dusk", "./dusk", ...
```
Uses `libfat` for filesystem access.
### ISO mode (`DUSK_DOLPHIN_BUILD_TYPE=ISO`)
`dusk.dsk` is read directly off the DVD disc via the libogc DVD driver
(`assetdolphindvd.c`). Reads are 32-byte aligned:
```c
#define ASSET_DOLPHIN_DVD_ALIGN 32u
```
The DVD FST (file-system table) is parsed at init to locate the data
file. All reads go through `assetDolphinDVDRead(offset, size)` which
returns an aligned heap buffer that the caller must free.
Post-build in ISO mode, `makedolphiniso.py` produces **three disc
images** (NTSC-J, NTSC-U, PAL).
---
## Input
Uses libogc `PAD` API. Only GameCube controllers are supported (port 0
by default; up to 4 via `PAD_CHANMAX`).
Available axes (6 total per controller):
| Axis | Enum |
|------|------|
| Left stick X/Y | `INPUT_GAMEPAD_AXIS_LEFT_X/Y` |
| C-stick X/Y | `INPUT_GAMEPAD_AXIS_C_X/Y` |
| L trigger | `INPUT_GAMEPAD_AXIS_TRIGGER_LEFT` |
| R trigger | `INPUT_GAMEPAD_AXIS_TRIGGER_RIGHT` |
Axis values are normalised by dividing the raw 8-bit value by 128.0.
Deadzone: 0.2 (hardcoded).
Default bindings set at init: D-pad/left stick = directional actions,
A = ACCEPT, B = CANCEL, X = CONSOLE, Start = RAGEQUIT.
Wii Remote / Nunchuk / Classic Controller / Pro Controller are not yet
implemented (noted as TODO in `inputdolphin.h`).
---
## Save system
Uses the libogc Memory Card API (`CARD_*`) to read/write save slots.
```c
typedef struct {
card_file cardFile;
uint8_t cardBuffer[CARD_WORKAREA] __attribute__((aligned(32)));
bool_t mounted;
} savedolphin_t;
```
- Default channel: `CARD_SLOTA` (Memory Card slot A).
Override via `SAVE_DOLPHIN_CHANNEL`.
- Sector size: 8192 bytes (`SAVE_DOLPHIN_SECTOR_SIZE`).
- Buffers must be 32-byte aligned (enforced by `__attribute__((aligned(32)))`).
- Game code: `DUSK` (4 chars, override via `SAVE_DOLPHIN_GAME_CODE`).
- The card must be mounted before any read/write. `saveInitDolphin()`
mounts slot A; failures are treated as "no save present".
- Save stream handles little-endian encoding transparently -- all data
stored little-endian on the card even though the CPU is big-endian.
---
## Network
### GameCube
`net_init()` is commented out. Networking is **non-functional** on
GameCube in the current codebase. The BBA (Broadband Adapter) link
library is in a commented `# bba` in `gamecube.cmake`.
### Wii
Uses `if_config()` from libogc which reads Wi-Fi settings saved in the
Wii System Menu. The call **blocks** the main thread until DHCP
completes or fails. Wii network is available only when `DUSK_WII` is
defined; the GameCube path always fails immediately.
IPv6 is not supported on either Dolphin target.
---
## Time
- No `DUSK_TIME_DYNAMIC`. All ticks are fixed 16 ms steps.
- Tick source: `__SYS_GetSystemTime()` returns PowerPC bus ticks.
- Real time: ticks converted to microseconds via `ticks_to_microsecs()`,
then offset from the GameCube epoch (2000-01-01 00:00:00) to the UNIX
epoch (1970-01-01 00:00:00) by adding **946 684 800 seconds**.
- Timezone: always returned as 0 -- no timezone data without network time.
---
## System
Language and aspect ratio queries:
```c
// Language (used for locale selection):
systemGetLanguageDolphin();
// -> SYS_GetLanguage() on GameCube
// -> CONF_GetLanguage() on Wii
// Aspect ratio:
systemGetAspectRatioDolphin();
// -> CONF_ASPECT_4_3 always on GameCube
// -> CONF_GetAspectRatio() on Wii (4:3 or 16:9)
```
---
## Build and toolchain
Requires [devkitPro](https://devkitpro.org/) with `devkitPPC` and
`libogc` installed.
```sh
# GameCube (SD card / DOL mode)
cmake -B build \
-DDUSK_TARGET_SYSTEM=gamecube \
-DCMAKE_TOOLCHAIN_FILE=/opt/devkitpro/cmake/GameCube.cmake \
-DCMAKE_BUILD_TYPE=Release
cmake --build build
# Wii (SD card / DOL mode)
cmake -B build \
-DDUSK_TARGET_SYSTEM=wii \
-DCMAKE_TOOLCHAIN_FILE=/opt/devkitpro/cmake/Wii.cmake \
-DCMAKE_BUILD_TYPE=Release
cmake --build build
# Either target in ISO mode
cmake -B build \
-DDUSK_TARGET_SYSTEM=gamecube \
-DCMAKE_TOOLCHAIN_FILE=/opt/devkitpro/cmake/GameCube.cmake \
-DDUSK_DOLPHIN_BUILD_TYPE=ISO \
-DCMAKE_BUILD_TYPE=Release
cmake --build build
```
Post-build outputs (DOL mode): `Dusk.elf` + `Dusk.dol` (generated by
`elf2dol`). Copy `Dusk.dol` and `dusk.dsk` to the SD card.
Post-build outputs (ISO mode): `Dusk.dol` + disc images in
`NTSC-J/`, `NTSC-U/`, `PAL/` subdirectories.
Dependencies: libogc, devkitPPC, `fat` (DOL mode), cglm, zip, bz2,
zstd, z, lzma, m.
---
## Gotchas
- **Big-endian is the most common source of bugs** when porting code
from Linux. Always use `endian.h` utilities for file I/O and network.
- Memory is tight on GameCube -- 16 MB MEM1 must hold code, stack, heap,
framebuffers (2x 640x480x2 bytes), and the GX FIFO (256 KB).
- GX display lists are the correct rendering path; immediate-mode GX
calls carry heavy CPU overhead on the short FIFO pipeline.
- The GameCube has no FPU for integer paths. Avoid `double`; use
`float_t` throughout.
- `consoleInit` is shadowed to `consoleInitDolphin` to avoid conflicts
with the devkitPPC console API.
- On GameCube `CONF_GetAspectRatio()` is always 4:3; the macro is
defined to return `CONF_ASPECT_4_3` unconditionally.
- DVD reads must be 32-byte aligned and padded -- use
`ASSET_DOLPHIN_DVD_ALIGN_UP(n)` when computing read sizes in ISO mode.
.claude/platform-linux.md
-162
View File
@@ -1,162 +0,0 @@
# Platform -- Linux and Knulli
`DUSK_TARGET_SYSTEM`: `linux` / `knulli`
Source layer: `src/dusklinux/`
Renderer: OpenGL (Linux) / OpenGL ES via EGL (Knulli)
---
## Overview
Linux is the primary development target. Knulli is a Linux-based handheld
OS (e.g. Anbernic devices); it shares the `src/dusklinux/` layer entirely
and differs only in the CMake target (OpenGL ES instead of desktop OpenGL,
EGL instead of GLX, and no backtrace support).
Both targets use SDL2 for windowing and input. The window is resizable on
both (`DUSK_DISPLAY_SIZE_DYNAMIC`).
---
## Compile-time macros
| Macro | Linux | Knulli |
|-------|-------|--------|
| `DUSK_LINUX` | yes | yes |
| `DUSK_KNULLI` | no | yes |
| `DUSK_SDL2` | yes | yes |
| `DUSK_OPENGL` | yes | yes |
| `DUSK_OPENGL_ES` | no | yes |
| `DUSK_DISPLAY_SIZE_DYNAMIC` | yes | yes |
| `DUSK_INPUT_KEYBOARD` | yes | yes |
| `DUSK_INPUT_POINTER` | yes | yes |
| `DUSK_INPUT_GAMEPAD` | yes | yes |
| `DUSK_TIME_DYNAMIC` | yes | yes |
| `DUSK_NETWORK_IPV6` | yes | no |
| `DUSK_THREAD_PTHREAD` | yes | yes |
| `DUSK_CONSOLE_POSIX` | yes | no |
---
## Display
- Default logical resolution: **640x480** (`DUSK_DISPLAY_WIDTH_DEFAULT` /
`DUSK_DISPLAY_HEIGHT_DEFAULT`); game content renders at
`DUSK_DISPLAY_SCREEN_HEIGHT=240`.
- Dynamic resize: the window can be resized at any time; the engine
letterboxes/scales the logical framebuffer to fit.
- Screen mode is configurable via `SCREEN.mode` (see
`.claude/display-core.md`).
- Knulli uses OpenGL ES (GLES2) linked via EGL. Avoid any desktop
OpenGL extensions that are not in the ES2 core.
---
## Asset loading
`dusk.dsk` is located by searching a list of paths relative to the
current working directory:
```c
static const char_t *ASSET_LINUX_SEARCH_PATHS[] = {
"%s",
"../%s",
"../../%s",
"data/%s",
"../data/%s",
NULL
};
```
The first path where `dusk.dsk` is found wins. No packaging step is
required on Linux -- run from the build directory or the project root.
---
## Input
All three input types are supported:
- **Keyboard** -- SDL scancode array via `SDL_GetKeyboardState()`.
- **Pointer** -- mouse position normalized to [0, 1], scroll axes.
- **Gamepad** -- first available `SDL_GameController`; axes normalized
to [-1, 1] with a 0.2 deadzone.
See `.claude/input.md` for the full action/button API.
---
## Save system
Save files are plain files written to disk.
- Path: `./saves/save_N.dat` (override `SAVE_LINUX_PATH` to change the
directory at CMake configure time).
- Format: `SAVE_LINUX_FILE_FORMAT = "%s/save_%u.dat"` where `%u` is the
slot index.
- No OS-level dialog blocking -- saves are synchronous filesystem calls.
- Endian: host byte order (little-endian on x86/ARM).
---
## Network
- Connection is detected automatically via `getifaddrs()`. No explicit
connect step is needed.
- `networkRequestConnection` immediately calls `onConnected` if any
non-loopback interface is up, `onFailed` otherwise.
- IPv4 and IPv6 supported (`DUSK_NETWORK_IPV6`).
---
## Time
- Tick source: `SDL_GetTicks64()`.
- Real time: `clock_gettime(CLOCK_REALTIME)`.
- Dynamic timestep enabled (`DUSK_TIME_DYNAMIC`).
---
## Threading
pthreads (`DUSK_THREAD_PTHREAD`). Thread-local storage via `__thread`.
---
## Build and toolchain
No cross-compiler needed -- use the host GCC/Clang.
```sh
# Debug build
cmake -B build -DDUSK_TARGET_SYSTEM=linux -DCMAKE_BUILD_TYPE=Debug
cmake --build build
# Knulli (cross-compile to aarch64)
cmake -B build \
-DDUSK_TARGET_SYSTEM=knulli \
-DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/aarch64-linux-gnu.cmake \
-DCMAKE_BUILD_TYPE=Release
cmake --build build
```
Dependencies: `SDL2`, `OpenGL` (Linux) or `GLES2` + `EGL` (Knulli),
`pthread`, `m`.
---
## Endianness
Little-endian. Detected at CMake configure time via `TestBigEndian` and
set as `DUSK_PLATFORM_ENDIAN_LITTLE` or `DUSK_PLATFORM_ENDIAN_BIG`.
---
## Gotchas
- `DUSK_CONSOLE_POSIX` enables POSIX-specific assert backtracing (Linux
only; Knulli does not set it).
- Knulli does not set `DUSK_NETWORK_IPV6` -- IPv6 may not be available
on handheld devices.
- `DUSK_TIME_DYNAMIC` is set, so physics/networking skip dynamic sub-steps
by checking `if(TIME.dynamicUpdate) return;`.
.claude/platform-macos.md
-46
View File
@@ -1,46 +0,0 @@
# Platform -- macOS
`DUSK_TARGET_SYSTEM`: `macos`
Source layer: `src/duskmacos/` (planned, does not exist yet)
Status: **Planned -- not yet implemented**
---
## Overview
macOS desktop is a planned target. No source layer, CMake target file,
or toolchain exists yet. The intended architecture mirrors Linux: SDL2
for windowing/input, OpenGL (or Metal via MoltenVK/SDL2) for rendering.
---
## Expected macros (when implemented)
| Macro | Expected |
|-------|---------|
| `DUSK_MACOS` | yes |
| `DUSK_SDL2` | yes |
| `DUSK_OPENGL` | yes |
| `DUSK_DISPLAY_SIZE_DYNAMIC` | yes |
| `DUSK_INPUT_KEYBOARD` | yes |
| `DUSK_INPUT_POINTER` | yes |
| `DUSK_INPUT_GAMEPAD` | yes |
| `DUSK_PLATFORM_ENDIAN_LITTLE` | yes |
| `DUSK_TIME_DYNAMIC` | yes |
| `DUSK_THREAD_PTHREAD` | yes |
---
## Notes
- Will be little-endian (Apple Silicon and Intel x86-64).
- Apple deprecated OpenGL on macOS in 10.14 (Mojave). The implementation
will need to either target the deprecated OpenGL path or use MoltenVK
(Vulkan-over-Metal) with an SDL2 OpenGL layer. This decision is
pending.
- Save files will likely live in `~/Library/Application Support/`.
- Expected to share `src/dusksdl2/` and `src/duskgl/` with Linux.
- Toolchain: native Clang via Xcode Command Line Tools, or a
cross-compile from Linux with osxcross.
Update this document when the macOS target is implemented.
.claude/platform-psp.md
-200
View File
@@ -1,200 +0,0 @@
# Platform -- Sony PSP
`DUSK_TARGET_SYSTEM`: `psp`
Source layer: `src/duskpsp/`
Renderer: OpenGL ES (legacy, via PSPGL/SDL2)
---
## Overview
The PSP is a 32 MB MIPS-based handheld console running at up to 333 MHz.
It uses SDL2 (ported to PSP) for windowing and OpenGL in legacy/fixed-
function mode. The game binary and all assets are packaged together inside
a `.pbp` file -- the PSP's native executable format.
---
## Hardware
| Attribute | Value |
|-----------|-------|
| CPU | MIPS R4000 (Allegrex), up to 333 MHz |
| RAM | 32 MB (4 MB reserved for OS) |
| Display | 480x272, 16/32-bit colour |
| Storage | Memory Stick (UMD for retail; MS for homebrew) |
| Endian | Little-endian |
---
## Compile-time macros
| Macro | Set |
|-------|-----|
| `DUSK_PSP` | yes |
| `DUSK_SDL2` | yes |
| `DUSK_OPENGL` | yes |
| `DUSK_OPENGL_LEGACY` | yes |
| `DUSK_INPUT_GAMEPAD` | yes |
| `DUSK_PLATFORM_ENDIAN_LITTLE` | yes |
| `DUSK_DISPLAY_WIDTH` | 480 |
| `DUSK_DISPLAY_HEIGHT` | 272 |
| `DUSK_THREAD_PTHREAD` | yes |
No `DUSK_DISPLAY_SIZE_DYNAMIC` -- the resolution is fixed.
No `DUSK_INPUT_KEYBOARD`, no `DUSK_INPUT_POINTER`.
---
## Display
- Fixed 480x272 resolution.
- OpenGL legacy (fixed-function pipeline, `DUSK_OPENGL_LEGACY`).
- Texture dimensions **must** be powers of two (use `mathNextPowTwo`).
- VFPU (4-wide float SIMD) is available -- use it for matrix/vector hot
paths under `#ifdef DUSK_PSP`.
---
## Asset loading
Assets are packed into the **PSAR** section of the `.pbp` file by the
post-build `create_pbp_file()` CMake command. At runtime,
`assetInitPBP()` locates and opens the PSAR from the running executable's
path.
The PBP format header:
```c
typedef struct {
char_t signature[4]; // "\0PBP"
uint32_t version;
uint32_t sfoOffset;
uint32_t icon0Offset;
uint32_t icon1Offset;
uint32_t pic0Offset;
uint32_t pic1Offset;
uint32_t snd0Offset;
uint32_t pspOffset;
uint32_t psarOffset; // dusk.dsk starts here
} assetpbpheader_t;
```
`assetpbp_t` holds the open file handle and parsed header. Asset paths
inside the PSAR are ZIP paths within `dusk.dsk`.
---
## Input
Layered on SDL2. `inputInitPSP()` maps PSP physical buttons to SDL2
`SDL_CONTROLLER_BUTTON_*` constants:
| PSP button | Action |
|------------|--------|
| Cross | Accept |
| Circle | Cancel |
| Triangle | - |
| Square | - |
| L / R | Shoulder buttons |
| D-pad | Directional |
| L-Stick | Analog axes |
No keyboard or pointer input available. Attempting to use
`INPUT_BUTTON_TYPE_KEYBOARD` on PSP is undefined behaviour.
The PSP system setting `PSP_UTILITY_ACCEPT_CROSS` / `ACCEPT_CIRCLE`
swaps the Cross and Circle button roles in OS dialogs -- read this via
`systemPSPGetCrossButtonSetting()` if you need to match the system
convention.
---
## Save system
- Path: `ms0:/PSP/SAVEDATA/<TITLE_ID><slot>/save.dat`
(default title ID `DUSK00001`, configurable via `SAVE_PSP_TITLE_ID`).
- Uses `sceIo` for file I/O -- no extra dialog required for raw reads.
- PSP OS-level save/load dialogs (via `sceUtility`) are separate and
block the main loop when open (`systemGetActiveDialogType()` returns
`SYSTEM_DIALOG_TYPE_TICK_BLOCKING`).
- Do not call save functions directly from game code during a dialog.
---
## Network
Connection requires an explicit user Wi-Fi selection step via the PSP
system network dialog (`sceUtilityNetconfInitStart`).
```
networkRequestConnection(onConnected, onFailed, onDisconnect, user);
// -> shows PSP Wi-Fi selection dialog (blocking dialog type)
// -> calls onConnected or onFailed when the dialog closes
```
HTTP and SSL modules (`psphttp`, `pspssl`, `pspnet_resolver`) are
linked in `psp.cmake` but the HTTP implementation code is commented out.
The infrastructure exists for future use.
---
## Time
- Tick source: `SDL_GetTicks64()`.
- Real time: `sceRtcGetCurrentTick()` (returns microseconds).
- Dynamic timestep is **not** enabled (`DUSK_TIME_DYNAMIC` not set).
Every tick is a fixed 16 ms step.
---
## System dialogs
PSP shows OS-level dialogs for:
- Wi-Fi configuration (`networkRequestConnection`)
- Save management (if using `sceUtility` save dialogs)
Check `systemGetActiveDialogTypePSP()` to know whether the main loop
should skip rendering or ticking.
---
## Build and toolchain
Requires the [PSPDEV toolchain](https://github.com/pspdev/pspdev).
Set `PSPDEV` in your environment before configuring.
```sh
cmake -B build \
-DDUSK_TARGET_SYSTEM=psp \
-DCMAKE_TOOLCHAIN_FILE=${PSPDEV}/lib/cmake/psp.cmake \
-DCMAKE_BUILD_TYPE=Release
cmake --build build
```
Post-build output: `Dusk.pbp` (executable + assets combined).
Dependencies: SDL2-PSP, OpenGL-PSP, pspgu, pspctrl, pspdisplay,
pspaudio, pspaudiolib, psputility, pspvfpu, pspvram, pspnet,
pspnet_inet, pspnet_apctl, psphttp, pspssl, pspdebug, psphprm,
mbedtls, mbedcrypto, lzma, zip, bz2, z.
---
## Endianness
Little-endian. `DUSK_PLATFORM_ENDIAN_LITTLE` is set at compile time.
No runtime endian check is needed.
---
## Gotchas
- The PSP has only 28 MB of usable RAM after the OS. Keep asset budgets
tight -- see `.claude/optimization.md`.
- VFPU instructions are not valid on threads other than the main thread
on some firmware versions. Use `assertIsMainThread` on any code that
calls VFPU intrinsics.
- OpenGL legacy mode means no vertex/fragment shaders; rendering uses
the fixed-function pipeline via `pspgl`.
- `DUSK_TIME_DYNAMIC` is absent -- physics always runs at exactly the
fixed step rate.
.claude/platform-vita.md
-173
View File
@@ -1,173 +0,0 @@
# Platform -- PlayStation Vita
`DUSK_TARGET_SYSTEM`: `vita`
Source layer: `src/duskvita/`
Renderer: vitaGL (OpenGL-over-GXM compatibility layer)
---
## Overview
The PlayStation Vita is an ARM-based handheld with 512 MB of RAM and a
960x544 OLED/LCD display. It uses SDL2 (ported to Vita) for input
abstraction, but the graphics layer is vitaGL -- an OpenGL compatibility
shim that translates OpenGL calls to Sony's native GXM API.
The distribution format is a `.vpk` (Vita Package) file containing the
signed executable and `dusk.dsk` bundled as `dusk.dsk` at the package
root, accessible at `app0:/dusk.dsk` at runtime.
---
## Hardware
| Attribute | Value |
|-----------|-------|
| CPU | ARM Cortex-A9 quad-core, ~444 MHz |
| RAM | 512 MB |
| Display | 960x544 |
| Storage | Vita game card / memory card / internal flash |
| Endian | Little-endian |
---
## Compile-time macros
| Macro | Set |
|-------|-----|
| `DUSK_VITA` | yes |
| `DUSK_SDL2` | yes |
| `DUSK_OPENGL` | yes |
| `DUSK_OPENGL_LEGACY` | yes |
| `DUSK_INPUT_GAMEPAD` | yes |
| `DUSK_PLATFORM_ENDIAN_LITTLE` | yes |
| `DUSK_DISPLAY_WIDTH` | 960 |
| `DUSK_DISPLAY_HEIGHT` | 544 |
No `DUSK_DISPLAY_SIZE_DYNAMIC`, no `DUSK_TIME_DYNAMIC`,
no `DUSK_INPUT_KEYBOARD`, no `DUSK_INPUT_POINTER`,
no `DUSK_NETWORK_IPV6`.
---
## Display
- Fixed 960x544 resolution.
- vitaGL translates OpenGL calls to GXM. Some OpenGL calls are stubbed
out in `duskplatform.h` where vitaGL does not support them:
```c
#define glDrawArrays(type, first, count) ((void)0)
#define glDepthFunc(func) ((void)0)
#define glBlendFunc(sfactor, dfactor) ((void)0)
#define glColorTableEXT(...) ((void)0)
```
These stubs mean the Vita uses the fixed-function pipeline through
vitaGL. Do not rely on `glDrawArrays` or depth/blend state changes
being applied -- use the engine's `displaystate_t` flags instead
(see `.claude/display-shader.md`).
- `DUSK_OPENGL_LEGACY` is set. Avoid shader-based features that are
not in the fixed-function ES1 subset.
- Texture dimensions **must** be powers of two.
---
## Asset loading
`dusk.dsk` is bundled inside the `.vpk` and mounted at `app0:/` by the
Vita OS. The asset system opens it at the fixed path:
```c
#define ASSET_VITA_DSK_PATH "app0:/" ASSET_FILE_NAME
```
No path search is needed -- the file is always at that location.
---
## Input
Uses SDL2 with Vita button mapping. Buttons map to SDL2 gamepad
constants:
| Vita button | SDL2 constant |
|-------------|---------------|
| Triangle | `SDL_CONTROLLER_BUTTON_Y` |
| Cross | `SDL_CONTROLLER_BUTTON_A` |
| Circle | `SDL_CONTROLLER_BUTTON_B` |
| Square | `SDL_CONTROLLER_BUTTON_X` |
| Start | `SDL_CONTROLLER_BUTTON_START` |
| Select | `SDL_CONTROLLER_BUTTON_BACK` |
| D-pad | `SDL_CONTROLLER_BUTTON_DPAD_*` |
| L / R | `SDL_CONTROLLER_BUTTON_LEFTSHOULDER / RIGHTSHOULDER` |
| L-Stick | `SDL_CONTROLLER_AXIS_LEFTX/Y` |
Vita also has L2, R2, L3, R3 and touch surfaces -- not currently wired
into the input system.
---
## Save system
Uses `SceIofilemgr` (Vita filesystem API) for file I/O. Save data lives
in the application's sandbox on the memory card. The stream API
(`savestream_t`) handles all serialization with automatic CRC32 and
little-endian encoding (see `.claude/save.md`).
---
## Network
No network implementation exists in `src/duskvita/`. Network
functionality is not currently available on Vita.
---
## Time
No `src/duskvita/time/` directory exists -- the Vita time implementation
falls back to the SDL2 time layer if available, or is not yet
implemented.
---
## Build and toolchain
Requires the [VITASDK](https://vitasdk.org/). Set `VITASDK` in your
environment before configuring.
```sh
cmake -B build \
-DDUSK_TARGET_SYSTEM=vita \
-DCMAKE_TOOLCHAIN_FILE=$VITASDK/share/vita.cmake \
-DCMAKE_BUILD_TYPE=Release
cmake --build build
```
Post-build output: `Dusk.self` (signed executable) and `Dusk.vpk`
(installable package containing the SELF + `dusk.dsk`).
Title ID: `DUSK00001` (configurable via `VITA_TITLEID`).
Dependencies: SDL2, vitaGL, mathneon, vitashark, kubridge, SceGxm,
SceCtrl, SceAudio, SceTouch, SceRtc, SceAppUtil, zip, bz2, z, lzma.
---
## Endianness
Little-endian. `DUSK_PLATFORM_ENDIAN_LITTLE` is set at compile time.
---
## Gotchas
- vitaGL stubs several OpenGL calls. Always use the engine display state
API rather than calling `glBlendFunc` / `glDepthFunc` directly.
- `DUSK_TIME_DYNAMIC` is not set -- all ticks are fixed-step 16 ms.
- Threading: `pthread` is linked but `DUSK_THREAD_PTHREAD` is not
explicitly defined in `vita.cmake`. Verify threading behaviour before
relying on it.
- The Vita implementation is less complete than Linux and PSP -- network
and time platform layers are absent. Contributions welcome.
.claude/platform-windows.md
-46
View File
@@ -1,46 +0,0 @@
# Platform -- Windows
`DUSK_TARGET_SYSTEM`: `windows`
Source layer: `src/duskwindows/` (planned, does not exist yet)
Status: **Planned -- not yet implemented**
---
## Overview
Windows desktop is a planned target. No source layer, CMake target file,
or toolchain exists yet. The intended architecture closely mirrors Linux:
SDL2 for windowing/input, desktop OpenGL for rendering, pthreads (via
MinGW or MSVC pthreads shim) for threading.
---
## Expected macros (when implemented)
| Macro | Expected |
|-------|---------|
| `DUSK_WINDOWS` | yes |
| `DUSK_SDL2` | yes |
| `DUSK_OPENGL` | yes |
| `DUSK_DISPLAY_SIZE_DYNAMIC` | yes |
| `DUSK_INPUT_KEYBOARD` | yes |
| `DUSK_INPUT_POINTER` | yes |
| `DUSK_INPUT_GAMEPAD` | yes |
| `DUSK_PLATFORM_ENDIAN_LITTLE` | yes |
| `DUSK_TIME_DYNAMIC` | yes |
| `DUSK_THREAD_PTHREAD` | yes |
---
## Notes
- Will be little-endian (x86-64 Windows).
- Expected to share `src/dusksdl2/` and `src/duskgl/` with Linux and
Knulli; only a thin `src/duskwindows/` layer for OS-specific
functionality (save paths, system dialogs) should be needed.
- Save files will likely live in `%APPDATA%` or a sibling `saves/`
directory.
- No cross-compiler needed; MSVC or MinGW-w64 on Windows or a
cross-compile from Linux.
Update this document when the Windows target is implemented.
.claude/platforms.md
-98
View File
@@ -1,98 +0,0 @@
# Platform Support
Dusk targets a wide range of platforms, from modern desktops to classic
handheld and home consoles. New platform targets will be added over time.
## Platform index
| Platform | `DUSK_TARGET_SYSTEM` | Status | Reference |
|----------|----------------------|--------|-----------|
| Linux | `linux` | Supported | `.claude/platform-linux.md` |
| Knulli | `knulli` | Supported | `.claude/platform-linux.md` |
| Windows | `windows` | Planned | `.claude/platform-windows.md` |
| macOS | `macos` | Planned | `.claude/platform-macos.md` |
| Sony PSP | `psp` | Supported | `.claude/platform-psp.md` |
| PlayStation Vita | `vita` | Supported | `.claude/platform-vita.md` |
| Nintendo GameCube | `gamecube` | Supported | `.claude/platform-dolphin.md` |
| Nintendo Wii | `wii` | Supported | `.claude/platform-dolphin.md` |
GameCube and Wii share the `src/duskdolphin/` layer and are collectively
referred to as **Dolphin** targets throughout the codebase.
---
## Layer structure
```
src/dusk/ Core -- platform-agnostic game logic and ECS
src/duskgl/ OpenGL abstraction (Linux, Knulli, PSP, Vita)
src/dusksdl2/ SDL2 window + input (Linux, Knulli, PSP, Vita)
src/dusklinux/ Linux + Knulli platform impl
src/duskpsp/ PSP platform impl
src/duskvita/ Vita platform impl
src/duskdolphin/ GameCube + Wii platform impl
```
Dolphin is the only target that bypasses SDL2 and OpenGL entirely --
it uses native libogc GX for rendering and PAD for input.
---
## Capability macros
Each target sets a combination of these macros. Do not assume a
capability is present without checking the appropriate macro.
| Macro | Meaning |
|-------|---------|
| `DUSK_SDL2` | SDL2 is available |
| `DUSK_OPENGL` | OpenGL is available |
| `DUSK_OPENGL_ES` | OpenGL ES variant (Knulli) |
| `DUSK_OPENGL_LEGACY` | Fixed-function OpenGL (PSP, Vita) |
| `DUSK_INPUT_GAMEPAD` | Gamepad / controller input |
| `DUSK_INPUT_KEYBOARD` | Keyboard input (Linux, Knulli only) |
| `DUSK_INPUT_POINTER` | Mouse / pointer input (Linux, Knulli only) |
| `DUSK_DISPLAY_SIZE_DYNAMIC` | Window is resizable (Linux, Knulli) |
| `DUSK_TIME_DYNAMIC` | Dynamic timestep available (Linux, Knulli) |
| `DUSK_THREAD_PTHREAD` | pthreads available |
| `DUSK_NETWORK_IPV6` | IPv6 supported (Linux only) |
| `DUSK_PLATFORM_ENDIAN_BIG` | Big-endian byte order |
| `DUSK_PLATFORM_ENDIAN_LITTLE` | Little-endian byte order |
| `DUSK_DOLPHIN` | Any Dolphin target |
| `DUSK_DOLPHIN_BUILD_ISO` | Dolphin DVD-ISO asset mode |
| `DUSK_CONSOLE_POSIX` | POSIX assert backtrace (Linux only) |
---
## Quick comparison
| | Linux | Knulli | PSP | Vita | GameCube | Wii |
|-|-------|--------|-----|------|----------|-----|
| SDL2 | yes | yes | yes | yes | no | no |
| OpenGL | desktop | ES2 | legacy | vitaGL | no | no |
| Endian | little | little | little | little | **big** | **big** |
| Dynamic resize | yes | yes | no | no | no | no |
| Dynamic timestep | yes | yes | no | no | no | no |
| Keyboard | yes | yes | no | no | no | no |
| Pointer/mouse | yes | yes | no | no | no | no |
| Network | full | full | partial | no | no | partial |
| Save storage | file | file | MS/SAVEDATA | SceIo | Mem Card | SD/NAND |
| Asset source | dsk file | dsk file | inside .pbp | inside .vpk | SD or DVD | SD or DVD |
---
## Abstraction pattern
Platform-specific implementations are wired in via `#define` macros in
each platform's `displayplatform.h`, `inputplatform.h`, etc., which the
core calls through. Functions that a platform does not support are
simply left undefined -- the core guards calls with `#ifdef`.
## Adding platform-specific code
- Put new code under `src/dusk<platform>/` in the matching subsystem
folder.
- Gate any core call-site with `#ifdef DUSK_<PLATFORM>` or the
relevant capability macro.
- Keep `src/dusk/` free of platform `#ifdef`s -- delegate through
the platform header macros instead.
.claude/save.md
-148
View File
@@ -1,148 +0,0 @@
# Save System
Source: `src/dusk/save/`, platform layers in `src/dusk<platform>/save/`
## Overview
The save system provides multi-slot persistent storage. Each slot
maps to one `savefile_t`. Platform implementations handle the actual
read/write (memory card on GameCube/Wii, EEPROM/flash on PSP,
filesystem on Linux).
## Global state
```c
extern save_t SAVE;
// SAVE.files[SAVE_FILE_COUNT_MAX] -- one per slot
// SAVE.platform -- platform-specific state
```
## API
```c
errorret_t saveInit(void);
errorret_t saveDispose(void);
errorret_t saveLoad(uint8_t slot); // read slot from storage -> SAVE.files[slot]
errorret_t saveWrite(uint8_t slot); // write SAVE.files[slot] -> storage
errorret_t saveDelete(uint8_t slot); // delete slot from storage
bool_t saveExists(uint8_t slot); // true if a save file is present
savefile_t *saveGet(uint8_t slot); // pointer to the in-memory slot data
```
Slot indices are 0-based, range `[0, SAVE_FILE_COUNT_MAX - 1]`.
## Save file structure (`savefile.h`)
`savefile_t` is a plain struct written verbatim to storage. Keep it
small and use fixed-width integer types (`uint8_t`, `int32_t`, etc.)
to ensure cross-platform binary compatibility.
**Endianness:** storage is always written in little-endian byte order.
Use the `endian.h` utilities when reading fields on big-endian targets
(GameCube, Wii). See `.claude/util.md`.
**Versioning:** include a version field at the start of `savefile_t`.
Check it on load and handle mismatches gracefully (reset to defaults
rather than crashing on corrupt data).
## Save stream (`savestream.h`)
`savestream_t` is a cursor-based reader/writer used to serialize
`savefile_t` to/from a raw byte buffer. Platform implementations
use it to abstract the I/O layer.
```c
typedef struct {
bool_t found;
uint32_t checksum;
uint32_t expectedChecksum;
saveplatformstream_t platform;
} savestream_t;
```
### Typed read/write macros
Use the `saveFile*` macros inside `saveFileLoad` and `saveFileWrite`.
All multi-byte values are stored in little-endian order; endian
conversion is handled automatically.
```c
saveFileReadHeader(stream, headerBuf)
saveFileWriteHeader(stream, headerBuf)
saveFileReadVersion(stream, &version)
saveFileWriteVersion(stream, &version)
saveFileReadBool(stream, &boolField)
saveFileWriteBool(stream, &boolField)
saveFileReadInt8(stream, &i8) saveFileWriteInt8(stream, &i8)
saveFileReadUInt8(stream, &u8) saveFileWriteUInt8(stream, &u8)
saveFileReadInt16(stream, &i16) saveFileWriteInt16(stream, &i16)
saveFileReadUInt16(stream, &u16) saveFileWriteUInt16(stream, &u16)
saveFileReadInt32(stream, &i32) saveFileWriteInt32(stream, &i32)
saveFileReadUInt32(stream, &u32) saveFileWriteUInt32(stream, &u32)
saveFileReadInt64(stream, &i64) saveFileWriteInt64(stream, &i64)
saveFileReadUInt64(stream, &u64) saveFileWriteUInt64(stream, &u64)
saveFileReadFloat(stream, &f) saveFileWriteFloat(stream, &f)
saveFileReadString(stream, buf, maxLen)
saveFileWriteString(stream, str, maxLen)
saveFileReadDate(stream, &epoch)
saveFileWriteDate(stream, &epoch)
```
Each macro expands to `errorChain(saveStreamRead/WriteXxxImpl(...))`.
A failing read/write propagates the error up from `saveFileLoad` /
`saveFileWrite`.
### Typical saveFileLoad / saveFileWrite pattern
```c
errorret_t saveFileLoad(savestream_t *stream, savefile_t *file) {
char_t header[SAVE_FILE_HEADER_SIZE];
saveFileReadHeader(stream, header);
saveFileReadVersion(stream, &file->version);
saveFileReadInt32(stream, &file->score);
// ... remaining fields ...
errorOk();
}
errorret_t saveFileWrite(savestream_t *stream, savefile_t *file) {
char_t header[SAVE_FILE_HEADER_SIZE] = SAVE_FILE_HEADER;
saveFileWriteHeader(stream, header);
saveFileWriteVersion(stream, &file->version);
saveFileWriteInt32(stream, &file->score);
// ... remaining fields ...
errorOk();
}
```
After `saveFileWrite` completes, the platform layer calls
`saveStreamFinalizeWriteImpl` which seeks back and writes the CRC32.
After `saveFileLoad`, the platform calls `saveStreamVerifyChecksumImpl`
to confirm the CRC matches.
## Platform notes
| Platform | Storage mechanism |
|----------|------------------|
| Linux | File in user home / working directory |
| Knulli | File on filesystem |
| PSP | EEPROM / memory stick via `sceIo` |
| GameCube | Memory Card via libogc `CARD_*` API |
| Wii | NAND filesystem via libogc or SD card |
Platform-specific save implementations go in `src/dusk<platform>/save/`
and are wired in via `save/saveplatform.h` macros.
## PSP note
PSP save dialogs are OS-level UI shown via `sceUtility`. When a dialog
is open, `systemGetActiveDialogType()` returns a blocking type so the
engine pauses the main loop. Never call save functions directly from
game code without going through the engine's dialog guard.
.claude/scene.md
-138
View File
@@ -1,138 +0,0 @@
# Scene System
Source: `src/dusk/scene/`
## Overview
The scene system is the top-level coordinator for a running game state.
It manages one active scene at a time. Scenes are JS scripts -- each
scene is a `.js` asset file that exports an object with lifecycle hooks.
The scene system loads, ticks, and tears down these scripts, while the
C side runs the ECS and render pipeline on each tick.
## Scene lifecycle (C side)
```c
extern scene_t SCENE;
errorret_t sceneInit(void); // initialise the scene manager
errorret_t sceneUpdate(void); // process pending transition, tick active scene
errorret_t sceneRender(void); // render entities + render pipeline + UI
errorret_t sceneDispose(void); // dispose the active scene immediately
```
`sceneUpdate` each tick:
1. Checks for a pending scene transition and performs it (dispose old,
load and init new).
2. Calls the JS scene's `update()` hook.
3. Calls `entityManagerUpdate()` to fire all entity update callbacks.
`sceneRender` each tick:
1. Binds the screen.
2. Calls `sceneRenderPipeline()` -- renders all entities with a
`COMPONENT_TYPE_RENDERABLE` in priority order.
3. Renders UI.
4. Calls the JS scene's `render()` hook (for any custom drawing).
5. Unbinds the screen.
## Scene lifecycle (JS side)
A scene file exports a plain object with these optional hooks:
```js
var scene = {};
scene.init = async function() {
// Load assets, create entities, set up state.
// May be async -- await asset loads here.
};
scene.update = function() {
// Called each fixed-timestep tick.
};
scene.render = function() {
// Called each render tick, after ECS renderables.
};
scene.dispose = function() {
// Clean up entities and state.
};
module.exports = scene;
```
See `CLAUDE.md` -- "JavaScript (asset scripts)" for JS style rules.
## Render pipeline (`scenerenderpipeline.h`)
`sceneRenderPipeline(cameraEntityId)` gathers all active
`COMPONENT_TYPE_RENDERABLE` components, sorts them by effective
priority, and draws each one using its shader.
**Priority rules:**
- `renderable.priority != 0` -- use that value directly.
- `renderable.priority == 0` -- auto-derive: opaque geometry sorts
before transparent geometry; sprite batches sort before shader
materials; etc.
- Lower priority number = drawn first (behind); higher = drawn last
(on top).
The shader used for each renderable:
- `ENTITY_RENDERABLE_TYPE_SPRITEBATCH` and `CUSTOM` default to
`SHADER_LIST_SHADER_UNLIT`.
- `ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL` uses the shader indexed by
`renderable.data.material.shaderType` in `SHADER_LIST_DEFS`.
## Transitioning between scenes
Scene transitions are handled entirely in JS via the `Scene` global.
The `Scene` object is a singleton with:
```js
// Switch to a new scene. Calls dispose() on the current scene, then
// init() on the new one. Both happen synchronously this tick.
Scene.set(newSceneObject);
// The current scene object (may be null):
Scene.current
```
Typical scene-switch pattern:
```js
// Inside a scene's update or event handler:
const nextScene = require("scenes/gameplay.js");
Scene.set(nextScene);
```
`Scene.set` is synchronous -- it calls `dispose` on the old scene and
`init` on the new scene before returning. If `init` needs async work
(loading assets), use an async function and `await` inside `init`:
```js
nextScene.init = async function() {
await batch.load(); // wait for assets before proceeding
};
```
The C side does not defer the transition; the switch happens inside
the current `sceneUpdate` call.
## Relationship to the engine loop
```
engineUpdate()
timeUpdate()
inputUpdate()
physicsManagerUpdate()
scriptUpdate() <- runs JS microjobs
sceneUpdate() <- JS update + ECS entity updates
engineUpdate() -> sceneRender()
screenBind()
sceneRenderPipeline() <- ECS renderables sorted by priority
uiRender()
sceneRender (JS hook)
screenUnbind / screenRender
```
.claude/script-promises.md
-104
View File
@@ -1,104 +0,0 @@
# Script -- Async Promises (`scriptpromisepend_t`)
Source: `src/dusk/script/scriptpromisepend.h`
See also: `.claude/script.md`
---
## Overview
When a C module needs to resolve a JS `Promise` from an asynchronous
C event (e.g. an asset finishing loading, a network response arriving),
use `scriptpromisepend_t`. The pattern avoids heap allocation by using
a fixed-size pending slot array declared in the module.
---
## Declaring the pending array
```c
#define MY_MODULE_PENDING_MAX 8
static scriptpromisepend_t MY_PENDING[MY_MODULE_PENDING_MAX];
static uint32_t MY_PENDING_COUNT = 0;
```
---
## Add a pending promise
Called from the JS-facing function that returns the Promise:
```c
jerry_value_t promise = jerry_create_promise();
scriptPromisePendAdd(
MY_PENDING, &MY_PENDING_COUNT, MY_MODULE_PENDING_MAX,
key, // opaque void * used to match the resolve/reject later
promise
);
return jerry_acquire_value(promise); // return a copy to the caller
```
The `key` should be a stable pointer that uniquely identifies the
async operation -- e.g. an `assetentry_t *`, a network request handle,
or a pointer to a fixed-size slot in the module.
---
## Resolve or reject
Called when the C event fires, typically from `moduleUpdate` or an
event callback:
```c
// On success:
scriptPromisePendResolve(
MY_PENDING, &MY_PENDING_COUNT,
key, jerry_undefined() // or a result value
);
// On failure:
jerry_value_t err = jerry_create_error(
JERRY_ERROR_COMMON, (const jerry_char_t *)"reason"
);
scriptPromisePendReject(MY_PENDING, &MY_PENDING_COUNT, key, err);
jerry_release_value(err);
```
Both macros remove the slot from the pending array after settling.
---
## Guard against double-submit
```c
if(scriptPromisePendHas(MY_PENDING, MY_PENDING_COUNT, key)) {
// already waiting -- return the existing promise or an error
}
```
---
## Module teardown
Free all pending promises before cleaning up events or other state:
```c
scriptPromisePendFreeAll(MY_PENDING, &MY_PENDING_COUNT);
```
This rejects all still-pending promises and resets the count to 0.
Call it from the module's `Dispose` function, **before** any backing
data (asset entries, event subscriptions) is torn down.
---
## Design notes
- `MY_MODULE_PENDING_MAX` sets a hard cap on concurrent async ops.
Exceeding it is a runtime assertion -- size the array to the maximum
realistic concurrency for the module.
- The key is opaque (`void *`); the system does not dereference it.
A raw integer cast to `void *` is fine if no pointer is available.
- `scriptUpdate()` runs the JerryScript microjob queue each frame,
which is what processes `.then()` chains after a resolve/reject.
.claude/script.md
-167
View File
@@ -1,167 +0,0 @@
# Script System (JerryScript)
Source: `src/dusk/script/`, modules at `src/dusk/script/module/`
## Overview
The engine embeds **JerryScript** as its scripting runtime. Game scenes
and logic are authored in JavaScript (ES5 subset). The script system
initialises JerryScript, registers all built-in C modules as JS globals,
and runs the event loop each tick.
The full rules for writing JS asset scripts are in `CLAUDE.md` under
"JavaScript (asset scripts)". This doc covers the C-side module system.
## Script lifecycle
```c
errorret_t scriptInit(); // start JerryScript, register all modules
errorret_t scriptUpdate(); // run pending microjobs (call once per frame)
errorret_t scriptDispose(); // shut down JerryScript
errorret_t scriptExecString(const char_t *source);
// Evaluate a JS source string in global scope.
errorret_t scriptExecFile(const char_t *path);
// Load + eval a script from the asset archive. Result cached by asset
// system -- repeated calls with the same path do not re-execute.
```
## Module registration
All C modules are initialised in `src/dusk/script/module/modulelist.c`:
```c
void moduleListInit(void); // called by scriptInit
void moduleListDispose(void); // called by scriptDispose
```
Each module's `Init` is called once. The module registers its
properties and methods on `scriptproto_t` objects (see below), which
become JS globals.
## Writing a C module -- the `scriptproto_t` pattern
A `scriptproto_t` represents a JS class prototype backed by a C struct.
### 1. Declare in the header
```c
// moduleMything.h
extern scriptproto_t MODULE_MYTHING_PROTO;
// Init and dispose for the module itself:
void moduleMyThingInit(void);
void moduleMyThingDispose(void);
```
### 2. Implement
```c
// moduleMything.c
scriptproto_t MODULE_MYTHING_PROTO;
// JS-callable function using the convenience macro:
moduleBaseFunction(myThingDoSomething) {
moduleBaseRequireArgs(1);
moduleBaseRequireNumber(0);
float_t x = moduleBaseArgFloat(0);
// ... do work ...
return jerry_undefined();
}
void moduleMyThingInit(void) {
scriptProtoInit(
&MODULE_MYTHING_PROTO,
"MyThing", // JS global name; NULL to skip registration
sizeof(mything_t),
myThingCtor // constructor handler, or NULL
);
// Instance methods:
scriptProtoDefineFunc(
&MODULE_MYTHING_PROTO, "doSomething", myThingDoSomething
);
// Instance property (get/set):
scriptProtoDefineProp(
&MODULE_MYTHING_PROTO, "x", myThingGetX, myThingSetX
);
// Static method:
scriptProtoDefineStaticFunc(
&MODULE_MYTHING_PROTO, "create", myThingCreate
);
}
```
### 3. Register
In `modulelist.c`: `#include` the header and call `moduleMyThingInit()`
in `moduleListInit()` (and `Dispose` in `moduleListDispose()`).
## `moduleBaseFunction` macro
```c
moduleBaseFunction(myFn) {
// callInfo, args[], argc available
moduleBaseRequireArgs(2);
moduleBaseRequireNumber(0);
moduleBaseRequireString(1);
float_t x = moduleBaseArgFloat(0);
int32_t n = moduleBaseArgInt(0);
bool_t b = moduleBaseArgBool(0);
float_t opt = moduleBaseOptFloat(2, 0.0f); // optional with default
// Error propagation:
errorret_t ret = someCall();
if(errorIsNotOk(ret)) return moduleBaseThrowError(ret);
return jerry_undefined(); // or jerry_boolean(true) etc.
}
```
## Wrapping C values in JS objects
```c
// Create a JS object wrapping a copy of a C value:
jerry_value_t obj = scriptProtoCreateValue(&MY_PROTO, &myValue);
// Unwrap back to C pointer:
mything_t *ptr = scriptProtoGetValue(&MY_PROTO, jsObj);
// ptr is NULL if jsObj is not an instance of MY_PROTO.
```
## Utility helpers (`modulebase.h`)
| Helper | Purpose |
|--------|---------|
| `moduleBaseThrow(msg)` | Return a JS TypeError |
| `moduleBaseThrowError(ret)` | Convert `errorret_t` -> JS error |
| `moduleBaseToString(val, buf, len)` | Jerry value -> C string |
| `moduleBaseGetProp(obj, name)` | Get object property by name |
| `moduleBaseWrapPointer(ptr)` | Wrap a raw pointer in a JS object |
| `moduleBaseUnwrapPointer(val)` | Unwrap a raw pointer |
| `moduleBaseSetValue(name, val)` | Set a global JS variable |
| `moduleBaseSetNumber(name, n)` | Set a global JS number |
| `moduleBaseSetInt(name, n)` | Set a global JS integer |
| `moduleBaseDefineMethod(obj, name, fn)` | Add method to any JS object |
| `moduleBaseDefineGlobalMethod(name, fn)` | Add method to global scope |
## Async JS -- pending promises (`scriptpromisepend.h`)
When a C module needs to resolve a JS `Promise` from an asynchronous
C event, use `scriptpromisepend_t`. Each module declares a fixed-size
pending slot array; the helpers add/resolve/reject by an opaque key.
Full API and design notes: `.claude/script-promises.md`
## Type declarations (`.d.ts`)
Every module that is accessible from JS **must** have a corresponding
TypeScript declaration file in `types/`. The CLAUDE.md checklist
requires updating these whenever a `.c` module file changes.
- Add `types/<category>/mymod.d.ts`
- Add `/// <reference path="..." />` to `types/index.d.ts`
.claude/tests.md
-111
View File
@@ -1,111 +0,0 @@
# Tests and Assertions
## Test infrastructure
Tests live in `test/` and mirror the `src/dusk/` directory structure.
Enable with `-DDUSK_BUILD_TESTS=ON`. The test runner is **cmocka**.
### Entry point
Every test file includes `dusktest.h`, which pulls in `dusk.h` and
`assert/assert.h`. When `DUSK_TEST_ASSERT` is defined, `assert.h`
includes `cmocka.h` and redirects assertion failures through
`mock_assert()` instead of calling `abort()`.
### Test function signature
```c
static void test_something(void **state) {
// ... setup ...
// ... exercise ...
// ... assert ...
assert_int_equal(memoryGetAllocatedCount(), 0); // leak check
}
```
### Registering and running tests
```c
int main(void) {
const struct CMUnitTest tests[] = {
cmocka_unit_test(test_errorThrow),
cmocka_unit_test(test_errorOk),
};
return cmocka_run_group_tests(tests, NULL, NULL);
}
```
Use `cmocka_unit_test_setup_teardown()` when a test needs per-test
setup or teardown callbacks.
### Assertion mix
Tests use **two** sets of assertion macros:
| Origin | When to use |
|--------|-------------|
| cmocka: `assert_int_equal()`, `assert_non_null()` etc. | Validate results inside test functions |
| Dusk: `assertTrue()`, `assertNotNull()` etc. | Exercise the code under test (these may fire and need catching) |
To assert that a Dusk assertion fires, use cmocka's mock system:
```c
expect_assert_failure(assertTrueImpl(__FILE__, __LINE__, false, "msg"));
```
### Memory leak discipline
Every test function must end by asserting:
```c
assert_int_equal(memoryGetAllocatedCount(), 0);
```
This ensures all allocations from the code under test were freed.
---
## Assertion system
Source: `src/dusk/assert/`
### Runtime vs test mode
| Mode | Trigger | Effect on failure |
|------|---------|-------------------|
| Runtime (default) | Release / non-test builds | Logs the message + backtrace, then calls `abort()` |
| Test (`DUSK_TEST_ASSERT`) | `-DDUSK_TEST_ASSERT` build flag | Routes through cmocka `mock_assert()` for controlled catching |
| Faked (`DUSK_ASSERTIONS_FAKED`) | Defined by platform or test | All macros become no-ops (`((void)0)`) |
### Available macros
| Macro | Description |
|-------|-------------|
| `assertTrue(x, msg)` | Fails if `x` is false |
| `assertFalse(x, msg)` | Fails if `x` is true |
| `assertNotNull(ptr, msg)` | Fails if `ptr` is NULL |
| `assertNull(ptr, msg)` | Fails if `ptr` is not NULL |
| `assertUnreachable(msg)` | Unconditional failure; marks unreachable code |
| `assertDeprecated(msg)` | Marks a code path as deprecated |
| `assertStringEqual(a, b, msg)` | Fails if strings differ |
| `assertStrLenMax(str, len, msg)` | Fails if `strlen(str) >= len` |
| `assertStrLenMin(str, len, msg)` | Fails if `strlen(str) < len` |
| `assertIsMainThread(msg)` | Fails if called from a non-main thread |
| `assertNotMainThread(msg)` | Fails if called from the main thread |
| `assertStructSize(type, size)` | Compile-time size check via `_Static_assert` |
### Thread tracking
`assertInit()` records the main thread ID (pthreads). The main-thread
assertions compare against this stored ID. Call `assertInit()` once at
startup before spawning any threads.
### Usage guidelines
- Prefer the specific macro over a bare `assertTrue` for clarity
(e.g. use `assertNotNull` instead of `assertTrue(ptr != NULL, ...)`).
- Use `assertUnreachable` in `default:` cases of exhaustive switches.
- Use `assertStructSize` to guard struct layouts that must match
a known binary format or a platform ABI.
- Do not use asserts for expected error paths -- use `errorThrow`
instead. Asserts are for programmer mistakes, not runtime errors.
.claude/threading.md
-100
View File
@@ -1,100 +0,0 @@
# Threading System
Source: `src/dusk/thread/`
## Platform support
Threading currently requires **pthreads** (`DUSK_THREAD_PTHREAD`). The
implementation lives in the core thread files and is guarded by that
compile-time flag -- there are no separate per-platform thread
directories.
Thread-local storage uses the `THREAD_LOCAL` macro, which maps to
`__thread` when pthreads is available. This is used by the error system
to give each thread its own `ERROR_STATE`.
## Thread lifecycle
Threads follow a strict state machine:
```
STOPPED -> STARTING -> RUNNING -> STOP_REQUESTED -> STOPPED
```
- `threadStart()` -- blocking: starts the thread and waits until it
reaches RUNNING.
- `threadStop()` -- blocking: requests stop and waits until STOPPED.
- `threadStartRequest()` -- non-blocking equivalent of `threadStart`.
- `threadStopRequest()` -- non-blocking equivalent of `threadStop`.
The thread callback polls `threadShouldStop()` to know when to exit.
Never kill a thread forcefully -- always let it stop cooperatively.
## Thread API
```c
void threadInit(thread_t *thread, errorret_t (*callback)(thread_t *t));
// Initialise; callback is the thread entry point.
errorret_t threadStart(thread_t *thread);
// Start and block until RUNNING.
errorret_t threadStop(thread_t *thread);
// Request stop, block until STOPPED.
void threadStartRequest(thread_t *thread);
void threadStopRequest(thread_t *thread);
// Non-blocking variants.
bool_t threadShouldStop(const thread_t *thread);
// Call from inside the thread callback to know when to exit.
```
## Mutex API (`threadmutex.h`)
Each `threadmutex_t` wraps a pthread mutex and a condition variable.
```c
void threadMutexInit(threadmutex_t *mutex);
void threadMutexDispose(threadmutex_t *mutex);
void threadMutexLock(threadmutex_t *mutex);
void threadMutexUnlock(threadmutex_t *mutex);
bool_t threadMutexTryLock(threadmutex_t *mutex);
// Returns true if the lock was acquired; false if already held.
void threadMutexWaitLock(threadmutex_t *mutex);
// Block until signalled (like pthread_cond_wait).
// Must be called while holding the lock.
void threadMutexSignal(threadmutex_t *mutex);
// Wake one waiter.
```
## Usage example
```c
static errorret_t workerCallback(thread_t *t) {
while(!threadShouldStop(t)) {
// do work
}
errorOk();
}
thread_t worker;
threadInit(&worker, workerCallback);
errorChain(threadStart(&worker));
// ... later ...
errorChain(threadStop(&worker));
```
## Thread safety rules
- The error system (`ERROR_STATE`) is thread-local -- each thread has
its own error state. Do not pass `errorret_t` across thread
boundaries without copying the message and lines strings first.
- Asset loading: the background thread calls `loadAsync`; the main
thread calls `loadSync`. Never call GPU or SDL functions from the
loader background thread.
- Use `assertIsMainThread()` / `assertNotMainThread()` to guard
functions that have thread affinity requirements.
.claude/time.md
-115
View File
@@ -1,115 +0,0 @@
# Time System
Source: `src/dusk/time/`, platform layers in `src/dusk<platform>/time/`
## Global state
```c
extern dusktime_t TIME;
```
```c
typedef struct {
float_t delta; // Fixed step size in seconds (DUSK_TIME_STEP)
float_t time; // Accumulated game time in seconds
// Only present when DUSK_TIME_DYNAMIC is defined:
float_t lastNonDynamic;
bool_t dynamicUpdate; // true on sub-step ticks
float_t dynamicDelta; // real elapsed seconds this frame
float_t dynamicTime; // accumulated real time
} dusktime_t;
```
## Fixed vs dynamic timestep
### Fixed timestep (default)
`DUSK_TIME_STEP` defaults to `16ms / 1000 = 0.016f` seconds (62.5 Hz).
Every call to `timeUpdate()` advances `TIME.time` by exactly
`DUSK_TIME_STEP` and sets `TIME.delta = DUSK_TIME_STEP`. This is the
safe, deterministic mode for physics and game logic.
### Dynamic timestep (`DUSK_TIME_DYNAMIC`)
When enabled, `timeUpdate()` calls the platform tick hook to measure
actual elapsed time. It fires a "non-dynamic" step (`dynamicUpdate =
false`, `delta = DUSK_TIME_STEP`) once per fixed interval, and
"dynamic" sub-steps (`dynamicUpdate = true`) in between. Systems that
must run on the fixed interval (physics, networking) skip the dynamic
sub-steps by checking:
```c
if(TIME.dynamicUpdate) return;
```
## Platform hooks
Each platform provides three macros in its `time/timeplatform.h`:
| Macro | Purpose |
|-------|---------|
| `timeTickPlatform()` | Sample the hardware timer |
| `timeGetDeltaPlatform()` | Return seconds since last tick |
| `timeGetRealPlatform()` | Return epoch seconds since 1970 |
| `timeGetRealTimeZonePlatform()` | Return local timezone offset (seconds) |
`timeTickPlatform` and `timeGetDeltaPlatform` are only required when
`DUSK_TIME_DYNAMIC` is defined.
## Platform implementations
| Platform | Tick source | Real time source |
|----------|------------|-----------------|
| Linux | `SDL_GetTicks64()` (via SDL2) | `clock_gettime(CLOCK_REALTIME)` |
| Knulli | `SDL_GetTicks64()` (via SDL2) | `clock_gettime(CLOCK_REALTIME)` |
| PSP | `SDL_GetTicks64()` (via SDL2) | `sceRtcGetCurrentTick()` (microseconds) |
| GameCube | none (fixed step only) | `ticks_to_microsecs(__SYS_GetSystemTime())` + 2000->1970 offset |
| Wii | none (fixed step only) | same as GameCube |
GameCube / Wii note: the hardware timer returns ticks since
2000-01-01, so an offset of 946684800 seconds is added to convert to
UNIX epoch. The timezone offset is always returned as 0.0 on Dolphin
(timezone is not available without network time).
## Epoch time (`timeepoch.h`)
```c
typedef struct {
double_t time; // raw UTC seconds since 1970
double_t timeZone; // timezone offset in seconds
double_t offsetTime; // time + timeZone
} dusktimeepoch_t;
dusktimeepoch_t timeGetEpoch(void);
// Returns current time in local timezone.
```
### Epoch helpers
```c
int32_t timeEpochGetYear(epoch);
int32_t timeEpochGetMonth(epoch); // 1-12
int32_t timeEpochGetDayOfMonth(epoch); // 1-31
int32_t timeEpochGetHours(epoch); // 0-23
int32_t timeEpochGetMinutes(epoch); // 0-59
int32_t timeEpochGetSeconds(epoch); // 0-59
bool_t timeEpochIsLeapYear(year);
size_t timeEpochFormat(
dusktimeepoch_t epoch,
const char_t *format, // %Y %m %d %H %M %S
char_t *buffer,
size_t bufferSize
);
```
## Adding a new platform time implementation
1. Create `src/dusk<platform>/time/time<platform>.h/.c`.
2. Implement `timeGetReal<Platform>()` and
`timeGetRealTimeZone<Platform>()`.
3. If `DUSK_TIME_DYNAMIC`: also implement `timeTick<Platform>()` and
`timeGetDelta<Platform>()`.
4. Create `src/dusk<platform>/time/timeplatform.h` with the `#define`
macros pointing to your functions.
.claude/ui.md
-226
View File
@@ -1,226 +0,0 @@
# UI System
Source: `src/dusk/ui/`
See also: `.claude/display-spritebatch.md`, `.claude/display-text.md`,
`.claude/display-color.md`
---
## Overview
The UI system renders overlaid interface elements on top of the scene
each frame. It is called by the engine after the scene render pipeline
and before the screen unbind -- game code does not drive it directly.
All UI elements render through the global SpriteBatch.
---
## Lifecycle
```c
extern ui_t UI;
errorret_t uiInit(void);
void uiUpdate(void);
errorret_t uiRender(void);
void uiDispose(void);
```
`uiUpdate` is called each game tick; `uiRender` is called each render
tick. The engine calls both automatically -- do not call them from
game scripts.
---
## Element registration (`uielement.h`)
```c
typedef struct {
uielementtype_t type; // UI_ELEMENT_TYPE_NULL or UI_ELEMENT_TYPE_NATIVE
errorret_t (*draw)(); // draw callback
} uielement_t;
extern uielement_t UI_ELEMENTS[]; // registered element array
```
`uiRender` iterates `UI_ELEMENTS` and calls each element's `draw`
callback. Elements register themselves during `uiInit`.
---
## Elements
### uiframe_t -- 9-slice border (`uiframe.h`)
A resizable bordered panel rendered using 9-slice (9-patch) technique
from a 3x3 tileset.
```c
typedef struct {
tileset_t tileset;
texture_t *texture;
} uiframe_t;
errorret_t uiFrameInit(uiframe_t *frame);
errorret_t uiFrameDraw(
const uiframe_t *frame,
const float_t x,
const float_t y,
const float_t width,
const float_t height
);
void uiFrameDispose(uiframe_t *frame); // does not dispose texture
```
`uiFrameDraw` pushes 9 quads (corners + edges + centre) to the
SpriteBatch without flushing. The caller must call `spriteBatchFlush()`
after all sprites for a draw pass are buffered.
---
### uitextbox_t -- typewriter dialogue box (`uitextbox.h`)
A global single-instance dialogue box that displays text one character
at a time with word-wrap and multi-page support.
```c
extern uitextbox_t UI_TEXTBOX;
errorret_t uiTextboxInit(void);
void uiTextboxDispose(void);
```
**Setting text:**
```c
uiTextboxSetText("Hello, world!");
// Automatically word-wraps and paginates.
// Resets currentPage and scroll to 0.
```
**Tick update (called from script `update` or uiUpdate):**
```c
uiTextboxUpdate();
// Advances typewriter by UI_TEXTBOX_SCROLL_CHARS_PER_TICK (1) each
// fixed tick. Skipped on dynamic sub-ticks.
```
**Page control:**
```c
bool_t uiTextboxPageIsComplete(void); // scroll revealed full page
bool_t uiTextboxHasNextPage(void); // more pages remain
void uiTextboxNextPage(void); // advance; no-op on last page
int32_t uiTextboxGetPageCharCount(void);
```
**Events:**
```c
// Fires when the current page is fully scrolled into view:
UI_TEXTBOX.onPageComplete
// Fires when the last page has been fully scrolled:
UI_TEXTBOX.onLastPage
```
Subscribe via the event system (see `.claude/events.md`).
**Limits:**
| Constant | Value |
|----------|-------|
| `UI_TEXTBOX_TEXT_MAX` | 1024 chars |
| `UI_TEXTBOX_LINES_MAX` | 64 lines |
| `UI_TEXTBOX_LINES_PER_PAGE_MAX` | 3 lines per page |
| `UI_TEXTBOX_SCROLL_CHARS_PER_TICK` | 1 char per tick |
---
### uifullbox_t -- full-screen colour overlay (`uifullbox.h`)
An animated solid-colour overlay that covers the entire screen. Used
for fade-to-black, scene transitions, and flash effects.
Two global instances are provided:
```c
extern uifullbox_t UI_FULLBOX_UNDER; // draws below scene content
extern uifullbox_t UI_FULLBOX_OVER; // draws above all content
```
```c
void uiFullboxInit(uifullbox_t *fullbox);
// Start a colour-to-colour transition:
void uiFullboxTransition(
uifullbox_t *fullbox,
color_t from,
color_t to,
float_t duration,
easingtype_t easing
);
void uiFullboxUpdate(uifullbox_t *fullbox, float_t delta);
errorret_t uiFullboxDraw(uifullbox_t *fullbox);
// Draw is skipped entirely when alpha == 0.
```
`fullbox.onTransitionEnd` event fires once when the transition
completes. Subscribe to it to chain scene transitions:
```c
// Typical fade-out before a scene change:
uiFullboxTransition(
&UI_FULLBOX_OVER,
COLOR_TRANSPARENT, COLOR_BLACK,
0.5f, EASING_OUT_QUAD
);
eventSubscribe(&UI_FULLBOX_OVER.onTransitionEnd, onFadeComplete, NULL);
```
---
### uiloading_t -- loading indicator (`uiloading.h`)
An animated loading indicator with fade-in / fade-out transitions.
Shown while asset batches are loading.
```c
extern uiloading_t UI_LOADING;
void uiLoadingInit(void);
void uiLoadingUpdate(float_t delta);
errorret_t uiLoadingDraw(void);
// Fade in; callback fires when fully visible:
void uiLoadingShow(eventcallback_t callback, void *user);
// Fade out; callback fires when fully hidden:
void uiLoadingHide(eventcallback_t callback, void *user);
```
`UI_LOADING_FADE_DURATION` is 0.5 seconds. `UI_LOADING_MARGIN` is 8px.
`uiLoadingDraw` is a no-op when the indicator is fully transparent.
---
### uifps_t -- FPS counter (`uifps.h`)
Debug FPS display. Measures real elapsed time between ticks and draws
the average frame rate as text in the corner of the screen.
```c
extern uifps_t UIFPS;
errorret_t uiFPSDraw(); // also performs the measurement update
```
Intended for debug builds only. Draw it explicitly from a JS `render`
hook or from a UI element -- it is not registered in `UI_ELEMENTS` by
default.
.claude/util.md
-191
View File
@@ -1,191 +0,0 @@
# Utility Library
Source: `src/dusk/util/`
All C code in the project must use these utilities instead of their
standard library equivalents. Do not use `malloc`, `free`, `strcmp`,
`strcpy`, `memcpy`, `memset`, etc. directly.
---
## Memory (`memory.h`)
```c
void *memoryAllocate(size_t size);
void *memoryAlign(size_t alignment, size_t size); // aligned alloc
void memoryFree(void *ptr);
void memoryCopy(void *dest, const void *src, size_t size);
void memoryZero(void *dest, size_t size);
errorret_t memoryCompare(const void *a, const void *b, size_t size);
size_t memoryGetAllocatedCount(void);
// Returns the number of live allocations. Must be 0 at test teardown.
void memoryTrack(void *ptr);
// Register a pointer that was malloc'd outside the engine (e.g. by a
// third-party library) so it counts toward the allocation tracker.
```
`MEMORY_POINTERS_IN_USE` is a file-scope static tracking the live count.
It is incremented by `memoryAllocate` / `memoryTrack` and decremented by
`memoryFree`. Tests assert this is 0 at teardown to catch leaks.
---
## String (`string.h`)
Use these instead of `<string.h>` / `<ctype.h>` functions:
```c
void stringCopy(char_t *dest, const char_t *src, size_t destSize);
int stringCompare(const char_t *a, const char_t *b);
bool_t stringEquals(const char_t *a, const char_t *b);
int stringCompareInsensitive(const char_t *a, const char_t *b);
size_t stringLength(const char_t *str);
void stringTrim(char_t *str);
bool_t stringIsWhitespace(char_t c);
bool_t stringStartsWith(const char_t *str, const char_t *prefix);
bool_t stringEndsWith(const char_t *str, const char_t *suffix);
bool_t stringContains(const char_t *haystack, const char_t *needle);
char_t *stringFind(const char_t *haystack, const char_t *needle);
void stringFormat(char_t *dest, size_t destSize, const char_t *fmt, ...);
int32_t stringToInt(const char_t *str);
float_t stringToFloat(const char_t *str);
void stringFromInt(char_t *dest, size_t destSize, int32_t value);
void stringFromFloat(char_t *dest, size_t destSize, float_t value);
```
`destSize` in `stringCopy` / `stringFormat` is the buffer capacity
**excluding** the null terminator.
---
## Math (`math.h`)
```c
#define MATH_PI M_PI
#define mathMax(a, b)
#define mathMin(a, b)
#define mathClamp(x, lower, upper)
#define mathAbs(amt)
uint32_t mathNextPowTwo(uint32_t value);
float_t mathModFloat(float_t x, float_t y); // always non-negative
float_t mathLerp(float_t a, float_t b, float_t t);
// plus additional trig / remap helpers
```
The project uses **cglm** for vector and matrix math (`vec3`, `mat4`,
`glm_vec3_*`, `glm_mat4_*`, etc.). `math.h` provides scalar helpers
that complement cglm.
---
## Endian (`endian.h`)
GameCube and Wii are big-endian. Any binary data format (asset files,
network packets) must use the endian utilities when reading multi-byte
values.
```c
bool_t isHostLittleEndian(void);
uint16_t endianLittleToHost16(uint16_t value);
uint32_t endianLittleToHost32(uint32_t value);
uint64_t endianLittleToHost64(uint64_t value);
float_t endianLittleToHostFloat(float_t value);
```
If neither `DUSK_PLATFORM_ENDIAN_LITTLE` nor `DUSK_PLATFORM_ENDIAN_BIG`
is defined, the implementation falls back to a runtime check
(`ENDIAN_MAGIC` probe). Prefer setting the compile-time macro for new
platform targets.
---
## Reference counting (`ref.h`)
`ref_t` is a generic reference-counted handle with optional lock /
unlock / all-unlocked callbacks.
```c
void refInit(
ref_t *ref,
void *data,
refcallback_t onLock,
refcallback_t onUnlock,
refcallback_t onAllUnlocked // called when count -> 0; do cleanup here
);
void refLock(ref_t *ref); // increment count
bool_t refUnlock(ref_t *ref); // decrement; returns true if count == 0
```
The asset entry system uses `ref_t` internally to track how many
subsystems have locked a loaded asset.
---
## Array (`array.h`)
```c
void arrayReverse(void *array, size_t count, size_t elementSize);
```
Generic in-place reverse using the element stride.
---
## Sort (`sort.h`)
Use these instead of `qsort` for portability across all platforms.
```c
typedef int_t (*sortcompare_t)(const void *, const void *);
void sortBubble(
void *array,
const size_t count,
const size_t size,
const sortcompare_t compare
);
void sortQuick(
void *array,
const size_t count,
const size_t size,
const sortcompare_t compare
);
#define sort sortQuick // preferred; use this in new code
```
Typed convenience helpers for `uint8_t` arrays:
```c
int sortArrayU8Compare(const void *a, const void *b);
void sortArrayU8(uint8_t *array, const size_t count);
```
---
## Crypt (`crypt.h`)
CRC32 checksum for save file integrity. Not cryptographically secure --
do not use for security purposes.
```c
// One-shot checksum:
uint32_t cryptCRC32(const void *data, const size_t size);
// Streaming (incremental) CRC32:
uint32_t cryptCRC32Begin(void);
void cryptCRC32Update(
uint32_t *crc, const void *data, const size_t size
);
uint32_t cryptCRC32End(const uint32_t crc);
```
The streaming API allows computing a checksum across multiple buffers
or while interleaving other reads -- the save system uses this to
verify the whole save slot in a single pass.
CLAUDE.md
+13 -100
View File
@@ -1,79 +1,4 @@
# 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` |
| Display -- mesh, vertex format, primitives | `.claude/display-mesh.md` |
| Display -- SpriteBatch (2D quad renderer) | `.claude/display-spritebatch.md` |
| Display -- text rendering, FONT_DEFAULT | `.claude/display-text.md` |
| Display -- color types, macros, constants | `.claude/display-color.md` |
| UI system (frame, textbox, fullbox, loading, FPS) | `.claude/ui.md` |
| Console (debug overlay, POSIX stdin mode) | `.claude/console.md` |
| Scene system (lifecycle, render pipeline, JS hooks) | `.claude/scene.md` |
---
## File headers ## File headers
Every C, H, and JS file starts with: Every C, H, and JS file starts with:
@@ -176,10 +101,6 @@ assertIsMainThread("msg");
--- ---
## Build system ## 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: Each subdirectory has its own `CMakeLists.txt` that adds sources with:
```cmake ```cmake
@@ -195,10 +116,6 @@ Never add source files to the root `CMakeLists.txt` directly.
## Platform support ## Platform support
See `.claude/platforms.md` for the full platform table (including
planned Windows / macOS targets), capability macros, toolchain setup,
and endianness notes.
### Targets ### Targets
Set `DUSK_TARGET_SYSTEM` at CMake configure time to select a platform: Set `DUSK_TARGET_SYSTEM` at CMake configure time to select a platform:
@@ -258,11 +175,19 @@ 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 ## 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 1. Create `src/dusk/entity/component/<category>/entityMyComp.h/.c` with
struct `entityMyComp_t`, `entityMyCompInit()`, and optionally struct `entityMyComp_t`, `entityMyCompInit()`, and optionally
`entityMyCompDispose()`. `entityMyCompDispose()`.
@@ -276,18 +201,6 @@ entity lifecycle details.
--- ---
## 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 ## Adding a new script (JS) module
1. Create `src/dusk/script/module/<category>/moduleMyMod.h/.c`. 1. Create `src/dusk/script/module/<category>/moduleMyMod.h/.c`.
- Declare `extern scriptproto_t MODULE_MYMOD_PROTO;` in the header. - Declare `extern scriptproto_t MODULE_MYMOD_PROTO;` in the header.
archive/rpg/rpgcamera.h
-1
View File
@@ -16,7 +16,6 @@ typedef enum {
typedef struct { typedef struct {
rpgcameramode_t mode; rpgcameramode_t mode;
union { union {
worldpos_t free; worldpos_t free;
struct { struct {
cmake/modules/Findjerryscript.cmake
-96
View File
@@ -1,96 +0,0 @@
# Copyright (c) 2026 Dominic Masters
#
# This software is released under the MIT License.
# https://opensource.org/licenses/MIT
# Turn things off we don't need
set(JERRY_CMDLINE OFF CACHE BOOL "" FORCE)
set(JERRY_EXT ON CACHE BOOL "" FORCE)
set(JERRY_DEBUGGER OFF CACHE BOOL "" FORCE)
set(JERRY_BUILTIN_DATE OFF CACHE BOOL "" FORCE)
set(ENABLE_LTO OFF CACHE BOOL "" FORCE)
# Fetch Jerry
include(FetchContent)
FetchContent_Declare(
jerryscript
GIT_REPOSITORY https://git.wish.moe/YourWishes/jerryscript
GIT_TAG float32-fix
)
FetchContent_MakeAvailable(jerryscript)
# Mark found
set(jerryscript_FOUND ON)
# Define targets
if(TARGET jerryscript-core)
set(JERRY_CORE_TARGET jerryscript-core)
elseif(TARGET jerry-core)
set(JERRY_CORE_TARGET jerry-core)
endif()
if(TARGET jerryscript-ext)
set(JERRY_EXT_TARGET jerryscript-ext)
elseif(TARGET jerry-ext)
set(JERRY_EXT_TARGET jerry-ext)
endif()
if(TARGET jerryscript-port-default)
set(JERRY_PORT_TARGET jerryscript-port-default)
elseif(TARGET jerry-port-default)
set(JERRY_PORT_TARGET jerry-port-default)
elseif(TARGET jerryscript-port)
set(JERRY_PORT_TARGET jerryscript-port)
elseif(TARGET jerry-port)
set(JERRY_PORT_TARGET jerry-port)
endif()
if(NOT JERRY_CORE_TARGET)
message(FATAL_ERROR "JerryScript core target not found")
endif()
if(NOT JERRY_EXT_TARGET)
message(FATAL_ERROR "JerryScript ext target not found")
endif()
if(NOT JERRY_PORT_TARGET)
message(FATAL_ERROR "JerryScript port target not found")
endif()
foreach(tgt IN ITEMS
${JERRY_CORE_TARGET}
${JERRY_EXT_TARGET}
${JERRY_PORT_TARGET}
)
if(TARGET ${tgt})
set_property(TARGET ${tgt} PROPERTY INTERPROCEDURAL_OPTIMIZATION OFF)
target_compile_definitions(${JERRY_CORE_TARGET} PRIVATE
JERRY_NUMBER_TYPE_FLOAT64=0
JERRY_BUILTIN_DATE=0
)
endif()
endforeach()
# Export include dirs through the targets
target_include_directories(${JERRY_CORE_TARGET} INTERFACE
${jerryscript_SOURCE_DIR}/jerry-core/include
)
target_include_directories(${JERRY_EXT_TARGET} INTERFACE
${jerryscript_SOURCE_DIR}/jerry-ext/include
)
target_include_directories(${JERRY_PORT_TARGET} INTERFACE
${jerryscript_SOURCE_DIR}/jerry-port/default/include
)
# Suppress JerryScript-only warning
if(CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
target_compile_options(${JERRY_CORE_TARGET} PRIVATE
-Wno-error
)
endif()
add_library(jerryscript::core ALIAS ${JERRY_CORE_TARGET})
add_library(jerryscript::ext ALIAS ${JERRY_EXT_TARGET})
add_library(jerryscript::port ALIAS ${JERRY_PORT_TARGET})
cmake/modules/duskjs2c.cmake
-43
View File
@@ -1,43 +0,0 @@
# Copyright (c) 2026 Dominic Masters
#
# This software is released under the MIT License.
# https://opensource.org/licenses/MIT
# dusk_embed_js(TARGET JS_FILE [NAME identifier])
#
# Converts a JS file into a C string header in DUSK_GENERATED_HEADERS_DIR.
# The generated header defines:
# static const char <NAME>[] = "...";
# static const size_t <NAME>_SIZE = sizeof(<NAME>) - 1;
#
# NAME defaults to the uppercase stem + "_JS" (e.g. scene.js -> SCENE_JS).
function(dusk_embed_js TARGET JS_FILE)
cmake_parse_arguments(ARG "" "NAME" "" ${ARGN})
get_filename_component(JS_ABS "${JS_FILE}" ABSOLUTE)
get_filename_component(JS_STEM "${JS_FILE}" NAME_WE)
set(OUTPUT_HEADER "${DUSK_GENERATED_HEADERS_DIR}/${JS_STEM}_js.h")
set(NAME_ARG "")
if(ARG_NAME)
set(NAME_ARG "--name" "${ARG_NAME}")
endif()
add_custom_command(
OUTPUT "${OUTPUT_HEADER}"
COMMAND ${Python3_EXECUTABLE} -m tools.js2c
--input "${JS_ABS}"
--output "${OUTPUT_HEADER}"
${NAME_ARG}
WORKING_DIRECTORY "${DUSK_ROOT_DIR}"
DEPENDS "${JS_ABS}"
COMMENT "js2c: ${JS_STEM}.js -> ${JS_STEM}_js.h"
VERBATIM
)
file(RELATIVE_PATH JS_REL "${DUSK_ROOT_DIR}" "${JS_ABS}")
string(MAKE_C_IDENTIFIER "dusk_js2c_${JS_REL}" JS_TARGET)
add_custom_target(${JS_TARGET} DEPENDS "${OUTPUT_HEADER}")
add_dependencies(${TARGET} ${JS_TARGET})
endfunction()
src/dusk/CMakeLists.txt
+1 -15
View File
@@ -32,15 +32,6 @@ if(NOT yyjson_FOUND)
endif() endif()
endif() endif()
if(NOT jerryscript_FOUND)
find_package(jerryscript REQUIRED)
target_link_libraries(${DUSK_LIBRARY_TARGET_NAME} PUBLIC
jerryscript::core
jerryscript::ext
jerryscript::port
)
endif()
if(DUSK_BACKTRACE) if(DUSK_BACKTRACE)
target_link_options(${DUSK_LIBRARY_TARGET_NAME} PUBLIC -rdynamic) target_link_options(${DUSK_LIBRARY_TARGET_NAME} PUBLIC -rdynamic)
target_compile_definitions(${DUSK_BINARY_TARGET_NAME} PUBLIC target_compile_definitions(${DUSK_BINARY_TARGET_NAME} PUBLIC
@@ -66,24 +57,19 @@ add_subdirectory(event)
add_subdirectory(assert) add_subdirectory(assert)
add_subdirectory(asset) add_subdirectory(asset)
add_subdirectory(cutscene) add_subdirectory(cutscene)
add_subdirectory(item)
add_subdirectory(story)
add_subdirectory(console) add_subdirectory(console)
add_subdirectory(display) add_subdirectory(display)
add_subdirectory(log) add_subdirectory(log)
add_subdirectory(engine) add_subdirectory(engine)
add_subdirectory(entity)
add_subdirectory(error) add_subdirectory(error)
add_subdirectory(input) add_subdirectory(input)
add_subdirectory(locale) add_subdirectory(locale)
add_subdirectory(physics) add_subdirectory(rpg)
add_subdirectory(scene) add_subdirectory(scene)
add_subdirectory(script)
add_subdirectory(system) add_subdirectory(system)
add_subdirectory(time) add_subdirectory(time)
add_subdirectory(ui) add_subdirectory(ui)
add_subdirectory(network) add_subdirectory(network)
add_subdirectory(overworld)
add_subdirectory(save) add_subdirectory(save)
add_subdirectory(util) add_subdirectory(util)
add_subdirectory(thread) add_subdirectory(thread)
src/dusk/asset/asset.c
-15
View File
@@ -411,21 +411,6 @@ errorret_t assetDispose(void) {
assertIsMainThread("Must be called from the main thread."); assertIsMainThread("Must be called from the main thread.");
threadStop(&ASSET.loadThread); threadStop(&ASSET.loadThread);
// Free any script read-buffers left behind by an in-flight async load
// that was interrupted before the sync eval phase ran.
for(size_t i = 0; i < ASSET_LOADING_COUNT_MAX; i++) {
assetloading_t *loading = &ASSET.loading[i];
if(
loading->entry != NULL &&
loading->type == ASSET_LOADER_TYPE_SCRIPT &&
loading->loading.script.buffer != NULL
) {
memoryFree(loading->loading.script.buffer);
loading->loading.script.buffer = NULL;
}
threadMutexDispose(&loading->mutex);
}
// Dispose every non-null entry so type-specific dispose callbacks // Dispose every non-null entry so type-specific dispose callbacks
// (e.g. assetScriptDispose freeing jerry values) run before the // (e.g. assetScriptDispose freeing jerry values) run before the
// scripting engine is torn down. // scripting engine is torn down.
src/dusk/asset/loader/CMakeLists.txt
+1 -2
View File
@@ -14,5 +14,4 @@ target_sources(${DUSK_LIBRARY_TARGET_NAME}
# Subdirs # Subdirs
add_subdirectory(display) add_subdirectory(display)
add_subdirectory(locale) add_subdirectory(locale)
add_subdirectory(json) add_subdirectory(json)
add_subdirectory(script)
src/dusk/asset/loader/assetloader.c
-6
View File
@@ -39,10 +39,4 @@ assetloadercallbacks_t ASSET_LOADER_CALLBACKS[ASSET_LOADER_TYPE_COUNT] = {
.loadAsync = assetJsonLoaderAsync, .loadAsync = assetJsonLoaderAsync,
.dispose = assetJsonDispose .dispose = assetJsonDispose
}, },
[ASSET_LOADER_TYPE_SCRIPT] = {
.loadSync = assetScriptLoaderSync,
.loadAsync = assetScriptLoaderAsync,
.dispose = assetScriptDispose
},
}; };
src/dusk/asset/loader/assetloader.h
-5
View File
@@ -11,7 +11,6 @@
#include "asset/loader/display/assettilesetloader.h" #include "asset/loader/display/assettilesetloader.h"
#include "asset/loader/locale/assetlocaleloader.h" #include "asset/loader/locale/assetlocaleloader.h"
#include "asset/loader/json/assetjsonloader.h" #include "asset/loader/json/assetjsonloader.h"
#include "asset/loader/script/assetscriptloader.h"
typedef enum { typedef enum {
ASSET_LOADER_TYPE_NULL, ASSET_LOADER_TYPE_NULL,
@@ -21,7 +20,6 @@ typedef enum {
ASSET_LOADER_TYPE_TILESET, ASSET_LOADER_TYPE_TILESET,
ASSET_LOADER_TYPE_LOCALE, ASSET_LOADER_TYPE_LOCALE,
ASSET_LOADER_TYPE_JSON, ASSET_LOADER_TYPE_JSON,
ASSET_LOADER_TYPE_SCRIPT,
ASSET_LOADER_TYPE_COUNT ASSET_LOADER_TYPE_COUNT
} assetloadertype_t; } assetloadertype_t;
@@ -32,7 +30,6 @@ typedef union {
assettilesetloaderinput_t tileset; assettilesetloaderinput_t tileset;
assetlocaleloaderinput_t locale; assetlocaleloaderinput_t locale;
assetjsonloaderinput_t json; assetjsonloaderinput_t json;
assetscriptloaderinput_t script;
} assetloaderinput_t; } assetloaderinput_t;
typedef union { typedef union {
@@ -41,7 +38,6 @@ typedef union {
assettilesetloaderloading_t tileset; assettilesetloaderloading_t tileset;
assetlocaleloaderloading_t locale; assetlocaleloaderloading_t locale;
assetjsonloaderloading_t json; assetjsonloaderloading_t json;
assetscriptloaderloading_t script;
} assetloaderloading_t; } assetloaderloading_t;
typedef union { typedef union {
@@ -50,7 +46,6 @@ typedef union {
assettilesetoutput_t tileset; assettilesetoutput_t tileset;
assetlocaleoutput_t locale; assetlocaleoutput_t locale;
assetjsonoutput_t json; assetjsonoutput_t json;
assetscriptoutput_t script;
} assetloaderoutput_t; } assetloaderoutput_t;
typedef struct assetloading_s assetloading_t; typedef struct assetloading_s assetloading_t;
src/dusk/asset/loader/script/CMakeLists.txt
-9
View File
@@ -1,9 +0,0 @@
# Copyright (c) 2026 Dominic Masters
#
# This software is released under the MIT License.
# https://opensource.org/licenses/MIT
target_sources(${DUSK_LIBRARY_TARGET_NAME}
PUBLIC
assetscriptloader.c
)
src/dusk/asset/loader/script/assetscriptloader.c
-137
View File
@@ -1,137 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "assetscriptloader.h"
#include "asset/loader/assetloading.h"
#include "asset/loader/assetentry.h"
#include "asset/loader/assetloader.h"
#include "script/module/require/modulerequire.h"
#include "util/memory.h"
#include "assert/assert.h"
#include <jerryscript.h>
errorret_t assetScriptLoaderAsync(assetloading_t *loading) {
assertNotNull(loading, "Loading cannot be NULL");
assertNotMainThread("Async loader should not be on main thread.");
if(loading->loading.script.state != ASSET_SCRIPT_LOADING_STATE_READ_FILE) {
errorOk();
}
assertNull(loading->loading.script.buffer, "Buffer already defined?");
assetfile_t *file = &loading->loading.script.file;
assetLoaderErrorChain(
loading, assetFileInit(file, loading->entry->name, NULL, NULL)
);
uint8_t *buffer = NULL;
size_t size = 0;
assetLoaderErrorChain(loading, assetFileReadEntire(file, &buffer, &size));
assetLoaderErrorChain(loading, assetFileDispose(file));
// Null-terminate for jerry_eval.
memoryResize((void **)&buffer, size, size + 1);
buffer[size] = '\0';
loading->loading.script.buffer = buffer;
loading->loading.script.size = size;
loading->loading.script.state = ASSET_SCRIPT_LOADING_STATE_EXEC;
loading->entry->state = ASSET_ENTRY_STATE_PENDING_SYNC;
errorOk();
}
errorret_t assetScriptLoaderSync(assetloading_t *loading) {
assertNotNull(loading, "Loading cannot be NULL");
assertTrue(loading->type == ASSET_LOADER_TYPE_SCRIPT, "Invalid type.");
assertIsMainThread("Must be called from the main thread.");
switch(loading->loading.script.state) {
case ASSET_SCRIPT_LOADING_STATE_INITIAL:
loading->loading.script.state = ASSET_SCRIPT_LOADING_STATE_READ_FILE;
loading->entry->state = ASSET_ENTRY_STATE_PENDING_ASYNC;
errorOk();
break;
case ASSET_SCRIPT_LOADING_STATE_EXEC:
break;
default:
errorOk();
}
// Get read buffer
uint8_t *buffer = loading->loading.script.buffer;
assertNotNull(buffer, "Script buffer should have been loaded by now.");
// Get the current global script realm
jerry_value_t global = jerry_current_realm();
// Replace globalThis.module with a new `module = {}`
jerry_value_t oldModule = jerry_object_get_sz(global, "module");
jerry_value_t module = jerry_object();
jerry_object_set_sz(global, "module", module);
// Eval the script, we handle failure later down the code.
jerry_value_t result = jerry_eval(
buffer,
loading->loading.script.size,
JERRY_PARSE_NO_OPTS
);
// Free the read buffer
memoryFree(buffer);
loading->loading.script.buffer = NULL;
// Restore globalThis.module
jerry_object_set_sz(global, "module", oldModule);
jerry_value_free(oldModule);
jerry_value_free(global);
if(jerry_value_is_exception(result)) {
jerry_value_free(module);
loading->entry->data.script.exports = jerry_undefined();
loading->entry->state = ASSET_ENTRY_STATE_ERROR;
// Get error string
char_t buf[256];
moduleBaseExceptionMessage(result, buf, sizeof(buf));
jerry_value_free(result);
assetLoaderErrorThrow(
loading,
"Script execution failed: %s: %s", loading->entry->name, buf
);
}
// Get module.exports
jerry_value_t exports = jerry_object_get_sz(module, "exports");
jerry_value_free(result);
jerry_value_free(module);
// Store the exports.
loading->entry->data.script.exports = exports;
loading->entry->state = ASSET_ENTRY_STATE_LOADED;
errorOk();
}
errorret_t assetScriptDispose(assetentry_t *entry) {
assertNotNull(entry, "Asset entry cannot be NULL");
assertTrue(entry->type == ASSET_LOADER_TYPE_SCRIPT, "Invalid type.");
assertIsMainThread("Must be called from the main thread.");
if(
entry->data.script.exports != 0 &&
!jerry_value_is_undefined(entry->data.script.exports)
) {
jerry_value_free(entry->data.script.exports);
entry->data.script.exports = 0;
}
errorOk();
}
src/dusk/asset/loader/script/assetscriptloader.h
-60
View File
@@ -1,60 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "asset/assetfile.h"
#include "script/scriptmodule.h"
#define ASSET_SCRIPT_CHUNK_SIZE 1024
typedef struct assetloading_s assetloading_t;
typedef struct assetentry_s assetentry_t;
typedef struct {
void *nothing;
} assetscriptloaderinput_t;
typedef scriptmodule_t assetscriptoutput_t;
typedef enum {
ASSET_SCRIPT_LOADING_STATE_INITIAL,
ASSET_SCRIPT_LOADING_STATE_READ_FILE,
ASSET_SCRIPT_LOADING_STATE_EXEC,
ASSET_SCRIPT_LOADING_STATE_DONE
} assetscriptloadingstate_t;
typedef struct {
assetfile_t file;
assetscriptloadingstate_t state;
uint8_t *buffer;
size_t size;
} assetscriptloaderloading_t;
/**
* Asynchronous loader for a script asset/module.
*
* @param loading The loading context.
* @returns An error code and state.
*/
errorret_t assetScriptLoaderAsync(assetloading_t *loading);
/**
* Synchronous loader for a script asset/module. This executes the script after
* it has been loaded by the async loader.
*
* @param loading The loading context.
* @returns An error code and state.
*/
errorret_t assetScriptLoaderSync(assetloading_t *loading);
/**
* Disposes of a loaded script asset/module.
*
* @param entry The asset entry to dispose.
* @returns An error code and state.
*/
errorret_t assetScriptDispose(assetentry_t *entry);
src/dusk/display/display.c
+6
View File
@@ -38,6 +38,10 @@ errorret_t displayInit(void) {
&TEXTURE_WHITE, 4, 4, &TEXTURE_WHITE, 4, 4,
TEXTURE_FORMAT_RGBA, (texturedata_t){ .rgbaColors = TEXTURE_WHITE_PIXELS } TEXTURE_FORMAT_RGBA, (texturedata_t){ .rgbaColors = TEXTURE_WHITE_PIXELS }
)); ));
errorChain(textureInit(
&TEXTURE_TEST, 4, 4,
TEXTURE_FORMAT_RGBA, (texturedata_t){ .rgbaColors = TEXTURE_TEST_PIXELS }
));
// Standard meshes // Standard meshes
errorChain(quadInit()); errorChain(quadInit());
@@ -100,6 +104,8 @@ errorret_t displayDispose(void) {
errorChain(spriteBatchDispose()); errorChain(spriteBatchDispose());
screenDispose(); screenDispose();
errorChain(textDispose()); errorChain(textDispose());
errorChain(textureDispose(&TEXTURE_WHITE));
errorChain(textureDispose(&TEXTURE_TEST));
#ifdef displayPlatformDispose #ifdef displayPlatformDispose
displayPlatformDispose(); displayPlatformDispose();
src/dusk/display/spritebatch/spritebatch.c
+46 -21
View File
@@ -50,70 +50,95 @@ errorret_t spriteBatchBuffer(
} }
// Buffer the vertices. // Buffer the vertices.
for(uint32_t i = 0; i < count; i++ ){ uint32_t remaining = count;
spritebatchsprite_t sprite = sprites[i]; do {
uint32_t spritesBeforeFlush = (
SPRITEBATCH_SPRITES_MAX_PER_FLUSH - SPRITEBATCH.spriteCount
);
if(spritesBeforeFlush == 0) {
// Flush if we have no capacity before flushing.
errorChain(spriteBatchFlush());
spritesBeforeFlush = SPRITEBATCH_SPRITES_MAX_PER_FLUSH;
}
// Many we buffering?
const uint32_t batchCount = mathMin(
remaining,
spritesBeforeFlush
);
// Destination
meshvertex_t *v = &SPRITEBATCH_VERTICES[ meshvertex_t *v = &SPRITEBATCH_VERTICES[
(SPRITEBATCH.spriteCount + (SPRITEBATCH.spriteFlush * (SPRITEBATCH.spriteCount + (SPRITEBATCH.spriteFlush *
SPRITEBATCH_SPRITES_MAX_PER_FLUSH)) * QUAD_VERTEX_COUNT SPRITEBATCH_SPRITES_MAX_PER_FLUSH)) * QUAD_VERTEX_COUNT
]; ];
// Buffer to the mesh vertices.
spriteBatchBufferToMesh(
sprites, batchCount, v, batchCount * QUAD_VERTEX_COUNT
);
SPRITEBATCH.spriteCount += batchCount;
remaining -= batchCount;
} while(remaining > 0);
errorOk();
}
void spriteBatchBufferToMesh(
const spritebatchsprite_t *sprites,
const uint32_t count,
meshvertex_t *vertices,
const uint32_t verticesSize
) {
assertNotNull(sprites, "Sprites cannot be null");
assertTrue(count > 0, "Count must be greater than zero");
assertNotNull(vertices, "Vertices cannot be null");
assertTrue(
verticesSize >= count * QUAD_VERTEX_COUNT, "Vertices array too small"
);
for(uint32_t i = 0; i < count; i++ ){
spritebatchsprite_t sprite = sprites[i];
meshvertex_t *v = &vertices[i * QUAD_VERTEX_COUNT];
// Buffer the quad // Buffer the quad
v[0].pos[0] = sprite.min[0]; v[0].pos[0] = sprite.min[0];
v[0].pos[1] = sprite.min[1]; v[0].pos[1] = sprite.min[1];
v[0].pos[2] = sprite.min[2]; v[0].pos[2] = sprite.min[2];
v[0].uv[0] = sprite.uvMin[0]; v[0].uv[0] = sprite.uvMin[0];
v[0].uv[1] = sprite.uvMin[1]; v[0].uv[1] = sprite.uvMin[1];
v[1].pos[0] = sprite.max[0]; v[1].pos[0] = sprite.max[0];
v[1].pos[1] = sprite.min[1]; v[1].pos[1] = sprite.min[1];
v[1].pos[2] = sprite.min[2]; v[1].pos[2] = sprite.min[2];
v[1].uv[0] = sprite.uvMax[0]; v[1].uv[0] = sprite.uvMax[0];
v[1].uv[1] = sprite.uvMin[1]; v[1].uv[1] = sprite.uvMin[1];
v[2].pos[0] = sprite.max[0]; v[2].pos[0] = sprite.max[0];
v[2].pos[1] = sprite.max[1]; v[2].pos[1] = sprite.max[1];
v[2].pos[2] = sprite.max[2]; v[2].pos[2] = sprite.max[2];
v[2].uv[0] = sprite.uvMax[0]; v[2].uv[0] = sprite.uvMax[0];
v[2].uv[1] = sprite.uvMax[1]; v[2].uv[1] = sprite.uvMax[1];
v[3].pos[0] = sprite.min[0]; v[3].pos[0] = sprite.min[0];
v[3].pos[1] = sprite.min[1]; v[3].pos[1] = sprite.min[1];
v[3].pos[2] = sprite.min[2]; v[3].pos[2] = sprite.min[2];
v[3].uv[0] = sprite.uvMin[0]; v[3].uv[0] = sprite.uvMin[0];
v[3].uv[1] = sprite.uvMin[1]; v[3].uv[1] = sprite.uvMin[1];
v[4].pos[0] = sprite.max[0]; v[4].pos[0] = sprite.max[0];
v[4].pos[1] = sprite.max[1]; v[4].pos[1] = sprite.max[1];
v[4].pos[2] = sprite.max[2]; v[4].pos[2] = sprite.max[2];
v[4].uv[0] = sprite.uvMax[0]; v[4].uv[0] = sprite.uvMax[0];
v[4].uv[1] = sprite.uvMax[1]; v[4].uv[1] = sprite.uvMax[1];
v[5].pos[0] = sprite.min[0]; v[5].pos[0] = sprite.min[0];
v[5].pos[1] = sprite.max[1]; v[5].pos[1] = sprite.max[1];
v[5].pos[2] = sprite.max[2]; v[5].pos[2] = sprite.max[2];
v[5].uv[0] = sprite.uvMin[0]; v[5].uv[0] = sprite.uvMin[0];
v[5].uv[1] = sprite.uvMax[1]; v[5].uv[1] = sprite.uvMax[1];
// Do we need to flush?
SPRITEBATCH.spriteCount++;
if(SPRITEBATCH.spriteCount >= SPRITEBATCH_SPRITES_MAX_PER_FLUSH) {
errorChain(spriteBatchFlush());
}
} }
errorOk();
} }
void spriteBatchClear() { void spriteBatchClear() {
src/dusk/display/spritebatch/spritebatch.h
+20
View File
@@ -63,6 +63,26 @@ errorret_t spriteBatchBuffer(
const shadermaterial_t material const shadermaterial_t material
); );
/**
* Buffers an array of sprites to a given array of mesh vertices. This is the
* internal method that is used to buffer to the internal spritebatch mesh, but
* you can use it to achieve sprite buffering to a mesh you own.
*
* verticesSize is the size of the vertices array, we use this to ensure no
* buffer overflows.
*
* @param sprites Pointer to the sprite array.
* @param count Number of sprites to buffer.
* @param vertices Pointer to the vertex array to write to.
* @param verticesSize Size of the vertex array, in number of vertices.
*/
void spriteBatchBufferToMesh(
const spritebatchsprite_t *sprites,
const uint32_t count,
meshvertex_t *vertices,
const uint32_t verticesSize
);
/** /**
* Resets sprite and flush counters and clears the current material state. * Resets sprite and flush counters and clears the current material state.
* Calling spriteBatchFlush after this renders nothing. * Calling spriteBatchFlush after this renders nothing.
src/dusk/display/text/text.c
-9
View File
@@ -93,15 +93,6 @@ errorret_t textDraw(
float_t posX = x; float_t posX = x;
float_t posY = y; float_t posY = y;
errorChain(shaderSetTexture(
&SHADER_UNLIT, SHADER_UNLIT_TEXTURE, font->texture
));
#if MESH_ENABLE_COLOR
#else
errorChain(shaderSetColor(&SHADER_UNLIT, SHADER_UNLIT_COLOR, color));
#endif
char_t c; char_t c;
int32_t i = 0; int32_t i = 0;
while((c = text[i++]) != '\0') { while((c = text[i++]) != '\0') {
src/dusk/display/texture/texture.c
+8
View File
@@ -19,6 +19,14 @@ color_t TEXTURE_WHITE_PIXELS[4*4] = {
COLOR_WHITE, COLOR_WHITE, COLOR_WHITE, COLOR_WHITE, COLOR_WHITE, COLOR_WHITE, COLOR_WHITE, COLOR_WHITE,
}; };
texture_t TEXTURE_TEST;
color_t TEXTURE_TEST_PIXELS[4*4] = {
COLOR_BLACK, COLOR_MAGENTA, COLOR_BLACK, COLOR_MAGENTA,
COLOR_MAGENTA, COLOR_BLACK, COLOR_MAGENTA, COLOR_BLACK,
COLOR_BLACK, COLOR_MAGENTA, COLOR_BLACK, COLOR_MAGENTA,
COLOR_MAGENTA, COLOR_BLACK, COLOR_MAGENTA, COLOR_BLACK,
};
errorret_t textureInit( errorret_t textureInit(
texture_t *texture, texture_t *texture,
const int32_t width, const int32_t width,
src/dusk/display/texture/texture.h
+2
View File
@@ -30,6 +30,8 @@ typedef union texturedata_u {
extern texture_t TEXTURE_WHITE; extern texture_t TEXTURE_WHITE;
extern color_t TEXTURE_WHITE_PIXELS[4*4]; extern color_t TEXTURE_WHITE_PIXELS[4*4];
extern texture_t TEXTURE_TEST;
extern color_t TEXTURE_TEST_PIXELS[4*4];
/** /**
* Initializes a texture. * Initializes a texture.
src/dusk/engine/engine.c
+8 -16
View File
@@ -10,6 +10,7 @@
#include "time/time.h" #include "time/time.h"
#include "input/input.h" #include "input/input.h"
#include "locale/localemanager.h" #include "locale/localemanager.h"
#include "rpg/rpg.h"
#include "display/display.h" #include "display/display.h"
#include "scene/scene.h" #include "scene/scene.h"
#include "cutscene/cutscene.h" #include "cutscene/cutscene.h"
@@ -17,14 +18,9 @@
#include "ui/ui.h" #include "ui/ui.h"
#include "ui/uitextbox.h" #include "ui/uitextbox.h"
#include "assert/assert.h" #include "assert/assert.h"
#include "entity/entitymanager.h"
#include "entity/component/physics/entityphysics.h"
#include "physics/physicsmanager.h"
#include "network/network.h" #include "network/network.h"
#include "system/system.h" #include "system/system.h"
#include "console/console.h" #include "console/console.h"
#include "script/script.h"
#include "item/backpack.h"
#include "save/save.h" #include "save/save.h"
engine_t ENGINE; engine_t ENGINE;
@@ -49,15 +45,13 @@ errorret_t engineInit(const int32_t argc, const char_t **argv) {
errorChain(uiInit()); errorChain(uiInit());
errorChain(uiTextboxInit()); errorChain(uiTextboxInit());
errorChain(cutsceneInit()); errorChain(cutsceneInit());
entityManagerInit(); errorChain(rpgInit());
backpackInit();
physicsManagerInit();
errorChain(networkInit()); errorChain(networkInit());
errorChain(scriptInit());
errorChain(sceneInit()); errorChain(sceneInit());
consolePrint("Engine initialized"); consolePrint("Engine initialized");
errorChain(scriptExecFile("init.js")); sceneSet(SCENE_TYPE_OVERWORLD);
errorOk(); errorOk();
} }
@@ -68,16 +62,15 @@ errorret_t engineUpdate(void) {
timeUpdate(); timeUpdate();
inputUpdate(); inputUpdate();
consoleUpdate(); consoleUpdate();
entityManagerUpdate(); errorChain(rpgUpdate());
uiUpdate(); uiUpdate();
errorChain(uiTextboxUpdate()); errorChain(uiTextboxUpdate());
physicsManagerUpdate();
errorChain(displayUpdate());
errorChain(cutsceneUpdate()); errorChain(cutsceneUpdate());
errorChain(sceneUpdate()); errorChain(sceneUpdate());
errorChain(assetUpdate()); errorChain(assetUpdate());
errorChain(scriptUpdate());
// Render
errorChain(displayUpdate());
if(inputPressed(INPUT_ACTION_RAGEQUIT)) ENGINE.running = false; if(inputPressed(INPUT_ACTION_RAGEQUIT)) ENGINE.running = false;
errorOk(); errorOk();
} }
@@ -90,9 +83,8 @@ errorret_t engineDispose(void) {
uiTextboxDispose(); uiTextboxDispose();
cutsceneDispose(); cutsceneDispose();
errorChain(sceneDispose()); errorChain(sceneDispose());
errorChain(scriptDispose());
errorChain(networkDispose()); errorChain(networkDispose());
entityManagerDispose(); errorChain(rpgDispose());
localeManagerDispose(); localeManagerDispose();
uiDispose(); uiDispose();
consoleDispose(); consoleDispose();
src/dusk/entity/component.c
-149
View File
@@ -1,149 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "entitymanager.h"
#include "assert/assert.h"
#include "util/memory.h"
componentdefinition_t COMPONENT_DEFINITIONS[] = {
[COMPONENT_TYPE_NULL] = { 0 },
#define X(enm, type, field, iMethod, dMethod, rMethod) \
[COMPONENT_TYPE_##enm] = { \
.enumName = #enm, \
.name = #field, \
.init = iMethod, \
.dispose = dMethod, \
.render = rMethod \
},
#include "componentlist.h"
#undef X
[COMPONENT_TYPE_COUNT] = { 0 }
};
void componentInit(
const entityid_t entityId,
const componentid_t componentId,
const componenttype_t type
) {
assertTrue(entityId < ENTITY_COUNT_MAX, "Entity ID OOB");
assertTrue(componentId < ENTITY_COMPONENT_COUNT_MAX, "Component ID OOB");
assertTrue(type < COMPONENT_TYPE_COUNT, "Component type OOB");
assertTrue(type != COMPONENT_TYPE_NULL, "Cannot initialize null component");
componentindex_t index = componentGetIndex(entityId, componentId);
component_t *cmp = &ENTITY_MANAGER.components[index];
memoryZero(cmp, sizeof(component_t));
cmp->type = type;
if(COMPONENT_DEFINITIONS[type].init) {
COMPONENT_DEFINITIONS[type].init(entityId, componentId);
}
}
void * componentGetData(
const entityid_t entityId,
const componentid_t componentId,
const componenttype_t type
) {
assertTrue(entityId < ENTITY_COUNT_MAX, "Entity ID OOB");
assertTrue(componentId < ENTITY_COMPONENT_COUNT_MAX, "Component ID OOB");
assertTrue(type < COMPONENT_TYPE_COUNT, "Component type OOB");
assertTrue(type != COMPONENT_TYPE_NULL, "Cannot get data of null component");
componentindex_t index = componentGetIndex(entityId, componentId);
component_t *cmp = &ENTITY_MANAGER.components[index];
assertTrue(cmp->type == type, "Component type mismatch");
return &cmp->data;
}
componentindex_t componentGetIndex(
const entityid_t entityId,
const componentid_t componentId
) {
assertTrue(entityId < ENTITY_COUNT_MAX, "Entity ID OOB");
assertTrue(componentId < ENTITY_COMPONENT_COUNT_MAX, "Component ID OOB");
return (entityId * ENTITY_COMPONENT_COUNT_MAX) + componentId;
}
entityid_t componentGetEntitiesWithComponent(
const componenttype_t type,
entityid_t outEntities[ENTITY_COUNT_MAX],
componentid_t outComponents[ENTITY_COUNT_MAX]
) {
assertTrue(type < COMPONENT_TYPE_COUNT, "Component type OOB");
assertTrue(type != COMPONENT_TYPE_NULL, "Cannot check NULL type");
assertNotNull(outEntities, "Output entities array cannot be null");
assertNotNull(outComponents, "Output components array cannot be null");
entityid_t written = 0;
for(entityid_t i = 0; i < ENTITY_COUNT_MAX; i++) {
componentid_t used = ENTITY_MANAGER.entitiesWithComponent[
type * ENTITY_COUNT_MAX + i
];
if(used == COMPONENT_ID_INVALID) continue;
assertTrue(
ENTITY_MANAGER.components[componentGetIndex(i, used)].type == type,
"Component type mismatch in entitiesWithComponent lookup"
);
assertTrue(
(ENTITY_MANAGER.entities[i].state & ENTITY_STATE_ACTIVE) != 0,
"Inactive entity in entitiesWithComponent lookup"
);
assertTrue(
used < ENTITY_COMPONENT_COUNT_MAX,
"Component ID OOB in entitiesWithComponent lookup"
);
assertTrue(
componentGetIndex(i,used) < ENTITY_COUNT_MAX*ENTITY_COMPONENT_COUNT_MAX,
"Component index OOB in entitiesWithComponent lookup"
);
assertTrue(
ENTITY_MANAGER.components[componentGetIndex(i,used)].type == type,
"Component type mismatch in entitiesWithComponent lookup"
);
outComponents[written] = used;
outEntities[written++] = i;
}
return written;
}
errorret_t componentRenderAll(void) {
for(entityid_t eid = 0; eid < ENTITY_COUNT_MAX; eid++) {
if(!(ENTITY_MANAGER.entities[eid].state & ENTITY_STATE_ACTIVE)) continue;
for(componentid_t cid = 0; cid < ENTITY_COMPONENT_COUNT_MAX; cid++) {
component_t *cmp = &ENTITY_MANAGER.components[
componentGetIndex(eid, cid)
];
if(cmp->type == COMPONENT_TYPE_NULL) continue;
if(!COMPONENT_DEFINITIONS[cmp->type].render) continue;
errorChain(COMPONENT_DEFINITIONS[cmp->type].render(eid, cid));
}
}
errorOk();
}
void componentDispose(
const entityid_t entityId,
const componentid_t componentId
) {
assertTrue(entityId < ENTITY_COUNT_MAX, "Entity ID OOB");
assertTrue(componentId < ENTITY_COMPONENT_COUNT_MAX, "Component ID OOB");
componentindex_t index = componentGetIndex(entityId, componentId);
component_t *cmp = &ENTITY_MANAGER.components[index];
if(cmp->type == COMPONENT_TYPE_NULL) return;
if(COMPONENT_DEFINITIONS[cmp->type].dispose) {
COMPONENT_DEFINITIONS[cmp->type].dispose(entityId, componentId);
}
cmp->type = COMPONENT_TYPE_NULL;
}
src/dusk/entity/component.h
-120
View File
@@ -1,120 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "entitybase.h"
#define X(enumName, type, field, init, dispose, render) \
// do nothing
#include "componentlist.h"
#undef X
typedef union {
#define X(enumName, type, field, init, dispose, render) type field;
#include "componentlist.h"
#undef X
} componentdata_t;
typedef struct {
const char_t *enumName;
const char_t *name;
void (*init)(const entityid_t, const componentid_t);
void (*dispose)(const entityid_t, const componentid_t);
errorret_t (*render)(const entityid_t, const componentid_t);
} componentdefinition_t;
typedef enum {
COMPONENT_TYPE_NULL,
#define X(enumName, type, field, init, dispose, render) \
COMPONENT_TYPE_##enumName,
#include "componentlist.h"
#undef X
COMPONENT_TYPE_COUNT
} componenttype_t;
typedef struct {
componenttype_t type;
componentdata_t data;
} component_t;
extern componentdefinition_t COMPONENT_DEFINITIONS[];
/**
* Initializes a component of the given type for the entity with component ID.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param type The type of the component to initialize.
*/
void componentInit(
const entityid_t entityId,
const componentid_t componentId,
const componenttype_t type
);
/**
* Gets the pointer to the data of a component for the entity with component ID.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param type The type of the component to get, only used for assertion.
* @return A pointer to the component data.
*/
void * componentGetData(
const entityid_t entityId,
const componentid_t componentId,
const componenttype_t type
);
/**
* Gets the index of a component for the entity with component ID.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @return The index of the component in the component array.
*/
componentindex_t componentGetIndex(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Gets the entity IDs of all entities with a component of the given type.
*
* @param type The type of the component to get entities for.
* @param outEntities An array to write the entity IDs to, must be at least
* ENTITY_COUNT_MAX in size.
* @param outComponents An array to write the component IDs to.
* @return The number of entity IDs written to outEntities.
*/
entityid_t componentGetEntitiesWithComponent(
const componenttype_t type,
entityid_t outEntities[ENTITY_COUNT_MAX],
componentid_t outComponents[ENTITY_COUNT_MAX]
);
/**
* Disposes of a component for the entity with component ID.
*
* @param entityId The entity ID.
* @param componentId The component ID.
*/
void componentDispose(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Calls the render callback on every active component that defines one.
* Iterates all active entities and all their component slots. No-op for
* components whose definition has render == NULL.
*
* @return Error state.
*/
errorret_t componentRenderAll(void);
src/dusk/entity/component/CMakeLists.txt
-8
View File
@@ -1,8 +0,0 @@
# Copyright (c) 2026 Dominic Masters
#
# This software is released under the MIT License.
# https://opensource.org/licenses/MIT
add_subdirectory(display)
add_subdirectory(physics)
add_subdirectory(trigger)
src/dusk/entity/component/display/CMakeLists.txt
-12
View File
@@ -1,12 +0,0 @@
# Copyright (c) 2026 Dominic Masters
#
# This software is released under the MIT License.
# https://opensource.org/licenses/MIT
# Sources
target_sources(${DUSK_LIBRARY_TARGET_NAME}
PUBLIC
entityposition.c
entitycamera.c
entityrenderable.c
)
src/dusk/entity/component/display/entitycamera.c
-120
View File
@@ -1,120 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "entity/entitymanager.h"
#include "entity/entity.h"
#include "entity/component/display/entityposition.h"
#include "display/framebuffer/framebuffer.h"
#include "display/screen/screen.h"
void entityCameraInit(const entityid_t ent, const componentid_t comp) {
entitycamera_t *cam = (entitycamera_t *)componentGetData(
ent, comp, COMPONENT_TYPE_CAMERA
);
cam->nearClip = 0.1f;
cam->farClip = 5000.0f;
cam->projType = ENTITY_CAMERA_PROJECTION_TYPE_PERSPECTIVE;
cam->perspective.fov = glm_rad(45.0f);
}
void entityCameraGetProjection(
const entityid_t ent,
const componentid_t comp,
mat4 out
) {
entitycamera_t *cam = (entitycamera_t *)componentGetData(
ent, comp, COMPONENT_TYPE_CAMERA
);
if(
cam->projType == ENTITY_CAMERA_PROJECTION_TYPE_PERSPECTIVE ||
cam->projType == ENTITY_CAMERA_PROJECTION_TYPE_PERSPECTIVE_FLIPPED
) {
glm_mat4_identity(out);
glm_perspective(
cam->perspective.fov,
SCREEN.aspect,
cam->nearClip,
cam->farClip,
out
);
if(cam->projType == ENTITY_CAMERA_PROJECTION_TYPE_PERSPECTIVE_FLIPPED) {
out[1][1] *= -1.0f;
}
} else if(cam->projType == ENTITY_CAMERA_PROJECTION_TYPE_ORTHOGRAPHIC) {
glm_mat4_identity(out);
glm_ortho(
cam->orthographic.left,
cam->orthographic.right,
cam->orthographic.top,
cam->orthographic.bottom,
cam->nearClip,
cam->farClip,
out
);
}
}
entityid_t entityCameraGetCurrent(void) {
entityid_t camEnts[ENTITY_COUNT_MAX];
componentid_t camComps[ENTITY_COUNT_MAX];
entityid_t count = componentGetEntitiesWithComponent(
COMPONENT_TYPE_CAMERA, camEnts, camComps
);
if(count == 0) return ENTITY_ID_INVALID;
return camEnts[0];
}
void entityCameraGetForward(const entityid_t entityId, vec2 out) {
componentid_t posComp = entityGetComponent(entityId, COMPONENT_TYPE_POSITION);
entityposition_t *pos = entityPositionGet(entityId, posComp);
// View matrix column layout: M[col][row],
// forward = {-M[0][2], -M[1][2], -M[2][2]}
float_t fx = -pos->worldTransform[0][2];
float_t fz = -pos->worldTransform[2][2];
float_t len = sqrtf(fx * fx + fz * fz);
if(len > 1e-6f) { fx /= len; fz /= len; }
out[0] = fx;
out[1] = fz;
}
void entityCameraLookAtPixelPerfect(
const entityid_t ent,
const componentid_t posComp,
const componentid_t camComp,
const vec3 point,
const vec3 eyeOffset,
const float_t scale
) {
entitycamera_t *cam = (entitycamera_t *)componentGetData(
ent, camComp, COMPONENT_TYPE_CAMERA
);
float_t dist = (
(float_t)SCREEN.height / (2.0f * scale * tanf(cam->perspective.fov * 0.5f))
);
vec3 eye = {
point[0] + eyeOffset[0],
point[1] + dist + eyeOffset[1],
point[2] + eyeOffset[2]
};
vec3 up = { 0.0f, 0.0f, -1.0f };
entityPositionLookAt(ent, posComp, eye, (float_t *)point, up);
}
void entityCameraGetRight(const entityid_t entityId, vec2 out) {
componentid_t posComp = entityGetComponent(entityId, COMPONENT_TYPE_POSITION);
entityposition_t *pos = entityPositionGet(entityId, posComp);
// View matrix column layout: right = {M[0][0], M[1][0], M[2][0]}
float_t rx = pos->worldTransform[0][0];
float_t rz = pos->worldTransform[2][0];
float_t len = sqrtf(rx * rx + rz * rz);
if(len > 1e-6f) { rx /= len; rz /= len; }
out[0] = rx;
out[1] = rz;
}
src/dusk/entity/component/display/entitycamera.h
-99
View File
@@ -1,99 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "entity/entitybase.h"
typedef enum {
ENTITY_CAMERA_PROJECTION_TYPE_PERSPECTIVE,
ENTITY_CAMERA_PROJECTION_TYPE_PERSPECTIVE_FLIPPED,
ENTITY_CAMERA_PROJECTION_TYPE_ORTHOGRAPHIC
} entitycameraprojectiontype_t;
typedef struct {
union {
struct {
float_t fov;
} perspective;
struct {
float_t left;
float_t right;
float_t top;
float_t bottom;
} orthographic;
};
float_t nearClip;
float_t farClip;
entitycameraprojectiontype_t projType;
} entitycamera_t;
/**
* Initializes an entity camera component.
*
* @param ent The entity ID.
* @param comp The component ID.
*/
void entityCameraInit(const entityid_t ent, const componentid_t comp);
/**
* Renders out the projection matrix for the given camera.
*
* @param ent The entity ID.
* @param comp The component ID.
* @param out The output projection matrix.
*/
void entityCameraGetProjection(
const entityid_t ent,
const componentid_t comp,
mat4 out
);
/**
* Returns the entity ID of the first active camera, or ENTITY_ID_INVALID if
* none are active.
*/
entityid_t entityCameraGetCurrent(void);
/**
* Gets the camera's horizontal forward direction (XZ plane) from its position
* component. Automatically finds the position component on the entity.
*
* @param entityId The camera entity ID.
* @param out Output vec2: {forwardX, forwardZ} normalized.
*/
void entityCameraGetForward(const entityid_t entityId, vec2 out);
/**
* Gets the camera's horizontal right direction (XZ plane) from its position
* component. Automatically finds the position component on the entity.
*
* @param entityId The camera entity ID.
* @param out Output vec2: {rightX, rightZ} normalized.
*/
void entityCameraGetRight(const entityid_t entityId, vec2 out);
/**
* Positions the camera to look at a 3D point at a pixel-perfect distance
* derived from the camera's FOV and screen height.
*
* @param ent The camera entity ID.
* @param posComp The position component ID.
* @param camComp The camera component ID.
* @param point World position to look at.
* @param eyeOffset Offset added to the eye position only (not the target).
* @param scale Pixels per world unit. 1.0 = pixel perfect, 2.0 = 2px per unit.
*/
void entityCameraLookAtPixelPerfect(
const entityid_t ent,
const componentid_t posComp,
const componentid_t camComp,
const vec3 point,
const vec3 eyeOffset,
const float_t scale
);
src/dusk/entity/component/display/entityposition.c
-630
View File
@@ -1,630 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "entity/entitymanager.h"
// Decompose localTransform into the PRS cache. Only called when PRS_DIRTY.
static void entityPositionEnsurePRS(entityposition_t *pos) {
if(!(pos->flags & ENTITY_POSITION_FLAG_PRS_DIRTY)) return;
entityPositionDecompose(pos);
pos->flags &= ~ENTITY_POSITION_FLAG_PRS_DIRTY;
}
// Rebuild localTransform from the PRS cache. Only rebuilds what changed.
static void entityPositionEnsureLocal(entityposition_t *pos) {
const uint8_t dirty = pos->flags & (
ENTITY_POSITION_FLAG_ROTATION_DIRTY | ENTITY_POSITION_FLAG_POSITION_DIRTY
);
if(!dirty) return;
if(dirty & ENTITY_POSITION_FLAG_ROTATION_DIRTY) {
// Rotation or scale changed: rebuild cols 0-2 analytically (XYZ euler).
const float_t c0 = cosf(pos->rotation[0]), s0 = sinf(pos->rotation[0]);
const float_t c1 = cosf(pos->rotation[1]), s1 = sinf(pos->rotation[1]);
const float_t c2 = cosf(pos->rotation[2]), s2 = sinf(pos->rotation[2]);
const float_t s0s1 = s0 * s1;
const float_t c0s1 = c0 * s1;
pos->localTransform[0][0] = c1 * c2 * pos->scale[0];
pos->localTransform[0][1] = (c0 * s2 + s0s1 * c2) * pos->scale[0];
pos->localTransform[0][2] = (s0 * s2 - c0s1 * c2) * pos->scale[0];
pos->localTransform[0][3] = 0.0f;
pos->localTransform[1][0] = -c1 * s2 * pos->scale[1];
pos->localTransform[1][1] = (c0 * c2 - s0s1 * s2) * pos->scale[1];
pos->localTransform[1][2] = (s0 * c2 + c0s1 * s2) * pos->scale[1];
pos->localTransform[1][3] = 0.0f;
pos->localTransform[2][0] = s1 * pos->scale[2];
pos->localTransform[2][1] = -s0 * c1 * pos->scale[2];
pos->localTransform[2][2] = c0 * c1 * pos->scale[2];
pos->localTransform[2][3] = 0.0f;
}
if(dirty & ENTITY_POSITION_FLAG_POSITION_DIRTY) {
// Only position changed: update column 3 only (no trig needed).
pos->localTransform[3][0] = pos->position[0];
pos->localTransform[3][1] = pos->position[1];
pos->localTransform[3][2] = pos->position[2];
pos->localTransform[3][3] = 1.0f;
}
pos->flags &= ~(
ENTITY_POSITION_FLAG_ROTATION_DIRTY | ENTITY_POSITION_FLAG_POSITION_DIRTY
);
}
// Recompute worldTransform from the parent chain. Only called when WORLD_DIRTY.
static void entityPositionEnsureWorld(entityposition_t *pos) {
if(!(pos->flags & ENTITY_POSITION_FLAG_WORLD_DIRTY)) return;
entityPositionEnsureLocal(pos);
if(pos->parentEntityId != ENTITY_ID_INVALID) {
// Parented: world = parent.world x local. worldTransform must be written
// because children (and this node's getters) read it.
entityposition_t *parent = componentGetData(
pos->parentEntityId, pos->parentComponentId, COMPONENT_TYPE_POSITION
);
entityPositionEnsureWorld(parent);
glm_mat4_mul(
parent->worldTransform, pos->localTransform, pos->worldTransform
);
} else if(pos->childCount > 0) {
// Parentless root with children: children need a valid worldTransform to
// multiply against, but world == local, so just copy.
glm_mat4_copy(pos->localTransform, pos->worldTransform);
}
// Parentless leaf: world == local. Getters read localTransform directly;
// no copy needed.
pos->flags &= ~ENTITY_POSITION_FLAG_WORLD_DIRTY;
}
void entityPositionMarkDirty(entityposition_t *pos) {
if(pos->flags & ENTITY_POSITION_FLAG_WORLD_DIRTY) return;
pos->flags |= ENTITY_POSITION_FLAG_WORLD_DIRTY;
for(uint8_t i = 0; i < pos->childCount; i++) {
entityposition_t *child = componentGetData(
pos->childEntityIds[i], pos->childComponentIds[i], COMPONENT_TYPE_POSITION
);
entityPositionMarkDirty(child);
}
}
void entityPositionInit(
const entityid_t entityId,
const componentid_t componentId
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
pos->flags = 0;
pos->parentEntityId = ENTITY_ID_INVALID;
pos->parentComponentId = COMPONENT_ID_INVALID;
pos->childCount = 0;
glm_vec3_zero(pos->position);
glm_vec3_zero(pos->rotation);
glm_vec3_one(pos->scale);
glm_mat4_identity(pos->localTransform);
glm_mat4_identity(pos->worldTransform);
}
void entityPositionLookAt(
const entityid_t entityId,
const componentid_t componentId,
vec3 eye,
vec3 target,
vec3 up
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
glm_lookat(eye, target, up, pos->localTransform);
// localTransform is now authoritative; PRS cache is stale.
pos->flags = (pos->flags | ENTITY_POSITION_FLAG_PRS_DIRTY)
& ~(ENTITY_POSITION_FLAG_ROTATION_DIRTY |
ENTITY_POSITION_FLAG_POSITION_DIRTY);
entityPositionMarkDirty(pos);
}
void entityPositionGetTransform(
const entityid_t entityId,
const componentid_t componentId,
mat4 dest
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
entityPositionEnsureWorld(pos);
glm_mat4_copy(
pos->parentEntityId == ENTITY_ID_INVALID
? pos->localTransform : pos->worldTransform,
dest
);
}
void entityPositionGetLocalTransform(
const entityid_t entityId,
const componentid_t componentId,
mat4 dest
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
entityPositionEnsureLocal(pos);
glm_mat4_copy(pos->localTransform, dest);
}
void entityPositionGetLocalPosition(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
entityPositionEnsurePRS(pos);
glm_vec3_copy(pos->position, dest);
}
void entityPositionGetWorldPosition(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
if(pos->parentEntityId == ENTITY_ID_INVALID) {
entityPositionEnsurePRS(pos);
glm_vec3_copy(pos->position, dest);
return;
}
entityPositionEnsureWorld(pos);
dest[0] = pos->worldTransform[3][0];
dest[1] = pos->worldTransform[3][1];
dest[2] = pos->worldTransform[3][2];
}
void entityPositionSetWorldPosition(
const entityid_t entityId,
const componentid_t componentId,
vec3 position
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
if(pos->parentEntityId == ENTITY_ID_INVALID) {
glm_vec3_copy(position, pos->position);
pos->flags = (pos->flags | ENTITY_POSITION_FLAG_POSITION_DIRTY)
& ~ENTITY_POSITION_FLAG_PRS_DIRTY;
entityPositionMarkDirty(pos);
return;
}
entityposition_t *parent = componentGetData(
pos->parentEntityId, pos->parentComponentId, COMPONENT_TYPE_POSITION
);
entityPositionEnsureWorld(parent);
mat4 invParent;
glm_mat4_inv(parent->worldTransform, invParent);
vec3 localPos;
glm_mat4_mulv3(invParent, position, 1.0f, localPos);
glm_vec3_copy(localPos, pos->position);
pos->flags = (pos->flags | ENTITY_POSITION_FLAG_POSITION_DIRTY)
& ~ENTITY_POSITION_FLAG_PRS_DIRTY;
entityPositionMarkDirty(pos);
}
void entityPositionSetLocalPosition(
const entityid_t entityId,
const componentid_t componentId,
vec3 position
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
glm_vec3_copy(position, pos->position);
pos->flags = (pos->flags | ENTITY_POSITION_FLAG_POSITION_DIRTY)
& ~ENTITY_POSITION_FLAG_PRS_DIRTY;
entityPositionMarkDirty(pos);
}
void entityPositionGetLocalRotation(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
entityPositionEnsurePRS(pos);
glm_vec3_copy(pos->rotation, dest);
}
void entityPositionGetWorldRotation(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
if(pos->parentEntityId == ENTITY_ID_INVALID) {
entityPositionEnsurePRS(pos);
glm_vec3_copy(pos->rotation, dest);
return;
}
entityPositionEnsureWorld(pos);
const float_t (*wt)[4] = pos->worldTransform;
const float_t sx = sqrtf(
wt[0][0]*wt[0][0] + wt[0][1]*wt[0][1] + wt[0][2]*wt[0][2]
);
const float_t sy = sqrtf(
wt[1][0]*wt[1][0] + wt[1][1]*wt[1][1] + wt[1][2]*wt[1][2]
);
const float_t sz = sqrtf(
wt[2][0]*wt[2][0] + wt[2][1]*wt[2][1] + wt[2][2]*wt[2][2]
);
const float_t r00 = sx > 0.0f ? wt[0][0]/sx : 0.0f;
const float_t r10 = sy > 0.0f ? wt[1][0]/sy : 0.0f;
const float_t r20 = sz > 0.0f ? wt[2][0]/sz : 0.0f;
const float_t r01 = sx > 0.0f ? wt[0][1]/sx : 0.0f;
const float_t r11 = sy > 0.0f ? wt[1][1]/sy : 0.0f;
const float_t r21 = sz > 0.0f ? wt[2][1]/sz : 0.0f;
const float_t r22 = sz > 0.0f ? wt[2][2]/sz : 0.0f;
const float_t sinBeta = glm_clamp(r20, -1.0f, 1.0f);
dest[1] = asinf(sinBeta);
const float_t cosBeta = cosf(dest[1]);
if(fabsf(cosBeta) > 1e-6f) {
dest[0] = atan2f(-r21, r22);
dest[2] = atan2f(-r10, r00);
} else {
dest[2] = 0.0f;
dest[0] = (sinBeta > 0.0f) ? atan2f(r01, r11) : -atan2f(r01, r11);
}
}
void entityPositionSetLocalRotation(
const entityid_t entityId,
const componentid_t componentId,
vec3 rotation
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
glm_vec3_copy(rotation, pos->rotation);
pos->flags = (pos->flags | ENTITY_POSITION_FLAG_ROTATION_DIRTY)
& ~ENTITY_POSITION_FLAG_PRS_DIRTY;
entityPositionMarkDirty(pos);
}
void entityPositionSetWorldRotation(
const entityid_t entityId,
const componentid_t componentId,
vec3 rotation
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
if(pos->parentEntityId == ENTITY_ID_INVALID) {
glm_vec3_copy(rotation, pos->rotation);
pos->flags = (pos->flags | ENTITY_POSITION_FLAG_ROTATION_DIRTY)
& ~ENTITY_POSITION_FLAG_PRS_DIRTY;
entityPositionMarkDirty(pos);
return;
}
entityposition_t *parent = componentGetData(
pos->parentEntityId, pos->parentComponentId, COMPONENT_TYPE_POSITION
);
entityPositionEnsureWorld(parent);
// Build target world rotation matrix (unit scale) from XYZ euler.
const float_t c0 = cosf(rotation[0]), s0 = sinf(rotation[0]);
const float_t c1 = cosf(rotation[1]), s1 = sinf(rotation[1]);
const float_t c2 = cosf(rotation[2]), s2 = sinf(rotation[2]);
const float_t s0s1 = s0*s1, c0s1 = c0*s1;
// Named wr[col_stored][row_stored] matching cglm column-major layout.
const float_t wr00 = c1*c2;
const float_t wr01 = c0*s2 + s0s1*c2;
const float_t wr02 = s0*s2 - c0s1*c2;
const float_t wr10 = -c1*s2;
const float_t wr11 = c0*c2 - s0s1*s2;
const float_t wr12 = s0*c2 + c0s1*s2;
const float_t wr20 = s1;
const float_t wr21 = -s0*c1;
const float_t wr22 = c0*c1;
// Normalize parent world columns to extract pure rotation.
const float_t (*pt)[4] = parent->worldTransform;
const float_t psx = sqrtf(
pt[0][0]*pt[0][0] + pt[0][1]*pt[0][1] + pt[0][2]*pt[0][2]
);
const float_t psy = sqrtf(
pt[1][0]*pt[1][0] + pt[1][1]*pt[1][1] + pt[1][2]*pt[1][2]
);
const float_t psz = sqrtf(
pt[2][0]*pt[2][0] + pt[2][1]*pt[2][1] + pt[2][2]*pt[2][2]
);
const float_t pr00 = psx > 0.f ? pt[0][0]/psx : 0.f;
const float_t pr01 = psx > 0.f ? pt[0][1]/psx : 0.f;
const float_t pr02 = psx > 0.f ? pt[0][2]/psx : 0.f;
const float_t pr10 = psy > 0.f ? pt[1][0]/psy : 0.f;
const float_t pr11 = psy > 0.f ? pt[1][1]/psy : 0.f;
const float_t pr12 = psy > 0.f ? pt[1][2]/psy : 0.f;
const float_t pr20 = psz > 0.f ? pt[2][0]/psz : 0.f;
const float_t pr21 = psz > 0.f ? pt[2][1]/psz : 0.f;
const float_t pr22 = psz > 0.f ? pt[2][2]/psz : 0.f;
// local_R = parent_R^T * world_R (R^-1 == R^T for orthogonal matrices).
// Compute only the 7 entries of the local rotation matrix needed for XYZ
// euler extraction (stored column-major: [col][row] = math [row][col]).
// sinBeta = stored[2][0] = math[0][2]
// r21/r22 = stored[2][1..2] = math[1..2][2]
// r10/r00 = stored[1][0], stored[0][0] = math[0][1], math[0][0]
// gimbal = stored[0][1], stored[1][1] = math[1][0], math[1][1]
const float_t lr00 = pr00*wr00 + pr01*wr10 + pr02*wr20; // math[0][0]
const float_t lr10 = pr00*wr01 + pr01*wr11 + pr02*wr21; // math[0][1]
const float_t lr20 = pr00*wr02 + pr01*wr12 + pr02*wr22; // [0][2] -> sinBeta
const float_t lr01 = pr10*wr00 + pr11*wr10 + pr12*wr20; // math[1][0]
const float_t lr11 = pr10*wr01 + pr11*wr11 + pr12*wr21; // math[1][1]
const float_t lr21 = pr10*wr02 + pr11*wr12 + pr12*wr22; // [1][2] -> r21
const float_t lr22 = pr20*wr02 + pr21*wr12 + pr22*wr22; // [2][2] -> r22
const float_t sinBeta = glm_clamp(lr20, -1.0f, 1.0f);
pos->rotation[1] = asinf(sinBeta);
const float_t cosBeta = cosf(pos->rotation[1]);
if(fabsf(cosBeta) > 1e-6f) {
pos->rotation[0] = atan2f(-lr21, lr22);
pos->rotation[2] = atan2f(-lr10, lr00);
} else {
pos->rotation[2] = 0.0f;
pos->rotation[0] = (sinBeta > 0.0f)
? atan2f(lr01, lr11) : -atan2f(lr01, lr11);
}
pos->flags = (pos->flags | ENTITY_POSITION_FLAG_ROTATION_DIRTY)
& ~ENTITY_POSITION_FLAG_PRS_DIRTY;
entityPositionMarkDirty(pos);
}
void entityPositionGetLocalScale(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
entityPositionEnsurePRS(pos);
glm_vec3_copy(pos->scale, dest);
}
void entityPositionGetWorldScale(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
if(pos->parentEntityId == ENTITY_ID_INVALID) {
entityPositionEnsurePRS(pos);
glm_vec3_copy(pos->scale, dest);
return;
}
entityPositionEnsureWorld(pos);
const float_t (*wt)[4] = pos->worldTransform;
dest[0] = sqrtf(wt[0][0]*wt[0][0] + wt[0][1]*wt[0][1] + wt[0][2]*wt[0][2]);
dest[1] = sqrtf(wt[1][0]*wt[1][0] + wt[1][1]*wt[1][1] + wt[1][2]*wt[1][2]);
dest[2] = sqrtf(wt[2][0]*wt[2][0] + wt[2][1]*wt[2][1] + wt[2][2]*wt[2][2]);
}
void entityPositionSetLocalScale(
const entityid_t entityId,
const componentid_t componentId,
vec3 scale
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
glm_vec3_copy(scale, pos->scale);
pos->flags = (pos->flags | ENTITY_POSITION_FLAG_ROTATION_DIRTY)
& ~ENTITY_POSITION_FLAG_PRS_DIRTY;
entityPositionMarkDirty(pos);
}
void entityPositionSetWorldScale(
const entityid_t entityId,
const componentid_t componentId,
vec3 scale
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
if(pos->parentEntityId == ENTITY_ID_INVALID) {
glm_vec3_copy(scale, pos->scale);
pos->flags = (pos->flags | ENTITY_POSITION_FLAG_ROTATION_DIRTY)
& ~ENTITY_POSITION_FLAG_PRS_DIRTY;
entityPositionMarkDirty(pos);
return;
}
entityposition_t *parent = componentGetData(
pos->parentEntityId, pos->parentComponentId, COMPONENT_TYPE_POSITION
);
entityPositionEnsureWorld(parent);
const float_t (*pt)[4] = parent->worldTransform;
const float_t psx = sqrtf(
pt[0][0]*pt[0][0] + pt[0][1]*pt[0][1] + pt[0][2]*pt[0][2]
);
const float_t psy = sqrtf(
pt[1][0]*pt[1][0] + pt[1][1]*pt[1][1] + pt[1][2]*pt[1][2]
);
const float_t psz = sqrtf(
pt[2][0]*pt[2][0] + pt[2][1]*pt[2][1] + pt[2][2]*pt[2][2]
);
pos->scale[0] = psx > 0.0f ? scale[0] / psx : scale[0];
pos->scale[1] = psy > 0.0f ? scale[1] / psy : scale[1];
pos->scale[2] = psz > 0.0f ? scale[2] / psz : scale[2];
pos->flags = (pos->flags | ENTITY_POSITION_FLAG_ROTATION_DIRTY)
& ~ENTITY_POSITION_FLAG_PRS_DIRTY;
entityPositionMarkDirty(pos);
}
void entityPositionSetParent(
const entityid_t entityId,
const componentid_t componentId,
const entityid_t parentEntityId,
const componentid_t parentComponentId
) {
entityposition_t *pos = componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
// Remove from old parent's child list.
if(pos->parentEntityId != ENTITY_ID_INVALID) {
entityposition_t *oldParent = componentGetData(
pos->parentEntityId, pos->parentComponentId, COMPONENT_TYPE_POSITION
);
for(uint8_t i = 0; i < oldParent->childCount; i++) {
if(
oldParent->childEntityIds[i] == entityId &&
oldParent->childComponentIds[i] == componentId
) {
oldParent->childCount--;
for(uint8_t j = i; j < oldParent->childCount; j++) {
oldParent->childEntityIds[j] = oldParent->childEntityIds[j + 1];
oldParent->childComponentIds[j] = oldParent->childComponentIds[j + 1];
}
break;
}
}
}
pos->parentEntityId = parentEntityId;
pos->parentComponentId = parentComponentId;
// Register with new parent.
if(parentEntityId != ENTITY_ID_INVALID) {
entityposition_t *parent = componentGetData(
parentEntityId, parentComponentId, COMPONENT_TYPE_POSITION
);
if(parent->childCount < ENTITY_POSITION_CHILDREN_MAX) {
parent->childEntityIds[parent->childCount] = entityId;
parent->childComponentIds[parent->childCount] = componentId;
parent->childCount++;
}
}
entityPositionMarkDirty(pos);
}
entityposition_t *entityPositionGet(
const entityid_t entityId,
const componentid_t componentId
) {
return componentGetData(
entityId, componentId, COMPONENT_TYPE_POSITION
);
}
void entityPositionRebuild(entityposition_t *pos) {
pos->flags = (
pos->flags |
ENTITY_POSITION_FLAG_ROTATION_DIRTY |
ENTITY_POSITION_FLAG_POSITION_DIRTY
) & ~ENTITY_POSITION_FLAG_PRS_DIRTY;
entityPositionMarkDirty(pos);
}
void entityPositionDisposeDeep(
const entityid_t entityId,
const componentid_t componentId
) {
entityposition_t *pos = entityPositionGet(entityId, componentId);
// Detach from parent so the parent's child list stays consistent.
if(pos->parentEntityId != ENTITY_ID_INVALID) {
entityPositionSetParent(
entityId, componentId, ENTITY_ID_INVALID, COMPONENT_ID_INVALID
);
}
// Copy the child list before disposing self (entityDispose invalidates pos).
uint8_t childCount = pos->childCount;
entityid_t childEntityIds[ENTITY_POSITION_CHILDREN_MAX];
componentid_t childComponentIds[ENTITY_POSITION_CHILDREN_MAX];
for(uint8_t i = 0; i < childCount; i++) {
childEntityIds[i] = pos->childEntityIds[i];
childComponentIds[i] = pos->childComponentIds[i];
// Sever child's parent link so it won't try to modify our disposed data.
entityposition_t *child = entityPositionGet(
childEntityIds[i], childComponentIds[i]
);
child->parentEntityId = ENTITY_ID_INVALID;
child->parentComponentId = COMPONENT_ID_INVALID;
}
entityDispose(entityId);
for(uint8_t i = 0; i < childCount; i++) {
entityPositionDisposeDeep(childEntityIds[i], childComponentIds[i]);
}
}
void entityPositionDecompose(entityposition_t *pos) {
// Translation: column 3
pos->position[0] = pos->localTransform[3][0];
pos->position[1] = pos->localTransform[3][1];
pos->position[2] = pos->localTransform[3][2];
// Scale: length of each basis column (xyz only)
pos->scale[0] = sqrtf(
pos->localTransform[0][0] * pos->localTransform[0][0] +
pos->localTransform[0][1] * pos->localTransform[0][1] +
pos->localTransform[0][2] * pos->localTransform[0][2]
);
pos->scale[1] = sqrtf(
pos->localTransform[1][0] * pos->localTransform[1][0] +
pos->localTransform[1][1] * pos->localTransform[1][1] +
pos->localTransform[1][2] * pos->localTransform[1][2]
);
pos->scale[2] = sqrtf(
pos->localTransform[2][0] * pos->localTransform[2][0] +
pos->localTransform[2][1] * pos->localTransform[2][1] +
pos->localTransform[2][2] * pos->localTransform[2][2]
);
// Normalize columns to isolate the rotation matrix (no mat4 needed).
const float_t invS0 = pos->scale[0] > 0.0f ? 1.0f / pos->scale[0] : 0.0f;
const float_t invS1 = pos->scale[1] > 0.0f ? 1.0f / pos->scale[1] : 0.0f;
const float_t invS2 = pos->scale[2] > 0.0f ? 1.0f / pos->scale[2] : 0.0f;
const float_t r00 = pos->localTransform[0][0] * invS0;
const float_t r01 = pos->localTransform[0][1] * invS0;
const float_t r02 = pos->localTransform[0][2] * invS0;
const float_t r10 = pos->localTransform[1][0] * invS1;
const float_t r11 = pos->localTransform[1][1] * invS1;
const float_t r20 = pos->localTransform[2][0] * invS2;
const float_t r21 = pos->localTransform[2][1] * invS2;
const float_t r22 = pos->localTransform[2][2] * invS2;
// Extract XYZ euler angles (R = Rx * Ry * Rz, column-major)
const float_t sinBeta = glm_clamp(r20, -1.0f, 1.0f);
pos->rotation[1] = asinf(sinBeta);
const float_t cosBeta = cosf(pos->rotation[1]);
if(fabsf(cosBeta) > 1e-6f) {
pos->rotation[0] = atan2f(-r21, r22);
pos->rotation[2] = atan2f(-r10, r00);
} else {
// Gimbal lock: pin Z to 0, recover X.
pos->rotation[2] = 0.0f;
pos->rotation[0] = (sinBeta > 0.0f)
? atan2f(r01, r11)
: -atan2f(r01, r11);
}
}
src/dusk/entity/component/display/entityposition.h
-375
View File
@@ -1,375 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "entity/entitybase.h"
/** Maximum number of child position components this node can track. */
#define ENTITY_POSITION_CHILDREN_MAX 8
/**
* PRS cache is stale. localTransform was written directly (e.g. lookAt) and
* position/rotation/scale need to be decomposed before they can be read.
*/
#define ENTITY_POSITION_FLAG_PRS_DIRTY (1 << 0)
/**
* Columns 0-2 of localTransform are stale. Rotation or scale changed; the
* basis vectors need to be rebuilt analytically before the matrix can be used.
* Does not imply column 3 (translation) is stale.
*/
#define ENTITY_POSITION_FLAG_ROTATION_DIRTY (1 << 1)
/**
* Column 3 of localTransform is stale. Position changed; only the translation
* column needs to be written. Does not imply columns 0-2 are stale.
*/
#define ENTITY_POSITION_FLAG_POSITION_DIRTY (1 << 2)
/**
* worldTransform is stale. Either the local matrix changed or an ancestor
* moved; worldTransform must be recomputed before world data can be read.
*/
#define ENTITY_POSITION_FLAG_WORLD_DIRTY (1 << 3)
typedef struct {
/*
* Hot fields - flag checks, parent/child traversal (markDirty, ensureWorld)
* only touch these. Kept at the front so they share the first cache line.
*/
/** ENTITY_POSITION_FLAG_* bitmask; describes which caches are stale. */
uint8_t flags;
/** Entity ID of the parent node, or ENTITY_ID_INVALID if none. */
entityid_t parentEntityId;
/** Component ID of the parent position, or COMPONENT_ID_INVALID if none. */
componentid_t parentComponentId;
/** Number of currently registered children. */
uint8_t childCount;
/** Entity IDs of child nodes. */
entityid_t childEntityIds[ENTITY_POSITION_CHILDREN_MAX];
/** Component IDs of child position components. */
componentid_t childComponentIds[ENTITY_POSITION_CHILDREN_MAX];
/*
* Warm fields - read/written by PRS getters/setters.
* Accessed more often than the matrices but less often than flags.
*/
/** Cached local position (XYZ). Stale when PRS_DIRTY is set. */
vec3 position;
/** Cached local rotation (XYZ euler, radians). Stale when PRS_DIRTY. */
vec3 rotation;
/** Cached local scale (XYZ). Stale when PRS_DIRTY is set. */
vec3 scale;
/*
* Cold fields - only touched when actually rebuilding transforms.
*/
/** Local transform matrix, rebuilt lazily from position/rotation/scale. */
mat4 localTransform;
/** World transform matrix, recomputed lazily from the parent chain. */
mat4 worldTransform;
} entityposition_t;
/**
* Initializes the entity position component, setting identity transforms and
* zeroing all parent/child state.
*
* @param entityId The entity ID.
* @param componentId The component ID.
*/
void entityPositionInit(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Transforms the entity's local transform to look at a target point.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param eye The eye/camera position.
* @param target The target point to look at.
* @param up The up vector.
*/
void entityPositionLookAt(
const entityid_t entityId,
const componentid_t componentId,
vec3 eye,
vec3 target,
vec3 up
);
/**
* Gets the world-space transform matrix, recomputing it lazily if dirty.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param dest Destination matrix.
*/
void entityPositionGetTransform(
const entityid_t entityId,
const componentid_t componentId,
mat4 dest
);
/**
* Gets the local transform matrix (does not include parent transforms).
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param dest Destination matrix.
*/
void entityPositionGetLocalTransform(
const entityid_t entityId,
const componentid_t componentId,
mat4 dest
);
/**
* Gets the cached local position (XYZ). Decomposes localTransform into PRS
* first if ENTITY_POSITION_FLAG_PRS_DIRTY is set; never triggers a matrix
* rebuild or world-transform update.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param dest Destination vector.
*/
void entityPositionGetLocalPosition(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
);
/**
* Gets the world-space position. For parentless entities this is the same as
* the local position.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param dest Destination vector.
*/
void entityPositionGetWorldPosition(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
);
/**
* Sets the world-space position. For parentless entities this is equivalent to
* entityPositionSetLocalPosition. For parented entities the position is
* converted to local space via the inverted parent world transform.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param position The desired world-space position.
*/
void entityPositionSetWorldPosition(
const entityid_t entityId,
const componentid_t componentId,
vec3 position
);
/**
* Sets the local position, marks localTransform and worldTransform (self +
* descendants) dirty.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param position The new local position.
*/
void entityPositionSetLocalPosition(
const entityid_t entityId,
const componentid_t componentId,
vec3 position
);
/**
* Gets the cached local euler rotation (XYZ, radians). Decomposes
* localTransform first if ENTITY_POSITION_FLAG_PRS_DIRTY is set.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param dest Destination vector.
*/
void entityPositionGetLocalRotation(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
);
/**
* Gets the world-space euler rotation (XYZ, radians) by decomposing the world
* transform. For parentless entities this is the same as local rotation.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param dest Destination vector.
*/
void entityPositionGetWorldRotation(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
);
/**
* Sets the local euler rotation (XYZ, radians) and marks transforms dirty.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param rotation The new local rotation.
*/
void entityPositionSetLocalRotation(
const entityid_t entityId,
const componentid_t componentId,
vec3 rotation
);
/**
* Sets the world-space euler rotation (XYZ, radians). For parentless entities
* this is equivalent to entityPositionSetLocalRotation. For parented entities
* the rotation is converted to local space by removing the parent world
* rotation.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param rotation The desired world-space euler rotation.
*/
void entityPositionSetWorldRotation(
const entityid_t entityId,
const componentid_t componentId,
vec3 rotation
);
/**
* Gets the cached local scale. Decomposes localTransform first if
* ENTITY_POSITION_FLAG_PRS_DIRTY is set.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param dest Destination vector.
*/
void entityPositionGetLocalScale(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
);
/**
* Gets the world-space scale by extracting column lengths from the world
* transform. For parentless entities this is the same as local scale.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param dest Destination vector.
*/
void entityPositionGetWorldScale(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
);
/**
* Sets the local scale and marks transforms dirty.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param scale The new local scale.
*/
void entityPositionSetLocalScale(
const entityid_t entityId,
const componentid_t componentId,
vec3 scale
);
/**
* Sets the world-space scale. For parentless entities this is equivalent to
* entityPositionSetLocalScale. For parented entities the scale is converted to
* local space by dividing by the parent world scale (assumes no shear).
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param scale The desired world-space scale.
*/
void entityPositionSetWorldScale(
const entityid_t entityId,
const componentid_t componentId,
vec3 scale
);
/**
* Sets the parent of this entity's position component.
* Pass ENTITY_ID_INVALID / COMPONENT_ID_INVALID to detach from any parent.
*
* @param entityId The child entity ID.
* @param componentId The child component ID.
* @param parentEntityId The parent entity ID.
* @param parentComponentId The parent component ID.
*/
void entityPositionSetParent(
const entityid_t entityId,
const componentid_t componentId,
const entityid_t parentEntityId,
const componentid_t parentComponentId
);
/**
* Returns a direct pointer to the entity position component data.
* After modifying localTransform directly, call entityPositionMarkDirty() to
* set ENTITY_POSITION_FLAG_WORLD_DIRTY on self and descendants. After
* modifying PRS directly, call entityPositionRebuild() instead.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @return Pointer to the component data.
*/
entityposition_t *entityPositionGet(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Signals that the PRS cache was modified externally. Sets both
* ENTITY_POSITION_FLAG_ROTATION_DIRTY and ENTITY_POSITION_FLAG_POSITION_DIRTY
* so all of localTransform is rebuilt lazily on the next read, clears
* ENTITY_POSITION_FLAG_PRS_DIRTY, propagates ENTITY_POSITION_FLAG_WORLD_DIRTY
* to self and all descendants.
*
* @param pos The position component whose PRS was modified.
*/
void entityPositionRebuild(entityposition_t *pos);
/**
* Sets ENTITY_POSITION_FLAG_WORLD_DIRTY on this node and all descendants,
* indicating that worldTransform must be recomputed before it is read.
* Call this after modifying localTransform directly.
*
* @param pos The position component to mark dirty.
*/
void entityPositionMarkDirty(entityposition_t *pos);
/**
* Disposes this entity and all of its position-component descendants
* recursively. Detaches from any parent before destroying.
*
* @param entityId The root entity ID.
* @param componentId The root position component ID.
*/
void entityPositionDisposeDeep(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Decomposes the local transform matrix back into the position, rotation
* (XYZ euler, radians), and scale cache fields.
*
* @param pos The position component to decompose.
*/
void entityPositionDecompose(entityposition_t *pos);
src/dusk/entity/component/display/entityrenderable.c
-142
View File
@@ -1,142 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "entityrenderable.h"
#include "entity/entitymanager.h"
#include "display/shader/shadermaterial.h"
#include "display/shader/shaderunlit.h"
#include "display/display.h"
#include "display/mesh/cube.h"
#include "util/memory.h"
#include "assert/assert.h"
void entityRenderableInit(
const entityid_t entityId,
const componentid_t componentId
) {
entityrenderable_t *r = componentGetData(
entityId, componentId, COMPONENT_TYPE_RENDERABLE
);
memoryZero(r, sizeof(entityrenderable_t));
r->type = ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL;
r->data.material.shaderType = SHADER_LIST_SHADER_UNLIT;
r->data.material.material.unlit.color = COLOR_WHITE;
r->data.material.meshes[0] = &CUBE_MESH_SIMPLE;
r->data.material.meshOffsets[0] = 0;
r->data.material.meshCounts[0] = -1;
r->data.material.meshCount = 1;
r->data.material.state.flags = DISPLAY_STATE_FLAG_DEPTH_TEST;
}
void entityRenderableDispose(
const entityid_t entityId,
const componentid_t componentId
) {
}
void entityRenderableSetType(
const entityid_t entityId,
const componentid_t componentId,
const entityrenderabletype_t type
) {
entityrenderable_t *r = componentGetData(
entityId, componentId, COMPONENT_TYPE_RENDERABLE
);
r->type = type;
}
void entityRenderableSetPriority(
const entityid_t entityId,
const componentid_t componentId,
const int8_t priority
) {
entityrenderable_t *r = componentGetData(
entityId, componentId, COMPONENT_TYPE_RENDERABLE
);
r->priority = priority;
}
void entityRenderableSetDraw(
const entityid_t entityId,
const componentid_t componentId,
errorret_t (*draw)(
const entityid_t entityId,
const componentid_t componentId,
void *user
),
void *user
) {
assertNotNull(draw, "Draw callback cannot be null");
entityrenderable_t *r = componentGetData(
entityId, componentId, COMPONENT_TYPE_RENDERABLE
);
r->type = ENTITY_RENDERABLE_TYPE_CUSTOM;
r->data.custom.draw = draw;
r->data.custom.drawUser = user;
}
static errorret_t entityRenderableDrawSpritebatch(
const entityrenderablespritebatch_t *sb
) {
if(sb->spriteCount == 0) errorOk();
errorChain(displaySetState((displaystate_t){
.flags = DISPLAY_STATE_FLAG_BLEND
}));
spriteBatchClear();
shadermaterial_t mat;
memoryZero(&mat, sizeof(shadermaterial_t));
mat.unlit.texture = sb->texture;
mat.unlit.color = COLOR_WHITE;
errorChain(spriteBatchBuffer(
sb->sprites, sb->spriteCount,
SHADER_LIST_DEFS[SHADER_LIST_SHADER_UNLIT].shader, mat
));
return spriteBatchFlush();
}
static errorret_t entityRenderableDrawMaterial(
const entityrenderablematerial_t *m
) {
errorChain(displaySetState(m->state));
shader_t *shader = SHADER_LIST_DEFS[m->shaderType].shader;
assertNotNull(shader, "Shader cannot be null for material type");
errorChain(shaderBind(shader));
errorChain(shaderSetMaterial(shader, &m->material));
for(uint8_t i = 0; i < m->meshCount; i++) {
errorChain(meshDraw(m->meshes[i], m->meshOffsets[i], m->meshCounts[i]));
}
errorOk();
}
static errorret_t entityRenderableDrawCustom(
const entityid_t entityId,
const componentid_t componentId,
const entityrenderablecustom_t *custom
) {
return custom->draw(entityId, componentId, custom->drawUser);
}
errorret_t entityRenderableDraw(
const entityid_t entityId,
const componentid_t componentId
) {
entityrenderable_t *r = componentGetData(
entityId, componentId, COMPONENT_TYPE_RENDERABLE
);
switch(r->type) {
case ENTITY_RENDERABLE_TYPE_SPRITEBATCH:
return entityRenderableDrawSpritebatch(&r->data.spritebatch);
case ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL:
return entityRenderableDrawMaterial(&r->data.material);
case ENTITY_RENDERABLE_TYPE_CUSTOM:
return entityRenderableDrawCustom(entityId, componentId, &r->data.custom);
default:
assertUnreachable("Invalid renderable type");
}
}
src/dusk/entity/component/display/entityrenderable.h
-147
View File
@@ -1,147 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "entity/entitybase.h"
#include "display/mesh/mesh.h"
#include "display/shader/shadermaterial.h"
#include "display/spritebatch/spritebatch.h"
#include "display/displaystate.h"
#define ENTITY_RENDERABLE_SPRITEBATCH_SPRITES_MAX 64
#define ENTITY_RENDERABLE_MESHES_MAX 8
typedef enum {
ENTITY_RENDERABLE_TYPE_CUSTOM = 0,
ENTITY_RENDERABLE_TYPE_SPRITEBATCH,
ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL,
} entityrenderabletype_t;
typedef struct {
spritebatchsprite_t sprites[ENTITY_RENDERABLE_SPRITEBATCH_SPRITES_MAX];
uint32_t spriteCount;
texture_t *texture;
} entityrenderablespritebatch_t;
typedef struct {
mesh_t *meshes[ENTITY_RENDERABLE_MESHES_MAX];
int32_t meshOffsets[ENTITY_RENDERABLE_MESHES_MAX];
int32_t meshCounts[ENTITY_RENDERABLE_MESHES_MAX];
uint8_t meshCount;
shaderlistshader_t shaderType;
shadermaterial_t material;
displaystate_t state;
} entityrenderablematerial_t;
typedef struct {
errorret_t (*draw)(
const entityid_t entityId,
const componentid_t componentId,
void *user
);
void *drawUser;
} entityrenderablecustom_t;
typedef union entityrenderabledata_u {
entityrenderablespritebatch_t spritebatch;
entityrenderablematerial_t material;
entityrenderablecustom_t custom;
} entityrenderabledata_t;
typedef struct {
entityrenderabletype_t type;
entityrenderabledata_t data;
/**
* Render priority. 0 = auto (derived from type/flags). Higher values render
* later (on top of lower values). Range: [-128..127] with 0 is auto.
*/
int8_t priority;
} entityrenderable_t;
/**
* Initializes the entity renderable component. Defaults to
* ENTITY_RENDERABLE_TYPE_SHADER_MATERIAL with the unlit shader, a white cube,
* and depth-test enabled.
*
* @param entityId The entity to initialize the component for.
* @param componentId The renderable component of the entity.
*/
void entityRenderableInit(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Disposes the entity renderable component.
*
* @param entityId The entity to dispose the component for.
* @param componentId The renderable component of the entity.
*/
void entityRenderableDispose(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Sets the rendering type for the renderable component. Resets type-specific
* data to zero.
*
* @param entityId The entity to configure.
* @param componentId The renderable component.
* @param type The rendering type to use.
*/
void entityRenderableSetType(
const entityid_t entityId,
const componentid_t componentId,
const entityrenderabletype_t type
);
/**
* Sets the render priority. 0 = auto (derived from type/flags). Higher values
* render later (on top). Use non-zero to force ordering.
*
* @param entityId The entity to configure.
* @param componentId The renderable component.
* @param priority The priority value, or 0 for auto.
*/
void entityRenderableSetPriority(
const entityid_t entityId,
const componentid_t componentId,
const int8_t priority
);
/**
* Sets the draw callback, switching the type to ENTITY_RENDERABLE_TYPE_CUSTOM.
*
* @param entityId The entity to configure.
* @param componentId The renderable component of the entity.
* @param draw The draw callback to assign.
* @param user Userdata passed to the callback.
*/
void entityRenderableSetDraw(
const entityid_t entityId,
const componentid_t componentId,
errorret_t (*draw)(
const entityid_t entityId,
const componentid_t componentId,
void *user
),
void *user
);
/**
* Draws the entity using its renderable component data.
*
* @param entityId The entity to draw.
* @param componentId The renderable component of the entity.
* @return Any error state that happened.
*/
errorret_t entityRenderableDraw(
const entityid_t entityId,
const componentid_t componentId
);
src/dusk/entity/component/physics/entityphysics.c
-126
View File
@@ -1,126 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "entityphysics.h"
#include "entity/entitymanager.h"
#include "entity/component/display/entityposition.h"
#include "physics/physicsmanager.h"
#include "assert/assert.h"
#include "util/memory.h"
void entityPhysicsInit(
const entityid_t entityId,
const componentid_t componentId
) {
entityphysics_t *phys = entityPhysicsGet(entityId, componentId);
assertNotNull(phys, "Failed to get physics component data");
memoryZero(phys, sizeof(entityphysics_t));
// Default to cube
phys->type = PHYSICS_BODY_DYNAMIC;
phys->shape.type = PHYSICS_SHAPE_CUBE;
phys->shape.data.cube.halfExtents[0] = 0.5f;
phys->shape.data.cube.halfExtents[1] = 0.5f;
phys->shape.data.cube.halfExtents[2] = 0.5f;
phys->gravityScale = 1.0f;
phys->onGround = false;
}
entityphysics_t *entityPhysicsGet(
const entityid_t entityId,
const componentid_t componentId
) {
return componentGetData(entityId, componentId, COMPONENT_TYPE_PHYSICS);
}
void entityPhysicsSetShape(
const entityid_t entityId,
const componentid_t componentId,
const physicsshape_t shape
) {
entityphysics_t *phys = entityPhysicsGet(entityId, componentId);
assertNotNull(phys, "Failed to get physics component data");
phys->shape = shape;
// TODO: Do I need to reset the state for ground/active?
}
physicsshape_t entityPhysicsGetShape(
const entityid_t entityId,
const componentid_t componentId
) {
entityphysics_t *phys = entityPhysicsGet(entityId, componentId);
assertNotNull(phys, "Failed to get physics component data");
return phys->shape;
}
void entityPhysicsGetVelocity(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
) {
entityphysics_t *phys = entityPhysicsGet(entityId, componentId);
assertNotNull(phys, "Failed to get physics component data");
glm_vec3_copy(phys->velocity, dest);
}
void entityPhysicsSetVelocity(
const entityid_t entityId,
const componentid_t componentId,
vec3 velocity
) {
entityphysics_t *phys = entityPhysicsGet(entityId, componentId);
assertNotNull(phys, "Failed to get physics component data");
glm_vec3_copy(velocity, phys->velocity);
}
void entityPhysicsApplyImpulse(
const entityid_t entityId,
const componentid_t componentId,
vec3 impulse
) {
entityphysics_t *phys = entityPhysicsGet(entityId, componentId);
assertNotNull(phys, "Failed to get physics component data");
if(phys->type == PHYSICS_BODY_STATIC) return;
glm_vec3_add(phys->velocity, impulse, phys->velocity);
}
bool_t entityPhysicsIsOnGround(
const entityid_t entityId,
const componentid_t componentId
) {
entityphysics_t *phys = entityPhysicsGet(entityId, componentId);
assertNotNull(phys, "Failed to get physics component data");
return phys->onGround;
}
void entityPhysicsSetBodyType(
const entityid_t entityId,
const componentid_t componentId,
const physicsbodytype_t type
) {
entityphysics_t *phys = entityPhysicsGet(entityId, componentId);
assertNotNull(phys, "Failed to get physics component data");
phys->type = type;
}
physicsbodytype_t entityPhysicsGetBodyType(
const entityid_t entityId,
const componentid_t componentId
) {
entityphysics_t *phys = entityPhysicsGet(entityId, componentId);
assertNotNull(phys, "Failed to get physics component data");
return phys->type;
}
void entityPhysicsDispose(
const entityid_t entityId,
const componentid_t componentId
) {
}
src/dusk/entity/component/physics/entityphysics.h
-157
View File
@@ -1,157 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "entity/entitybase.h"
#include "physics/physicsshape.h"
#include "physics/physicsbodytype.h"
typedef struct {
physicsbodytype_t type;
physicsshape_t shape;
vec3 velocity;
float_t gravityScale;
bool_t onGround;
} entityphysics_t;
/**
* Initializes the physics component: allocates a body in PHYSICS_WORLD.
* Asserts if the world body limit is reached.
*/
void entityPhysicsInit(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Gets the underlying physics structure (temporarily) for the given entity.
* This is really just intended for doing operations faster than using the
* getters and setters, but it is preferred that you use those.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @return The physics component data for the given entity and component ID.
*/
entityphysics_t *entityPhysicsGet(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Sets the shape of the entity's physics body. This will not reset the body
* state, so if you change from a cube to a sphere, it will keep the same
* velocity and onGround state.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param shape The new shape to set on the physics body.
*/
void entityPhysicsSetShape(
const entityid_t entityId,
const componentid_t componentId,
const physicsshape_t shape
);
/**
* Gets the shape of the entity's physics body.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @return The shape of the physics body.
*/
physicsshape_t entityPhysicsGetShape(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Gets the velocity of the entity's physics body.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param dest The destination vec3 to write the velocity to.
*/
void entityPhysicsGetVelocity(
const entityid_t entityId,
const componentid_t componentId,
vec3 dest
);
/**
* Sets the velocity of the entity's physics body. This is not an impulse, so
* it will be affected by mass and drag.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param velocity The new velocity to set on the physics body.
*/
void entityPhysicsSetVelocity(
const entityid_t entityId,
const componentid_t componentId,
vec3 velocity
);
/**
* Applies an impulse to the entity's physics body. This is an immediate
* velocity change that is not affected by mass or drag. No-op on STATIC bodies.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param impulse The impulse to apply to the physics body.
*/
void entityPhysicsApplyImpulse(
const entityid_t entityId,
const componentid_t componentId,
vec3 impulse
);
/**
* Returns true if the entity's physics body rested on a surface during the last
* step or move.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @return True if the body is on the ground, false otherwise.
*/
bool_t entityPhysicsIsOnGround(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Sets the body type of the entity's physics body.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @param type The body type to set.
*/
void entityPhysicsSetBodyType(
const entityid_t entityId,
const componentid_t componentId,
const physicsbodytype_t type
);
/**
* Gets the body type of the entity's physics body.
*
* @param entityId The entity ID.
* @param componentId The component ID.
* @return The body type of the physics body.
*/
physicsbodytype_t entityPhysicsGetBodyType(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Releases the body slot back to PHYSICS_WORLD. Called automatically when
* the component is disposed via the component system.
*/
void entityPhysicsDispose(
const entityid_t entityId,
const componentid_t componentId
);
src/dusk/entity/component/trigger/CMakeLists.txt
-9
View File
@@ -1,9 +0,0 @@
# Copyright (c) 2026 Dominic Masters
#
# This software is released under the MIT License.
# https://opensource.org/licenses/MIT
target_sources(${DUSK_LIBRARY_TARGET_NAME}
PUBLIC
entitytrigger.c
)
src/dusk/entity/component/trigger/entitytrigger.c
-54
View File
@@ -1,54 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "entity/entitymanager.h"
void entityTriggerInit(
const entityid_t entityId,
const componentid_t componentId
) {
entitytrigger_t *t = componentGetData(
entityId, componentId, COMPONENT_TYPE_TRIGGER
);
glm_vec3_zero(t->min);
glm_vec3_zero(t->max);
}
entitytrigger_t * entityTriggerGet(
const entityid_t entityId,
const componentid_t componentId
) {
return componentGetData(entityId, componentId, COMPONENT_TYPE_TRIGGER);
}
bool_t entityTriggerContains(
const entityid_t entityId,
const componentid_t componentId,
const vec3 point
) {
entitytrigger_t *t = componentGetData(
entityId, componentId, COMPONENT_TYPE_TRIGGER
);
return (
point[0] >= t->min[0] && point[0] <= t->max[0] &&
point[1] >= t->min[1] && point[1] <= t->max[1] &&
point[2] >= t->min[2] && point[2] <= t->max[2]
);
}
void entityTriggerSetBounds(
const entityid_t entityId,
const componentid_t componentId,
const vec3 min,
const vec3 max
) {
entitytrigger_t *t = componentGetData(
entityId, componentId, COMPONENT_TYPE_TRIGGER
);
glm_vec3_copy((float_t*)min, t->min);
glm_vec3_copy((float_t*)max, t->max);
}
src/dusk/entity/component/trigger/entitytrigger.h
-49
View File
@@ -1,49 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "entity/entitybase.h"
typedef struct {
vec3 min;
vec3 max;
} entitytrigger_t;
/**
* Initializes the trigger component with zeroed bounds.
*/
void entityTriggerInit(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Returns a pointer to the trigger component data.
*/
entitytrigger_t * entityTriggerGet(
const entityid_t entityId,
const componentid_t componentId
);
/**
* Returns true if the given world-space point lies within [min, max].
*/
bool_t entityTriggerContains(
const entityid_t entityId,
const componentid_t componentId,
const vec3 point
);
/**
* Sets both bounds at once.
*/
void entityTriggerSetBounds(
const entityid_t entityId,
const componentid_t componentId,
const vec3 min,
const vec3 max
);
src/dusk/entity/componentlist.h
-27
View File
@@ -1,27 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "entity/component/display/entityposition.h"
#include "entity/component/display/entitycamera.h"
#include "entity/component/display/entityrenderable.h"
#include "entity/component/physics/entityphysics.h"
#include "entity/component/trigger/entitytrigger.h"
// Name (Uppercase)
// Structure
// Field name (lowercase)
// Init function (optional)
// Dispose function (optional)
// Render function (optional)
X(POSITION, entityposition_t, position, entityPositionInit, NULL, NULL)
X(CAMERA, entitycamera_t, camera, entityCameraInit, NULL, NULL)
X(RENDERABLE, entityrenderable_t, renderable,
entityRenderableInit, entityRenderableDispose, NULL)
X(PHYSICS, entityphysics_t, physics,
entityPhysicsInit, entityPhysicsDispose, NULL)
X(TRIGGER, entitytrigger_t, trigger, entityTriggerInit, NULL, NULL)
src/dusk/entity/entity.c
-179
View File
@@ -1,179 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "entitymanager.h"
#include "component/display/entityposition.h"
#include "util/memory.h"
#include "assert/assert.h"
void entityInit(const entityid_t entityId) {
entity_t *ent = &ENTITY_MANAGER.entities[entityId];
memoryZero(ent, sizeof(entity_t));
// Mark all component types not using this entity.
for(
componenttype_t compType = 0;
compType < COMPONENT_TYPE_COUNT;
compType++
) {
ENTITY_MANAGER.entitiesWithComponent[
compType * ENTITY_COUNT_MAX + entityId
] = COMPONENT_ID_INVALID;
}
ent->state |= ENTITY_STATE_ACTIVE;
}
componentid_t entityAddComponent(
const entityid_t entityId,
const componenttype_t type
) {
componentindex_t compInd;
entity_t *ent = &ENTITY_MANAGER.entities[entityId];
for(componentid_t i = 0; i < ENTITY_COMPONENT_COUNT_MAX; i++) {
compInd = componentGetIndex(entityId, i);
if(ENTITY_MANAGER.components[compInd].type != COMPONENT_TYPE_NULL) {
assertTrue(
ENTITY_MANAGER.components[compInd].type != type,
"Entity already has component of this type"
);
continue;
}
componentInit(entityId, i, type);
ENTITY_MANAGER.entitiesWithComponent[
type * ENTITY_COUNT_MAX + entityId
] = i;
return i;
}
assertUnreachable("Entity has no more component slots available");
return COMPONENT_ID_INVALID;
}
componentid_t entityGetComponent(
const entityid_t entityId,
const componenttype_t type
) {
componentid_t compId = ENTITY_MANAGER.entitiesWithComponent[
type * ENTITY_COUNT_MAX + entityId
];
if(compId == COMPONENT_ID_INVALID) return compId;
assertTrue(
ENTITY_MANAGER.components[componentGetIndex(entityId, compId)].type == type,
"Component type mismatch"
);
return compId;
}
void entityDisposeDeep(const entityid_t entityId) {
componentid_t posComp = entityGetComponent(entityId, COMPONENT_TYPE_POSITION);
if(posComp != COMPONENT_ID_INVALID) {
entityPositionDisposeDeep(entityId, posComp);
} else {
entityDispose(entityId);
}
}
void entityUpdate(const entityid_t entityId) {
entity_t *ent = &ENTITY_MANAGER.entities[entityId];
for(uint8_t i = 0; i < ent->updateCount; i++) {
ent->onUpdate[i](entityId, ent->updateComponentId[i], ent->updateUser[i]);
}
}
void entityDispose(const entityid_t entityId) {
componentindex_t compInd;
entity_t *ent = &ENTITY_MANAGER.entities[entityId];
for(uint8_t i = 0; i < ent->disposeCount; i++) {
ent->onDispose[i](
entityId, ent->disposeComponentId[i], ent->disposeUser[i]
);
}
for(componentid_t i = 0; i < ENTITY_COMPONENT_COUNT_MAX; i++) {
compInd = componentGetIndex(entityId, i);
componenttype_t type = ENTITY_MANAGER.components[compInd].type;
if(type == COMPONENT_TYPE_NULL) continue;
ENTITY_MANAGER.entitiesWithComponent[
type * ENTITY_COUNT_MAX + entityId
] = COMPONENT_ID_INVALID;
componentDispose(entityId, i);
}
ent->state = 0;
}
void entityUpdateAdd(
const entityid_t entityId,
const entitycallback_t callback,
const componentid_t componentId,
void *user
) {
entity_t *ent = &ENTITY_MANAGER.entities[entityId];
assertTrue(
ent->updateCount < ENTITY_UPDATE_CALLBACK_COUNT_MAX,
"Entity update callback slots full"
);
ent->onUpdate[ent->updateCount] = callback;
ent->updateComponentId[ent->updateCount] = componentId;
ent->updateUser[ent->updateCount] = user;
ent->updateCount++;
}
void entityUpdateRemove(
const entityid_t entityId,
const entitycallback_t callback
) {
entity_t *ent = &ENTITY_MANAGER.entities[entityId];
for(uint8_t i = 0; i < ent->updateCount; i++) {
if(ent->onUpdate[i] != callback) continue;
ent->updateCount--;
for(uint8_t j = i; j < ent->updateCount; j++) {
ent->onUpdate[j] = ent->onUpdate[j + 1];
ent->updateComponentId[j] = ent->updateComponentId[j + 1];
ent->updateUser[j] = ent->updateUser[j + 1];
}
return;
}
}
void entityDisposeAdd(
const entityid_t entityId,
const entitycallback_t callback,
const componentid_t componentId,
void *user
) {
entity_t *ent = &ENTITY_MANAGER.entities[entityId];
assertTrue(
ent->disposeCount < ENTITY_DISPOSE_CALLBACK_COUNT_MAX,
"Entity dispose callback slots full"
);
ent->onDispose[ent->disposeCount] = callback;
ent->disposeComponentId[ent->disposeCount] = componentId;
ent->disposeUser[ent->disposeCount] = user;
ent->disposeCount++;
}
void entityDisposeRemove(
const entityid_t entityId,
const entitycallback_t callback
) {
entity_t *ent = &ENTITY_MANAGER.entities[entityId];
for(uint8_t i = 0; i < ent->disposeCount; i++) {
if(ent->onDispose[i] != callback) continue;
ent->disposeCount--;
for(uint8_t j = i; j < ent->disposeCount; j++) {
ent->onDispose[j] = ent->onDispose[j + 1];
ent->disposeComponentId[j] = ent->disposeComponentId[j + 1];
ent->disposeUser[j] = ent->disposeUser[j + 1];
}
return;
}
}
src/dusk/entity/entity.h
-137
View File
@@ -1,137 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "component.h"
#define ENTITY_STATE_ACTIVE (1 << 0)
#define ENTITY_UPDATE_CALLBACK_COUNT_MAX 5
#define ENTITY_DISPOSE_CALLBACK_COUNT_MAX 5
typedef void (*entitycallback_t)(
const entityid_t entityId,
const componentid_t componentId,
void *user
);
typedef struct {
uint8_t state;
uint8_t updateCount;
uint8_t disposeCount;
entitycallback_t onUpdate[ENTITY_UPDATE_CALLBACK_COUNT_MAX];
componentid_t updateComponentId[ENTITY_UPDATE_CALLBACK_COUNT_MAX];
void *updateUser[ENTITY_UPDATE_CALLBACK_COUNT_MAX];
entitycallback_t onDispose[ENTITY_DISPOSE_CALLBACK_COUNT_MAX];
componentid_t disposeComponentId[ENTITY_DISPOSE_CALLBACK_COUNT_MAX];
void *disposeUser[ENTITY_DISPOSE_CALLBACK_COUNT_MAX];
} entity_t;
/**
* Initializes an entity with the given ID.
*
* @param entityId The ID of the entity to initialize.
*/
void entityInit(const entityid_t entityId);
/**
* Adds a component of the given type to the entity with the given ID.
*
* @param entityId The ID of the entity to add the component to.
* @param type The type of the component to add.
* @return The ID of the entity with component.
*/
componentid_t entityAddComponent(
const entityid_t entityId,
const componenttype_t type
);
/**
* Gets the ID of the component of the given type on the entity with the given
* ID, or COMPONENT_ID_INVALID if the entity lacks the component.
*
* @param entityId The ID of the entity to get the component from.
* @param type The type of the component to get.
* @return The ID of the component.
*/
componentid_t entityGetComponent(
const entityid_t entityId,
const componenttype_t type
);
/**
* Runs all registered update callbacks for the entity.
*
* @param entityId The ID of the entity to update.
*/
void entityUpdate(const entityid_t entityId);
/**
* Disposes of an entity with the given ID. Fires all dispose callbacks before
* cleaning up components and state.
*
* @param entityId The ID of the entity to dispose of.
*/
void entityDispose(const entityid_t entityId);
/**
* Disposes of an entity and all of its position-component descendants
* recursively. If the entity has no position component, behaves like
* entityDispose.
*
* @param entityId The root entity ID.
*/
void entityDisposeDeep(const entityid_t entityId);
/**
* Registers an update callback, invoked each time entityUpdate is called.
*
* @param entityId The entity to register on.
* @param callback The function to call.
*/
void entityUpdateAdd(
const entityid_t entityId,
const entitycallback_t callback,
const componentid_t componentId,
void *user
);
/**
* Removes a previously registered update callback.
*
* @param entityId The entity to remove from.
* @param callback The function to remove.
*/
void entityUpdateRemove(
const entityid_t entityId,
const entitycallback_t callback
);
/**
* Registers a dispose callback, invoked at the start of entityDispose before
* any component or state cleanup.
*
* @param entityId The entity to register on.
* @param callback The function to call.
*/
void entityDisposeAdd(
const entityid_t entityId,
const entitycallback_t callback,
const componentid_t componentId,
void *user
);
/**
* Removes a previously registered dispose callback.
*
* @param entityId The entity to remove from.
* @param callback The function to remove.
*/
void entityDisposeRemove(
const entityid_t entityId,
const entitycallback_t callback
);
src/dusk/entity/entitybase.h
-19
View File
@@ -1,19 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "dusk.h"
#define ENTITY_COUNT_MAX 64
#define ENTITY_COMPONENT_COUNT_MAX 16
#define ENTITY_ID_INVALID 0xFF
#define COMPONENT_ID_INVALID 0xFF
typedef uint8_t entityid_t;
typedef uint8_t componentid_t;
typedef uint16_t componentindex_t;
src/dusk/entity/entitymanager.c
-54
View File
@@ -1,54 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "entitymanager.h"
#include "assert/assert.h"
#include "util/memory.h"
#include "console/console.h"
entitymanager_t ENTITY_MANAGER;
void entityManagerInit(void) {
memoryZero(&ENTITY_MANAGER, sizeof(entitymanager_t));
memorySet(
ENTITY_MANAGER.entitiesWithComponent, COMPONENT_ID_INVALID,
sizeof(componentid_t) * COMPONENT_TYPE_COUNT * ENTITY_COUNT_MAX
);
consolePrint(
"Entity Manager size: %zu bytes (%.2f KB)",
sizeof(entitymanager_t),
sizeof(entitymanager_t) / 1024.0f
);
}
entityid_t entityManagerAdd() {
for(entityid_t i = 0; i < ENTITY_COUNT_MAX; i++) {
if((ENTITY_MANAGER.entities[i].state & ENTITY_STATE_ACTIVE) != 0) continue;
entityInit(i);
return i;
}
assertUnreachable("No more entity IDs available");
return ENTITY_ID_INVALID;
}
void entityManagerUpdate(void) {
entityid_t i = 0;
while(i < ENTITY_COUNT_MAX) {
if((ENTITY_MANAGER.entities[i].state & ENTITY_STATE_ACTIVE) != 0) {
entityUpdate(i);
}
i++;
}
}
void entityManagerDispose(void) {
for(entityid_t i = 0; i < ENTITY_COUNT_MAX; i++) {
if((ENTITY_MANAGER.entities[i].state & ENTITY_STATE_ACTIVE) == 0) continue;
entityDispose(i);
}
}
src/dusk/entity/entitymanager.h
-39
View File
@@ -1,39 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "entity.h"
typedef struct {
entity_t entities[ENTITY_COUNT_MAX];
component_t components[ENTITY_COUNT_MAX * ENTITY_COMPONENT_COUNT_MAX];
componentid_t entitiesWithComponent[COMPONENT_TYPE_COUNT * ENTITY_COUNT_MAX];
} entitymanager_t;
extern entitymanager_t ENTITY_MANAGER;
/**
* Initializes the entity manager.
*/
void entityManagerInit(void);
/**
* Adds / Reserves a new entity ID.
*
* @return The new entity ID.
*/
entityid_t entityManagerAdd();
/**
* Updates all active entities.
*/
void entityManagerUpdate(void);
/**
* Disposes of the entity manager, in turn freeing all entities and components.
*/
void entityManagerDispose(void);
src/dusk/overworld/facingdir.c
-17
View File
@@ -1,17 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "facingdir.h"
void facingDirToVec2(facingdir_t facing, vec2 dest) {
switch(facing) {
case FACING_DIR_UP: dest[0] = 0.0f; dest[1] = -1.0f; return;
case FACING_DIR_LEFT: dest[0] = -1.0f; dest[1] = 0.0f; return;
case FACING_DIR_RIGHT: dest[0] = 1.0f; dest[1] = 0.0f; return;
default: dest[0] = 0.0f; dest[1] = 1.0f; return;
}
}
src/dusk/overworld/facingdir.h
-28
View File
@@ -1,28 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "dusk.h"
typedef enum {
FACING_DIR_DOWN = 0,
FACING_DIR_UP = 1,
FACING_DIR_LEFT = 2,
FACING_DIR_RIGHT = 3,
FACING_DIR_SOUTH = FACING_DIR_DOWN,
FACING_DIR_NORTH = FACING_DIR_UP,
FACING_DIR_WEST = FACING_DIR_LEFT,
FACING_DIR_EAST = FACING_DIR_RIGHT,
} facingdir_t;
/**
* Converts a facing direction to a normalized XZ vec2.
*
* @param facing The facing direction.
* @param dest Output vec2 - [0] is X, [1] is Z.
*/
void facingDirToVec2(facingdir_t facing, vec2 dest);
src/dusk/overworld/map.c
-151
View File
@@ -1,151 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "map.h"
#include "assert/assert.h"
#include "asset/assetfile.h"
#include "util/memory.h"
#include "util/string.h"
#include "console/console.h"
map_t MAP;
chunkindex_t mapChunkRelToIndex(
chunkunit_t rx,
chunkunit_t ry,
chunkunit_t rz
) {
return (chunkindex_t)(
rz * (MAP_CHUNKS_WIDE * MAP_CHUNKS_HIGH) +
ry * MAP_CHUNKS_WIDE +
rx
);
}
void mapInit(void) {
memoryZero(&MAP, sizeof(map_t));
}
errorret_t mapLoad(const char_t *handle) {
assertStrLenMin(handle, 1, "Map handle cannot be empty");
assertStrLenMax(handle, MAP_HANDLE_MAX - 1, "Map handle too long");
if(mapIsLoaded()) mapDispose();
memoryZero(&MAP, sizeof(map_t));
stringCopy(MAP.handle, handle, MAP_HANDLE_MAX);
char_t path[ASSET_FILE_NAME_MAX];
stringFormat(path, sizeof(path), "maps/%s/init.js", handle);
consolePrint("Map loaded: %s", handle);
errorOk();
}
bool_t mapIsLoaded(void) {
return MAP.loaded;
}
errorret_t mapPositionSet(tilepos_t tilePos) {
assertTrue(MAP.chunkTileWidth > 0, "chunkTileWidth not set");
assertTrue(MAP.chunkTileHeight > 0, "chunkTileHeight not set");
assertTrue(MAP.chunkTileDepth > 0, "chunkTileDepth not set");
// Convert tile position to chunk-space window origin.
chunkpos_t newPos = {
.x = (chunkunit_t)(tilePos.x / MAP.chunkTileWidth),
.y = (chunkunit_t)(tilePos.y / MAP.chunkTileHeight),
.z = (chunkunit_t)(tilePos.z / MAP.chunkTileDepth),
};
if(MAP.loaded && chunkPosEqual(MAP.chunkPosition, newPos)) errorOk();
// Categorise existing chunks as remaining or freed.
chunkindex_t remaining[MAP_CHUNKS_COUNT];
chunkindex_t freed[MAP_CHUNKS_COUNT];
chunkindex_t remainingCount = 0;
chunkindex_t freedCount = 0;
for(chunkindex_t i = 0; i < MAP_CHUNKS_COUNT; i++) {
mapchunk_t *chunk = &MAP.chunks[i];
chunkpos_t p = chunk->position;
bool_t stays = MAP.loaded &&
p.x >= newPos.x && p.x < newPos.x + MAP_CHUNKS_WIDE &&
p.y >= newPos.y && p.y < newPos.y + MAP_CHUNKS_HIGH &&
p.z >= newPos.z && p.z < newPos.z + MAP_CHUNKS_DEEP;
if(stays) {
remaining[remainingCount++] = i;
} else {
if(MAP.loaded) mapChunkUnload(chunk);
freed[freedCount++] = i;
}
}
// Build chunkOrder for the new window, loading into freed slots as needed.
chunkindex_t orderIndex = 0;
for(chunkunit_t zOff = 0; zOff < MAP_CHUNKS_DEEP; zOff++) {
for(chunkunit_t yOff = 0; yOff < MAP_CHUNKS_HIGH; yOff++) {
for(chunkunit_t xOff = 0; xOff < MAP_CHUNKS_WIDE; xOff++) {
chunkpos_t target = {
.x = (chunkunit_t)(newPos.x + xOff),
.y = (chunkunit_t)(newPos.y + yOff),
.z = (chunkunit_t)(newPos.z + zOff),
};
// Check if the target chunk is already loaded.
chunkindex_t poolIdx = -1;
for(chunkindex_t r = 0; r < remainingCount; r++) {
if(chunkPosEqual(MAP.chunks[remaining[r]].position, target)) {
poolIdx = remaining[r];
break;
}
}
// Otherwise recycle a freed slot.
if(poolIdx == -1) {
poolIdx = freed[--freedCount];
MAP.chunks[poolIdx].position = target;
errorChain(mapChunkLoad(&MAP.chunks[poolIdx]));
}
MAP.chunkOrder[orderIndex++] = &MAP.chunks[poolIdx];
}}}
MAP.chunkPosition = newPos;
MAP.loaded = true;
errorOk();
}
mapchunk_t *mapGetChunkAt(chunkpos_t pos) {
if(!MAP.loaded) return NULL;
chunkpos_t p = MAP.chunkPosition;
if(
pos.x < p.x || pos.x >= p.x + MAP_CHUNKS_WIDE ||
pos.y < p.y || pos.y >= p.y + MAP_CHUNKS_HIGH ||
pos.z < p.z || pos.z >= p.z + MAP_CHUNKS_DEEP
) return NULL;
chunkindex_t idx = mapChunkRelToIndex(
pos.x - p.x, pos.y - p.y, pos.z - p.z
);
return MAP.chunkOrder[idx];
}
errorret_t mapUpdate(void) {
if(!MAP.loaded) errorOk();
errorOk();
}
void mapDispose(void) {
consolePrint("Map disposing: %s", MAP.handle);
if(!MAP.loaded) return;
for(chunkindex_t i = 0; i < MAP_CHUNKS_COUNT; i++) {
mapChunkUnload(&MAP.chunks[i]);
}
MAP.loaded = false;
}
src/dusk/overworld/map.h
-97
View File
@@ -1,97 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "mapchunk.h"
#include "error/error.h"
#define MAP_NAME_MAX 64
#define MAP_HANDLE_MAX 32
#define MAP_CHUNKS_WIDE 3
#define MAP_CHUNKS_HIGH 3
#define MAP_CHUNKS_DEEP 2
#define MAP_CHUNKS_COUNT (MAP_CHUNKS_WIDE * MAP_CHUNKS_HIGH * MAP_CHUNKS_DEEP)
typedef struct {
char_t name[MAP_NAME_MAX];
char_t handle[MAP_HANDLE_MAX];
uint16_t chunkTileWidth;
uint16_t chunkTileHeight;
uint16_t chunkTileDepth;
mapchunk_t chunks[MAP_CHUNKS_COUNT];
mapchunk_t *chunkOrder[MAP_CHUNKS_COUNT];
chunkpos_t chunkPosition;
bool_t loaded;
} map_t;
extern map_t MAP;
/**
* Initializes the map, zeroing all state.
*/
void mapInit(void);
/**
* Prepares the map for use with the given handle. If a map is already loaded
* it is disposed first. Chunk positions are not set until mapPositionSet is
* called.
*
* @param handle Short identifier for this map (max MAP_HANDLE_MAX - 1 chars).
* @return An error code.
*/
errorret_t mapLoad(const char_t *handle);
/**
* Returns true if a map is currently loaded.
*
* @return true if a map is loaded, false otherwise.
*/
bool_t mapIsLoaded(void);
/**
* Converts a chunk position relative to the window origin to its pool index.
*
* @param rx Relative chunk X offset within the window.
* @param ry Relative chunk Y offset within the window.
* @param rz Relative chunk Z offset within the window.
* @return The flat pool index for that relative position.
*/
chunkindex_t mapChunkRelToIndex(
chunkunit_t rx,
chunkunit_t ry,
chunkunit_t rz
);
/**
* Slides the loaded chunk window so its origin is the chunk that contains
* the given tile-space position. Only the delta is loaded/unloaded.
*
* @param tilePos Tile-space position of the new window origin.
* @return An error code.
*/
errorret_t mapPositionSet(tilepos_t tilePos);
/**
* Updates the map each frame.
*
* @return An error code.
*/
errorret_t mapUpdate(void);
/**
* Disposes the map, unloading all chunks.
*/
void mapDispose(void);
/**
* Returns the chunk at the given absolute chunk-space position, or NULL if
* it is outside the currently loaded window.
*
* @param pos Absolute chunk-space position to look up.
* @return Pointer to the chunk, or NULL if not loaded.
*/
mapchunk_t *mapGetChunkAt(chunkpos_t pos);
src/dusk/overworld/mapchunk.c
-56
View File
@@ -1,56 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "mapchunk.h"
#include "map.h"
#include "entity/entitymanager.h"
#include "util/memory.h"
#include "util/string.h"
#include "asset/asset.h"
#include "console/console.h"
errorret_t mapChunkLoad(mapchunk_t *chunk) {
chunk->entityCount = 0;
memoryZero(chunk->entities, sizeof(chunk->entities));
if(MAP.handle[0] == '\0') errorOk();
char_t path[ASSET_FILE_NAME_MAX];
stringFormat(
path, sizeof(path),
"maps/%s/chunks/%d_%d_%d.js",
MAP.handle,
(int)chunk->position.x,
(int)chunk->position.y,
(int)chunk->position.z
);
if(!assetFileExists(path)) errorOk();
consolePrint(
"Chunk loaded: %s [%d,%d,%d]",
path,
(int)chunk->position.x,
(int)chunk->position.y,
(int)chunk->position.z
);
errorOk();
}
void mapChunkUnload(mapchunk_t *chunk) {
consolePrint(
"Chunk unloading: [%d,%d,%d]",
(int)chunk->position.x,
(int)chunk->position.y,
(int)chunk->position.z
);
for(uint8_t i = 0; i < chunk->entityCount; i++) {
entityDispose(chunk->entities[i]);
}
chunk->entityCount = 0;
}
src/dusk/overworld/mapchunk.h
-34
View File
@@ -1,34 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "maptypes.h"
#include "entity/entitybase.h"
#include "error/error.h"
#define MAP_CHUNK_ENTITY_COUNT_MAX 64
typedef struct {
chunkpos_t position;
entityid_t entities[MAP_CHUNK_ENTITY_COUNT_MAX];
uint8_t entityCount;
} mapchunk_t;
/**
* Loads content into a chunk at its current position.
*
* @param chunk The chunk to load.
* @return An error code.
*/
errorret_t mapChunkLoad(mapchunk_t *chunk);
/**
* Disposes all entities owned by the chunk and resets its state.
*
* @param chunk The chunk to unload.
*/
void mapChunkUnload(mapchunk_t *chunk);
src/dusk/overworld/maptypes.c
-12
View File
@@ -1,12 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "maptypes.h"
bool_t chunkPosEqual(chunkpos_t a, chunkpos_t b) {
return a.x == b.x && a.y == b.y && a.z == b.z;
}
src/dusk/overworld/maptypes.h
-30
View File
@@ -1,30 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "dusk.h"
typedef int16_t chunkunit_t;
typedef int16_t chunkindex_t;
typedef int32_t tileunit_t;
typedef struct {
chunkunit_t x, y, z;
} chunkpos_t;
typedef struct {
tileunit_t x, y, z;
} tilepos_t;
/**
* Checks if two chunk positions are equal.
*
* @param a The first chunk position.
* @param b The second chunk position.
* @return true if the positions are equal, false otherwise.
*/
bool_t chunkPosEqual(chunkpos_t a, chunkpos_t b);
src/dusk/physics/CMakeLists.txt
-12
View File
@@ -1,12 +0,0 @@
# Copyright (c) 2026 Dominic Masters
#
# This software is released under the MIT License.
# https://opensource.org/licenses/MIT
# Sources
target_sources(${DUSK_LIBRARY_TARGET_NAME}
PUBLIC
physicsmanager.c
physicsworld.c
physicstest.c
)
src/dusk/physics/physicsbodytype.h
-27
View File
@@ -1,27 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "dusk.h"
typedef enum {
/**
* Never moves. Acts as an immovable collision surface.
*/
PHYSICS_BODY_STATIC,
/**
* Simulated by the world step: gravity, forces, and collision response.
*/
PHYSICS_BODY_DYNAMIC,
/**
* Moved programmatically via physicsWorldMoveBody; collides but is not
* driven by the simulation. Typical use: player character controller.
*/
PHYSICS_BODY_KINEMATIC
} physicsbodytype_t;
src/dusk/physics/physicsmanager.c
-21
View File
@@ -1,21 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "physicsmanager.h"
#include "time/time.h"
void physicsManagerInit(void) {
physicsWorldInit();
}
void physicsManagerUpdate() {
#if DUSK_TIME_DYNAMIC
if(TIME.dynamicUpdate) return; // Don't update on dynamic updates.
#endif
physicsWorldStep(TIME.delta);
}
src/dusk/physics/physicsmanager.h
-19
View File
@@ -1,19 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "physicsworld.h"
/**
* Initializes the physics manager.
*/
void physicsManagerInit(void);
/**
* Advances the physics simulation.
*/
void physicsManagerUpdate();
src/dusk/physics/physicsshape.h
-46
View File
@@ -1,46 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "dusk.h"
typedef enum {
PHYSICS_SHAPE_CUBE,
PHYSICS_SHAPE_SPHERE,
PHYSICS_SHAPE_CAPSULE,
PHYSICS_SHAPE_PLANE
} physicshapetype_t;
typedef struct {
vec3 halfExtents;
} physicsshapecube_t;
typedef struct {
float_t radius;
} physicsshapesphere_t;
typedef struct {
float_t radius;
float_t halfHeight;
} physicsshapecapsule_t;
typedef struct {
vec3 normal;
float_t distance;
} physicsshapeplane_t;
typedef union {
physicsshapecube_t cube;
physicsshapesphere_t sphere;
physicsshapecapsule_t capsule;
physicsshapeplane_t plane;
} physicsshapedata_t;
typedef struct {
physicshapetype_t type;
physicsshapedata_t data;
} physicsshape_t;
src/dusk/physics/physicstest.c
-402
View File
@@ -1,402 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "physicstest.h"
bool_t physicsTestAabbVsAabb(
const vec3 ac, const vec3 ah,
const vec3 bc, const vec3 bh,
vec3 outNormal, float_t *outDepth
) {
float_t dx = ac[0] - bc[0];
float_t dy = ac[1] - bc[1];
float_t dz = ac[2] - bc[2];
float_t px = (ah[0] + bh[0]) - fabsf(dx);
float_t py = (ah[1] + bh[1]) - fabsf(dy);
float_t pz = (ah[2] + bh[2]) - fabsf(dz);
if(px <= 0.0f || py <= 0.0f || pz <= 0.0f) return false;
outNormal[0] = outNormal[1] = outNormal[2] = 0.0f;
if(px < py && px < pz) {
*outDepth = px;
outNormal[0] = dx >= 0.0f ? 1.0f : -1.0f;
} else if(py < pz) {
*outDepth = py;
outNormal[1] = dy >= 0.0f ? 1.0f : -1.0f;
} else {
*outDepth = pz;
outNormal[2] = dz >= 0.0f ? 1.0f : -1.0f;
}
return true;
}
bool_t physicsTestSphereVsSphere(
const vec3 ac, const float_t ar,
const vec3 bc, const float_t br,
vec3 outNormal, float_t *outDepth
) {
vec3 diff;
glm_vec3_sub((float_t *)ac, (float_t *)bc, diff);
float_t dist2 = glm_vec3_norm2(diff);
float_t sumR = ar + br;
if(dist2 >= sumR * sumR) return false;
float_t dist = sqrtf(dist2);
*outDepth = sumR - dist;
if(dist > 1e-6f) {
glm_vec3_scale(diff, 1.0f / dist, outNormal);
} else {
outNormal[0] = 0.0f;
outNormal[1] = 1.0f;
outNormal[2] = 0.0f;
}
return true;
}
bool_t physicsTestSphereVsAabb(
const vec3 sc, const float_t sr,
const vec3 ac, const vec3 ah,
vec3 outNormal, float_t *outDepth
) {
vec3 closest = {
glm_clamp(sc[0], ac[0] - ah[0], ac[0] + ah[0]),
glm_clamp(sc[1], ac[1] - ah[1], ac[1] + ah[1]),
glm_clamp(sc[2], ac[2] - ah[2], ac[2] + ah[2])
};
vec3 diff;
glm_vec3_sub((float_t *)sc, closest, diff);
float_t dist2 = glm_vec3_norm2(diff);
bool_t inside = (dist2 < 1e-10f);
if(!inside && dist2 >= sr * sr) return false;
if(!inside) {
float_t dist = sqrtf(dist2);
*outDepth = sr - dist;
glm_vec3_scale(diff, 1.0f / dist, outNormal);
} else {
float_t faces[6] = {
(ac[0] + ah[0]) - sc[0],
sc[0] - (ac[0] - ah[0]),
(ac[1] + ah[1]) - sc[1],
sc[1] - (ac[1] - ah[1]),
(ac[2] + ah[2]) - sc[2],
sc[2] - (ac[2] - ah[2])
};
const float_t normals[6][3] = {
{1,0,0},{-1,0,0},{0,1,0},{0,-1,0},{0,0,1},{0,0,-1}
};
int_t mi = 0;
for(int_t k = 1; k < 6; k++) {
if(faces[k] < faces[mi]) mi = k;
}
*outDepth = sr + faces[mi];
outNormal[0] = normals[mi][0];
outNormal[1] = normals[mi][1];
outNormal[2] = normals[mi][2];
}
return true;
}
bool_t physicsTestSphereVsPlane(
const vec3 sc, const float_t sr,
const vec3 pn, const float_t pd,
vec3 outNormal, float_t *outDepth
) {
float_t signedDist = glm_vec3_dot((float_t *)pn, (float_t *)sc) - pd;
*outDepth = sr - signedDist;
if(*outDepth <= 0.0f) return false;
glm_vec3_copy((float_t *)pn, outNormal);
return true;
}
bool_t physicsTestAabbVsPlane(
const vec3 ac, const vec3 ah,
const vec3 pn, const float_t pd,
vec3 outNormal, float_t *outDepth
) {
float_t proj = fabsf(pn[0] * ah[0])
+ fabsf(pn[1] * ah[1])
+ fabsf(pn[2] * ah[2]);
float_t signedDist = glm_vec3_dot((float_t *)pn, (float_t *)ac) - pd;
*outDepth = proj - signedDist;
if(*outDepth <= 0.0f) return false;
glm_vec3_copy((float_t *)pn, outNormal);
return true;
}
void physicsTestClosestPointOnSegment(
const vec3 a, const vec3 b, const vec3 p, vec3 out
) {
vec3 ab, ap;
glm_vec3_sub((float_t *)b, (float_t *)a, ab);
glm_vec3_sub((float_t *)p, (float_t *)a, ap);
float_t denom = glm_vec3_dot(ab, ab);
float_t t = (denom > 1e-10f)
? glm_clamp(glm_vec3_dot(ap, ab) / denom, 0.0f, 1.0f)
: 0.0f;
glm_vec3_lerp((float_t *)a, (float_t *)b, t, out);
}
void physicsTestClosestPointsBetweenSegments(
const vec3 a1, const vec3 b1,
const vec3 a2, const vec3 b2,
vec3 outP1, vec3 outP2
) {
vec3 d1, d2, r;
glm_vec3_sub((float_t *)b1, (float_t *)a1, d1);
glm_vec3_sub((float_t *)b2, (float_t *)a2, d2);
glm_vec3_sub((float_t *)a1, (float_t *)a2, r);
float_t a = glm_vec3_dot(d1, d1);
float_t e = glm_vec3_dot(d2, d2);
float_t f = glm_vec3_dot(d2, r);
float_t s, t;
if(a <= 1e-10f && e <= 1e-10f) {
glm_vec3_copy((float_t *)a1, outP1);
glm_vec3_copy((float_t *)a2, outP2);
return;
}
if(a <= 1e-10f) {
t = 0.0f;
s = glm_clamp(f / e, 0.0f, 1.0f);
} else {
float_t c = glm_vec3_dot(d1, r);
if(e <= 1e-10f) {
s = 0.0f;
t = glm_clamp(-c / a, 0.0f, 1.0f);
} else {
float_t b = glm_vec3_dot(d1, d2);
float_t denom = a * e - b * b;
t = (fabsf(denom) > 1e-10f)
? glm_clamp((b * f - c * e) / denom, 0.0f, 1.0f)
: 0.0f;
s = glm_clamp((b * t + f) / e, 0.0f, 1.0f);
t = glm_clamp((b * s - c) / a, 0.0f, 1.0f);
}
}
glm_vec3_lerp((float_t *)a1, (float_t *)b1, t, outP1);
glm_vec3_lerp((float_t *)a2, (float_t *)b2, s, outP2);
}
bool_t physicsTestCapsuleVsSphere(
const vec3 cc, const float_t cr, const float_t chh,
const vec3 sc, const float_t sr,
vec3 outNormal, float_t *outDepth
) {
vec3 capA = { cc[0], cc[1] - chh, cc[2] };
vec3 capB = { cc[0], cc[1] + chh, cc[2] };
vec3 closest;
physicsTestClosestPointOnSegment(capA, capB, sc, closest);
return physicsTestSphereVsSphere(
closest, cr, sc, sr, outNormal, outDepth
);
}
bool_t physicsTestCapsuleVsAabb(
const vec3 cc, const float_t cr, const float_t chh,
const vec3 ac, const vec3 ah,
vec3 outNormal, float_t *outDepth
) {
vec3 capA = { cc[0], cc[1] - chh, cc[2] };
vec3 capB = { cc[0], cc[1] + chh, cc[2] };
vec3 closest;
physicsTestClosestPointOnSegment(capA, capB, ac, closest);
return physicsTestSphereVsAabb(
closest, cr, ac, ah, outNormal, outDepth
);
}
bool_t physicsTestCapsuleVsPlane(
const vec3 cc, const float_t cr, const float_t chh,
const vec3 pn, const float_t pd,
vec3 outNormal, float_t *outDepth
) {
vec3 capA = { cc[0], cc[1] - chh, cc[2] };
vec3 capB = { cc[0], cc[1] + chh, cc[2] };
float_t da = glm_vec3_dot((float_t *)pn, capA) - pd;
float_t db = glm_vec3_dot((float_t *)pn, capB) - pd;
float_t minDist = (da < db) ? da : db;
*outDepth = cr - minDist;
if(*outDepth <= 0.0f) return false;
glm_vec3_copy((float_t *)pn, outNormal);
return true;
}
bool_t physicsTestCapsuleVsCapsule(
const vec3 c1, const float_t r1, const float_t hh1,
const vec3 c2, const float_t r2, const float_t hh2,
vec3 outNormal, float_t *outDepth
) {
vec3 a1 = { c1[0], c1[1] - hh1, c1[2] };
vec3 b1 = { c1[0], c1[1] + hh1, c1[2] };
vec3 a2 = { c2[0], c2[1] - hh2, c2[2] };
vec3 b2 = { c2[0], c2[1] + hh2, c2[2] };
vec3 p1, p2;
physicsTestClosestPointsBetweenSegments(a1, b1, a2, b2, p1, p2);
return physicsTestSphereVsSphere(p1, r1, p2, r2, outNormal, outDepth);
}
bool_t physicsTestDispatch(
const vec3 aPos, const physicsshape_t aShape,
const vec3 bPos, const physicsshape_t bShape,
vec3 outNormal, float_t *outDepth
) {
physicshapetype_t ta = aShape.type;
physicshapetype_t tb = bShape.type;
if(tb == PHYSICS_SHAPE_PLANE) {
const float_t *pn = bShape.data.plane.normal;
const float_t pd = bShape.data.plane.distance;
switch(ta) {
case PHYSICS_SHAPE_CUBE:
return physicsTestAabbVsPlane(
aPos, aShape.data.cube.halfExtents,
pn, pd, outNormal, outDepth
);
case PHYSICS_SHAPE_SPHERE:
return physicsTestSphereVsPlane(
aPos, aShape.data.sphere.radius,
pn, pd, outNormal, outDepth
);
case PHYSICS_SHAPE_CAPSULE:
return physicsTestCapsuleVsPlane(
aPos,
aShape.data.capsule.radius,
aShape.data.capsule.halfHeight,
pn, pd, outNormal, outDepth
);
default:
return false;
}
}
if(ta == PHYSICS_SHAPE_PLANE) {
vec3 tmp; float_t d;
if(!physicsTestDispatch(
bPos, bShape, aPos, aShape, tmp, &d
)) return false;
glm_vec3_scale(tmp, -1.0f, outNormal);
*outDepth = d;
return true;
}
switch(ta) {
case PHYSICS_SHAPE_CUBE: {
const float_t *ac = aPos;
const float_t *ah = aShape.data.cube.halfExtents;
switch(tb) {
case PHYSICS_SHAPE_CUBE:
return physicsTestAabbVsAabb(
ac, ah,
bPos, bShape.data.cube.halfExtents,
outNormal, outDepth
);
case PHYSICS_SHAPE_SPHERE: {
vec3 tmp; float_t d;
if(!physicsTestSphereVsAabb(
bPos, bShape.data.sphere.radius,
ac, ah, tmp, &d
)) return false;
glm_vec3_scale(tmp, -1.0f, outNormal);
*outDepth = d;
return true;
}
case PHYSICS_SHAPE_CAPSULE: {
vec3 tmp; float_t d;
if(!physicsTestCapsuleVsAabb(
bPos,
bShape.data.capsule.radius,
bShape.data.capsule.halfHeight,
ac, ah, tmp, &d
)) return false;
glm_vec3_scale(tmp, -1.0f, outNormal);
*outDepth = d;
return true;
}
default: return false;
}
}
case PHYSICS_SHAPE_SPHERE: {
const float_t sr = aShape.data.sphere.radius;
switch(tb) {
case PHYSICS_SHAPE_CUBE:
return physicsTestSphereVsAabb(
aPos, sr,
bPos, bShape.data.cube.halfExtents,
outNormal, outDepth
);
case PHYSICS_SHAPE_SPHERE:
return physicsTestSphereVsSphere(
aPos, sr,
bPos, bShape.data.sphere.radius,
outNormal, outDepth
);
case PHYSICS_SHAPE_CAPSULE: {
vec3 tmp; float_t d;
if(!physicsTestCapsuleVsSphere(
bPos,
bShape.data.capsule.radius,
bShape.data.capsule.halfHeight,
aPos, sr, tmp, &d
)) return false;
glm_vec3_scale(tmp, -1.0f, outNormal);
*outDepth = d;
return true;
}
default: return false;
}
}
case PHYSICS_SHAPE_CAPSULE: {
const float_t cr = aShape.data.capsule.radius;
const float_t chh = aShape.data.capsule.halfHeight;
switch(tb) {
case PHYSICS_SHAPE_CUBE:
return physicsTestCapsuleVsAabb(
aPos, cr, chh,
bPos, bShape.data.cube.halfExtents,
outNormal, outDepth
);
case PHYSICS_SHAPE_SPHERE:
return physicsTestCapsuleVsSphere(
aPos, cr, chh,
bPos, bShape.data.sphere.radius,
outNormal, outDepth
);
case PHYSICS_SHAPE_CAPSULE:
return physicsTestCapsuleVsCapsule(
aPos, cr, chh,
bPos,
bShape.data.capsule.radius,
bShape.data.capsule.halfHeight,
outNormal, outDepth
);
default: return false;
}
}
default: return false;
}
}
bool_t physicsTestShapeVsShape(
const vec3 aPos, const physicsshape_t aShape,
const vec3 bPos, const physicsshape_t bShape,
vec3 outNormal, float_t *outDepth
) {
return physicsTestDispatch(
aPos, aShape, bPos, bShape, outNormal, outDepth
);
}
src/dusk/physics/physicstest.h
-247
View File
@@ -1,247 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "physicsshape.h"
/**
* Tests overlap between two axis-aligned bounding boxes.
* outNormal points from B toward A.
*
* @param ac Center of AABB A.
* @param ah Half-extents of AABB A.
* @param bc Center of AABB B.
* @param bh Half-extents of AABB B.
* @param outNormal Push-out normal (B toward A).
* @param outDepth Penetration depth.
* @return true if overlapping.
*/
bool_t physicsTestAabbVsAabb(
const vec3 ac, const vec3 ah,
const vec3 bc, const vec3 bh,
vec3 outNormal, float_t *outDepth
);
/**
* Tests overlap between two spheres.
* outNormal points from B toward A.
*
* @param ac Center of sphere A.
* @param ar Radius of sphere A.
* @param bc Center of sphere B.
* @param br Radius of sphere B.
* @param outNormal Push-out normal (B toward A).
* @param outDepth Penetration depth.
* @return true if overlapping.
*/
bool_t physicsTestSphereVsSphere(
const vec3 ac, const float_t ar,
const vec3 bc, const float_t br,
vec3 outNormal, float_t *outDepth
);
/**
* Tests overlap between a sphere and an axis-aligned bounding box.
* outNormal points from the AABB toward the sphere.
*
* @param sc Center of the sphere.
* @param sr Radius of the sphere.
* @param ac Center of the AABB.
* @param ah Half-extents of the AABB.
* @param outNormal Push-out normal (AABB toward sphere).
* @param outDepth Penetration depth.
* @return true if overlapping.
*/
bool_t physicsTestSphereVsAabb(
const vec3 sc, const float_t sr,
const vec3 ac, const vec3 ah,
vec3 outNormal, float_t *outDepth
);
/**
* Tests overlap between a sphere and an infinite plane.
* outNormal equals the plane normal (pointing away from the surface).
*
* @param sc Center of the sphere.
* @param sr Radius of the sphere.
* @param pn Plane normal (unit vector, world-space).
* @param pd Plane offset: dot(pn, surfacePoint) == pd.
* @param outNormal Push-out normal (equals pn).
* @param outDepth Penetration depth.
* @return true if overlapping.
*/
bool_t physicsTestSphereVsPlane(
const vec3 sc, const float_t sr,
const vec3 pn, const float_t pd,
vec3 outNormal, float_t *outDepth
);
/**
* Tests overlap between an AABB and an infinite plane.
* outNormal equals the plane normal.
*
* @param ac Center of the AABB.
* @param ah Half-extents of the AABB.
* @param pn Plane normal (unit vector, world-space).
* @param pd Plane offset (see physicsTestSphereVsPlane).
* @param outNormal Push-out normal (equals pn).
* @param outDepth Penetration depth.
* @return true if overlapping.
*/
bool_t physicsTestAabbVsPlane(
const vec3 ac, const vec3 ah,
const vec3 pn, const float_t pd,
vec3 outNormal, float_t *outDepth
);
/**
* Finds the closest point on segment [a, b] to query point p.
*
* @param a Start of the segment.
* @param b End of the segment.
* @param p Query point.
* @param out Receives the closest point on [a, b] to p.
*/
void physicsTestClosestPointOnSegment(
const vec3 a, const vec3 b, const vec3 p, vec3 out
);
/**
* Finds the closest points between two line segments.
*
* @param a1 Start of segment 1.
* @param b1 End of segment 1.
* @param a2 Start of segment 2.
* @param b2 End of segment 2.
* @param outP1 Receives the closest point on segment 1.
* @param outP2 Receives the closest point on segment 2.
*/
void physicsTestClosestPointsBetweenSegments(
const vec3 a1, const vec3 b1,
const vec3 a2, const vec3 b2,
vec3 outP1, vec3 outP2
);
/**
* Tests overlap between a Y-axis-aligned capsule and a sphere.
* outNormal points from the sphere toward the capsule.
*
* @param cc Center of the capsule.
* @param cr Radius of the capsule.
* @param chh Half-height of the capsule's cylindrical segment.
* @param sc Center of the sphere.
* @param sr Radius of the sphere.
* @param outNormal Push-out normal (sphere toward capsule).
* @param outDepth Penetration depth.
* @return true if overlapping.
*/
bool_t physicsTestCapsuleVsSphere(
const vec3 cc, const float_t cr, const float_t chh,
const vec3 sc, const float_t sr,
vec3 outNormal, float_t *outDepth
);
/**
* Tests overlap between a Y-axis-aligned capsule and an AABB.
* outNormal points from the AABB toward the capsule.
*
* @param cc Center of the capsule.
* @param cr Radius of the capsule.
* @param chh Half-height of the capsule's cylindrical segment.
* @param ac Center of the AABB.
* @param ah Half-extents of the AABB.
* @param outNormal Push-out normal (AABB toward capsule).
* @param outDepth Penetration depth.
* @return true if overlapping.
*/
bool_t physicsTestCapsuleVsAabb(
const vec3 cc, const float_t cr, const float_t chh,
const vec3 ac, const vec3 ah,
vec3 outNormal, float_t *outDepth
);
/**
* Tests overlap between a Y-axis-aligned capsule and an infinite plane.
* outNormal equals the plane normal.
*
* @param cc Center of the capsule.
* @param cr Radius of the capsule.
* @param chh Half-height of the capsule's cylindrical segment.
* @param pn Plane normal (unit vector, world-space).
* @param pd Plane offset (see physicsTestSphereVsPlane).
* @param outNormal Push-out normal (equals pn).
* @param outDepth Penetration depth.
* @return true if overlapping.
*/
bool_t physicsTestCapsuleVsPlane(
const vec3 cc, const float_t cr, const float_t chh,
const vec3 pn, const float_t pd,
vec3 outNormal, float_t *outDepth
);
/**
* Tests overlap between two Y-axis-aligned capsules.
* outNormal points from capsule B toward capsule A.
*
* @param c1 Center of capsule A.
* @param r1 Radius of capsule A.
* @param hh1 Half-height of capsule A's cylindrical segment.
* @param c2 Center of capsule B.
* @param r2 Radius of capsule B.
* @param hh2 Half-height of capsule B's cylindrical segment.
* @param outNormal Push-out normal (B toward A).
* @param outDepth Penetration depth.
* @return true if overlapping.
*/
bool_t physicsTestCapsuleVsCapsule(
const vec3 c1, const float_t r1, const float_t hh1,
const vec3 c2, const float_t r2, const float_t hh2,
vec3 outNormal, float_t *outDepth
);
/**
* Routes a shape-pair collision test to the correct primitive.
* When A is a plane, delegates with swapped arguments and negates
* the resulting normal. outNormal points from B toward A.
*
* @param aPos Position of shape A.
* @param aShape Shape descriptor of A.
* @param bPos Position of shape B.
* @param bShape Shape descriptor of B.
* @param outNormal Push-out normal (B toward A).
* @param outDepth Penetration depth.
* @return true if overlapping.
*/
bool_t physicsTestDispatch(
const vec3 aPos, const physicsshape_t aShape,
const vec3 bPos, const physicsshape_t bShape,
vec3 outNormal, float_t *outDepth
);
/**
* Tests for collision between two shapes. Returns true if they
* overlap, and if so, outputs the push-out normal and depth.
*
* outNormal always points from shape B toward shape A, so adding
* (outNormal * outDepth) to A's position separates the two shapes.
*
* @param aPos Position of shape A.
* @param aShape Shape descriptor of A.
* @param bPos Position of shape B.
* @param bShape Shape descriptor of B.
* @param outNormal Push-out normal, pointing from B toward A.
* @param outDepth Penetration depth (positive when overlapping).
* @return true if the shapes overlap, false otherwise.
*/
bool_t physicsTestShapeVsShape(
const vec3 aPos,
const physicsshape_t aShape,
const vec3 bPos,
const physicsshape_t bShape,
vec3 outNormal,
float_t *outDepth
);
src/dusk/physics/physicsworld.c
-151
View File
@@ -1,151 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "physicsworld.h"
#include "assert/assert.h"
#include "util/memory.h"
#include "entity/entity.h"
#include "entity/component.h"
#include "physicstest.h"
physicsworld_t PHYSICS_WORLD;
void physicsWorldInit() {
memoryZero(&PHYSICS_WORLD, sizeof(physicsworld_t));
PHYSICS_WORLD.gravity[0] = 0.0f;
PHYSICS_WORLD.gravity[1] = -9.81f;
PHYSICS_WORLD.gravity[2] = 0.0f;
}
void physicsWorldStep(const float_t dt) {
assertTrue(dt > 0.0f, "Delta time must be positive");
entityid_t physEnts[ENTITY_COUNT_MAX];
componentid_t physComps[ENTITY_COUNT_MAX];
entityid_t physCount = componentGetEntitiesWithComponent(
COMPONENT_TYPE_PHYSICS, physEnts, physComps
);
/* Pre-fetch all position and physics pointers once. */
entityposition_t *positions[ENTITY_COUNT_MAX];
entityphysics_t *physBodies[ENTITY_COUNT_MAX];
for(entityid_t i = 0; i < physCount; i++) {
componentid_t posComp = entityGetComponent(
physEnts[i], COMPONENT_TYPE_POSITION
);
positions[i] = (posComp != 0xFF)
? entityPositionGet(physEnts[i], posComp)
: NULL;
physBodies[i] = entityPhysicsGet(physEnts[i], physComps[i]);
}
/* Phase 1: integrate dynamic bodies (gravity + velocity -> position).
* Writes directly to pos->position, matrix rebuilt at end. */
for(entityid_t i = 0; i < physCount; i++) {
if(!positions[i]) continue;
entityphysics_t *phys = physBodies[i];
if(phys->type != PHYSICS_BODY_DYNAMIC) continue;
phys->onGround = false;
phys->velocity[0] += PHYSICS_WORLD.gravity[0] * phys->gravityScale * dt;
phys->velocity[1] += PHYSICS_WORLD.gravity[1] * phys->gravityScale * dt;
phys->velocity[2] += PHYSICS_WORLD.gravity[2] * phys->gravityScale * dt;
float_t *pos = positions[i]->position;
pos[0] += phys->velocity[0] * dt;
pos[1] += phys->velocity[1] * dt;
pos[2] += phys->velocity[2] * dt;
}
/* Phase 2: dynamic vs static/kinematic. */
for(entityid_t i = 0; i < physCount; i++) {
if(!positions[i]) continue;
entityphysics_t *phys = physBodies[i];
if(phys->type != PHYSICS_BODY_DYNAMIC) continue;
float_t *pos = positions[i]->position;
for(entityid_t j = 0; j < physCount; j++) {
if(i == j || !positions[j]) continue;
entityphysics_t *otherPhys = physBodies[j];
if(otherPhys->type == PHYSICS_BODY_DYNAMIC) continue;
vec3 normal; float_t depth;
if(!physicsTestShapeVsShape(
pos, phys->shape,
positions[j]->position, otherPhys->shape,
normal, &depth
)) continue;
pos[0] += normal[0] * depth;
pos[1] += normal[1] * depth;
pos[2] += normal[2] * depth;
float_t vn = glm_vec3_dot(phys->velocity, normal);
if(vn < 0.0f) {
phys->velocity[0] -= vn * normal[0];
phys->velocity[1] -= vn * normal[1];
phys->velocity[2] -= vn * normal[2];
}
if(normal[1] > PHYSICS_GROUND_THRESHOLD) phys->onGround = true;
}
}
/* Phase 3: dynamic vs dynamic. */
for(entityid_t i = 0; i < physCount; i++) {
if(!positions[i]) continue;
entityphysics_t *physA = physBodies[i];
if(physA->type != PHYSICS_BODY_DYNAMIC) continue;
float_t *posA = positions[i]->position;
for(entityid_t j = i + 1; j < physCount; j++) {
if(!positions[j]) continue;
entityphysics_t *physB = physBodies[j];
if(physB->type != PHYSICS_BODY_DYNAMIC) continue;
float_t *posB = positions[j]->position;
vec3 normal; float_t depth;
if(!physicsTestShapeVsShape(
posA, physA->shape, posB, physB->shape, normal, &depth
)) continue;
posA[0] += normal[0] * depth * 0.5f;
posA[1] += normal[1] * depth * 0.5f;
posA[2] += normal[2] * depth * 0.5f;
posB[0] -= normal[0] * depth * 0.5f;
posB[1] -= normal[1] * depth * 0.5f;
posB[2] -= normal[2] * depth * 0.5f;
float_t v_rel = glm_vec3_dot(physA->velocity, normal)
- glm_vec3_dot(physB->velocity, normal);
if(v_rel < 0.0f) {
physA->velocity[0] -= v_rel * normal[0];
physA->velocity[1] -= v_rel * normal[1];
physA->velocity[2] -= v_rel * normal[2];
physB->velocity[0] += v_rel * normal[0];
physB->velocity[1] += v_rel * normal[1];
physB->velocity[2] += v_rel * normal[2];
}
if( normal[1] > PHYSICS_GROUND_THRESHOLD) physA->onGround = true;
if(-normal[1] > PHYSICS_GROUND_THRESHOLD) physB->onGround = true;
}
}
/* Rebuild transforms for all dynamic bodies once, after all phases. */
for(entityid_t i = 0; i < physCount; i++) {
if(!positions[i]) continue;
if(physBodies[i]->type != PHYSICS_BODY_DYNAMIC) continue;
entityPositionRebuild(positions[i]);
}
}
src/dusk/physics/physicsworld.h
-30
View File
@@ -1,30 +0,0 @@
/**
* Copyright (c) 2026 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "physics/physicsshape.h"
#include "physics/physicsbodytype.h"
#define PHYSICS_GROUND_THRESHOLD 0.707f
typedef struct {
vec3 gravity;
} physicsworld_t;
extern physicsworld_t PHYSICS_WORLD;
/**
* Initializes the physics world.
*/
void physicsWorldInit(void);
/**
* Steps the physics simulation forward.
*
* @param dt The time delta in seconds since the last step.
*/
void physicsWorldStep(const float_t dt);
src/dusk/rpg/CMakeLists.txt
+20
View File
@@ -0,0 +1,20 @@
# Copyright (c) 2025 Dominic Masters
#
# This software is released under the MIT License.
# https://opensource.org/licenses/MIT
# Sources
target_sources(${DUSK_LIBRARY_TARGET_NAME}
PUBLIC
rpg.c
rpgcamera.c
rpgtextbox.c
)
# Subdirs
add_subdirectory(cutscene)
add_subdirectory(entity)
add_subdirectory(overworld)
add_subdirectory(story)
add_subdirectory(item)
src/dusk/script/module/entity/CMakeLists.txt → src/dusk/rpg/cutscene/CMakeLists.txt
+5 -4
View File
@@ -1,13 +1,14 @@
# Copyright (c) 2026 Dominic Masters # Copyright (c) 2025 Dominic Masters
# #
# This software is released under the MIT License. # This software is released under the MIT License.
# https://opensource.org/licenses/MIT # https://opensource.org/licenses/MIT
# Sources
target_sources(${DUSK_LIBRARY_TARGET_NAME} target_sources(${DUSK_LIBRARY_TARGET_NAME}
PUBLIC PUBLIC
modulecomponent.c cutscenesystem.c
moduleentity.c cutscenemode.c
) )
# Subdirs # Subdirs
add_subdirectory(component) add_subdirectory(item)
src/dusk/rpg/cutscene/cutscene.h
+14
View File
@@ -0,0 +1,14 @@
/**
* Copyright (c) 2025 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "rpg/cutscene/item/cutsceneitem.h"
typedef struct cutscene_s {
const cutsceneitem_t *items;
uint8_t itemCount;
} cutscene_t;
src/dusk/rpg/cutscene/cutscenemode.c
+19
View File
@@ -0,0 +1,19 @@
/**
* Copyright (c) 2025 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "rpg/cutscene/cutscenesystem.h"
bool_t cutsceneModeIsInputAllowed() {
switch(CUTSCENE_SYSTEM.mode) {
case CUTSCENE_MODE_FULL_FREEZE:
case CUTSCENE_MODE_INPUT_FREEZE:
return false;
default:
return true;
}
}
src/dusk/rpg/cutscene/cutscenemode.h
+26
View File
@@ -0,0 +1,26 @@
/**
* Copyright (c) 2025 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#pragma once
#include "dusk.h"
typedef enum {
CUTSCENE_MODE_NONE,
CUTSCENE_MODE_FULL_FREEZE,
CUTSCENE_MODE_INPUT_FREEZE,
CUTSCENE_MODE_GAMEPLAY
} cutscenemode_t;
// Default mode for all cutscenes.
#define CUTSCENE_MODE_INITIAL CUTSCENE_MODE_INPUT_FREEZE
/**
* Check if input is allowed in the current cutscene mode.
*
* @return true if input is allowed, false otherwise.
*/
bool_t cutsceneModeIsInputAllowed();
src/dusk/rpg/cutscene/cutscenesystem.c
+56
View File
@@ -0,0 +1,56 @@
/**
* Copyright (c) 2025 Dominic Masters
*
* This software is released under the MIT License.
* https://opensource.org/licenses/MIT
*/
#include "cutscenesystem.h"
#include "util/memory.h"
cutscenesystem_t CUTSCENE_SYSTEM;
void cutsceneSystemInit() {
memoryZero(&CUTSCENE_SYSTEM, sizeof(cutscenesystem_t));
}
void cutsceneSystemStartCutscene(const cutscene_t *cutscene) {
CUTSCENE_SYSTEM.scene = cutscene;
CUTSCENE_SYSTEM.mode = CUTSCENE_MODE_INITIAL;
CUTSCENE_SYSTEM.currentItem = 0xFF;// Set to 0xFF so start wraps.
cutsceneSystemNext();
}
void cutsceneSystemUpdate() {
if(CUTSCENE_SYSTEM.scene == NULL) return;
const cutsceneitem_t *item = cutsceneSystemGetCurrentItem();
cutsceneItemUpdate(item, &CUTSCENE_SYSTEM.data);
}
void cutsceneSystemNext() {
if(CUTSCENE_SYSTEM.scene == NULL) return;
CUTSCENE_SYSTEM.currentItem++;
// End of the cutscene?
if(
CUTSCENE_SYSTEM.currentItem >= CUTSCENE_SYSTEM.scene->itemCount
) {
CUTSCENE_SYSTEM.scene = NULL;
CUTSCENE_SYSTEM.currentItem = 0xFF;
CUTSCENE_SYSTEM.mode = CUTSCENE_MODE_NONE;
return;
}
// Start item.
const cutsceneitem_t *item = cutsceneSystemGetCurrentItem();
memset(&CUTSCENE_SYSTEM.data, 0, sizeof(CUTSCENE_SYSTEM.data));
cutsceneItemStart(item, &CUTSCENE_SYSTEM.data);
}
const cutsceneitem_t * cutsceneSystemGetCurrentItem() {
if(CUTSCENE_SYSTEM.scene == NULL) return NULL;
return &CUTSCENE_SYSTEM.scene->items[CUTSCENE_SYSTEM.currentItem];
}

Some files were not shown because too many files have changed in this diff Show More