### Installation Configuration

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Configures the installation process, setting the default installation prefix to a bundle directory and ensuring a clean build bundle each time. This prepares the application for deployment.

```cmake
set(BUILD_BUNDLE_DIR "${PROJECT_BINARY_DIR}/bundle")
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

install(CODE "
  file(REMOVE_RECURSE \"${BUILD_BUNDLE_DIR}/\")
  " COMPONENT Runtime)

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}/lib")
```

--------------------------------

### Installing Application Target and Data

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Installs the application executable, ICU data, and Flutter library to their respective destinations within the installation bundle. This makes the application ready for distribution.

```cmake
install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)
```

--------------------------------

### Full Example: Animated Character Viewer

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

This example demonstrates setting up the controller, loading a model, controlling animations, switching textures, rotating the model, and manipulating the camera. It includes UI elements for user interaction.

```dart
import 'package:flutter/material.dart';
import 'package:flutter_3d_controller/flutter_3d_controller.dart';

class CharacterViewerPage extends StatefulWidget {
  const CharacterViewerPage({super.key});
  @override
  State<CharacterViewerPage> createState() => _CharacterViewerPageState();
}

class _CharacterViewerPageState extends State<CharacterViewerPage> {
  final Flutter3DController _controller = Flutter3DController();
  List<String> _animations = [];
  List<String> _textures = [];
  bool _isLoaded = false;

  @override
  void initState() {
    super.initState();
    _controller.onModelLoaded.addListener(() async {
      if (_controller.onModelLoaded.value) {
        setState(() => _isLoaded = true);
        _animations = await _controller.getAvailableAnimations();
        _textures   = await _controller.getAvailableTextures();
        setState(() {});
        _controller.playAnimation(); // auto-play on load
      }
    });
  }

  @override
  void dispose() {
    _controller.onModelLoaded.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('3D Character Viewer')),
      body: Column(
        children: [
          Expanded(
            child: Flutter3DViewer(
              src: 'assets/business_man.glb',
              controller: _controller,
              activeGestureInterceptor: true,
              progressBarColor: Colors.deepPurple,
              onLoad: (_) => debugPrint('Ready'),
              onError: (e) => debugPrint('Error: $e'),
            ),
          ),
          if (_isLoaded) ...[
            // Animation controls
            Row(
              mainAxisAlignment: MainAxisAlignment.spaceEvenly,
              children: [
                IconButton(
                  icon: const Icon(Icons.play_arrow),
                  onPressed: () => _controller.playAnimation(),
                ),
                IconButton(
                  icon: const Icon(Icons.pause),
                  onPressed: () => _controller.pauseAnimation(),
                ),
                IconButton(
                  icon: const Icon(Icons.replay),
                  onPressed: () => _controller.resetAnimation(),
                ),
                IconButton(
                  icon: const Icon(Icons.stop),
                  onPressed: () => _controller.stopAnimation(),
                ),
              ],
            ),
            // Rotation controls
            Row(
              mainAxisAlignment: MainAxisAlignment.spaceEvenly,
              children: [
                ElevatedButton(
                  onPressed: () => _controller.startRotation(rotationSpeed: 30),
                  child: const Text('Rotate'),
                ),
                ElevatedButton(
                  onPressed: () => _controller.pauseRotation(),
                  child: const Text('Pause Rot'),
                ),
                ElevatedButton(
                  onPressed: () => _controller.stopRotation(),
                  child: const Text('Stop Rot'),
                ),
              ],
            ),
            // Named animation picker
            if (_animations.isNotEmpty)
              SizedBox(
                height: 40,
                child: ListView.separated(
                  scrollDirection: Axis.horizontal,
                  padding: const EdgeInsets.symmetric(horizontal: 12),
                  itemCount: _animations.length,
                  separatorBuilder: (_, __) => const SizedBox(width: 8),
                  itemBuilder: (_, i) => ActionChip(
                    label: Text(_animations[i]),
                    onPressed: () => _controller.playAnimation(
                      animationName: _animations[i],
                      loopCount: 0,
                    ),
                  ),
                ),
              ),
            // Camera preset buttons
            Row(
              mainAxisAlignment: MainAxisAlignment.spaceEvenly,
              children: [
                TextButton(
                  onPressed: () => _controller.setCameraOrbit(20, 20, 5),
                  child: const Text('Front'),
                ),
                TextButton(
                  onPressed: () => _controller.setCameraOrbit(90, 75, 105),
                  child: const Text('Side'),
                ),
                TextButton(
                  onPressed: () => _controller.resetCameraOrbit(),
                  child: const Text('Reset Cam'),
                ),
              ],
            ),
          ],
        ],
      ),
    );
  }
}
```

--------------------------------

### Installing Bundled Libraries

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Installs any bundled libraries required by plugins to the library directory within the installation bundle. This ensures plugins have access to their dependencies.

```cmake
foreach(bundled_library ${PLUGIN_BUNDLED_LIBRARIES})
  install(FILES "${bundled_library}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endforeach(bundled_library)
```

--------------------------------

### Installation Configuration for Runtime

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/CMakeLists.txt

Configures installation rules to place the application executable, ICU data, Flutter library, and bundled plugin libraries next to the executable for in-place execution.

