93 lines
2.4 KiB
Markdown
93 lines
2.4 KiB
Markdown
# Console
|
|
|
|
Source: `src/dusk/console/`
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The console is a lightweight in-engine debug overlay. It maintains a
|
|
fixed-size ring buffer of text lines and can render them to the screen
|
|
as an overlay. On Linux (where `DUSK_CONSOLE_POSIX` is defined), it
|
|
also reads commands from stdin on a background thread, allowing
|
|
interactive input during development without pausing the game loop.
|
|
|
|
---
|
|
|
|
## Limits
|
|
|
|
| Constant | Value |
|
|
|----------|-------|
|
|
| `CONSOLE_LINE_MAX` | 512 chars per line |
|
|
| `CONSOLE_HISTORY_MAX` | 16 lines in the ring buffer |
|
|
| `CONSOLE_EXEC_BUFFER_MAX` | 32 pending execution slots |
|
|
|
|
---
|
|
|
|
## Global state
|
|
|
|
```c
|
|
typedef struct {
|
|
char_t line[CONSOLE_HISTORY_MAX][CONSOLE_LINE_MAX]; // ring buffer
|
|
bool_t visible;
|
|
|
|
#ifdef DUSK_CONSOLE_POSIX
|
|
threadmutex_t printMutex; // guards ring buffer on POSIX targets
|
|
#endif
|
|
} console_t;
|
|
|
|
extern console_t CONSOLE;
|
|
```
|
|
|
|
---
|
|
|
|
## API
|
|
|
|
```c
|
|
void consoleInit(void);
|
|
|
|
// printf-style print into the ring buffer.
|
|
// Thread-safe on POSIX (uses printMutex).
|
|
void consolePrint(const char_t *message, ...);
|
|
|
|
// Process any queued script input lines. Must be called from the
|
|
// main thread once per frame.
|
|
void consoleUpdate(void);
|
|
|
|
// Draw the ring buffer as an overlay in UI space.
|
|
errorret_t consoleDraw(void);
|
|
|
|
void consoleDispose(void);
|
|
```
|
|
|
|
---
|
|
|
|
## POSIX stdin mode (`DUSK_CONSOLE_POSIX`)
|
|
|
|
On Linux only (`DUSK_CONSOLE_POSIX`), the console launches a background
|
|
thread that polls stdin using `poll()` at 75 ms intervals
|
|
(`CONSOLE_POSIX_POLL_RATE`). Lines typed at the terminal are queued
|
|
and dispatched on the main thread by `consoleUpdate()`.
|
|
|
|
This allows typing commands or JS expressions into the running game
|
|
without blocking the render loop. The ring buffer is protected by
|
|
`CONSOLE.printMutex` so `consolePrint` is safe to call from either
|
|
thread.
|
|
|
|
POSIX mode is not available on PSP, Vita, or Dolphin targets.
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- `CONSOLE.visible` controls whether `consoleDraw` renders anything.
|
|
Toggle it from a debug keybind or always set it to `true` in
|
|
development builds.
|
|
- `consolePrint` wraps lines at `CONSOLE_LINE_MAX` -- long messages are
|
|
truncated. Use multiple calls for long output.
|
|
- The console is distinct from the error system (`errorThrow` /
|
|
`errorPrint`). Use `consolePrint` for diagnostic output; use
|
|
`errorThrow` for recoverable failures.
|
|
- Log calls (`logDebug`, `logError`) go to the platform's debug output
|
|
(stdout/stderr), not to the console ring buffer.
|