Bevy Ecs Tilemap

https://github.com/stararawn/bevy_ecs_tilemap
Admin
A Bevy plugin for rendering tilemaps with a tile-per-entity approach, offering fast rendering,...
Tokens:11,013
Snippets:59
Trust Score:-
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Run Basic Example

Source: https://github.com/stararawn/bevy_ecs_tilemap/blob/main/README.md

Execute the basic tilemap example using cargo. This is the simplest way to get started.

```bash
cargo run --release --example basic
```

--------------------------------

### Run Animation Example (WebGL2)

Source: https://github.com/stararawn/bevy_ecs_tilemap/blob/main/README.md

Compile and run the animation example for WebGL2 target using wasm32-unknown-unknown.

```bash
cargo run --target wasm32-unknown-unknown --example animation
```

--------------------------------

### Run Animation Example (WebGPU)

Source: https://github.com/stararawn/bevy_ecs_tilemap/blob/main/README.md

Compile and run the animation example for WebGPU target, enabling the bevy/webgpu feature.

```bash
cargo run --example animation --target=wasm32-unknown-unknown --features=bevy/webgpu
```

--------------------------------

### Accessing and Modifying Tiles with TileStorage

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Demonstrates how to use TileStorage for efficient tile entity lookup by position. Includes safe direct gets, bounds-checked gets, and iteration over tile slots. Ensure TilePos is within map bounds for direct access.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn access_tiles(
    tilemap_q: Query<&TileStorage>,
    mut tile_q: Query<&mut TileTextureIndex>,
) {
    for tile_storage in tilemap_q.iter() {
        // Safe direct get — panics if pos is out of bounds
        if let Some(entity) = tile_storage.get(&TilePos { x: 0, y: 0 }) {
            if let Ok(mut idx) = tile_q.get_mut(entity) {
                idx.0 = 3;
            }
        }

        // Bounds-checked get — returns None for out-of-bounds positions
        let oob = TilePos { x: 9999, y: 9999 };
        assert!(tile_storage.checked_get(&oob).is_none());

        // Iterate over all tile slots (Some = occupied, None = empty)
        let occupied: usize = tile_storage.iter().filter(|s| s.is_some()).count();
        println!("Occupied tiles: {occupied}");
    }
}

fn remove_tile(
    mut tilemap_q: Query<&mut TileStorage>,
    mut commands: Commands,
) {
    for mut tile_storage in tilemap_q.iter_mut() {
        if let Some(entity) = tile_storage.remove(&TilePos { x: 2, y: 2 }) {
            commands.entity(entity).despawn();
        }
    }
}
```

--------------------------------

### Spawning Isometric Tilemaps

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Example of spawning an isometric tilemap using the Diamond coordinate system. Requires a specific texture file for isometric tiles.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn spawn_iso_map(mut commands: Commands, asset_server: Res<AssetServer>) {
    let map_size = TilemapSize { x: 8, y: 8 };
    let tilemap_entity = commands.spawn_empty().id();
    let mut tile_storage = TileStorage::empty(map_size);

    fill_tilemap(
        TileTextureIndex(0),
        map_size,
        TilemapId(tilemap_entity),
        &mut commands,
        &mut tile_storage,
    );

    commands.entity(tilemap_entity).insert(TilemapBundle {
        grid_size: TilemapGridSize { x: 100.0, y: 50.0 },
        map_type: TilemapType::Isometric(IsoCoordSystem::Diamond),
        size: map_size,
        storage: tile_storage,
        texture: TilemapTexture::Single(asset_server.load("bw-tile-iso.png")),
        tile_size: TilemapTileSize { x: 100.0, y: 50.0 },
        anchor: TilemapAnchor::Center,
        ..Default::default()
    });
}
```

--------------------------------

### Spawning Hexagonal Tilemaps

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Example of spawning a hexagonal tilemap with pointy-top tiles and row-based coordinates. Requires a specific texture file for hex tiles.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn spawn_hex_map(mut commands: Commands, asset_server: Res<AssetServer>) {
    let map_size = TilemapSize { x: 10, y: 10 };
    let tilemap_entity = commands.spawn_empty().id();
    let mut tile_storage = TileStorage::empty(map_size);

    fill_tilemap(
        TileTextureIndex(0),
        map_size,
        TilemapId(tilemap_entity),
        &mut commands,
        &mut tile_storage,
    );

    // Pointy-top hex tiles with row-based coordinates
    commands.entity(tilemap_entity).insert(TilemapBundle {
        grid_size: TilemapGridSize { x: 50.0, y: 58.0 },
        map_type: TilemapType::Hexagon(HexCoordSystem::Row),
        size: map_size,
        storage: tile_storage,
        texture: TilemapTexture::Single(asset_server.load("bw-tile-hex-row.png")),
        tile_size: TilemapTileSize { x: 50.0, y: 58.0 },
        anchor: TilemapAnchor::Center,
        ..Default::default()
    });
}
```

--------------------------------

### Spawning an Animated Tile

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Adds an individual tile entity with the AnimatedTile component to enable GPU-driven animation. The animation range is defined by `start` (inclusive) and `end` (exclusive) atlas frame indices, and `speed` controls the animation rate.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*
use bevy_ecs_tilemap::tiles::{AnimatedTile, TileBundle, TileTextureIndex};

fn spawn_animated_tile(
    mut commands: Commands,
    tilemap_entity: Entity,
    tile_storage: &mut TileStorage,
) {
    let tile_pos = TilePos { x: 5, y: 5 };
    commands.spawn((
        TileBundle {
            position: tile_pos,
            tilemap_id: TilemapId(tilemap_entity),
            texture_index: TileTextureIndex(0),
            ..Default::default()
        },
        AnimatedTile {
            start: 0,   // first frame index in atlas (inclusive)
            end: 13,    // last frame index in atlas (exclusive)
            speed: 0.95,
        },
    ));
}
```

