Struct World 

pub struct World {
    pub meta: WorldMeta,
    pub owners: IndexMap<Guid, Owner>,
    pub bricks: Vec<Brick>,
    pub grids: Vec<(Entity, Vec<Brick>)>,
    pub wires: Vec<WireConnection>,
    pub entities: Vec<Entity>,
    pub microchip_links: Vec<(usize, usize)>,
    pub prefabs: IndexMap<String, Vec<u8>>,
    pub global_data: BrdbSchemaGlobalData,
    pub component_schema: BrdbSchema,
    pub entity_schema: BrdbSchema,
    pub schema_format: BrdbSchemaFormat,
}

Fields

meta: WorldMeta

owners: IndexMap<Guid, Owner>

bricks: Vec<Brick>

Bricks on the main grid

grids: Vec<(Entity, Vec<Brick>)>

Non-main grids require an entity to be created for them

wires: Vec<WireConnection>

entities: Vec<Entity>

microchip_links: Vec<(usize, usize)>

Per-microchip linkage pairs: (brick_id, entity_id) where the brick is the outer microchip shell and the entity is the inner grid.

prefabs: IndexMap<String, Vec<u8>>

Embedded prefab archives (the root Prefabs/ folder), keyed by root-relative path (Prefabs/Uploads/<BLAKE3>.brz) with raw .brz bytes as values. Populate via World::add_prefab; the returned path is what a Prefab component property references.

The game requires the Prefabs/Uploads/<BLAKE3>.brz naming — it crashes loading a bundle whose embedded prefab has any other filename. Use World::add_prefab rather than inserting a custom key here.

global_data: BrdbSchemaGlobalData

component_schema: BrdbSchema

entity_schema: BrdbSchema

schema_format: BrdbSchemaFormat

The save format this world is written in.

BrdbSchemaFormat::Latest (the default) writes every schema in the map form, as the game writes them.

BrdbSchemaFormat::Auto writes each .schema in the container it needs: the map form for schemas with a types table or dynamic containers (the component schema), the array form otherwise. Every current game build reads both, but a world written this way without components has an EA3 component schema, so crate::migrate::needs_migration reports it as an EA3 save.

Writing EA3 worlds is not supported: World::to_unsaved fails with BrdbWorldError::Ea3WriteUnsupported.

Implementations

impl World

pub fn new() -> Self

Examples found in repository

examples/write_fixtures.rs (line 26)

fn brick_world() -> World {
    // Mirror of examples/write_brz.rs — the historical example_brick world.
    let mut world = World::new();
    world.meta.bundle.description = "Example World".to_string();
    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    world
}

fn features_world() -> World {
    // Single chunk (all coords in [0, 2048)): registries, owners, procedural
    // size run-length grouping (new/extend/reuse), a basic asset, collision
    // and visibility variants, orientations, material intensity.
    let mut world = World::new();
    world.meta.bundle.description = "Feature fixture".to_string();

    let alice = Guid::from_uuid(uuid::Uuid::parse_str(ALICE_UUID).unwrap());
    let bob = Guid::from_uuid(uuid::Uuid::parse_str(BOB_UUID).unwrap());
    world.owners.insert(
        alice,
        Owner {
            user_id: alice,
            user_name: "alice".to_string(),
            display_name: "Alice".to_string(),
        },
    );
    world.owners.insert(
        bob,
        Owner {
            user_id: bob,
            user_name: "bob".to_string(),
            display_name: "Bob".to_string(),
        },
    );

    let tile = |size: (u16, u16, u16)| BrickType::Procedural {
        asset: assets::bricks::PB_DEFAULT_TILE, // "PB_DefaultTile"
        size: BrickSize {
            x: size.0,
            y: size.1,
            z: size.2,
        },
    };

    // 1: default brick (PB_DefaultBrick 5x5x6, plastic, intensity 5) — new size slot
    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        owner_index: Some(1),
        ..Default::default()
    });
    // 2: tile 10x10x2, metallic, intensity 7, XPositive/Deg90 — new counter entry
    world.bricks.push(Brick {
        asset: tile((10, 10, 2)),
        position: (20, 0, 2).into(),
        color: (0, 255, 0).into(),
        owner_index: Some(1),
        material: assets::materials::METALLIC, // "BMC_Metallic"
        material_intensity: 7,
        direction: Direction::XPositive,
        rotation: Rotation::Deg90,
        ..Default::default()
    });
    // 3: same tile size — size_index_map reuse
    world.bricks.push(Brick {
        asset: tile((10, 10, 2)),
        position: (40, 0, 2).into(),
        color: (0, 0, 255).into(),
        owner_index: Some(2),
        ..Default::default()
    });
    // 4: tile 20x20x2 — extends the tail counter (same asset, new size)
    world.bricks.push(Brick {
        asset: tile((20, 20, 2)),
        position: (80, 0, 2).into(),
        color: (255, 255, 0).into(),
        owner_index: Some(2),
        ..Default::default()
    });
    // 5: default brick again — reuses slot from brick 1 (map hit after other asset)
    world.bricks.push(Brick {
        position: (100, 0, 6).into(),
        color: (255, 255, 255).into(),
        owner_index: Some(1),
        ..Default::default()
    });
    // 6: BASIC asset, PUBLIC owner, glow, partial collision, YNegative/Deg180
    world.bricks.push(Brick {
        asset: assets::bricks::B_2X2_OVERHANG, // "B_2x2_Overhang"
        position: (200, 0, 10).into(),
        color: (128, 64, 32).into(),
        material: assets::materials::GLOW, // "BMC_Glow"
        material_intensity: 3,
        direction: Direction::YNegative,
        rotation: Rotation::Deg180,
        collision: Collision {
            player: false,
            ..Default::default()
        },
        ..Default::default()
    });
    // 7: invisible, all-collision-off, tiny proc brick
    world.bricks.push(Brick {
        asset: BrickType::Procedural {
            asset: assets::bricks::PB_DEFAULT_BRICK,
            size: BrickSize { x: 2, y: 2, z: 2 },
        },
        position: (300, 0, 2).into(),
        color: (10, 20, 30).into(),
        owner_index: Some(1),
        visible: false,
        collision: Collision {
            player: false,
            weapon: false,
            interact: false,
            physics: false,
            ..Default::default()
        },
        ..Default::default()
    });
    world
}

fn chunks_world() -> World {
    // Multi-chunk: euclidean chunking with negative coords, plus chunks
    // 0_0_0 and 1_0_0 carry byte-identical SoA payloads → blob dedup.
    // NOTE: multi-chunk Rust output has nondeterministic FILE ORDER
    // (HashMap iteration), so this fixture is hashes-gate only — never
    // byte-compare its container.
    let mut world = World::new();
    world.meta.bundle.description = "Chunk fixture".to_string();
    for (pos, color) in [
        ((0, 0, 0), (1, 2, 3)),
        ((-1, -1, -1), (4, 5, 6)),
        ((2048, 0, 0), (1, 2, 3)), // same rel pos + color as brick 1
        ((-2048, 4096, 10), (10, 11, 12)),
        ((500, 500, 500), (42, 42, 42)),
        ((2548, 500, 500), (42, 42, 42)), // same rel pos + color as brick 5
    ] {
        world.bricks.push(Brick {
            position: pos.into(),
            color: color.into(),
            ..Default::default()
        });
    }
    world
}

fn wires_world() -> World {
    // Mirror of examples/write_wire.rs (single grid, single chunk — fully
    // deterministic), extended to 3 bricks/2 wires: a boolean NOT gate feeds
    // one input of an AND gate, whose output feeds a rerouter.
    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Wire fixture".to_string();

    let (a, a_id) = Brick {
        position: (30, 0, 1).into(),
        color: (255, 0, 0).into(),
        asset: assets::bricks::B_REROUTE,
        ..Default::default()
    }
    .with_component(assets::components::Rerouter)
    .with_id_split();
    let (b, b_id) = Brick {
        position: (15, 0, 1).into(),
        color: (0, 255, 0).into(),
        asset: assets::components::LogicGate::BoolAnd.brick(),
        ..Default::default()
    }
    .with_component(assets::components::LogicGate::BoolAnd.component())
    .with_id_split();
    let (c, c_id) = Brick {
        position: (0, 0, 1).into(),
        color: (0, 0, 255).into(),
        asset: assets::components::LogicGate::BoolNot.brick(),
        ..Default::default()
    }
    .with_component(assets::components::LogicGate::BoolNot.component())
    .with_id_split();

    world.add_bricks([a, b, c]);
    // Wire 1: NOT.output -> AND.inputA
    world.add_wire_connection(
        assets::components::LogicGate::BoolNot.output_of(c_id),
        assets::components::LogicGate::BoolAnd.input_a_of(b_id),
    );
    // Wire 2: AND.output -> Rerouter.input
    world.add_wire_connection(
        assets::components::LogicGate::BoolAnd.output_of(b_id),
        assets::components::Rerouter::input_of(a_id),
    );

    world
}

fn components_world() -> World {
    // Single grid, single chunk (all positions < 2048) — fully deterministic.
    // register_all_components() embeds the full component catalog so every
    // type below (light/interact/buffer/expr) resolves; each
    // component below carries non-default property values, and #4/#5 exercise
    // a WireValue-typed property (BufferTicks' Input/Output, and the Blend
    // gate's inputs).
    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Component fixture".to_string();

    // 1: Point light — non-default brightness/radius/color, decoupled from
    // brick color (bUseBrickColor: false).
    world.bricks.push(
        Brick {
            position: (0, 0, 6).into(),
            color: (255, 255, 255).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("Component_PointLight").with_data([
                ("bMatchBrickShape", Box::new(false) as Box<dyn AsBrdbValue>),
                ("bEnabled", Box::new(true)),
                ("Brightness", Box::new(500.0f32)),
                ("Radius", Box::new(800.0f32)),
                (
                    "Color",
                    Box::new(SavedBrickColor {
                        r: 10,
                        g: 20,
                        b: 30,
                        a: 255,
                    }),
                ),
                ("bUseBrickColor", Box::new(false)),
                ("bCastShadows", Box::new(true)),
            ]),
        ),
    );

    // 2: Spot light — narrow cone, non-default brightness/color.
    world.bricks.push(
        Brick {
            position: (20, 0, 6).into(),
            color: (255, 255, 0).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("Component_SpotLight").with_data([
                ("InnerConeAngle", Box::new(15.0f32) as Box<dyn AsBrdbValue>),
                ("OuterConeAngle", Box::new(45.0f32)),
                ("bEnabled", Box::new(true)),
                ("Brightness", Box::new(300.0f32)),
                ("Radius", Box::new(600.0f32)),
                (
                    "Color",
                    Box::new(SavedBrickColor {
                        r: 255,
                        g: 0,
                        b: 0,
                        a: 255,
                    }),
                ),
                ("bUseBrickColor", Box::new(false)),
                ("bCastShadows", Box::new(true)),
            ]),
        ),
    );

    // 3: Interact — custom prompt text, hidden interaction.
    world.bricks.push(
        Brick {
            position: (40, 0, 6).into(),
            color: (0, 255, 255).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("Component_Interact").with_data([
                (
                    "Message",
                    Box::new("You interacted!".to_string()) as Box<dyn AsBrdbValue>,
                ),
                ("ConsoleTag", Box::new("fixture_interact".to_string())),
                ("bAllowNearbyInteraction", Box::new(false)),
                ("bHiddenInteraction", Box::new(true)),
                ("PromptCustomLabel", Box::new("Open Door".to_string())),
            ]),
        ),
    );

    // 4: Buffer (ticks) — Input/Output are WireValue; non-default counters
    // plus a Number/Bool value pair.
    world.bricks.push(
        Brick {
            position: (60, 0, 1).into(),
            color: (128, 0, 128).into(),
            asset: assets::components::BufferTicks::default().brick(),
            ..Default::default()
        }
        .with_component(assets::components::BufferTicks {
            current_ticks: 3,
            ticks_to_wait: 10,
            input: WireValue::Number(2.5),
            output: WireValue::Bool(true),
            ..Default::default()
        }),
    );

    // 5: Blend gate — Expr_MathBlend's InputA/InputB are each a WireValue
    // (here an f64 and an i64, showing the value is polymorphic per-port);
    // Blend itself is a plain f64.
    world.bricks.push(
        Brick {
            position: (80, 0, 1).into(),
            color: (0, 128, 0).into(),
            asset: assets::components::LogicGate::Blend.brick(),
            ..Default::default()
        }
        .with_component(
            assets::components::LogicGate::Blend.component_with_overrides(HashMap::from([
                (
                    "InputA".into(),
                    Box::new(WireValue::Number(10.0)) as Box<dyn AsBrdbValue>,
                ),
                ("InputB".into(), Box::new(WireValue::Int(7))),
                ("Blend".into(), Box::new(0.75f64)),
            ])),
        ),
    );

    world
}

fn entities_world() -> World {
    // Mirror of examples/write_entity.rs's floating sub-grid — the first
    // grid added after the always-present main grid 1 gets persistent index
    // 2, so it lands at Grids/2 — plus a couple of main-grid (Grids/1)
    // bricks. Both grids are single-chunk; note the *outer* Grids/1 vs
    // Grids/2 folder order comes from a HashMap<usize, UnsavedGrid> in the
    // writer and is NOT guaranteed stable run-to-run (see stability notes).
    //
    // register_all_components() is required here (matching
    // test_write_entity_save, NOT the plain write_entity.rs example): without
    // it, Entity_DynamicBrickGrid's class name is never registered and the
    // write fails with `UnknownType("Entity_DynamicBrickGrid")` — confirmed
    // by running the crate's own unmodified write_entity example.
    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Entity fixture".to_string();

    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (200, 50, 50).into(),
        ..Default::default()
    });
    world.bricks.push(Brick {
        position: (20, 0, 6).into(),
        color: (50, 200, 50).into(),
        ..Default::default()
    });

    world.add_brick_grid(
        Entity {
            frozen: true,
            location: (0.0, 0.0, 40.0).into(),
            ..Default::default()
        },
        [Brick {
            position: (0, 0, 3).into(),
            color: (0, 255, 0).into(),
            ..Default::default()
        }],
    );

    world
}

