kiln/kiln-core/src/map_file.rs

use crate::floor::{build_floor, FloorSpec};
use crate::board::Board;
use crate::log::LogLine;
use color::Rgba8;
use serde::{Deserialize, Serialize};
use std::collections::hash_map::Entry;
use std::collections::{BTreeMap, HashMap};
use std::convert::TryFrom;
use std::path::Path;
use crate::archetype::Archetype;
use crate::glyph::Glyph;
use crate::object_def::ObjectDef;
use crate::utils::{ObjectId, Player, PortalDef};

/// The top-level serialization/deserialization type for a `.toml` map file.
///
/// This struct mirrors the TOML file structure exactly. On load it is
/// immediately converted into a [`Board`] via [`TryFrom<MapFile>`] and then
/// discarded. On save a [`Board`] is converted back into this struct via
/// [`From<&Board>`] before serialization.
///
/// See `maps/start.toml` for a complete example of the file format.
#[derive(Deserialize, Serialize)]
pub struct MapFile {
    /// The `[map]` section: name, dimensions, player start position.
    pub map: MapHeader,
    /// The `[palette]` section: maps single-character keys to tile definitions.
    pub palette: HashMap<String, PaletteEntry>,
    /// The `[grid]` section: the multi-line string that defines cell layout.
    pub grid: GridData,
    /// Optional `[floor]` declaration: the visual floor layer (a generator name,
    /// a single glyph, or a grid with its own palette). See [`FloorSpec`].
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub floor: Option<FloorSpec>,
    /// Any `[[objects]]` entries. Optional; defaults to empty.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub(crate) objects: Vec<MapFileObjectEntry>,
    /// Any `[[portals]]` entries. Optional; defaults to empty.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub portals: Vec<PortalDef>,
}

/// The `[map]` header section of a map file.
#[derive(Deserialize, Serialize)]
pub struct MapHeader {
    /// Human-readable name for this board, e.g. `"Opening Room"`.
    pub name: String,
    /// Width of the board in cells. Must match the length of every row in `[grid] content`.
    pub width: usize,
    /// Height of the board in cells. Must match the number of rows in `[grid] content`.
    pub height: usize,
    /// Where the player starts: either explicit `[x, y]` coordinates or a single
    /// grid character to locate (e.g. `"@"`). See [`PlayerStart`].
    pub player_start: PlayerStart,
    /// Name of the board-level script in the `[scripts]` table, if any.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub board_script_name: Option<String>,
}

/// A tile index in a palette entry: either a plain integer or a character literal.
///
/// Accepting both forms lets map files use `tile = 32` for new files or
/// `tile = " "` for convenience (the char is converted to its Unicode scalar).
/// This means existing maps that used `ch = "#"` can be migrated by renaming
/// the key to `tile`; the char form keeps working.
#[derive(Deserialize, Serialize, Clone, Copy)]
#[serde(untagged)]
pub enum TileIndex {
    /// A direct tile index (e.g. `tile = 35`).
    Num(u32),
    /// A single-character shorthand (e.g. `tile = "#"`); converted to its Unicode scalar.
    Chr(char),
}

impl TileIndex {
    pub(crate) fn into_u32(self) -> u32 {
        match self {
            TileIndex::Num(n) => n,
            TileIndex::Chr(c) => c as u32,
        }
    }
}

/// Where the player starts in a map file: explicit coordinates or a single grid
/// character to locate.
///
/// Untagged like [`TileIndex`], so `player_start = [30, 12]` parses as
/// [`PlayerStart::Coord`] and `player_start = "@"` as [`PlayerStart::Char`]
/// (`Coord` is listed first, so a TOML array matches it and a string falls
/// through to `Char`).
#[derive(Deserialize, Serialize)]
#[serde(untagged)]
pub enum PlayerStart {
    /// Explicit `[x, y]` coordinates (0-indexed, origin top-left).
    Coord([i32; 2]),
    /// A single grid character marking the player's cell (its cell loads `Empty`).
    Char(char),
}