--------------------------------

### Get Hex Grid Neighbors

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Retrieves up to six neighbors for a tile in a hexagonal grid. Use specific `_row_even`, `_row_odd`, etc. variants for performance if the coordinate system is known. `.entities()` converts positions to entities.

```rust
use bevy::prelude::*;
use bevy_ecs_tilemap::helpers::hex_grid::neighbors::{HexNeighbors, HexDirection};
use bevy_ecs_tilemap::prelude::*;

fn paint_hex_neighbors(
    tilemap_q: Query<(&TileStorage, &TilemapSize, &TilemapType)>,
    mut tile_q: Query<&mut TileTextureIndex>,
) {
    for (tile_storage, map_size, map_type) in tilemap_q.iter() {
        if let TilemapType::Hexagon(coord_sys) = map_type {
            let center = TilePos { x: 4, y: 4 };

            // Generic dispatch across all hex coord systems
            let neighbors =
                HexNeighbors::get_neighboring_positions(&center, map_size, coord_sys);

            for entity in neighbors.entities(tile_storage).iter() {
                if let Ok(mut idx) = tile_q.get_mut(*entity) {
                    idx.0 = 1;
                }
            }

            // Direction-specific access
            if let Some(pos) = neighbors.get(HexDirection::Zero) {
                println!("Hex direction 0 neighbor: {:?}", pos);
            }
        }
    }
}
```

--------------------------------

### Get Square Grid Neighbors

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Retrieves up to eight directional neighbors for a tile in a square grid. Pass `include_diagonals: false` for cardinal directions only. Use `.entities()` to convert positions to entities.

```rust
use bevy::prelude::*;
use bevy_ecs_tilemap::helpers::square_grid::neighbors::{Neighbors, SquareDirection};
use bevy_ecs_tilemap::prelude::*;

fn highlight_neighbors(
    tilemap_q: Query<(&TileStorage, &TilemapSize)>,
    mut tile_q: Query<&mut TileTextureIndex>,
) {
    for (tile_storage, map_size) in tilemap_q.iter() {
        let center = TilePos { x: 5, y: 5 };

        // Get all 8 neighbors (including diagonals)
        let neighbors = Neighbors::get_square_neighboring_positions(&center, map_size, true);

        for neighbor_entity in neighbors.entities(tile_storage).iter() {
            if let Ok(mut idx) = tile_q.get_mut(*neighbor_entity) {
                idx.0 = 3; // highlight neighbor tile
            }
        }

        // Access a specific direction
        if let Some(north_pos) = neighbors.get(SquareDirection::North) {
            println!("North neighbor: {:?}", north_pos);
        }

        // Cardinal-only neighbors (4-connected)
        let cardinal = Neighbors::get_square_neighboring_positions(&center, map_size, false);
        assert!(cardinal.north_east.is_none()); // diagonal excluded
    }
}
```

--------------------------------

### Dynamically Update Tile Textures and Positions

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Demonstrates updating tile properties like texture index and position at runtime using ECS queries. Change detection ensures efficient GPU updates.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*
use bevy_ecs_tilemap::tiles::AnimatedTile;

// Example: randomly cycle tile textures at 5 Hz
fn randomize_tiles(
    time: Res<Time>,
    mut query: Query<(&mut TileTextureIndex, &TilePos)>, // Changed from &mut TileTextureIndex, &TilePos
) {
    let t = time.elapsed_secs();
    for (mut idx, pos) in query.iter_mut() {
        if (t * 5.0) as u32 % 2 == 0 {
            idx.0 = (pos.x + pos.y) % 6;
        }
    }
}

// Example: move a tile without despawning/respawning
fn move_tile(keyboard: Res<ButtonInput<KeyCode>>, mut query: Query<&mut TilePos>) {
    if keyboard.just_pressed(KeyCode::ArrowRight) {
        for mut pos in query.iter_mut() {
            pos.x += 1;
        }
    }
}