fn spawner_world() -> World {
    // Prefab-embedding fixture: an outer prefab whose spawner gate references
    // an inner single-brick prefab embedded at Prefabs/Uploads/<BLAKE3>.brz.
    // Single grid, single chunk, one insertion-ordered prefab map entry —
    // fully deterministic. The inner archive is written raw (no zstd) so the
    // embedded bytes are cross-language reproducible.
    let mut inner = World::new();
    inner.meta.bundle.description = "Inner prefab".to_string();
    inner.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    inner.make_prefab();
    let inner_bytes = {
        let pending = inner.to_unsaved().unwrap().to_pending().unwrap();
        let mut buf = Vec::new();
        pending
            .to_brz_data(None)
            .unwrap()
            .write(&mut buf, None)
            .unwrap();
        buf
    };

    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Spawner fixture".to_string();
    let prefab_path = world.add_prefab(inner_bytes);
    world.bricks.push(
        Brick {
            asset: brdb::BrickType::str("B_1x1_Gate_Exec_PrefabSpawner"),
            position: (0, 0, 1).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("BrickComponentType_Exec_PrefabSpawner")
                .with_data([("Prefab", Box::new(prefab_path) as Box<dyn AsBrdbValue>)]),
        ),
    );
    world.make_prefab();
    world
}

/// `features_world` written in the Latest format.
fn features_latest_world() -> World {
    let mut world = features_world();
    world.schema_format = BrdbSchemaFormat::Latest;
    world
}

/// `entities_world` with the current build's schemas in the Latest format.
fn entities_latest_world() -> World {
    let mut world = World::new();
    world.schema_format = BrdbSchemaFormat::Latest;
    world.register_all_components();
    world.meta.bundle.description = "Entity fixture".to_string();
    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (200, 50, 50).into(),
        ..Default::default()
    });
    world.add_brick_grid(
        Entity {
            frozen: true,
            location: (0.0, 0.0, 40.0).into(),
            ..Default::default()
        },
        [Brick {
            position: (0, 0, 3).into(),
            color: (0, 255, 0).into(),
            ..Default::default()
        }],
    );
    world
}

/// Current-build components in the Latest format: WireValue fields, dynamic
/// arrays/maps (typed and empty) and a dynamic enum, plus a wire.
fn components_latest_world() -> World {
    let mut world = World::new();
    world.meta.bundle.description = "Latest component fixture".to_string();
    let gate = |x: i32, asset: &'static str| Brick {
        position: (x, 0, 1).into(),
        asset: BrickType::str(asset),
        ..Default::default()
    };

    // 1: Blend gate with WireValue inputs (f64 and i64 alternatives).
    let (blend, blend_id) = gate(0, "B_1x1_Gate_Expr_MathBlend")
        .with_component(
            assets::components::LogicGate::Blend.component_with_overrides(HashMap::from([
                (
                    "InputA".into(),
                    Box::new(WireValue::Number(1.5)) as Box<dyn AsBrdbValue>,
                ),
                ("InputB".into(), Box::new(WireValue::Int(-3))),
                ("Blend".into(), Box::new(0.25f64)),
            ])),
        )
        .with_id_split();
    // 2: Buffer with Str / Bool alternatives.
    let buffer =
        gate(20, "B_1x1_Gate_BufferTicks").with_component(assets::components::BufferTicks {
            ticks_to_wait: 4,
            input: WireValue::Str("hello".into()),
            output: WireValue::Bool(true),
            buffered: WireValue::Vector {
                x: 1.0,
                y: -2.0,
                z: 0.5,
            },
            ..Default::default()
        });
    // 3: Array variable holding i64 elements.
    let array = gate(40, "B_1x1_Gate_Variable_Array").with_component(
        assets::LiteralComponent::new("BrickComponentType_ArrayVar").with_data([(
            "Value",
            Box::new(BrdbDynamicArray::new(
                "i64",
                vec![BrdbValue::I64(7), BrdbValue::I64(300)],
            )) as Box<dyn AsBrdbValue>,
        )]),
    );
    // 4: Map variable from Str keys to f64 values.
    let map = gate(60, "B_1x1_Gate_Variable_Map").with_component(
        assets::LiteralComponent::new("BrickComponentType_MapVar").with_data([(
            "Value",
            Box::new(BrdbDynamicMap::new(
                "Str",
                "f64",
                [(BrdbValue::String("k".into()), BrdbValue::F64(2.5))]
                    .into_iter()
                    .collect(),
            )) as Box<dyn AsBrdbValue>,
        )]),
    );
    // 5: Unset array variable: the default empty container.
    let empty_array = gate(80, "B_1x1_Gate_Variable_Array")
        .with_component(assets::LiteralComponent::new("BrickComponentType_ArrayVar"));
    // 6: Integer to enum: a dynamic enum field.
    let to_enum = gate(100, "B_1x1_Gate_Expr_IntegerToEnum").with_component(
        assets::LiteralComponent::new("BrickComponentType_Expr_IntegerToEnum").with_data([
            ("Input", Box::new(2i64) as Box<dyn AsBrdbValue>),
            (
                "TargetType",
                Box::new(BrdbDynamicEnum::new("EBrickAxis", 0)),
            ),
        ]),
    );
    // 7: A rerouter fed by the blend gate.
    let (reroute, reroute_id) = Brick {
        position: (120, 0, 1).into(),
        asset: assets::bricks::B_REROUTE,
        ..Default::default()
    }
    .with_component(assets::components::Rerouter)
    .with_id_split();

    world.add_bricks([blend, buffer, array, map, empty_array, to_enum, reroute]);
    world.add_wire_connection(
        assets::components::LogicGate::Blend.output_of(blend_id),
        assets::components::Rerouter::input_of(reroute_id),
    );
    // Embed only the structs these components use (what brs-js writes).
    world.register_used_components();
    world
}

examples/write_brick.rs (line 8)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = PathBuf::from("./example_brick.brdb");

    let mut world = World::new();
    world.meta.bundle.description = "Example World".to_string();
    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });

    world.write_brdb(&path)?;

    let db = Brdb::new(&path)?.into_reader();

    println!("file structure: {}", db.get_fs()?.render());

    let soa = db.brick_chunk_soa(1, (0, 0, 0).into())?;
    let color = soa.colors_and_alphas[0];
    assert_eq!(color.r, 255);
    assert_eq!(color.g, 0);
    assert_eq!(color.b, 0);
    assert_eq!(color.a, 5);

    Ok(())
}

examples/write_entity.rs (line 10)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = PathBuf::from("./example_entity.brdb");

    // Ensures the memory db can be created without errors
    let db = Brdb::new(&path)?.into_reader();
    let mut world = World::new();
    world.meta.bundle.description = "Example World".to_string();
    world.add_brick_grid(
        Entity {
            frozen: true,
            location: (0.0, 0.0, 40.0).into(),
            ..Default::default()
        },
        [Brick {
            position: (0, 0, 3).into(),
            color: (0, 255, 0).into(),
            ..Default::default()
        }],
    );

    db.save("example world", &world)?;

    println!("{}", db.get_fs()?.render());

    Ok(())
}

examples/write_brz.rs (line 8)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = PathBuf::from("./example_brick.brz");

    let mut world = World::new();
    world.meta.bundle.description = "Example World".to_string();
    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });

    if path.exists() {
        std::fs::remove_file(&path)?;
    }
    world.write_brz(&path)?;

    let db = Brz::new(&path)?.into_reader();

    println!("{}", db.get_fs()?.render());

    let soa = db.brick_chunk_soa(1, (0, 0, 0).into())?;
    let color = soa.colors_and_alphas[0];
    assert_eq!(color.r, 255);
    assert_eq!(color.g, 0);
    assert_eq!(color.b, 0);
    assert_eq!(color.a, 5);

    Ok(())
}

examples/write_prefab.rs (line 8)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = PathBuf::from("./example_prefab.brz");

    let mut world = World::new();
    // A single 1x1 plate-ish brick (half-extent 5,5,2) at the origin so the
    // bounds match the hand-captured reference prefab.
    world.bricks.push(Brick {
        asset: BrickType::Procedural {
            asset: assets::bricks::PB_DEFAULT_BRICK.into(),
            size: BrickSize { x: 5, y: 5, z: 2 },
        },
        position: (0, 0, 0).into(),
        ..Default::default()
    });

    world.make_prefab();
    println!(
        "Prefab.json:\n{}",
        serde_json::to_string_pretty(world.meta.prefab.as_ref().unwrap())?
    );
    println!(
        "Bundle.json:\n{}",
        serde_json::to_string_pretty(&world.meta.bundle)?
    );

    if path.exists() {
        std::fs::remove_file(&path)?;
    }
    world.write_brz(&path)?;
    println!("wrote {}", path.display());
    Ok(())
}

examples/write_wire.rs (line 10)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = PathBuf::from("./example_wire.brdb");

    // Ensures the memory db can be created without errors
    let db = Brdb::new(&path)?.into_reader();
    let mut world = World::new();
    // Register the built-in component type/struct mappings so the gate and
    // rerouter component types resolve when writing.
    world.register_all_components();
    world.meta.bundle.description = "Example World".to_string();

    let (a, a_id) = Brick {
        position: (0, 0, 1).into(),
        color: (255, 0, 0).into(),
        asset: assets::bricks::B_REROUTE,
        ..Default::default()
    }
    .with_component(assets::components::Rerouter)
    .with_id_split();
    let (b, b_id) = Brick {
        position: (15, 0, 1).into(),
        color: (255, 0, 0).into(),
        asset: assets::components::LogicGate::BoolNot.brick(),
        ..Default::default()
    }
    .with_component(assets::components::LogicGate::BoolNot.component())
    .with_id_split();

    world.add_bricks([a, b]);
    world.add_wire_connection(
        assets::components::LogicGate::BoolNot.output_of(b_id),
        assets::components::Rerouter::input_of(a_id),
    );

    db.save("example world", &world)?;

    println!("{}", db.get_fs()?.render());

    Ok(())
}

Additional examples can be found in:

• examples/write_prefab_spawner.rs

pub fn write_brdb(&self, path: impl AsRef<Path>) -> Result<(), BrError>

Examples found in repository

examples/write_brick.rs (line 16)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = PathBuf::from("./example_brick.brdb");

    let mut world = World::new();
    world.meta.bundle.description = "Example World".to_string();
    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });

    world.write_brdb(&path)?;

    let db = Brdb::new(&path)?.into_reader();

    println!("file structure: {}", db.get_fs()?.render());

    let soa = db.brick_chunk_soa(1, (0, 0, 0).into())?;
    let color = soa.colors_and_alphas[0];
    assert_eq!(color.r, 255);
    assert_eq!(color.g, 0);
    assert_eq!(color.b, 0);
    assert_eq!(color.a, 5);

    Ok(())
}

pub fn write_brz(&self, path: impl AsRef<Path>) -> Result<(), BrError>

Examples found in repository

examples/write_brz.rs (line 19)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = PathBuf::from("./example_brick.brz");

    let mut world = World::new();
    world.meta.bundle.description = "Example World".to_string();
    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });

    if path.exists() {
        std::fs::remove_file(&path)?;
    }
    world.write_brz(&path)?;

    let db = Brz::new(&path)?.into_reader();

    println!("{}", db.get_fs()?.render());

    let soa = db.brick_chunk_soa(1, (0, 0, 0).into())?;
    let color = soa.colors_and_alphas[0];
    assert_eq!(color.r, 255);
    assert_eq!(color.g, 0);
    assert_eq!(color.b, 0);
    assert_eq!(color.a, 5);

    Ok(())
}

examples/write_prefab.rs (line 33)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = PathBuf::from("./example_prefab.brz");

    let mut world = World::new();
    // A single 1x1 plate-ish brick (half-extent 5,5,2) at the origin so the
    // bounds match the hand-captured reference prefab.
    world.bricks.push(Brick {
        asset: BrickType::Procedural {
            asset: assets::bricks::PB_DEFAULT_BRICK.into(),
            size: BrickSize { x: 5, y: 5, z: 2 },
        },
        position: (0, 0, 0).into(),
        ..Default::default()
    });

    world.make_prefab();
    println!(
        "Prefab.json:\n{}",
        serde_json::to_string_pretty(world.meta.prefab.as_ref().unwrap())?
    );
    println!(
        "Bundle.json:\n{}",
        serde_json::to_string_pretty(&world.meta.bundle)?
    );

    if path.exists() {
        std::fs::remove_file(&path)?;
    }
    world.write_brz(&path)?;
    println!("wrote {}", path.display());
    Ok(())
}

