kiln/kiln-core/src/builtin_scripts.rs

//! Tag helpers for script-backed archetypes expanded from map-file keywords.
//!
//! When a [`Builtin`] archetype cell is expanded into an [`ObjectDef`] by
//! [`Board::expand_builtin_archetypes`], the object receives a `BUILTIN_<alias>`
//! tag (e.g. `"BUILTIN_pusher_north"`) so its Rhai script can read which specific
//! variant it is (via `Me.has_tag("BUILTIN_pusher_north")`).
//!
//! The save path ([`map_file`]) uses [`archetype_from_builtin_tag`] to collapse
//! an expanded object back into its original map-file keyword so worlds
//! round-trip correctly.
//!
//! The full builtin registry — which archetypes exist, their behaviors, glyphs,
//! and embedded scripts — lives in [`crate::archetype`] via the `builtins!` macro.
//!
//! [`Builtin`]: crate::archetype::Builtin
//! [`ObjectDef`]: crate::object_def::ObjectDef
//! [`Board::expand_builtin_archetypes`]: crate::board::Board::expand_builtin_archetypes
//! [`map_file`]: crate::map_file

use crate::archetype::Archetype;

/// Prefix for the tag that marks an object as an expanded built-in archetype and
/// names which alias it came from (e.g. `"BUILTIN_pusher_east"`).
pub(crate) const BUILTIN_TAG_PREFIX: &str = "BUILTIN_";

/// Returns the `BUILTIN_<alias>` tag for `arch` — e.g. `"BUILTIN_pusher_east"`.
///
/// For a `Builtin` archetype, `arch.name()` returns the alias (e.g. `"pusher_east"`).
/// For terrain archetypes (wall, crate, etc.) this is never called in practice.
pub(crate) fn builtin_tag(arch: Archetype) -> String {
    format!("{BUILTIN_TAG_PREFIX}{}", arch.name())
}

/// Recovers the `Archetype` a `BUILTIN_*` tag came from, or `None` if `tag` is not
/// a built-in tag naming a known archetype. Used by the save path to round-trip.
pub(crate) fn archetype_from_builtin_tag(tag: &str) -> Option<Archetype> {
    let name = tag.strip_prefix(BUILTIN_TAG_PREFIX)?;
    Archetype::try_from(name).ok()
}