// Example: apply game damage to a tile's texture
#[derive(Component)]
struct Damage(u32);

const TILE_DAMAGE_OFFSET: u32 = 10;

fn update_damage(mut query: Query<(&mut TileTextureIndex, &Damage), Changed<Damage>>) {
    for (mut texture, damage) in query.iter_mut() {
        texture.0 = TILE_DAMAGE_OFFSET + damage.0;
    }
}

```

--------------------------------

### Spawn Tilemaps with Different Anchors

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Demonstrates spawning tilemaps with various anchor points. The anchor determines the pivot point of the tilemap relative to its transform.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn spawn_anchored_tilemaps(mut commands: Commands, asset_server: Res<AssetServer>) {
    let texture = TilemapTexture::Single(asset_server.load("tiles.png"));
    let tile_size = TilemapTileSize { x: 16.0, y: 16.0 };
    let map_size = TilemapSize { x: 10, y: 10 };

    // Helper macro to reduce repetition
    let mut spawn = |anchor: TilemapAnchor, z: f32| {
        let entity = commands.spawn_empty().id();
        let mut storage = TileStorage::empty(map_size);
        fill_tilemap(TileTextureIndex(0), map_size, TilemapId(entity), &mut commands, &mut storage);
        commands.entity(entity).insert(TilemapBundle {
            grid_size: tile_size.into(),
            map_type: TilemapType::Square,
            size: map_size,
            storage,
            texture: texture.clone(),
            tile_size,
            anchor,
            transform: Transform::from_xyz(0.0, 0.0, z),
            ..Default::default()
        });
    };

    spawn(TilemapAnchor::Center, 0.0);        // centered on origin
    spawn(TilemapAnchor::BottomLeft, 1.0);    // bottom-left corner at origin
    spawn(TilemapAnchor::TopRight, 2.0);      // top-right corner at origin
    spawn(TilemapAnchor::Custom(Vec2::new(0.25, -0.1)), 3.0); // custom fractional anchor
}
```

--------------------------------

### TilemapPlugin — Register the plugin

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

The `TilemapPlugin` is a Bevy `Plugin` that must be added to an `App` to enable tilemap rendering and position-tracking systems. Without it, tilemaps will be spawned but not rendered.

```APIDOC
## TilemapPlugin — Register the plugin

### Description
The `TilemapPlugin` is a Bevy `Plugin` that must be added to an `App` to enable tilemap rendering and position-tracking systems. Without it, tilemaps will be spawned but not rendered.

### Usage
```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn main() {
    App::new()
        .add_plugins(DefaultPlugins.set(ImagePlugin::default_nearest()))
        .add_plugins(TilemapPlugin)           // <-- required
        .add_systems(Startup, setup)
        .run();
}

fn setup(mut commands: Commands) {
    commands.spawn(Camera2d);
}
```
```

--------------------------------

### Register TilemapPlugin

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Add TilemapPlugin to your Bevy App to enable tilemap rendering and position-tracking systems. This is required for tilemaps to be rendered.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn main() {
    App::new()
        .add_plugins(DefaultPlugins.set(ImagePlugin::default_nearest()))
        .add_plugins(TilemapPlugin)           // <-- required
        .add_systems(Startup, setup)
        .run();
}

fn setup(mut commands: Commands) {
    commands.spawn(Camera2d);
}
```

--------------------------------

### TileBundle — Spawn a tile entity

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

`TileBundle` is the bundle spawned for each individual tile. It includes components for position, tilemap association, texture, color, visibility, and flip state.

```APIDOC
## TileBundle — Spawn a tile entity

### Description
`TileBundle` is the bundle spawned for each individual tile. Key fields are `position` (`TilePos`), `tilemap_id` (`TilemapId`), `texture_index` (`TileTextureIndex`), `color` (`TileColor`), `visible` (`TileVisible`), and `flip` (`TileFlip`).

### Usage
```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn spawn_single_tile(mut commands: Commands, tilemap_entity: Entity, storage: &mut TileStorage) {
    let tile_pos = TilePos { x: 3, y: 7 };
    let tile_entity = commands
        .spawn(TileBundle {
            position: tile_pos,
            tilemap_id: TilemapId(tilemap_entity),
            texture_index: TileTextureIndex(5),           // atlas frame index
            color: TileColor(Color::srgba(1.0, 0.5, 0.5, 1.0)), // red tint
            visible: TileVisible(true),
            flip: TileFlip { x: false, y: true, d: false }, // flip vertically
            ..Default::default()
        })
        .id();
    storage.set(&tile_pos, tile_entity);
}
```
```

--------------------------------

### Spawn Individual Tile Entity with TileBundle

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Use TileBundle to spawn individual tile entities. Key fields include position, tilemap_id, texture_index, color, visibility, and flip flags. Ensure the tilemap_id references an existing tilemap entity.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn spawn_single_tile(mut commands: Commands, tilemap_entity: Entity, storage: &mut TileStorage) {
    let tile_pos = TilePos { x: 3, y: 7 };
    let tile_entity = commands
        .spawn(TileBundle {
            position: tile_pos,
            tilemap_id: TilemapId(tilemap_entity),
            texture_index: TileTextureIndex(5),           // atlas frame index
            color: TileColor(Color::srgba(1.0, 0.5, 0.5, 1.0)), // red tint
            visible: TileVisible(true),
            flip: TileFlip { x: false, y: true, d: false }, // flip vertically
            ..Default::default()
        })
        .id();
    storage.set(&tile_pos, tile_entity);
}
```

