Crate hecs

Expand description

A handy ECS

hecs provides a high-performance, minimalist entity-component-system (ECS) world. It is a library, not a framework. In place of an explicit “System” abstraction, a World’s entities are easily queried from regular code. Organize your application however you like!

In order of importance, hecs pursues:

fast traversals
a simple interface
a small dependency closure
exclusion of externally-implementable functionality

let mut world = World::new();
// Nearly any type can be used as a component with zero boilerplate
let a = world.spawn((123, true, "abc"));
let b = world.spawn((42, false));
// Systems can be simple for loops
for (id, (number, &flag)) in world.query_mut::<(&mut i32, &bool)>() {
  if flag { *number *= 2; }
}
// Random access is simple and safe
assert_eq!(*world.get::<&i32>(a).unwrap(), 246);
assert_eq!(*world.get::<&i32>(b).unwrap(), 42);

Modules§

serialize: Convenience tools for serializing Worlds

Structs§

Archetype: A collection of entities having the same component types
ArchetypeColumn: Shared reference to a single column of component data in an Archetype
ArchetypeColumnMut: Unique reference to a single column of component data in an Archetype
ArchetypesGeneration: Determines freshness of information derived from World::archetypes
Batch: A sequence of entities yielded by BatchedIter
BatchIncomplete: Error indicating that a ColumnBatchBuilder was missing components
BatchWriter: Handle for appending components
BatchedIter: Batched version of QueryIter
BuiltEntity: The output of an EntityBuilder, suitable for passing to World::spawn or World::insert
BuiltEntityClone: A collection of components that implement Clone
ChangeTracker: Helper to track changes in T components
Changes: Collection of iterators over changes in T components
ColumnBatch: A collection of component data for entities with the same component types
ColumnBatchBuilder: An incomplete collection of component data for entities with the same component types
ColumnBatchType: A collection of component types
CommandBuffer: Records operations for future application to a World
Entity: Lightweight unique ID, or handle, of an entity
EntityBuilder: Helper for incrementally constructing a bundle of components with dynamic component types
EntityBuilderClone: Variant of EntityBuilder that clones components on use
EntityRef: Handle to an entity with any component types
Iter: Iterator over all of a world’s entities
MissingComponent: Error indicating that an entity did not have a required component
NoSuchEntity: Error indicating that no entity with a particular ID exists
PreparedQuery: A prepared query can be stored independently of the World to amortize query set-up costs.
PreparedQueryBorrow: Combined borrow of a PreparedQuery and a World
PreparedQueryIter: Iterates over all entities matching a PreparedQuery
PreparedView: Provides random access to the results of a prepared query
QueryBorrow: A borrow of a World sufficient to execute the query Q
QueryIter: Iterator over the set of entities with the components in Q
QueryMut: A query builder that’s convertible directly into an iterator
QueryOne: A borrow of a World sufficient to execute the query Q on a single entity
Ref: Shared borrow of an entity’s component
RefMut: Unique borrow of an entity’s component
Satisfies: A query that matches all entities, yielding bools indicating whether each satisfies query Q
SpawnBatchIter: Entity IDs created by World::spawn_batch
SpawnColumnBatchIter: Iterator over Entitys spawned by World::spawn_column_batch()
TakenEntity: An entity removed from a World
View: Provides random access to the results of a query
ViewBorrow: A borrow of a World sufficient to random-access the results of the query Q.
With: Transforms query Q by skipping entities not satisfying query R
Without: Transforms query Q by skipping entities satisfying query R
World: An unordered collection of entities, each having any number of distinctly typed components

Enums§

Access: Type of access a Query may have to an Archetype
ComponentError: Errors that arise when accessing components
Or: Holds an L, or an R, or both
QueryOneError: Errors that arise when querying a single entity

Traits§

Bundle: A statically typed collection of components
Component: Types that can be components, implemented automatically for all Send + Sync + 'static types
ComponentRef: &T or &mut T where T is some component type
ComponentRefShared: &T where T is some component type
DynamicBundle: A dynamically typed collection of components
DynamicBundleClone: A dynamically typed collection of cloneable components
Query: A collection of component types to fetch from a World
QueryShared: Marker trait indicating whether a given Query will not produce unique references

Functions§

bundle_satisfies_query: Checks if a query is satisfied by a bundle. This is primarily useful for unit tests.
dynamic_bundle_satisfies_query: Checks if a query is satisfied by a dynamic bundle. For static bundles, see bundle_satisfies_query. This is primarily useful for unit tests.

Derive Macros§

Bundle: Implement Bundle for a struct
DynamicBundleClone: Implement DynamicBundleClone for a struct.
Query: Implement Query for a struct