Struct SparseSet 

pub struct SparseSet<T> { /* private fields */ }

A sparse set storing values of type T indexed by Entity.

Provides O(1) access operations while maintaining cache-friendly iteration. This is the primary storage backend for ECS components.

Type Parameters

• T: The value type stored in the set

Memory Layout

The sparse set trades memory for performance:

• Sparse vec grows to max entity index seen (sparse memory usage)
• Dense and values vecs are tightly packed (no gaps)

For entities with indices 0, 100, 1000, the sparse vec will have 1001 entries, but dense/values will only have 3 entries.

Implementations

impl<T> SparseSet<T>

pub fn new() -> SparseSet<T>

Creates a new, empty sparse set.

Example

use goud_engine::ecs::SparseSet;

let set: SparseSet<i32> = SparseSet::new();
assert!(set.is_empty());
assert_eq!(set.len(), 0);

pub fn with_capacity(capacity: usize) -> SparseSet<T>

Creates a sparse set with pre-allocated capacity.

This pre-allocates the dense and values vectors, but not the sparse vector (which grows on demand based on entity indices).

Arguments

• capacity - Number of elements to pre-allocate

Example

use goud_engine::ecs::SparseSet;

let set: SparseSet<String> = SparseSet::with_capacity(1000);
assert!(set.is_empty());

pub fn insert(&mut self, entity: Entity, value: T) -> Option<T>

Inserts a value for the given entity.

If the entity already has a value, it is replaced and the old value is returned. Otherwise, None is returned.

Arguments

• entity - The entity to associate with the value
• value - The value to store

Returns

The previous value if one existed, or None.

Panics

Panics if the entity is a placeholder (Entity::PLACEHOLDER).

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set = SparseSet::new();
let entity = Entity::new(0, 1);

assert_eq!(set.insert(entity, 42), None);
assert_eq!(set.insert(entity, 99), Some(42)); // Returns old value
assert_eq!(set.get(entity), Some(&99));

pub fn remove(&mut self, entity: Entity) -> Option<T>

Removes the value for the given entity.

Uses swap-remove to maintain dense packing: the last element is moved to fill the gap, keeping iteration cache-friendly.

Arguments

• entity - The entity whose value to remove

Returns

The removed value if one existed, or None.

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set = SparseSet::new();
let entity = Entity::new(0, 1);

set.insert(entity, "hello");
assert_eq!(set.remove(entity), Some("hello"));
assert_eq!(set.remove(entity), None); // Already removed

pub fn get(&self, entity: Entity) -> Option<&T>

Returns a reference to the value for the given entity.

Arguments

• entity - The entity to look up

Returns

A reference to the value if the entity has one, or None.

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set = SparseSet::new();
let entity = Entity::new(0, 1);

set.insert(entity, 42);
assert_eq!(set.get(entity), Some(&42));

let missing = Entity::new(999, 1);
assert_eq!(set.get(missing), None);

pub fn get_mut(&mut self, entity: Entity) -> Option<&mut T>

Returns a mutable reference to the value for the given entity.

Arguments

• entity - The entity to look up

Returns

A mutable reference to the value if the entity has one, or None.

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set = SparseSet::new();
let entity = Entity::new(0, 1);

set.insert(entity, 42);

if let Some(value) = set.get_mut(entity) {
    *value = 100;
}

assert_eq!(set.get(entity), Some(&100));

pub fn contains(&self, entity: Entity) -> bool

Returns true if the entity has a value in this set.

Arguments

• entity - The entity to check

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set = SparseSet::new();
let entity = Entity::new(0, 1);

assert!(!set.contains(entity));
set.insert(entity, "value");
assert!(set.contains(entity));

pub fn len(&self) -> usize

Returns the number of entities with values in this set.

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set = SparseSet::new();
assert_eq!(set.len(), 0);

set.insert(Entity::new(0, 1), "a");
set.insert(Entity::new(5, 1), "b");
assert_eq!(set.len(), 2);

pub fn is_empty(&self) -> bool

Returns true if the set contains no values.

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set: SparseSet<i32> = SparseSet::new();
assert!(set.is_empty());

set.insert(Entity::new(0, 1), 42);
assert!(!set.is_empty());

pub fn clear(&mut self)

Removes all values from the set.

This clears all three internal arrays. After calling clear(), len() will return 0.

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set = SparseSet::new();
set.insert(Entity::new(0, 1), "a");
set.insert(Entity::new(1, 1), "b");
assert_eq!(set.len(), 2);

set.clear();
assert!(set.is_empty());

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements.

This affects the dense and values arrays, not the sparse array (which grows based on entity indices).

Arguments

• additional - Number of additional elements to reserve

Example

use goud_engine::ecs::SparseSet;

let mut set: SparseSet<i32> = SparseSet::new();
set.reserve(1000);

impl<T> SparseSet<T>

pub fn iter(&self) -> SparseSetIter<'_, T>

Returns an iterator over (Entity, &T) pairs.

Iteration is cache-friendly because it traverses the dense array sequentially.

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set = SparseSet::new();
set.insert(Entity::new(0, 1), "a");
set.insert(Entity::new(1, 1), "b");

for (entity, value) in set.iter() {
    println!("{}: {}", entity, value);
}

pub fn iter_mut(&mut self) -> SparseSetIterMut<'_, T>