--------------------------------

### Spawn Tilemap with Vector Textures

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Spawns a tilemap using `TilemapTexture::Vector`, where each tile frame is a separate image asset. All images must match the `TilemapTileSize`.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn spawn_texture_vec_map(mut commands: Commands, asset_server: Res<AssetServer>) {
    let handles: Vec<Handle<Image>> = (1..=6) 
        .map(|i| asset_server.load(format!("individual/tile-0{i}.png")))
        .collect();

    let map_size = TilemapSize { x: 8, y: 8 };
    let tilemap_entity = commands.spawn_empty().id();
    let mut tile_storage = TileStorage::empty(map_size);

    fill_tilemap(TileTextureIndex(0), map_size, TilemapId(tilemap_entity), &mut commands, &mut tile_storage);

    commands.entity(tilemap_entity).insert(TilemapBundle {
        grid_size: TilemapGridSize { x: 32.0, y: 32.0 },
        map_type: TilemapType::Square,
        size: map_size,
        storage: tile_storage,
        texture: TilemapTexture::Vector(handles), // one image per tile frame
        tile_size: TilemapTileSize { x: 32.0, y: 32.0 },
        anchor: TilemapAnchor::Center,
        ..Default::default()
    });
}

```

--------------------------------

### Spawn Tilemap with Custom Chunk Size

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Configures a tilemap with custom render chunk size. Smaller chunks are beneficial for frequently changing maps, while larger chunks are better for static maps.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn spawn_with_custom_chunks(mut commands: Commands, asset_server: Res<AssetServer>) {
    let map_size = TilemapSize { x: 512, y: 512 };
    let tilemap_entity = commands.spawn_empty().id();
    let mut tile_storage = TileStorage::empty(map_size);

    fill_tilemap(
        TileTextureIndex(0), map_size, TilemapId(tilemap_entity),
        &mut commands, &mut tile_storage,
    );

    commands.entity(tilemap_entity).insert(TilemapBundle {
        grid_size: TilemapGridSize { x: 16.0, y: 16.0 },
        map_type: TilemapType::Square,
        size: map_size,
        storage: tile_storage,
        texture: TilemapTexture::Single(asset_server.load("tiles.png")),
        tile_size: TilemapTileSize { x: 16.0, y: 16.0 },
        // Use 16×16 tile chunks for a map that changes often
        render_settings: TilemapRenderSettings {
            render_chunk_size: bevy::math::UVec2::new(16, 16),
            y_sort: false,
        },
        anchor: TilemapAnchor::Center,
        ..Default::default()
    });
}
```

--------------------------------

### Fill Entire Tilemap with One Tile Type

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Use `fill_tilemap` to initialize a map with a single tile type across all positions. Ensure `TileStorage` is correctly set up before calling.

```Rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn startup(mut commands: Commands, asset_server: Res<AssetServer>) {
    let map_size = TilemapSize { x: 32, y: 32 };
    let tilemap_entity = commands.spawn_empty().id();
    let mut tile_storage = TileStorage::empty(map_size);

    // Fills all 32×32 positions with texture index 0
    fill_tilemap(
        TileTextureIndex(0),
        map_size,
        TilemapId(tilemap_entity),
        &mut commands,
        &mut tile_storage,
    );

    let tile_size = TilemapTileSize { x: 16.0, y: 16.0 };
    commands.entity(tilemap_entity).insert(TilemapBundle {
        grid_size: tile_size.into(),
        map_type: TilemapType::Square,
        size: map_size,
        storage: tile_storage,
        texture: TilemapTexture::Single(asset_server.load("tiles.png")),
        tile_size,
        anchor: TilemapAnchor::Center,
        ..Default::default()
    });
}
```

--------------------------------

