Skip to content

@pawnjs/maps ​

Not on npm yet

This package comes with a later release of Pawn.

Draws a pawn engine into a Google Maps vector map through WebGLOverlayView. The engine shares the map's WebGL context and ticks on the map's draws.

ts
import { 
Engine
,
Position
,
Visual
} from "@pawnjs/core";
import {
latLngToPosition
,
MapOverlay
} from "@pawnjs/maps";
const
anchor
= {
lat
: 52.2318,
lng
: 21.006 };
const
map
= new google.
maps
.
Map
(
element
, {
center
:
anchor
,
zoom
: 17,
tilt
: 60,
mapId
});
const
overlay
= new
MapOverlay
({
map
,
anchor
});
const
engine
= new
Engine
({
driver
:
overlay
}).
use
(
overlay
);
engine
.
world
.
spawn
(
Position
(
latLngToPosition
(
anchor
, {
lat
: 52.232,
lng
: 21.007 })),
Visual
(
mesh
),
);
engine
.
start
();

MapOverlay is both the engine's loop driver and a plugin: installing it adds its view (overlay.view, a MapView drawn with the map's camera) and hands the map's renderer to the engine.

Requirements ​

  • The map needs a mapId of a vector map; raster maps cannot host WebGL overlays.
  • Load the Maps JavaScript API before creating a MapOverlay. Importing this package does not need it.
  • Use the overlay as the engine's driver. With another driver the engine would draw into the map's context outside the map's draw callback.

MapOverlay options ​

OptionMeaning
mapA vector map (created with a mapId).
anchor{ lat, lng, altitude? }, the geographic point of the engine's origin. overlay.anchor can be changed later; it takes effect on the next draw.
createRenderer(gl) => WebGLRenderer, to customize the renderer (for example to enable shadows). It must keep autoClear off so the map stays visible.
enablePointerWhether the map's events drive the engine's Pointer (see Picking). Defaults to true.

Coordinates ​

Positions are meters from the anchor: x east, y up, -z north.

  • latLngToPosition(anchor, point, target?) converts a geographic point ({ lat, lng, altitude? }) into a position.
  • positionToLatLng(anchor, position) converts back.

Both use a flat approximation on a sphere of EARTH_RADIUS (6378137 m, as in Web Mercator) around the anchor, off by about a meter at 3 km from it and a few meters at 5 km.

Picking ​

The map takes the page's pointer events, so the overlay drives the engine's Pointer from the map's mousemove, mouseout and click events, installing one (without Input) if the engine has none. Pointer clicks, Hoverable and Clickable then work over the map as anywhere else:

ts
engine
.
plugin
(
Pointer
).
on
("click", ({
entity
}) => {
if (
entity
)
select
(
entity
);
});

The map clicks only when it was not dragged, and a drag pans the map, so Draggable does not work on a map. Pass enablePointer: false to drive the pointer yourself. engine.pick(clientX, clientY) still picks through overlay.view from any map listener.

Notes ​

  • With the engine stopped, map draws still render the scene. Call overlay.requestRedraw() after changes.
  • engine.dispose() disposes the overlay's renderer, but the map's context lives on: dispose your geometries and materials first to free their GPU memory.
  • Lighting treats the eye as sitting at the anchor (the map's camera pose is baked into one matrix), so specular highlights and reflections are approximate.

The Maps example shows a pawn and boxes over Warsaw.