examples/write_prefab_spawner.rs (line 80)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Build the prefab that gets spawned: a single red brick.
    let mut prefab = World::new();
    prefab.meta.bundle.name = "Spawned Brick".to_string();
    prefab.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    prefab.make_prefab();
    let prefab_bytes = prefab.to_brz_vec()?;

    // 2. Build the outer world holding the button + spawner.
    let mut world = World::new();
    // Registers the built-in component/port tables so the Button and
    // PrefabSpawner component types and their wire ports resolve.
    world.register_all_components();
    world.meta.bundle.description = "Button-triggered prefab spawner".to_string();

    // Embed the prefab; the returned path is what the spawner references.
    let prefab_path = world.add_prefab(prefab_bytes);

    // A pressable button (Component_Button on a 1x1 flat round brick). The
    // crate exposes brick assets as constants; components it doesn't model as
    // typed gates (like the button and spawner) are built from string names
    // via LiteralComponent.
    let (button, button_id) = Brick {
        position: (0, 0, 2).into(),
        color: (0, 255, 0).into(),
        asset: assets::bricks::B_1X1F_ROUND,
        ..Default::default()
    }
    .with_component(assets::LiteralComponent::new("Component_Button").with_data([(
        "PromptCustomLabel",
        Box::new("Spawn Brick".to_string()) as Box<dyn AsBrdbValue>,
    )]))
    .with_id_split();

    // The prefab-spawner gate, pointed at the embedded prefab.
    let (spawner, spawner_id) = Brick {
        position: (15, 0, 1).into(),
        color: (0, 0, 255).into(),
        asset: assets::bricks::B_1X1_GATE_EXEC_PREFAB_SPAWNER,
        ..Default::default()
    }
    .with_component(
        assets::LiteralComponent::new("BrickComponentType_WireGraph_Exec_PrefabSpawner").with_data(
            [(
                "Prefab",
                Box::new(prefab_path.clone()) as Box<dyn AsBrdbValue>,
            )],
        ),
    )
    .with_id_split();

    world.add_bricks([button, spawner]);

    // Wire the button's held signal into the spawner's Exec input, so a
    // press fires the spawn.
    world.add_wire_connection(
        WirePort::new(button_id, "Component_Button", "bHeld"),
        WirePort::new(
            spawner_id,
            "BrickComponentType_WireGraph_Exec_PrefabSpawner",
            "Exec",
        ),
    );

    // 3. Write it out.
    let path = PathBuf::from("./example_prefab_spawner.brz");
    world.write_brz(&path)?;
    println!("wrote {}", path.display());

    // Read it back to confirm the embedded prefab and wire survived.
    let reader = Brz::open(&path)?.into_reader();
    println!("embedded prefab: {}", prefab_path);
    println!("prefab paths in archive: {:?}", reader.prefab_paths()?);
    println!("{}", reader.get_fs()?.render());

    Ok(())
}

pub fn to_brz_vec(&self) -> Result<Vec<u8>, BrError>

Examples found in repository

examples/write_prefab_spawner.rs (line 20)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Build the prefab that gets spawned: a single red brick.
    let mut prefab = World::new();
    prefab.meta.bundle.name = "Spawned Brick".to_string();
    prefab.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    prefab.make_prefab();
    let prefab_bytes = prefab.to_brz_vec()?;

    // 2. Build the outer world holding the button + spawner.
    let mut world = World::new();
    // Registers the built-in component/port tables so the Button and
    // PrefabSpawner component types and their wire ports resolve.
    world.register_all_components();
    world.meta.bundle.description = "Button-triggered prefab spawner".to_string();

    // Embed the prefab; the returned path is what the spawner references.
    let prefab_path = world.add_prefab(prefab_bytes);

    // A pressable button (Component_Button on a 1x1 flat round brick). The
    // crate exposes brick assets as constants; components it doesn't model as
    // typed gates (like the button and spawner) are built from string names
    // via LiteralComponent.
    let (button, button_id) = Brick {
        position: (0, 0, 2).into(),
        color: (0, 255, 0).into(),
        asset: assets::bricks::B_1X1F_ROUND,
        ..Default::default()
    }
    .with_component(assets::LiteralComponent::new("Component_Button").with_data([(
        "PromptCustomLabel",
        Box::new("Spawn Brick".to_string()) as Box<dyn AsBrdbValue>,
    )]))
    .with_id_split();

    // The prefab-spawner gate, pointed at the embedded prefab.
    let (spawner, spawner_id) = Brick {
        position: (15, 0, 1).into(),
        color: (0, 0, 255).into(),
        asset: assets::bricks::B_1X1_GATE_EXEC_PREFAB_SPAWNER,
        ..Default::default()
    }
    .with_component(
        assets::LiteralComponent::new("BrickComponentType_WireGraph_Exec_PrefabSpawner").with_data(
            [(
                "Prefab",
                Box::new(prefab_path.clone()) as Box<dyn AsBrdbValue>,
            )],
        ),
    )
    .with_id_split();

    world.add_bricks([button, spawner]);

    // Wire the button's held signal into the spawner's Exec input, so a
    // press fires the spawn.
    world.add_wire_connection(
        WirePort::new(button_id, "Component_Button", "bHeld"),
        WirePort::new(
            spawner_id,
            "BrickComponentType_WireGraph_Exec_PrefabSpawner",
            "Exec",
        ),
    );

    // 3. Write it out.
    let path = PathBuf::from("./example_prefab_spawner.brz");
    world.write_brz(&path)?;
    println!("wrote {}", path.display());

    // Read it back to confirm the embedded prefab and wire survived.
    let reader = Brz::open(&path)?.into_reader();
    println!("embedded prefab: {}", prefab_path);
    println!("prefab paths in archive: {:?}", reader.prefab_paths()?);
    println!("{}", reader.get_fs()?.render());

    Ok(())
}

pub fn register_all_components(&mut self)

Load the full component schema and register all known type→struct mappings and wire port names from the built-in component database.

Examples found in repository

examples/write_wire.rs (line 13)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = PathBuf::from("./example_wire.brdb");

    // Ensures the memory db can be created without errors
    let db = Brdb::new(&path)?.into_reader();
    let mut world = World::new();
    // Register the built-in component type/struct mappings so the gate and
    // rerouter component types resolve when writing.
    world.register_all_components();
    world.meta.bundle.description = "Example World".to_string();

    let (a, a_id) = Brick {
        position: (0, 0, 1).into(),
        color: (255, 0, 0).into(),
        asset: assets::bricks::B_REROUTE,
        ..Default::default()
    }
    .with_component(assets::components::Rerouter)
    .with_id_split();
    let (b, b_id) = Brick {
        position: (15, 0, 1).into(),
        color: (255, 0, 0).into(),
        asset: assets::components::LogicGate::BoolNot.brick(),
        ..Default::default()
    }
    .with_component(assets::components::LogicGate::BoolNot.component())
    .with_id_split();

    world.add_bricks([a, b]);
    world.add_wire_connection(
        assets::components::LogicGate::BoolNot.output_of(b_id),
        assets::components::Rerouter::input_of(a_id),
    );

    db.save("example world", &world)?;

    println!("{}", db.get_fs()?.render());

    Ok(())
}

examples/write_fixtures.rs (line 180)

fn wires_world() -> World {
    // Mirror of examples/write_wire.rs (single grid, single chunk — fully
    // deterministic), extended to 3 bricks/2 wires: a boolean NOT gate feeds
    // one input of an AND gate, whose output feeds a rerouter.
    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Wire fixture".to_string();

    let (a, a_id) = Brick {
        position: (30, 0, 1).into(),
        color: (255, 0, 0).into(),
        asset: assets::bricks::B_REROUTE,
        ..Default::default()
    }
    .with_component(assets::components::Rerouter)
    .with_id_split();
    let (b, b_id) = Brick {
        position: (15, 0, 1).into(),
        color: (0, 255, 0).into(),
        asset: assets::components::LogicGate::BoolAnd.brick(),
        ..Default::default()
    }
    .with_component(assets::components::LogicGate::BoolAnd.component())
    .with_id_split();
    let (c, c_id) = Brick {
        position: (0, 0, 1).into(),
        color: (0, 0, 255).into(),
        asset: assets::components::LogicGate::BoolNot.brick(),
        ..Default::default()
    }
    .with_component(assets::components::LogicGate::BoolNot.component())
    .with_id_split();

    world.add_bricks([a, b, c]);
    // Wire 1: NOT.output -> AND.inputA
    world.add_wire_connection(
        assets::components::LogicGate::BoolNot.output_of(c_id),
        assets::components::LogicGate::BoolAnd.input_a_of(b_id),
    );
    // Wire 2: AND.output -> Rerouter.input
    world.add_wire_connection(
        assets::components::LogicGate::BoolAnd.output_of(b_id),
        assets::components::Rerouter::input_of(a_id),
    );

    world
}

fn components_world() -> World {
    // Single grid, single chunk (all positions < 2048) — fully deterministic.
    // register_all_components() embeds the full component catalog so every
    // type below (light/interact/buffer/expr) resolves; each
    // component below carries non-default property values, and #4/#5 exercise
    // a WireValue-typed property (BufferTicks' Input/Output, and the Blend
    // gate's inputs).
    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Component fixture".to_string();

    // 1: Point light — non-default brightness/radius/color, decoupled from
    // brick color (bUseBrickColor: false).
    world.bricks.push(
        Brick {
            position: (0, 0, 6).into(),
            color: (255, 255, 255).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("Component_PointLight").with_data([
                ("bMatchBrickShape", Box::new(false) as Box<dyn AsBrdbValue>),
                ("bEnabled", Box::new(true)),
                ("Brightness", Box::new(500.0f32)),
                ("Radius", Box::new(800.0f32)),
                (
                    "Color",
                    Box::new(SavedBrickColor {
                        r: 10,
                        g: 20,
                        b: 30,
                        a: 255,
                    }),
                ),
                ("bUseBrickColor", Box::new(false)),
                ("bCastShadows", Box::new(true)),
            ]),
        ),
    );

    // 2: Spot light — narrow cone, non-default brightness/color.
    world.bricks.push(
        Brick {
            position: (20, 0, 6).into(),
            color: (255, 255, 0).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("Component_SpotLight").with_data([
                ("InnerConeAngle", Box::new(15.0f32) as Box<dyn AsBrdbValue>),
                ("OuterConeAngle", Box::new(45.0f32)),
                ("bEnabled", Box::new(true)),
                ("Brightness", Box::new(300.0f32)),
                ("Radius", Box::new(600.0f32)),
                (
                    "Color",
                    Box::new(SavedBrickColor {
                        r: 255,
                        g: 0,
                        b: 0,
                        a: 255,
                    }),
                ),
                ("bUseBrickColor", Box::new(false)),
                ("bCastShadows", Box::new(true)),
            ]),
        ),
    );

    // 3: Interact — custom prompt text, hidden interaction.
    world.bricks.push(
        Brick {
            position: (40, 0, 6).into(),
            color: (0, 255, 255).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("Component_Interact").with_data([
                (
                    "Message",
                    Box::new("You interacted!".to_string()) as Box<dyn AsBrdbValue>,
                ),
                ("ConsoleTag", Box::new("fixture_interact".to_string())),
                ("bAllowNearbyInteraction", Box::new(false)),
                ("bHiddenInteraction", Box::new(true)),
                ("PromptCustomLabel", Box::new("Open Door".to_string())),
            ]),
        ),
    );

    // 4: Buffer (ticks) — Input/Output are WireValue; non-default counters
    // plus a Number/Bool value pair.
    world.bricks.push(
        Brick {
            position: (60, 0, 1).into(),
            color: (128, 0, 128).into(),
            asset: assets::components::BufferTicks::default().brick(),
            ..Default::default()
        }
        .with_component(assets::components::BufferTicks {
            current_ticks: 3,
            ticks_to_wait: 10,
            input: WireValue::Number(2.5),
            output: WireValue::Bool(true),
            ..Default::default()
        }),
    );

    // 5: Blend gate — Expr_MathBlend's InputA/InputB are each a WireValue
    // (here an f64 and an i64, showing the value is polymorphic per-port);
    // Blend itself is a plain f64.
    world.bricks.push(
        Brick {
            position: (80, 0, 1).into(),
            color: (0, 128, 0).into(),
            asset: assets::components::LogicGate::Blend.brick(),
            ..Default::default()
        }
        .with_component(
            assets::components::LogicGate::Blend.component_with_overrides(HashMap::from([
                (
                    "InputA".into(),
                    Box::new(WireValue::Number(10.0)) as Box<dyn AsBrdbValue>,
                ),
                ("InputB".into(), Box::new(WireValue::Int(7))),
                ("Blend".into(), Box::new(0.75f64)),
            ])),
        ),
    );

    world
}

fn entities_world() -> World {
    // Mirror of examples/write_entity.rs's floating sub-grid — the first
    // grid added after the always-present main grid 1 gets persistent index
    // 2, so it lands at Grids/2 — plus a couple of main-grid (Grids/1)
    // bricks. Both grids are single-chunk; note the *outer* Grids/1 vs
    // Grids/2 folder order comes from a HashMap<usize, UnsavedGrid> in the
    // writer and is NOT guaranteed stable run-to-run (see stability notes).
    //
    // register_all_components() is required here (matching
    // test_write_entity_save, NOT the plain write_entity.rs example): without
    // it, Entity_DynamicBrickGrid's class name is never registered and the
    // write fails with `UnknownType("Entity_DynamicBrickGrid")` — confirmed
    // by running the crate's own unmodified write_entity example.
    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Entity fixture".to_string();

    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (200, 50, 50).into(),
        ..Default::default()
    });
    world.bricks.push(Brick {
        position: (20, 0, 6).into(),
        color: (50, 200, 50).into(),
        ..Default::default()
    });

    world.add_brick_grid(
        Entity {
            frozen: true,
            location: (0.0, 0.0, 40.0).into(),
            ..Default::default()
        },
        [Brick {
            position: (0, 0, 3).into(),
            color: (0, 255, 0).into(),
            ..Default::default()
        }],
    );

    world
}

