From a08af99b6f1a9ce1cc97fef37ada8fa38db7ae4b Mon Sep 17 00:00:00 2001 From: Hans Kokx Date: Tue, 24 Mar 2026 14:53:25 +0100 Subject: [PATCH] feat: Update README files to provide detailed project structure and usage instructions for Wolfenstein 3D workspace Signed-off-by: Hans Kokx --- README.md | 83 +++++++++++++++++++++++++-- apps/wolf_3d_cli/README.md | 91 ++++++++++++++++++++++++++++++ apps/wolf_3d_gui/README.md | 83 +++++++++++++++++++++++++++ packages/wolf_3d_assets/README.md | 52 +++++++++++++++++ packages/wolf_3d_dart/README.md | 70 +++++++++++++++++++++++ packages/wolf_3d_flutter/README.md | 91 ++++++++++++++++++++++-------- 6 files changed, 442 insertions(+), 28 deletions(-) create mode 100644 apps/wolf_3d_cli/README.md create mode 100644 apps/wolf_3d_gui/README.md create mode 100644 packages/wolf_3d_assets/README.md create mode 100644 packages/wolf_3d_dart/README.md diff --git a/README.md b/README.md index d5623e6..d2e95de 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/apps/wolf_3d_cli/README.md b/apps/wolf_3d_cli/README.md new file mode 100644 index 0000000..2491490 --- /dev/null +++ b/apps/wolf_3d_cli/README.md @@ -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) diff --git a/apps/wolf_3d_gui/README.md b/apps/wolf_3d_gui/README.md new file mode 100644 index 0000000..e969026 --- /dev/null +++ b/apps/wolf_3d_gui/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) diff --git a/packages/wolf_3d_assets/README.md b/packages/wolf_3d_assets/README.md new file mode 100644 index 0000000..486ad1e --- /dev/null +++ b/packages/wolf_3d_assets/README.md @@ -0,0 +1,52 @@ +# wolf_3d_assets + +Shared asset package that exposes Wolfenstein 3D game-data trees for workspace apps. + +## What This Package Is + +`wolf_3d_assets` is a content package used by Flutter hosts to bundle known asset directories. + +This package does not expose runtime logic APIs; it exists to provide structured asset roots consumed by hosts and tooling. + +## Current Asset Layout + +Configured asset roots (see `pubspec.yaml`): + +- `assets/retail/` +- `assets/shareware/` +- `assets/sod/shareware/` + +## Setup + +From this directory: + +```bash +flutter pub get +``` + +## How Hosts Consume It + +- Dependent Flutter apps/packages include `wolf_3d_assets` as a workspace dependency. +- Flutter build tooling includes directories listed in this package `pubspec.yaml`. +- Runtime data discovery/selection is handled by host and engine packages. + +## Maintenance Guidelines + +When updating assets: + +1. Preserve directory structure conventions by game/version. +2. Update `pubspec.yaml` asset entries if new top-level roots are introduced. +3. Validate that host apps still discover and load the updated data sets. + +## Verification + +Because this is a content package, verification is integration-focused: + +- run `apps/wolf_3d_gui` and confirm expected data appears, +- run `apps/wolf_3d_cli` with explicit `--data-directory` when testing local trees. + +## Related Modules + +- Core runtime: [`../wolf_3d_dart/README.md`](../wolf_3d_dart/README.md) +- Flutter integration package: [`../wolf_3d_flutter/README.md`](../wolf_3d_flutter/README.md) +- Workspace overview: [`../../README.md`](../../README.md) diff --git a/packages/wolf_3d_dart/README.md b/packages/wolf_3d_dart/README.md new file mode 100644 index 0000000..a88be10 --- /dev/null +++ b/packages/wolf_3d_dart/README.md @@ -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) diff --git a/packages/wolf_3d_flutter/README.md b/packages/wolf_3d_flutter/README.md index 4a260d8..b95b87f 100644 --- a/packages/wolf_3d_flutter/README.md +++ b/packages/wolf_3d_flutter/README.md @@ -1,39 +1,82 @@ - +## What This Package Provides -TODO: Put a short description of the package here that helps potential users -know whether this package might be useful for them. +`wolf_3d_flutter` layers Flutter-specific host concerns on top of `wolf_3d_dart`: -## Features +- high-level engine facade (`Wolf3dFlutterEngine`), +- Flutter input adapter, +- platform audio integration, +- renderer host widgets and runtime mode helpers, +- app/session managers and persistence adapters, +- shader-enabled rendering support. -TODO: List what your package can do. Maybe include images, gifs, or videos. +Primary entrypoint: `lib/wolf_3d_flutter.dart` -## Getting started +## Prerequisites -TODO: List prerequisites and provide or point to information on how to -start using the package. +- Flutter SDK +- Dart SDK `^3.11.1` +- Workspace dependency on `wolf_3d_dart` + +## Setup + +From this directory: + +```bash +flutter pub get +``` ## Usage -TODO: Include short and useful examples for package users. Add longer examples -to `/example` folder. +Typical host initialization pattern: ```dart -const like = 'sample'; +final Wolf3dFlutterEngine engine = await Wolf3dFlutterEngine( + debug: kDebugMode, +).init(); ``` -## Additional information +`init()` handles platform setup, audio init, and configured game-data discovery. -TODO: Tell users more about the package: where to find more information, how to -contribute to the package, how to file issues, what response they can expect -from the package authors, and more. +For full host wiring examples, see: + +- `apps/wolf_3d_gui/lib/main.dart` + +## Package Structure + +- `lib/wolf_3d_flutter.dart` — exports main host facade and public Flutter APIs. +- `lib/renderer/` — renderer host widgets. +- `lib/managers/` — runtime/session/display/persistence managers. +- `lib/audio/` — platform-aware audio backends. +- `shaders/wolf_world.frag` — fragment shader included in package configuration. + +## Development Commands + +From this directory: + +```bash +flutter analyze +flutter test +``` + +## Integration Notes + +- Keep UI/platform concerns in this package or app hosts, not in `wolf_3d_dart`. +- Use exported APIs from `lib/wolf_3d_flutter.dart` rather than importing private internals from `lib/src` in dependencies. +- Shader path is declared in this package `pubspec.yaml` and must stay synchronized with renderer usage. + +## Troubleshooting + +- **No discovered game data**: confirm configured/persisted data directory paths are valid. +- **Desktop behavior mismatch**: verify desktop windowing and audio dependencies are available on the target OS. +- **Render issues after shader changes**: confirm shader path and package config are still aligned. + +## Related Modules + +- Core runtime package: [`../wolf_3d_dart/README.md`](../wolf_3d_dart/README.md) +- GUI host app: [`../../apps/wolf_3d_gui/README.md`](../../apps/wolf_3d_gui/README.md) +- Shared assets package: [`../wolf_3d_assets/README.md`](../wolf_3d_assets/README.md) +- Workspace overview: [`../../README.md`](../../README.md)