dusk/.claude/systems.md

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.

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):

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:

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.

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)

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.

// 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.

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:

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().

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:

networkRequestConnection(onConnected, onFailed, onDisconnect, user);
networkRequestDisconnection(onComplete, user);
networkIsConnected();   // bool_t

State machine: DISCONNECTED → CONNECTING → CONNECTED → DISCONNECTING → DISCONNECTED.

Network address info (after connection):

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.