Struct World 

pub struct World { /* private fields */ }

Entities with their components, opaque components and resources.

Implementations

impl World

pub fn new() -> Self

pub fn take_dropped(&mut self) -> Dropped

What entities leaving dropped since the last call (World::retain, World::despawn, World::move_components); a World::part states its own.

pub fn spawn(&mut self) -> Entity

pub fn spawn_at(&mut self, e: Entity) -> Result<Entity, IdError>

Spawn with an explicit id, for readers of serialised worlds that keep the file’s ids. Ids must come in ascending order (gaps allowed), so ids stay unique: an id at or below one already handed out, or the last id (there is none to follow it), is an error and changes nothing.

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

Remove an entity and all its components. Returns false if it was not alive.

pub fn move_components( &mut self, from: Entity, to: Entity, ) -> Result<bool, String>

Every component of from, typed and opaque, moved onto to, replacing to’s of the same name (to keeps the others), then from despawned: for a pass that swaps one form of an entity for another without knowing its components (select-lod). Ok(false), and nothing changed, unless both are alive and differ.

Refused, changing nothing, when it would leave data describing one mesh beside another (Component::GEOMETRY): from brings a mesh (core.mesh or core.mesh_file) while to keeps such data from has none of (take to’s away first: World::remove_mesh), or from brings such data without a mesh onto a to that has one.

pub fn duplicate(&mut self, e: Entity) -> Option<Entity>

A new entity with a copy of every typed and opaque component of e; None when e is not alive. Shallow: references in the copies still name the entities e’s did (a pass that needs referenced entities copied too, LOD forms of a prototype, copies them itself).

