API reference
Everything @dzbot/map exports. With the script tag, the same names live on window.dzmap.
// Classnew DzMap(container, options)
container is an element or a CSS selector; give it a height. The map fills it.
Options
| Name | Type | Meaning |
|---|---|---|
map | string | A built-in map: nasdara (default), chernarus, livonia, sakhal |
tiles | TileSource | Your own tile pyramid instead: { url, size, maxZoom, types? }; url has {z}, {x}, {y}, optionally {type} |
center | [x, z] | Where the map opens, in world metres; default: the middle of the map |
zoom | number | 'cover' | Zoom level (1 = whole map in 256 px, +1 doubles); cover fills the frame with the map. Default 2 |
minZoom / maxZoom | number | Limits; maxZoom never exceeds the tiles (8 for the built-in maps) |
placeNames | boolean | PlaceName[] | true loads the map’s place names from dzbot; an array shows your own { name, x, z, radius? } |
controls | ControlsOptions | Which built-in buttons to show — see Controls. Default: zoom only |
locale | 'en' | 'de' | Language of the button labels |
cursor | string | Cursor over the empty map. Default grab |
doubleClickZoom | boolean | Zoom in on double click / double tap. Default true |
keyboard | boolean | Arrow keys pan, + and − zoom while the map has focus. Default true |
View
| Method | Does |
|---|---|
getView() → { center, zoom } | Where the map is |
setView(center, zoom?, { animate? }) | Moves the map; zoom may be 'cover' |
setZoom(zoom, anchor?) | Zooms, keeping the screen point anchor in place |
zoomIn() / zoomOut() | One level, animated |
panBy(dx, dy) | Moves by pixels |
fitBounds(points, { padding?, maxZoom?, animate? }) | Shows all the points |
project([x, z]) → [px, py] | World metres to pixels in the frame |
unproject([px, py]) → [x, z] | Pixels in the frame to world metres |
setMap(name | TileSource) | Switches the map, keeps the view |
setPlaceNames(true | PlaceName[] | false) | Changes the place names |
setPlaceNamesVisible(boolean) | Shows or hides them without reloading |
setFullscreen(boolean) | Fills the window with the map; Escape leaves |
setControls(options) | Changes the built-in buttons |
setOptions({ cursor, minZoom, maxZoom, doubleClickZoom, keyboard }) | Changes options on a live map |
ruler.start() / stop() / undo() | The ruler without its button, e.g. from your own UI; ruler.onChange(fn) reports the points |
setTool(tool | null) | Hands clicks, long presses and keys to a tool of your own ({ name, click?, contextmenu?, hover?, keydown?, deactivate? }); nothing can be dragged meanwhile |
destroy() | Removes the map and all its listeners |
// DrawingShapes
The quick way to draw. Each call returns a MapObject with update(patch), remove() and the events click, dragstart, drag, dragend.
| Method | Does |
|---|---|
addMarker([x, z], { label?, color?, dot?, area?, draggable? }) | A dot with a label; area: { radius, opacity?, soft? } draws a circle of metres around it |
addPin([x, z], { label?, radius?, draggable? }) | A highlighted spot: ring and dot |
addPolygon(points, { fill?, stroke?, fillOpacity?, strokeStyle?, label? }) | An area; strokeStyle is solid, dotted or none |
addLine(points, { color?, width?, opacity?, endpoints? }) | A route; endpoints marks start and end |
addCircle([x, z], radius, { color?, fillOpacity?, strokeOpacity? }) | A circle of radius metres |
addGeoJSON(objectOrUrl, { fit? }) → Promise<VectorLayer> | GeoJSON in world metres, styled by title/label, marker-color, stroke, fill, fill-opacity, radius |
featuresAt([px, py]) → Feature[] | What is drawn under a point, topmost first |
// ListeningEvents
map.on(name, handler) returns a function that unsubscribes; map.off(name, handler) does the same.
| Event | Data | When |
|---|---|---|
click | PointerEvent | A click or tap that did not move the map |
dblclick | PointerEvent | Call e.preventDefault() to stop the zoom |
contextmenu | PointerEvent | Right click, or a long press on touch |
hover | PointerEvent | null | The pointer rests on the map; null when it leaves |
move | { center, zoom } | The view changed |
render | Frame | A frame was drawn |
dragstart / drag / dragend | { id, world, screen } | A drag target is being moved |
targethover | { id } | The drag target under the pointer changed |
fullscreen | { active } | Fullscreen switched |
placenames | { visible } | Place names shown or hidden |
tool | { name } | A tool (the ruler, yours) started or stopped; null when none is active |
search | { label, at, detail?, zoom? } | A search result was picked |
mapchange | { map } | setMap or the map switcher changed the map |
A PointerEvent has world ([x, z]), screen ([px, py]), features (what is under the pointer), originalEvent and preventDefault().
// ExtendingLayers
A layer is any object with onAdd(map), optionally render(frame) and onRemove(map). Add it with map.addLayer(layer), remove it with map.removeLayer(layer). In onAdd, put your elements into one of the panes from map.getPane(name): tiles, underlay, vector, overlay (bottom to top). render runs once per frame in which something changed.
| Frame | Type | Meaning |
|---|---|---|
frame.zoom | number | Current zoom |
frame.width / height | number | Size of the map in CSS pixels |
frame.scale | number | Pixels per metre |
frame.size | number | Edge of the tile pyramid in metres |
frame.project / unproject | function | World metres ⇄ pixels |
Built-in layers: new VectorLayer(features, pane?) with setFeatures(features); new TileLayer({ url, maxZoom, type?, has?, backdrop? }) for transparent tile overlays.
Drag targets: map.addDragSource(() => targets) registers spots that can be picked up ({ id, at, touch?, reach?, cursor?, swallowClick? }); the map sends dragstart, drag and dragend with the id. The map draws nothing for them — draw them yourself.
// DataFeatures
What a VectorLayer draws. Every feature also takes id, minZoom and maxZoom.
| Feature | Draws |
|---|---|
{ type: 'point', at, color?, dot?, area?, label?, labelColor?, subtitle? } | A dot with a label |
{ type: 'pin', at, label?, radius? } | A highlighted spot |
{ type: 'polygon', points, fill?, stroke?, fillOpacity?, strokeStyle?, fadeOnZoom?, label? } | An area; fadeOnZoom lightens the fill as you zoom in |
{ type: 'line', points, color?, width?, opacity?, endpoints? } | A route |
{ type: 'circle', at, radius, color?, fillOpacity?, strokeOpacity? } | A circle in metres |
{ type: 'place', at, name, radius?, fontSize? } | A place name; hidden with the place names |
{ type: 'handle', at, color? } | A grabbable corner, drawn on top |
Colours: any CSS colour, or one of the map colours red, blue, green, yellow, orange, purple, grey, white, black.
// UIControls
| Name | Type | Meaning |
|---|---|---|
zoom | boolean | ControlOptions | + and − buttons; default on the right |
fullscreen | boolean | ControlOptions | Fullscreen button; default top right |
placeNames | boolean | ControlOptions | Toggles the place names; default top left |
tileType | boolean | ControlOptions | Map / satellite, where the tiles offer both |
ruler | boolean | { stamina?, staminaSource?, panelClassName? } | Measures a route: distance per leg, total, and the time to sprint it (DayZ stamina rules; pass a server’s { max, sprintDrain }). Sits with the zoom buttons |
coordinates | boolean | ControlOptions | The coordinate under the mouse; Ctrl/⌘+C copies it. Hidden on touch screens |
search | boolean | { providers?, placeholder? } | Finds place names, coordinates like 4512 10230, and every labelled feature; providers add your own results |
layers | boolean | ControlOptions | Switches the place names and every layer that has a name |
mapSwitcher | boolean | ControlOptions | Switches between the four built-in maps |
ControlOptions is { position?, className? }; positions are top-left, top-right, bottom-left, bottom-right, left, right. A className without a position lets you place the control yourself. Mark your own elements over the map with data-dzmap-ui so gestures on them never move it.
// React@dzbot/map-react
| Export | Does |
|---|---|
<DzMapView {...options} className style onReady> | Mounts a map; map, tiles, controls, placeNames, cursor and the zoom limits follow prop changes |
useDzMap() | The map of the surrounding DzMapView |
useMapEvent(map, name, handler) | Subscribes with the latest handler |
useMapFrame(map) | The last frame; re-renders on every frame |
useLayer(map, layer) | Adds a layer while the component is mounted |
<MapPane pane> | Renders React content into a pane |
// LookStyling
The map reads CSS variables, so it fits your site: --dzmap-background, --dzmap-font, --dzmap-radius, --dzmap-control-bg, --dzmap-control-fg, --dzmap-control-border, --dzmap-control-border-hover, --dzmap-focus, the map colours --dzmap-red … --dzmap-black, and --dzmap-route, --dzmap-marker, --dzmap-marker-ring, --dzmap-waypoint.
// EmbedEmbed helpers
| Method | Does |
|---|---|
embedUrl(options, base?) | Builds an embed URL — see the embed builder for the parameters |
parseEmbed(search) | Reads one back |
mountEmbed(element, search) | Renders an embed into an element |