```cmake
set(BUILD_BUNDLE_DIR "$<TARGET_FILE_DIR:${BINARY_NAME}>")
set(CMAKE_VS_INCLUDE_INSTALL_TO_DEFAULT_BUILD 1)
if(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
  set(CMAKE_INSTALL_PREFIX "${BUILD_BUNDLE_DIR}" CACHE PATH "..." FORCE)
endif()

set(INSTALL_BUNDLE_DATA_DIR "${CMAKE_INSTALL_PREFIX}/data")
set(INSTALL_BUNDLE_LIB_DIR "${CMAKE_INSTALL_PREFIX}")

install(TARGETS ${BINARY_NAME} RUNTIME DESTINATION "${CMAKE_INSTALL_PREFIX}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_ICU_DATA_FILE}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  COMPONENT Runtime)

install(FILES "${FLUTTER_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
  COMPONENT Runtime)

if(PLUGIN_BUNDLED_LIBRARIES)
  install(FILES "${PLUGIN_BUNDLED_LIBRARIES}"
    DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### AOT Library Installation

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/CMakeLists.txt

Installs the Ahead-Of-Time (AOT) compiled library for Profile and Release build configurations.

```cmake
install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_DATA_DIR}"
  CONFIGURATIONS Profile;Release
  COMPONENT Runtime)
