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>
This commit is contained in:
@@ -1,11 +1,86 @@
|
|||||||
# wolf_dart
|
# 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`
|
`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
|
||||||
|
|||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -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)
|
||||||
@@ -1,39 +1,82 @@
|
|||||||
<!--
|
# wolf_3d_flutter
|
||||||
This README describes the package. If you publish this package to pub.dev,
|
|
||||||
this README's contents appear on the landing page for your package.
|
|
||||||
|
|
||||||
For information about how to write a good package README, see the guide for
|
Flutter integration package for the shared Wolfenstein 3D runtime.
|
||||||
[writing package pages](https://dart.dev/tools/pub/writing-package-pages).
|
|
||||||
|
|
||||||
For general information about developing packages, see the Dart guide for
|
## What This Package Provides
|
||||||
[creating packages](https://dart.dev/guides/libraries/create-packages)
|
|
||||||
and the Flutter guide for
|
|
||||||
[developing packages and plugins](https://flutter.dev/to/develop-packages).
|
|
||||||
-->
|
|
||||||
|
|
||||||
TODO: Put a short description of the package here that helps potential users
|
`wolf_3d_flutter` layers Flutter-specific host concerns on top of `wolf_3d_dart`:
|
||||||
know whether this package might be useful for them.
|
|
||||||
|
|
||||||
## 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
|
- Flutter SDK
|
||||||
start using the package.
|
- Dart SDK `^3.11.1`
|
||||||
|
- Workspace dependency on `wolf_3d_dart`
|
||||||
|
|
||||||
|
## Setup
|
||||||
|
|
||||||
|
From this directory:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
flutter pub get
|
||||||
|
```
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
TODO: Include short and useful examples for package users. Add longer examples
|
Typical host initialization pattern:
|
||||||
to `/example` folder.
|
|
||||||
|
|
||||||
```dart
|
```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
|
For full host wiring examples, see:
|
||||||
contribute to the package, how to file issues, what response they can expect
|
|
||||||
from the package authors, and more.
|
- `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)
|
||||||
|
|||||||
Reference in New Issue
Block a user