Add claude docs
This commit is contained in:
@@ -0,0 +1,162 @@
|
||||
# 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;`.
|
||||
Reference in New Issue
Block a user