```

--------------------------------

### Asset Directory Installation

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/CMakeLists.txt

Installs the Flutter assets directory by first removing any existing directory and then copying the new assets. This ensures assets are up-to-date.

```cmake
set(FLUTTER_ASSET_DIR_NAME "flutter_assets")
install(CODE "
  file(REMOVE_RECURSE \"${INSTALL_BUNDLE_DATA_DIR}/${FLUTTER_ASSET_DIR_NAME}\")
  " COMPONENT Runtime)
install(DIRECTORY "${PROJECT_BUILD_DIR}/${FLUTTER_ASSET_DIR_NAME}"
  DESTINATION "${INSTALL_BUNDLE_DATA_DIR}" COMPONENT Runtime)
```

--------------------------------

### Project and CMake Version Setup

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/CMakeLists.txt

Sets the minimum required CMake version and names the project. It also explicitly opts into modern CMake behaviors to avoid warnings.

```cmake
cmake_minimum_required(VERSION 3.14)
project(example LANGUAGES CXX)
set(BINARY_NAME "example")
cmake_policy(SET CMP0063 NEW)
```

--------------------------------

### Project and Minimum CMake Version

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Sets the minimum required CMake version and names the project. This is a standard starting point for CMake projects.

```cmake
cmake_minimum_required(VERSION 3.10)
project(runner LANGUAGES CXX)
```

--------------------------------

### controller.playAnimation

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Starts playback of a model animation. Without arguments it plays the first available animation infinitely. Pass `animationName` to select a specific clip, and `loopCount` to limit repetitions (0 = infinite).

```APIDOC
## controller.playAnimation — Play Animation

Starts playback of a model animation. Without arguments it plays the first available animation infinitely. Pass `animationName` to select a specific clip, and `loopCount` to limit repetitions (0 = infinite).

```dart
// Play first animation, loop forever
controller.playAnimation();

// Play a named animation once
controller.playAnimation(animationName: 'Walk', loopCount: 1);

// Play a named animation 3 times then stop
controller.playAnimation(animationName: 'Jump', loopCount: 3);

// Discover available animation names first, then play
final List<String> animations = await controller.getAvailableAnimations();
// animations = ['Idle', 'Walk', 'Run', 'Jump']
if (animations.isNotEmpty) {
  controller.playAnimation(animationName: animations.first, loopCount: 2);
}
```
```

--------------------------------

### Get and Select Available Textures

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Fetches a list of available material variant names and allows the user to select one to apply to the model. Requires the context for showing the modal bottom sheet.

```dart
ElevatedButton(
  child: const Text('Pick Texture'),
  onPressed: () async {
    final List<String> textures = 
        await controller.getAvailableTextures();
    debugPrint('Variants: $textures');

    final String? chosen = await showModalBottomSheet<String>(
      context: context,
      builder: (_) => ListView(
        children: textures
            .map((name) => ListTile(
                  title: Text(name),
                  onTap: () => Navigator.pop(context, name),
                ))
            .toList(),
      ),
    );
    if (chosen != null) {
      controller.setTexture(textureName: chosen);
    }
  },
);
```

--------------------------------

### Setting Installation RPATH

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Configures the RPATH to load bundled libraries from the 'lib/' directory relative to the binary. This is important for ensuring the application can find its dynamic libraries at runtime.

```cmake
set(CMAKE_INSTALL_RPATH "$ORIGIN/lib")
```

--------------------------------

### Install AOT Library Conditionally in CMake

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Installs the AOT library to the runtime destination only when the build type is not Debug. Ensure the AOT_LIBRARY variable is defined.

```cmake
if(NOT CMAKE_BUILD_TYPE MATCHES "Debug")
  install(FILES "${AOT_LIBRARY}" DESTINATION "${INSTALL_BUNDLE_LIB_DIR}"
    COMPONENT Runtime)
endif()
```

--------------------------------

### Control Model Auto-Rotation

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Starts, pauses, or stops the continuous auto-rotation of the 3D model. Rotation speed can be specified when starting.

```dart
// Default speed (10 deg/s)
controller.startRotation();

// Fast spin (60 deg/s)
controller.startRotation(rotationSpeed: 60);

// Slow drift (5 deg/s)
controller.startRotation(rotationSpeed: 5);
```

```dart
controller.pauseRotation();
// Model is stationary; call startRotation() again to resume
```

```dart
controller.stopRotation();
// Model snaps back to its default facing direction
```

--------------------------------

### Play Animation

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Starts or resumes animation playback. Specify an animation by name and optionally limit repetitions. If no arguments are provided, it plays the first animation infinitely.

```dart
// Play first animation, loop forever
controller.playAnimation();
```

```dart
// Play a named animation once
controller.playAnimation(animationName: 'Walk', loopCount: 1);
```

```dart
// Play a named animation 3 times then stop
controller.playAnimation(animationName: 'Jump', loopCount: 3);
```

```dart
// Discover available animation names first, then play
final List<String> animations = await controller.getAvailableAnimations();
// animations = ['Idle', 'Walk', 'Run', 'Jump']
if (animations.isNotEmpty) {
  controller.playAnimation(animationName: animations.first, loopCount: 2);
}
```

--------------------------------

### Render OBJ Models with Flutter3DViewer.obj

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Use Flutter3DViewer.obj for rendering OBJ models with a pure-Dart renderer. Configure initial scale, camera position, and load callbacks. Supports asset paths or remote URLs starting with http(s)://.

```dart
Flutter3DViewer.obj(
  // Asset path or remote URL ending in .obj
  src: 'assets/flutter_dash.obj',
  // src: 'https://example.com/models/flutter_dash.obj',

  scale: 5,      // initial uniform scale
  cameraX: 0,    // camera target X offset
  cameraY: 0,    // camera target Y offset
  cameraZ: 10,   // camera distance from origin

  onProgress: (double progress) {
    debugPrint('OBJ loading: ${(progress * 100).toStringAsFixed(0)}%');
  },
  onLoad: (String modelAddress) {
    debugPrint('OBJ loaded: $modelAddress');
  },
  onError: (String error) {
    debugPrint('OBJ failed: $error');
  },
)
```

--------------------------------

### controller.stopRotation

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Stops the auto-rotation of the model and resets its orientation to the default starting position.

```APIDOC
## controller.stopRotation — Stop Auto-Rotation

Stops auto-rotation and resets the turntable back to its initial orientation (0°).

### Usage Example
```dart
controller.stopRotation();
// Model snaps back to its default facing direction
```
```

--------------------------------

### Reset Animation

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Stops the current animation, resets the playback to the first frame (frame zero), and immediately begins playing from the start. This is useful for restarting an animation from its beginning.

```dart
IconButton(
  icon: const Icon(Icons.replay),
  onPressed: () {
    controller.resetAnimation();
  },
);
```

--------------------------------

### Get Available Animations

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Retrieves a list of all animation clip names embedded within the loaded 3D model. This is essential for dynamically populating UI elements like pickers before selecting an animation to play.

```dart
ElevatedButton(
  child: const Text('Pick Animation'),
  onPressed: () async {
    final List<String> animations = 
        await controller.getAvailableAnimations();
    // e.g. ['Idle', 'Walk', 'Run', 'Attack']
    debugPrint('Found ${animations.length} animations: $animations');

    if (animations.isNotEmpty) {
      // Show a picker and play the selection
      final String? chosen = await showModalBottomSheet<String>(
        context: context,
        builder: (_) => ListView(
          children: animations
              .map((name) => ListTile(
                    title: Text(name),
                    onTap: () => Navigator.pop(context, name),
                  ))
              .toList(),
        ),
      );
      if (chosen != null) {
        controller.playAnimation(animationName: chosen);
      }
    }
  },
);
```

--------------------------------

### Set Flutter library and ICU data for parent scope

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/flutter/CMakeLists.txt

Exports the Flutter library path and the ICU data file path to the parent CMake scope, making them available for installation and other build steps.

```cmake
set(FLUTTER_LIBRARY ${FLUTTER_LIBRARY} PARENT_SCOPE)
set(FLUTTER_ICU_DATA_FILE "${EPHEMERAL_DIR}/icudtl.dat" PARENT_SCOPE)
set(PROJECT_BUILD_DIR "${PROJECT_DIR}/build/" PARENT_SCOPE)
set(AOT_LIBRARY "${PROJECT_DIR}/build/windows/app.so" PARENT_SCOPE)
```

--------------------------------

### Find System Dependencies

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/flutter/CMakeLists.txt

Uses PkgConfig to find and check for required system libraries like GTK, GLIB, and GIO.

```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
pkg_check_modules(GLIB REQUIRED IMPORTED_TARGET glib-2.0)
pkg_check_modules(GIO REQUIRED IMPORTED_TARGET gio-2.0)
```

--------------------------------

### Add Dependency Libraries and Include Directories

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/runner/CMakeLists.txt

Links necessary libraries (flutter, flutter_wrapper_app, dwmapi.lib) and adds the source directory to include paths. Add any other application-specific dependencies here.

```cmake
# Add dependency libraries and include directories. Add any application-specific
# dependencies here.
target_link_libraries(${BINARY_NAME} PRIVATE flutter flutter_wrapper_app)
target_link_libraries(${BINARY_NAME} PRIVATE "dwmapi.lib")
target_include_directories(${BINARY_NAME} PRIVATE "${CMAKE_SOURCE_DIR}")
```

--------------------------------

### Finding System Dependencies

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Finds and checks for the PkgConfig and GTK+ 3.0 libraries. These are system-level dependencies required for the application.

```cmake
find_package(PkgConfig REQUIRED)
pkg_check_modules(GTK REQUIRED IMPORTED_TARGET gtk+-3.0)
```

--------------------------------

### Apply Standard Build Settings

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/runner/CMakeLists.txt

Applies a standard set of build settings to the application target. This can be removed if custom build settings are required.

```cmake
# Apply the standard set of build settings. This can be removed for applications
# that need different build settings.
apply_standard_settings(${BINARY_NAME})
```

--------------------------------

### Configure macOS App Sandbox for Outgoing Connections

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/README.md

For macOS, enable the `Outgoing Connections (Client)` option in Xcode under `Runner > Signing & Capabilities` to load 3D models.

```text
Outgoing Connections (Client)
```

--------------------------------

### Configure Flutter Library Interface

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/flutter/CMakeLists.txt

Sets up an interface library for Flutter, including include directories and linking against system libraries and the Flutter library itself.

```cmake
add_library(flutter INTERFACE)
target_include_directories(flutter INTERFACE
  "${EPHEMERAL_DIR}"
)
target_link_libraries(flutter INTERFACE "${FLUTTER_LIBRARY}")
target_link_libraries(flutter INTERFACE
  PkgConfig::GTK
  PkgConfig::GLIB
  PkgConfig::GIO
)
add_dependencies(flutter flutter_assemble)
```

--------------------------------

### Set Minimum SDK Version for Android

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Configure the minimum Android SDK version in the app/build.gradle file. Version 21 is recommended.

```gradle
defaultConfig {
    minSdkVersion 21
}
```

--------------------------------

### Linking Dependencies

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Links the application target with necessary libraries, including 'flutter' and PkgConfig::GTK. This ensures all required components are available at link time.

```cmake
target_link_libraries(${BINARY_NAME} PRIVATE flutter)
target_link_libraries(${BINARY_NAME} PRIVATE PkgConfig::GTK)
```

--------------------------------

### Initialize Flutter3DController

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Instantiate the controller. It's recommended to create one instance per Flutter3DViewer and pass it to the widget. Ensure methods are called only after the model is fully loaded.

```dart
final Flutter3DController controller = Flutter3DController();
```

--------------------------------

### Include generated configuration

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/flutter/CMakeLists.txt

Includes the generated configuration file, which provides build-specific settings from the Flutter tool.

```cmake
include(${EPHEMERAL_DIR}/generated_config.cmake)
```

--------------------------------

### Exception Handling

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Details on how to handle exceptions thrown by the controller methods, including specific exception types and a safe pattern for method calls.

```APIDOC
## Exception Handling

All controller methods throw typed exceptions from the `flutter_3d_controller` exception hierarchy when called in an invalid state. Guard calls with try/catch in production code.

### Exception Types
- `Flutter3dControllerLoadingException`: Thrown when a method is called before the model is ready.
- `Flutter3dControllerFormatException`: Thrown when an incorrect model format is used for a given API.
- `Flutter3dControllerException`: A catch-all for any other package-specific exceptions.

### Usage Example with try-catch
```dart
try {
  await controller.playAnimation();
} on Flutter3dControllerLoadingException catch (e) {
  debugPrint('Model not ready: $e');
  // Output: Flutter3DControllerLoadingException: The 3D model is not loaded yet …
} on Flutter3dControllerFormatException catch (e) {
  debugPrint('Format error: $e');
  // Output: Flutter3DControllerFormatException: Wrong model format has been used.
} on Flutter3dControllerException catch (e) {
  // Catch-all for any other package exception
  debugPrint('Controller error: $e');
}
```

### Safe Pattern using `onModelLoaded` guard
```dart
void safePlay() {
  if (controller.onModelLoaded.value) {
    controller.playAnimation();
  } else {
    debugPrint('Skipping: model not yet loaded');
  }
}
```
```

--------------------------------

### Include Model Viewer JavaScript for Web

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Add the model_viewer.min.js script to the <head> section of your web/index.html file to enable 3D model rendering on the web.

```html
<script type="module"
  src="./assets/packages/flutter_3d_controller/assets/model_viewer.min.js"
  defer></script>
```

--------------------------------

### Handle Controller Exceptions

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Demonstrates how to catch specific exceptions thrown by controller methods when the model is not ready or if there's a format error. Includes a safe pattern using an onModelLoaded guard.

```dart
// Flutter3dControllerLoadingException — called before model is ready
// Flutter3dControllerFormatException  — wrong model format for a given API

try {
  await controller.playAnimation();
} on Flutter3dControllerLoadingException catch (e) {
  debugPrint('Model not ready: $e');
  // Output: Flutter3DControllerLoadingException: The 3D model is not loaded yet …
} on Flutter3dControllerFormatException catch (e) {
  debugPrint('Format error: $e');
  // Output: Flutter3DControllerFormatException: Wrong model format has been used.
} on Flutter3dControllerException catch (e) {
  // Catch-all for any other package exception
  debugPrint('Controller error: $e');
}

// Safe pattern using onModelLoaded guard
void safePlay() {
  if (controller.onModelLoaded.value) {
    controller.playAnimation();
  } else {
    debugPrint('Skipping: model not yet loaded');
  }
}
```

--------------------------------

### Load Model Viewer JavaScript in Web Index.html

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/README.md

Modify the `<head>` tag of your `web/index.html` to include the `model_viewer.min.js` script.

```html
<head>
  <!-- Other stuff -->
    <script type="module" src="./assets/packages/flutter_3d_controller/assets/model_viewer.min.js" defer></script>
</head>
```

--------------------------------

### controller.startRotation

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Initiates continuous auto-rotation of the 3D model around its vertical axis. The speed of rotation can be customized.

```APIDOC
## controller.startRotation — Start Auto-Rotation

Starts continuous auto-rotation of the model around its vertical axis. The `rotationSpeed` parameter sets degrees per second (default: 10).

### Parameters
#### Query Parameters
- **rotationSpeed** (double) - Optional - The speed of rotation in degrees per second. Defaults to 10.

### Usage Example
```dart
// Default speed (10 deg/s)
controller.startRotation();

// Fast spin (60 deg/s)
controller.startRotation(rotationSpeed: 60);
```
```

--------------------------------

### Create static library for Flutter wrapper plugin

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/flutter/CMakeLists.txt

Builds a static library for the Flutter C++ wrapper intended for use by plugins. It includes core and plugin-specific sources and links against the Flutter library.

```cmake
add_library(flutter_wrapper_plugin STATIC
  ${CPP_WRAPPER_SOURCES_CORE}
  ${CPP_WRAPPER_SOURCES_PLUGIN}
)
apply_standard_settings(flutter_wrapper_plugin)
set_target_properties(flutter_wrapper_plugin PROPERTIES
  POSITION_INDEPENDENT_CODE ON)
set_target_properties(flutter_wrapper_plugin PROPERTIES
  CXX_VISIBILITY_PRESET hidden)
target_link_libraries(flutter_wrapper_plugin PUBLIC flutter)
target_include_directories(flutter_wrapper_plugin PUBLIC
  "${WRAPPER_ROOT}/include"
)
add_dependencies(flutter_wrapper_plugin flutter_assemble)
```

--------------------------------

### Create static library for Flutter wrapper application

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/flutter/CMakeLists.txt

Builds a static library for the Flutter C++ wrapper intended for the application runner. It includes core and application-specific sources and links against the Flutter library.

```cmake
add_library(flutter_wrapper_app STATIC
  ${CPP_WRAPPER_SOURCES_CORE}
  ${CPP_WRAPPER_SOURCES_APP}
)
apply_standard_settings(flutter_wrapper_app)
target_link_libraries(flutter_wrapper_app PUBLIC flutter)
target_include_directories(flutter_wrapper_app PUBLIC
  "${WRAPPER_ROOT}/include"
)
add_dependencies(flutter_wrapper_app flutter_assemble)
```

--------------------------------

### Setting Runtime Output Directory

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Configures the runtime output directory for the executable to a subdirectory within the build directory. This prevents accidental execution of unbundled copies.

```cmake
set_target_properties(${BINARY_NAME}
  PROPERTIES
    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/intermediates_do_not_run"
)
```

--------------------------------

### Profile Build Mode Settings

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/CMakeLists.txt

Configures linker and compiler flags for the Profile build mode, typically inheriting settings from the Release mode.

```cmake
set(CMAKE_EXE_LINKER_FLAGS_PROFILE "${CMAKE_EXE_LINKER_FLAGS_RELEASE}")
set(CMAKE_SHARED_LINKER_FLAGS_PROFILE "${CMAKE_SHARED_LINKER_FLAGS_RELEASE}")
set(CMAKE_C_FLAGS_PROFILE "${CMAKE_C_FLAGS_RELEASE}")
set(CMAKE_CXX_FLAGS_PROFILE "${CMAKE_CXX_FLAGS_RELEASE}")
```

--------------------------------

### Unicode Support

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/CMakeLists.txt

Enables Unicode support for all projects by defining specific preprocessor macros.

```cmake
add_definitions(-DUNICODE -D_UNICODE)
```

--------------------------------

### Configure Build Types (Multi-config Generators)

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/CMakeLists.txt

Defines the available build configurations (Debug, Profile, Release) for multi-configuration CMake generators.

```cmake
get_property(IS_MULTICONFIG GLOBAL PROPERTY GENERATOR_IS_MULTI_CONFIG)
if(IS_MULTICONFIG)
  set(CMAKE_CONFIGURATION_TYPES "Debug;Profile;Release"
    CACHE STRING "" FORCE)
else()
  if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
    set(CMAKE_BUILD_TYPE "Debug" CACHE
      STRING "Flutter build mode" FORCE)
    set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
      "Debug" "Profile" "Release")
  endif()
endif()
```

--------------------------------

### Defining Application Target

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Defines the main executable target for the application, listing its source files. Any new source files should be added here.

```cmake
add_executable(${BINARY_NAME}
  "main.cc"
  "my_application.cc"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
)
```

--------------------------------

### Add flutter_3d_controller Dependency

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/README.md

Add the flutter_3d_controller package to your project's `pubspec.yaml` file.

```yaml
dependencies:
  flutter_3d_controller: ^2.3.0
```

--------------------------------

### Flutter3DController Initialization

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Instantiate Flutter3DController and monitor its load state using onModelLoaded. Ensure all controller methods are called only after the model is fully loaded.

```APIDOC
## Flutter3DController

`Flutter3DController` is the bridge between Dart code and the underlying `model-viewer` instance. Create one instance per `Flutter3DViewer`, pass it to the widget, and call its methods only after `onModelLoaded` becomes `true`. Calling any method before the model is fully loaded throws `Flutter3dControllerLoadingException`.

```dart
final Flutter3DController controller = Flutter3DController();

// Monitor load state
controller.onModelLoaded.addListener(() {
  if (controller.onModelLoaded.value) {
    debugPrint('Ready for programmatic control');
  }
});
```
```

--------------------------------

### Setting Executable and Application IDs

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Defines the name of the executable and the unique application identifier. These are crucial for the application's identity and deployment.

```cmake
set(BINARY_NAME "example")
set(APPLICATION_ID "com.mrdavari.example")
```

--------------------------------

### Define C++ wrapper plugin sources

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/flutter/CMakeLists.txt

Lists the C++ source files specific to the Flutter plugin wrapper.

```cmake
list(APPEND CPP_WRAPPER_SOURCES_PLUGIN
  "plugin_registrar.cc"
)
list(TRANSFORM CPP_WRAPPER_SOURCES_PLUGIN PREPEND "${WRAPPER_ROOT}/")
```

--------------------------------

### Applying Standard Compilation Settings

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Defines a function to apply common compilation settings like C++ standard, warning options, optimization levels, and debug definitions. This promotes consistency across targets.

```cmake
function(APPLY_STANDARD_SETTINGS TARGET)
  target_compile_features(${TARGET} PUBLIC cxx_std_14)
  target_compile_options(${TARGET} PRIVATE -Wall -Werror)
  target_compile_options(${TARGET} PRIVATE "$<$<NOT:$<CONFIG:Debug>>:-O3>")
  target_compile_definitions(${TARGET} PRIVATE "$<$<NOT:$<CONFIG:Debug>>:NDEBUG>")
endfunction()
```

--------------------------------

### Enable Embedded Views Preview on iOS

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/README.md

Opt into the embedded views preview by adding `io.flutter.embedded_views_preview` with a value of `YES` to your `ios/Runner/Info.plist` file.

```xml
<key>io.flutter.embedded_views_preview</key>
<true/>
```

--------------------------------

### Load OBJ Models with Flutter3DViewer.obj

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/README.md

Use the Flutter3DViewer.obj constructor to load and display OBJ 3D models. Configure initial scale, camera position, and handle loading progress and errors.

```dart
//The 3D viewer widget for obj format
Flutter3DViewer.obj(
    src: 'assets/flutter_dash.obj',
    //src: 'https://raw.githubusercontent.com/m-r-davari/content-holder/refs/heads/master/flutter_3d_controller/flutter_dash_model/flutter_dash.obj',
    scale: 5,
    // Initial scale of obj model
    cameraX: 0,
    // Initial cameraX position of obj model
    cameraY: 0,
    //Initial cameraY position of obj model
    cameraZ: 10,
    //Initial cameraZ position of obj model
    //This callBack will return the loading progress value between 0 and 1.0
    onProgress: (double progressValue) {
      debugPrint('model loading progress : $progressValue');
    },
    //This callBack will call after model loaded successfully and will return model address
    onLoad: (String modelAddress) {
      debugPrint('model loaded : $modelAddress');
    },
    //this callBack will call when model failed to load and will return failure erro
    onError: (String error) {
      debugPrint('model failed to load : $error');
    },
)
```

--------------------------------

### controller.resetAnimation

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Stops the animation and seeks back to frame zero, then immediately begins playing from the beginning.

```APIDOC
## controller.resetAnimation — Reset Animation

Stops the animation and seeks back to frame zero, then immediately begins playing from the beginning.

```dart
IconButton(
  icon: const Icon(Icons.replay),
  onPressed: () {
    controller.resetAnimation();
  },
);
```
```

--------------------------------

### Configure Android Manifest for Internet Permission

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Ensure the AndroidManifest.xml file includes the INTERNET permission and sets usesCleartextTraffic to true for network access.

```xml
<uses-permission android:name="android.permission.INTERNET"/>
<application
    android:usesCleartextTraffic="true"
    ...>
```

--------------------------------

### Enable Transparent Background in macOS AppDelegate

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/README.md

Add the provided Swift code to your macOS `AppDelegate` to support transparent backgrounds for the 3D controller.

```swift
import flutter_inappwebview_macos

extension InAppWebView {
    @objc public override func viewDidMoveToWindow() {
        super.viewDidMoveToWindow()
        
        if window != nil {
            print("InAppWebView moved to window, enforcing transparency")
            self.setValue(false, forKey: "opaque")
            self.setValue(false, forKey: "drawsBackground")
            self.layer?.backgroundColor = NSColor.clear.cgColor
        }
    }
}
```

--------------------------------

### Define C++ wrapper application sources

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/flutter/CMakeLists.txt

Lists the C++ source files specific to the Flutter application runner wrapper.

```cmake
list(APPEND CPP_WRAPPER_SOURCES_APP
  "flutter_engine.cc"
  "flutter_view_controller.cc"
)
list(TRANSFORM CPP_WRAPPER_SOURCES_APP PREPEND "${WRAPPER_ROOT}/")
```

--------------------------------

### Standard Compilation Settings Function

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/CMakeLists.txt

Applies standard compilation features, options, and definitions to a target, including C++17 support and specific warning configurations.

```cmake
function(APPLY_STANDARD_SETTINGS TARGET)
  target_compile_features(${TARGET} PUBLIC cxx_std_17)
  target_compile_options(${TARGET} PRIVATE /W4 /WX /wd"4100")
  target_compile_options(${TARGET} PRIVATE /EHsc)
  target_compile_definitions(${TARGET} PRIVATE "_HAS_EXCEPTIONS=0")
  target_compile_definitions(${TARGET} PRIVATE "$<$<CONFIG:Debug>:_DEBUG>")
endfunction()
```

--------------------------------

### Define Executable Target

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/runner/CMakeLists.txt

Defines the main executable for the Windows runner. Ensure BINARY_NAME is consistent with the top-level CMakeLists.txt for `flutter run` to function correctly. Add any new application source files to this list.

```cmake
cmake_minimum_required(VERSION 3.14)
project(runner LANGUAGES CXX)

# Define the application target. To change its name, change BINARY_NAME in the
# top-level CMakeLists.txt, not the value here, or `flutter run` will no longer
# work.
#
# Any new source files that you add to the application should be added here.
add_executable(${BINARY_NAME} WIN32
  "flutter_window.cpp"
  "main.cpp"
  "utils.cpp"
  "win32_window.cpp"
  "${FLUTTER_MANAGED_DIR}/generated_plugin_registrant.cc"
  "Runner.rc"
  "runner.exe.manifest"
)
```

--------------------------------

### Custom Command for Flutter Tool Backend

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/flutter/CMakeLists.txt

Defines a custom command to execute the Flutter tool backend script, which is necessary for generating build artifacts like the Flutter library and headers.

```cmake
add_custom_command(
  OUTPUT ${FLUTTER_LIBRARY} ${FLUTTER_LIBRARY_HEADERS}
    ${CMAKE_CURRENT_BINARY_DIR}/_phony_
  COMMAND ${CMAKE_COMMAND} -E env
    ${FLUTTER_TOOL_ENVIRONMENT}
    "${FLUTTER_ROOT}/packages/flutter_tools/bin/tool_backend.sh"
      ${FLUTTER_TARGET_PLATFORM} ${CMAKE_BUILD_TYPE}
  VERBATIM
)
```

--------------------------------

### Define C++ wrapper core sources

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/flutter/CMakeLists.txt

Lists the core C++ source files for the Flutter wrapper, used by both plugins and the application runner.

```cmake
list(APPEND CPP_WRAPPER_SOURCES_CORE
  "core_implementations.cc"
  "standard_codec.cc"
)
list(TRANSFORM CPP_WRAPPER_SOURCES_CORE PREPEND "${WRAPPER_ROOT}/")
```

--------------------------------

### Cross-Building Configuration

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Configures CMake for cross-building by setting the sysroot and search paths. This is used when building for a different architecture or operating system than the build machine.

```cmake
if(FLUTTER_TARGET_PLATFORM_SYSROOT)
  set(CMAKE_SYSROOT ${FLUTTER_TARGET_PLATFORM_SYSROOT})
  set(CMAKE_FIND_ROOT_PATH ${CMAKE_SYSROOT})
  set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
  set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)
  set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
  set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
