Vkm::Engine::Prefab Namespace Reference

Entity subtrees saved once and instanced many times. More...

Typedefs
using	BuiltSlots = std::map<uint32_t, uint32_t>
	Where one instance's built entities stand: prefab uid to slot.
using	InstanceSlots = std::map<uint32_t, BuiltSlots>
	Every instance's BuiltSlots, keyed by the slot its root holds.

Functions
EntityId	instanceRootOf (const Scene &scene, EntityId id)
	The root of the prefab instance id belongs to: itself, or its nearest ancestor carrying PrefabInstance.
bool	isInsideInstance (const Scene &scene, EntityId id)
	Is id inside (but not the root of) a prefab instance?
bool	save (Scene &scene, EntityId root, const std::string &path, const ResourceManager &resources)
	Write root and its descendants to path as a prefab.
bool	definesComponent (const std::string &path, uint32_t uid, const std::string &component)
	Does the prefab at path define component on the entity uid names?
BuiltSlots	builtSlotsOf (const Scene &scene, EntityId root)
	Where the instance rooted at root put each of its entities.
InstanceSlots	instanceSlotsOf (const Scene &scene)
	builtSlotsOf for every instance in scene.
EntityId	instantiate (Scene &scene, ResourceManager &resources, const std::string &path, const Transform &at)
	Instantiate path into scene, placing the root at at.
EntityId	instantiate (Scene &scene, ResourceManager &resources, const std::string &path)
	Instantiate at the prefab's own authored pose.
bool	instantiateInto (Scene &scene, ResourceManager &resources, const std::string &path, EntityId root, const std::vector< PrefabOverride > &overrides={}, std::set< std::string > *drift=nullptr, const BuiltSlots *slots=nullptr)
	Build a prefab into an entity that already exists.
bool	reloadComponent (Scene &scene, ResourceManager &resources, const std::string &path, EntityId entity, uint32_t uid, const std::string &component, const std::vector< PrefabOverride > &overrides)
	Re-read one component of one instance entity from the prefab.

Detailed Description

Entity subtrees saved once and instanced many times.

A prefab is a scene fragment, one entity and its descendants, in its own file. Instances are built fresh on each scene load, so editing the prefab changes them all. A scene stores an instance as a reference, the root's Transform and its overrides.

Referenced by path, not through the AssetLibrary: nothing cooks them. Each file carries a scene's assets block, so it can be instantiated into a scene that never held its meshes. Every entry point reports an unusable document and returns rather than throwing. Overrides: docs/reference/io.md, "Per-instance overrides".

Typedef Documentation

BuiltSlots

using Vkm::Engine::Prefab::BuiltSlots = std::map<uint32_t, uint32_t>

Where one instance's built entities stand: prefab uid to slot.

A scene file does not keep it: a load builds an instance into whatever slots are free, and a history addressing entities by slot then addresses others. A rebuild handed this puts each entity back.

InstanceSlots

using Vkm::Engine::Prefab::InstanceSlots = std::map<uint32_t, BuiltSlots>

Every instance's BuiltSlots, keyed by the slot its root holds.

Comparable, so a caller that rebuilt a world can ask whether it came back exactly.

Function Documentation

instanceRootOf()

EntityId Vkm::Engine::Prefab::instanceRootOf	(	const Scene &	scene,
		EntityId	id )

The root of the prefab instance id belongs to: itself, or its nearest ancestor carrying PrefabInstance.

Walks up, so descendants carry no bookkeeping that could fall out of sync.

Parameters

scene	Scene holding the entity.
id	Entity to resolve.

Returns

The instance root, or a null id when id is not part of one.

isInsideInstance()

bool Vkm::Engine::Prefab::isInsideInstance	(	const Scene &	scene,
		EntityId	id )

Is id inside (but not the root of) a prefab instance?

Parameters

scene	Scene holding the entity.
id	Entity to test.

Returns

True when an ancestor of id carries PrefabInstance.

save()

bool Vkm::Engine::Prefab::save	(	Scene &	scene,
		EntityId	root,
		const std::string &	path,
		const ResourceManager &	resources )

Write root and its descendants to path as a prefab.

The root's Transform is saved as the authored pose; an instance replaces it. path is stored on the root verbatim, so a project-relative one stays portable. The subtree becomes an instance of the file, its overrides dropped.

Parameters

