Docs

.claude/systems.md

@@ -0,0 +1,177 @@
+# Engine Systems
+
+Smaller systems that support the engine but don't warrant their own file each.
+
+---
+
+## Time (`src/dusk/time/`)
+
+`dusktime_t TIME` tracks fixed and dynamic delta time.
+
+```c
+TIME.delta         // fixed_t: always DUSK_TIME_STEP (16ms default) on fixed-rate platforms
+TIME.time          // fixed_t: total elapsed time in seconds
+```
+
+On platforms with `DUSK_TIME_DYNAMIC` (Linux/SDL2):
+```c
+TIME.dynamicDelta  // fixed_t: actual time since last frame
+TIME.dynamicTime   // fixed_t: total elapsed (dynamic)
+TIME.dynamicUpdate // bool_t: true when a real tick occurred
+```
+
+Call `timeUpdate()` once per frame (before input/logic). `timeGetEpoch()` returns the current wall-clock time as a `dusktimeepoch_t`.
+
+### Epoch time (`time/timeepoch.h`)
+
+`dusktimeepoch_t` stores a Unix timestamp (double) with timezone offset. Utilities:
+
+```c
+dusktimeepoch_t e = timeGetEpoch();
+timeEpochGetHours(e)      // 0–23
+timeEpochGetMinutes(e)    // 0–59
+timeEpochGetSeconds(e)    // 0–59
+timeEpochGetDayOfMonth(e) // 0–30
+timeEpochGetMonth(e)      // 0–11
+timeEpochGetYear(e)
+
+// Format: %Y year, %m month, %d day, %H hour, %M minute, %S second
+timeEpochFormat(e, "%Y-%m-%d %H:%M:%S", buf, sizeof(buf));
+
+// Compare: returns -1, 0, 1
+timeEpochCompare(a, b);
+
+// Timezone shift:
+dusktimeepoch_t local = timeEpochSwitchTimeZone(e, offsetHours);
+```
+
+---
+
+## Thread (`src/dusk/thread/`)
+
+Currently only the pthread backend (`DUSK_THREAD_PTHREAD`) exists. Thread objects are `thread_t` — used primarily by the asset loader.
+
+```c
+threadInit(&thread, myCallback);   // myCallback: void (*)(thread_t *)
+threadStart(&thread);              // blocks until thread is RUNNING
+threadStop(&thread);               // requests stop, blocks until STOPPED
+
+// Inside the thread callback:
+while(!threadShouldStop(&thread)) { /* work */ }
+```
+
+State flow: `STOPPED → STARTING → RUNNING → (STOP_REQUESTED) → STOPPED`.
+
+### Mutex (`thread/threadmutex.h`)
+
+```c
+threadMutexInit(&lock);
+threadMutexLock(&lock);
+threadMutexUnlock(&lock);
+threadMutexTryLock(&lock);       // non-blocking; returns false if already held
+threadMutexWaitLock(&lock);      // release lock and sleep until signalled
+threadMutexSignal(&lock);        // wake a thread waiting on this mutex
+threadMutexDispose(&lock);
+```
+
+### Thread-local storage
+
+`THREAD_LOCAL` expands to `__thread` (GCC) on pthread platforms. Used for the per-thread error state (`ERROR_STATE` in `error/error.h`).
+
+---
+
+## Event (`src/dusk/event/`)
+
+A fixed-capacity multicast callback list.
+
+```c
+// Declare backing arrays (choose a size):
+eventcallback_t cbs[4];
+void *users[4];
+event_t myEvent;
+eventInit(&myEvent, cbs, users, 4);
+
+eventSubscribe(&myEvent, myCallback, myUser);
+eventUnsubscribe(&myEvent, myCallback);
+eventInvoke(&myEvent, params);   // calls all subscribers; params passed as-is
+```
+
+Callback signature: `void cb(void *params, void *user)`.
+
+`event_t` does not own its callback/user arrays. Always declare them alongside the event in the same struct or as static arrays.
+
+---
+
+## Console (`src/dusk/console/`)
+
+`CONSOLE` is a scrolling in-game terminal for debug output. On POSIX platforms (`DUSK_CONSOLE_POSIX`) it also polls stdin in a thread so commands can be typed during a running session.
+
+```c
+consolePrint("Value is %d", x);   // printf-style; thread-safe
+consoleDraw();                     // renders visible history lines to screen
+```
+
+Configuration constants (`consoledefs.h`):
+- `CONSOLE_LINE_MAX` — 512 chars per line
+- `CONSOLE_HISTORY_MAX` — 16 lines of scrollback
+- `CONSOLE_EXEC_BUFFER_MAX` — 32 pending exec commands
+
+`CONSOLE.visible` controls whether `consoleDraw()` actually renders anything.
+
+---
+
+## Log (`src/dusk/log/`)
+
+Two simple output functions, implemented per-platform:
+
+```c
+logDebug("format %s", arg);   // debug output (stdout on Linux, debug channel on consoles)
+logError("format %s", arg);   // error output; may pause execution on some platforms
+```
+
+These go directly to the platform's native output and are not buffered by the console history.
+
+---
+
+## System / Platform (`src/dusk/system/`)
+
+`systemInit()` runs platform-specific startup (e.g. Wii PAD init, PSP kernel setup). Must be the first call in `engineInit()`.
+
+```c
+systemplatform_t p = systemGetPlatform();   // SYSTEM_PLATFORM_LINUX, _PSP, etc.
+systemdialogtype_t d = systemGetActiveDialogType();
+// SYSTEM_DIALOG_TYPE_NONE / RENDER_BLOCKING / TICK_BLOCKING
+```
+
+The full platform list is defined via X-macro in `system/systemplatformlist.h`:
+
+| Constant | Value |
+|---|---|
+| `SYSTEM_PLATFORM_LINUX` | 0 |
+| `SYSTEM_PLATFORM_KNULLI` | 1 |
+| `SYSTEM_PLATFORM_PSP` | 2 |
+| `SYSTEM_PLATFORM_GAMECUBE` | 3 |
+| `SYSTEM_PLATFORM_WII` | 4 |
+
+---
+
+## Network (`src/dusk/network/`)
+
+`network_t NETWORK` manages platform connection state. The engine calls `networkInit` / `networkUpdate` / `networkDispose`; game code uses the request API:
+
+```c
+networkRequestConnection(onConnected, onFailed, onDisconnect, user);
+networkRequestDisconnection(onComplete, user);
+networkIsConnected();   // bool_t
+```
+
+State machine: `DISCONNECTED → CONNECTING → CONNECTED → DISCONNECTING → DISCONNECTED`.
+
+Network address info (after connection):
+```c
+networkinfo_t info = networkGetInfo();
+// info.type = NETWORK_TYPE_IPV4 / IPV6
+// info.ipv4.ip[4] or info.ipv6.ip[16]
+```
+
+Platform backends implement `networkPlatformInit/Update/Dispose/IsConnected`. Currently only Linux (socket-based) and PSP/Vita are implemented.