endif()
```

--------------------------------

### Define Flutter library path

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/flutter/CMakeLists.txt

Sets the path to the Flutter Windows DLL, which is essential for the application's runtime.

```cmake
set(FLUTTER_LIBRARY "${EPHEMERAL_DIR}/flutter_windows.dll")
```

--------------------------------

### Generated Plugin Inclusion

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/CMakeLists.txt

Includes CMake scripts to manage the building and integration of generated plugins into the application.

```cmake
include(flutter/generated_plugins.cmake)
```

--------------------------------

### Configure Android Manifest for Internet and Cleartext Traffic

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/README.md

Update `AndroidManifest.xml` to include the INTERNET permission and enable cleartext traffic for loading external resources.

```xml
<uses-permission android:name="android.permission.INTERNET"/>

    <application
       android:name="${applicationName}"
       android:icon="@mipmap/ic_launcher"
       android:label="example"
       android:usesCleartextTraffic="true">
       <activity
           android:name=".MainActivity"

```

--------------------------------

### Modern CMake Policy

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Explicitly opts into modern CMake behaviors to avoid warnings with recent CMake versions. This ensures compatibility and adherence to current CMake standards.

```cmake
cmake_policy(SET CMP0063 NEW)
```

--------------------------------

### controller.setTexture

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Switches the model's active material variant. GLB files can embed multiple named material sets (variants); this method selects one by name.

```APIDOC
## controller.setTexture — Switch Texture Variant