fn spawner_world() -> World {
    // Prefab-embedding fixture: an outer prefab whose spawner gate references
    // an inner single-brick prefab embedded at Prefabs/Uploads/<BLAKE3>.brz.
    // Single grid, single chunk, one insertion-ordered prefab map entry —
    // fully deterministic. The inner archive is written raw (no zstd) so the
    // embedded bytes are cross-language reproducible.
    let mut inner = World::new();
    inner.meta.bundle.description = "Inner prefab".to_string();
    inner.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    inner.make_prefab();
    let inner_bytes = {
        let pending = inner.to_unsaved().unwrap().to_pending().unwrap();
        let mut buf = Vec::new();
        pending
            .to_brz_data(None)
            .unwrap()
            .write(&mut buf, None)
            .unwrap();
        buf
    };

    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Spawner fixture".to_string();
    let prefab_path = world.add_prefab(inner_bytes);
    world.bricks.push(
        Brick {
            asset: brdb::BrickType::str("B_1x1_Gate_Exec_PrefabSpawner"),
            position: (0, 0, 1).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("BrickComponentType_Exec_PrefabSpawner")
                .with_data([("Prefab", Box::new(prefab_path) as Box<dyn AsBrdbValue>)]),
        ),
    );
    world.make_prefab();
    world
}

/// `features_world` written in the Latest format.
fn features_latest_world() -> World {
    let mut world = features_world();
    world.schema_format = BrdbSchemaFormat::Latest;
    world
}

/// `entities_world` with the current build's schemas in the Latest format.
fn entities_latest_world() -> World {
    let mut world = World::new();
    world.schema_format = BrdbSchemaFormat::Latest;
    world.register_all_components();
    world.meta.bundle.description = "Entity fixture".to_string();
    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (200, 50, 50).into(),
        ..Default::default()
    });
    world.add_brick_grid(
        Entity {
            frozen: true,
            location: (0.0, 0.0, 40.0).into(),
            ..Default::default()
        },
        [Brick {
            position: (0, 0, 3).into(),
            color: (0, 255, 0).into(),
            ..Default::default()
        }],
    );
    world
}

examples/write_prefab_spawner.rs (line 26)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Build the prefab that gets spawned: a single red brick.
    let mut prefab = World::new();
    prefab.meta.bundle.name = "Spawned Brick".to_string();
    prefab.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    prefab.make_prefab();
    let prefab_bytes = prefab.to_brz_vec()?;

    // 2. Build the outer world holding the button + spawner.
    let mut world = World::new();
    // Registers the built-in component/port tables so the Button and
    // PrefabSpawner component types and their wire ports resolve.
    world.register_all_components();
    world.meta.bundle.description = "Button-triggered prefab spawner".to_string();

    // Embed the prefab; the returned path is what the spawner references.
    let prefab_path = world.add_prefab(prefab_bytes);

    // A pressable button (Component_Button on a 1x1 flat round brick). The
    // crate exposes brick assets as constants; components it doesn't model as
    // typed gates (like the button and spawner) are built from string names
    // via LiteralComponent.
    let (button, button_id) = Brick {
        position: (0, 0, 2).into(),
        color: (0, 255, 0).into(),
        asset: assets::bricks::B_1X1F_ROUND,
        ..Default::default()
    }
    .with_component(assets::LiteralComponent::new("Component_Button").with_data([(
        "PromptCustomLabel",
        Box::new("Spawn Brick".to_string()) as Box<dyn AsBrdbValue>,
    )]))
    .with_id_split();

    // The prefab-spawner gate, pointed at the embedded prefab.
    let (spawner, spawner_id) = Brick {
        position: (15, 0, 1).into(),
        color: (0, 0, 255).into(),
        asset: assets::bricks::B_1X1_GATE_EXEC_PREFAB_SPAWNER,
        ..Default::default()
    }
    .with_component(
        assets::LiteralComponent::new("BrickComponentType_WireGraph_Exec_PrefabSpawner").with_data(
            [(
                "Prefab",
                Box::new(prefab_path.clone()) as Box<dyn AsBrdbValue>,
            )],
        ),
    )
    .with_id_split();

    world.add_bricks([button, spawner]);

    // Wire the button's held signal into the spawner's Exec input, so a
    // press fires the spawn.
    world.add_wire_connection(
        WirePort::new(button_id, "Component_Button", "bHeld"),
        WirePort::new(
            spawner_id,
            "BrickComponentType_WireGraph_Exec_PrefabSpawner",
            "Exec",
        ),
    );

    // 3. Write it out.
    let path = PathBuf::from("./example_prefab_spawner.brz");
    world.write_brz(&path)?;
    println!("wrote {}", path.display());

    // Read it back to confirm the embedded prefab and wire survived.
    let reader = Brz::open(&path)?.into_reader();
    println!("embedded prefab: {}", prefab_path);
    println!("prefab paths in archive: {:?}", reader.prefab_paths()?);
    println!("{}", reader.get_fs()?.render());

    Ok(())
}

pub fn register_used_components(&mut self)

Register only the components actually used by this world’s bricks, mirroring how the game embeds a bundle: ComponentsShared.schema and the global-data component tables carry only the data structs that appear, not the full catalog (which [register_all_components] embeds).

Call this AFTER all bricks/grids have been added. The component schema starts from the minimal SoA scaffolding and gains each used component’s data struct plus its transitive type dependencies; global-data component type/struct/port tables are rebuilt to match. Entity types are registered in full (the catalog is a single microchip-grid entry).

This keeps generated bundles byte-compatible with what the current game build writes — embedding the stale full catalog can make the game reject the schema (“while building schema: while reading struct count”).

Examples found in repository

examples/write_fixtures.rs (line 565)

fn components_latest_world() -> World {
    let mut world = World::new();
    world.meta.bundle.description = "Latest component fixture".to_string();
    let gate = |x: i32, asset: &'static str| Brick {
        position: (x, 0, 1).into(),
        asset: BrickType::str(asset),
        ..Default::default()
    };

    // 1: Blend gate with WireValue inputs (f64 and i64 alternatives).
    let (blend, blend_id) = gate(0, "B_1x1_Gate_Expr_MathBlend")
        .with_component(
            assets::components::LogicGate::Blend.component_with_overrides(HashMap::from([
                (
                    "InputA".into(),
                    Box::new(WireValue::Number(1.5)) as Box<dyn AsBrdbValue>,
                ),
                ("InputB".into(), Box::new(WireValue::Int(-3))),
                ("Blend".into(), Box::new(0.25f64)),
            ])),
        )
        .with_id_split();
    // 2: Buffer with Str / Bool alternatives.
    let buffer =
        gate(20, "B_1x1_Gate_BufferTicks").with_component(assets::components::BufferTicks {
            ticks_to_wait: 4,
            input: WireValue::Str("hello".into()),
            output: WireValue::Bool(true),
            buffered: WireValue::Vector {
                x: 1.0,
                y: -2.0,
                z: 0.5,
            },
            ..Default::default()
        });
    // 3: Array variable holding i64 elements.
    let array = gate(40, "B_1x1_Gate_Variable_Array").with_component(
        assets::LiteralComponent::new("BrickComponentType_ArrayVar").with_data([(
            "Value",
            Box::new(BrdbDynamicArray::new(
                "i64",
                vec![BrdbValue::I64(7), BrdbValue::I64(300)],
            )) as Box<dyn AsBrdbValue>,
        )]),
    );
    // 4: Map variable from Str keys to f64 values.
    let map = gate(60, "B_1x1_Gate_Variable_Map").with_component(
        assets::LiteralComponent::new("BrickComponentType_MapVar").with_data([(
            "Value",
            Box::new(BrdbDynamicMap::new(
                "Str",
                "f64",
                [(BrdbValue::String("k".into()), BrdbValue::F64(2.5))]
                    .into_iter()
                    .collect(),
            )) as Box<dyn AsBrdbValue>,
        )]),
    );
    // 5: Unset array variable: the default empty container.
    let empty_array = gate(80, "B_1x1_Gate_Variable_Array")
        .with_component(assets::LiteralComponent::new("BrickComponentType_ArrayVar"));
    // 6: Integer to enum: a dynamic enum field.
    let to_enum = gate(100, "B_1x1_Gate_Expr_IntegerToEnum").with_component(
        assets::LiteralComponent::new("BrickComponentType_Expr_IntegerToEnum").with_data([
            ("Input", Box::new(2i64) as Box<dyn AsBrdbValue>),
            (
                "TargetType",
                Box::new(BrdbDynamicEnum::new("EBrickAxis", 0)),
            ),
        ]),
    );
    // 7: A rerouter fed by the blend gate.
    let (reroute, reroute_id) = Brick {
        position: (120, 0, 1).into(),
        asset: assets::bricks::B_REROUTE,
        ..Default::default()
    }
    .with_component(assets::components::Rerouter)
    .with_id_split();

    world.add_bricks([blend, buffer, array, map, empty_array, to_enum, reroute]);
    world.add_wire_connection(
        assets::components::LogicGate::Blend.output_of(blend_id),
        assets::components::Rerouter::input_of(reroute_id),
    );
    // Embed only the structs these components use (what brs-js writes).
    world.register_used_components();
    world
}

pub fn register_component_schema(&mut self, schema_str: &str)

Parse a schema string and merge its definitions.

pub fn register_component(&mut self, struct_name: &str)

Pull a single struct from the max schema.

pub fn brick_bounds(&self) -> Option<(Position, Position)>

Inclusive axis-aligned bounding box over the main-grid bricks, in brick units, as (min, max). Returns None if there are no main-grid bricks. Non-main grids (microchips) are excluded — their bricks live inside an entity and are offset to the chunk center.

pub fn make_prefab(&mut self)

Mark this world’s metadata as a prefab: sets the bundle type to "Prefab" and fills Meta/Prefab.json with pivots/bounds computed from the main-grid brick bounding box (see World::brick_bounds). The write path then emits a prefab bundle (Bundle.json + Prefab.json, plus the optional Screenshot/Thumbnail; no World.json).

Examples found in repository

examples/write_prefab.rs (line 20)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = PathBuf::from("./example_prefab.brz");

    let mut world = World::new();
    // A single 1x1 plate-ish brick (half-extent 5,5,2) at the origin so the
    // bounds match the hand-captured reference prefab.
    world.bricks.push(Brick {
        asset: BrickType::Procedural {
            asset: assets::bricks::PB_DEFAULT_BRICK.into(),
            size: BrickSize { x: 5, y: 5, z: 2 },
        },
        position: (0, 0, 0).into(),
        ..Default::default()
    });

    world.make_prefab();
    println!(
        "Prefab.json:\n{}",
        serde_json::to_string_pretty(world.meta.prefab.as_ref().unwrap())?
    );
    println!(
        "Bundle.json:\n{}",
        serde_json::to_string_pretty(&world.meta.bundle)?
    );

    if path.exists() {
        std::fs::remove_file(&path)?;
    }
    world.write_brz(&path)?;
    println!("wrote {}", path.display());
    Ok(())
}

examples/write_fixtures.rs (line 413)

fn spawner_world() -> World {
    // Prefab-embedding fixture: an outer prefab whose spawner gate references
    // an inner single-brick prefab embedded at Prefabs/Uploads/<BLAKE3>.brz.
    // Single grid, single chunk, one insertion-ordered prefab map entry —
    // fully deterministic. The inner archive is written raw (no zstd) so the
    // embedded bytes are cross-language reproducible.
    let mut inner = World::new();
    inner.meta.bundle.description = "Inner prefab".to_string();
    inner.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    inner.make_prefab();
    let inner_bytes = {
        let pending = inner.to_unsaved().unwrap().to_pending().unwrap();
        let mut buf = Vec::new();
        pending
            .to_brz_data(None)
            .unwrap()
            .write(&mut buf, None)
            .unwrap();
        buf
    };

    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Spawner fixture".to_string();
    let prefab_path = world.add_prefab(inner_bytes);
    world.bricks.push(
        Brick {
            asset: brdb::BrickType::str("B_1x1_Gate_Exec_PrefabSpawner"),
            position: (0, 0, 1).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("BrickComponentType_Exec_PrefabSpawner")
                .with_data([("Prefab", Box::new(prefab_path) as Box<dyn AsBrdbValue>)]),
        ),
    );
    world.make_prefab();
    world
}

examples/write_prefab_spawner.rs (line 19)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Build the prefab that gets spawned: a single red brick.
    let mut prefab = World::new();
    prefab.meta.bundle.name = "Spawned Brick".to_string();
    prefab.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    prefab.make_prefab();
    let prefab_bytes = prefab.to_brz_vec()?;

    // 2. Build the outer world holding the button + spawner.
    let mut world = World::new();
    // Registers the built-in component/port tables so the Button and
    // PrefabSpawner component types and their wire ports resolve.
    world.register_all_components();
    world.meta.bundle.description = "Button-triggered prefab spawner".to_string();

    // Embed the prefab; the returned path is what the spawner references.
    let prefab_path = world.add_prefab(prefab_bytes);

    // A pressable button (Component_Button on a 1x1 flat round brick). The
    // crate exposes brick assets as constants; components it doesn't model as
    // typed gates (like the button and spawner) are built from string names
    // via LiteralComponent.
    let (button, button_id) = Brick {
        position: (0, 0, 2).into(),
        color: (0, 255, 0).into(),
        asset: assets::bricks::B_1X1F_ROUND,
        ..Default::default()
    }
    .with_component(assets::LiteralComponent::new("Component_Button").with_data([(
        "PromptCustomLabel",
        Box::new("Spawn Brick".to_string()) as Box<dyn AsBrdbValue>,
    )]))
    .with_id_split();

    // The prefab-spawner gate, pointed at the embedded prefab.
    let (spawner, spawner_id) = Brick {
        position: (15, 0, 1).into(),
        color: (0, 0, 255).into(),
        asset: assets::bricks::B_1X1_GATE_EXEC_PREFAB_SPAWNER,
        ..Default::default()
    }
    .with_component(
        assets::LiteralComponent::new("BrickComponentType_WireGraph_Exec_PrefabSpawner").with_data(
            [(
                "Prefab",
                Box::new(prefab_path.clone()) as Box<dyn AsBrdbValue>,
            )],
        ),
    )
    .with_id_split();

    world.add_bricks([button, spawner]);

    // Wire the button's held signal into the spawner's Exec input, so a
    // press fires the spawn.
    world.add_wire_connection(
        WirePort::new(button_id, "Component_Button", "bHeld"),
        WirePort::new(
            spawner_id,
            "BrickComponentType_WireGraph_Exec_PrefabSpawner",
            "Exec",
        ),
    );

    // 3. Write it out.
    let path = PathBuf::from("./example_prefab_spawner.brz");
    world.write_brz(&path)?;
    println!("wrote {}", path.display());

    // Read it back to confirm the embedded prefab and wire survived.
    let reader = Brz::open(&path)?.into_reader();
    println!("embedded prefab: {}", prefab_path);
    println!("prefab paths in archive: {:?}", reader.prefab_paths()?);
    println!("{}", reader.get_fs()?.render());

    Ok(())
}