### Spawn Isometric Tilemap with Y-Sorting Enabled

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Spawns an isometric tilemap and enables y-sorting for depth-based sorting in 3D views. This is useful for creating a 3D isometric effect.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn spawn_isometric_ysort(mut commands: Commands, asset_server: Res<AssetServer>) {
    let map_size = TilemapSize { x: 16, y: 16 };
    let tilemap_entity = commands.spawn_empty().id();
    let mut tile_storage = TileStorage::empty(map_size);
    fill_tilemap(TileTextureIndex(0), map_size, TilemapId(tilemap_entity), &mut commands, &mut tile_storage);

    commands.entity(tilemap_entity).insert(TilemapBundle {
        grid_size: TilemapGridSize { x: 96.0, y: 48.0 },
        map_type: TilemapType::Isometric(IsoCoordSystem::Diamond),
        size: map_size,
        storage: tile_storage,
        texture: TilemapTexture::Single(asset_server.load("isometric-sheet.png")),
        tile_size: TilemapTileSize { x: 96.0, y: 48.0 },
        render_settings: TilemapRenderSettings {
            render_chunk_size: bevy::math::UVec2::new(4, 1),
            y_sort: true,   // enables depth-based sorting for 3D iso look
        },
        ..Default::default()
    });
}
```

--------------------------------

### Toggle Frustum Culling at Runtime

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Query for `FrustumCulling` components and toggle their boolean value when a specific key is pressed. This allows dynamic control over frustum culling during gameplay. Ensure `bevy::prelude::*`, `bevy_ecs_tilemap::prelude::*`, and `bevy_ecs_tilemap::FrustumCulling` are imported.

```rust
// Toggle frustum culling at runtime
fn toggle_culling(
    keyboard: Res<ButtonInput<KeyCode>>,
    mut query: Query<&mut FrustumCulling>,
) {
    if keyboard.just_pressed(KeyCode::KeyC) {
        for mut culling in query.iter_mut() {
            culling.0 = !culling.0;
            println!("Frustum culling: {}", culling.0);
        }
    }
}
```

--------------------------------

### Spawn Tilemap Entity with TilemapBundle

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Use TilemapBundle to spawn a tilemap entity, grouping essential components like size, type, storage, and texture. Pre-spawn the tilemap entity before spawning individual tiles.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn startup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Camera2d);

    let texture_handle: Handle<Image> = asset_server.load("tiles.png");
    let map_size = TilemapSize { x: 32, y: 32 };

    // Pre-spawn the tilemap entity so tile entities can reference it via TilemapId.
    let tilemap_entity = commands.spawn_empty().id();
    let mut tile_storage = TileStorage::empty(map_size);

    for x in 0..map_size.x {
        for y in 0..map_size.y {
            let tile_pos = TilePos { x, y };
            let tile_entity = commands
                .spawn(TileBundle {
                    position: tile_pos,
                    tilemap_id: TilemapId(tilemap_entity),
                    ..Default::default()
                })
                .id();
            tile_storage.set(&tile_pos, tile_entity);
        }
    }

    let tile_size = TilemapTileSize { x: 16.0, y: 16.0 };
    let grid_size: TilemapGridSize = tile_size.into();

    commands.entity(tilemap_entity).insert(TilemapBundle {
        grid_size,
        map_type: TilemapType::Square,
        size: map_size,
        storage: tile_storage,
        texture: TilemapTexture::Single(texture_handle),
        tile_size,
        anchor: TilemapAnchor::Center,   // center the map on the transform origin
        ..Default::default()
    });
}
```

--------------------------------

### Generate Hexagonal Regions for Tilemaps

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Use `fill_tilemap_hexagon` to directly populate a hexagonal area. `generate_hexagon` and `generate_hex_ring` provide `AxialPos` vectors for manual tile spawning, skipping out-of-bounds tiles.

```Rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*
use bevy_ecs_tilemap::helpers::filling::{fill_tilemap_hexagon, generate_hexagon, generate_hex_ring};
use bevy_ecs_tilemap::helpers::hex_grid::axial::AxialPos;

fn spawn_hex_region(mut commands: Commands, asset_server: Res<AssetServer>) {
    let map_size = TilemapSize { x: 16, y: 16 };
    let tilemap_entity = commands.spawn_empty().id();
    let mut tile_storage = TileStorage::empty(map_size);
    let coord_sys = HexCoordSystem::Row;

    // Fills a hexagonal "blob" of radius 4 centred on tile (8,8)
    fill_tilemap_hexagon(
        TileTextureIndex(0),
        TilePos { x: 8, y: 8 },
        4,
        coord_sys,
        TilemapId(tilemap_entity),
        &mut commands,
        &mut tile_storage,
    );

    // Generate ring positions (radius=2) for manual processing
    let origin = AxialPos { q: 0, r: 0 };
    let ring: Vec<AxialPos> = generate_hex_ring(origin, 2);
    println!("Ring has {} positions", ring.len()); // 12

    // Generate full hexagon positions (radius=3)
    let hex_area: Vec<AxialPos> = generate_hexagon(origin, 3);
    println!("Hexagon has {} positions", hex_area.len()); // 37

    commands.entity(tilemap_entity).insert(TilemapBundle {
        grid_size: TilemapGridSize { x: 50.0, y: 58.0 },
        map_type: TilemapType::Hexagon(coord_sys),
        size: map_size,
        storage: tile_storage,
        texture: TilemapTexture::Single(asset_server.load("bw-tile-hex-row.png")),
        tile_size: TilemapTileSize { x: 50.0, y: 58.0 },
        anchor: TilemapAnchor::Center,
        ..Default::default()
    });
}
```

