Struct World 

pub struct World {
    pub ecs: DynEcs,
}

The engine’s ECS: a freecs::dynamic::DynEcs group with the core and retained-UI member worlds over one shared entity allocator, plus the engine’s resources. The group keeps the lifecycle log (handle allocation and death anywhere); each member world keeps its own row-level structural log. Member access is world.ecs.worlds[CORE] / world.ecs.worlds[UI]; group operations (spawning, despawn broadcast, liveness) are available directly on World through deref.

Fields

ecs: DynEcs

Implementations

impl World

pub fn plugin_resource<T>(&self) -> &T

where T: Send + Sync + 'static,

Borrows a plugin-owned resource stored in the ECS resource map, panicking with the type name if the owning plugin was never composed.

pub fn plugin_resource_mut<T>(&mut self) -> &mut T

where T: Send + Sync + 'static,

Mutably borrows a plugin-owned resource stored in the ECS resource map, panicking with the type name if the owning plugin was never composed.

pub fn set<T>(&mut self, entity: Entity, value: T)

where T: Send + Sync + Default + 'static,

Writes T on the member world that registered it, exactly as the group-typed DynEcs::set does. A type no member world has registered is an app component: it lazily registers into the app member world (GAME), creating that world the first time one is written, so game code stores components on engine entities without declaring a schema. Reads of an unregistered type already come back empty (get, has, query_ref); a component a game serializes into snapshots still earns an explicit serde schema, which lazy registration cannot carry.

Methods from Deref<Target = DynEcs>

pub fn structural_sequence(&self) -> u64

pub fn structural_changes_since(&self, cursor: u64) -> &[StructuralChange]

The group-level lifecycle log: handle allocation (Spawned with mask 0), handle death anywhere (Despawned with mask 0), and group tag flips (TagsAdded/TagsRemoved carrying the tag index in the mask field, since group tags have no mask bits). Row-level history lives in each member world’s own structural log, where an entity is Spawned with a component mask when its first components arrive there.

pub fn trim_structural_log(&mut self, up_to_sequence: u64)

pub fn clear_structural_log(&mut self)

pub fn add_world(&mut self, registry: ComponentRegistry) -> usize

Adds a world built from the given registry and returns its index. Grouped worlds insert rows for live handles they have never stored, which is what lets an entity gain components per world lazily.

pub fn spawn(&mut self) -> Entity

Allocates a handle with no rows anywhere. Give it components through any member world’s set/add_components.

pub fn spawn_with<B>(&mut self, bundle: B) -> Entity

where B: Bundle,

Spawns one group entity carrying the bundle, with each component routed to the member world that registered its type, so a bundle can span worlds. Panics like set if a component type is registered nowhere.

pub fn route<T>(&mut self) -> Option<usize>

where T: Send + Sync + Default + 'static,

Which member world holds T, scanning members in index order and caching the answer in type_routes. Returns None when no member world has registered T; group-typed access never registers lazily, because only a schema decides where a type lives.

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

where T: Send + Sync + Default + 'static,

Reads T from whichever member world holds it, no world index required.

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

where T: Send + Sync + Default + 'static,

The mutable form of get; stamps change ticks exactly like the member world’s accessor.

pub fn set<T>(&mut self, entity: Entity, value: T)

where T: Send + Sync + Default + 'static,

Writes T on the member world that registered it, adding the component if the entity lacks it. Panics if no member world has registered T: group-typed access never picks a world for a new type, that is a schema decision.

pub fn has<T>(&self, entity: Entity) -> bool

where T: Send + Sync + Default + 'static,

Whether the entity carries T in whichever member world holds it.

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

where T: Send + Sync + Default + 'static,

Removes T from the member world that holds it. Returns false when the type is registered nowhere or the entity lacks it.

pub fn query<Q>(&mut self) -> DynQuery<'_, Q>

where Q: QueryTuple,

A typed query against the first member world where every required element of the tuple is registered; optional elements do not constrain the routing. When no member world qualifies the query is empty rather than a panic, mirroring query_ref: an unregistered component matches nothing, and a tuple whose parts live in different member worlds runs through query_join to iterate for real.

pub fn query_join<Q>(&mut self) -> DynJoin<'_, Q>

where Q: QueryTuple,

A typed query whose tuple may span member worlds, joined by entity. One world drives the iteration at full slice speed, the world holding every mutable element; the other worlds resolve their elements per entity at get speed, read-only, skipping entities that lack a required foreign component. Mutable elements in two different worlds panic at for_each: mutate your own state, read theirs, or co-locate the types in one schema when a hot loop needs slice speed for everything. A tuple that resolves to a single world degenerates to a plain scan of it.

