Files
worldwideview/docs/iss-plugin-tutorial.md
T
SilvertakanaandAntigravity AI a5125dba7b docs: Comprehensive Documentation Overhaul (#39)
* 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]>
2026-04-28 23:39:20 +12:00

9.9 KiB

End-to-End Tutorial: Building a Real-Time ISS Tracking Plugin

Welcome! This tutorial is designed for complete beginners. If you have never built a WorldWideView plugin before, you are in the right place.

By following these steps exactly, you will build a complete, real-time International Space Station (ISS) tracker from scratch. You will learn how to set up your environment, stream live data using a backend seeder, render it in 3D on the globe, and publish your work to the world.

Let's get started.


Step 1: Setting up your Workspace

Before we write any code, we need to prepare your computer. We will install the required tools and download the two main repositories that make up the WorldWideView platform.

1.1 Install Prerequisites

Ensure you have the following installed on your machine:

  1. Node.js: Download and install Node.js (Version 18 or higher is required).
  2. Git: Download and install Git.
  3. pnpm: This is the package manager we use. Open your terminal and run:
    npm install -g pnpm
    

1.2 Clone the Repositories

You need both the frontend application and the backend data engine. Open your terminal and navigate to the folder where you want to store your code (e.g., C:\dev).

Run these commands to download the code:

git clone https://github.com/silvertakana/worldwideview.git
git clone https://github.com/silvertakana/wwv-data-engine.git

1.3 Install Dependencies

Next, we need to install the libraries that these projects depend on.

First, install dependencies for the Data Engine:

cd wwv-data-engine
pnpm install

Second, install dependencies for the main WorldWideView application:

cd ../worldwideview
pnpm install

1.4 Setup Environment Variables

WorldWideView needs a few basic configuration keys to run.

While still in the worldwideview folder, run the automated setup script. This will generate a .env.local file with the necessary secrets:

pnpm run setup

Your workspace is now ready!


Step 2: Creating the Data Engine Seeder (Backend)

The ISS moves incredibly fast. If our frontend tries to ask for its location every second, it will lag. Instead, we use the Bring Your Own Backend (BYOB) pattern. We will write a "Seeder" script in the Data Engine that fetches the ISS location and instantly broadcasts it to the frontend via WebSockets.

2.1 Create the Seeder File

Navigate to your data engine repository and create a new file named iss.ts in the src/seeders folder: c:\dev\wwv-data-engine\src\seeders\iss.ts

2.2 Write the Polling Logic

Open iss.ts in your text editor and paste the following code. This script reaches out to the free WhereTheISS.at API every 5 seconds and saves the data to the engine's memory (Redis).

import { setLiveSnapshot } from '../core/redis';
import axios from 'axios';

const WTIA_URL = 'https://api.wheretheiss.at/v1/satellites/25544';
const POLLING_INTERVAL = 5000; // 5 seconds

async function pollISS() {
  try {
    // 1. Fetch data from the API
    const response = await axios.get(WTIA_URL);
    const data = response.data;

    // 2. Format the data into a GeoEntity object
    const stateObj = {
      id: 25544,
      name: "International Space Station",
      latitude: data.latitude,
      longitude: data.longitude,
      altitude: data.altitude * 1000, // Convert kilometers to meters
      velocity: data.velocity,
      visibility: data.visibility,
      footprint: data.footprint
    };

    // 3. Save to Redis under the 'iss' namespace for 60 seconds
    await setLiveSnapshot('iss', { "25544": stateObj }, 60);
    console.log(`[ISS] Poll OK: updated position to ${data.latitude}, ${data.longitude}`);
    
  } catch (error) {
    console.error(`[ISS] Polling error:`, error.message);
  } finally {
    // 4. Repeat the process after 5 seconds
    setTimeout(pollISS, POLLING_INTERVAL);
  }
}

// Start the loop
pollISS();

2.3 Register the Seeder

The engine needs to know your seeder exists. Open c:\dev\wwv-data-engine\src\seeders\index.ts and add this line at the bottom:

import './iss';

Step 3: Testing the Data Engine

Before we build the frontend, let's prove that our backend is actually fetching the ISS data.

3.1 Start the Engine

In your terminal, navigate to the wwv-data-engine folder and start the backend:

pnpm dev:backends

You should see [ISS] Poll OK: updated position appearing in your console every 5 seconds. Leave this terminal running.

3.2 Write a Quick Test Script

Open a new terminal window. Let's write a tiny script to peek into the engine's memory. Create a file called test_iss.mjs in the wwv-data-engine folder:

// test_iss.mjs
import Redis from 'ioredis';
const redis = new Redis();

async function verify() {
  const data = await redis.get('data:iss:live');
  if (data) {
    console.log("Success! We found the ISS:", JSON.parse(data));
  } else {
    console.log("No data found yet.");
  }
  process.exit(0);
}
verify();

