bevy_ecs_tilemap

Because every tile is an entity, you can manipulate them using standard Bevy queries. This makes it easy to implement features like tile-based damage, animations, or environmental changes by querying for specific tile components and updating them.

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;
    }
}

You can run examples in a web browser using wasm-server-runner.

For WebGL2:

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

For WebGPU:

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

DiamondPos is a vector-like coordinate system used for tiles arranged in an isometric diamond grid. It supports standard arithmetic operations like addition, subtraction, and scalar multiplication by an i32.

Key capabilities include:

• Mapping DiamondPos to world space (center, corners, or fractional positions).
• Mapping world space positions back to a DiamondPos.
• Converting from other coordinate systems like TilePos, StaggeredPos, or SquarePos.
• Calculating neighbor offsets using SquareDirection via the offset method or diamond_offset on TilePos.

Depending on your coordinate system, you can use semantic compass directions instead of raw mathematical directions.

• HexRowDirection: Used for row-oriented systems (Row, RowEven, RowOdd). Variants: North, NorthWest, SouthWest, South, SouthEast, NorthEast.
• HexColDirection: Used for column-oriented systems (Column, ColumnEven, ColumnOdd). Variants: East, NorthEast, NorthWest, West, SouthWest, SouthEast.

Both enums can be converted to/from HexDirection and provide an .offset() method to find the neighboring TilePos given a starting position and a HexCoordSystem.

To use bevy_ecs_tilemap in your Bevy application, you must add the TilemapPlugin to your app. This plugin is required for rendering tilemaps. If you are running a headless application without a renderer, the plugin will still function but the rendering components will be omitted.

Note that if the render feature is enabled, the plugin automatically adds the TilemapRenderingPlugin and handles internal scheduling for tile position updates.

To run the simplest example of creating a tilemap, use the following command:

cargo run --release --example basic

The CubePos struct represents a coordinate in a hexagonal grid using the cube coordinate system. It consists of three components q, r, and s that always satisfy the identity q + r + s = 0.

CubePos behaves like a vector: you can add or subtract two CubePos instances, and you can multiply a CubePos by an i32 or u32 scalar. It can be converted from AxialPos or TilePos.

FractionalAxialPos represents a point that lies inside a hexagon, typically resulting from mapping a world position into hexagonal space. It uses f32 components for q and r.

It can be converted into a discrete AxialPos using the .round() method, which uses cube rounding to find the nearest hex center.

Use fill_tilemap_rect to spawn tiles within a rectangular area. The region is defined by an origin (TilePos) and a size (TilemapSize).

fill_tilemap_rect(
    texture_index,
    origin,
    size,
    tilemap_id,
    &mut commands,
    &mut tile_storage,
);

To find adjacent tiles in a square grid, use SquareDirection in conjunction with SquarePos or TilePos.

• From SquarePos: Use pos.offset(direction) to get a new SquarePos representing the neighbor.
• From TilePos: Use tile_pos.square_offset(direction, map_size) to get an Option<TilePos>. This method automatically handles bounds checking against the provided map_size, returning None if the neighbor is outside the map.

This is specifically for standard (non-isometric) square coordinate systems.