/// One entry in the `[palette]` table.
///
/// Each entry is keyed by a single character (e.g. `"#"` or `" "`).
/// That character is used in the `[grid]` content string to place tiles.
/// The entry defines both how the tile looks (`tile`, `fg`, `bg`) and which
/// [`Archetype`] it uses for behavior.
///
/// `tile` accepts either an integer (`tile = 35`) or a char (`tile = "#"`).
#[derive(Deserialize, Serialize)]
pub struct PaletteEntry {
    /// The archetype name for this tile, e.g. `"wall"` or `"empty"`.
    pub archetype: String,
    /// The tile index into the board's bitmap font.
    /// Accepts either an integer or a single-character string.
    tile: TileIndex,
    /// Foreground color as an `"#RRGGBB"` hex string.
    pub fg: String,
    /// Background color as an `"#RRGGBB"` hex string.
    pub bg: String,
}

/// The `[grid]` section of a map file.
///
/// `content` is a TOML multi-line string. Each line is one row of the board;
/// each character in a line is looked up in the palette to determine the
/// tile for that cell.
#[derive(Deserialize, Serialize)]
pub struct GridData {
    /// The raw grid content. Split by [`str::lines`] during loading.
    pub content: String,
}

/// One `[[objects]]` entry in a map file.
///
/// Used only for TOML serialization/deserialization. Converted to/from
/// [`ObjectDef`] (which holds a [`Glyph`] directly) in the [`TryFrom`] /
/// [`From`] impls below.
#[derive(Deserialize, Serialize)]
pub(crate) struct MapFileObjectEntry {
    /// Column of this object on the board (0-indexed). Mutually exclusive with
    /// `palette`: provide either `x`/`y` or `palette`, not both.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    x: Option<usize>,
    /// Row of this object on the board (0-indexed). See `x`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    y: Option<usize>,
    /// Single grid character marking where this object sits, as an alternative to
    /// `x`/`y`. By convention an uppercase letter. The char may appear multiple
    /// times in the grid — one `ObjectDef` is spawned per occurrence in reading
    /// order. Only one `[[objects]]` entry may use a given char, and it must not
    /// collide with a `[palette]` key. Each cell under the char loads as `Empty`.
    /// If the entry has a `name`, only the first spawned instance keeps it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    palette: Option<String>,
    /// Tile index into the board's bitmap font. Accepts integer or single-char string.
    tile: TileIndex,
    /// Foreground color as an `"#RRGGBB"` hex string.
    fg: String,
    /// Background color as an `"#RRGGBB"` hex string.
    bg: String,
    /// Whether the object blocks / participates in movement. Defaults to `true`
    /// (blocking). Inverse of the old `passable` field.
    #[serde(default = "default_true")]
    solid: bool,
    /// Whether the object blocks player line of sight / FOV
    #[serde(default = "default_true")]
    opaque: bool,
    /// Whether the object can be shoved by a mover. Unused for now; defaults `false`.
    #[serde(default)]
    pushable: bool,
    /// Name of the Rhai script in the `[scripts]` table, if any.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    script_name: Option<String>,
    /// Open-ended string labels. Serialized as a TOML array; omitted when empty.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    tags: Vec<String>,
    /// Optional unique human-readable name. Omitted from TOML when absent.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    name: Option<String>,
}

fn default_true() -> bool {
    true
}

/// Constructs a [`Glyph`] from the three raw TOML-sourced fields.
fn make_glyph(tile: u32, fg: &str, bg: &str) -> Glyph {
    Glyph { tile, fg: parse_color(fg), bg: parse_color(bg) }
}

/// Constructs a serializable [`PaletteEntry`] from core board types.
fn make_palette_entry(glyph: Glyph, arch: Archetype) -> PaletteEntry {
    PaletteEntry {
        archetype: arch.name().to_string(),
        tile: TileIndex::Num(glyph.tile),
        fg: color_to_hex(glyph.fg),
        bg: color_to_hex(glyph.bg),
    }
}

/// Resolves the player's starting cell from `player_start`, falling back to `(0, 0)` on any error.
fn resolve_player_start(
    start: &PlayerStart,
    w: usize,
    h: usize,
    player_grid_pos: Option<(usize, usize)>,
    player_grid_count: usize,
    errors: &mut Vec<LogLine>,
) -> (usize, usize) {
    match start {
        PlayerStart::Coord([x, y])
            if *x >= 0 && *y >= 0 && (*x as usize) < w && (*y as usize) < h =>
        {
            (*x as usize, *y as usize)
        }
        PlayerStart::Coord([x, y]) => {
            errors.push(LogLine::error(format!(
                "player_start ({x}, {y}) is out of bounds; placing player at (0, 0)"
            )));
            (0, 0)
        }
        PlayerStart::Char(c) => match (player_grid_pos, player_grid_count) {
            (Some(pos), 1) => pos,
            (Some(pos), n) => {
                errors.push(LogLine::error(format!(
                    "player char '{c}' appears {n} times in the grid; using the first"
                )));
                pos
            }
            _ => {
                errors.push(LogLine::error(format!(
                    "player char '{c}' not found in the grid; placing player at (0, 0)"
                )));
                (0, 0)
            }
        },
    }
}