Switches the model's active material variant. GLB files can embed multiple named material sets (variants); this method selects one by name.

```dart
// First fetch the variant names
final List<String> textures = await controller.getAvailableTextures();
// e.g. ['Night', 'Desert', 'Tropical']

// Apply a specific variant
controller.setTexture(textureName: 'Desert');
```
```

--------------------------------

### Including Flutter Managed Directory

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Adds the Flutter managed directory as a subdirectory. This is essential for integrating Flutter's build system and generated files.

```cmake
set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})
```

--------------------------------

### Create Flutter interface library

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/flutter/CMakeLists.txt

Defines an interface library for Flutter, allowing other targets to link against it and include its headers.

```cmake
add_library(flutter INTERFACE)
target_include_directories(flutter INTERFACE
  "${EPHEMERAL_DIR}"
)
target_link_libraries(flutter INTERFACE "${FLUTTER_LIBRARY}.lib")
add_dependencies(flutter flutter_assemble)
```

--------------------------------

### Add Preprocessor Definitions for Build Version

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/runner/CMakeLists.txt

Adds preprocessor definitions for the Flutter build version. These are useful for conditionally compiling code based on the application's version.

```cmake
# Add preprocessor definitions for the build version.
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION=\"${FLUTTER_VERSION}\"")
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_MAJOR=${FLUTTER_VERSION_MAJOR}")
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_MINOR=${FLUTTER_VERSION_MINOR}")
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_PATCH=${FLUTTER_VERSION_PATCH}")
target_compile_definitions(${BINARY_NAME} PRIVATE "FLUTTER_VERSION_BUILD=${FLUTTER_VERSION_BUILD}")
```

--------------------------------

### Define Flutter library headers

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/flutter/CMakeLists.txt

Appends a list of Flutter library header files, which are necessary for C++ integration.

```cmake
list(APPEND FLUTTER_LIBRARY_HEADERS
  "flutter_export.h"
  "flutter_windows.h"
  "flutter_messenger.h"
  "flutter_plugin_registrar.h"
  "flutter_texture_registrar.h"
)
list(TRANSFORM FLUTTER_LIBRARY_HEADERS PREPEND "${EPHEMERAL_DIR}/")
```

--------------------------------

### Load GLB/GLTF Models with Flutter3DViewer

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/README.md

Use the Flutter3DViewer widget to display glb and gltf 3D models. Customize gesture interception, loading progress bar color, touch response, and handle loading events.

```dart
//The 3D viewer widget for glb and gltf format
Flutter3DViewer(
    //If you pass 'true' the flutter_3d_controller will add gesture interceptor layer
    //to prevent gesture recognizers from malfunctioning on iOS and some Android devices.
    //the default value is true
    activeGestureInterceptor: true,
    //If you don't pass progressBarColor, the color of defaultLoadingProgressBar will be grey.
    //You can set your custom color or use [Colors.transparent] for hiding loadingProgressBar.
    progressBarColor: Colors.orange,
    //You can disable viewer touch response by setting 'enableTouch' to 'false'
    enableTouch: true,
    //This callBack will return the loading progress value between 0 and 1.0
    onProgress: (double progressValue) {
      debugPrint('model loading progress : $progressValue');
    },
    //This callBack will call after model loaded successfully and will return model address
    onLoad: (String modelAddress) {
      debugPrint('model loaded : $modelAddress');
    },
    //this callBack will call when model failed to load and will return failure error
    onError: (String error) {
      debugPrint('model failed to load : $error');
    },
    //You can have full control of 3d model animations, textures and camera
    controller: controller,
    src: 'assets/business_man.glb', //3D model with different animations
    //src: 'assets/sheen_chair.glb', //3D model with different textures
    //src: 'https://modelviewer.dev/shared-assets/models/Astronaut.glb', // 3D model from URL
)
```

--------------------------------

### Render GLB/GLTF Models with Flutter3DViewer

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Use the Flutter3DViewer widget to display GLB and GLTF models. Configure asset paths, gesture interceptors, progress bar, and touch controls. Listen to load lifecycle events via the controller.

```dart
import 'package:flutter/material.dart';
import 'package:flutter_3d_controller/flutter_3d_controller.dart';

