118 lines
3.7 KiB
Markdown
118 lines
3.7 KiB
Markdown
# wolf_3d_flutter
|
|
|
|
Flutter integration package for the shared Wolfenstein 3D runtime.
|
|
|
|
## What This Package Provides
|
|
|
|
`wolf_3d_flutter` layers Flutter-specific host concerns on top of `wolf_3d_dart`:
|
|
|
|
- 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.
|
|
|
|
Primary entrypoint: `lib/wolf_3d_flutter.dart`
|
|
|
|
## Prerequisites
|
|
|
|
- Flutter SDK
|
|
- Dart SDK `^3.11.1`
|
|
- Workspace dependency on `wolf_3d_dart`
|
|
|
|
## Setup
|
|
|
|
From this directory:
|
|
|
|
```bash
|
|
flutter pub get
|
|
```
|
|
|
|
## Usage
|
|
|
|
Typical host initialization pattern:
|
|
|
|
```dart
|
|
final Wolf3dFlutterEngine engine = await Wolf3dFlutterEngine(
|
|
debug: kDebugMode,
|
|
).init();
|
|
```
|
|
|
|
`init()` handles platform setup, audio init, configured external discovery, and
|
|
optional seeded game injection.
|
|
|
|
To load packaged game data from `wolf_3d_assets`, use
|
|
`Wolf3dFlutterEngine.loadGameDataFromAssets(...)` and pass the result via
|
|
`seededGames`:
|
|
|
|
```dart
|
|
final retail = await Wolf3dFlutterEngine.loadGameDataFromAssets(
|
|
version: GameVersion.retail,
|
|
packageName: 'wolf_3d_assets',
|
|
assetDirectory: 'assets/retail',
|
|
);
|
|
|
|
final shareware = await Wolf3dFlutterEngine.loadGameDataFromAssets(
|
|
version: GameVersion.shareware,
|
|
packageName: 'wolf_3d_assets',
|
|
assetDirectory: 'assets/shareware',
|
|
);
|
|
|
|
final Wolf3dFlutterEngine engine = await Wolf3dFlutterEngine(
|
|
debug: kDebugMode,
|
|
).init(seededGames: [retail, shareware]);
|
|
```
|
|
|
|
The facade itself lives in `lib/engine/wolf3d_flutter_engine.dart` and is re-exported
|
|
through the package barrel at `lib/wolf_3d_flutter.dart`. External consumers
|
|
should keep importing the barrel unless they have a specific reason to target
|
|
the engine library directly.
|
|
|
|
The same pattern applies to the Flutter input adapter and the desktop
|
|
persistence adapters: they now live in focused subdirectories and are
|
|
re-exported through `lib/wolf_3d_flutter.dart`.
|
|
|
|
For full host wiring examples, see:
|
|
|
|
- `apps/wolf_3d_gui/lib/main.dart`
|
|
|
|
## Package Structure
|
|
|
|
- `lib/wolf_3d_flutter.dart` — barrel export for the public Flutter package surface.
|
|
- `lib/engine/wolf3d_flutter_engine.dart` — high-level engine facade and discovery bootstrap.
|
|
- `lib/input/` — Flutter-specific input adapters.
|
|
- `lib/persistence/` — desktop persistence adapters for saves and renderer settings.
|
|
- `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)
|