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

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:

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