Struct SceneWorld 

pub struct SceneWorld { /* private fields */ }

Native two-archetype ECS: render-only and render+velocity. No external ECS or locks. IDs index a location table; row compaction always repairs the moved entity’s location.

Implementations

impl SceneWorld

pub fn new(limits: SceneLimits) -> Result<Self, RenderError>

Reserve bounded columns after validating the CPU budget.

Examples found in repository

examples/scene_admission.rs (line 24)

fn sample(count: u32, binding: RenderBinding) -> Result<(u128, u128, u64)> {
    let limits = SceneLimits {
        max_entities: count,
        max_snapshot_instances: count,
        max_snapshots: 1,
        managed_cpu_bytes: 512 * 1024 * 1024,
    };
    let bytes = limits.reservation_bytes()?;
    let mut world = SceneWorld::new(limits)?;
    let mut entities = Vec::with_capacity(count as usize);
    let started = Instant::now();
    for _ in 0..count {
        entities.push(world.spawn(black_box(Transform::default()), black_box(binding), None)?);
    }
    let initial = started.elapsed().as_nanos();
    let started = Instant::now();
    for id in entities.drain(..) {
        world.despawn(black_box(id))?;
    }
    for _ in 0..count {
        entities.push(world.spawn(black_box(Transform::default()), black_box(binding), None)?);
    }
    let reuse = started.elapsed().as_nanos();
    black_box((&world, &entities));
    assert_eq!(world.len(), count as usize);
    Ok((initial, reuse, bytes))
}

examples/scene.rs (lines 25-29)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Opaque asset identities only; this example qualifies CPU scene ownership, not drawing.
    let mut assets = ResourceArena::new(RenderLimits::default())?;
    let binding = RenderBinding {
        mesh: assets.insert((), 1)?,
        material: assets.insert((), 1)?,
        tint: [1.0; 4],
        animation: 0,
        morph: 0,
    };
    let mut world = SceneWorld::new(SceneLimits {
        max_entities: 64,
        max_snapshot_instances: 64,
        ..Default::default()
    })?;
    let mut first = None;
    for i in 0..64 {
        let id = world.spawn(
            Transform::default().with_position([i as f32, 0.0, 0.0])?,
            binding,
            Some(Velocity::new([1.0, 0.0, 0.0])?),
        )?;
        first = first.or(Some(id));
    }
    let before = world.snapshot()?;
    world.step_velocity(0.016)?;
    let after = world.snapshot()?;
    assert_eq!(before.instances()[0].transform.position()[0], 0.0);
    assert_eq!(after.instances()[0].transform.position()[0], 0.016);
    let mut commands = SceneCommands::new(8)?;
    if let Some(first) = first {
        commands.push(SceneCommand::SetVelocity(first, None))?;
    }
    for outcome in commands.apply(&mut world)? {
        outcome?;
    }
    println!(
        "entities={} owned_snapshots=2 moving_rows={}",
        world.len(),
        world.moving_columns().entities.len()
    );
    Ok(())
}

pub fn len(&self) -> usize

Live entities, bounded by the identity slot capacity.

Examples found in repository

examples/scene_admission.rs (line 40)

fn sample(count: u32, binding: RenderBinding) -> Result<(u128, u128, u64)> {
    let limits = SceneLimits {
        max_entities: count,
        max_snapshot_instances: count,
        max_snapshots: 1,
        managed_cpu_bytes: 512 * 1024 * 1024,
    };
    let bytes = limits.reservation_bytes()?;
    let mut world = SceneWorld::new(limits)?;
    let mut entities = Vec::with_capacity(count as usize);
    let started = Instant::now();
    for _ in 0..count {
        entities.push(world.spawn(black_box(Transform::default()), black_box(binding), None)?);
    }
    let initial = started.elapsed().as_nanos();
    let started = Instant::now();
    for id in entities.drain(..) {
        world.despawn(black_box(id))?;
    }
    for _ in 0..count {
        entities.push(world.spawn(black_box(Transform::default()), black_box(binding), None)?);
    }
    let reuse = started.elapsed().as_nanos();
    black_box((&world, &entities));
    assert_eq!(world.len(), count as usize);
    Ok((initial, reuse, bytes))
}

examples/scene.rs (line 53)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Opaque asset identities only; this example qualifies CPU scene ownership, not drawing.
    let mut assets = ResourceArena::new(RenderLimits::default())?;
    let binding = RenderBinding {
        mesh: assets.insert((), 1)?,
        material: assets.insert((), 1)?,
        tint: [1.0; 4],
        animation: 0,
        morph: 0,
    };
    let mut world = SceneWorld::new(SceneLimits {
        max_entities: 64,
        max_snapshot_instances: 64,
        ..Default::default()
    })?;
    let mut first = None;
    for i in 0..64 {
        let id = world.spawn(
            Transform::default().with_position([i as f32, 0.0, 0.0])?,
            binding,
            Some(Velocity::new([1.0, 0.0, 0.0])?),
        )?;
        first = first.or(Some(id));
    }
    let before = world.snapshot()?;
    world.step_velocity(0.016)?;
    let after = world.snapshot()?;
    assert_eq!(before.instances()[0].transform.position()[0], 0.0);
    assert_eq!(after.instances()[0].transform.position()[0], 0.016);
    let mut commands = SceneCommands::new(8)?;
    if let Some(first) = first {
        commands.push(SceneCommand::SetVelocity(first, None))?;
    }
    for outcome in commands.apply(&mut world)? {
        outcome?;
    }
    println!(
        "entities={} owned_snapshots=2 moving_rows={}",
        world.len(),
        world.moving_columns().entities.len()
    );
    Ok(())
}

