hecs

The ChangeTracker<T> provides a way to detect when components of type T have been added, modified, or removed from entities in a World.

Usage Requirements

• Component Constraints: The component T must implement Component, Clone, and PartialEq.
• Single Tracker Rule: Always use exactly one ChangeTracker per World per component type. Using multiple trackers for the same type on the same world, or sharing a tracker across multiple worlds, will cause unpredictable results.
• Performance Note: This mechanism works by inserting a private Previous<T> component to store the last known state. It is best suited for components that are fast to Clone and PartialEq. For expensive components, consider manual change tracking (e.g., via a flag in DerefMut).

Workflow

1. Create a tracker using ChangeTracker::new().
2. Call tracker.track(&mut world) to obtain a Changes object.
3. Iterate over the desired change sets (added(), changed(), or removed()) using the Changes object.
4. The Changes object must be dropped (e.g., by letting it go out of scope) to finalize the tracking state and update the internal Previous<T> components.

To iterate over entities and components, use World::query::<Q>(). This returns a QueryBorrow which provides access to the data. You can use .iter() for standard iteration, .view() for random access, or .iter_batched(batch_size) to distribute work across threads.

Common query types include:

• (Entity, &T, &mut U): A tuple of components and the entity ID.
• Option<T>: An optional component (returns None if the entity lacks T).
• Or<L, R>: Matches either query L or query R.
• With<Q, R>: Matches query Q only if the entity also satisfies R.
• Without<Q, R>: Matches query Q only if the entity does not satisfy R.
• Satisfies<Q>: Matches all entities, yielding true if they satisfy Q and false otherwise. This is faster than Option<Q> for checking existence because it doesn't borrow components.

let mut world = World::new();
let a = world.spawn((123, true, "abc"));
let b = world.spawn((456, false));
let c = world.spawn((42, "def"));

// Example: Using With to filter
let entities = world.query::<With<(Entity, &i32), &bool>>()
    .iter()
    .map(|(e, i)| (e, i))
    .collect::<Vec<_>>();

// Example: Using Satisfies for fast existence checks
let entities = world.query::<(Entity, Satisfies<&bool>)>()
    .iter()
    .collect::<Vec<_>>();

The EntityBuilder allows you to incrementally add components to a bundle before spawning an entity in the World. This is useful for constructing complex entities step-by-step.

Key behaviors:

• Replacement: If you add a component of a type T that is already in the builder, the old component is dropped and replaced by the new one.
• Reuse: You can reuse the same builder instance by calling .build() to get a BuiltEntity, which can then be passed to world.spawn(). The builder is cleared implicitly when built, making it ready for the next entity.
• Access: You can check for component existence with .has::<T>() or borrow components using .get::<T>() (shared) and .get_mut::<T>() (unique) during the building process.

# use hecs::*;
let mut world = World::new();
let mut builder = EntityBuilder::new();
builder.add(123).add("abc");
let e = world.spawn(builder.build()); // builder can now be reused
assert_eq!(*world.get::<&i32>(e).unwrap(), 123);
assert_eq!(*world.get::<&&str>(e).unwrap(), "abc");

If you need to spawn multiple entities with the exact same set of components, use EntityBuilderClone. Unlike the standard EntityBuilder, which is consumed or cleared upon building, EntityBuilderClone produces a BuiltEntityClone that can be cloned and used to spawn many entities.

Key behaviors:

• Clonable Components: Only components that implement Clone can be added via .add().
• Repeated Spawning: The output of .build() is a BuiltEntityClone. Because &BuiltEntityClone implements DynamicBundle, you can pass a reference to it to world.spawn() multiple times.

Note: EntityBuilderClone does not perform dynamic borrow checking during the building phase.

# use hecs::*;
let mut world = World::new();
let mut builder = EntityBuilderClone::new();
builder.add(123).add("abc");
let bundle = builder.build();
let e = world.spawn(&bundle);
let f = world.spawn(&bundle); // `&bundle` can be used many times
assert_eq!(*world.get::<&i32>(e).unwrap(), 123);
assert_eq!(*world.get::<&&str>(e).unwrap(), "abc");
assert_eq!(*world.get::<&i32>(f).unwrap(), 123);
assert_eq!(*world.get::<&&str>(f).unwrap(), "abc");

hecs is a minimalist Entity-Component-System (ECS). Instead of a rigid 'System' abstraction, you use a World to spawn entities with various components and query them using standard Rust loops. Any type can be used as a component with zero boilerplate.

To use hecs:

1. Create a World using World::new().
2. Spawn entities with world.spawn((component1, component2, ...)).
3. Query entities using world.query_mut::<(&mut Type1, &Type2)>() for mutable access or world.query_shared::<(&Type1, &Type2)>() for read-only access.
4. Access specific components of an entity using world.get::<&Type>(entity).

use hecs::*;
let mut world = World::new();

// Spawn entities with components
let a = world.spawn((123, true, "abc"));
let b = world.spawn((42, false));

// Systems are simple for loops using queries
for (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);