Why Choose flutter_sceneview?

The flutter_sceneview plugin gives you native‑level 3D and AR rendering while keeping the UI declarative in Dart. It delegates the heavy lifting to Filament on Android and RealityKit on iOS, delivering realistic lighting, hardware‑accelerated frame rates, and support for common formats such as glTF and USDZ. If you need immersive product visualisations, architectural walkthroughs, or simple AR demos without maintaining separate native codebases, this package is a solid choice.

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 dependency.

Platform‑Specific Setup

Android

  • Make sure your minSdkVersion is at least 24 (required by Filament).
  • Add the required camera permission if you plan to enable AR mode:
    Code
    <uses-permission android:name="android.permission.CAMERA" />

iOS

  • Open ios/Runner/Info.plist and add the NSCameraUsageDescription key with a user‑facing description.
  • RealityKit requires iOS 13 or later; ensure your deployment target reflects this.

Adding 3D Assets

Place your glTF, USDZ, or other supported files in the assets/ folder and declare them in pubspec.yaml:

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

Both local assets and remote URLs are accepted by the widget.

Basic Usage Example

The following minimal example demonstrates how to embed a 3‑D model and optionally enable 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 (iOS & Android ARCore)
          enableAR: true,
          // Called when the native scene is ready
          onSceneCreated: (controller) {
            // Adjust the initial scale or other properties
            controller.setScale(1.0);
          },
        ),
      ),
    );
  }
}

The SceneView widget behaves like any other Flutter widget, so you can wrap it in Expanded, AspectRatio, or layout it alongside other UI elements.

Understanding the SceneController

The callback supplied to onSceneCreated receives a SceneController instance. With this controller you can:

  • Change the model’s scale, rotation, or position.
  • Toggle AR mode at runtime (if the device supports it).
  • Listen for interaction events such as taps or gestures.

All controller methods are documented on the pub.dev page; refer to the API reference for the full list.

Common Pitfalls & How to Avoid Them

  • Missing permissions: Forgetting to add camera permissions will cause AR initialization to fail. Verify both AndroidManifest.xml and Info.plist entries.
  • Unsupported platform: The package currently works only on Android and iOS. Attempting to run on web, desktop, or older iOS versions will result in a runtime error.
  • Large binary size: Because Filament and RealityKit are bundled as native binaries, the app size increases noticeably. Consider using --split-per-abi for Android to reduce the download payload.
  • Asset path errors: Ensure the asset path matches exactly (case‑sensitive) and that the file is listed under flutter.assets in pubspec.yaml.

Tip: When testing AR features, use a physical device rather than an emulator. Emulators cannot provide camera input or the required ARCore/ARKit services.

Performance Tips

  • Keep model geometry lightweight – aim for under 100k triangles for smooth interaction on mid‑range devices.
  • Use compressed textures (e.g., KTX2) to reduce memory usage.
  • Leverage the controller’s setScale and setPosition methods instead of rebuilding the widget tree for every transformation.

When to Use flutter_sceneview

This plugin shines in scenarios where you need high‑fidelity 3‑D rendering or basic AR without writing native Swift/Java/Kotlin code. Typical use cases include:

  • E‑commerce product visualisation (rotate, zoom, AR preview).
  • Architectural walkthroughs or interior design previews.
  • Educational demos that overlay 3‑D models onto the real world.
  • Simple AR gaming prototypes that require only a single scene.

If you need multi‑platform support (web or desktop) or advanced AR features like plane detection, you may need to evaluate alternatives such as arcore_flutter_plugin or arkit_flutter_plugin.

Further Resources

  • Pub.dev page: flutter_sceneview
  • API documentation (auto‑generated on pub.dev).
  • Sample project on the package’s GitHub repository (if available).

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). For web or desktop you would need a different solution.

What 3‑D file formats are supported?

The package can load common formats such as glTF (.glb, .gltf) and USDZ out of the box. Other formats may work if the underlying native engine supports them, but you should verify on pub.dev.

Do I need to write any platform‑specific code?

No. All interaction is performed through the Dart API. You only need to add the required permissions (camera) in AndroidManifest.xml and Info.plist.

How can I toggle AR mode at runtime?

Use the <code>SceneController</code> received in <code>onSceneCreated</code>. It provides methods such as <code>enableAR(bool)</code> (verify the exact method name in the official docs) to switch between pure 3‑D and AR modes.

What should I do if the scene fails to load?

Check the console for error messages, verify that the asset path is correct and listed in <code>pubspec.yaml</code>, and ensure the device meets the minimum SDK requirements (Android API 24+, iOS 13+).