Crate hecs

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
• 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
• 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

Derive Macros

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