--------------------------------

### Spawn Layered Tilemaps

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Spawns multiple tilemap entities with different Z-transforms to create layers. Each layer has its own TileStorage and texture.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn spawn_layered_map(mut commands: Commands, asset_server: Res<AssetServer>) {
    let texture = asset_server.load("tiles.png");
    let map_size = TilemapSize { x: 32, y: 32 };
    let tile_size = TilemapTileSize { x: 16.0, y: 16.0 };
    let grid_size: TilemapGridSize = tile_size.into();
    let map_type = TilemapType::Square;

    // --- Layer 0: ground ---
    let e0 = commands.spawn_empty().id();
    let mut s0 = TileStorage::empty(map_size);
    fill_tilemap(TileTextureIndex(0), map_size, TilemapId(e0), &mut commands, &mut s0);
    commands.entity(e0).insert(TilemapBundle {
        grid_size, map_type, size: map_size, storage: s0,
        texture: TilemapTexture::Single(texture.clone()),
        tile_size,
        anchor: TilemapAnchor::Center,
        transform: Transform::from_xyz(0.0, 0.0, 0.0),
        ..Default::default()
    });

    // --- Layer 1: decoration (z=1, offset so it overlaps correctly) ---
    let e1 = commands.spawn_empty().id();
    let mut s1 = TileStorage::empty(map_size);
    fill_tilemap(TileTextureIndex(2), map_size, TilemapId(e1), &mut commands, &mut s1);
    commands.entity(e1).insert(TilemapBundle {
        grid_size, map_type, size: map_size, storage: s1,
        texture: TilemapTexture::Single(texture.clone()),
        tile_size,
        anchor: TilemapAnchor::Center,
        transform: Transform::from_xyz(0.0, 0.0, 1.0),
        ..Default::default()
    });
}

```

--------------------------------

### TilemapBundle / MaterialTilemapBundle — Spawn a tilemap entity

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

`TilemapBundle` (a type alias for `MaterialTilemapBundle<StandardTilemapMaterial>`) is the bundle inserted onto the tilemap entity. It groups all required components for a tilemap.

```APIDOC
## TilemapBundle / MaterialTilemapBundle — Spawn a tilemap entity

### Description
`TilemapBundle` (a type alias for `MaterialTilemapBundle<StandardTilemapMaterial>`) is the bundle inserted onto the tilemap entity. It groups all required components: `TilemapSize`, `TilemapTileSize`, `TilemapGridSize`, `TilemapSpacing`, `TilemapTexture`, `TilemapType`, `TileStorage`, `Transform`, `TilemapRenderSettings`, `Visibility`, `FrustumCulling`, and `TilemapAnchor`.

### Usage
```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*

fn startup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(Camera2d);

    let texture_handle: Handle<Image> = asset_server.load("tiles.png");
    let map_size = TilemapSize { x: 32, y: 32 };

    // Pre-spawn the tilemap entity so tile entities can reference it via TilemapId.
    let tilemap_entity = commands.spawn_empty().id();
    let mut tile_storage = TileStorage::empty(map_size);

    for x in 0..map_size.x {
        for y in 0..map_size.y {
            let tile_pos = TilePos { x, y };
            let tile_entity = commands
                .spawn(TileBundle {
                    position: tile_pos,
                    tilemap_id: TilemapId(tilemap_entity),
                    ..Default::default()
                })
                .id();
            tile_storage.set(&tile_pos, tile_entity);
        }
    }

    let tile_size = TilemapTileSize { x: 16.0, y: 16.0 };
    let grid_size: TilemapGridSize = tile_size.into();

    commands.entity(tilemap_entity).insert(TilemapBundle {
        grid_size,
        map_type: TilemapType::Square,
        size: map_size,
        storage: tile_storage,
        texture: TilemapTexture::Single(texture_handle),
        tile_size,
        anchor: TilemapAnchor::Center,   // center the map on the transform origin
        ..Default::default()
    });
}
```
```

--------------------------------

### Convert World Position to Tile Position

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Converts a 2D world-space position to a tile position for any map type and anchor. Returns `None` if the position is outside the map boundaries. Useful for mouse picking and interaction.

```rust
use bevy::{math::Vec4Swizzles, prelude::*};
use bevy_ecs_tilemap::prelude::*;

#[derive(Resource, Default)]
struct CursorPos(Vec2);

fn update_cursor_pos(
    camera_q: Query<(&GlobalTransform, &Camera)>,
    mut cursor_events: EventReader<CursorMoved>,
    mut cursor_pos: ResMut<CursorPos>,
) {
    for ev in cursor_events.read() {
        for (cam_transform, cam) in camera_q.iter() {
            if let Ok(pos) = cam.viewport_to_world_2d(cam_transform, ev.position) {
                cursor_pos.0 = pos;
            }
        }
    }
}

