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