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)
@@ -0,0 +1,83 @@
+# wolf_3d_gui
+
+Flutter GUI host application for running Wolfenstein 3D with the shared engine and Flutter integration package.
+
+## What This App Is
+
+`wolf_3d_gui` is the primary Flutter app host in this workspace.
+
+It:
+
+- initializes `Wolf3dFlutterEngine`,
+- discovers available game data directories,
+- manages game-data selection and session flow,
+- renders gameplay through Flutter-native UI and renderer widgets.
+
+Entrypoint: `lib/main.dart`
+
+## Prerequisites
+
+- Flutter SDK
+- Dart SDK `^3.11.1`
+- Local Wolfenstein 3D game data files
+
+### Linux native requirements
+
+On Debian/Ubuntu, install:
+
+`libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev lld`
+
+## Setup
+
+From this directory:
+
+```bash
+flutter pub get
+```
+
+## Run
+
+Run on your default connected Flutter target:
+
+```bash
+flutter run
+```
+
+Examples by target:
+
+```bash
+flutter run -d linux
+flutter run -d chrome
+```
+
+## Test and Analyze
+
+From this directory:
+
+```bash
+flutter test
+flutter analyze
+```
+
+## App Flow Overview
+
+Startup sequence:
+
+1. `lib/main.dart` creates and initializes `Wolf3dFlutterEngine`.
+2. Engine init discovers configured game-data directories.
+3. App shell (`Wolf3dGuiApp`) drives selection/navigation.
+4. Gameplay screen builds engine session + renderer mode and runs loop.
+
+Game data directory selection/persistence is managed by app managers and Flutter package persistence helpers.
+
+## Troubleshooting
+
+- **No game data discovered**: choose a valid directory in the picker and ensure files are present.
+- **Linux build/runtime issues**: verify native dependency packages are installed.
+- **Web target limitations**: use desktop target for full native-audio/path behavior.
+
+## Related Modules
+
+- Flutter integration package: [`../../packages/wolf_3d_flutter/README.md`](../../packages/wolf_3d_flutter/README.md)
+- Core runtime package: [`../../packages/wolf_3d_dart/README.md`](../../packages/wolf_3d_dart/README.md)
+- Workspace overview: [`../../README.md`](../../README.md)