Prefabs are entities that can be used as templates for other entities. They can provide a convenient API for creating assets natively in the ECS. Prefabs have the following features:
Prefab components can be shared across instances
Inherited components can be overridden on a per-instance basis
Inherited components can be auto-overridden on a per-prefab basis
Prefab inheritance makes creating variations easy
Prefabs can have children that are instantiated for instances
Prefab children can be easily identified with prefab slots
Prefabs are runtime accessible and modifiable
Prefabs can be mapped to types for easy access in the C++ API
Natively supported by Flecs Script & the JSON serializer
The following example shows how to instantiate a simple prefab:
// Create a spaceship prefab with a Defense component.
let spaceship = world.prefab_named("spaceship").set(Defense { value: 50 });
// Create two prefab instances
let inst_1 = world.entity().is_a_id(spaceship);
let inst_2 = world.entity().is_a_id(spaceship);
// Get instantiated component
inst_1.get::<&Defense>(|defense| {
println!("Defense value: {}", defense.value);
});
The following sections go over the different aspects of the prefab feature.
The Prefab tag
Prefabs are regular entities with as only difference that prefabs by default are not matched by queries. This allows prefab entities to coexist with regular entities in the same world without impacting game logic. The mechanism used to exclude prefabs from queries is a builtin Prefab tag. The following example shows how to create a prefab:
let myprefab = world.entity().add::<flecs::Prefab>();
// or the shortcut
let myprefab = world.prefab();
Queries don't match prefab entities unless the Prefab tag is explicitly queried for. The following example shows how to match only prefabs by adding the Prefab tag to a query:
Prefabs are only ignored by queries when they are matched on the $this variable, which is the default for query terms. If a prefab component is matched through query traversal, a fixed term source or variable non-$this source, the query will not ignore the prefab.
To match both regular and prefab entities, make the prefab term optional:
Instead of an optional term, queries can also specify a MatchPrefabs flag. This matches the same entities as an optional term, but since the term doesn't need to populate a field slightly improves performance:
Entities can inherit components from prefabs. Inherited components are only stored once in memory, and shared across instances. This can be useful for static data that's shared across instances, such as material data, textures or meshes.
For a component to be inheritable, it needs to have the (OnInstantiate, Inherit) trait (for more details see the ComponentTraits manual). The following example shows what happens when a prefab with one inheritable and one non-inheritable component is instantiated:
When an instance inherits a component from a prefab, it can be overridden with a value that's specific to the instance. To override a component, simply add or set it on the instance. The following example shows how:
let spaceship = world.prefab().set(Defense { value: 50 });
// Create prefab instance
let inst_a = world.entity().is_a_id(spaceship);
let inst_b = world.entity().is_a_id(spaceship);
// Override Defense only for inst_a
inst_a.set(Defense { value: 75 });
When a component is overridden by adding it to an instance, the component on the instance is initialized with the value from the prefab component. An example:
let spaceship = world.prefab().set(Defense { value: 50 });
// Create prefab instance
let inst_a = world.entity().is_a_id(spaceship);
let inst_b = world.entity().is_a_id(spaceship);
// Override Defense only for inst_a
inst_a.add::<Defense>(); // Initialized with value 50
When an override is removed, the original value of the prefab is reexposed.
Auto Overriding
When a component is configured to be inheritable, sometimes it can still be useful for a specific prefab to have the instances always own the component. This can be achieved with an auto override, which flags a component on the prefab to be always overridden on instantiation:
let spaceship = world.prefab().set_auto_override(Defense { value: 50 }); // Set & auto override Defense
// Create prefab instance
let inst = world.entity().is_a_id(spaceship);
inst.owns::<Defense>(); // true
Auto overrides can also be added to prefabs that don't have the actual component. In this case the component is not copied from the prefab (there is nothing to copy), but is added & default constructed on the instance.
This also works for prefab children. Adding an auto override to a child entity without adding the component will add & default construct the component on the instance child.
Prefab Variants
Prefabs can inherit from each other to create prefab variations without duplicating the prefab data. The following example shows a prefab and a prefab variant.
When a prefab has children, the entire subtree of a prefab is copied to the instance. Other than with the instance itself where components can be inherited from a prefab, child entities never inherit components from prefab children. Prefab hierarchies are created in the same way as entity hierarchies:
let cockpit = world.prefab_named("Cockpit").child_of_id(spaceship);
// Instantiate the prefab hierarchy
let inst = world.entity().is_a_id(spaceship);
// Lookup instantiated child
let inst_cockpit = inst.lookup("Cockpit");
Prefab Slots
When a prefab hierarchy is instantiated often code will want to refer to a specific instantiated child. A typical example is a turret prefab with a turret head that needs to rotate.
While it is possible to lookup a child by name and store it on a component, this adds boilerplate and reduces efficiency. Prefab slots make this easier.
A prefab child can be created as a slot. Slots are created as relationships on the instance, with as target of the relationship the instantiated child. The slot is added as a union relationship which doesn't fragment archetypes.
The following example shows how to create and use a prefab slot:
let cockpit = world.prefab_named("Cockpit").child_of_id(spaceship).slot(); // Defaults to (SlotOf, spaceship)
// Instantiate the prefab hierarchy
let inst = world.entity().is_a_id(spaceship);
// Lookup instantiated child
let inst_cockpit = inst.target_id(cockpit, 0);
Prefab Types (C++, C#)
Like entities and components, prefabs can be associated with a C++ type. This makes it easier to instantiate prefabs as it is not necessary to pass prefab handles around in the application. The following example shows how to associate types with prefabs:
struct SpaceShip {};
// Create prefab associated with the SpaceShip type
