# Bevy Tilemap Renderer

## Motivation

Bevy currently lacks first-party support for tilemap rendering, leaving developers to rely on third-party crates or implement their own systems. This fragmentation leads to inconsistent APIs and duplicate effort. First-party tilemap rendering will enable developers to build tile-based games and 3rd party integrations more easily and efficiently.

## Goals

* Support a wide variety of use cases
* Rectangular, isometric, hexagonal tile shapes
* Finite and infinite tilemaps
* Atlas, array texture, and file-per-tile assets for tilesets
* Clean separation of tilemap rendering and higher-level APIs
* Focus on performance
* Enable existing tilemap crates to swap out their own rendering implementations
* Build on top of Bevy's high-level rendering as much as possible (Mesh2d/Material2d)

## Features

### Asset to Tileset Pipeline

* Provide a first-party asset type for tilesets
* Load tileset images as array texture (1 layer per tile variant)
* Define metadata for tile dimensions and layout
* Support slicing packed texture atlases into the array texture
* Support combining separate tile images into the array texture

### Fast Chunk-Based Rendering

* Divide the map into fixed-size chunks (e.g. 32x32 tiles)
* A chunk is a Mesh2d with a custom chunk shader
* The shader is responsible for rendering tiles based on tile data and cached mesh data

### Tile Data

* Tileset texture index (tile variant)
* Color
* Visible
* Flip X/Y/Diagonal
* Rotate?

### Tile Storage

* Tile data stored in a single source of truth
* Support both sparse and dense storage?
* Modifying tile storage should only update relevant chunks

### Infinite/finite Map

* Allow dynamic growth in all directions (IVec2 tile positions, not UVec2)
* Support lazy loading of chunks?
* Allow setting map bounds to constrain and enable whole-map transform anchoring

## Proposed API

* Basic infinite map with sparse storage

    let chunk_size = UVec2::splat(32);
    let mut tile_storage = TileStorage::sparse(chunk_size);

    // Sets tiledata at (3200,3200) and marks chunk position 100,100 as dirty.
    tile_storage.set(
        IVec2::splat(3200),
        TileData {
            tileset_index: 0,
            color: Color::WHITE,
            visible: true,
            flip: TileFlip {
                x: true,
                y: false,
                d: false
            }
        }
    );

    commands.spawn((
        Tilemap::default(),
        Tileset(assets.load("atlas-tileset.tileset.ron")),
        tile_storage
    ));

* Basic finite map with dense storage

    let map_size = UVec2::new(128, 32);
    let chunk_size = UVec2::splat(32);
    let mut tile_storage = TileStorage::new_dense_fill(map_size, chunk_size, TileData::from_index(0));

    commands.spawn((
        Tilemap {
            // Override the tile size determined by the tileset
            tile_display_size: UVec2::splat(32)
        },
        Tileset(assets.load("atlas-tileset.tileset.ron")),
        tile_storage,
        Anchor::BOTTOM_CENTER
    ));

## Out of Scope

* Higher-level ECS API (Entity-per-tile, Tile/Tilemap relation, traversal, etc.)
* Advanced features like animated tiles, auto-tiling,