symbios-shape

A pure-Rust derivation engine for CGA Shape Grammars, as popularised by Esri CityEngine. Define procedural building rules as text or Rust code; derive a flat list of oriented mesh instances ready for any renderer.

attr Floors = 4
Lot    --> Extrude(Floors * 3.2) Split(Y) { 3: Ground | ~1: Body | 2: Roof }
Body   --> Comp(Faces) { Side: Facade }
Facade --> Split(X) { 1: Corner | { 0.6: Pier | ~1: Bay }* | 1: Corner }
Bay    --> when(scope.x < 1.1): Wall | else: Pick("win") { 70% WinA | 30% WinB }
Roof   --> Roof(Gable, height=2.5, ridge=X) { Slope: Tiles | GableEnd: Wall }

Features

• All core CGA ops — Extrude, Split, Repeat, Comp(Faces|Edges), Taper, Scale, Translate, Rotate, Align, Offset (inset and outset), Roof, Attach, I, Mat, Polygon, Size, Center, Mirror
• An expression language in every numeric argument — arithmetic, comparisons, &&/||/!, rand(min, max), floor/ceil/rint/abs/ sqrt/pow/clamp/min/max, plus the built-in variables scope.x/y/z, split.i, split.n, and depth
• Rule parameters and guards — Spire(n) --> when(n == 0): I("finial") | else: … Spire(n - 1); call arguments work at every successor position
• Stochastic rules with per-shape seed streams — 70% A | 30% B | else: C, reproducible per seed, queue-order independent, and editing one subtree re-rolls only that subtree
• Rhythm, fit, and area splits — { pier | window }* groups tile between fixed bookends; Fit(X) takes the first candidate that fits; SplitArea divides by target areas
• Footprint carving — ShapeL / ShapeU deliver courtyard and wing plans as rectangular scopes plus a remainder
• 15 roof types — Pyramid, Shed, Gable, Hip, Flat, OpenGable, BoxGable, PyramidHip, Butterfly, MShaped, Gambrel, Mansard, Saltbox, Jerkinhead, DutchGable — with height= (shared ridge lines across mixed-width wings), ridge=X|Z orientation control, fascia bands, and a Back northlight face on Shed
• Labelled & graded occlusion — Label("chimneys") classes terminals; IfClear("chimneys"), IfOccluded, IfInside, IfTouches gate rules on precise spatial relations
• Coordination — Pick("key") { 60% A | 40% B } resolves once per derivation: every floor picks the same window variant
• Scatter — Scatter(Top, 12) { Bush } seed-stable point scopes over a face or through a volume
• Grammar statements — attr (host-overridable knobs), const, and style … extends … override sets; hosts call set_attr / set_style
• Snap-lines & material propagation — RegSnap + Split(snap=…); Mat("Brick", 1800) flows to terminals and computes mass properties
• Genetic evolution — ShapeGenotype wraps the rule table for symbios-genetics (literal-leaf mutation, BLX-α crossover)
• DoS-hardened — bounded queue, depth, terminal, expression, and identifier limits

Installation

[dependencies]
symbios-shape = "0.3"

Quick Start

use symbios_shape::{Interpreter, Scope, Vec3, Quat};
use symbios_shape::grammar::parse_statement;

let mut interp = Interpreter::new();
for line in [
    "attr Floors = 3",
    r#"Lot    --> Extrude(Floors * 3.2) Split(Y) { 3: Ground | ~1: Floor | 2: Roof }"#,
    r#"Ground --> I("GroundFloor")"#,
    r#"Floor  --> I("UpperFloor")"#,
    r#"Roof   --> Taper(0.8) I("Roof")"#,
] {
    interp.add_statement(parse_statement(line).unwrap()).unwrap();
}
interp.seed = 42;                       // reproducible derivation
interp.set_attr("Floors", 5.0);         // host override, no grammar edit

// XZ footprint — Y is set by Extrude
let footprint = Scope::new(Vec3::ZERO, Quat::IDENTITY, Vec3::new(10.0, 0.0, 10.0));
let model = interp.derive(footprint, "Lot").unwrap();

for t in &model.terminals {
    println!("{} @ {:?}", t.mesh_id, t.scope.position);
}

parse_rule / add_grammar_rule remain for rule-only hosts, and add_rule / add_weighted_rules / add_rule_def / add_rule_variants cover programmatic construction.

Expressions

Every numeric argument position accepts an expression, evaluated per shape at derivation time:

Extrude(rand(8, 14))                       # stochastic dimensions
Split(Y) { scope.y / 4: Base | ~1: Rest }  # scope-adaptive sizes
Scale(scope.x * 0.5, 1, 1)
Bay(split.i)                               # call arguments

Failures are loud: division by zero, non-finite results, unknown names, and inverted ranges abort the derivation with a descriptive ShapeError.

rand(..) draws from the shape's own seed stream, forked from its parent's along the derivation path. Consequences: the same seed always derives the same model; queue order is irrelevant; and editing the rules of one wing re-rolls that wing alone.

Rules

# Deterministic
Lot --> Extrude(10) Split(Y) { ~1: Floor | 2: Roof }

# Stochastic (weights are percentages; `else:` takes the remainder)
Facade --> 70% BrickWall | else: GlassCurtain

# Guarded (top-down; first true guard wins; `else:` is the fallback)
Bay --> when(scope.x < 1.2): Wall | when(split.i == 0): CornerBay | else: WindowBay