/// Parses an `"#RRGGBB"` hex color string into an [`Rgba8`].
/// Returns opaque black on any parse failure.
pub(crate) fn parse_color(hex: &str) -> Rgba8 {
    let hex = hex.trim_start_matches('#');
    if hex.len() != 6 {
        return Rgba8 {
            r: 0,
            g: 0,
            b: 0,
            a: 255,
        };
    }
    let r = u8::from_str_radix(&hex[0..2], 16).unwrap_or(0);
    let g = u8::from_str_radix(&hex[2..4], 16).unwrap_or(0);
    let b = u8::from_str_radix(&hex[4..6], 16).unwrap_or(0);
    Rgba8 { r, g, b, a: 255 }
}

/// Converts an [`Rgba8`] to an `"#RRGGBB"` hex string (alpha is ignored).
pub(crate) fn color_to_hex(color: Rgba8) -> String {
    format!("#{:02X}{:02X}{:02X}", color.r, color.g, color.b)
}

/// Converts a parsed map file into a runtime [`Board`].
///
/// Returns `Err(String)` if the grid dimensions do not match the header:
/// - wrong number of rows (actual row count ≠ `height`)
/// - any row whose character count ≠ `width`
///
/// The conversion proceeds in two passes:
///
/// 1. **Palette pass** — each entry is parsed into a `(Glyph, Archetype)` pair
///    and stored in a temporary `HashMap` keyed by the palette character.
///    Unknown archetype names produce an [`Archetype::ErrorBlock`] and a logged
///    warning so malformed maps are visible in-game.
///
/// 2. **Grid pass** — `grid.content` is split into lines; each character is
///    looked up in the palette map and pushed directly into `cells`.
impl TryFrom<MapFile> for Board {
    type Error = String;