pub fn is_empty(&self) -> bool

Whether no entities remain.

pub fn spawn( &mut self, transform: Transform, binding: RenderBinding, velocity: Option<Velocity>, ) -> Result<EntityId, RenderError>

Spawn a validated instance in the matching archetype. Failure makes no structural change. Slot admission is constant-time through a bounded free list; reuse order is unspecified.

Examples found in repository

examples/scene_admission.rs (line 28)

fn sample(count: u32, binding: RenderBinding) -> Result<(u128, u128, u64)> {
    let limits = SceneLimits {
        max_entities: count,
        max_snapshot_instances: count,
        max_snapshots: 1,
        managed_cpu_bytes: 512 * 1024 * 1024,
    };
    let bytes = limits.reservation_bytes()?;
    let mut world = SceneWorld::new(limits)?;
    let mut entities = Vec::with_capacity(count as usize);
    let started = Instant::now();
    for _ in 0..count {
        entities.push(world.spawn(black_box(Transform::default()), black_box(binding), None)?);
    }
    let initial = started.elapsed().as_nanos();
    let started = Instant::now();
    for id in entities.drain(..) {
        world.despawn(black_box(id))?;
    }
    for _ in 0..count {
        entities.push(world.spawn(black_box(Transform::default()), black_box(binding), None)?);
    }
    let reuse = started.elapsed().as_nanos();
    black_box((&world, &entities));
    assert_eq!(world.len(), count as usize);
    Ok((initial, reuse, bytes))
}

examples/scene.rs (lines 32-36)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Opaque asset identities only; this example qualifies CPU scene ownership, not drawing.
    let mut assets = ResourceArena::new(RenderLimits::default())?;
    let binding = RenderBinding {
        mesh: assets.insert((), 1)?,
        material: assets.insert((), 1)?,
        tint: [1.0; 4],
        animation: 0,
        morph: 0,
    };
    let mut world = SceneWorld::new(SceneLimits {
        max_entities: 64,
        max_snapshot_instances: 64,
        ..Default::default()
    })?;
    let mut first = None;
    for i in 0..64 {
        let id = world.spawn(
            Transform::default().with_position([i as f32, 0.0, 0.0])?,
            binding,
            Some(Velocity::new([1.0, 0.0, 0.0])?),
        )?;
        first = first.or(Some(id));
    }
    let before = world.snapshot()?;
    world.step_velocity(0.016)?;
    let after = world.snapshot()?;
    assert_eq!(before.instances()[0].transform.position()[0], 0.0);
    assert_eq!(after.instances()[0].transform.position()[0], 0.016);
    let mut commands = SceneCommands::new(8)?;
    if let Some(first) = first {
        commands.push(SceneCommand::SetVelocity(first, None))?;
    }
    for outcome in commands.apply(&mut world)? {
        outcome?;
    }
    println!(
        "entities={} owned_snapshots=2 moving_rows={}",
        world.len(),
        world.moving_columns().entities.len()
    );
    Ok(())
}

pub fn despawn(&mut self, id: EntityId) -> Result<(), RenderError>

Remove without invalidating other identities; stale handles never alias a later spawn.

Examples found in repository

examples/scene_admission.rs (line 33)

fn sample(count: u32, binding: RenderBinding) -> Result<(u128, u128, u64)> {
    let limits = SceneLimits {
        max_entities: count,
        max_snapshot_instances: count,
        max_snapshots: 1,
        managed_cpu_bytes: 512 * 1024 * 1024,
    };
    let bytes = limits.reservation_bytes()?;
    let mut world = SceneWorld::new(limits)?;
    let mut entities = Vec::with_capacity(count as usize);
    let started = Instant::now();
    for _ in 0..count {
        entities.push(world.spawn(black_box(Transform::default()), black_box(binding), None)?);
    }
    let initial = started.elapsed().as_nanos();
    let started = Instant::now();
    for id in entities.drain(..) {
        world.despawn(black_box(id))?;
    }
    for _ in 0..count {
        entities.push(world.spawn(black_box(Transform::default()), black_box(binding), None)?);
    }
    let reuse = started.elapsed().as_nanos();
    black_box((&world, &entities));
    assert_eq!(world.len(), count as usize);
    Ok((initial, reuse, bytes))
}

pub fn transform(&self, id: EntityId) -> Result<Transform, RenderError>

Read the current validated transform by stable identity.

pub fn set_transform( &mut self, id: EntityId, value: Transform, ) -> Result<(), RenderError>

Replace a validated transform without moving its row or binding.

pub fn set_velocity( &mut self, id: EntityId, velocity: Option<Velocity>, ) -> Result<(), RenderError>

