96 lines
2.8 KiB
Markdown
96 lines
2.8 KiB
Markdown
# 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()`.
|