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,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)