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,70 @@
+# wolf_3d_dart
+
+Core non-Flutter Wolfenstein 3D runtime package used by both CLI and Flutter hosts.
+
+## What This Package Provides
+
+`wolf_3d_dart` contains the platform-neutral simulation/runtime surface:
+
+- engine and session lifecycle,
+- game-data loading and data types,
+- renderer backends and frame-buffer abstractions,
+- menu state/navigation models,
+- input/audio host abstractions,
+- entity and gameplay logic.
+
+## Public Library Surfaces
+
+Primary entry libraries in `lib/`:
+
+- `wolf_3d_engine.dart` — engine exports and runtime contracts.
+- `wolf_3d_data.dart` / `wolf_3d_data_types.dart` — game-data discovery and DTOs.
+- `wolf_3d_renderer.dart` — rendering/backends integration points.
+- `wolf_3d_audio.dart` — audio interfaces and host backends.
+- `wolf_3d_input.dart` — input abstractions.
+- `wolf_3d_menu.dart` — menu models/managers.
+- `wolf_3d_host.dart` — host-level glue contracts.
+
+Implementation details live under `lib/src/`.
+
+## Setup
+
+From this directory:
+
+```bash
+dart pub get
+```
+
+## Development Commands
+
+From this directory:
+
+```bash
+dart analyze
+dart test
+```
+
+## Architecture Notes
+
+- Hosts own platform concerns (windowing, lifecycle, platform input wiring).
+- This package owns deterministic engine/frame progression and shared game logic.
+- Frame-buffer sizing is controlled by hosts through engine APIs.
+- Rendering code is maintained under `lib/src/rendering/`.
+
+## Non-Goals
+
+- Flutter widgets/screens are not part of this package.
+- Bundled app assets are handled by `wolf_3d_assets`.
+
+## Troubleshooting
+
+- **Parity regressions**: run targeted tests under `test/engine/` and `test/entities/`.
+- **Host integration issues**: verify host packages/apps are using exported surfaces from `lib/` rather than private `src/` paths.
+
+## Related Modules
+
+- Flutter integration layer: [`../wolf_3d_flutter/README.md`](../wolf_3d_flutter/README.md)
+- Shared packaged assets: [`../wolf_3d_assets/README.md`](../wolf_3d_assets/README.md)
+- CLI host app: [`../../apps/wolf_3d_cli/README.md`](../../apps/wolf_3d_cli/README.md)
+- GUI host app: [`../../apps/wolf_3d_gui/README.md`](../../apps/wolf_3d_gui/README.md)
+- Workspace overview: [`../../README.md`](../../README.md)