pub fn restate_components(&mut self, resolved: &Resolved<'_>) -> Vec<Entity>

Every typed component restated for the axes resolved gave values (Component::restate): the entities some component says are not present in that state, sorted and without repeats, for the caller to remove. The values of every other component are replaced in place. Opaque components hold no clause a pass could read.

pub fn apply_linear( &mut self, e: Entity, l: &Linear, ) -> Result<Vec<String>, Vec<String>>

Map e’s local space by l: every component of e through Component::apply_linear. All or nothing: when a component is Linearity::Unsupported (opaque components always are) nothing changes and the error names every such component, sorted. Otherwise the names of the components it dropped (Linearity::Drop), sorted.

pub fn remap_primitives( &mut self, e: Entity, from: &[usize], ) -> Result<(), String>

Keep e‘s per-primitive components in step with its rebuilt mesh: every typed component that follows primitives (Component::remap_primitives) remapped by from (new primitive i from old from[i]). A pass that splits, reorders or drops a mesh’s primitives calls it once, so it need not know the dialects’ components. All or nothing: an error (an index a component does not have, or a component refusing the mapping) names the component and changes nothing.

An opaque component (bytes a reader carried without a type) can’t follow: whether it describes primitives can’t be known, so a mapping that changes the list (anything but 0..n in order) is refused while e has one, before anything changes, naming them. The program removes them (a selection, reported) or gives them a typed form first.

pub fn remap_vertices( &mut self, e: Entity, primitive: usize, from: &[u32], ) -> Result<(), String>

Remap every per-vertex component of e (Component::remap_vertices) for its mesh primitive primitive, whose vertices a pass compacted or reordered: new vertex i is old vertex from[i]. The pass changes the primitive itself and calls this for every other component, so it need not know the dialects’ components; it calls it only when the vertices changed. All or nothing: an error (an index a component does not have, or a component refusing the mapping) names the component and changes nothing. Refused, changing nothing, while e has an opaque component, as World::remap_primitives refuses then (whether it describes vertices can’t be known).

pub fn check_remap_vertices( &self, e: Entity, primitive: usize, from: &[u32], ) -> Result<(), String>

Why World::remap_vertices would refuse, without changing anything: a pass checks every entity before it changes any.

pub fn blend_vertices( &mut self, e: Entity, primitive: usize, from: &[VertexBlend], ) -> Result<(), String>

Rebuild every per-vertex component of e (Component::blend_vertices) for its mesh primitive primitive, whose vertices a pass made as blends of the old ones: new vertex i is from[i]. The pass changes the primitive itself and calls this for every other component, so it need not know the dialects’ components. All or nothing, like World::remap_vertices: an error (an index a component does not have, a component that cannot combine its vertices, an opaque component on e) names the cause and changes nothing.

pub fn check_blend_vertices( &self, e: Entity, primitive: usize, from: &[VertexBlend], ) -> Result<(), String>

Why World::blend_vertices would refuse, without changing anything: a pass checks every entity before it changes any.

pub fn remove_mesh(&mut self, e: Entity) -> Result<Vec<&'static str>, String>

Take e’s mesh away with every component describing it (each typed component whose Component::GEOMETRY says it holds something per primitive or vertex) and its file link (core.mesh_file, which a load would restore it from): for an entity left drawing nothing, whose per-primitive data would describe no primitive, or one whose geometry another replaces (select-lod). A mesh still only in its file (core.mesh_file without core.mesh, as a world is before its load) goes the same way, with the per-primitive data describing it. Returns the names taken, the mesh’s first; none when e has neither. Refused, changing nothing, while e has an opaque component (World::check_remove_mesh).

pub fn check_remove_mesh(&self, e: Entity) -> Result<(), String>

Why World::remove_mesh would refuse e, so a pass can check every entity before it changes any: an opaque component on it, as World::remap_primitives refuses a change to the primitives then (whether it describes primitives can’t be known).

pub fn per_vertex_components(&self, e: Entity) -> Vec<&'static str>

The names of e’s typed components that hold something per vertex of its mesh (Geometry::PerVertex), in name order: what a pass that joins primitives into one (whose vertices a source primitive’s per-vertex data does not cover) must refuse, since Component::remap_vertices maps only one source primitive’s vertices.

pub fn copy_components(&mut self, from: Entity, to: Entity) -> bool

Every component of from, typed and opaque, copied onto to, replacing to’s of the same name (to keeps the others): for a pass that makes another entity like one it knows only partly (a prototype per tint row, keeping whatever dialect data the reader attached). References are copied as they are. False, and nothing changed, unless both are alive and differ.

pub fn rebuild_primitives( &mut self, e: Entity, f: impl FnOnce(&Mesh) -> Result<(Vec<Primitive>, Vec<usize>), String>, ) -> Result<(), String>

Rebuild e’s mesh primitives: f returns the new primitives and, for each, the old primitive it comes from (a source may repeat or be absent, as for World::remap_primitives). The new mesh and every per-primitive component change together, or, when f fails or a component cannot follow, nothing does. The one way to change a mesh’s primitive list.

pub fn edit_mesh( &mut self, e: Entity, f: impl FnOnce(&mut Mesh) -> Result<Option<Vec<usize>>, String>, ) -> Result<bool, String>

Edit e’s mesh with f, which may also rebuild its primitive list: f returns None when the list keeps its primitives in order (edited in place at most: the mesh stays the same mesh, whatever f built to hold them), else, for each primitive now, the one it comes from, as World::rebuild_primitives (per-primitive components follow, and the conservation diagnostics count the rebuild exactly). False when e has no mesh.

All or nothing: when f fails, its mapping is malformed, or a per-primitive component can’t follow it, the mesh and its components are as they were (the mesh is kept while f runs, to put back), and the error says why.

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

pub fn next_index(&self) -> u32

The index the next spawned entity gets: an entity with an index at or above it was made after this call (ids are handed out in order and never reused; a part loaded with World::subset keeps its planning world’s, so what a pass makes in it is told from what was loaded).

pub fn reserve_indices_before(&mut self, next: u32)

Reserve every index below next without creating entities. A freshly re-read subset that will be absorbed into a newer World uses that World’s next_index, so passes cannot reuse its other entities’ ids. Never rewinds the allocator or changes which entities are alive.

pub fn references(&self, e: Entity) -> Vec<Entity>

The entities e‘s components refer to (not its resources’), in no particular order, repeats possible.

pub fn unreferenced(&self) -> BTreeSet<Entity>

The entities nothing in the world refers to (through any entity’s components): its independent content, placements, markers, standalone soups, rather than the prototypes, materials and textures they reach.

pub fn closure( &self, roots: impl IntoIterator<Item = Entity>, ) -> BTreeSet<Entity>

roots and every alive entity they reach through Component::references, transitively. Opaque components declare no references: an entity’s opaque components travel with it in World::subset, but nothing they may name is followed.

pub fn subset(&self, keep: &BTreeSet<Entity>) -> World

A world of only keep’s entities (those alive) with all their components, typed and opaque, under the same ids, and every resource (forgetting its references to entities left out). Entities spawned in it get ids above every id of self.

For a selection that keeps everything the world’s render graph draws with: one that leaves some of it out drops what World::part states, and panics naming it (take that part with World::part and count it).

pub fn part(&self, keep: &BTreeSet<Entity>) -> Part

World::subset’s world, and what it dropped to stay whole: the render graph’s steps that drew with an entity left out, and the step bindings and step draws naming draws only they made (Dropped).

pub fn split_off(&mut self, keep: &BTreeSet<Entity>) -> World

Move keep’s entities (those alive), with all their components, out into a world of their own: what World::subset copies, without copying. The part has every resource (copied, as a subset’s) and spawns ids above every id of self, as a subset does; World::absorb moves it back. This world’s resources keep their references to the moved entities, which come back with the part.

A loss is data that leaves the world and does not arrive. The part’s render graph is a copy, and this world keeps every step: the steps pruned from the copy (they draw with entities the part lacks) are not a loss, and World::split_part counts them. The step bindings and step draws stripped from the moved entities (they named draws only those steps made) leave with the entities and do not come back on World::absorb: a loss, and split_off panics naming it (take the part with World::split_part and count it).

pub fn split_part(&mut self, keep: &BTreeSet<Entity>) -> Part

World::split_off’s part, and what it dropped to stay whole (World::part). The render graph steps in it are pruned from the part’s copy (this world keeps them all): counted, not a loss. The step bindings and step draws in it were stripped from the moved entities: a loss (World::split_off), since absorbed back the entities hold none of them.

pub fn absorb(&mut self, part: World) -> Result<(), IdError>

Move every entity of part (a World::split_off of this world) back in, with its components; part’s resources are dropped. Ids the part spawned and despawned again were never alive here and are not reserved, so a split, written and absorbed part leaves this world as it was. An entity of part that is alive here is an error, and so is an id with none after it; either changes nothing.

pub fn retain(&mut self, keep: &BTreeSet<Entity>)

Despawn every entity outside keep: in place, what World::subset copies.

pub fn entities(&self) -> impl DoubleEndedIterator<Item = Entity> + '_

Alive entities in ascending order.

pub fn entity_count(&self) -> usize

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

Attach (or replace) a component. Panics if the entity is not alive: attaching to a dead entity is a bug. Replacing a value an entity keeps is an in-place edit to the pass manager, as through World::get_mut: declared in crate::pass::Pass::modifies, not checked.

pub fn try_insert<T: Component>( &mut self, e: Entity, value: T, ) -> Result<Option<T>, NameClash>

World::insert for a name that may be taken: a clash (another type, a resource or an opaque component holds the name) is an error and changes nothing, whichever of the two came first. For a reader that puts what a file names in the world; World::insert is for a name the program chose and a clash there is its bug.

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

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

pub fn get_shared<T: Component>(&self, e: Entity) -> Option<Arc<T>>

e’s T as a shared handle: the world’s own value, not a copy (Column::get_shared). A later write to it through the world copies it first, so the handle keeps what it was given; a holder that only reads (a renderer uploading a texture) keeps the bytes without a second copy.

pub fn remove_shared<T: Component>(&mut self, e: Entity) -> Option<Arc<T>>

e’s T taken out as the shared handle: the world’s own value, never a copy, where World::remove copies a value something else still shares. For a holder of World::get_shared handles that takes over their keeping (a renderer that releases a texture’s levels once its image is on the GPU): the bytes go when the last handle does.

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

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

pub fn column<T: Component>(&self) -> Option<&Column<T>>

The column of T, if any entity ever had one.

pub fn column_mut<T: Component>(&mut self) -> Option<ColumnMut<'_, T>>

Mutable access to the values of T (entities cannot be added or removed through it).

pub fn columns2_mut<A: Component, B: Component>( &mut self, ) -> (Option<ColumnMut<'_, A>>, Option<ColumnMut<'_, B>>)

Two different columns at once, e.g. writing B while reading A of the same entities. Panics if A and B are the same type.

pub fn iter<T: Component>( &self, ) -> impl DoubleEndedIterator<Item = (Entity, &T)>

Entities with T, in ascending order.

pub fn iter2<A: Component, B: Component>( &self, ) -> impl Iterator<Item = (Entity, &A, &B)>

Entities with both A and B, in ascending order.

pub fn component_names(&self) -> Vec<&str>

Names of every component kind present (typed and opaque), sorted.

pub fn has_component_named(&self, name: &str) -> bool

Whether any entity has a component of this name (typed or opaque).

pub fn entities_named(&self, name: &str) -> Vec<Entity>

Entities that have a component of this name (typed or opaque), ascending.

pub fn verify_components(&self) -> Vec<(&'static str, Entity, String)>

Every typed component’s Component::verify, and that each entity it refers to (Component::references) is alive: (component name, entity, message) for each failure, by name then entity.

pub fn verify_resources(&self) -> Vec<(&'static str, String)>

Every typed resource’s Resource::verify, and that each entity it refers to is alive: (resource name, message) for each failure, by name.

pub fn payload_bytes(&self) -> BTreeMap<&str, u64>

Bulk payload bytes by component name, for the names that hold any: typed components’ Component::payload_bytes and opaque byte payloads.

pub fn component_names_of(&self, e: Entity) -> Vec<&str>

Names of the components (typed and opaque) this entity has, sorted.

pub fn entity_has_named(&self, e: Entity, name: &str) -> bool

Whether this entity has a component of this name (typed or opaque).

pub fn components_json( &self, e: Entity, ) -> Result<Vec<ComponentJson<'_>>, ComponentJsonError>

Every component of an entity as JSON, sorted by name: typed ones through Component::to_json, opaque JSON ones as they are. Components without a JSON view (opaque bytes, typed ones that are not shown) are listed with None, so callers can count them.

Fails, naming the component and the entity, when a view would lose a value (a non-finite float).

pub fn resources_json( &self, ) -> Result<Vec<ComponentJson<'_>>, ComponentJsonError>

Every resource (typed and opaque) as JSON, sorted by name; as World::components_json.

pub fn visit_components_debug( &self, f: &mut dyn FnMut(&str, u32, Entity, &dyn Debug), )

Every component (typed and opaque) with its schema version, for debugging tools: f(name, version, entity, value), by name then entity. Values are shown through Debug, which is not a format: its text may change between builds and toolchains, so nothing that is gated, cached or compared across builds may depend on it.

pub fn visit_resources_debug(&self, f: &mut dyn FnMut(&str, u32, &dyn Debug))

Every resource (typed and opaque) with its schema version, by name, through Debug; as World::visit_components_debug, for debugging tools only.

pub fn insert_opaque( &mut self, e: Entity, name: &str, value: Opaque, ) -> Result<Option<Opaque>, NameClash>

Attach a component this build does not model. A name a typed component or a resource holds (in this world so far) is an error and changes nothing: a reader that knows the type must decode it. A typed insert of a name held here by an opaque component is refused the same way (World::try_insert).

pub fn get_opaque(&self, e: Entity, name: &str) -> Option<&Opaque>

pub fn remove_opaque(&mut self, e: Entity, name: &str) -> Option<Opaque>

pub fn opaque_components( &self, ) -> impl Iterator<Item = (&str, &BTreeMap<Entity, Opaque>)>

Every opaque component kind with its values, by name then entity.

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

Insert (or replace) a resource. Panics if a component has its name: a name is a component’s or a resource’s, not both, so pass declarations, which list both, stay unambiguous. World::try_insert_resource refuses instead.

pub fn try_insert_resource<T: Resource>( &mut self, value: T, ) -> Result<Option<T>, NameClash>

World::insert_resource for a name that may be taken: a component’s name is an error and changes nothing.

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

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

Borrowed to write: a pass that does declares the name in crate::pass::Pass::modifies.

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

Lend resource T read-only to f while f changes the rest of the world, then put it back as it was: a borrow, not a write, so the pass manager records none. f gets None when the world holds no T. Panics if f puts a T of its own into the world while one is lent: the one lent is the one that goes back.

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

pub fn insert_opaque_resource( &mut self, name: &str, value: Opaque, ) -> Result<Option<Opaque>, NameClash>

As World::try_insert_resource, for a resource this build does not model: a component’s name is an error.

pub fn resource_names(&self) -> Vec<&str>

Names of every resource (typed and opaque), sorted.

pub fn opaque_resources(&self) -> impl Iterator<Item = (&str, &Opaque)>

Trait Implementations

impl Clone for World

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for World

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

Formats the value using the given formatter.

impl Default for World

fn default() -> Self

Returns the “default value” for a type.