---
url: /pawn/docs/packages/maps.md
description: The engine drawn into a Google Maps vector map.
---

# @pawnjs/maps

::: info Not on npm yet
This package comes with a later release of Pawn.
:::

Draws a pawn engine into a [Google Maps](https://developers.google.com/maps/documentation/javascript)
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](../guide/engine#loop-drivers)
and a [plugin](../guide/plugins): 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

| Option | Meaning |
|---|---|
| `map` | A 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. |
| `enablePointer` | Whether the map's events drive the engine's `Pointer` (see [Picking](#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`](../guide/input#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](https://jakubprill.github.io/pawn/maps.html) shows a pawn
and boxes over Warsaw.
