3.1 KiB
3.1 KiB
CLAUDE.md
Flutter plugin (Linux desktop only) 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 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, always
run flutter build linux in example/.
Architecture
CesiumViewer(Dart) renders a black placeholder and reports its global rect after each paint (_RenderRectReporter) →setRectover thecesiumjs/webviewmethod channel.linux/cesiumjs_plugin.cccreates oneWebKitWebViewper viewer inside aGtkOverlaythat holds theFlView;get-child-positionplaces 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.- JS → Dart:
CesiumChannel.postMessage→window.webkit.messageHandlers.cesium. Messages are JSON with atypefield →CesiumMessage. - HTML is generated in
lib/src/cesium_html.dartand loaded withload_html+ base URIhttps://cesium.localhost/; CesiumJS comes from jsDelivr (cesiumVersion). JS helperscesiumViewer/cesiumLayerslive onwindow.
Gotchas — do not regress
- Overlay creation: the stock runner realizes the
FlView(starting the engine's GL surface) before plugins register. A plaingtk_container_remove/addunrealizes it and Flutter fails with "Could not determine GL version".ensure_overlay()uses the deprecatedgtk_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).- Flutter widgets cannot paint over the globe; use
visible: false. runJavaScriptcannot return a Promise as the last expression; scripts that return nothing should end withundefined;.- Controller internals (
attach,detach,handleMessage) are@internal.
Conventions
- Never commit a Cesium ion token. The example reads
CESIUM_ION_TOKENvia--dart-define-from-file=cesium_ion.json(git-ignored). - New controller features: add a Dart method in
cesium_controller.dartthat callsrunJavaScript(JSON-encode string arguments withjsonEncode), plus a JS helper incesium_html.dartif it is more than a few lines. - Update
README.mdAPI tables andCHANGELOG.mdwhen the public API changes.