kitao/pyxel · error

Invalid tile size in file '{path}'

Error message

Invalid tile size in file '{path}'

What it means

`parse_tmx` parsed the TMX successfully but the map's tile size does not match the library's fixed TILE_SIZE, so it rejects the file. This library only supports tilemaps whose tilewidth and tileheight equal TILE_SIZE (8 pixels in Pyxel).

Source

Thrown at crates/pyxel-core/src/tmx_parser.rs:62

    #[serde(rename = "tileset", default)]
    tilesets: Vec<Tileset>,
    #[serde(rename = "layer", default)]
    layers: Vec<Layer>,
}

pub fn parse_tmx(path: &str, layer_index: u32) -> Result<RcTilemap, String> {
    let err = |msg| format!("{msg} '{path}'");

    // Load and validate the TMX layer.
    let mut file = File::open(path).map_err(|_| err("Failed to open file"))?;
    let mut tmx_text = String::new();
    file.read_to_string(&mut tmx_text)
        .map_err(|_| err("Failed to read file"))?;

    let tmx: TmxMap = serde_xml_rs::from_str(&tmx_text).map_err(|_| err("Failed to parse file"))?;

    if tmx.tilewidth != TILE_SIZE || tmx.tileheight != TILE_SIZE {
        return Err(err("Invalid tile size in file"));
    }

    let tileset = tmx
        .tilesets
        .first()
        .ok_or_else(|| err("No tileset found in file"))?;
    let columns = tileset
        .columns
        .ok_or_else(|| err("No embedded tileset in file"))?;

    let layer = tmx
        .layers
        .get(layer_index as usize)
        .ok_or_else(|| format!("Layer {layer_index} not found in file '{path}'"))?;
    if layer.data.encoding != "csv" {
        return Err(err("Unsupported encoding in file"));
    }

View on GitHub (pinned to 50f9bd7778)

Solutions

1. Re-export/recreate the Tiled map with tile size matching TILE_SIZE (8x8).
2. Or set your Tiled tileset images so each tile is 8x8 pixels (scale art to 8px tiles).
3. Alternatively, preprocess/convert the TMX to 8x8 tiles before passing it to from_tmx.
4. Check the TMX header attributes `tilewidth` and `tileheight` to confirm the mismatch.

Example fix

// before (map saved with tilewidth=16 tileheight=16)
let tilemap = Tilemap::from_tmx("level.tmx", 0)?; // Invalid tile size in file 'level.tmx'
// after: in Tiled, set Map > Tile size to 8x8 (or use an 8x8 tileset), re-save, then
let tilemap = Tilemap::from_tmx("level.tmx", 0)?;

// Check TMX header tile size matches the engine's TILE_SIZE (8) before parse_tmx
fn tmx_tile_size_ok(path: &str) -> Result<(), String> {
    let text = std::fs::read_to_string(path).map_err(|e| e.to_string())?;
    let width_ok = text.contains("tilewidth=\"8\"");
    let height_ok = text.contains("tileheight=\"8\"");
    if !(width_ok && height_ok) {
        return Err(format!("{} must use 8x8 tiles to match Pyxel TILE_SIZE", path));
    }
    Ok(())
}

match Tilemap::from_tmx(path, 0) {
    Ok(tm) => use_tilemap(tm),
    Err(e) if e.starts_with("Invalid tile size") => {
        eprintln!("{}: recreate the Tiled map with 8x8 tile size", path);
    }
    Err(e) => eprintln!("TMX load failed: {}", e),
}

When it happens

Trigger: Calling `parse_tmx(path, layer_index)` on a Tiled map whose 'tilewidth' or 'tileheight' attributes differ from the engine's TILE_SIZE (e.g. 16x16 or 32x32 tiles).

Common situations: Creating a Tiled map with default 16px or 32px tile sizes instead of Pyxel's 8px screen-scale tiles; importing a tilemap from another engine; changing Pyxel's display scale and assuming the TMX tile size should scale too.

Related errors

• tilemap dimensions are too large
• Failed to open file '{path}'
• Failed to read file '{path}'
• Failed to parse file '{path}'
• Layer dimensions are too large in file '{path}'

AI-assisted analysis of kitao/pyxel@50f9bd7778 (2026-09-03). Data as JSON: /api/errors/c574a019f54319b6. Report an issue: GitHub.