pub fn add_prefab(&mut self, brz_bytes: impl Into<Vec<u8>>) -> String

Embed a prefab archive, content-addressed the way the game does: Prefabs/Uploads/<BLAKE3-uppercase-hex>.brz. Returns that path — the exact string to store in a Prefab component property (bundle_path_ref), e.g. on BrickComponentType_PrefabSpawn or BrickComponentType_WireGraph_Exec_PrefabSpawner.

Examples found in repository

examples/write_fixtures.rs (line 428)

fn spawner_world() -> World {
    // Prefab-embedding fixture: an outer prefab whose spawner gate references
    // an inner single-brick prefab embedded at Prefabs/Uploads/<BLAKE3>.brz.
    // Single grid, single chunk, one insertion-ordered prefab map entry —
    // fully deterministic. The inner archive is written raw (no zstd) so the
    // embedded bytes are cross-language reproducible.
    let mut inner = World::new();
    inner.meta.bundle.description = "Inner prefab".to_string();
    inner.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    inner.make_prefab();
    let inner_bytes = {
        let pending = inner.to_unsaved().unwrap().to_pending().unwrap();
        let mut buf = Vec::new();
        pending
            .to_brz_data(None)
            .unwrap()
            .write(&mut buf, None)
            .unwrap();
        buf
    };

    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Spawner fixture".to_string();
    let prefab_path = world.add_prefab(inner_bytes);
    world.bricks.push(
        Brick {
            asset: brdb::BrickType::str("B_1x1_Gate_Exec_PrefabSpawner"),
            position: (0, 0, 1).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("BrickComponentType_Exec_PrefabSpawner")
                .with_data([("Prefab", Box::new(prefab_path) as Box<dyn AsBrdbValue>)]),
        ),
    );
    world.make_prefab();
    world
}

examples/write_prefab_spawner.rs (line 30)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Build the prefab that gets spawned: a single red brick.
    let mut prefab = World::new();
    prefab.meta.bundle.name = "Spawned Brick".to_string();
    prefab.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    prefab.make_prefab();
    let prefab_bytes = prefab.to_brz_vec()?;

    // 2. Build the outer world holding the button + spawner.
    let mut world = World::new();
    // Registers the built-in component/port tables so the Button and
    // PrefabSpawner component types and their wire ports resolve.
    world.register_all_components();
    world.meta.bundle.description = "Button-triggered prefab spawner".to_string();

    // Embed the prefab; the returned path is what the spawner references.
    let prefab_path = world.add_prefab(prefab_bytes);

    // A pressable button (Component_Button on a 1x1 flat round brick). The
    // crate exposes brick assets as constants; components it doesn't model as
    // typed gates (like the button and spawner) are built from string names
    // via LiteralComponent.
    let (button, button_id) = Brick {
        position: (0, 0, 2).into(),
        color: (0, 255, 0).into(),
        asset: assets::bricks::B_1X1F_ROUND,
        ..Default::default()
    }
    .with_component(assets::LiteralComponent::new("Component_Button").with_data([(
        "PromptCustomLabel",
        Box::new("Spawn Brick".to_string()) as Box<dyn AsBrdbValue>,
    )]))
    .with_id_split();

    // The prefab-spawner gate, pointed at the embedded prefab.
    let (spawner, spawner_id) = Brick {
        position: (15, 0, 1).into(),
        color: (0, 0, 255).into(),
        asset: assets::bricks::B_1X1_GATE_EXEC_PREFAB_SPAWNER,
        ..Default::default()
    }
    .with_component(
        assets::LiteralComponent::new("BrickComponentType_WireGraph_Exec_PrefabSpawner").with_data(
            [(
                "Prefab",
                Box::new(prefab_path.clone()) as Box<dyn AsBrdbValue>,
            )],
        ),
    )
    .with_id_split();

    world.add_bricks([button, spawner]);

    // Wire the button's held signal into the spawner's Exec input, so a
    // press fires the spawn.
    world.add_wire_connection(
        WirePort::new(button_id, "Component_Button", "bHeld"),
        WirePort::new(
            spawner_id,
            "BrickComponentType_WireGraph_Exec_PrefabSpawner",
            "Exec",
        ),
    );

    // 3. Write it out.
    let path = PathBuf::from("./example_prefab_spawner.brz");
    world.write_brz(&path)?;
    println!("wrote {}", path.display());

    // Read it back to confirm the embedded prefab and wire survived.
    let reader = Brz::open(&path)?.into_reader();
    println!("embedded prefab: {}", prefab_path);
    println!("prefab paths in archive: {:?}", reader.prefab_paths()?);
    println!("{}", reader.get_fs()?.render());

    Ok(())
}

pub fn add_prefab_world(&mut self, world: &World) -> Result<String, BrError>

Serialize world to an in-memory .brz and embed it as a prefab.

pub fn to_unsaved(&self) -> Result<UnsavedFs, BrError>

Examples found in repository

examples/write_fixtures.rs (line 415)

fn spawner_world() -> World {
    // Prefab-embedding fixture: an outer prefab whose spawner gate references
    // an inner single-brick prefab embedded at Prefabs/Uploads/<BLAKE3>.brz.
    // Single grid, single chunk, one insertion-ordered prefab map entry —
    // fully deterministic. The inner archive is written raw (no zstd) so the
    // embedded bytes are cross-language reproducible.
    let mut inner = World::new();
    inner.meta.bundle.description = "Inner prefab".to_string();
    inner.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    inner.make_prefab();
    let inner_bytes = {
        let pending = inner.to_unsaved().unwrap().to_pending().unwrap();
        let mut buf = Vec::new();
        pending
            .to_brz_data(None)
            .unwrap()
            .write(&mut buf, None)
            .unwrap();
        buf
    };

    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Spawner fixture".to_string();
    let prefab_path = world.add_prefab(inner_bytes);
    world.bricks.push(
        Brick {
            asset: brdb::BrickType::str("B_1x1_Gate_Exec_PrefabSpawner"),
            position: (0, 0, 1).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("BrickComponentType_Exec_PrefabSpawner")
                .with_data([("Prefab", Box::new(prefab_path) as Box<dyn AsBrdbValue>)]),
        ),
    );
    world.make_prefab();
    world
}

/// `features_world` written in the Latest format.
fn features_latest_world() -> World {
    let mut world = features_world();
    world.schema_format = BrdbSchemaFormat::Latest;
    world
}

/// `entities_world` with the current build's schemas in the Latest format.
fn entities_latest_world() -> World {
    let mut world = World::new();
    world.schema_format = BrdbSchemaFormat::Latest;
    world.register_all_components();
    world.meta.bundle.description = "Entity fixture".to_string();
    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (200, 50, 50).into(),
        ..Default::default()
    });
    world.add_brick_grid(
        Entity {
            frozen: true,
            location: (0.0, 0.0, 40.0).into(),
            ..Default::default()
        },
        [Brick {
            position: (0, 0, 3).into(),
            color: (0, 255, 0).into(),
            ..Default::default()
        }],
    );
    world
}

/// Current-build components in the Latest format: WireValue fields, dynamic
/// arrays/maps (typed and empty) and a dynamic enum, plus a wire.
fn components_latest_world() -> World {
    let mut world = World::new();
    world.meta.bundle.description = "Latest component fixture".to_string();
    let gate = |x: i32, asset: &'static str| Brick {
        position: (x, 0, 1).into(),
        asset: BrickType::str(asset),
        ..Default::default()
    };

    // 1: Blend gate with WireValue inputs (f64 and i64 alternatives).
    let (blend, blend_id) = gate(0, "B_1x1_Gate_Expr_MathBlend")
        .with_component(
            assets::components::LogicGate::Blend.component_with_overrides(HashMap::from([
                (
                    "InputA".into(),
                    Box::new(WireValue::Number(1.5)) as Box<dyn AsBrdbValue>,
                ),
                ("InputB".into(), Box::new(WireValue::Int(-3))),
                ("Blend".into(), Box::new(0.25f64)),
            ])),
        )
        .with_id_split();
    // 2: Buffer with Str / Bool alternatives.
    let buffer =
        gate(20, "B_1x1_Gate_BufferTicks").with_component(assets::components::BufferTicks {
            ticks_to_wait: 4,
            input: WireValue::Str("hello".into()),
            output: WireValue::Bool(true),
            buffered: WireValue::Vector {
                x: 1.0,
                y: -2.0,
                z: 0.5,
            },
            ..Default::default()
        });
    // 3: Array variable holding i64 elements.
    let array = gate(40, "B_1x1_Gate_Variable_Array").with_component(
        assets::LiteralComponent::new("BrickComponentType_ArrayVar").with_data([(
            "Value",
            Box::new(BrdbDynamicArray::new(
                "i64",
                vec![BrdbValue::I64(7), BrdbValue::I64(300)],
            )) as Box<dyn AsBrdbValue>,
        )]),
    );
    // 4: Map variable from Str keys to f64 values.
    let map = gate(60, "B_1x1_Gate_Variable_Map").with_component(
        assets::LiteralComponent::new("BrickComponentType_MapVar").with_data([(
            "Value",
            Box::new(BrdbDynamicMap::new(
                "Str",
                "f64",
                [(BrdbValue::String("k".into()), BrdbValue::F64(2.5))]
                    .into_iter()
                    .collect(),
            )) as Box<dyn AsBrdbValue>,
        )]),
    );
    // 5: Unset array variable: the default empty container.
    let empty_array = gate(80, "B_1x1_Gate_Variable_Array")
        .with_component(assets::LiteralComponent::new("BrickComponentType_ArrayVar"));
    // 6: Integer to enum: a dynamic enum field.
    let to_enum = gate(100, "B_1x1_Gate_Expr_IntegerToEnum").with_component(
        assets::LiteralComponent::new("BrickComponentType_Expr_IntegerToEnum").with_data([
            ("Input", Box::new(2i64) as Box<dyn AsBrdbValue>),
            (
                "TargetType",
                Box::new(BrdbDynamicEnum::new("EBrickAxis", 0)),
            ),
        ]),
    );
    // 7: A rerouter fed by the blend gate.
    let (reroute, reroute_id) = Brick {
        position: (120, 0, 1).into(),
        asset: assets::bricks::B_REROUTE,
        ..Default::default()
    }
    .with_component(assets::components::Rerouter)
    .with_id_split();

    world.add_bricks([blend, buffer, array, map, empty_array, to_enum, reroute]);
    world.add_wire_connection(
        assets::components::LogicGate::Blend.output_of(blend_id),
        assets::components::Rerouter::input_of(reroute_id),
    );
    // Embed only the structs these components use (what brs-js writes).
    world.register_used_components();
    world
}

fn hash_archive(
    path: &PathBuf,
) -> Result<BTreeMap<String, serde_json::Value>, Box<dyn std::error::Error>> {
    fn collect(fs: &BrFs, prefix: &str, out: &mut Vec<(String, Option<i64>)>) {
        match fs {
            BrFs::Root(children) => {
                for (n, c) in children {
                    collect(c, n, out);
                }
            }
            BrFs::Folder(_, children) => {
                for (n, c) in children {
                    collect(c, &format!("{prefix}/{n}"), out);
                }
            }
            BrFs::File(f) => out.push((prefix.to_string(), f.content_id)),
        }
    }
    let reader = Brz::open(path)?.into_reader();
    let reader = &*reader;
    let mut files = Vec::new();
    collect(&reader.get_fs()?, "", &mut files);
    let mut out = BTreeMap::new();
    for (p, content_id) in files {
        let content = match content_id {
            Some(id) => reader.find_blob(id)?.read()?,
            None => Vec::new(),
        };
        out.insert(
            p,
            serde_json::json!({
                "blake3": blake3::hash(&content).to_hex().to_string(),
                "len": content.len(),
            }),
        );
    }
    Ok(out)
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let dir = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("fixtures");
    fs::create_dir_all(dir.join("schemas"))?;

    let mut hashes = BTreeMap::new();
    for (name, world) in [
        ("brick", brick_world()),
        ("features", features_world()),
        ("chunks", chunks_world()),
        ("wires", wires_world()),
        ("components", components_world()),
        ("entities", entities_world()),
        ("spawner", spawner_world()),
        ("features_latest", features_latest_world()),
        ("components_latest", components_latest_world()),
        ("entities_latest", entities_latest_world()),
    ] {
        let pending = world.to_unsaved()?.to_pending()?;
        // raw variant: no zstd anywhere — byte-comparable across languages
        let raw_path = dir.join(format!("{name}_raw.brz"));
        let mut f = fs::File::create(&raw_path)?;
        pending.clone().to_brz_data(None)?.write(&mut f, None)?;
        // compressed variant: zstd level 14 (matches Brz::save)
        let mut f = fs::File::create(dir.join(format!("{name}.brz")))?;
        pending.to_brz_data(Some(14))?.write(&mut f, Some(14))?;

        // .brdb variant: content parity only (the .brdb container is not
        // byte-deterministic across runs).
        let db_path = dir.join(format!("{name}.brdb"));
        let _ = fs::remove_file(&db_path);
        Brdb::create(&db_path)?.save("Fixture", &world)?;

        hashes.insert(name.to_string(), hash_archive(&raw_path)?);
    }
    fs::write(
        dir.join("hashes.json"),
        serde_json::to_string_pretty(&hashes)?,
    )?;

    // The nine embedded schemas as binary msgpack (the exact bytes the
    // writer embeds as *.schema files inside archives).
    for (name, schema) in [
        ("BRSavedGlobalDataSoA", schemas::global_data_schema()),
        ("BRSavedOwnerTableSoA", schemas::owners_schema()),
        (
            "BRSavedBrickChunkIndexSoA",
            schemas::bricks_chunk_index_schema(),
        ),
        ("BRSavedBrickChunkSoA", schemas::bricks_chunks_schema()),
        ("BRSavedWireChunkSoA", schemas::bricks_wires_schema()),
        (
            "BRSavedComponentChunkSoA",
            schemas::bricks_components_schema_min(),
        ),
        (
            "BRSavedComponentChunkSoA_max",
            schemas::bricks_components_schema_max(),
        ),
        (
            "BRSavedEntityChunkIndexSoA",
            schemas::entities_chunk_index_schema(),
        ),
        ("BRSavedEntityChunkSoA", schemas::entities_chunks_schema()),
    ] {
        // Each schema in its own format (the current max schema has a
        // types table, so it is written in the Latest form).
        fs::write(dir.join(format!("schemas/{name}.bin")), schema.to_bytes()?)?;
    }
    eprintln!("fixtures written to {}", dir.display());
    Ok(())
}

