Accessing tiles to change textures and to add or remove components.

[frederickjjoubert]

Hello, first off, thanks for the great plugin. I'd like some guidance on the following:

I want to change textures on tiles and add and remove components easily; I'm trying to understand how to do this properly.

I've looked through the examples, specifically:

• https://github.com/StarArawn/bevy_ecs_tilemap/blob/main/examples/basic.rs
• https://github.com/StarArawn/bevy_ecs_tilemap/blob/main/examples/accessing_tiles.rs

I would like clarification on a few things:

1. From the example linked above, there is a comment Once the tile storage is inserted onto the tilemap entity it can no longer be accessed. I don't understand what this is supposed to imply because we can still access the TileStorage in queries such as tile_storage_query: Query<&TileStorage>. I'm not sure what the implications of this comment are supposed to mean.

2. Do we have to work with sprite atlases? I'd prefer to work with individual sprite files as it's easier for me to iterate on individual files and work with artists with individual files rather than a big atlas I need to keep up to date that can change texture indices as sprites are added, removed and changed. Same goes for animated tiles where I have sprite sheets with different animations on a per tile basis.

From the basics example:

commands
        .entity(tilemap_entity)
        .insert_bundle(TilemapBundle {
            grid_size,
            size: tilemap_size,
            storage: tile_storage,
            texture: TilemapTexture(texture_handle), // Here you have to pass in a texture atlas to the tilemap.
            tile_size,
            transform: get_centered_transform_2d(&tilemap_size, &tile_size, 0.0),
            ..Default::default()
        });

From the accessing example:

if let Ok(mut tile_texture) = tile_query.get_mut(neighbor_entity) {
    tile_texture.0 = color as u32; // Here you have to change the texture by changing the texture index.
}

it appears the only way to change a tile texture is to change the texture index.

3. What is the best practice for adding and removing components from Tiles? Should I follow Bevy's best practices to add and remove components from an entity since the tiles are all entities? Or is there a way for me to despawn the tile entity, spawn a new one with the components I want, and add that back into the tilemap? I ask because having a lot of checks for which components exist on the tile entity before I attempt to remove them is becoming verbose.

[StarArawn]

1. Once the tile storage is inserted onto the tilemap entity it can no longer be accessed

What's meant here is that once the tile storage is inserted onto the entity it cant be accessed until a hard sync point. This means that queries will not work to access it within the same system or a parallel system. You can however use a label/after or a different system stage as those are "hard" sync points where the commands from the system are processed.

Do we have to work with sprite atlases?

Yes and no. Internally if you are using the atlas feature the texture provided is used directly. Without the atlas feature a custom image process runs that adds the atlas textures into an array texture. Array textures are the most optimal for rendering tiles but we don't necessarily have to use a texture atlas to load them in. We can use individual textures instead but there is work that needs to happen first to allow that to happen.

I think what you are asking for is slightly different though where you want to be able to set a tile's texture by using a bevy Handle<Image>. This likely will never be supported as:

1. You would have to swap between different texture materials depending on the tile's ID. This would cause higher draw call counts.
2. We could map Handle into a texture array index, but my concern there is the additional overhead of having to resolve those mappings.

What is the best practice for adding and removing components from Tiles? Should I follow Bevy's best practices to add and remove components from an entity since the tiles are all entities? Or is there a way for me to despawn the tile entity, spawn a new one with the components I want, and add that back into the tilemap? I ask because having a lot of checks for which components exist on the tile entity before I attempt to remove them is becoming verbose.

Tiles should be treated like bevy entities and the title data like bevy components. You can despawn tiles and replace them with new tiles if you wish, but I modifying the tiles data via a mutable query is acceptable too.

The only gotcha here is the tile_storage does not automatically update. If you spawn a new tile or despawn a tile you need to make sure to remove/add the tile entity to the storage. The tile storage is really only needed currently for tile lookups. Individual tile lookups using position or neighbor lookups.

[StarArawn]

Just as a side note you might want to add a image > atlas processor into your workflow. There are a couple around aseprite provides some of this. I think there is another program called texture packer as well.

[frederickjjoubert]

Thank you for your reply; some follow up questions I have:

We can use individual textures instead but there is work that needs to happen first to allow that to happen.

What do you mean by individual textures and work that needs to happen to allow that? Could you point me to an example of this as a workaround for what I'm trying to do?

As an alternative, what would you recommend as best practice for working with large amounts of tiles as well as animated tiles and rule tiles, is one required to place them all in the same texture atlas and manually keep track of what exists at whatever index?

The only gotcha here is the tile_storage does not automatically update. If you spawn a new tile or despawn a tile you need to make sure to remove/add the tile entity to the storage. The tile storage is really only needed currently for tile lookups. Individual tile lookups using position or neighbor lookups.

How would you force the tile_storage to update in this case? Are there methods on the tile_storage for this?

[StarArawn]

What do you mean by individual textures and work that needs to happen to allow that? Could you point me to an example of this as a workaround for what I'm trying to do?

This is more long term plans but I would like to support loading in multiple image files and combine them into an array texture. Something like:

let dirt = asset_server.load("dirt.png");
let grass = asset_server.load("grass.png");
let stone = asset_server.load("stone.png");
commands.spawn().insert_bundle(TilemapBundle {
  texture: Texture::List(vec![dirt, grass, stone]),
  ...
});

I also want to support loading in array textures directly by using file formats that support them. This has the advantage of being able to load mipmaps in at the same time.

let tile_image = asset_server.load("tiles.dds");
commands.spawn().insert_bundle(TilemapBundle {
  texture: Texture::ArrayTexture(tile_image),
  ...
});

How would you force the tile_storage to update in this case? Are there methods on the tile_storage for this?

Tile storage is pretty simple:
https://github.com/StarArawn/bevy_ecs_tilemap/blob/main/src/tiles/storage.rs

I'm realizing as I write this it's not clear how to "clear" out a tile from the given functions but if you call set and pass a None value it will remove the tile entity from the tile storage. I think I'll likely add a remove function in the future though.

You can also access neighbors with some of the helper functions:
https://github.com/StarArawn/bevy_ecs_tilemap/blob/main/src/helpers.rs#L366

Some of the helper stuff is expected to change into less of a giant file and more individual modules in the future, but the functionality should be the same.

[Affinator]

It is also possible to build a TextureAtlas at runtime via a https://docs.rs/bevy/latest/bevy/sprite/struct.TextureAtlasBuilder.html
Maybe this helps.