* docs(core): comprehensive documentation overhaul * fix: resolve worktree paths dynamically via git CLI * refactor(ui): temporarily disable demo ad strip * fix(ui): redirect header logo and cleanup marketplace routes [Patch] - make header logo a clickable link to landing page [Patch] - cleanup marketplace routes and remove builtinPlugins [Patch] --------- Co-authored-by: Antigravity AI <[email protected]>
4.5 KiB
Advanced Plugin Guide
This guide covers complex architectures, real-time telemetry streaming, and the deployment lifecycle for WorldWideView plugins. If you haven't built a basic plugin yet, start with the Quickstart.
Architecture Paradigm: The All-Bundle Model
WorldWideView operates on a strict Dynamic CDN Loaded (Bundle) architecture.
Warning
Deprecation Notice: The legacy
StaticDataPlugin(GeoJSON loaders) andDeclarativePluginruntimes are fully deprecated. All new plugins must be dynamically imported at runtime as ES module bundles viaimport(/* webpackIgnore: true */ entry).
How Plugins Load
- A user clicks "Install" in the Marketplace.
- The marketplace sends the plugin manifest (containing an ES Module CDN URL, like
unpkg.com) to the WorldWideView database. - At runtime, the
InstalledPluginsLoaderdynamically fetches the JavaScript bundle. - The plugin is instantiated, and its
initialize(ctx)method is invoked.
Real-Time Data: Bring Your Own Backend (BYOB)
Relying on the frontend fetch() method is insufficient for high-frequency real-time tracking (like aviation or maritime). For continuous telemetry, you must build a Data Engine Seeder — a containerized backend microservice.
Microservice Seeder Architecture
Instead of the frontend fetching data, your backend container connects to an upstream source, normalizes the data, and publishes it to the central Redis stream managed by wwv-data-engine.
- Scaffold a Backend: Use the CLI to generate a backend template.
npx @worldwideview/cli create-backend my-plugin-backend - Containerize: This generates a Fastify Node.js server with a
Dockerfileanddocker-compose.yml. - Publish to Redis: Your backend polls the external API (e.g., ADS-B Exchange) and pushes snapshots to the WorldWideView Redis pipeline.
- WebSocket Delivery: The central
wwv-data-engineimmediately broadcasts these updates over WebSockets to all connected clients.
Tip
Debugging WebSockets: If your frontend isn't receiving data from your backend seeder:
- Check the
wwv-data-enginelogs to ensure your seeder is publishing to Redis successfully.- Verify the frontend is connected to the correct WebSocket endpoint. Local instances default to
ws://localhost:5001/stream, while unrecognized seeders fall back to the cloud atwss://dataengine.worldwideview.dev/stream.
Advanced Cesium Rendering
When returning CesiumEntityOptions in renderEntity(entity), you have direct access to the 3D engine's capabilities.
3D Models vs. Billboards (LOD Strategy)
To maintain 60 FPS with tens of thousands of entities, use WorldWideView's Level of Detail (LOD) promotion system.
- Render distant entities as simple
billboardorpointprimitives. - When the camera gets close, the system's
useModelRenderinghook can promote the entity to a full 3D glTF model.
renderEntity(entity: GeoEntity): CesiumEntityOptions {
return {
type: "billboard", // Primary lightweight renderer
color: "#ffffff",
iconUrl: "https://unpkg.com/my-plugin/assets/icon.png",
iconScale: 0.5,
// Provide a 3D model URL. The engine will swap it in automatically at close range.
modelUrl: "https://unpkg.com/my-plugin/assets/model.glb",
modelScale: 1.0,
heading: entity.heading,
};
}
Caution
GPU Clipping Bug: NEVER mix
size,outlineWidth, oroutlineColorproperties onto an entity oftype: "billboard". This will cause the WebGL compiler to panic and result in severe visual clipping artifacts.
Publishing to the Marketplace
To distribute your plugin globally:
- Publish to NPM:
npm publish --access public - Submit: Navigate to
https://marketplace.worldwideview.dev/submit. - Register: Enter your NPM package name. The marketplace automatically scrapes your
package.jsonfor the required"worldwideview"object block (containing yourid,icon, andcategory). - Review: Once approved, your plugin's ES Module bundle will be served via CDN to all WorldWideView instances worldwide.
Debugging Marketplace Submissions
- "Invalid Manifest" Error: Ensure you are using
@worldwideview/wwv-plugin-sdkas apeerDependency(not a direct dependency) so the host application injects the context correctly. - Icon Not Showing: Icons must be valid Lucide icon strings (e.g.,
"Plane","Anchor").