scene	Scene holding the subtree.
root	Entity whose subtree becomes the prefab.
path	Destination file, project-relative or absolute.
resources	Resolves asset handles to names.

Returns

True on success; false if the entity is dead, the subtree touches another instance, or the write fails.

definesComponent()

bool Vkm::Engine::Prefab::definesComponent	(	const std::string &	path,
		uint32_t	uid,
		const std::string &	component )

Does the prefab at path define component on the entity uid names?

Answers whether an override addressing that pair could ever apply. Reads the file per call.

Parameters

path	Prefab file to read.
uid	Entity identity inside the prefab.
component	Component key, as SceneSerializer writes it.

Returns

True when the prefab holds that entity and that component on it.

builtSlotsOf()

BuiltSlots Vkm::Engine::Prefab::builtSlotsOf	(	const Scene &	scene,
		EntityId	root )

Where the instance rooted at root put each of its entities.

Parameters

scene	Scene holding the instance.
root	Instance root; itself not listed, since its slot is its own.

Returns

Each entity below root carrying a PrefabEntity, by uid.

instanceSlotsOf()

InstanceSlots Vkm::Engine::Prefab::instanceSlotsOf

(

const Scene &

scene

)

builtSlotsOf for every instance in scene.

Parameters

scene

Scene to read.

Returns

One entry per PrefabInstance, by the slot of its root.

instantiate() [1/2]

EntityId Vkm::Engine::Prefab::instantiate	(	Scene &	scene,
		ResourceManager &	resources,
		const std::string &	path,
		const Transform &	at )

Instantiate path into scene, placing the root at at.

Parameters

scene	Scene to build into.
resources	Resolves asset names to handles.
path	Prefab file to read.
at	Pose for the instance root; the prefab's authored Transform is replaced by it.

Returns

The instance root, or a default (invalid) EntityId on failure.

instantiate() [2/2]

EntityId Vkm::Engine::Prefab::instantiate	(	Scene &	scene,
		ResourceManager &	resources,
		const std::string &	path )

Instantiate at the prefab's own authored pose.

The root is marked as a PrefabInstance of path, so the scene stores a reference to the file rather than the expanded entities.

Parameters

scene	Scene to build into.
resources	Resolves asset names to handles.
path	Prefab file to read, project-relative or absolute.

Returns

The instance root, or a default (invalid) EntityId on failure.

instantiateInto()

bool Vkm::Engine::Prefab::instantiateInto	(	Scene &	scene,
		ResourceManager &	resources,
		const std::string &	path,
		EntityId	root,
		const std::vector< PrefabOverride > &	overrides = {},
		std::set< std::string > *	drift = nullptr,
		const BuiltSlots *	slots = nullptr )

Build a prefab into an entity that already exists.

For a caller restoring entities at their saved slots: a root the prefab allocated would take a slot another entity is waiting for. root receives the prefab root's components and children, and keeps its own Transform.

The caller marks root as a PrefabInstance, so the overrides sit on it before the build; unmarked, the next save writes the result inline.

Parameters

scene	Scene to build into.
resources	Resolves asset names to handles.
path	Prefab file to read.
root	Existing entity to become the instance root.
overrides	Per-instance field deltas, addressed by PrefabEntity uid.
drift	Optional: one message per override the prefab no longer has a home for; the override is kept.
slots	Optional: an earlier build's slots; an entity whose slot is still free is built back into it.

Returns

True if the prefab was read and built.

reloadComponent()

bool Vkm::Engine::Prefab::reloadComponent	(	Scene &	scene,
		ResourceManager &	resources,
		const std::string &	path,
		EntityId	entity,
		uint32_t	uid,
		const std::string &	component,
		const std::vector< PrefabOverride > &	overrides )

Re-read one component of one instance entity from the prefab.

An instance's component is the prefab's value patched by its overrides, so dropping an override is a re-read, not an undo. Only component is touched. Reads the file per call, so not for a per-frame path.

Parameters

scene	Scene holding the entity.
resources	Resolves asset names to handles.
path	Prefab the instance was built from.
entity	Entity receiving the component.
uid	That entity's identity inside the prefab.
component	Component key, as SceneSerializer writes it.
overrides	Every override on the instance; only this uid's apply.

Returns

True when the prefab defines the component and it was loaded; false for the root's Transform, which is the instance's own pose.