Struct SimpleWorld 

pub struct SimpleWorld { /* private fields */ }

Simplified game world optimized for Soroban on-chain storage.

Uses Map-based storage for O(log n) component lookups instead of linear scans. This is the recommended ECS container for Soroban contracts.

Dual-Map storage

Components are split into two maps based on their ComponentStorage kind:

• Table (components): Frequently-iterated components (e.g., Position, Velocity). Queried by get_entities_with_component().
• Sparse (sparse_components): Infrequently-accessed marker or tag components. Not included in the default entity query; use get_all_entities_with_component() to include them.

Both maps are transparent to get_component(), has_component(), and remove_component().

Example

use cougr_core::component::ComponentStorage;
use cougr_core::simple_world::SimpleWorld;
use soroban_sdk::{symbol_short, Bytes, Env};

let env = Env::default();
let mut world = SimpleWorld::new(&env);
let entity_id = world.spawn_entity();
world.add_component(entity_id, symbol_short!("position"), Bytes::new(&env));
world.add_component_with_storage(
    entity_id,
    symbol_short!("marker"),
    Bytes::new(&env),
    ComponentStorage::Sparse,
);
assert!(world.has_component(entity_id, &symbol_short!("position")));

Implementations

impl SimpleWorld

pub const fn spec_xdr() -> [u8; 1716]

impl SimpleWorld

pub fn new(env: &Env) -> Self

pub fn version(&self) -> u64

Returns the current world version for cache invalidation.

pub fn next_entity_id(&self) -> EntityId

Returns the next entity ID that will be assigned on spawn.

pub fn env(&self) -> &Env

Returns the environment backing this world storage.

pub fn spawn_entity(&mut self) -> EntityId

pub fn add_component( &mut self, entity_id: EntityId, component_type: Symbol, data: Bytes, )

Add a component using the default Table storage.

pub fn add_component_with_storage( &mut self, entity_id: EntityId, component_type: Symbol, data: Bytes, storage: ComponentStorage, )

Add a component, routing to the Table or Sparse map based on storage.

pub fn get_component( &self, entity_id: EntityId, component_type: &Symbol, ) -> Option<Bytes>

Get a component’s data, checking both Table and Sparse maps transparently.

pub fn remove_component( &mut self, entity_id: EntityId, component_type: &Symbol, ) -> bool

Remove a component from both Table and Sparse maps transparently.

pub fn has_component( &self, entity_id: EntityId, component_type: &Symbol, ) -> bool

Check if an entity has a component in either Table or Sparse storage.

pub fn get_entities_with_component( &self, component_type: &Symbol, env: &Env, ) -> Vec<EntityId>

pub fn get_table_entities_with_component( &self, component_type: &Symbol, env: &Env, ) -> Vec<EntityId>

Get entities that have the given component in Table storage only. This is the fast path for querying frequently-iterated components.

pub fn get_all_entities_with_component( &self, component_type: &Symbol, env: &Env, ) -> Vec<EntityId>

Get entities that have the given component in either Table or Sparse storage.

pub fn table_component_count(&self, component_type: &Symbol) -> usize

Returns the number of entities indexed for a component in table storage only.

pub fn component_count(&self, component_type: &Symbol) -> usize

Returns the number of entities indexed for a component across both storage classes.

pub fn get_typed<T: ComponentTrait>( &self, env: &Env, entity_id: EntityId, ) -> Option<T>

Get a component and deserialize it into the concrete type.

Example

use cougr_core::component::Position;
use cougr_core::simple_world::SimpleWorld;
use soroban_sdk::Env;

let env = Env::default();
let mut world = SimpleWorld::new(&env);
let entity_id = world.spawn_entity();
world.set_typed(&env, entity_id, &Position::new(10, 20));
let pos: Option<Position> = world.get_typed::<Position>(&env, entity_id);
assert_eq!(pos.unwrap().x, 10);

pub fn set_typed<T: ComponentTrait>( &mut self, env: &Env, entity_id: EntityId, component: &T, )

Serialize a component and store it, using the type’s default storage kind.

Example

use cougr_core::component::Position;
use cougr_core::simple_world::SimpleWorld;
use soroban_sdk::Env;

let env = Env::default();
let mut world = SimpleWorld::new(&env);
let entity_id = world.spawn_entity();
world.set_typed(&env, entity_id, &Position::new(10, 20));
assert!(world.has_typed::<Position>(entity_id));

pub fn has_typed<T: ComponentTrait>(&self, entity_id: EntityId) -> bool

Check if an entity has a component of the given type.

pub fn remove_typed<T: ComponentTrait>(&mut self, entity_id: EntityId) -> bool

Remove a component of the given type from an entity.

pub fn despawn_entity(&mut self, entity_id: EntityId)

Trait Implementations

impl Clone for SimpleWorld

fn clone(&self) -> SimpleWorld

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SimpleWorld

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

Formats the value using the given formatter.

impl RuntimeWorld for SimpleWorld

fn backend(&self) -> WorldBackend

fn entity_count(&self) -> usize

fn version(&self) -> u64

fn has_component(&self, entity_id: EntityId, component_type: &Symbol) -> bool

fn entities_with_component( &self, component_type: &Symbol, storage: QueryStorage, env: &Env, ) -> Vec<EntityId>

impl RuntimeWorldMut for SimpleWorld

fn spawn_entity(&mut self) -> EntityId

fn despawn_entity(&mut self, entity_id: EntityId, _env: &Env)

fn get_component( &self, entity_id: EntityId, component_type: &Symbol, ) -> Option<Bytes>

fn add_component( &mut self, entity_id: EntityId, component_type: Symbol, data: Bytes, _env: &Env, )

fn remove_component( &mut self, entity_id: EntityId, component_type: &Symbol, _env: &Env, ) -> bool

fn get_typed<T: ComponentTrait>( &self, env: &Env, entity_id: EntityId, ) -> Option<T>

fn set_typed<T: ComponentTrait>( &mut self, env: &Env, entity_id: EntityId, component: &T, )

fn has_typed<T: ComponentTrait>(&self, entity_id: EntityId) -> bool

fn remove_typed<T: ComponentTrait>( &mut self, env: &Env, entity_id: EntityId, ) -> bool

impl TryFromVal<Env, &SimpleWorld> for Val

type Error = ConversionError

fn try_from_val(env: &Env, val: &&SimpleWorld) -> Result<Self, ConversionError>

impl TryFromVal<Env, SimpleWorld> for Val

type Error = ConversionError

fn try_from_val(env: &Env, val: &SimpleWorld) -> Result<Self, ConversionError>

impl TryFromVal<Env, Val> for SimpleWorld

type Error = ConversionError

fn try_from_val(env: &Env, val: &Val) -> Result<Self, ConversionError>