class GlbModelPage extends StatefulWidget {
  const GlbModelPage({super.key});
  @override
  State<GlbModelPage> createState() => _GlbModelPageState();
}

class _GlbModelPageState extends State<GlbModelPage> {
  final Flutter3DController controller = Flutter3DController();

  @override
  void initState() {
    super.initState();
    // Listen to model load state changes
    controller.onModelLoaded.addListener(() {
      debugPrint('Model loaded: ${controller.onModelLoaded.value}');
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Flutter3DViewer(
        // Required: asset path, file path, or URL
        src: 'assets/business_man.glb',
        // src: 'https://modelviewer.dev/shared-assets/models/Astronaut.glb',

        // Prevents gesture malfunctions on iOS / some Android devices (default: true)
        activeGestureInterceptor: true,

        // Orange progress bar; use Colors.transparent to hide it
        progressBarColor: Colors.orange,

        // Allow touch rotation/zoom (default: true)
        enableTouch: true,

        controller: controller,

        onProgress: (double progress) {
          debugPrint('Loading: ${(progress * 100).toStringAsFixed(0)}%');
        },
        onLoad: (String modelAddress) {
          debugPrint('Loaded: $modelAddress');
          // Safe to call controller methods only after this callback fires
          controller.playAnimation();
        },
        onError: (String error) {
          debugPrint('Error: $error');
        },
      ),
    );
  }

  @override
  void dispose() {
    controller.onModelLoaded.dispose();
    super.dispose();
  }
}
```

--------------------------------

### Adding Flutter Assemble Dependency

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Ensures that the 'flutter_assemble' target is built before the application executable. This is a mandatory step for Flutter builds.

```cmake
add_dependencies(${BINARY_NAME} flutter_assemble)
```

--------------------------------

### Setting Build Type

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/linux/CMakeLists.txt

Sets the default build type to 'Debug' if not already specified. This ensures a consistent build mode for development.

```cmake
if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
  set(CMAKE_BUILD_TYPE "Debug" CACHE
    STRING "Flutter build mode" FORCE)
  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
    "Debug" "Profile" "Release")
