- Migrated wwv-plugin-gps-jamming to local-plugins and fixed WebSocket payload handling (Patch) - Migrated wwv-plugin-fortiguard to local-plugins and refactored API proxy fetch logic (Patch) - Migrated wwv-plugin-nz-traffic-cameras to local-plugins (Patch) - Cleaned up tutorial plugin wwv-plugin-iss from tree (Patch) - Added scripts/migrate-plugin.mjs for automation (Patch)
3.3 KiB
Development
Overview
Development on WorldWideView prioritizes modularity, high performance, and strict architectural boundaries between the UI and the 3D rendering context. We adhere to rigorous file size constraints and rely heavily on Vanilla CSS and Zustand slice-patterns to maintain clarity across the large ecosystem.
Code Style
File Size Limits
- Max 150 lines per file. If a component or function grows beyond this, you must modularize it. Extract helper functions, split React components, and utilize custom hooks.
Styling Conventions
- Vanilla CSS Only: Do not use Tailwind CSS or CSS-in-JS.
- Global Styles: Located at
src/app/globals.css. - Component Styles: Use CSS Modules (
.module.css) or co-locate.cssfiles directly next to their components. - HUD Animations: Specialized interface animations are stored in
src/styles/hud-animations.css. - Color Theming & Design Tokens: Defined in
src/styles/theme-tokens.cssvia CSS variables (e.g.,[data-theme='black']).
Import Aliases
- Application core:
@/*→./src/* - Plugin SDK:
@worldwideview/wwv-plugin-sdk→./packages/wwv-plugin-sdk/src - Custom plugins use their respective names configured in
tsconfig.json.
Common Patterns
Entity Rendering
When translating raw plugin data into CesiumEntityOptions inside renderEntity(), follow these strict graphical rules:
// Correct Point Pattern
renderEntity(entity: GeoEntity): CesiumEntityOptions {
return {
type: "point",
color: "#ff0000",
size: 10,
outlineColor: "#ffffff",
outlineWidth: 2
};
}
// Correct Billboard Pattern
renderEntity(entity: GeoEntity): CesiumEntityOptions {
return {
type: "billboard",
color: "#ffffff",
iconUrl: "/icons/aircraft.png",
iconScale: 0.5
};
}
Warning
NEVER MIX PROPERTIES: Do not apply
size,outlineWidth, oroutlineColorto abillboardentity. Mixing these parameters causes severe GPU clipping and rendering artifacts in Cesium.
State Access
Zustand is divided into slices. For performance, components must select exactly the properties they need to avoid over-rendering:
// From src/components/panels/LayerPanel.tsx
const activeLayers = useStore((state) => state.layers.active);
const toggleLayer = useStore((state) => state.layers.toggle);
Workflows
Debugging & Temporary Scripts
Whenever generating temporary debugging scripts, testing REST endpoints via .mjs, or dumping traces/JSON outputs, save these exclusively inside /local-scripts/.
- Reference: The root directory is strictly for production configuration files.
Local Plugin & Seeder Testing
When developing a custom seeder for a plugin, place the seeder directory inside local-seeders/. The local wwv-data-engine Docker container automatically mounts this folder and discovers scripts on startup, providing a seamless sandbox.
Scaffold a New Component
- Create a new directory under
src/components/{category}/MyComponent. - Add
MyComponent.tsxandMyComponent.module.css. - Export from a local
index.tsif creating a composite view.
Reference
- Core Abstractions: See
packages/wwv-plugin-sdk/src/PluginTypes.tsfor interface expectations. - State Slices: Located in
src/core/state/(e.g.,globeSlice.ts,dataSlice.ts).