Files
cesiumflutter/CLAUDE.md
T
2026-11-07 15:48:01 +01:00

4.3 KiB

CLAUDE.md

Flutter plugin (Linux, Android, Windows) embedding a CesiumJS globe. The package is meant to be imported by other apps: keep the public API in lib/cesiumjs.dart small and stable; everything else stays in lib/src/. example/ is the test/demo app, not part of the package.

Commands

flutter pub get && flutter analyze && flutter test        # package (root)
cd example && flutter build linux --debug                 # compiles the native plugin
cd example && flutter build apk --debug                   # compiles the Kotlin plugin
cd example && flutter run -d linux --dart-define-from-file=cesium_ion.json

Native build needs libwebkit2gtk-4.1-dev. Native code is only compiled through the example app — after changing linux/cesiumjs_plugin.cc or android/, always run the matching flutter build in example/. windows/cesiumjs_plugin.cpp cannot be built from Linux (needs MSVC); it compiles with /W4 /WX, so avoid unused parameters, shadowed names and narrowing.

Android test emulator: AVD cesium_test (API 35, x86_64), lives in ~/.config/.android/avd → start with ANDROID_AVD_HOME=~/.config/.android/avd ~/Android/Sdk/emulator/emulator -avd cesium_test.

Architecture

All platforms share the cesiumjs/webview channel protocol (create eagerly builds the web view keyed by a Dart id; other calls address it by id).

  • CesiumViewer (Dart) renders a black placeholder and reports its global rect after each paint (_RenderRectReporter) → setRect over the cesiumjs/webview method channel.
  • linux/cesiumjs_plugin.cc creates one WebKitWebView per viewer inside a GtkOverlay that holds the FlView; get-child-position places it at the reported rect. Methods: create, setRect, runJavaScript, openInspector, dispose, disposeAll (called once per isolate so hot restart doesn't leave orphan views). Events back to Dart: onMessage, onError.
  • Android (android/…/CesiumjsPlugin.kt): create builds an android.webkit.WebView; the widget then shows it with an AndroidView (view type cesiumjs/webview, creation param id). setRect is a no-op. Flutter widgets can paint over the globe here.
  • Windows (windows/cesiumjs_plugin.cpp): WebView2 in a host child window, sibling of the Flutter view, placed at rect * scale (Dart sends devicePixelRatio as scale). Page served from https://cesium.localhost/ via WebResourceRequested. WebView2 SDK downloaded from NuGet by CMake.
  • JS → Dart: CesiumChannel.postMessage → window.webkit.messageHandlers.cesium (Linux), window.CesiumAndroid.postMessage (Android), window.chrome.webview.postMessage (Windows). Messages are JSON with a type field → CesiumMessage.
  • HTML is generated in lib/src/cesium_html.dart and loaded with load_html + base URI https://cesium.localhost/; CesiumJS comes from jsDelivr (cesiumVersion). JS helpers cesiumViewer / cesiumLayers live on window.

Gotchas — do not regress

  • Overlay creation: the stock runner realizes the FlView (starting the engine's GL surface) before plugins register. A plain gtk_container_remove/add unrealizes it and Flutter fails with "Could not determine GL version". ensure_overlay() uses the deprecated gtk_widget_reparent() via a temporary realized window to keep it realized.
  • on_view_realize → gdk_window_ensure_native() must stay: without a native child window, GTK3 composites WebKit with the FlView GL surface and only ~0.2 frames/s reach the screen (Cesium's own FPS counter still says 60 — measure presented frames with ffmpeg x11grab + mpdecimate instead).
  • Linux/Windows: Flutter widgets cannot paint over the globe; use visible: false.
  • runJavaScript cannot return a Promise as the last expression; scripts that return nothing should end with undefined;.
  • Controller internals (attach, detach, handleMessage) are @internal.

Conventions

  • Never commit a Cesium ion token. The example reads CESIUM_ION_TOKEN via --dart-define-from-file=cesium_ion.json (git-ignored).
  • New controller features: add a Dart method in cesium_controller.dart that calls runJavaScript (JSON-encode string arguments with jsonEncode), plus a JS helper in cesium_html.dart if it is more than a few lines.
  • Update README.md API tables and CHANGELOG.md when the public API changes.