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
@@ -1,11 +1,86 @@
 # wolf_dart

-A new Flutter project.
+Wolfenstein 3D workspace built with Dart + Flutter.

-## Running
+This repository is organized as a multi-package workspace:

-### Linux requirements
+- **Apps** in `apps/` (CLI host and Flutter GUI host)
+- **Packages** in `packages/` (core engine, Flutter integration, and assets)

-Linux (Debian/Ubuntu) requires the following packages to be installed:
+The project expects you to provide legal Wolfenstein 3D game data files locally.
+
+## Workspace Layout
+
+### Apps
+
+- [`apps/wolf_3d_gui/`](apps/wolf_3d_gui/README.md) — Flutter app host (desktop/web)
+- [`apps/wolf_3d_cli/`](apps/wolf_3d_cli/README.md) — terminal CLI host
+
+### Packages
+
+- [`packages/wolf_3d_dart/`](packages/wolf_3d_dart/README.md) — core engine/runtime (non-Flutter)
+- [`packages/wolf_3d_flutter/`](packages/wolf_3d_flutter/README.md) — Flutter host and UI integration
+- [`packages/wolf_3d_assets/`](packages/wolf_3d_assets/README.md) — shared packaged asset trees
+
+## Prerequisites
+
+- Dart SDK `^3.11.1`
+- Flutter SDK (for GUI app and Flutter package work)
+
+### Linux native requirements
+
+On Debian/Ubuntu, install:

 `libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev lld`
+
+## Quick Start
+
+From workspace root:
+
+```bash
+dart pub get
+```
+
+Run GUI host:
+
+```bash
+cd apps/wolf_3d_gui
+flutter run
+```
+
+Run CLI host:
+
+```bash
+cd apps/wolf_3d_cli
+dart run bin/main.dart
+```
+
+If game data is not auto-discovered, pass a directory explicitly for CLI:
+
+```bash
+dart run bin/main.dart --data-directory /path/to/game-data
+```
+
+## Development Workflow
+
+Typical contributor loop:
+
+1. Update dependencies in relevant app/package (`dart pub get` or `flutter pub get`).
+2. Run focused tests in the module you changed.
+3. Run static analysis for the same module before submitting changes.
+4. Keep docs in sync when command-line flags, platform support, or public APIs change.
+
+## Testing
+
+Run tests by module (examples):
+
+```bash
+cd packages/wolf_3d_dart && dart test
+cd packages/wolf_3d_flutter && flutter test
+cd apps/wolf_3d_gui && flutter test
+```
+
+## Related Docs
+
+- [`TODO.md`](TODO.md) — high-level project roadmap
+- App/package READMEs listed above for module-specific setup and architecture