A few days ago, I saw an idle game that ran directly as an Android live wallpaper, and it immediately clicked: that format would be a great fit for Crystal Cinders, the simulation game I’m currently building on top of Sting (my custom dart:ui 2D ECS engine).

Instead of forcing a player to open an app just to check on a slow-burning world simulation, the world is just there behind your icons every time you unlock your phone, shifting with your home screen and ticking along in real time.

Since Sting already compiles to native Android binaries via Flutter’s toolchain and draws directly onto Impeller’s GPU canvas, I figured wiring it up to Android’s WallpaperService would be a quick evening task.

It didn't work on the first attempt. Today, Crystal Cinders is running smoothly as the live wallpaper on my phone—but getting Flutter 3.x with Impeller (Vulkan) to actually put pixels inside an Android WallpaperService required throwing out the old advice and flipping one of Flutter’s own internal Android tricks in reverse.

Here is what I learned getting it working.

If you look at pub.dev for Flutter wallpaper packages, almost all of them just set static images or loop a pre-rendered video file. They don't actually run a live, interactive FlutterEngine as your home screen.

And if you dig up older guides from the Flutter 1.x / 2.x Skia OpenGL days—or ask an LLM how to hook a FlutterEngine into Android’s WallpaperService.Engine—they all tell you to grab surfaceHolder.surface and pass it straight to the renderer:

// The old Skia-era approach that fails on modern Flutter / Impeller
flutterEngine.renderer.startRenderingToSurface(holder.surface, false)

When I tried this, everything looked fine in the logs. My Dart entrypoint (wallpaperMain()) booted up, the ECS loop initialized, and onDrawFrame fired at the exact physical resolution of my phone’s screen. Zero Dart exceptions, zero native crashes.

And on the phone? A pitch-black screen.

Digging through logcat showed what was actually happening:

HWUI: Surface doesn't have any previously queued frames

In Flutter 3.x (with Impeller Vulkan enabled by default on Android):

  • A normal FlutterActivity creates a FlutterView wrapping a FlutterSurfaceView and calls flutterView.attachToFlutterEngine(engine). That FlutterView setup is what properly initializes the RenderSurface pipeline for Impeller.
  • Android’s WallpaperService.Engine, however, has no View hierarchy at all. It isn't an Activity or a Window—it only gives you a raw SurfaceHolder.
  • Calling flutterEngine.renderer.startRenderingToSurface(holder.surface, false) bypasses FlutterView and RenderSurface. Even though Dart runs onDrawFrame, Impeller never queues the rendered frame buffers onto the Wallpaper#0 surface.

Once I understood why Impeller was refusing to queue frames, the problem was clear: how do you mount a real FlutterView when WallpaperService doesn't have a View hierarchy?

Ironically, the answer was hiding inside Flutter’s own Android engine architecture—just used in the opposite direction.

When Flutter needs to render a native Android View (like a WebView or Google Map) inside a Flutter app using Platform Views (Virtual Display mode), Flutter creates an Android VirtualDisplay and wraps the native view inside a Presentation window (SingleViewPresentation).

To get Flutter working inside WallpaperService, you flip that exact trick inside out:

Instead of bypassing FlutterView, CrystalCindersWallpaperService creates a hardware-backed VirtualDisplay whose output target is the wallpaper’s SurfaceHolder.surface. Once Android treats the wallpaper surface as a virtual display, you open a Presentation window on that display and mount a real FlutterView inside it:

WallpaperService.Engine (holder.surface)
  └── DisplayManager.createVirtualDisplay(..., surface = holder.surface, VIRTUAL_DISPLAY_FLAG_OWN_CONTENT_ONLY)
        └── Presentation(context, virtualDisplay.display)
              └── FlutterView(context)
                    └── flutterView.attachToFlutterEngine(flutterEngine)

The moment flutterView.attachToFlutterEngine(flutterEngine) runs inside that Presentation window, Impeller gets the full FlutterView lifecycle it expects, Vulkan queues frame buffers onto the virtual display’s surface, and those pixels go straight onto the Android home screen.

Getting the first frame on screen was half the job. Making a simulation game behave nicely as a daily wallpaper took four more details:

1. OEM Background Thread Callbacks (Looper.getMainLooper())

On Pixel phones, WallpaperService callbacks usually arrive on the main thread. On several custom Android OEM ROMs, some surface callbacks fire on background threads—which immediately triggers a @UiThread crash if you touch FlutterEngine, VirtualDisplay, Presentation, or a MethodChannel. Wrapping those calls in Handler(Looper.getMainLooper()) and setting surfaceHolder.setFormat(PixelFormat.RGBA_8888) in Engine.onCreate keeps it stable everywhere.

2. Pausing the Loop When You Aren't Looking (onVisibilityChanged)

Running a 60 FPS ECS simulation while you're looking at your home screen is great. Running it at 60 FPS while you have another app open in front of it—or while your phone is locked in your pocket—will drain your battery in a couple of hours.

In onVisibilityChanged(visible: Boolean), the service calls engine.lifecycleChannel.appIsResumed() / appIsPaused() and sends a "resume" / "pause" message over MethodChannel("crystal_cinders/wallpaper") so the game loop stops scheduling frames the instant the home screen is hidden.

3. Home-Screen Swipe Parallax (onOffsetsChanged)

Whenever you swipe between home-screen pages, Android fires onOffsetsChanged in WallpaperService.Engine. Forwarding those horizontal offsets to Dart lets the game camera pan subtly across the simulation world as you swipe through your apps.

4. Clean Teardown Between Preview and Live Wallpaper

When you open the Android Wallpaper Picker (which the game triggers directly via WallpaperManager.ACTION_CHANGE_LIVE_WALLPAPER over a launcher channel in MainActivity.kt), Android spins up a preview engine instance alongside any existing wallpaper and destroys surfaces aggressively when switching. Dismissing the Presentation window (which detaches FlutterView) and releasing the VirtualDisplay in onSurfaceDestroyed and onDestroy—before destroying the FlutterEngine—prevents GPU leaks and black-screen race conditions.

Right now, having the simulation running live as my phone’s wallpaper feels awesome—and it immediately gave me the next idea I want to build.

Instead of treating the wallpaper and the full game as two disconnected things, I want tapping on the live wallpaper to take you seamlessly straight into the full interactive game world.

I haven't tested this part yet, and I’m 100% sure it has its own set of Android surprises waiting for me:

  • Fighting the home-screen launcher over which taps belong to app icons versus the wallpaper (onTouchEvent vs. COMMAND_TAP).
  • Dealing with Android 10+ restrictions on launching an Activity from a background WallpaperService.
  • Handing off the live simulation state between the wallpaper’s FlutterEngine and MainActivity so the camera and world transition without a jarring reload.

That will be my next experiment—and probably the next post once I figure out what breaks first.