endif()
```

--------------------------------

### controller.setCameraOrbit

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Sets the camera's position by defining its orbital angles and distance from the model. This allows precise control over the viewing perspective.

```APIDOC
## controller.setCameraOrbit — Set Camera Orbit

Positions the camera at a specific orbital angle around the model. `theta` is the horizontal angle in degrees, `phi` is the vertical angle in degrees, and `radius` is the distance as a percentage of the model's bounding sphere.

### Parameters
#### Path Parameters
- **theta** (double) - Required - The horizontal angle in degrees.
- **phi** (double) - Required - The vertical angle in degrees.
- **radius** (double) - Required - The distance from the model as a percentage of the bounding sphere.

### Usage Example
```dart
// Look at the model from the front-left, slightly above
controller.setCameraOrbit(45, 60, 80);

// Look straight down from above
controller.setCameraOrbit(0, 0, 100);
```
```

--------------------------------

### Set and Reset Camera Target

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Allows setting a specific point in 3D space for the camera to focus on, or resetting to the default auto-centering behavior.

```dart
// Focus the camera on the model's head region
controller.setCameraTarget(0.0, 1.7, 0.0);

// Reset to default (automatic centering)
controller.resetCameraTarget();
```

```dart
IconButton(
  icon: const Icon(Icons.center_focus_strong),
  onPressed: () => controller.resetCameraTarget(),
);
```

--------------------------------

### Set minSdkVersion to 21 in Android build.gradle

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/README.md

Ensure your Android app's `minSdkVersion` is set to 21 or higher in `app/build.gradle`.

```gradle
defaultConfig {
    ...
    minSdkVersion 21
    ...
}
```

--------------------------------

### controller.getAvailableAnimations

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Returns a `Future<List<String>>` of all animation clip names embedded in the loaded model. Use this to populate a picker UI before calling `playAnimation`.

```APIDOC
## controller.getAvailableAnimations — List Animations

