Add example for demonstrating/testing despawning tilemaps

Cargo.toml

@@ -47,6 +47,7 @@ features = [
     "bevy_window",
     "bevy_text",
     "bevy_sprite",
+    "bevy_ui",
     #"file_watcher",
     "multi_threaded",
     "webgl2",
@@ -67,6 +68,7 @@ features = [
     "x11",
     "bevy_text",
     "bevy_sprite",
+    "bevy_ui",
     "multi_threaded",
     "webgl2",
 ]
@@ -169,6 +171,10 @@ name = "spacing"
 path = "examples/spacing.rs"
 required-features = ["render"]
 [[example]]
+name = "spawn_despawn_tilemap"
+path = "examples/spawn_despawn_tilemap.rs"
+required-features = ["render"]
+[[example]]
 name = "texture_container"
 path = "examples/texture_container.rs"
 required-features = ["render"]

README.md

@@ -69,6 +69,7 @@ fn update_damage(
 - [`random_map`](examples/random_map.rs) - A bench of editing all of the tiles every 100 ms.
 - [`remove_tiles`](examples/remove_tiles.rs) - An example showing how you can remove tiles by using map_query
 - [`spacing`](examples/spacing.rs) - Shows how to load tilemap textures that contain spacing between the tiles.
+- [`spawn_despawn_tilemap`](examples/spawn_despawn_tilemap.rs) - Shows how spawn and despawn tilemaps.
 - [`texture_container`](examples/texture_container.rs) - An example showing how to load tiles from array layers inside a KTX2 or DDS container.
 - [`texture_vec`](examples/texture_vec.rs) - An example showing how to load tiles from a list of individual image assets.
 - [`tiled`](examples/tiled.rs) - An example of loading and rendering of a [Tiled](https://www.mapeditor.org/) editor map. We recommend checking out [`bevy_ecs_tiled`](https://github.com/adrien-bon/bevy_ecs_tiled).

examples/spawn_despawn_tilemap.rs

@@ -0,0 +1,117 @@
+//! Example showing tilemap despawning.
+
+use bevy::{input::common_conditions::input_just_pressed, prelude::*};
+use bevy_ecs_tilemap::prelude::*;
+mod helpers;
+
+fn startup(mut commands: Commands) {
+    commands.spawn(Camera2d);
+    commands.spawn((
+        Text::new("space: spawn tilemap\nesc: despawn tilemap"),
+        Node {
+            position_type: PositionType::Absolute,
+            top: Val::Px(12.0),
+            left: Val::Px(12.0),
+            ..default()
+        },
+    ));
+}
+
+fn spawn_map(
+    mut commands: Commands,
+    asset_server: Res<AssetServer>,
+    maps: Query<(), With<TileStorage>>,
+) {
+    let num_maps = maps.iter().len();
+
+    let texture_handle: Handle<Image> = asset_server.load("tiles.png");
+
+    let map_size = TilemapSize { x: 32, y: 32 };
+
+    let tilemap_entity = commands.spawn_empty().id();
+
+    let mut tile_storage = TileStorage::empty(map_size);
+
+    // Spawn the elements of the tilemap.
+    // Alternatively, you can use helpers::filling::fill_tilemap.
+    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),
+                    color: TileColor(
+                        Hsla::hsl(0., 0.9, 0.8)
+                            .rotate_hue(num_maps as f32 * 19.)
+                            .into(),
+                    ),
+                    texture_index: TileTextureIndex(5),
+                    ..default()
+                })
+                .id();
+            tile_storage.set(&tile_pos, tile_entity);
+        }
+    }
+
+    let tile_size = TilemapTileSize { x: 16.0, y: 16.0 };
+    let grid_size = tile_size.into();
+    let map_type = TilemapType::default();
+
+    let offset = Vec3::splat(num_maps as f32 * tile_size.x / 2.);
+    let mut transform = get_tilemap_center_transform(&map_size, &grid_size, &map_type, 0.0);
+    transform.translation += offset;
+
+    commands.entity(tilemap_entity).insert(TilemapBundle {
+        grid_size,
+        map_type,
+        size: map_size,
+        storage: tile_storage,
+        texture: TilemapTexture::Single(texture_handle),
+        tile_size,
+        transform,
+        ..default()
+    });
+}
+
+fn despawn_map(mut commands: Commands, mut maps: Query<(Entity, &mut TileStorage, &Transform)>) {
+    let Some((tilemap_entity, mut tile_storage, _)) = maps
+        .iter_mut()
+        .sort_by::<&Transform>(|a, b| b.translation.z.partial_cmp(&a.translation.z).unwrap())
+        .next()
+    else {
+        return;
+    };
+
+    commands.entity(tilemap_entity).despawn_recursive();
+
+    for maybe_entity in tile_storage.iter_mut() {
+        if let Some(entity) = maybe_entity.take() {
+            commands.entity(entity).despawn();
+        }
+    }
+}
+
+fn main() {
+    App::new()
+        .add_plugins(
+            DefaultPlugins
+                .set(WindowPlugin {
+                    primary_window: Some(Window {
+                        title: String::from("Despawn Tilemap Example"),
+                        ..default()
+                    }),
+                    ..default()
+                })
+                .set(ImagePlugin::default_nearest()),
+        )
+        .add_plugins(TilemapPlugin)
+        .add_systems(Startup, startup)
+        .add_systems(Update, helpers::camera::movement)
+        .add_systems(Update, spawn_map.run_if(input_just_pressed(KeyCode::Space)))
+        .add_systems(
+            Update,
+            despawn_map.run_if(input_just_pressed(KeyCode::Escape)),
+        )
+        .run();
+}