Returns a mutable iterator over (Entity, &mut T) pairs.

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set = SparseSet::new();
set.insert(Entity::new(0, 1), 1);
set.insert(Entity::new(1, 1), 2);

for (_, value) in set.iter_mut() {
    *value *= 10;
}

assert_eq!(set.get(Entity::new(0, 1)), Some(&10));
assert_eq!(set.get(Entity::new(1, 1)), Some(&20));

pub fn entities(&self) -> impl Iterator<Item = Entity>

Returns an iterator over all entities in the set.

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set = SparseSet::new();
set.insert(Entity::new(0, 1), "a");
set.insert(Entity::new(5, 1), "b");

let entities: Vec<_> = set.entities().collect();
assert_eq!(entities.len(), 2);

pub fn values(&self) -> impl Iterator<Item = &T>

Returns an iterator over all values in the set.

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set = SparseSet::new();
set.insert(Entity::new(0, 1), 10);
set.insert(Entity::new(5, 1), 20);

let sum: i32 = set.values().sum();
assert_eq!(sum, 30);

pub fn values_mut(&mut self) -> impl Iterator<Item = &mut T>

Returns a mutable iterator over all values in the set.

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set = SparseSet::new();
set.insert(Entity::new(0, 1), 10);
set.insert(Entity::new(1, 1), 20);

for value in set.values_mut() {
    *value += 1;
}

let sum: i32 = set.values().sum();
assert_eq!(sum, 32); // 11 + 21

pub fn dense(&self) -> &[Entity]

Returns the raw entity array for direct access.

This is useful for bulk operations or implementing custom iterators.

Example

use goud_engine::ecs::{Entity, SparseSet};

let mut set = SparseSet::new();
set.insert(Entity::new(0, 1), "a");
set.insert(Entity::new(1, 1), "b");

let dense = set.dense();
assert_eq!(dense.len(), 2);

pub fn dense_index(&self, entity: Entity) -> Option<usize>

Returns the dense index for an entity, if it exists.

This is an advanced method for implementing custom storage operations.

Arguments

• entity - The entity to look up

Returns

The index in the dense array, or None if the entity has no value.

pub fn get_by_dense_index(&self, dense_index: usize) -> Option<&T>

Returns the value at the given dense index.

Safety

This method does not validate the index. Use dense_index() to get a valid index first.

Arguments

• dense_index - Index into the dense/values arrays

pub fn get_mut_by_dense_index(&mut self, dense_index: usize) -> Option<&mut T>

Returns a mutable reference to the value at the given dense index.

impl<T> SparseSet<T>

pub fn insert_with_tick( &mut self, entity: Entity, value: T, change_tick: u32, ) -> Option<T>

Inserts a value for the given entity, recording the given change_tick.

On a new insert both added_tick and changed_tick are set to change_tick. On a replacement only changed_tick is updated.

If the entity already has a value, the old value is returned.

Panics

Panics if entity is a placeholder.

pub fn get_added_tick(&self, entity: Entity) -> Option<u32>

Returns the added tick for the given entity, if present.

pub fn get_changed_tick(&self, entity: Entity) -> Option<u32>

Returns the changed tick for the given entity, if present.

pub fn set_changed_tick(&mut self, entity: Entity, tick: u32)

Sets the changed tick for the given entity.

Does nothing if the entity is not in the set.

Trait Implementations

impl<T> AnyComponentStorage for SparseSet<T>

where T: Component,

fn contains_entity(&self, entity: Entity) -> bool

Returns true if the entity has a component in this storage.

fn remove_entity(&mut self, entity: Entity) -> bool

Removes the component for the given entity (dropping the value).

fn storage_len(&self) -> usize

Returns the number of components in this storage.

fn storage_is_empty(&self) -> bool

Returns true if this storage contains no components.

fn clear(&mut self)

Clears all components from this storage.

fn component_type_name(&self) -> &'static str

Returns the type name of the stored component (for debugging).

impl<T> Clone for SparseSet<T>

where T: Clone,

fn clone(&self) -> SparseSet<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> ComponentStorage for SparseSet<T>

where T: Component,

type Item = T

The component type stored in this storage.

fn insert(&mut self, entity: Entity, value: T) -> Option<T>

Inserts a component for the given entity.

fn remove(&mut self, entity: Entity) -> Option<T>

Removes the component for the given entity.

fn get(&self, entity: Entity) -> Option<&T>

Returns a reference to the component for the given entity.

fn get_mut(&mut self, entity: Entity) -> Option<&mut T>

Returns a mutable reference to the component for the given entity.

fn contains(&self, entity: Entity) -> bool

Returns true if the entity has a component in this storage.

fn len(&self) -> usize

Returns the number of components in this storage.

fn is_empty(&self) -> bool

Returns true if this storage contains no components.

impl<T> Debug for SparseSet<T>

where T: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Default for SparseSet<T>

fn default() -> SparseSet<T>

Returns the “default value” for a type.

impl<'a, T> IntoIterator for &'a SparseSet<T>

type Item = (Entity, &'a T)

The type of the elements being iterated over.

type IntoIter = SparseSetIter<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <&'a SparseSet<T> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<'a, T> IntoIterator for &'a mut SparseSet<T>

type Item = (Entity, &'a mut T)

The type of the elements being iterated over.

type IntoIter = SparseSetIterMut<'a, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> <&'a mut SparseSet<T> as IntoIterator>::IntoIter

Creates an iterator from a value.