NEOLearn

Scenes with bsn!

Describe an entity, its components and children once with the bsn! macro, compose scenes from other scenes, override single fields, name and reference entities, and spawn them.

Updated October 20, 2026

On this page

A scene describes an object made of one entity, its components, its children and the assets they use, so you can spawn it wherever you need it. You write scenes with the bsn! macro, usually in a function that returns impl Scene. Scenes compose: one scene can include another and change just the fields it needs.

A first scene#

src/main.rs
use neo::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, setup)
        .run();
}

fn setup(mut commands: Commands) {
    commands.spawn(Camera2d);
    commands.spawn_scene(bsn! {
        #Menu
        Node {
            width: percent(100),
            height: percent(100),
            justify_content: JustifyContent::Center,
            align_items: AlignItems::Center,
        }
        BackgroundColor(Color::BLACK)
        Children [
            Text("Paused")
            --
            Text("Press Esc to continue")
        ]
    });
}
SyntaxMeaning
Node { width: percent(100) }Adds the component, setting only the fields you list. The rest keep their defaults.
BackgroundColor(Color::BLACK)A tuple component.
#MenuNames the entity (adds Name("Menu")) and lets other entities in the same bsn! refer to it.
Children [ a -- b ]Spawns child entities. -- separates entities; components without -- between them go on the same entity.
@button("Ok")Includes another scene, here returned by the function button.
on(handler)Adds an observer to the entity.
{expression}Any Rust expression as a value.

Any relationship target works like Children, not only the hierarchy.

Scene functions and composition#

Write reusable pieces as functions:

Rust
use neo::{prelude::*, ui_widgets::Button};

fn button(label: &str) -> impl Scene {
    bsn! {
        Button
        Node {
            width: px(150),
            height: px(65),
            justify_content: JustifyContent::Center,
            align_items: AlignItems::Center,
        }
        BackgroundColor(Color::srgb(0.15, 0.15, 0.15))
        Children [
            Text(label)
        ]
    }
}

fn dialog() -> impl Scene {
    bsn! {
        Node { column_gap: px(5) }
        Children [
            @button("Ok")
            on(|_press: On<PointerPress>| info!("Ok pressed"))
            --
            @button("Cancel")
            BackgroundColor(Color::srgb(0.4, 0.15, 0.15))
        ]
    }
}

@button("Cancel") followed by BackgroundColor(...) patches the included scene: the cancel button keeps everything button set and only its colour changes. Patches apply in order, and each changes only the fields it names.

Rust
#[derive(Component, Default, Clone)]
struct Health {
    current: u32,
    max: u32,
}

fn enemy() -> impl Scene {
    bsn! { Health { current: 100, max: 100 } }
}

// a tougher enemy: current stays 100, max becomes 200
fn boss() -> impl Scene {
    bsn! {
        @enemy()
        Health { max: 200 }
    }
}

bsn_list! returns several root entities as one SceneList:

Rust
fn hud() -> impl SceneList {
    bsn_list! {
        Camera2d
        --
        @dialog()
    }
}

// spawn a scene function from a Startup system
app.add_systems(Startup, hud.spawn());

Which types can appear#

A component used in bsn! must implement Default and Clone, or derive FromTemplate.

DeriveUse it when
Default + CloneThe usual choice.
FromTemplateA field needs the world to be filled in when spawning: a Handle<T> given as an asset path, or an Entity given as #Name. The derive also makes a <Type>Template with a Default. Don't derive Default as well.

Enums must be written in full, every field of the variant.

Asset paths#

When a field is a Handle<T>, write the asset path as a string. It's loaded when the scene spawns, or the existing handle is reused:

Rust
#[derive(Component, FromTemplate)]
struct Icon {
    image: Handle<Image>,
    tint: Color,
}

commands.spawn_scene(bsn! {
    Sprite { image: "sprites/player.png" }
    Icon { image: "ui/heart.png", tint: Color::WHITE }
});

Names and references#

#Name makes an entity referable within the same bsn! call, from parents, children or siblings in a bsn_list!. A component with an Entity field (deriving FromTemplate) receives the spawned entity:

Rust
#[derive(Component, FromTemplate)]
struct Target(Entity);

bsn! {
    #Turret
    Children [
        Target(#Turret)
    ]
}

Each bsn! call has its own names, so two scenes can both use #Root without clashing. To give an entity a name computed at runtime, add Name({format!("Enemy {i}")}) after the #Name.

Spawning#

MethodWhen it spawns
commands.spawn_scene(scene), world.spawn_scene(scene)Now. With World, returns an error if an asset the scene needs hasn't loaded.
commands.queue_spawn_scene(scene), world.queue_spawn_scene(scene)Once every asset the scene depends on has loaded, during the SpawnScene schedule (after Update).
spawn_scene_list(list), queue_spawn_scene_list(list)The same for a SceneList.
scene_fn.spawn()A system that spawns the scene; add it to Startup.

apply_scene(scene) and queue_apply_scene(scene) on EntityCommands and EntityWorldMut apply a scene to an entity that already exists.

Example: cargo run --example bsn, from the engine core's workspace (the folder of the engine source that holds the neo crate's Cargo.toml). Many UI examples, such as size_constraints and box_shadow, build their UI with bsn!.

Next steps#