dusk/.claude/engine.md

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.

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

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:

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.

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