bevy_symbios_shape 0.7.0

//! # bevy_symbios_shape
//!
//! Bevy integration for [`symbios-shape`](https://crates.io/crates/symbios-shape) —
//! a CGA Shape Grammar engine for procedural architecture.
//!
//! ## Quick start
//!
//! ```ignore
//! use bevy::prelude::*;
//! use bevy_symbios_shape::prelude::*;
//! use symbios_shape::{Interpreter, Scope, grammar::parse_ops};
//!
//! fn main() {
//!     App::new()
//!         .add_plugins((DefaultPlugins, BevySymbiosShapePlugin))
//!         .add_systems(Startup, setup)
//!         .run();
//! }
//!
//! fn setup(
//!     mut commands: Commands,
//!     registry: Res<ShapeRegistry>,
//!     mut meshes: ResMut<Assets<Mesh>>,
//!     mut materials: ResMut<Assets<StandardMaterial>>,
//!     mut cache: ResMut<ShapeMeshCache>,
//! ) {
//!     let mut interp = Interpreter::new();
//!     interp.add_rule("Lot",    parse_ops("Extrude(12) Split(Y) { 3: Ground | ~1: Upper | 2: Roof }").unwrap());
//!     interp.add_rule("Ground", parse_ops(r#"I("GroundFloor")"#).unwrap());
//!     interp.add_rule("Upper",  parse_ops(r#"I("Floor")"#).unwrap());
//!     interp.add_rule("Roof",   parse_ops(r#"Taper(0.8) I("Roof")"#).unwrap());
//!
//!     let footprint = Scope::new(
//!         symbios_shape::Vec3::ZERO,
//!         symbios_shape::Quat::IDENTITY,
//!         symbios_shape::Vec3::new(10.0, 0.0, 10.0),
//!     );
//!
//!     commands
//!         .spawn_shape(&interp, footprint, "Lot", &registry, &mut meshes, &mut materials, &mut cache)
//!         .unwrap();
//! }
//! ```
//!
//! ## Modules
//!
//! | Module | Purpose |
//! |---|---|
//! | [`cache`] | [`ShapeMeshCache`] — bounded cross-spawn mesh cache (LRU, hit/miss/eviction counters) |
//! | [`events`] | [`SpawnShapeRequest`] / [`SpawnShapeSpawned`] / [`SpawnShapeFailed`] event surface |
//! | [`label`] | [`TerminalLabel`] component carrying the grammar's `Label("…")` occlusion class |
//! | [`mass`] | [`TerminalMass`] component carrying upstream `MassProperties` |
//! | [`mesh`] | `build_profiled_mesh` / `build_profiled_mesh_with` / `build_tapered_cuboid` — meshing, including round cross-sections |
//! | `mutation` | `mutation` feature only — texture-config evolution plumbing |
//! | [`query`] | [`LastDerivedModel`] resource exposing the most recent `ShapeModel` for spatial queries |
//! | [`registry`] | [`ShapeRegistry`] — asset routing table (mesh + material IDs → handles) |
//! | [`snap`] | [`SnapPlanes`] resource exposing `RegSnap("…")` recordings |
//! | [`spawner`] | [`SpawnShapeExt`] — `Commands` extension trait |
//! | [`transform`] | [`scope_to_transform`] — `Scope` → Bevy `Transform` with f64→f32 + corner-to-centroid offset |
//!
//! ## Round cross-sections
//!
//! Grammar scopes are always axis-aligned boxes, but a terminal's rendering
//! need not be. Opting an asset ID into round rendering makes the mesher
//! inscribe an elliptical prism in the scope — a cylinder for `Rectangle`
//! profiles, a frustum for `Taper(t)`, a cone at `Taper(1.0)` — which is how
//! columns, silos, chimneys, and spires are built without giving up the
//! OBB-pure derivation:
//!
//! ```ignore
//! // Grammar:  Column --> Extrude(0.6) Taper(0.14) Mat("Marble") I("Column")
//! registry.register_round_mesh("Column");
//! registry.set_round_segments(32);      // default 24
//! ```
//!
//! Splits, occlusion queries, and mass properties still see the box; only
//! the baked mesh changes. See [`registry::ShapeRegistry::register_round_mesh`].
//!
//! ## Cargo features
//!
//! - `egui` (off by default) — pulls in [`bevy_egui`](https://crates.io/crates/bevy_egui).
//!   Reserved for inspection/editor UIs built on top of the crate; the core
//!   pipeline does not depend on it.
//! - `mutation` (off by default) — enables the `mutation` module, which
//!   wires [`bevy_symbios_texture`](https://crates.io/crates/bevy_symbios_texture)
//!   procedural texture configs into a Bevy observer pipeline so shape-grammar
//!   materials can be evolved via `symbios_genetics::Genotype`.

