Crate bevy_sparse_tilemap

source ·
Expand description

# bevy_sparse_tilemap

Crates.io docs license Crates.io

A Tilemap crate for the Bevy game engine with a focus on large map sizes and ECS sparse maps

§Features

  • Sparse-set style tilemaps
    • Only the minimum amount of data is stored for each tile. Furthermore tiles that don’t need it don’t get their own Entity
    • Built in API to handle spawning, despawning, and accessing tiles optional entities
  • Massive tilemap sizes.
    • Because of the above feature, maps can be ludicrously large and have very good performance.
  • Purely focused on the tilemap logic - rendering is left to the user

§Examples

See Docs.rs for documentation on how to use bevy_sparse_tilemap as well as brief examples.

See Github Examples for longer examples of each feature of the crate.

§What about bevy_ecs_tilemap?

bevy_ecs_tilemap is a fabulous crate that will probably cover most of your needs in an easier to use plugin and you should reach for that first.

You should use bevy_ecs_tilemap if:

  • You don’t need very large maps (sub 200x200 in my testing)
  • You want every tile to be its own Entity for ECS integration (This crate tries to avoid unnecessary entities and uses a Voxel like approach)
  • You want a more mature and more feature rich plugin
  • You want tilemap rendering handled for you

You should use bevy_sparse_tilemap if:

  • You want very very large maps (bevy_sparse_tilemap can reach substantially larger map sizes. The bevy_fast_tilemap_example currently spawns a 15000x15000 tile map)
  • Basically the above is the main reason, giant maps that are (currently) more cumbersome to work with but can be millions of tiles
  • You want tile shapes other than square (other shapes are planned but not implemented and not on the radar currently)
  • You are willing to implement your own tilemap rendering (This crate has an example for integration with bevy_fast_tilemap however that is not currently a feature of this crate)

§Bevy Version

BST VersionBevy Version
0.30.14
0.20.13
0.10.13

§Tilemap Construction


fn spawn_tilemap(mut commands: Commands) {
    let chunk_conversion_settings = SquareChunkSettings {
        max_chunk_size: UVec2 { x: 100, y: 100 },
    };

    let mut tilemap_builder = TilemapBuilder::<TileData, MapLayers, SquareChunkLayer<TileData>, SquareMapData,
        >::new(
        TilemapLayer::new_dense_default(10000, 10000),
        SquareMapData {
            conversion_settings: SquareMapDataConversionSettings {
                max_chunk_dimensions: UVec2::new(100, 100),
                },
            },
        ChunkSettings {
            max_chunk_size: UVec2::new(100, 100),
        },
        chunk_conversion_settings,
    );

    let Some(tilemap) = tilemap_builder.spawn_tilemap(&mut commands)
        else {
            return;
    };
}

§Tilemap Access

bevy_sparse_tilemap includes a handy TilemapManager systemp aram that has a bevy of helper functions to make accessing, editing, and interacting with tilemaps that much easier.

    map_data::SquareMapData,
 map_chunk_layer::SquareChunkLayer,
 };

 fn access(tilemap_manager: TilemapManager<TileData, MapLayers, SquareChunkLayer<TileData>, SquareMapData>, mut commands: Commands, map_entity: Res<MapEntity>) {
    // We have to set the TilemapManager to the desired tilemap
    tilemap_manager.set_tilemap_entity(map_entity.0);
    // And set the manager to whatever layer we want to affect. Defaults to the default layer of the enum
    tilemap_manager.set_layer(MapLayers::Main);
    let tile_data = tilemap_manager.get_tile_data(Cell::new(9,16)).unwrap();

    // do something with the tilemap access here

 }

Modules§

Macros§

  • grid
    Init a grid with values.

Structs§

  • ColumnMeshBuilder
    Builder struct to customize hex column mesh generation.
  • EdgeDirection
    All 6 possible neighbor/edge directions in hexagonal space.
  • GridEdge
    Hexagonal grid orientated edge representation
  • GridVertex
    Hexagonal grid orientated vertex representation.
  • Hex
    Hexagonal axial coordinates
  • HexBounds
    Hexagonal bounds utils, represented as a center and radius. This type can be defined manually or from a Hex iterator.
  • HexLayout
    Hexagonal layout. This type is the bridge between your world/pixel coordinate system and the hexagonal coordinate system.
  • IVec2
    A 2-dimensional vector.
  • IVec3
    A 3-dimensional vector.
  • InsetOptions
    Insetting options for PlaneMeshBuilder and ColumnMeshBuilder used to create an insetted face on either hexagonal planes or quads
  • MeshInfo
    Hexagonal mesh information.
  • PlaneMeshBuilder
    Builder struct to customize hex plane mesh generation.
  • Quat
    A quaternion representing an orientation.
  • Rect
    2D rect, with remapping utilities
  • UVOptions
    Struct containing options for UV mapping.
  • Vec2
    A 2-dimensional vector.
  • Vec3
    A 3-dimensional vector.
  • VertexDirection
    All 6 possible diagonal/vertex directions in hexagonal space.

Enums§

Traits§

Functions§

  • hex
    Instantiates a new hexagon from axial coordinates

Derive Macros§