Returns a `Future<List<String>>` of all animation clip names embedded in the loaded model. Use this to populate a picker UI before calling `playAnimation`.

```dart
ElevatedButton(
  child: const Text('Pick Animation'),
  onPressed: () async {
    final List<String> animations = 
        await controller.getAvailableAnimations();
    // e.g. ['Idle', 'Walk', 'Run', 'Attack']
    debugPrint('Found ${animations.length} animations: $animations');

    if (animations.isNotEmpty) {
      // Show a picker and play the selection
      final String? chosen = await showModalBottomSheet<String>(
        context: context,
        builder: (_) => ListView(
          children: animations
              .map((name) => ListTile(
                    title: Text(name),
                    onTap: () => Navigator.pop(context, name),
                  ))
              .toList(),
        ),
      );
      if (chosen != null) {
        controller.playAnimation(animationName: chosen);
      }
    }
  },
);
```
```

--------------------------------

### controller.setTexture

Source: https://context7.com/m-r-davari/flutter_3d_controller/llms.txt

Applies a specified texture variant to the 3D model. This method allows dynamic changes to the model's appearance based on user selection or other application logic.

```APIDOC
## controller.setTexture — Set Texture Variant

Applies the specified texture variant to the 3D model.

### Parameters
#### Request Body
- **textureName** (String) - Required - The name of the texture variant to apply.
```

--------------------------------

### Flutter Subdirectory Inclusion

Source: https://github.com/m-r-davari/flutter_3d_controller/blob/master/example/windows/CMakeLists.txt

Includes the Flutter managed directory and the runner subdirectory, essential for building the Flutter application.

```cmake
set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
add_subdirectory(${FLUTTER_MANAGED_DIR})
add_subdirectory("runner")
```