hans/wolf_dart
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Update README files to provide detailed project structure and usage instructions for Wolfenstein 3D workspace

Browse Source 
Signed-off-by: Hans Kokx <hans.d.kokx@gmail.com>
This commit is contained in:
Hans Kokx
2026-03-24 14:53:25 +01:00
parent 8a9be477e4
commit a08af99b6f
6 changed files with 442 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+79 -4
View File
@@ -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
apps/wolf_3d_cli/README.md
+91
View File
@@ -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)
apps/wolf_3d_gui/README.md
+83
View File
@@ -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)
packages/wolf_3d_assets/README.md
+52
View File
@@ -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)
packages/wolf_3d_dart/README.md
+70
View File
@@ -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)
packages/wolf_3d_flutter/README.md
+67 -24
View File
@@ -1,39 +1,82 @@
<!--
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.
# wolf_3d_flutter
For information about how to write a good package README, see the guide for
[writing package pages](https://dart.dev/tools/pub/writing-package-pages).
Flutter integration package for the shared Wolfenstein 3D runtime.
For general information about developing packages, see the Dart guide for
[creating packages](https://dart.dev/guides/libraries/create-packages)
and the Flutter guide for
[developing packages and plugins](https://flutter.dev/to/develop-packages).
-->
## 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)