pub fn query_join_ref<Q>(&self) -> DynJoinRef<'_, Q>

where Q: ReadQueryTuple,

The read-only cross-world join, a real Iterator on &self: items borrow the group, the driver world walks its tables, and foreign elements resolve per entity, read-only like every join element. Unresolvable routing or filters degrade to an empty iterator, matching query_ref.

pub fn query_ref<Q>(&self) -> DynQueryRef<'_, Q>

where Q: ReadQueryTuple,

The read-only routed query. When no member world registers every required element the query is empty rather than a panic, matching DynWorld::query_ref’s graceful degradation.

pub fn step(&mut self)

Advances the group frame: expires group events past their two-frame window and steps every member world, so one call at frame end drives group-level and world-level event lifetimes and change windows together. This call replaces per-member stepping; call either this or the members’ own steps each frame, never both, or change windows and event expiry advance twice per frame.

pub fn send<T>(&mut self, event: T)

where T: Send + Sync + 'static,

Sends a group-level event, the shared channel for events that cross member-world (and plugin) boundaries; world-local events stay on DynWorld::send. Same two-frame buffer, expired by step.

pub fn read_events<T>(&self) -> &[T]

where T: Send + Sync + 'static,

Everything still buffered for T at the group level, oldest first.

pub fn read_frame_events<T>(&self) -> &[T]

where T: Send + Sync + 'static,

The group-level T events settled at the last step: the previous frame’s frozen set, broadcast without a cursor. See EventChannel::read_frame.

pub fn read_events_since<T>(&self, cursor: u64) -> &[T]

where T: Send + Sync + 'static,

pub fn consume_events<T>(&self, cursor: &mut u64) -> &[T]

where T: Send + Sync + 'static,

The exactly-once group read: yields events sent after the cursor and advances it past them. Keep one u64 cursor per consumer.

pub fn event_sequence<T>(&self) -> u64

where T: Send + Sync + 'static,

pub fn clear_events<T>(&mut self)

where T: Send + Sync + 'static,

pub fn insert_resource<T>(&mut self, value: T)

where T: Send + Sync + 'static,

Inserts a group-level resource, the home for state shared across member worlds and plugins; world-local resources stay on DynWorld::insert_resource.

pub fn insert_resources<B>(&mut self, bundle: B)

where B: ResourceBundle,

Inserts several group-level resources at once from a tuple, each replacing any existing resource of its type. Equivalent to one insert_resource per element.

pub fn resource<T>(&self) -> Option<&T>

where T: Send + Sync + 'static,

pub fn resource_mut<T>(&mut self) -> Option<&mut T>

where T: Send + Sync + 'static,

pub fn res<T>(&self) -> &T

where T: Send + Sync + 'static,

resource for resources that must exist: panics with the type name instead of returning Option.

pub fn res_mut<T>(&mut self) -> &mut T

where T: Send + Sync + 'static,

The mutable form of res.

pub fn remove_resource<T>(&mut self) -> Option<T>

where T: Send + Sync + 'static,

pub fn resource_scope<R, T>( &mut self, f: impl FnOnce(&mut DynEcs, &mut R) -> T, ) -> T

where R: Send + Sync + 'static,

Takes a group resource out, runs the closure with the group and the resource as independent borrows, then puts it back, even when the closure panics. Panics if R is not present.

The closure receives the bare DynEcs, so a host that wraps the group in its own state struct implements ResourceHost and imports ResourceHostExt, whose scope methods lend the host itself to the closure.

pub fn resources_scope<B, T>( &mut self, f: impl FnOnce(&mut DynEcs, &mut B) -> T, ) -> T

where B: ResourceBundle,

The tuple form of resource_scope, same semantics as DynWorld::resources_scope.

pub fn add_world_at( &mut self, expected_index: usize, registry: ComponentRegistry, ) -> usize

add_world with the index asserted against the constant a schema pairs with this member, replacing the hand-written add-then-assert dance. Panics when members register out of declaration order.

pub fn spawn_count(&mut self, count: usize) -> Vec<Entity>

pub fn spawn_entities( &mut self, world_index: usize, mask: u64, count: usize, ) -> Vec<Entity>

Spawns entities with rows in one member world. The handles land in the group lifecycle log as Spawned with mask 0; the component mask lands in that world’s own structural log.

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

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

Despawns the entity across every world, dropping its group tags. Returns false for stale or already-despawned handles. Retirement broadcasts the bumped generation into every world’s location table, 16 bytes per despawned id per world, which is what makes stale writes refusable everywhere.