fn highlight_hovered_tile(
    cursor_pos: Res<CursorPos>,
    tilemap_q: Query<(
        &TilemapSize, &TilemapGridSize, &TilemapTileSize,
        &TilemapType, &TileStorage, &Transform, &TilemapAnchor,
    )>,
    mut tile_q: Query<&mut TileColor>,
) {
    for (map_size, grid_size, tile_size, map_type, storage, transform, anchor) in tilemap_q.iter() {
        // Convert cursor to map-local space
        let cursor = Vec4::from((cursor_pos.0, 0.0, 1.0));
        let local = (transform.to_matrix().inverse() * cursor).xy();

        if let Some(tile_pos) =
            TilePos::from_world_pos(&local, map_size, grid_size, tile_size, map_type, anchor)
        {
            if let Some(entity) = storage.get(&tile_pos) {
                if let Ok(mut color) = tile_q.get_mut(entity) {
                    color.0 = Color::srgb(1.0, 0.0, 0.0);
                }
            }
        }
    }
}
```

--------------------------------

### Fill Rectangular Sub-Region of Tilemap

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Use `fill_tilemap_rect` to populate a specific rectangular area with a given tile texture. `fill_tilemap_rect_color` additionally applies a uniform color overlay to the region.

```Rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*
use bevy_ecs_tilemap::helpers::filling::{fill_tilemap_rect, fill_tilemap_rect_color};

fn create_colored_region(
    mut commands: Commands,
    tilemap_entity: Entity,
    tile_storage: &mut TileStorage,
) {
    // Plain rectangle: 5×3 block starting at (2,2)
    fill_tilemap_rect(
        TileTextureIndex(1),
        TilePos { x: 2, y: 2 },
        TilemapSize { x: 5, y: 3 },
        TilemapId(tilemap_entity),
        &mut commands,
        tile_storage,
    );

    // Colored rectangle: semi-transparent blue overlay
    fill_tilemap_rect_color(
        TileTextureIndex(2),
        TilePos { x: 8, y: 8 },
        TilemapSize { x: 4, y: 4 },
        Color::srgba(0.2, 0.4, 1.0, 0.7),
        TilemapId(tilemap_entity),
        &mut commands,
        tile_storage,
    );
}
```

--------------------------------

### Toggling Tile Animation Pause

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Pauses or resumes tile animations by toggling the `speed` property of the AnimatedTile component between 0.0 and 1.0 when the 'P' key is pressed.

```rust
// Toggle animation pause with keypress
fn pause_animation(mut query: Query<&mut AnimatedTile>, keys: Res<ButtonInput<KeyCode>>) {
    if keys.just_pressed(KeyCode::KeyP) {
        for mut anim in &mut query {
            anim.speed = if anim.speed == 0.0 { 1.0 } else { 0.0 };
        }
    }
}
```

--------------------------------

### Update Tile Texture Based on Damage

Source: https://github.com/stararawn/bevy_ecs_tilemap/blob/main/README.md

This system updates a tile's texture based on a 'Damage' component. Ensure the 'Damage' struct and 'TILE_DAMAGE_OFFSET' constant are defined elsewhere. It only processes tiles that have changed their 'Damage' component.

```rust
struct Damage {
    amount: u32,
}

fn update_damage(
    mut query: Query<(&mut TileTexture, &Damage), Changed<Damage>>,
) {
    for (mut tile_texture, damage) in query.iter_mut() {
        tile_texture.0 = TILE_DAMAGE_OFFSET + damage.amount;
    }
}
```

--------------------------------

### HexNeighbors<TilePos>::get_neighboring_positions

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Finds up to six neighbors for a tile in a hexagonal grid. Offers specialized variants for different coordinate systems for performance.

```APIDOC
## HexNeighbors<TilePos>::get_neighboring_positions

### Description
Returns up to six neighbors for any hex coordinate system. Specialized variants like `_row_even`, `_row_odd`, `_col_even`, `_col_odd` are available for known coordinate systems to avoid runtime matching.

### Method
`HexNeighbors::get_neighboring_positions(center: &TilePos, map_size: &TilemapSize, coord_sys: &TilemapCoordinateSystem) -> HexNeighbors<TilePos>`

### Parameters
- `center` (TilePos): The central tile position.
- `map_size` (TilemapSize): The size of the tilemap.
- `coord_sys` (TilemapCoordinateSystem): The coordinate system of the hex grid (e.g., `HexCoordSystem::RowEven`).

### Usage
- `.entities(tile_storage)`: Converts neighbor positions to `HexNeighbors<Entity>`.
- `.get(direction)`: Retrieves a specific neighbor by `HexDirection`.