pub mod cache;
pub mod events;
pub mod label;
pub mod mass;
pub mod mesh;
#[cfg(feature = "mutation")]
pub mod mutation;
pub mod query;
pub mod registry;
pub mod snap;
pub mod spawner;
pub mod transform;

pub use cache::ShapeMeshCache;
pub use events::{
    SpawnShapeFailed, SpawnShapeRequest, SpawnShapeSpawned, SpawnShapeSystems, handle_spawn_request,
};
pub use label::TerminalLabel;
pub use mass::TerminalMass;
#[cfg(feature = "mutation")]
pub use mutation::{
    MaterialMutationPlugin, MaterialTextureMutated, MutateMaterialsRequest, TextureConfigStore,
    handle_mutate_request, mutate_texture_config,
};
pub use query::LastDerivedModel;
pub use registry::ShapeRegistry;
pub use snap::{SnapPlane, SnapPlanes};
pub use spawner::SpawnShapeExt;
pub use transform::scope_to_transform;

pub use symbios_shape::{Material, TerminalQuery, obb_overlap};

/// Convenience re-exports for the most common types.
pub mod prelude {
    pub use crate::BevySymbiosShapePlugin;
    pub use crate::cache::ShapeMeshCache;
    pub use crate::events::{
        SpawnShapeFailed, SpawnShapeRequest, SpawnShapeSpawned, SpawnShapeSystems,
    };
    pub use crate::label::TerminalLabel;
    pub use crate::mass::TerminalMass;
    pub use crate::query::LastDerivedModel;
    pub use crate::registry::ShapeRegistry;
    pub use crate::snap::{SnapPlane, SnapPlanes};
    pub use crate::spawner::SpawnShapeExt;
    pub use crate::transform::scope_to_transform;
    pub use symbios_shape::{TerminalQuery, obb_overlap};

    #[cfg(feature = "mutation")]
    pub use crate::mutation::{
        MaterialMutationPlugin, MaterialTextureMutated, MutateMaterialsRequest, TextureConfigStore,
    };
}

/// Bevy plugin that wires the crate's resources and observer into an [`App`].
///
/// Add this plugin to your [`App`] alongside [`DefaultPlugins`]:
///
/// ```ignore
/// App::new()
///     .add_plugins((DefaultPlugins, BevySymbiosShapePlugin))
///     // ...
/// ```
///
/// The plugin installs the following [`Resource`]s (each in their `Default`
/// state) and observer:
///
/// - [`ShapeRegistry`] — asset routing table; populate it before any
///   `spawn_shape` call so terminals can resolve registered scenes/materials.
/// - [`SnapPlanes`] — overwritten by every `spawn_shape` call with the
///   `RegSnap("…")` planes recorded during derivation.
/// - [`LastDerivedModel`] — overwritten by every `spawn_shape` call with the
///   full upstream [`ShapeModel`][symbios_shape::ShapeModel] for spatial
///   queries.
/// - [`ShapeMeshCache`] — cross-spawn procedural mesh handle cache.
/// - An observer for [`SpawnShapeRequest`] that performs the derivation +
///   spawn and triggers [`SpawnShapeSpawned`] / [`SpawnShapeFailed`].
///
/// [`App`]: bevy::prelude::App
/// [`DefaultPlugins`]: bevy::prelude::DefaultPlugins
/// [`Resource`]: bevy::prelude::Resource
pub struct BevySymbiosShapePlugin;

impl bevy::prelude::Plugin for BevySymbiosShapePlugin {
    fn build(&self, app: &mut bevy::prelude::App) {
        app.init_resource::<ShapeRegistry>()
            .init_resource::<SnapPlanes>()
            .init_resource::<LastDerivedModel>()
            .init_resource::<ShapeMeshCache>()
            .add_observer(handle_spawn_request);
    }
}