Crate bevy_geo_tiles 

Bevy Geo Tiles

Open street map (or any other slippy map / TMS tile source) integration for Bevy.

This project is work in progress. Expect breaking changes, incomplete features and bugs.

Features

• Load and display map tiles as Bevy textures
• Basic 2D camera controls (pan and zoom)
• Support for custom tile sources
• File system caching of downloaded tiles
• Basic support for markers, polylines, and polygons
• local-origin for improved precision (avoiding f32 float precision issues at very large coordinates)
• Coordinate conversion between WGS84, Web Mercator and bevy world coordinates
• Tile-loading in a separate thread to avoid blocking the main thread
• Each tile is an individual ECS entity allowing bevy to handle things like frustum culling automatically.

Optional features

• bevy_pancam - Use bevy_pancam for camera controls instead of the minimalistic built-in controls.
• shapes - Enable drawing polylines and polygons using lyon.
• debug_draw - Enable displaying Bevy, Web-Mercator and WGS84 coordinates at the mouse cursor for debugging purposes.

Quick start

Add the crate to Cargo.toml and register the MapPlugin alongside Bevy’s default plugins:

use bevy::prelude::*;
use bevy_geo_tiles::MapPlugin;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(MapPlugin::default())
        .run();
}

For more examples, see the examples folder.

Coordinate systems

• Mercator space uses DVec2/DVec3 in meters relative to the Web Mercator map projection.
• Local space is Bevy’s world coordinate system (floating point Vec2/Vec3).

The LocalOrigin resource tracks the current offset between the two and recenters automatically when the camera drifts too far from the origin.

See MapPlugin for configuration options, including tile server customization and cache settings.

Limitations

• only supports 2D views (orthographic camera).
• no support for WASM targets (tile fetching and file system caching need to be adapted, PRs welcome).
• only supports 256x256 raster tiles.

Compatibility

bevy	bevy_geo_tiles
0.18	0.2
0.17	0.1

License

This project is dual-licensed:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

Contribution

Contributions are welcome! Please open issues or pull requests on the GitHub repository.

Structs

KeepDisplaySize

Marker component to keep the display size of an entity constant when zooming in/out

LocalOrigin

Local origin in web mercator coordinates and the distance at which to recenter.

LocalSpace

Marker component for entities in local space (relative to the LocalOrigin).

MainCam

Marker component for the main camera

MapPlugin

Bevy plugin for displaying slippy map tiles from a tile server (e.g. OpenStreetMap).

MercatorAabb2d

Axis-aligned bounding box in web mercator coordinates, uses DVec2 for min and max.

MercatorCoords

Web mercator coordinates (EPSG:3857) stored in a DVec3 (x, y, z).

Tile

TileFetchConfig

Configuration for downloading map tiles.

TileTextureError

ViewportConv

Constants

MIN_ORTHO_SCALE

SCALE_ZOOM_OFFSET

TILE_SIZE

ZOOM_RANGE

Traits

LocalOriginConversion

Trait to convert between local Bevy world coordinates and web mercator or lon/lat coordinates, given a LocalOrigin.

ToBBox

ToTileCoords

WebMercatorConversion