kiln/kiln-core/src/portal.rs

use serde::{Deserialize, Serialize};
use crate::glyph::Glyph;
use crate::utils::Point;

/// A portal that teleports the player to a named entry point on another board.
///
/// Portals are loaded from `[[portals]]` entries in `.toml` map files and
/// stored on [`Board`]. When the player steps onto a portal's cell, the engine
/// calls [`crate::game::GameState::enter_board`] with the `target_map` and
/// `target_entry`, placing the player at the matching named portal on the
/// destination board.
///
/// In map files, portals are conventionally placed using digit characters
/// (`'1'`–`'9'`) as palette keys — parallel to the uppercase-letter convention
/// for objects. A portal's `name` is board-unique: it is also used as the
/// `target_entry` value on the other end of the connection.
#[derive(Serialize, Deserialize, Clone, Debug)]
#[serde(rename_all = "lowercase")]
pub struct Portal {
    #[serde(flatten)]
    pub location: Point,
    /// Board-unique name for this portal, also used as `target_entry` by portals
    /// on other boards that want to arrive here.
    pub name: String,
    /// Key of the target board in `World::boards`.
    pub target_board: String,
    /// Name of the arrival portal on the target board.
    pub target_name: String,
    /// Visual representation of this portal. Omitted from a map file, it
    /// defaults to [`Glyph::portal`] — `≡`, black on white — so portals are
    /// visible unless the author opts out with `tile = 0` (the transparent
    /// sentinel). Unlike sensors (which are glyphless by default), a portal
    /// sits on a transparent grid cell and this glyph is what
    /// [`Board::glyph_at`](crate::board::Board::glyph_at) draws for it.
    #[serde(default = "Glyph::portal", skip_serializing_if = "Glyph::is_portal_default")]
    pub glyph: Glyph
}