pub fn add_brick(&mut self, brick: Brick)

Add a single brick to the world

pub fn add_bricks(&mut self, bricks: impl IntoIterator<Item = Brick>)

Add multiple bricks to the world

Examples found in repository

examples/write_wire.rs (line 33)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = PathBuf::from("./example_wire.brdb");

    // Ensures the memory db can be created without errors
    let db = Brdb::new(&path)?.into_reader();
    let mut world = World::new();
    // Register the built-in component type/struct mappings so the gate and
    // rerouter component types resolve when writing.
    world.register_all_components();
    world.meta.bundle.description = "Example World".to_string();

    let (a, a_id) = Brick {
        position: (0, 0, 1).into(),
        color: (255, 0, 0).into(),
        asset: assets::bricks::B_REROUTE,
        ..Default::default()
    }
    .with_component(assets::components::Rerouter)
    .with_id_split();
    let (b, b_id) = Brick {
        position: (15, 0, 1).into(),
        color: (255, 0, 0).into(),
        asset: assets::components::LogicGate::BoolNot.brick(),
        ..Default::default()
    }
    .with_component(assets::components::LogicGate::BoolNot.component())
    .with_id_split();

    world.add_bricks([a, b]);
    world.add_wire_connection(
        assets::components::LogicGate::BoolNot.output_of(b_id),
        assets::components::Rerouter::input_of(a_id),
    );

    db.save("example world", &world)?;

    println!("{}", db.get_fs()?.render());

    Ok(())
}

examples/write_fixtures.rs (line 208)

fn wires_world() -> World {
    // Mirror of examples/write_wire.rs (single grid, single chunk — fully
    // deterministic), extended to 3 bricks/2 wires: a boolean NOT gate feeds
    // one input of an AND gate, whose output feeds a rerouter.
    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Wire fixture".to_string();

    let (a, a_id) = Brick {
        position: (30, 0, 1).into(),
        color: (255, 0, 0).into(),
        asset: assets::bricks::B_REROUTE,
        ..Default::default()
    }
    .with_component(assets::components::Rerouter)
    .with_id_split();
    let (b, b_id) = Brick {
        position: (15, 0, 1).into(),
        color: (0, 255, 0).into(),
        asset: assets::components::LogicGate::BoolAnd.brick(),
        ..Default::default()
    }
    .with_component(assets::components::LogicGate::BoolAnd.component())
    .with_id_split();
    let (c, c_id) = Brick {
        position: (0, 0, 1).into(),
        color: (0, 0, 255).into(),
        asset: assets::components::LogicGate::BoolNot.brick(),
        ..Default::default()
    }
    .with_component(assets::components::LogicGate::BoolNot.component())
    .with_id_split();

    world.add_bricks([a, b, c]);
    // Wire 1: NOT.output -> AND.inputA
    world.add_wire_connection(
        assets::components::LogicGate::BoolNot.output_of(c_id),
        assets::components::LogicGate::BoolAnd.input_a_of(b_id),
    );
    // Wire 2: AND.output -> Rerouter.input
    world.add_wire_connection(
        assets::components::LogicGate::BoolAnd.output_of(b_id),
        assets::components::Rerouter::input_of(a_id),
    );

    world
}

fn components_world() -> World {
    // Single grid, single chunk (all positions < 2048) — fully deterministic.
    // register_all_components() embeds the full component catalog so every
    // type below (light/interact/buffer/expr) resolves; each
    // component below carries non-default property values, and #4/#5 exercise
    // a WireValue-typed property (BufferTicks' Input/Output, and the Blend
    // gate's inputs).
    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Component fixture".to_string();

    // 1: Point light — non-default brightness/radius/color, decoupled from
    // brick color (bUseBrickColor: false).
    world.bricks.push(
        Brick {
            position: (0, 0, 6).into(),
            color: (255, 255, 255).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("Component_PointLight").with_data([
                ("bMatchBrickShape", Box::new(false) as Box<dyn AsBrdbValue>),
                ("bEnabled", Box::new(true)),
                ("Brightness", Box::new(500.0f32)),
                ("Radius", Box::new(800.0f32)),
                (
                    "Color",
                    Box::new(SavedBrickColor {
                        r: 10,
                        g: 20,
                        b: 30,
                        a: 255,
                    }),
                ),
                ("bUseBrickColor", Box::new(false)),
                ("bCastShadows", Box::new(true)),
            ]),
        ),
    );

    // 2: Spot light — narrow cone, non-default brightness/color.
    world.bricks.push(
        Brick {
            position: (20, 0, 6).into(),
            color: (255, 255, 0).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("Component_SpotLight").with_data([
                ("InnerConeAngle", Box::new(15.0f32) as Box<dyn AsBrdbValue>),
                ("OuterConeAngle", Box::new(45.0f32)),
                ("bEnabled", Box::new(true)),
                ("Brightness", Box::new(300.0f32)),
                ("Radius", Box::new(600.0f32)),
                (
                    "Color",
                    Box::new(SavedBrickColor {
                        r: 255,
                        g: 0,
                        b: 0,
                        a: 255,
                    }),
                ),
                ("bUseBrickColor", Box::new(false)),
                ("bCastShadows", Box::new(true)),
            ]),
        ),
    );

    // 3: Interact — custom prompt text, hidden interaction.
    world.bricks.push(
        Brick {
            position: (40, 0, 6).into(),
            color: (0, 255, 255).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("Component_Interact").with_data([
                (
                    "Message",
                    Box::new("You interacted!".to_string()) as Box<dyn AsBrdbValue>,
                ),
                ("ConsoleTag", Box::new("fixture_interact".to_string())),
                ("bAllowNearbyInteraction", Box::new(false)),
                ("bHiddenInteraction", Box::new(true)),
                ("PromptCustomLabel", Box::new("Open Door".to_string())),
            ]),
        ),
    );

    // 4: Buffer (ticks) — Input/Output are WireValue; non-default counters
    // plus a Number/Bool value pair.
    world.bricks.push(
        Brick {
            position: (60, 0, 1).into(),
            color: (128, 0, 128).into(),
            asset: assets::components::BufferTicks::default().brick(),
            ..Default::default()
        }
        .with_component(assets::components::BufferTicks {
            current_ticks: 3,
            ticks_to_wait: 10,
            input: WireValue::Number(2.5),
            output: WireValue::Bool(true),
            ..Default::default()
        }),
    );

    // 5: Blend gate — Expr_MathBlend's InputA/InputB are each a WireValue
    // (here an f64 and an i64, showing the value is polymorphic per-port);
    // Blend itself is a plain f64.
    world.bricks.push(
        Brick {
            position: (80, 0, 1).into(),
            color: (0, 128, 0).into(),
            asset: assets::components::LogicGate::Blend.brick(),
            ..Default::default()
        }
        .with_component(
            assets::components::LogicGate::Blend.component_with_overrides(HashMap::from([
                (
                    "InputA".into(),
                    Box::new(WireValue::Number(10.0)) as Box<dyn AsBrdbValue>,
                ),
                ("InputB".into(), Box::new(WireValue::Int(7))),
                ("Blend".into(), Box::new(0.75f64)),
            ])),
        ),
    );

    world
}

fn entities_world() -> World {
    // Mirror of examples/write_entity.rs's floating sub-grid — the first
    // grid added after the always-present main grid 1 gets persistent index
    // 2, so it lands at Grids/2 — plus a couple of main-grid (Grids/1)
    // bricks. Both grids are single-chunk; note the *outer* Grids/1 vs
    // Grids/2 folder order comes from a HashMap<usize, UnsavedGrid> in the
    // writer and is NOT guaranteed stable run-to-run (see stability notes).
    //
    // register_all_components() is required here (matching
    // test_write_entity_save, NOT the plain write_entity.rs example): without
    // it, Entity_DynamicBrickGrid's class name is never registered and the
    // write fails with `UnknownType("Entity_DynamicBrickGrid")` — confirmed
    // by running the crate's own unmodified write_entity example.
    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Entity fixture".to_string();

    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (200, 50, 50).into(),
        ..Default::default()
    });
    world.bricks.push(Brick {
        position: (20, 0, 6).into(),
        color: (50, 200, 50).into(),
        ..Default::default()
    });

    world.add_brick_grid(
        Entity {
            frozen: true,
            location: (0.0, 0.0, 40.0).into(),
            ..Default::default()
        },
        [Brick {
            position: (0, 0, 3).into(),
            color: (0, 255, 0).into(),
            ..Default::default()
        }],
    );

    world
}

fn spawner_world() -> World {
    // Prefab-embedding fixture: an outer prefab whose spawner gate references
    // an inner single-brick prefab embedded at Prefabs/Uploads/<BLAKE3>.brz.
    // Single grid, single chunk, one insertion-ordered prefab map entry —
    // fully deterministic. The inner archive is written raw (no zstd) so the
    // embedded bytes are cross-language reproducible.
    let mut inner = World::new();
    inner.meta.bundle.description = "Inner prefab".to_string();
    inner.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    inner.make_prefab();
    let inner_bytes = {
        let pending = inner.to_unsaved().unwrap().to_pending().unwrap();
        let mut buf = Vec::new();
        pending
            .to_brz_data(None)
            .unwrap()
            .write(&mut buf, None)
            .unwrap();
        buf
    };

    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Spawner fixture".to_string();
    let prefab_path = world.add_prefab(inner_bytes);
    world.bricks.push(
        Brick {
            asset: brdb::BrickType::str("B_1x1_Gate_Exec_PrefabSpawner"),
            position: (0, 0, 1).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("BrickComponentType_Exec_PrefabSpawner")
                .with_data([("Prefab", Box::new(prefab_path) as Box<dyn AsBrdbValue>)]),
        ),
    );
    world.make_prefab();
    world
}

/// `features_world` written in the Latest format.
fn features_latest_world() -> World {
    let mut world = features_world();
    world.schema_format = BrdbSchemaFormat::Latest;
    world
}

/// `entities_world` with the current build's schemas in the Latest format.
fn entities_latest_world() -> World {
    let mut world = World::new();
    world.schema_format = BrdbSchemaFormat::Latest;
    world.register_all_components();
    world.meta.bundle.description = "Entity fixture".to_string();
    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (200, 50, 50).into(),
        ..Default::default()
    });
    world.add_brick_grid(
        Entity {
            frozen: true,
            location: (0.0, 0.0, 40.0).into(),
            ..Default::default()
        },
        [Brick {
            position: (0, 0, 3).into(),
            color: (0, 255, 0).into(),
            ..Default::default()
        }],
    );
    world
}

/// Current-build components in the Latest format: WireValue fields, dynamic
/// arrays/maps (typed and empty) and a dynamic enum, plus a wire.
fn components_latest_world() -> World {
    let mut world = World::new();
    world.meta.bundle.description = "Latest component fixture".to_string();
    let gate = |x: i32, asset: &'static str| Brick {
        position: (x, 0, 1).into(),
        asset: BrickType::str(asset),
        ..Default::default()
    };

    // 1: Blend gate with WireValue inputs (f64 and i64 alternatives).
    let (blend, blend_id) = gate(0, "B_1x1_Gate_Expr_MathBlend")
        .with_component(
            assets::components::LogicGate::Blend.component_with_overrides(HashMap::from([
                (
                    "InputA".into(),
                    Box::new(WireValue::Number(1.5)) as Box<dyn AsBrdbValue>,
                ),
                ("InputB".into(), Box::new(WireValue::Int(-3))),
                ("Blend".into(), Box::new(0.25f64)),
            ])),
        )
        .with_id_split();
    // 2: Buffer with Str / Bool alternatives.
    let buffer =
        gate(20, "B_1x1_Gate_BufferTicks").with_component(assets::components::BufferTicks {
            ticks_to_wait: 4,
            input: WireValue::Str("hello".into()),
            output: WireValue::Bool(true),
            buffered: WireValue::Vector {
                x: 1.0,
                y: -2.0,
                z: 0.5,
            },
            ..Default::default()
        });
    // 3: Array variable holding i64 elements.
    let array = gate(40, "B_1x1_Gate_Variable_Array").with_component(
        assets::LiteralComponent::new("BrickComponentType_ArrayVar").with_data([(
            "Value",
            Box::new(BrdbDynamicArray::new(
                "i64",
                vec![BrdbValue::I64(7), BrdbValue::I64(300)],
            )) as Box<dyn AsBrdbValue>,
        )]),
    );
    // 4: Map variable from Str keys to f64 values.
    let map = gate(60, "B_1x1_Gate_Variable_Map").with_component(
        assets::LiteralComponent::new("BrickComponentType_MapVar").with_data([(
            "Value",
            Box::new(BrdbDynamicMap::new(
                "Str",
                "f64",
                [(BrdbValue::String("k".into()), BrdbValue::F64(2.5))]
                    .into_iter()
                    .collect(),
            )) as Box<dyn AsBrdbValue>,
        )]),
    );
    // 5: Unset array variable: the default empty container.
    let empty_array = gate(80, "B_1x1_Gate_Variable_Array")
        .with_component(assets::LiteralComponent::new("BrickComponentType_ArrayVar"));
    // 6: Integer to enum: a dynamic enum field.
    let to_enum = gate(100, "B_1x1_Gate_Expr_IntegerToEnum").with_component(
        assets::LiteralComponent::new("BrickComponentType_Expr_IntegerToEnum").with_data([
            ("Input", Box::new(2i64) as Box<dyn AsBrdbValue>),
            (
                "TargetType",
                Box::new(BrdbDynamicEnum::new("EBrickAxis", 0)),
            ),
        ]),
    );
    // 7: A rerouter fed by the blend gate.
    let (reroute, reroute_id) = Brick {
        position: (120, 0, 1).into(),
        asset: assets::bricks::B_REROUTE,
        ..Default::default()
    }
    .with_component(assets::components::Rerouter)
    .with_id_split();

    world.add_bricks([blend, buffer, array, map, empty_array, to_enum, reroute]);
    world.add_wire_connection(
        assets::components::LogicGate::Blend.output_of(blend_id),
        assets::components::Rerouter::input_of(reroute_id),
    );
    // Embed only the structs these components use (what brs-js writes).
    world.register_used_components();
    world
}

