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