    fn try_from(mf: MapFile) -> Result<Self, Self::Error> {
        let w = mf.map.width;
        let h = mf.map.height;

        // Nonfatal problems collected as we load; surfaced on the Board so callers
        // can read `Board::is_valid`. Only grid-dimension mismatch (below) is fatal.
        let mut load_errors: Vec<LogLine> = Vec::new();

        // If the player is placed by a grid char, this is that char (e.g. '@').
        let player_char = match mf.map.player_start {
            PlayerStart::Char(c) => Some(c),
            PlayerStart::Coord(_) => None,
        };

        // Pass 1: build a char → (Glyph, Archetype) lookup from the palette.
        let mut palette: HashMap<char, (Glyph, Archetype)> = HashMap::new();

        for (key, entry) in mf.palette {
            let key_char = key.chars().next().unwrap_or(' ');
            let tile = entry.tile.into_u32();
            match Archetype::try_from(entry.archetype.as_str()) {
                Ok(archetype) => {
                    let glyph = make_glyph(tile, &entry.fg, &entry.bg);
                    palette.insert(key_char, (glyph, archetype));
                }
                Err(e) => {
                    load_errors.push(LogLine::error(e));
                    palette.insert(
                        key_char,
                        (Archetype::ErrorBlock.default_glyph(), Archetype::ErrorBlock),
                    );
                }
            }
        }

        // Validate grid dimensions before walking cells.
        // Collect lines eagerly so we can check the count and reuse them.
        let rows: Vec<&str> = mf.grid.content.lines().collect();
        if rows.len() != h {
            return Err(format!(
                "grid has {} rows but map header declares height = {}",
                rows.len(),
                h
            ));
        }
        for (i, line) in rows.iter().enumerate() {
            let col_count = line.chars().count();
            if col_count != w {
                return Err(format!(
                    "grid row {} has {} characters but map header declares width = {}",
                    i, col_count, w
                ));
            }
        }

        // Validate object `palette` references before the grid pass, since the
        // grid pass needs to know which chars are object placeholders.
        // `skip[i]` drops object `i`; `palette_char_owner` maps a valid object
        // palette char to the single object that owns it.
        let mut skip = vec![false; mf.objects.len()];
        let mut palette_char_owner: HashMap<char, usize> = HashMap::new();
        for (i, e) in mf.objects.iter().enumerate() {
            let Some(p) = e.palette.as_deref() else {
                continue;
            };
            // `palette` is mutually exclusive with explicit `x`/`y`.
            if e.x.is_some() || e.y.is_some() {
                load_errors.push(LogLine::error(format!(
                    "object {i}: specify either x/y or palette, not both; skipping object"
                )));
                skip[i] = true;
                continue;
            }
            // It must be exactly one character.
            let mut chs = p.chars();
            let (Some(ch), None) = (chs.next(), chs.next()) else {
                load_errors.push(LogLine::error(format!(
                    "object {i}: palette must be a single character (got {p:?}); skipping object"
                )));
                skip[i] = true;
                continue;
            };
            // The player's char (e.g. '@') is reserved.
            if Some(ch) == player_char {
                load_errors.push(LogLine::error(format!(
                    "object {i}: palette char '{ch}' is reserved for the player; skipping object"
                )));
                skip[i] = true;
                continue;
            }
            // It can't reuse a terrain palette key.
            if palette.contains_key(&ch) {
                load_errors.push(LogLine::error(format!(
                    "object {i}: palette char '{ch}' is already a [palette] key; skipping object"
                )));
                skip[i] = true;
                continue;
            }
            // It must be unique across objects — keep the first claimant, drop later ones.
            match palette_char_owner.entry(ch) {
                Entry::Occupied(_) => {
                    load_errors.push(LogLine::error(format!(
                        "object {i}: palette char '{ch}' is already used by another object; skipping object"
                    )));
                    skip[i] = true;
                }
                Entry::Vacant(v) => {
                    v.insert(i);
                }
            }
        }

        // Pass 2: walk the validated grid and build cells. Object palette chars
        // become `Empty` floor (with their positions remembered); truly unknown
        // chars become a visible `ErrorBlock` so the cell count stays correct.
        let canonical_empty = (Archetype::Empty.default_glyph(), Archetype::Empty);
        let mut cells: Vec<(Glyph, Archetype)> = Vec::with_capacity(w * h);
        // All grid positions (in reading order) at which each object palette char appears.
        let mut obj_palette_positions: HashMap<char, Vec<(usize, usize)>> = HashMap::new();
        // Where the player's char was first seen, and how many times (for recovery).
        let mut player_grid_pos: Option<(usize, usize)> = None;
        let mut player_grid_count: usize = 0;
        for (y, line) in rows.iter().enumerate() {
            for (x, ch) in line.chars().enumerate() {
                if let Some(&cell) = palette.get(&ch) {
                    cells.push(cell);
                } else if Some(ch) == player_char {
                    // Player placeholder: floor underneath; keep the first sighting.
                    cells.push(canonical_empty);
                    player_grid_pos.get_or_insert((x, y));
                    player_grid_count += 1;
                } else if palette_char_owner.contains_key(&ch) {
                    cells.push(canonical_empty);
                    obj_palette_positions.entry(ch).or_default().push((x, y));
                } else {
                    load_errors.push(LogLine::error(format!(
                        "unknown grid character '{ch}' at ({x}, {y}); using error block"
                    )));
                    cells.push((Archetype::ErrorBlock.default_glyph(), Archetype::ErrorBlock));
                }
            }
        }

        // Resolve each surviving object palette char: missing → drop the entry.
        // Multiple occurrences are valid — each spawns its own ObjectDef below.
        for (&ch, &owner) in &palette_char_owner {
            if skip[owner] {
                continue;
            }
            if obj_palette_positions.get(&ch).is_none_or(Vec::is_empty) {
                load_errors.push(LogLine::error(format!(
                    "object palette char '{ch}' not found in the grid; skipping object"
                )));
                skip[owner] = true;
            }
        }

        // Build the cached floor layer from the (optional) `[floor]` declaration.
        // Best-effort: any problem is recorded on `load_errors`, not fatal. The
        // raw spec is kept on the board so a save can round-trip it.
        let floor_spec = mf.floor;
        let floor = build_floor(&floor_spec, w, h, &mut load_errors);

        // Convert MapFileObjectEntry → ObjectDef, enforcing one solid per cell.
        // `solid_occupied` is seeded from the grid (solid archetypes); each solid
        // object then claims its cell, and a second solid on a cell is dropped.
        let mut solid_occupied: Vec<bool> = cells.iter().map(|(_, a)| a.behavior().solid).collect();

        // Resolve the player's cell (nonfatal; fall back to (0, 0) on any problem),
        // then let the player *win* its cell: clear solid terrain under it and claim
        // the cell so a solid object placed here is dropped by the loop below.
        let (px, py) = resolve_player_start(
            &mf.map.player_start,
            w,
            h,
            player_grid_pos,
            player_grid_count,
            &mut load_errors,
        );
        let pidx = py * w + px;
        if solid_occupied[pidx] {
            cells[pidx] = canonical_empty;
        }
        solid_occupied[pidx] = true;

        // Objects get sequential ids in load order (so BTreeMap iteration order ==
        // load order, preserving the documented "lowest id wins a collision" rule).
        let mut objects: BTreeMap<ObjectId, ObjectDef> = BTreeMap::new();
        let mut next_object_id: ObjectId = 1;
        // Track claimed names so duplicates can be caught and cleared (nonfatal).
        let mut seen_names: HashMap<String, usize> = HashMap::new();
        for (i, e) in mf.objects.into_iter().enumerate() {
            if skip[i] {
                continue;
            }
            // Collect all grid positions for this entry.  Palette entries produce one
            // position per occurrence (in reading order); x/y entries produce exactly one.
            let positions: Vec<(usize, usize)> = if let Some(p) = e.palette.as_deref() {
                let ch = p.chars().next().unwrap();
                obj_palette_positions.get(&ch).cloned().unwrap_or_default()
            } else {
                match (e.x, e.y) {
                    (Some(x), Some(y)) if x < w && y < h => vec![(x, y)],
                    (Some(x), Some(y)) => {
                        load_errors.push(LogLine::error(format!(
                            "object {i}: x/y ({x}, {y}) out of bounds; skipping object"
                        )));
                        continue;
                    }
                    _ => {
                        load_errors.push(LogLine::error(format!(
                            "object {i}: must specify both x and y (or a palette char); skipping object"
                        )));
                        continue;
                    }
                }
            };

            // Spawn one ObjectDef per position.  Only the first instance may claim the
            // entry's name; subsequent copies are anonymous (names must be board-unique).
            for (instance_idx, &(x, y)) in positions.iter().enumerate() {
                let name = if instance_idx == 0 {
                    // Validate name uniqueness: first claimant keeps the name, later ones
                    // have their name cleared and a nonfatal error is recorded.
                    e.name.as_ref().and_then(|n| {
                        match seen_names.entry(n.clone()) {
                            Entry::Vacant(v) => { v.insert(i); Some(n.clone()) }
                            Entry::Occupied(o) => {
                                load_errors.push(LogLine::error(format!(
                                    "object {i}: name {n:?} already used by object {}; clearing name",
                                    o.get()
                                )));
                                None
                            }
                        }
                    })
                } else {
                    None
                };

                let obj = ObjectDef {
                    id: 0, // stamped by Board::add_object
                    x,
                    y,
                    glyph: make_glyph(e.tile.into_u32(), &e.fg, &e.bg),
                    solid: e.solid,
                    opaque: e.opaque,
                    pushable: e.pushable,
                    script_name: e.script_name.clone(),
                    tags: e.tags.iter().cloned().collect(),
                    name,
                };

                // A solid object may not share a cell with another solid.
                if obj.solid {
                    let idx = y * w + x;
                    if solid_occupied[idx] {
                        // The player silently wins its own cell (by design); any other
                        // solid collision is a reportable mistake.
                        if idx != pidx {
                            load_errors.push(LogLine::error(format!(
                                "object {i}: solid object at ({x}, {y}) conflicts with an existing solid; skipping object"
                            )));
                        }
                        continue;
                    }
                    solid_occupied[idx] = true;
                }

                objects.insert(next_object_id, obj);
                next_object_id += 1;
            }
        }

        Ok(Board {
            name: mf.map.name,
            width: w,
            height: h,
            cells,
            floor,
            floor_spec,
            player: Player {
                x: px as i32,
                y: py as i32,
            },
            objects,
            next_object_id,
            portals: mf.portals,
            board_script_name: mf.map.board_script_name,
            load_errors,
        })
    }
}

