feat: Update README files to provide detailed project structure and usage instructions for Wolfenstein 3D workspace

Signed-off-by: Hans Kokx <hans.d.kokx@gmail.com>
2026-03-24 14:53:25 +01:00
parent 8a9be477e4
commit a08af99b6f
6 changed files with 442 additions and 28 deletions
@@ -0,0 +1,91 @@
+# wolf_3d_cli
+
+Terminal host application for running Wolfenstein 3D using the shared `wolf_3d_dart` engine.
+
+## What This App Is
+
+`wolf_3d_cli` is a pure Dart executable that:
+
+- discovers Wolf3D game data on local disk,
+- initializes `WolfEngine` with CLI input/audio backends,
+- runs the terminal game loop.
+
+Entrypoint: `bin/main.dart`
+
+## Prerequisites
+
+- Dart SDK `^3.11.1`
+- A terminal with ANSI escape support
+- Local Wolfenstein 3D game data files
+
+## Setup
+
+From this directory:
+
+```bash
+dart pub get
+```
+
+## Run
+
+Default discovery:
+
+```bash
+dart run bin/main.dart
+```
+
+With an explicit game-data directory:
+
+```bash
+dart run bin/main.dart --data-directory /path/to/game-data
+```
+
+Short option form:
+
+```bash
+dart run bin/main.dart -d /path/to/game-data
+```
+
+Show CLI usage:
+
+```bash
+dart run bin/main.dart --help
+```
+
+## Runtime Architecture
+
+At startup, `bin/main.dart` wires together:
+
+- `WolfensteinLoader.discover(...)` for data discovery,
+- `WolfEngine` for simulation/session state,
+- `CliInput` for keyboard input,
+- `NativeSubprocessAudio` for native-process audio playback,
+- `CliGameLoop` for terminal rendering loop + renderer settings persistence.
+
+The CLI host exits through engine callbacks (`onQuit`, `onGameWon`) after restoring terminal state.
+
+## Development Commands
+
+From this directory:
+
+```bash
+dart analyze
+```
+
+If module-level tests are added in this app later:
+
+```bash
+dart test
+```
+
+## Troubleshooting
+
+- **No game data found**: pass `--data-directory` explicitly.
+- **Terminal output artifacts**: resize terminal and rerun; ensure ANSI-capable terminal emulator.
+- **No audio output**: verify host OS has required native audio command support.
+
+## Related Modules
+
+- Core runtime: [`../../packages/wolf_3d_dart/README.md`](../../packages/wolf_3d_dart/README.md)
+- Flutter host alternative: [`../wolf_3d_gui/README.md`](../wolf_3d_gui/README.md)
+- Workspace overview: [`../../README.md`](../../README.md)