pub fn despawn_entities(&mut self, entities: &[Entity]) -> Vec<Entity>

pub fn despawn_recursive(&mut self, root: Entity) -> Vec<Entity>

Despawns an entity and every descendant reachable through ChildOf links in any member world, breadth-first over on-demand scans. This is the grouped form of DynWorld::despawn_recursive: each entity dies through the group, so retirement broadcasts into every member world, group tags drop, and the lifecycle log records each death. Link cycles are tolerated, each entity despawns once. Returns the despawned entities.

pub fn register_tag(&mut self) -> usize

Registers a group-level tag and returns its index. Group tags have no mask bit; they filter queries by set reference.

pub fn add_tag(&mut self, tag_index: usize, entity: Entity)

pub fn remove_tag(&mut self, tag_index: usize, entity: Entity) -> bool

pub fn has_tag(&self, tag_index: usize, entity: Entity) -> bool

pub fn query_tag(&self, tag_index: usize) -> impl Iterator<Item = Entity>

pub fn stats(&self) -> EcsStats

The group-level census. See EcsStats for the fields.

pub fn compact(&mut self) -> usize

DynWorld::compact over every member world. Returns the total number of tables dropped.

pub fn tag_type_index<T>(&mut self) -> usize

where T: 'static,

The group tag index for marker type T, registering the tag on first use. Group tags are the natural home for entity-scoped markers: they consume no member world’s mask bits and need no world index to touch.

pub fn lookup_tag_type<T>(&self) -> Option<usize>

where T: 'static,

The group tag index for marker type T if it has been used, without registering it. Falls back to the persisted type names, so marker tags restored by DynEcs::from_snapshot resolve here before the TypeId map is rebuilt.

pub fn add_tag_type<T>(&mut self, entity: Entity)

where T: 'static,

Adds the marker type T’s group tag to an entity, registering the tag on first use.

pub fn remove_tag_type<T>(&mut self, entity: Entity) -> bool

where T: 'static,

Removes the marker type T’s group tag from an entity. Unregistered marker types remove nothing.

pub fn has_tag_type<T>(&self, entity: Entity) -> bool

where T: 'static,

Whether an entity carries the marker type T’s group tag. Unregistered marker types read as absent.

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

where T: 'static,

Iterates entities carrying the marker type T’s group tag. Unregistered marker types match nothing.

pub fn tag_set_type<T>(&self) -> Option<&SparseTagSet>

where T: 'static,

The marker type T’s group tag set, for composing into per-world typed queries with with_tag_set/without_tag_set. None until the tag’s first use.

pub fn delta_cursor(&mut self) -> DynEcsDeltaCursor

The group cursor a delta stream starts from, fencing every member’s change window like DynWorld::delta_cursor.

pub fn delta_since( &mut self, cursor: &DynEcsDeltaCursor, ) -> Result<DynEcsDelta, SnapshotError>

DynWorld::delta_since across the whole group: the group’s structural window (handle lifecycle and group tags) plus one world delta per member, each fenced.

pub fn apply_delta(&mut self, delta: &DynEcsDelta) -> Result<(), SnapshotError>

Replays a group delta: group handle lifecycle and group tags in order, then each member’s delta.

pub fn set_component_by_name( &mut self, entity: Entity, name: &str, bytes: &[u8], ) -> Result<(), SnapshotError>

DynWorld::set_component_by_name routed to the member world whose registry carries the name.

pub fn get_component_by_name( &self, entity: Entity, name: &str, ) -> Result<Option<Vec<u8>>, SnapshotError>

DynWorld::get_component_by_name routed to the member world whose registry carries the name.

pub fn snapshot(&self) -> Result<DynEcsSnapshot, SnapshotError>

Trait Implementations

impl Default for World

fn default() -> World

Returns the “default value” for a type.

impl Deref for World

type Target = DynEcs

The resulting type after dereferencing.

fn deref(&self) -> &<World as Deref>::Target

Dereferences the value.

impl DerefMut for World

fn deref_mut(&mut self) -> &mut <World as Deref>::Target

Mutably dereferences the value.

impl EventHost for World

fn event_bus_mut(&mut self) -> &mut EventBus

The host’s event bus, for reading and writing events.

fn event_bus(&self) -> &EventBus

The same bus, shared, for reading events behind a &self, such as the frame-settled broadcast EventBus::read_frame. Must return the same bus as event_bus_mut.

impl ResourceHost for World

fn resource_map_mut(&mut self) -> &mut ResourceMap

fn resource_map(&self) -> &ResourceMap

The same map, shared, for reading a resource behind a &self, such as a run condition that checks a state. Must return the same map as resource_map_mut.