examples/write_prefab_spawner.rs (line 65)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Build the prefab that gets spawned: a single red brick.
    let mut prefab = World::new();
    prefab.meta.bundle.name = "Spawned Brick".to_string();
    prefab.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    prefab.make_prefab();
    let prefab_bytes = prefab.to_brz_vec()?;

    // 2. Build the outer world holding the button + spawner.
    let mut world = World::new();
    // Registers the built-in component/port tables so the Button and
    // PrefabSpawner component types and their wire ports resolve.
    world.register_all_components();
    world.meta.bundle.description = "Button-triggered prefab spawner".to_string();

    // Embed the prefab; the returned path is what the spawner references.
    let prefab_path = world.add_prefab(prefab_bytes);

    // A pressable button (Component_Button on a 1x1 flat round brick). The
    // crate exposes brick assets as constants; components it doesn't model as
    // typed gates (like the button and spawner) are built from string names
    // via LiteralComponent.
    let (button, button_id) = Brick {
        position: (0, 0, 2).into(),
        color: (0, 255, 0).into(),
        asset: assets::bricks::B_1X1F_ROUND,
        ..Default::default()
    }
    .with_component(assets::LiteralComponent::new("Component_Button").with_data([(
        "PromptCustomLabel",
        Box::new("Spawn Brick".to_string()) as Box<dyn AsBrdbValue>,
    )]))
    .with_id_split();

    // The prefab-spawner gate, pointed at the embedded prefab.
    let (spawner, spawner_id) = Brick {
        position: (15, 0, 1).into(),
        color: (0, 0, 255).into(),
        asset: assets::bricks::B_1X1_GATE_EXEC_PREFAB_SPAWNER,
        ..Default::default()
    }
    .with_component(
        assets::LiteralComponent::new("BrickComponentType_WireGraph_Exec_PrefabSpawner").with_data(
            [(
                "Prefab",
                Box::new(prefab_path.clone()) as Box<dyn AsBrdbValue>,
            )],
        ),
    )
    .with_id_split();

    world.add_bricks([button, spawner]);

    // Wire the button's held signal into the spawner's Exec input, so a
    // press fires the spawn.
    world.add_wire_connection(
        WirePort::new(button_id, "Component_Button", "bHeld"),
        WirePort::new(
            spawner_id,
            "BrickComponentType_WireGraph_Exec_PrefabSpawner",
            "Exec",
        ),
    );

    // 3. Write it out.
    let path = PathBuf::from("./example_prefab_spawner.brz");
    world.write_brz(&path)?;
    println!("wrote {}", path.display());

    // Read it back to confirm the embedded prefab and wire survived.
    let reader = Brz::open(&path)?.into_reader();
    println!("embedded prefab: {}", prefab_path);
    println!("prefab paths in archive: {:?}", reader.prefab_paths()?);
    println!("{}", reader.get_fs()?.render());

    Ok(())
}

pub fn add_entity(&mut self, entity: Entity)

pub fn add_brick_grid( &mut self, entity: Entity, bricks: impl IntoIterator<Item = Brick>, )

Examples found in repository

examples/write_entity.rs (lines 12-23)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = PathBuf::from("./example_entity.brdb");

    // Ensures the memory db can be created without errors
    let db = Brdb::new(&path)?.into_reader();
    let mut world = World::new();
    world.meta.bundle.description = "Example World".to_string();
    world.add_brick_grid(
        Entity {
            frozen: true,
            location: (0.0, 0.0, 40.0).into(),
            ..Default::default()
        },
        [Brick {
            position: (0, 0, 3).into(),
            color: (0, 255, 0).into(),
            ..Default::default()
        }],
    );

    db.save("example world", &world)?;

    println!("{}", db.get_fs()?.render());

    Ok(())
}

examples/write_fixtures.rs (lines 384-395)

fn entities_world() -> World {
    // Mirror of examples/write_entity.rs's floating sub-grid — the first
    // grid added after the always-present main grid 1 gets persistent index
    // 2, so it lands at Grids/2 — plus a couple of main-grid (Grids/1)
    // bricks. Both grids are single-chunk; note the *outer* Grids/1 vs
    // Grids/2 folder order comes from a HashMap<usize, UnsavedGrid> in the
    // writer and is NOT guaranteed stable run-to-run (see stability notes).
    //
    // register_all_components() is required here (matching
    // test_write_entity_save, NOT the plain write_entity.rs example): without
    // it, Entity_DynamicBrickGrid's class name is never registered and the
    // write fails with `UnknownType("Entity_DynamicBrickGrid")` — confirmed
    // by running the crate's own unmodified write_entity example.
    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Entity fixture".to_string();

    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (200, 50, 50).into(),
        ..Default::default()
    });
    world.bricks.push(Brick {
        position: (20, 0, 6).into(),
        color: (50, 200, 50).into(),
        ..Default::default()
    });

    world.add_brick_grid(
        Entity {
            frozen: true,
            location: (0.0, 0.0, 40.0).into(),
            ..Default::default()
        },
        [Brick {
            position: (0, 0, 3).into(),
            color: (0, 255, 0).into(),
            ..Default::default()
        }],
    );

    world
}

fn spawner_world() -> World {
    // Prefab-embedding fixture: an outer prefab whose spawner gate references
    // an inner single-brick prefab embedded at Prefabs/Uploads/<BLAKE3>.brz.
    // Single grid, single chunk, one insertion-ordered prefab map entry —
    // fully deterministic. The inner archive is written raw (no zstd) so the
    // embedded bytes are cross-language reproducible.
    let mut inner = World::new();
    inner.meta.bundle.description = "Inner prefab".to_string();
    inner.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    inner.make_prefab();
    let inner_bytes = {
        let pending = inner.to_unsaved().unwrap().to_pending().unwrap();
        let mut buf = Vec::new();
        pending
            .to_brz_data(None)
            .unwrap()
            .write(&mut buf, None)
            .unwrap();
        buf
    };

    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Spawner fixture".to_string();
    let prefab_path = world.add_prefab(inner_bytes);
    world.bricks.push(
        Brick {
            asset: brdb::BrickType::str("B_1x1_Gate_Exec_PrefabSpawner"),
            position: (0, 0, 1).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("BrickComponentType_Exec_PrefabSpawner")
                .with_data([("Prefab", Box::new(prefab_path) as Box<dyn AsBrdbValue>)]),
        ),
    );
    world.make_prefab();
    world
}

/// `features_world` written in the Latest format.
fn features_latest_world() -> World {
    let mut world = features_world();
    world.schema_format = BrdbSchemaFormat::Latest;
    world
}

/// `entities_world` with the current build's schemas in the Latest format.
fn entities_latest_world() -> World {
    let mut world = World::new();
    world.schema_format = BrdbSchemaFormat::Latest;
    world.register_all_components();
    world.meta.bundle.description = "Entity fixture".to_string();
    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (200, 50, 50).into(),
        ..Default::default()
    });
    world.add_brick_grid(
        Entity {
            frozen: true,
            location: (0.0, 0.0, 40.0).into(),
            ..Default::default()
        },
        [Brick {
            position: (0, 0, 3).into(),
            color: (0, 255, 0).into(),
            ..Default::default()
        }],
    );
    world
}

pub fn add_wire(&mut self, conn: WireConnection)

Add a single wire connection to the world

pub fn add_wires(&mut self, wires: impl IntoIterator<Item = WireConnection>)

Add multiple wire connections to the world

pub fn add_wire_connection(&mut self, source: WirePort, target: WirePort)

Add a wire connection from one port to another

Examples found in repository

examples/write_wire.rs (lines 34-37)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let path = PathBuf::from("./example_wire.brdb");

    // Ensures the memory db can be created without errors
    let db = Brdb::new(&path)?.into_reader();
    let mut world = World::new();
    // Register the built-in component type/struct mappings so the gate and
    // rerouter component types resolve when writing.
    world.register_all_components();
    world.meta.bundle.description = "Example World".to_string();

    let (a, a_id) = Brick {
        position: (0, 0, 1).into(),
        color: (255, 0, 0).into(),
        asset: assets::bricks::B_REROUTE,
        ..Default::default()
    }
    .with_component(assets::components::Rerouter)
    .with_id_split();
    let (b, b_id) = Brick {
        position: (15, 0, 1).into(),
        color: (255, 0, 0).into(),
        asset: assets::components::LogicGate::BoolNot.brick(),
        ..Default::default()
    }
    .with_component(assets::components::LogicGate::BoolNot.component())
    .with_id_split();

    world.add_bricks([a, b]);
    world.add_wire_connection(
        assets::components::LogicGate::BoolNot.output_of(b_id),
        assets::components::Rerouter::input_of(a_id),
    );

    db.save("example world", &world)?;

    println!("{}", db.get_fs()?.render());

    Ok(())
}

examples/write_fixtures.rs (lines 210-213)

fn wires_world() -> World {
    // Mirror of examples/write_wire.rs (single grid, single chunk — fully
    // deterministic), extended to 3 bricks/2 wires: a boolean NOT gate feeds
    // one input of an AND gate, whose output feeds a rerouter.
    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Wire fixture".to_string();

    let (a, a_id) = Brick {
        position: (30, 0, 1).into(),
        color: (255, 0, 0).into(),
        asset: assets::bricks::B_REROUTE,
        ..Default::default()
    }
    .with_component(assets::components::Rerouter)
    .with_id_split();
    let (b, b_id) = Brick {
        position: (15, 0, 1).into(),
        color: (0, 255, 0).into(),
        asset: assets::components::LogicGate::BoolAnd.brick(),
        ..Default::default()
    }
    .with_component(assets::components::LogicGate::BoolAnd.component())
    .with_id_split();
    let (c, c_id) = Brick {
        position: (0, 0, 1).into(),
        color: (0, 0, 255).into(),
        asset: assets::components::LogicGate::BoolNot.brick(),
        ..Default::default()
    }
    .with_component(assets::components::LogicGate::BoolNot.component())
    .with_id_split();

    world.add_bricks([a, b, c]);
    // Wire 1: NOT.output -> AND.inputA
    world.add_wire_connection(
        assets::components::LogicGate::BoolNot.output_of(c_id),
        assets::components::LogicGate::BoolAnd.input_a_of(b_id),
    );
    // Wire 2: AND.output -> Rerouter.input
    world.add_wire_connection(
        assets::components::LogicGate::BoolAnd.output_of(b_id),
        assets::components::Rerouter::input_of(a_id),
    );

    world
}

