Why Choose flutter_sceneview?

The flutter_sceneview plugin gives you native‑level rendering performance while keeping the Flutter declarative UI model intact. It delegates the heavy lifting to Filament (Android) and RealityKit (iOS), so you get:

  • Hardware‑accelerated graphics with realistic lighting.
  • Support for common 3‑D formats such as glTF and USDZ.
  • A single widget (SceneView) that works for pure 3‑D and AR use‑cases.
  • Cross‑platform consistency without writing separate native code.

Installation

Add the package to your pubspec.yaml using the Flutter CLI:

Code
flutter pub add flutter_sceneview

After the command finishes, run flutter pub get to fetch the plugin.

Platform‑Specific Setup

Both Android and iOS require a few extra steps before you can render AR content.

Android

  • Ensure your minSdkVersion is at least 24 in android/app/build.gradle.
  • Add the required permissions to AndroidManifest.xml:
    Code
    <uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera.ar" android:required="false" />
  • Enable Java 8 language features if they are not already enabled.

iOS

  • Open ios/Runner/Info.plist and add the camera usage description:
    Code
    <key>NSCameraUsageDescription</key>
<string>This app uses the camera for AR experiences.</string>
  • Set the deployment target to iOS 13 or higher (RealityKit requires iOS 13+).
Tip: If you only need pure 3‑D rendering (no AR), you can skip the camera permissions, but the widget still works the same way.

Simple Usage Example

The following minimal example loads a glTF model from the app’s assets and optionally enables AR on supported devices.

Dart / Flutter
import 'package:flutter/material.dart';
import 'package:flutter_sceneview/flutter_sceneview.dart';

class SimpleScenePage extends StatelessWidget {
  const SimpleScenePage({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('3D Scene')),
      body: Center(
        child: SceneView(
          // Load a glTF model from assets
          assetPath: 'assets/models/robot.glb',
          // Enable AR on devices that support it (optional)
          enableAR: true,
          // Called when the native scene is ready
          onSceneCreated: (controller) {
            // Adjust the initial scale, position, etc.
            controller.setScale(1.0);
          },
        ),
      ),
    );
  }
}

Make sure the model file (robot.glb) is listed under the assets section of your pubspec.yaml:

Code
flutter:
  assets:
    - assets/models/robot.glb

Understanding the SceneView
Code
Widget

The widget exposes a small but powerful API:

  • assetPath: Relative path to a model bundled with the app.
  • url: Remote URL for loading a model over HTTP/HTTPS.
  • bytes: In‑memory byte buffer (useful for dynamically generated scenes).
  • enableAR: Boolean flag that toggles AR mode on devices that support it.
  • onSceneCreated: Callback that provides a SceneController for runtime manipulation (scale, rotation, lighting, etc.).

The SceneController methods are thin wrappers around the native APIs. Typical methods include:

  • setScale(double)
  • setRotation(double x, double y, double z)
  • setPosition(double x, double y, double z)
  • addLight(LightConfig) – see the package docs for the exact signature.

Common Pitfalls & How to Avoid Them

  • Missing permissions: Forgetting the camera permission on Android or iOS will cause AR initialization to fail. Check the console logs for permission‑related errors.
  • Unsupported file format: The plugin currently supports glTF/GLB and USDZ. Trying to load OBJ or FBX will result in a runtime error. Verify the format before calling SceneView.
  • Large binary size: Because the plugin bundles native Filament and RealityKit binaries, the final APK/IPA can increase by ~10‑15 MB. Consider using split-per-abi on Android to reduce the download size for end users.
  • Running on the web or desktop: The package does not support those platforms yet. Guard your code with kIsWeb or defaultTargetPlatform checks if you target multiple platforms.
Mistake to avoid: Instantiating SceneView inside a scrolling list without a fixed height. The native view needs a bounded size; otherwise you’ll see layout warnings and a blank area.

Performance Tips

  • Reuse the same SceneController when you need to update a model instead of rebuilding the entire SceneView.
  • Keep model file sizes under a few megabytes for faster load times on mobile networks.
  • Use the enableAR flag only on devices that actually support AR; on other devices the widget falls back to pure 3‑D rendering, which is lighter.

Next Steps

Once you’re comfortable with the basics, explore the following advanced topics:

  • Loading scenes from a remote server and handling caching.
  • Adding interactive anchors and hit‑testing for AR experiences.
  • Custom lighting and material overrides via SceneController.
  • Integrating with state‑management solutions (Provider, Riverpod, Bloc) to react to user input.

For the complete API reference and up‑to‑date examples, visit the official package page on pub.dev:

https://pub.dev/packages/flutter_sceneview

Frequently Asked Questions

Does flutter_sceneview work on web or desktop?

No. The plugin currently supports only Android and iOS because it relies on native renderers (Filament and RealityKit). Attempting to use it on web, macOS, Windows, or Linux will result in a runtime error.

What 3‑D file formats are supported?

The package supports glTF/GLB files on both platforms and USDZ files on iOS (RealityKit). Other formats like OBJ or FBX are not supported out of the box.

Do I need to request camera permission for pure 3‑D rendering?

Camera permission is only required when you enable AR mode (set <code>enableAR: true</code>). For pure 3‑D scenes you can omit the permission entries.

How can I update a model after it has been loaded?

Use the <code>SceneController</code> provided by the <code>onSceneCreated</code> callback. Methods such as <code>setScale</code>, <code>setRotation</code>, and <code>setPosition</code> let you manipulate the scene without rebuilding the widget.

Is there a way to reduce the app size added by flutter_sceneview?

The plugin bundles native binaries for both Filament and RealityKit, which adds roughly 10‑15 MB. Enabling Android's <code>split-per-abi</code> and using ProGuard/R8 can help shrink the final APK.