/// Converts a runtime [`Board`] back into a serializable [`MapFile`].
///
/// The palette is reconstructed by enumerating unique `(Glyph, Archetype)`
/// combinations in the board's cells and assigning each a single printable
/// ASCII character key. The grid is rebuilt by looking up each cell in the
/// resulting palette map.
impl From<&Board> for MapFile {
    fn from(board: &Board) -> Self {
        // Pool for non-empty archetypes: printable ASCII 33-126 ('!' onward),
        // excluding `"` and `\` which would require escaping inside TOML strings.
        // Space (32) is reserved exclusively for Archetype::Empty.
        let pool: Vec<char> = (33u8..=126u8)
            .filter(|&b| b != b'"' && b != b'\\')
            .map(|b| b as char)
            .collect();
        let mut pool_iter = pool.iter();

        // The canonical empty cell (tile 32, black/black) is always serialized as ' '.
        // Every other unique (Glyph, Archetype) pair draws from the pool above.
        let canonical_empty = (Archetype::Empty.default_glyph(), Archetype::Empty);
        let mut cell_to_key: HashMap<(Glyph, Archetype), char> = HashMap::new();
        let mut palette: HashMap<String, PaletteEntry> = HashMap::new();

        for y in 0..board.height {
            for x in 0..board.width {
                let (glyph, arch) = board.get(x, y);
                let key = (*glyph, *arch);
                if let Entry::Vacant(e) = cell_to_key.entry(key) {
                    let ch = if key == canonical_empty {
                        ' '
                    } else {
                        *pool_iter.next().expect("board has more than 92 unique non-canonical cell types")
                    };
                    e.insert(ch);
                    palette.insert(ch.to_string(), make_palette_entry(*glyph, *arch));
                }
            }
        }

        // Pass 2: reconstruct the grid string row by row.
        let mut rows: Vec<String> = Vec::with_capacity(board.height);
        for y in 0..board.height {
            let mut row = String::with_capacity(board.width);
            for x in 0..board.width {
                let (glyph, arch) = board.get(x, y);
                row.push(cell_to_key[&(*glyph, *arch)]);
            }
            rows.push(row);
        }
        // Trailing newline ensures the last row is complete; str::lines handles it correctly.
        let content = rows.join("\n") + "\n";

        // Convert ObjectDef → MapFileObjectEntry, encoding the glyph as TOML-compatible fields.
        let objects: Vec<MapFileObjectEntry> = board
            .objects
            .values()
            .map(|o| MapFileObjectEntry {
                // Saving always emits concrete coordinates; the palette form is a
                // load-time convenience only.
                x: Some(o.x),
                y: Some(o.y),
                palette: None,
                tile: TileIndex::Num(o.glyph.tile),
                fg: color_to_hex(o.glyph.fg),
                bg: color_to_hex(o.glyph.bg),
                solid: o.solid,
                opaque: o.opaque,
                pushable: o.pushable,
                script_name: o.script_name.clone(),
                // Sort for stable TOML output; HashSet iteration order is non-deterministic.
                tags: { let mut v: Vec<String> = o.tags.iter().cloned().collect(); v.sort(); v },
                name: o.name.clone(),
            })
            .collect();

        let portals = board.portals.clone();

        MapFile {
            map: MapHeader {
                name: board.name.clone(),
                width: board.width,
                height: board.height,
                player_start: PlayerStart::Coord([board.player.x, board.player.y]),
                board_script_name: board.board_script_name.clone(),
            },
            palette,
            grid: GridData { content },
            // Round-trip the original floor declaration verbatim (generators
            // re-randomize on the next load; literal glyph grids are exact).
            floor: board.floor_spec.clone(),
            objects,
            portals,
        }
    }
}

/// Loads a map file from disk and returns a ready-to-use [`Board`].
///
/// Reads the file at `path`, deserializes it as TOML into a [`MapFile`],
/// then converts it via [`TryFrom<MapFile>`]. Propagates I/O errors, TOML
/// parse errors, and grid dimension mismatches through the `Box<dyn Error>` return.
pub fn load(path: &str) -> Result<Board, Box<dyn std::error::Error>> {
    let content = std::fs::read_to_string(path)?;
    let map_file: MapFile = toml::from_str(&content)?;
    Board::try_from(map_file).map_err(|e| e.into())
}

/// Serializes a [`Board`] to a `.toml` map file at `path`.
///
/// Converts the board to a [`MapFile`] via [`From<&Board>`], then serializes
/// it with `toml::to_string_pretty`. Propagates I/O and serialization errors.
pub fn save(board: &Board, path: &Path) -> Result<(), Box<dyn std::error::Error>> {
    let map_file = MapFile::from(board);
    let toml_str = toml::to_string_pretty(&map_file)?;
    std::fs::write(path, toml_str)?;
    Ok(())
}