NEOLearn

Dynamic worlds and scene files

Spawn world assets such as glTF scenes and .scn.ron files, save part of a running world as a DynamicWorld, filter what's saved and load it back.

Updated October 20, 2026

On this page

A world asset is a set of entities, with their components, and resources, kept as data so it can be spawned into the game once or many times. It's how a glTF scene arrives, how you load a level stored as a file, and how you save part of a running world.

TypeWhat it is
WorldAssetAn asset holding a ready-made ECS World. Fast to spawn. glTF scenes load as WorldAssets.
DynamicWorldAn asset holding entities and resources as reflected data. Can be serialized; .scn.ron files load as DynamicWorlds.
WorldAssetRoot(Handle<WorldAsset>)A component: spawns the world asset as children of this entity.
DynamicWorldRoot(Handle<DynamicWorld>)A component: the same for a dynamic world.
WorldInstanceReadyAn event triggered on the root entity once its instance has spawned.
WorldInstanceSpawnerA resource for spawning and despawning instances directly.

Spawn a world file#

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

fn load_level(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn((
        DynamicWorldRoot(asset_server.load("levels/arena.scn.ron")),
        Transform::from_xyz(0.0, 0.0, 0.0),
    ));
}

The root entity gets a Transform and Visibility if it has none. When the asset has loaded, its entities are spawned as children of the root during the SpawnScene schedule, which runs after Update. Despawn the root to despawn the instance. If the asset changes (a hot reload), the instance is spawned again.

To act on the spawned entities, observe WorldInstanceReady:

Rust
fn on_level_ready(ready: On<WorldInstanceReady>, children: Query<&Children>) {
    let count = children.iter_descendants(ready.entity).count();
    info!("level spawned with {count} entities");
}

// app.add_observer(on_level_ready);

Resources in the file are inserted into the world. A resource that already exists has the saved values applied over it.

The file format#

A world file is RON, with .scn.ron (or .scn) as its extension. Components and resources are keyed by their full type path:

assets/levels/arena.scn.ron
(
  resources: {
    "my_game::RoundRules": (
      time_limit: 120.0,
    ),
  },
  entities: {
    "0v0": (
      components: {
        "neo_ecs::name::Name": "spawn point",
        "neo_transform::components::transform::Transform": (
          translation: (0.0, 1.0, 0.0),
          rotation: (0.0, 0.0, 0.0, 1.0),
          scale: (1.0, 1.0, 1.0),
        ),
        "my_game::SpawnPoint": (team: 1),
      },
    ),
    "1v0": (
      components: {
        "neo_world_serialization::components::WorldAssetRoot": (Path("models/crate.glb#Scene0")),
      },
    ),
  },
)

Every type in the file must be registered and reflect Component or Resource. A file that names an unknown type fails to load, with an error naming it. Asset handles are written as paths, so the second entity above spawns a glTF model.

Make your types saveable#

Rust
#[derive(Component, Reflect, Default)]
#[reflect(Component, Default)]
struct SpawnPoint {
    team: u8,
    #[reflect(skip_serializing)]
    last_used: f32, // runtime only
}

#[derive(Resource, Reflect, Default)]
#[reflect(Resource, Default)]
struct RoundRules {
    time_limit: f32,
}
  • #[reflect(Component)] or #[reflect(Resource)] is required.
  • Mark fields that are only meaningful at runtime with #[reflect(skip_serializing)]. They get their default value when loaded.
  • Components that store Entity ids should mark those fields with #[entities], so they point at the new entities when the world is spawned.

Save part of a world#

Build a DynamicWorld from a world, then serialize it:

Rust
fn save_level(world: &mut World) {
    let registry = world.resource::<AppTypeRegistry>().clone();
    let registry = registry.read();

    let mut query = world.query_filtered::<Entity, With<SpawnPoint>>();
    let entities: Vec<Entity> = query.iter(world).collect();

    let dynamic_world = DynamicWorldBuilder::from_world(world, &registry)
        .deny_all_resources()
        .allow_resource::<RoundRules>()
        .extract_entities(entities.into_iter())
        .extract_resources()
        .build();

    let ron = dynamic_world.serialize(&registry).unwrap();
    info!("{ron}");
}
DynamicWorldBuilder methodWhat it does
from_world(&world, &registry)Starts a builder.
extract_entity(e), extract_entities(iter)Adds entities with every reflected component they have.
extract_resources()Adds the world's reflected resources.
allow_component::<T>(), deny_component::<T>(), allow_all_components(), deny_all_components()Chooses components. Apply filters before extracting.
allow_resource::<T>(), deny_resource::<T>(), allow_all_resources(), deny_all_resources()Chooses resources.
with_component_filter(WorldFilter), with_resource_filter(WorldFilter)Sets a whole filter at once.
remove_empty_entities()Drops entities left with no components.
build()Returns the DynamicWorld.

DynamicWorld::from_world(&world) takes everything. To write the result to a file on the desktop, do it off the main thread with IoTaskPool::get().spawn(...), as the example does.

Spawn and despawn by hand#

WorldInstanceSpawner does what the root components do, without them:

MethodWhat it does
spawn(handle), spawn_dynamic(handle)Queues an instance with no parent. Returns an InstanceId.
spawn_as_child(handle, parent), spawn_dynamic_as_child(handle, parent)Queues an instance under parent.
instance_is_ready(id)Whether it has spawned.
iter_instance_entities(id)Its entities, once spawned.
despawn_instance(id)Despawns it.

dynamic_world.write_to_world(&mut world, &mut entity_map) writes a dynamic world into a world immediately, filling entity_map with each saved entity's new id.

Example: cargo run --example world_serialization, from the engine core's workspace (the folder of the engine source that holds the neo crate's Cargo.toml). It writes a file, so it doesn't run on the web.

Next steps#