rakata_formats/vis/

mod.rs

//! VIS ASCII reader and writer.
//!
//! VIS (visibility) resources define which rooms are visible from each other
//! and are used for renderer culling decisions.
//!
//! ## Format Layout
//! ```text
//! <observer_room> <child_count>
//!   <visible_room>
//!   <visible_room>
//! <observer_room> <child_count>
//!   ...
//! ```
//!
//! Empty lines are ignored. Room names are treated case-insensitively and are
//! normalized to lowercase in-memory.
//! Text is decoded/encoded as Windows-1252.

mod reader;
mod writer;

pub use reader::{read_vis, read_vis_from_bytes};
pub use writer::{write_vis, write_vis_to_vec};

use std::collections::{BTreeMap, BTreeSet};
use thiserror::Error;

use rakata_core::{DecodeTextError, EncodeTextError};

use crate::binary::{DecodeBinary, EncodeBinary};

/// In-memory VIS graph.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Vis {
    visibility: BTreeMap<String, BTreeSet<String>>,
}

impl Vis {
    /// Creates an empty VIS graph.
    pub fn new() -> Self {
        Self::default()
    }

    /// Returns all known rooms.
    pub fn all_rooms(&self) -> BTreeSet<String> {
        self.visibility.keys().cloned().collect()
    }

    /// Returns visibility edges keyed by observer room.
    pub fn visibility(&self) -> &BTreeMap<String, BTreeSet<String>> {
        &self.visibility
    }

    /// Returns `true` if `room` exists in the graph.
    pub fn room_exists(&self, room: &str) -> bool {
        self.visibility.contains_key(&canonical_room(room))
    }

    /// Adds a room if it does not already exist.
    pub fn add_room(&mut self, room: impl AsRef<str>) {
        let room = canonical_room(room.as_ref());
        self.visibility.entry(room).or_default();
    }

    /// Removes a room and all references to it.
    pub fn remove_room(&mut self, room: &str) {
        let room = canonical_room(room);
        self.visibility.remove(&room);
        for observed in self.visibility.values_mut() {
            observed.remove(&room);
        }
    }

    /// Renames a room and updates all references to it.
    pub fn rename_room(&mut self, old: &str, new: &str) -> Result<(), VisError> {
        let old = canonical_room(old);
        let new = canonical_room(new);
        if old == new {
            return Ok(());
        }
        let observed = self
            .visibility
            .remove(&old)
            .ok_or_else(|| VisError::MissingRoom(old.clone()))?;
        self.visibility.insert(new.clone(), observed);
        for room_observed in self.visibility.values_mut() {
            if room_observed.remove(&old) {
                room_observed.insert(new.clone());
            }
        }
        Ok(())
    }

    /// Sets visibility between two rooms.
    pub fn set_visible(
        &mut self,
        when_inside: &str,
        show: &str,
        visible: bool,
    ) -> Result<(), VisError> {
        let when_inside = canonical_room(when_inside);
        let show = canonical_room(show);

        if !self.visibility.contains_key(&when_inside) {
            return Err(VisError::MissingRoom(when_inside));
        }
        if !self.visibility.contains_key(&show) {
            return Err(VisError::MissingRoom(show));
        }

        if visible {
            self.visibility
                .entry(when_inside)
                .or_default()
                .insert(show.clone());
        } else if let Some(observed) = self.visibility.get_mut(&when_inside) {
            observed.remove(&show);
        }
        Ok(())
    }

    /// Returns whether one room is visible from another.
    pub fn get_visible(&self, when_inside: &str, show: &str) -> Result<bool, VisError> {
        let when_inside = canonical_room(when_inside);
        let show = canonical_room(show);
        let observed = self
            .visibility
            .get(&when_inside)
            .ok_or_else(|| VisError::MissingRoom(when_inside.clone()))?;
        if !self.visibility.contains_key(&show) {
            return Err(VisError::MissingRoom(show));
        }
        Ok(observed.contains(&show))
    }

    /// Marks all rooms visible from each other (excluding self-visibility).
    pub fn set_all_visible(&mut self) {
        // Take the map by value to iterate keys while inserting new entries.
        // The borrow checker prevents iterating `self.visibility.keys()` while
        // calling `self.visibility.entry()`, so we operate on an owned map
        // and rebuild in place.
        let rooms: Vec<String> = self.visibility.keys().cloned().collect();
        for observer in &rooms {
            let observed = self
                .visibility
                .get_mut(observer)
                .expect("observer was just collected from the map's keys");
            observed.clear();
            observed.extend(rooms.iter().filter(|r| *r != observer).cloned());
        }
    }
}

impl DecodeBinary for Vis {
    type Error = VisError;

    fn decode_binary(bytes: &[u8]) -> Result<Self, Self::Error> {
        read_vis_from_bytes(bytes)
    }
}

impl EncodeBinary for Vis {
    type Error = VisError;

    fn encode_binary(&self) -> Result<Vec<u8>, Self::Error> {
        write_vis_to_vec(self)
    }
}

/// Errors produced while parsing or serializing VIS ASCII data.
#[derive(Debug, Error)]
pub enum VisError {
    /// I/O read/write failure.
    #[error(transparent)]
    Io(#[from] std::io::Error),
    /// Text content is malformed.
    #[error("invalid VIS data: {0}")]
    InvalidData(String),
    /// Text cannot be represented in Windows-1252 output.
    #[error("VIS text encoding failed for {context}: {source}")]
    TextEncoding {
        /// Value context.
        context: String,
        /// Encoding error details.
        #[source]
        source: EncodeTextError,
    },
    /// Input bytes could not be decoded losslessly as Windows-1252.
    #[error("VIS text decoding failed for {context}: {source}")]
    TextDecoding {
        /// Value context.
        context: String,
        /// Decoding error details.
        #[source]
        source: DecodeTextError,
    },
    /// A room referenced by an API call does not exist.
    #[error("VIS room `{0}` does not exist")]
    MissingRoom(String),
    /// A room token contains disallowed whitespace.
    #[error("invalid VIS room `{0}` (whitespace is not allowed)")]
    InvalidRoom(String),
}

fn canonical_room(room: &str) -> String {
    room.to_ascii_lowercase()
}