Bevy Slippy Tiles

A helper bevy plugin to handle downloading and displaying OpenStreetMap-compliant slippy tiles.

DownloadSlippyTilesEvent can be fired to request one or more slippy tile downloads.

SlippyTileDownloadedEvent is fired when a requested slippy tile has been retrieved successfully. The file path is stored in the event and can be used with the asset loader.

Features

• Automatic tile rendering with configurable reference point
• Control over tile Z-layer for proper rendering order
• Optional transform offset for precise positioning
• Toggle automatic rendering for manual control
• Configurable download settings (concurrency, retries, rate limits)

Example

Here's a snippet showing how to download and display map tiles at a specific location. This app will load a slippy tile and its surrounding 24 tiles at the specified latitude and longitude.

Run with: cargo run --example simple

use bevy::prelude::*;
use bevy_slippy_tiles::*;

const LATITUDE: f64 = 45.4111;
const LONGITUDE: f64 = -75.6980;

fn main() {
    App::new()
        // Configure settings with defaults
        .insert_resource(SlippyTilesSettings {
            reference_latitude: LATITUDE,
            reference_longitude: LONGITUDE,
            ..Default::default()
        })
        .add_plugins(DefaultPlugins)
        .add_plugins(SlippyTilesPlugin)
        .add_systems(Startup, request_slippy_tiles)
        .run();
}

fn request_slippy_tiles(mut commands: Commands, mut download_slippy_tile_events: EventWriter<DownloadSlippyTilesEvent>) {
    commands.spawn(Camera2dBundle::default());
    let slippy_tile_event = DownloadSlippyTilesEvent {
        tile_size: TileSize::Normal,    // Size of tiles - Normal = 256px, Large = 512px
        zoom_level: ZoomLevel::L18,     // Map zoom level (L0 = entire world, L19 = closest)
        coordinates: Coordinates::from_latitude_longitude(LATITUDE, LONGITUDE),
        radius: Radius(2),              // Request surrounding tiles (2 = 25 tiles total)
        use_cache: true,                // Use cached tiles if available
    };
    download_slippy_tile_events.send(slippy_tile_event);
}

Configuration

SlippyTilesSettings

The plugin uses reasonable defaults but can be configured:

• endpoint: The tile server endpoint
• tiles_directory: The tile cache directory (where tiles will end up after being downloaded)
• max_concurrent_downloads: Maximum number of concurrent tile downloads
• max_retries: Maximum number of times a tile download will be retried upon failure
• rate_limit_requests: Maximum number of tile download requests within the rate limit window
• rate_limit_window: The duration of the rate limit window
• reference_latitude/reference_longitude: The geographic point that should appear at Transform(0,0,0) (or at transform_offset if specified)
• transform_offset: Optional Transform to offset where the reference point appears
• z_layer: Z coordinate for rendered tiles, useful for layering with other sprites
• auto_render: Toggle automatic tile rendering (disable for manual control)

SlippyTilesSettings {
    endpoint: "https://tile.openstreetmap.org".into(), // Tile server endpoint
    tiles_directory: "tiles/".into(), // Cache directory
    max_concurrent_downloads: 4, // Concurrent downloads
    max_retries: 3, // Download retry attempts
    rate_limit_requests: 10, // Rate limit requests
    rate_limit_window: Duration::from_secs(1), // Rate limit window
    reference_latitude: 45.4111, // Reference latitude
    reference_longitude: -75.6980, // Reference longitude
    transform_offset: Some( // Optional offset from 0,0 (default: None)
        Transform::from_xyz(100.0, 100.0, 0.0)
    ),
    z_layer: 1.0, // Z coordinate for tiles (default: 0.0)
    auto_render: true, // Enable automatic rendering (default: true)
}

Cargo Features

This crate provides optional Cargo features for customization:

• display (enabled by default): Enables automatic Slippy tile rendering

To disable this feature:

cargo build --no-default-features

Bevy Compatibility