Skip to content

Latest commit

 

History

History
90 lines (68 loc) · 6.49 KB

plugin-advanced.md

File metadata and controls

90 lines (68 loc) · 6.49 KB

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) and DeclarativePlugin runtimes are fully deprecated. All new plugins must be dynamically imported at runtime as ES module bundles via import(/* webpackIgnore: true */ entry).

How Plugins Load

  1. A user clicks "Install" in the Marketplace.
  2. The marketplace sends the plugin manifest (containing an ES Module CDN URL, like unpkg.com) to the WorldWideView database.
  3. At runtime, the client useMarketplaceSync hook fetches the manifests from /api/marketplace/load and pluginManager.loadFromManifest dynamically imports the JavaScript bundle.
  4. 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 lightweight Javascript data polling script.

WorldWideView is a completely agnostic renderer. It has absolutely no concept of a "unified" Data Engine. If 30 plugins require 30 different WebSocket servers, the application will blindly open 30 connections. Each plugin is a self-contained package and MUST explicitly declare its own streamUrl in its manifest or config. Do NOT assume the frontend acts as a unified pipe.

While you can host your own backend, we provide the DataEngineV2 runner as a standardized environment for seeders.

Data Engine V2 Seeder Architecture

Instead of the frontend fetching data, you write a lightweight seeder script that connects to an upstream source, normalizes the data, and is executed by the central wwv-data-engine-v2 host runner.

  1. Create a Seeder Directory: Inside your WorldWideView project, create a folder under local-seeders/ (e.g., local-seeders/community/my-plugin/). Note that seeders are split into community and private tiers to prevent namespace collisions.
  2. Write the Seeder Script: Create a seeder.mjs file that exports a fetch(ctx) function.
  3. Engine Auto-Discovery: The local Docker-based wwv-data-engine-v2 automatically mounts this directory, discovers your script, and runs it on the defined interval.
  4. WebSocket & REST Delivery: Seeders in V2 expose both a WebSocket stream (/stream) for real-time instantaneous updates, and a REST API endpoint (/api/:id) for fetching live data snapshots directly from Redis.

Dependency Management & Monorepo Hoisting

Seeders within local-seeders/ are strictly orchestrated within the pnpm workspace. They are executed by the central runner, not as standalone applications.

  • Keep package.json clean: Do not include bulky dependencies in your seeder's local package.json (unless it's an exceptional, bespoke library).
  • Workspace Resolution: Standard packages (e.g., zod, ws, node-cron, undici) are provided by the engine. At runtime, wwv-data-engine-v2 leverages native Node.js module resolution to fetch the required dependencies directly from the root workspace or its own containerized runtime. Seeders MUST NOT bundle these dependencies.
  • Lightweight by Design: This dependency orchestration guarantees that seeders remain extremely lightweight, hot-reloading takes milliseconds, and Docker container size stays optimized.

Tip

Debugging WebSockets: If your frontend isn't receiving data from your backend seeder:

  1. Check the wwv-data-engine-v2 logs to ensure your seeder is publishing to Redis successfully.
  2. Verify the frontend is connected to the correct WebSocket endpoint. Local instances default to ws://localhost:5000/stream, while unrecognized plugins should explicitly define their own streamUrl, or fallback to the cloud at wss://dataenginev2.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 billboard or point primitives.
  • When the camera gets close, the system's useModelRendering hook 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, or outlineColor properties onto an entity of type: "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:

  1. Publish to NPM: Log in to NPM and publish your package using the WWV CLI from the project root (you can also use the --org flag to publish under your own NPM organization):
    npm login
    node packages/wwv-cli/dist/index.js publish <plugin-name> [--org <your-org>]
    (Or npx wwv publish <plugin-name> [--org <your-org>] if installed globally)
  2. Submit: Navigate to https://marketplace.worldwideview.dev/submit.
  3. Register: Enter your NPM package name. The marketplace automatically scrapes your package.json for the required "worldwideview" object block (containing your id, icon, and category).
  4. 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-sdk as a peerDependency (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").