Add/remove velocity through explicit archetype migration, preserving entity identity.

pub fn moving_columns(&mut self) -> MovingColumns<'_>

Borrow disjoint aligned transform/velocity columns. Structural mutation requires releasing them.

Examples found in repository

examples/scene.rs (line 54)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Opaque asset identities only; this example qualifies CPU scene ownership, not drawing.
    let mut assets = ResourceArena::new(RenderLimits::default())?;
    let binding = RenderBinding {
        mesh: assets.insert((), 1)?,
        material: assets.insert((), 1)?,
        tint: [1.0; 4],
        animation: 0,
        morph: 0,
    };
    let mut world = SceneWorld::new(SceneLimits {
        max_entities: 64,
        max_snapshot_instances: 64,
        ..Default::default()
    })?;
    let mut first = None;
    for i in 0..64 {
        let id = world.spawn(
            Transform::default().with_position([i as f32, 0.0, 0.0])?,
            binding,
            Some(Velocity::new([1.0, 0.0, 0.0])?),
        )?;
        first = first.or(Some(id));
    }
    let before = world.snapshot()?;
    world.step_velocity(0.016)?;
    let after = world.snapshot()?;
    assert_eq!(before.instances()[0].transform.position()[0], 0.0);
    assert_eq!(after.instances()[0].transform.position()[0], 0.016);
    let mut commands = SceneCommands::new(8)?;
    if let Some(first) = first {
        commands.push(SceneCommand::SetVelocity(first, None))?;
    }
    for outcome in commands.apply(&mut world)? {
        outcome?;
    }
    println!(
        "entities={} owned_snapshots=2 moving_rows={}",
        world.len(),
        world.moving_columns().entities.len()
    );
    Ok(())
}

pub fn step_velocity(&mut self, dt: f32) -> Result<(), RenderError>

Integrate local velocity with a bounded timestep; validate every candidate before committing any.

Examples found in repository

examples/scene.rs (line 40)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Opaque asset identities only; this example qualifies CPU scene ownership, not drawing.
    let mut assets = ResourceArena::new(RenderLimits::default())?;
    let binding = RenderBinding {
        mesh: assets.insert((), 1)?,
        material: assets.insert((), 1)?,
        tint: [1.0; 4],
        animation: 0,
        morph: 0,
    };
    let mut world = SceneWorld::new(SceneLimits {
        max_entities: 64,
        max_snapshot_instances: 64,
        ..Default::default()
    })?;
    let mut first = None;
    for i in 0..64 {
        let id = world.spawn(
            Transform::default().with_position([i as f32, 0.0, 0.0])?,
            binding,
            Some(Velocity::new([1.0, 0.0, 0.0])?),
        )?;
        first = first.or(Some(id));
    }
    let before = world.snapshot()?;
    world.step_velocity(0.016)?;
    let after = world.snapshot()?;
    assert_eq!(before.instances()[0].transform.position()[0], 0.0);
    assert_eq!(after.instances()[0].transform.position()[0], 0.016);
    let mut commands = SceneCommands::new(8)?;
    if let Some(first) = first {
        commands.push(SceneCommand::SetVelocity(first, None))?;
    }
    for outcome in commands.apply(&mut world)? {
        outcome?;
    }
    println!(
        "entities={} owned_snapshots=2 moving_rows={}",
        world.len(),
        world.moving_columns().entities.len()
    );
    Ok(())
}

pub fn snapshot(&self) -> Result<SceneSnapshot, RenderError>

Extract owned instances; rejects excess before allocating the snapshot. A renderer must resolve asset identities before uploading or submitting a draw.

Examples found in repository

examples/scene.rs (line 39)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Opaque asset identities only; this example qualifies CPU scene ownership, not drawing.
    let mut assets = ResourceArena::new(RenderLimits::default())?;
    let binding = RenderBinding {
        mesh: assets.insert((), 1)?,
        material: assets.insert((), 1)?,
        tint: [1.0; 4],
        animation: 0,
        morph: 0,
    };
    let mut world = SceneWorld::new(SceneLimits {
        max_entities: 64,
        max_snapshot_instances: 64,
        ..Default::default()
    })?;
    let mut first = None;
    for i in 0..64 {
        let id = world.spawn(
            Transform::default().with_position([i as f32, 0.0, 0.0])?,
            binding,
            Some(Velocity::new([1.0, 0.0, 0.0])?),
        )?;
        first = first.or(Some(id));
    }
    let before = world.snapshot()?;
    world.step_velocity(0.016)?;
    let after = world.snapshot()?;
    assert_eq!(before.instances()[0].transform.position()[0], 0.0);
    assert_eq!(after.instances()[0].transform.position()[0], 0.016);
    let mut commands = SceneCommands::new(8)?;
    if let Some(first) = first {
        commands.push(SceneCommand::SetVelocity(first, None))?;
    }
    for outcome in commands.apply(&mut world)? {
        outcome?;
    }
    println!(
        "entities={} owned_snapshots=2 moving_rows={}",
        world.len(),
        world.moving_columns().entities.len()
    );
    Ok(())
}