### Example
```rust
use bevy_ecs_tilemap::helpers::hex_grid::neighbors::HexNeighbors;
use bevy_ecs_tilemap::prelude::TilemapCoordinateSystem;

// Assuming center, map_size, and coord_sys are defined
let neighbors = HexNeighbors::get_neighboring_positions(&center, &map_size, &coord_sys);
```
```

--------------------------------

### TilePos::from_world_pos

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Converts a 2D world-space coordinate into a tile position, accounting for map type, grid size, tile size, and anchor. Returns None if the position is outside the map boundaries.

```APIDOC
## TilePos::from_world_pos

### Description
Converts a 2D world-space position into a tile position for any map type and anchor. This is useful for interactions like mouse picking or projectile targeting. Returns `None` if the world position falls outside the map.

### Method
`TilePos::from_world_pos(world_pos: &Vec2, map_size: &TilemapSize, grid_size: &TilemapGridSize, tile_size: &TilemapTileSize, map_type: &TilemapType, anchor: &TilemapAnchor) -> Option<TilePos>`

### Parameters
- `world_pos` (Vec2): The 2D world-space position to convert.
- `map_size` (TilemapSize): The dimensions of the tilemap.
- `grid_size` (TilemapGridSize): The size of each grid cell.
- `tile_size` (TilemapTileSize): The dimensions of each tile.
- `map_type` (TilemapType): The type of the tilemap (e.g., `Hexagon`, `Square`).
- `anchor` (TilemapAnchor): The anchor point of the tilemap.

### Returns
- `Option<TilePos>`: The calculated tile position if the world position is within the map bounds, otherwise `None`.

### Example
```rust
use bevy_ecs_tilemap::prelude::TilePos;

// Assuming world_pos, map_size, grid_size, tile_size, map_type, and anchor are defined
if let Some(tile_pos) = TilePos::from_world_pos(&world_pos, &map_size, &grid_size, &tile_size, &map_type, &anchor) {
    println!("Converted tile position: {:?}", tile_pos);
}
```
```

--------------------------------

### Spawn Tilemap Without Frustum Culling

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Use `FrustumCulling(false)` in `TilemapBundle` to disable frustum culling, forcing all chunks to render. This is useful for debugging or render-to-texture scenarios. Ensure `bevy_ecs_tilemap::FrustumCulling` is imported.

```rust
use bevy::prelude::*
use bevy_ecs_tilemap::prelude::*
use bevy_ecs_tilemap::FrustumCulling;

fn spawn_without_culling(mut commands: Commands, asset_server: Res<AssetServer>) {
    let map_size = TilemapSize { x: 16, y: 16 };
    let tilemap_entity = commands.spawn_empty().id();
    let mut tile_storage = TileStorage::empty(map_size);
    fill_tilemap(TileTextureIndex(0), map_size, TilemapId(tilemap_entity), &mut commands, &mut tile_storage);

    commands.entity(tilemap_entity).insert(TilemapBundle {
        grid_size: TilemapGridSize { x: 16.0, y: 16.0 },
        map_type: TilemapType::Square,
        size: map_size,
        storage: tile_storage,
        texture: TilemapTexture::Single(asset_server.load("tiles.png")),
        tile_size: TilemapTileSize { x: 16.0, y: 16.0 },
        frustum_culling: FrustumCulling(false), // always render all chunks
        ..Default::default()
    });
}
```

--------------------------------

### Neighbors<TilePos>::get_square_neighboring_positions

Source: https://context7.com/stararawn/bevy_ecs_tilemap/llms.txt

Retrieves up to eight directional neighbors for a tile in a square or isometric diamond grid. Supports including or excluding diagonals.

```APIDOC
## Neighbors<TilePos>::get_square_neighboring_positions

### Description
Returns a `Neighbors<TilePos>` struct containing up to eight directional neighbors for a square (or isometric diamond) grid tile. The `include_diagonals` parameter controls whether to include diagonal neighbors.

### Method
`Neighbors::get_square_neighboring_positions(center: &TilePos, map_size: &TilemapSize, include_diagonals: bool) -> Neighbors<TilePos>`

### Parameters
- `center` (TilePos): The central tile position.
- `map_size` (TilemapSize): The size of the tilemap.
- `include_diagonals` (bool): If true, includes diagonal neighbors; otherwise, only cardinal neighbors are returned.

### Usage
- `.entities(tile_storage)`: Converts the neighbor positions to `Neighbors<Entity>` using the provided `TileStorage`.
- `.get(direction)`: Accesses a specific neighbor by direction (e.g., `SquareDirection::North`).

### Example
```rust
use bevy_ecs_tilemap::helpers::square_grid::neighbors::Neighbors;

// Assuming center and map_size are defined
let neighbors = Neighbors::get_square_neighboring_positions(&center, &map_size, true);
let cardinal_neighbors = Neighbors::get_square_neighboring_positions(&center, &map_size, false);
```
```
Tokens:
Raw