wolf_dart/packages/wolf_3d_flutter/README.md

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:

flutter pub get

Usage

Typical host initialization pattern:

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:

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:

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
• GUI host app: ../../apps/wolf_3d_gui/README.md
• Shared assets package: ../wolf_3d_assets/README.md
• Workspace overview: ../../README.md