Interface ISystemPluginExperimental

Super experimental — this API may change or be removed in any release without notice. Do not depend on it in production.

Interface for plugins that hook into the Mappedin render loop.

Plugins receive the full renderer state every frame, providing direct access to the Three.js scene, camera, renderer, lighting, and all ECS geometry entities. Use this to inject custom Three.js objects, apply per-frame effects, or read scene state.

Lifecycle

  • update() is called every frame during the finalization phase of the render loop (after camera, path, and 2D systems have run, but before DrawSystem applies style changes and before paint() draws the frame).
  • Plugins are called in registration order.

Standalone vs. Overlay Mode

Concern Standalone MapLibre Overlay
Add meshes to state.threeJSScene state.geometryScene
Camera position Reflects actual viewer position Not reliable — MapLibre overwrites the projection matrix each frame
Coordinate space Scene units (meters from map center) Scene units (meters from map center)

Performance

update() runs on the main thread every frame. Avoid heavy computation, allocations, or GPU-blocking operations. Gate one-time work behind an initialization flag.

Example

Adding a custom Three.js mesh

import { type ISystemPlugin, type TRendererState } from '@mappedin/mappedin-js';
import { Mesh, MeshStandardMaterial, SphereGeometry } from 'three';

class SpherePlugin implements ISystemPlugin {
  private sphere: Mesh | null = null;

  update(state: TRendererState): void {
    // One-time setup — add a sphere to the scene
    if (!this.sphere) {
      const geo = new SphereGeometry(3, 32, 32);
      const mat = new MeshStandardMaterial({ color: 0xff4444 });
      this.sphere = new Mesh(geo, mat);
      // Use geometryScene for overlay mode, threeJSScene for standalone
      state.geometryScene.add(this.sphere);
    }
    this.sphere.rotation.y += 0.01;
  }
}

mapView.registerPlugin(new SpherePlugin());

Example

Reading ECS component data

class InspectorPlugin implements ISystemPlugin {
  update(state: TRendererState): void {
    for (const geometry of state.geometry3DsInScene) {
      const style = geometry.getComponent('style');
      if (style) {
        console.log(geometry.id, style.color, style.opacity);
      }
    }
  }
}

Example

Mutating ECS styles (mark dirty to apply)

class HighlightPlugin implements ISystemPlugin {
  update(state: TRendererState): void {
    for (const geometry of state.geometry3DMap.values()) {
      const style = geometry.getComponent('style');
      if (style) {
        style.color = 'red';
        style.dirty = true; // Required — triggers DrawSystem to apply the change
      }
    }
  }
}
interface ISystemPlugin {
    update(state: TRendererState): void;
}

Methods

update

Methods

update

  • update(state: TRendererState): void
    Experimental

    Called every frame with the current renderer state.

    Parameters

    • state: TRendererState

      The renderer state snapshot for this frame. Contains Three.js objects (threeJSScene, renderer, cameraObject, directionalLight, ambientLight), the geometry scene graph (geometryScene), and all ECS entity maps (geometry3DMap, geometry3DsInScene, geometry2DMap, geometry2DsInScene).

    Returns void

Settings

Member Visibility

On This Page

LifecycleStandalone vs. Overlay ModePerformance
Methods