Run the script:

node test_iss.mjs

If you see a large block of data containing coordinates and altitude, your backend is working perfectly!


Step 4: Creating the WorldWideView Plugin (Frontend)

Now we will build the visual part of the plugin that connects to our backend stream and draws the ISS on the 3D globe.

4.1 Scaffold the Plugin

In your terminal, navigate back to your main c:\dev folder. We will use the official CLI tool to generate a blank plugin template. Run:

npx @worldwideview/create-plugin@latest wwv-plugin-iss

When prompted, name the folder wwv-plugin-iss.

Move into your new plugin folder and install its dependencies:

cd wwv-plugin-iss
npm install

4.2 Write the Plugin Logic

Open c:\dev\wwv-plugin-iss\src\index.ts in your text editor. Replace everything in the file with this code:

import type { WorldPlugin, GeoEntity, PluginContext, LayerConfig, CesiumEntityOptions } from "@worldwideview/wwv-plugin-sdk";

export class IssPlugin implements WorldPlugin {
  // The ID MUST match the namespace we used in the backend ('iss')
  id = "iss"; 
  name = "ISS Live Tracker";
  description = "Real-time International Space Station tracking.";
  icon = "Satellite"; 
  category = "space" as const;
  version = "1.0.0";

  async initialize(ctx: PluginContext): Promise<void> {
    console.log("ISS Plugin loaded!");
  }

  destroy(): void { }

  async fetch(): Promise<GeoEntity[]> {
    // We return an empty array because the WebSockets handle the data automatically.
    return [];
  }

  getPollingInterval(): number {
    return 0; // Disabled: we use continuous WebSockets instead of polling.
  }

  getLayerConfig(): LayerConfig {
    return {
      color: "#00ffcc",
      clusterEnabled: false
    };
  }

  renderEntity(entity: GeoEntity): CesiumEntityOptions {
    // Level of Detail (LOD): Use a 2D billboard from far away, 
    // and transition to a 3D model when zooming in close.
    return {
      type: "billboard",
      color: "#ffffff",
      iconUrl: "https://unpkg.com/wwv-plugin-iss/assets/iss-icon.png",
      iconScale: 0.8,
      modelUrl: "https://unpkg.com/wwv-plugin-iss/assets/ISS_stationary.glb",
      modelScale: 2.5,
      heading: entity.heading || 0,
    };
  }
}

Step 5: Connecting and Testing Everything

Now we will link your new plugin to your local WorldWideView application to see it in action.

In your wwv-plugin-iss terminal, tell the CLI where your main WorldWideView folder is:

npx wwv config set wwv-path C:\dev\worldwideview

Now, link the plugin. This creates a shortcut so WorldWideView can see your code:

npm run link

Start the plugin watcher. This will automatically update your plugin if you make any changes to the code:

npm run dev

Leave this terminal running.

5.2 Start WorldWideView

Open a third, final terminal window. Navigate to your main worldwideview folder and start the frontend application:

cd C:\dev\worldwideview
pnpm dev

5.3 View the ISS

  1. Open your web browser and go to http://localhost:3000.
  2. Click the Layers icon on the left sidebar.
  3. Find ISS Live Tracker in the list and toggle it ON.
  4. The globe will instantly fly to the current location of the ISS, and you will see it moving in real-time!

Tip

Troubleshooting missing points:

  • Ensure your Data Engine terminal (pnpm dev:backends) is still running.
  • Press F12 in your browser to open Developer Tools. Check the Console tab for any red errors.
  • Ensure the id in your plugin ("iss") exactly matches the name you used in the backend setLiveSnapshot('iss', ...).

Step 6: Publishing Your Plugin

You've built it, now share it with the world!

6.1 Update package.json

Open c:\dev\wwv-plugin-iss\package.json. You must add a "worldwideview" metadata block so the marketplace knows how to read your plugin. Ensure your file looks like this:

{
  "name": "wwv-plugin-iss",
  "version": "1.0.0",
  "main": "dist/index.js",
  "worldwideview": {
    "id": "iss",
    "name": "ISS Live Tracker",
    "version": "1.0.0",
    "icon": "Satellite",
    "category": "space"
  },
  "scripts": { ... }
}

6.2 Publish to NPM

In your plugin terminal, log in to NPM and publish your package:

npm login
npm publish --access public

6.3 Submit to the Marketplace

  1. Go to the official marketplace at https://marketplace.worldwideview.dev/submit.
  2. Type in your package name (wwv-plugin-iss) and click submit.
  3. The system will automatically verify your code. Once approved, any WorldWideView user on the planet can click "Install" to add your ISS tracker to their globe.

Congratulations! You have successfully navigated the entire stack, from API polling and WebSockets to 3D rendering and global publishing.