# Parameterized (+ recursion with a guard base case)
Spire(n) --> when(n == 0): I("finial") | else: Extrude(scope.y * 0.7) Next(n)
Next(n)  --> Spire(n - 1)

Weighted and guarded variants cannot mix within one rule. A guarded rule with no matching guard and no else derives nothing.

NIL is a reserved rule name that vanishes its shape — legal in any successor position: Split(X) { ~1: Wall | 0.4: NIL | ~1: Wall }, 50% Balcony | 50% NIL.

Statements

attr Floors = 4                    # host-overridable knob
const FloorH = 3.2                 # fixed named value
style Poor { Floors = 2 }          # named attr override set
style Rich extends Poor { Floors = 6 }

Declaration values must be constant expressions. Effective precedence when an expression reads a name: rule parameters → host set_attr → active set_style → attr default → const.

Grammar Syntax

Operations

Comments (// line, /* block */) are legal anywhere whitespace is. Op keywords match at word boundaries — rule names like Inner or Sized never collide with I( or Size(.

Roof

Roof(Gable, 30) { Slope: Tiles | GableEnd: Bricks }
Roof(Hip, 30, 0.5) { Slope: Tiles }                          # 0.5 = overhang
Roof(Gambrel, 45, 20) { LowerSlope: Shingles | UpperSlope: Tiles }
Roof(Gable, height=2.5) { Slope: Tiles | GableEnd: Wall }    # byHeight
Roof(Gable, 35, ridge=Z) { Slope: Tiles | GableEnd: Wall }   # force ridge axis
Roof(Shed, 40) { Slope: Metal | Back: NorthLight }           # sawtooth glazing
Roof(Mansard, 60, secondary=20, tier=0.4) { LowerSlope: P | UpperSlope: T }
Roof(Hip, 30, fascia=0.3) { Slope: Tiles | Fascia: Board }

Named args (any order, overriding positionals): overhang=, offset= (Saltbox ridge, default 0.5), tier=, fascia=, secondary=, height= (rise in world units; replaces pitch — mixed-width wings sharing one height meet at the same ridge line; Shed measures over its full depth), ridge=X|Z (honoured by the gable family, Gambrel, Saltbox, Jerkinhead, DutchGable; the hip family derives its ridge from the footprint). The second positional is the secondary pitch for Gambrel/Mansard and the overhang for every other type.

Face selectors: Slope, GableEnd, LowerSlope, UpperSlope, HipEnd, ValleySlope, OuterSlope, InnerSlope, Fascia, Back (Shed), All/_.

Occlusion & snap-lines (BFS-order caveat)

RegSnap/Split(snap=…) and the If* conditionals consult the derivation state at the moment they fire. Structure grammars so the shapes being tested against derive first — one or two rules of indirection on the testing branch is the standard idiom.

Rust API highlights

let mut interp = Interpreter::new();
interp.add_statement(parse_statement("attr Wear = 0.3")?)?;   // text statements
interp.add_grammar_rule(parse_rule("Lot --> Extrude(9) I(\"Mass\")")?)?;
interp.add_rule_def("Box", vec!["h".into()],                   // programmatic params
    vec![(1.0, parse_ops("Extrude(h) I(\"Mass\")")?)])?;
interp.set_attr("Wear", 0.8);                                  // host override
interp.set_style("Poor")?;                                     // style select
interp.seed = 7;
let model = interp.derive(footprint, "Lot")?;

Output

derive returns a ShapeModel:

pub struct ShapeModel {
    pub terminals: Vec<Terminal>,
    pub snap_planes: Vec<SnapPlane>,
}

pub struct Terminal {
    pub scope: Scope,                            // OBB: position, rotation, size
    pub mesh_id: String,
    pub face_profile: FaceProfile,               // Rectangle, Taper, Triangle, Trapezoid, Polygon
    pub material: Option<Material>,
    pub mass_properties: Option<MassProperties>, // when material has density
    pub label: Option<String>,                   // set by Label("…")
}

model.query() exposes OBB overlap tests (TerminalQuery), and obb_overlap(&a, &b) is a free function.

Safety Limits

Exceeding a limit returns a structured ShapeError rather than panicking.

Genetic Evolution

genetics::ShapeGenotype wraps the rule table (parameters included) for symbios-genetics algorithms. Mutation jitters literal leaves only — bare literals keep validity clamps; compound expressions re-validate at derivation. Guard conditions and Pick weights are treated as logic, not aesthetics, and pass through crossover unblended.

Migrating from 0.2

Grammar text from 0.2 parses unchanged. API changes: op fields hold Expr/RuleCall (literals via Expr::lit, names via "Name".into()), Split uses entries, Roof takes a RoofSpec (RoofConfig::from bridges numeric configs), WeightedVariant → RuleVariant, and Terminal gained label. Derivations reshuffle once: per-shape seed streams change which variant a given seed picks (structure is unaffected). Non-finite argument values now report ShapeError::ExprEval.

Architecture

• OBB scopes — all geometry is oriented bounding boxes; no mesh booleans
• BFS queue — breadth-first expansion; per-shape RNG states fork along the ancestry path (SplitMix64), so results are queue-order independent
• Pure derivation — the engine produces a ShapeModel; rendering is the caller's responsibility (see bevy_symbios_shape)
• Serde support — scopes, ops, models, and sub-types round-trip; pre-0.3 Terminal payloads deserialize (the label field defaults)

License

MIT