# 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, and configured game-data discovery.

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)