fn components_world() -> World {
    // Single grid, single chunk (all positions < 2048) — fully deterministic.
    // register_all_components() embeds the full component catalog so every
    // type below (light/interact/buffer/expr) resolves; each
    // component below carries non-default property values, and #4/#5 exercise
    // a WireValue-typed property (BufferTicks' Input/Output, and the Blend
    // gate's inputs).
    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Component fixture".to_string();

    // 1: Point light — non-default brightness/radius/color, decoupled from
    // brick color (bUseBrickColor: false).
    world.bricks.push(
        Brick {
            position: (0, 0, 6).into(),
            color: (255, 255, 255).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("Component_PointLight").with_data([
                ("bMatchBrickShape", Box::new(false) as Box<dyn AsBrdbValue>),
                ("bEnabled", Box::new(true)),
                ("Brightness", Box::new(500.0f32)),
                ("Radius", Box::new(800.0f32)),
                (
                    "Color",
                    Box::new(SavedBrickColor {
                        r: 10,
                        g: 20,
                        b: 30,
                        a: 255,
                    }),
                ),
                ("bUseBrickColor", Box::new(false)),
                ("bCastShadows", Box::new(true)),
            ]),
        ),
    );

    // 2: Spot light — narrow cone, non-default brightness/color.
    world.bricks.push(
        Brick {
            position: (20, 0, 6).into(),
            color: (255, 255, 0).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("Component_SpotLight").with_data([
                ("InnerConeAngle", Box::new(15.0f32) as Box<dyn AsBrdbValue>),
                ("OuterConeAngle", Box::new(45.0f32)),
                ("bEnabled", Box::new(true)),
                ("Brightness", Box::new(300.0f32)),
                ("Radius", Box::new(600.0f32)),
                (
                    "Color",
                    Box::new(SavedBrickColor {
                        r: 255,
                        g: 0,
                        b: 0,
                        a: 255,
                    }),
                ),
                ("bUseBrickColor", Box::new(false)),
                ("bCastShadows", Box::new(true)),
            ]),
        ),
    );

    // 3: Interact — custom prompt text, hidden interaction.
    world.bricks.push(
        Brick {
            position: (40, 0, 6).into(),
            color: (0, 255, 255).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("Component_Interact").with_data([
                (
                    "Message",
                    Box::new("You interacted!".to_string()) as Box<dyn AsBrdbValue>,
                ),
                ("ConsoleTag", Box::new("fixture_interact".to_string())),
                ("bAllowNearbyInteraction", Box::new(false)),
                ("bHiddenInteraction", Box::new(true)),
                ("PromptCustomLabel", Box::new("Open Door".to_string())),
            ]),
        ),
    );

    // 4: Buffer (ticks) — Input/Output are WireValue; non-default counters
    // plus a Number/Bool value pair.
    world.bricks.push(
        Brick {
            position: (60, 0, 1).into(),
            color: (128, 0, 128).into(),
            asset: assets::components::BufferTicks::default().brick(),
            ..Default::default()
        }
        .with_component(assets::components::BufferTicks {
            current_ticks: 3,
            ticks_to_wait: 10,
            input: WireValue::Number(2.5),
            output: WireValue::Bool(true),
            ..Default::default()
        }),
    );

    // 5: Blend gate — Expr_MathBlend's InputA/InputB are each a WireValue
    // (here an f64 and an i64, showing the value is polymorphic per-port);
    // Blend itself is a plain f64.
    world.bricks.push(
        Brick {
            position: (80, 0, 1).into(),
            color: (0, 128, 0).into(),
            asset: assets::components::LogicGate::Blend.brick(),
            ..Default::default()
        }
        .with_component(
            assets::components::LogicGate::Blend.component_with_overrides(HashMap::from([
                (
                    "InputA".into(),
                    Box::new(WireValue::Number(10.0)) as Box<dyn AsBrdbValue>,
                ),
                ("InputB".into(), Box::new(WireValue::Int(7))),
                ("Blend".into(), Box::new(0.75f64)),
            ])),
        ),
    );

    world
}

fn entities_world() -> World {
    // Mirror of examples/write_entity.rs's floating sub-grid — the first
    // grid added after the always-present main grid 1 gets persistent index
    // 2, so it lands at Grids/2 — plus a couple of main-grid (Grids/1)
    // bricks. Both grids are single-chunk; note the *outer* Grids/1 vs
    // Grids/2 folder order comes from a HashMap<usize, UnsavedGrid> in the
    // writer and is NOT guaranteed stable run-to-run (see stability notes).
    //
    // register_all_components() is required here (matching
    // test_write_entity_save, NOT the plain write_entity.rs example): without
    // it, Entity_DynamicBrickGrid's class name is never registered and the
    // write fails with `UnknownType("Entity_DynamicBrickGrid")` — confirmed
    // by running the crate's own unmodified write_entity example.
    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Entity fixture".to_string();

    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (200, 50, 50).into(),
        ..Default::default()
    });
    world.bricks.push(Brick {
        position: (20, 0, 6).into(),
        color: (50, 200, 50).into(),
        ..Default::default()
    });

    world.add_brick_grid(
        Entity {
            frozen: true,
            location: (0.0, 0.0, 40.0).into(),
            ..Default::default()
        },
        [Brick {
            position: (0, 0, 3).into(),
            color: (0, 255, 0).into(),
            ..Default::default()
        }],
    );

    world
}

fn spawner_world() -> World {
    // Prefab-embedding fixture: an outer prefab whose spawner gate references
    // an inner single-brick prefab embedded at Prefabs/Uploads/<BLAKE3>.brz.
    // Single grid, single chunk, one insertion-ordered prefab map entry —
    // fully deterministic. The inner archive is written raw (no zstd) so the
    // embedded bytes are cross-language reproducible.
    let mut inner = World::new();
    inner.meta.bundle.description = "Inner prefab".to_string();
    inner.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    inner.make_prefab();
    let inner_bytes = {
        let pending = inner.to_unsaved().unwrap().to_pending().unwrap();
        let mut buf = Vec::new();
        pending
            .to_brz_data(None)
            .unwrap()
            .write(&mut buf, None)
            .unwrap();
        buf
    };

    let mut world = World::new();
    world.register_all_components();
    world.meta.bundle.description = "Spawner fixture".to_string();
    let prefab_path = world.add_prefab(inner_bytes);
    world.bricks.push(
        Brick {
            asset: brdb::BrickType::str("B_1x1_Gate_Exec_PrefabSpawner"),
            position: (0, 0, 1).into(),
            ..Default::default()
        }
        .with_component(
            assets::LiteralComponent::new("BrickComponentType_Exec_PrefabSpawner")
                .with_data([("Prefab", Box::new(prefab_path) as Box<dyn AsBrdbValue>)]),
        ),
    );
    world.make_prefab();
    world
}

/// `features_world` written in the Latest format.
fn features_latest_world() -> World {
    let mut world = features_world();
    world.schema_format = BrdbSchemaFormat::Latest;
    world
}

/// `entities_world` with the current build's schemas in the Latest format.
fn entities_latest_world() -> World {
    let mut world = World::new();
    world.schema_format = BrdbSchemaFormat::Latest;
    world.register_all_components();
    world.meta.bundle.description = "Entity fixture".to_string();
    world.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (200, 50, 50).into(),
        ..Default::default()
    });
    world.add_brick_grid(
        Entity {
            frozen: true,
            location: (0.0, 0.0, 40.0).into(),
            ..Default::default()
        },
        [Brick {
            position: (0, 0, 3).into(),
            color: (0, 255, 0).into(),
            ..Default::default()
        }],
    );
    world
}

/// Current-build components in the Latest format: WireValue fields, dynamic
/// arrays/maps (typed and empty) and a dynamic enum, plus a wire.
fn components_latest_world() -> World {
    let mut world = World::new();
    world.meta.bundle.description = "Latest component fixture".to_string();
    let gate = |x: i32, asset: &'static str| Brick {
        position: (x, 0, 1).into(),
        asset: BrickType::str(asset),
        ..Default::default()
    };

    // 1: Blend gate with WireValue inputs (f64 and i64 alternatives).
    let (blend, blend_id) = gate(0, "B_1x1_Gate_Expr_MathBlend")
        .with_component(
            assets::components::LogicGate::Blend.component_with_overrides(HashMap::from([
                (
                    "InputA".into(),
                    Box::new(WireValue::Number(1.5)) as Box<dyn AsBrdbValue>,
                ),
                ("InputB".into(), Box::new(WireValue::Int(-3))),
                ("Blend".into(), Box::new(0.25f64)),
            ])),
        )
        .with_id_split();
    // 2: Buffer with Str / Bool alternatives.
    let buffer =
        gate(20, "B_1x1_Gate_BufferTicks").with_component(assets::components::BufferTicks {
            ticks_to_wait: 4,
            input: WireValue::Str("hello".into()),
            output: WireValue::Bool(true),
            buffered: WireValue::Vector {
                x: 1.0,
                y: -2.0,
                z: 0.5,
            },
            ..Default::default()
        });
    // 3: Array variable holding i64 elements.
    let array = gate(40, "B_1x1_Gate_Variable_Array").with_component(
        assets::LiteralComponent::new("BrickComponentType_ArrayVar").with_data([(
            "Value",
            Box::new(BrdbDynamicArray::new(
                "i64",
                vec![BrdbValue::I64(7), BrdbValue::I64(300)],
            )) as Box<dyn AsBrdbValue>,
        )]),
    );
    // 4: Map variable from Str keys to f64 values.
    let map = gate(60, "B_1x1_Gate_Variable_Map").with_component(
        assets::LiteralComponent::new("BrickComponentType_MapVar").with_data([(
            "Value",
            Box::new(BrdbDynamicMap::new(
                "Str",
                "f64",
                [(BrdbValue::String("k".into()), BrdbValue::F64(2.5))]
                    .into_iter()
                    .collect(),
            )) as Box<dyn AsBrdbValue>,
        )]),
    );
    // 5: Unset array variable: the default empty container.
    let empty_array = gate(80, "B_1x1_Gate_Variable_Array")
        .with_component(assets::LiteralComponent::new("BrickComponentType_ArrayVar"));
    // 6: Integer to enum: a dynamic enum field.
    let to_enum = gate(100, "B_1x1_Gate_Expr_IntegerToEnum").with_component(
        assets::LiteralComponent::new("BrickComponentType_Expr_IntegerToEnum").with_data([
            ("Input", Box::new(2i64) as Box<dyn AsBrdbValue>),
            (
                "TargetType",
                Box::new(BrdbDynamicEnum::new("EBrickAxis", 0)),
            ),
        ]),
    );
    // 7: A rerouter fed by the blend gate.
    let (reroute, reroute_id) = Brick {
        position: (120, 0, 1).into(),
        asset: assets::bricks::B_REROUTE,
        ..Default::default()
    }
    .with_component(assets::components::Rerouter)
    .with_id_split();

    world.add_bricks([blend, buffer, array, map, empty_array, to_enum, reroute]);
    world.add_wire_connection(
        assets::components::LogicGate::Blend.output_of(blend_id),
        assets::components::Rerouter::input_of(reroute_id),
    );
    // Embed only the structs these components use (what brs-js writes).
    world.register_used_components();
    world
}

examples/write_prefab_spawner.rs (lines 69-76)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Build the prefab that gets spawned: a single red brick.
    let mut prefab = World::new();
    prefab.meta.bundle.name = "Spawned Brick".to_string();
    prefab.bricks.push(Brick {
        position: (0, 0, 6).into(),
        color: (255, 0, 0).into(),
        ..Default::default()
    });
    prefab.make_prefab();
    let prefab_bytes = prefab.to_brz_vec()?;

    // 2. Build the outer world holding the button + spawner.
    let mut world = World::new();
    // Registers the built-in component/port tables so the Button and
    // PrefabSpawner component types and their wire ports resolve.
    world.register_all_components();
    world.meta.bundle.description = "Button-triggered prefab spawner".to_string();

    // Embed the prefab; the returned path is what the spawner references.
    let prefab_path = world.add_prefab(prefab_bytes);

    // A pressable button (Component_Button on a 1x1 flat round brick). The
    // crate exposes brick assets as constants; components it doesn't model as
    // typed gates (like the button and spawner) are built from string names
    // via LiteralComponent.
    let (button, button_id) = Brick {
        position: (0, 0, 2).into(),
        color: (0, 255, 0).into(),
        asset: assets::bricks::B_1X1F_ROUND,
        ..Default::default()
    }
    .with_component(assets::LiteralComponent::new("Component_Button").with_data([(
        "PromptCustomLabel",
        Box::new("Spawn Brick".to_string()) as Box<dyn AsBrdbValue>,
    )]))
    .with_id_split();

    // The prefab-spawner gate, pointed at the embedded prefab.
    let (spawner, spawner_id) = Brick {
        position: (15, 0, 1).into(),
        color: (0, 0, 255).into(),
        asset: assets::bricks::B_1X1_GATE_EXEC_PREFAB_SPAWNER,
        ..Default::default()
    }
    .with_component(
        assets::LiteralComponent::new("BrickComponentType_WireGraph_Exec_PrefabSpawner").with_data(
            [(
                "Prefab",
                Box::new(prefab_path.clone()) as Box<dyn AsBrdbValue>,
            )],
        ),
    )
    .with_id_split();

    world.add_bricks([button, spawner]);

    // Wire the button's held signal into the spawner's Exec input, so a
    // press fires the spawn.
    world.add_wire_connection(
        WirePort::new(button_id, "Component_Button", "bHeld"),
        WirePort::new(
            spawner_id,
            "BrickComponentType_WireGraph_Exec_PrefabSpawner",
            "Exec",
        ),
    );

    // 3. Write it out.
    let path = PathBuf::from("./example_prefab_spawner.brz");
    world.write_brz(&path)?;
    println!("wrote {}", path.display());

    // Read it back to confirm the embedded prefab and wire survived.
    let reader = Brz::open(&path)?.into_reader();
    println!("embedded prefab: {}", prefab_path);
    println!("prefab paths in archive: {:?}", reader.prefab_paths()?);
    println!("{}", reader.get_fs()?.render());

    Ok(())
}

pub fn register_microchip_link(&mut self, brick_id: usize, entity_id: usize)

Register an outer-microchip-brick ↔ inner-grid-entity pairing. The write path consumes this into ComponentChunkSoA.microchip_brick_indices / microchip_brick_grid_references. Most callers get this for free by going through add_microchip; use this directly only when constructing the pair manually.

pub fn add_microchip( &mut self, position: Position, entity_location: Vector3f, plane_extent: IntVector, collapsed: bool, ) -> (usize, usize, (Entity, Vec<Brick>))

Build a microchip: spawns the outer microchip brick on the main grid, calls register_microchip_link with the pairing, and returns the outer brick’s id, the grid entity’s id, and the (Entity, Vec<Brick>) pair the caller populates before pushing to world.grids.

Typical usage:

let (chip_brick_id, chip_entity_id, mut inner) = world.add_microchip(
    Position { x: 0, y: 0, z: 6 },
    Vector3f { x: 0.0, y: 0.0, z: 40.0 },
    IntVector { x: 14, y: 14, z: 2 },
    true, // collapsed
);
inner.1.push(some_gate_brick);
world.grids.push(inner);

Trait Implementations

impl Default for World

fn default() -> Self

Returns the “default value” for a type.