superdex::prefab Namespace Reference

Classes
struct	ActorContactEntry
	Used by ContactFilter to enable or disable contact for a pair of actors. More...
struct	ActorLists
	Lists of actors grouped by type. More...
struct	AddToSceneResult
	Struct used to return all created actors and constraints from AddToScene. More...
struct	Articulated3dRotationRangeConstraintPrefab
	Prefab parameters for a Articulated3dRotationRangeConstraintParams. More...
struct	Articulated3dRotationTargetConstraintPrefab
	Prefab parameters for a Articulated3dRotationTargetConstraintParams. More...
struct	ArticulatedActorPrefab
	Prefab parameters for an articulated actor. More...
struct	ArticulatedJointPrefab
	Joint parameters for an articulated actor prefab. More...
struct	ArticulatedLinkPrefab
	Link parameters for an articulated actor prefab. More...
struct	ArticulatedSingleDofRangeConstraintPrefab
	Prefab parameters for a ArticulatedSingleDofRangeConstraintParams. More...
struct	ArticulatedSingleDofTargetConstraintPrefab
	Prefab parameters for a ArticulatedSingleDofTargetConstraintParams. More...
struct	ArticulatedSkinPrefab
	Skin parameters for an articulated actor prefab. More...
struct	ConstraintLists
	Lists of constraints grouped by type. More...
struct	ContactFilter
	Contact filtering parameters for a prefab. More...
struct	DeformableNodePositionConstraintPrefab
	Prefab parameters for a DeformableNodePositionConstraintParams. More...
struct	DeformableNodeToDeformableNodeConstraintPrefab
	Prefab parameters for a DeformableNodeToDeformableNodeConstraintParams. More...
struct	DeformableNodeToRigidConstraintPrefab
	Prefab parameters for a DeformableNodeToRigidConstraintParams. More...
struct	JointRotationRangeConstraintPrefab
	Prefab parameters for a JointRotationRangeConstraintParams. More...
struct	JointRotationTrackingConstraintPrefab
	Prefab parameters for a JointRotationTrackingConstraintParams. More...
struct	LayerContactEntry
	Used by ContactFilter to enable or disable contact for a pair of layers. More...
struct	PoseControllerPrefab
	Prefab parameters for an articulated pose controller. More...
struct	PrefabParams
	Parameters for instantiating a ScenePrefab into a Scene. More...
struct	PrefabReference
	Reference to another prefab file (scene or actor) for prefab nesting. More...
struct	RigidActorPrefab
	Prefab parameters for a rigid actor. More...
struct	RigidPivotPositionConstraintPrefab
	Prefab parameters for a RigidPivotPositionConstraintParams. More...
struct	RigidPivotRotationConstraintPrefab
	Prefab parameters for a RigidPivotRotationConstraintParams. More...
struct	RigidPivotToRigidTargetConstraintPrefab
	Prefab parameters for a RigidPivotToRigidTargetConstraintParams. More...
struct	RigidPrismaticJointConstraintPrefab
	Prefab parameters for a RigidPrismaticJointConstraintParams. More...
struct	RigidSphericalJointConstraintPrefab
	Prefab parameters for a RigidSphericalJointConstraintParams. More...
struct	SceneParams
	Parameters that are global to the Scene in which this prefab will be instantiated. More...
struct	ScenePrefab
	Top-level prefab describing a complete or partial physics scene (possibly just one actor). More...
struct	SoftActorPrefab
	Prefab parameters for a soft actor. More...
struct	SoftSkinnedActorPrefab
	Prefab parameters for a soft skinned actor. More...

Functions
AddToSceneResult	AddToScene (ScenePrefab const &prefab, Scene *scene, Error &error)
	Overload of AddToScene that instantiates a ScenePrefab using default PrefabParams.
AddToSceneResult	AddToScene (ScenePrefab const &prefab, Scene *scene, PrefabParams const &params, Error &error)
	Instantiate a ScenePrefab and add it to a Scene.
AddToSceneResult	AddToScene (std::string_view prefabPath, std::string_view rootPath, Scene *scene, Error &error)
	Overload of AddToScene that loads a prefab from a file and instantiates it using default PrefabParams.
AddToSceneResult	AddToScene (std::string_view prefabPath, std::string_view rootPath, Scene *scene, PrefabParams const &params, Error &error)
	Load a scene prefab from a file and create an instance of it in the Scene.
void	EnsureFullyLoaded (ScenePrefab &prefab, std::string_view rootPath, Context *context, Error &error)
	Ensure that all nested prefabs and shape files are loaded, skipping any that are already loaded.
void	ExportActor (Actor const *actor, std::string_view exportName, std::string_view outputDir, Error &error)
	Export a single actor to a prefab file under outputDir/exportName/<exportName>.mochi_scene.
void	ExportScene (Scene const *scene, std::string_view exportName, std::string_view outputDir, Error &error)
	Export a Scene to a folder containing a prefab file and all generated mesh files.
void	ExportSceneExcluding (Scene const *scene, std::string_view exportName, std::string_view outputDir, Span< ActorHandle const > excludeActors, Error &error)
	Export a Scene to a folder containing a prefab file and all generated mesh files, omitting a caller-provided set of actors.
DynamicString	GetPrefabFullPath (std::string_view inputPath, std::string_view rootForRelativePath, std::string_view prefabFilePath)
	Resolve a path referenced inside a prefab to a full path.
ScenePrefab	LoadFromFile (std::string_view prefabPath, std::string_view rootPath, Context *context, Error &error)
	Fully load a ScenePrefab from a file, including all nested prefabs and shapes.
ScenePrefab	LoadFromJsonString (std::string_view json, std::string_view rootPath, Context *context, Error &error)
	Fully load a ScenePrefab from a JSON string, including all nested prefabs and shapes.
void	LoadNestedPrefabs (ScenePrefab &prefab, std::string_view rootPath, Error &error)
	Load nested prefab files recursively.
void	LoadShapes (ScenePrefab &prefab, std::string_view rootPath, Context *context, Error &error)
	Load shape files referenced by prefab and its loaded nested prefabs.
void	SaveToJsonFile (ScenePrefab const &prefab, std::string_view path, Error &error)
	Serialize a ScenePrefab to a JSON file.
DynamicString	SaveToJsonString (ScenePrefab const &prefab, Error &error)
	Serialize a ScenePrefab to a JSON string.
ScenePrefab	ShallowLoadFromFile (std::string_view path, Error &error)
	Deserialize a single ScenePrefab from a file, without loading any nested files.
ScenePrefab	ShallowLoadFromJsonString (std::string_view json, Error &error)
	Deserialize a single ScenePrefab from a JSON string, without loading any nested files.

Function Documentation

AddToScene() [1/4]

AddToSceneResult superdex::prefab::AddToScene ( ScenePrefab const & prefab, Scene * scene, Error & error )

inline

Overload of AddToScene that instantiates a ScenePrefab using default PrefabParams.

Parameters

[in]	prefab	The fully loaded ScenePrefab to instantiate.
[in,out]	Scene	The Scene to add things to.
[in,out]	error	Error status. Check Error::IsOK for success.

Returns

An AddToSceneResult containing pointers to all created actors and constraints.

Warning

This function is not transactional. If it returns an error, the prefab may have been partially instantiated in the scene.

See also

AddToScene

Definition at line 27 of file mochi_prefab_inl.h.

AddToScene() [2/4]

AddToSceneResult superdex::prefab::AddToScene	(	ScenePrefab const &	prefab,
		Scene *	scene,
		PrefabParams const &	params,
		Error &	error )

Instantiate a ScenePrefab and add it to a Scene.

Creates the prefab's actors, constraints, and controllers, applies any scene settings enabled by PrefabParams::applySceneSettings, and applies contact filter entries.

Parameters

[in]	prefab	The fully loaded ScenePrefab to instantiate.
[in,out]	Scene	The Scene to add things to.
[in]	params	Parameters for how and where to instantiate the prefab. Can optionally be omitted in Python.
[in,out]	error	Error status. Check Error::IsOK for success.

Returns

An AddToSceneResult containing pointers to all created actors and constraints.

Note

The prefab must be fully loaded (nested prefabs and shapes) before calling this function. If you're not sure, then call EnsureFullyLoaded.

Warning

This function is not transactional. If it returns an error, the prefab may have been partially instantiated in the scene.

Only supported with PrefabParams::scale = 1. To instantiate at a non-identity scale, use the file-path AddToScene overload or a nested PrefabReference::scale.

See also

LoadFromFile, EnsureFullyLoaded, PrefabParams

AddToScene() [3/4]

AddToSceneResult superdex::prefab::AddToScene ( std::string_view prefabPath, std::string_view rootPath, Scene * scene, Error & error )

inline

Overload of AddToScene that loads a prefab from a file and instantiates it using default PrefabParams.

Parameters

[in]	prefabPath	File path to the prefab file.
[in]	rootPath	Root directory for resolving relative paths, except those resolved against a prefab file.
[in,out]	Scene	The Scene to add things to.
[in,out]	error	Error status. Check Error::IsOK for success.

Returns

An AddToSceneResult containing pointers to all created actors and constraints.

Warning

This function is not transactional. If it returns an error, the prefab may have been partially instantiated in the scene.

See also

AddToScene

Definition at line 32 of file mochi_prefab_inl.h.

AddToScene() [4/4]

AddToSceneResult superdex::prefab::AddToScene	(	std::string_view	prefabPath,
		std::string_view	rootPath,
		Scene *	scene,
		PrefabParams const &	params,
		Error &	error )

Load a scene prefab from a file and create an instance of it in the Scene.

This is a convenience function that loads the prefab, including all nested prefabs and shapes, and immediately adds it to the scene. All loaded shape handles are released automatically afterward.

Parameters

[in]	prefabPath	File path to the prefab file.
[in]	rootPath	Root directory for resolving relative paths, except those resolved against a prefab file.
[in,out]	Scene	The Scene to add things to.
[in]	params	Parameters for how and where to instantiate the prefab.
[in,out]	error	Error status. Check Error::IsOK for success.

Returns

An AddToSceneResult containing pointers to all created actors and constraints.

Note

If you intend to add multiple copies of the prefab to a scene, or to multiple scenes, then consider using LoadFromFile to load a ScenePrefab object. You can use that ScenePrefab multiple times.

Unlike the ScenePrefab overload, this overload supports non-identity PrefabParams::scale by baking it into actor geometry during load.

Warning

This function is not transactional. If it returns an error, the prefab may have been partially instantiated in the scene.

See also

LoadFromFile, AddToScene, PrefabParams

EnsureFullyLoaded()

void superdex::prefab::EnsureFullyLoaded	(	ScenePrefab &	prefab,
		std::string_view	rootPath,
		Context *	context,
		Error &	error )

Ensure that all nested prefabs and shape files are loaded, skipping any that are already loaded.

Parameters

[in,out]	prefab	The ScenePrefab whose nested prefabs and shapes will be loaded.
[in]	rootPath	Root directory for resolving relative paths, except those resolved against a prefab file.
[in]	Context	The Context that owns the loaded resources.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Use this if the file was loaded via ShallowLoadFromFile or ShallowLoadFromJsonString or if the ScenePrefab was created procedurally.

You do not need to call this after LoadFromFile or LoadFromJsonString because they load all nested content for you.

A prefab must not reference itself, directly or indirectly.

See also

LoadNestedPrefabs, LoadShapes, AddToScene

ExportActor()

void superdex::prefab::ExportActor	(	Actor const *	actor,
		std::string_view	exportName,
		std::string_view	outputDir,
		Error &	error )

Export a single actor to a prefab file under outputDir/exportName/<exportName>.mochi_scene.

Extracts creation parameters from the actor and writes the prefab plus any generated mesh assets to disk. Only supported for standalone rigid actors, soft actors and articulated actors.

Parameters

[in]	actor	The actor to export. Must not be null.
[in]	exportName	Label used for the actor's name, the export subdirectory, and the prefab filename (<exportName>.mochi_scene).
[in]	outputDir	Parent directory for the export. The subdirectories <outputDir>/<exportName> and <outputDir>/<exportName>/generated_assets are created automatically.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Uses the same prefab export path as ExportScene. In addition to the soft-skinned restriction above, any limitations documented in ExportScene also apply here.

When exporting an articulated actor, pass the top-level articulated actor (the one returned by Scene::CreateArticulatedActor or by Actor::GetArticulatedActor on a nested link), not a nested actor.

Generated mesh files (.mochi.h5) are written under generated_assets/ and referenced from the prefab using "./generated_assets/" paths.

Warning

Only supported for standalone rigid, soft, and articulated actors. Soft-skinned actors are not supported here.

Contact-filter settings are not exported. Adding an exported articulated actor to a scene applies automatic adjacent-link filtering, even if contact between adjacent links was explicitly enabled before export. To preserve this behavior, add an equivalent enabling entry to the exported prefab or re-enable the pair after adding the prefab to a scene.

See also

ExportScene, ExportSceneExcluding

ExportScene()

void superdex::prefab::ExportScene	(	Scene const *	scene,
		std::string_view	exportName,
		std::string_view	outputDir,
		Error &	error )

Export a Scene to a folder containing a prefab file and all generated mesh files.

Parameters

[in]	Scene	The Scene to export.
[in]	exportName	Name for the exported prefab. Used both for the export subdirectory and for the prefab filename (<exportName>.mochi_scene).
[in]	outputDir	Directory where the export folder will be created. The subdirectories <outputDir>/<exportName> and <outputDir>/<exportName>/generated_assets are created automatically.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Generated mesh files (.mochi.h5) are written under generated_assets/ and referenced from the prefab using "./generated_assets/" paths.

Exported actor names are made unique: when two actors share a name, later ones receive a numeric suffix (e.g. "box", "box1"), so an exported name may differ from the runtime name.

Warning

Currently exports only rigid, soft, articulated, and soft-skinned actors. Constraints, pose controllers, shell, rod actors, and implicit (non-mesh) shapes are NOT exported.

For articulated actors, current joint pose and joint velocities are NOT exported.

Scene export does not record explicit settings that enable contact between actor pairs. If such a setting enables contact between adjacent links of an articulated or soft-skinned actor, adding the exported prefab to a scene applies automatic adjacent-link filtering and disables contact for that pair again. To preserve this behavior, add an equivalent enabling entry to the exported prefab or re-enable the pair after adding the prefab to a scene.

See also

ExportSceneExcluding, ExportActor

ExportSceneExcluding()

void superdex::prefab::ExportSceneExcluding	(	Scene const *	scene,
		std::string_view	exportName,
		std::string_view	outputDir,
		Span< ActorHandle const >	excludeActors,
		Error &	error )

Export a Scene to a folder containing a prefab file and all generated mesh files, omitting a caller-provided set of actors.

Parameters

[in]	Scene	The Scene to export.
[in]	exportName	Name for the exported prefab. Used both for the export subdirectory and for the prefab filename (<exportName>.mochi_scene).
[in]	outputDir	Directory where the export folder will be created. The subdirectories <outputDir>/<exportName> and <outputDir>/<exportName>/generated_assets are created automatically.
[in]	excludeActors	Handles of actors that should not be exported. Excluding an articulated actor also excludes all of its nested link actors. Excluding a soft-skinned actor also excludes all of its nested link and soft sub-actors. Any contact filter entries that reference excluded actors are dropped.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Generated mesh files (.mochi.h5) are written under generated_assets/ and referenced from the prefab using "./generated_assets/" paths.

Exported actor names are made unique: when two actors share a name, later ones receive a numeric suffix (e.g. "box", "box1"), so an exported name may differ from the runtime name.

Warning

Currently exports only rigid, soft, articulated, and soft-skinned actors. Constraints, pose controllers, shell, rod actors, and implicit (non-mesh) shapes are NOT exported.

For articulated actors, current joint pose and joint velocities are NOT exported.

Scene export does not record explicit settings that enable contact between actor pairs. If such a setting enables contact between adjacent links of an articulated or soft-skinned actor, adding the exported prefab to a scene applies automatic adjacent-link filtering and disables contact for that pair again. To preserve this behavior, add an equivalent enabling entry to the exported prefab or re-enable the pair after adding the prefab to a scene.

See also

ExportScene, ExportActor

GetPrefabFullPath()

DynamicString superdex::prefab::GetPrefabFullPath	(	std::string_view	inputPath,
		std::string_view	rootForRelativePath,
		std::string_view	prefabFilePath )

Resolve a path referenced inside a prefab to a full path.

Parameters

[in]	inputPath	The path to resolve, as stored in the prefab (may be prefixed with "./" to indicate it is relative to the prefab file).
[in]	rootForRelativePath	Root directory used to resolve paths that are not prefixed with "./".
[in]	prefabFilePath	Path to the prefab file that references inputPath, used to resolve "./"-prefixed paths relative to its location.

Returns

The resolved full path.

Note

Absolute paths are returned unchanged. Paths starting with "./" are resolved relative to the directory containing prefabFilePath when provided. Other relative paths are resolved against rootForRelativePath.

LoadFromFile()

ScenePrefab superdex::prefab::LoadFromFile	(	std::string_view	prefabPath,
		std::string_view	rootPath,
		Context *	context,
		Error &	error )

Fully load a ScenePrefab from a file, including all nested prefabs and shapes.

Parameters

[in]	prefabPath	File path to the prefab file.
[in]	rootPath	Root directory for resolving relative paths, except those resolved against a prefab file.
[in]	Context	The Context that owns the loaded resources.
[in,out]	error	Error status. Check Error::IsOK for success.

Returns

The fully loaded ScenePrefab, or a default-constructed ScenePrefab on error.

Note

Prefab files are in JSON format.

A prefab must not reference itself, directly or indirectly.

See also

LoadFromJsonString, ShallowLoadFromFile, ShallowLoadFromJsonString

LoadFromJsonString()

ScenePrefab superdex::prefab::LoadFromJsonString	(	std::string_view	json,
		std::string_view	rootPath,
		Context *	context,
		Error &	error )

Fully load a ScenePrefab from a JSON string, including all nested prefabs and shapes.

Parameters

[in]	json	JSON string containing the serialized prefab.
[in]	rootPath	Root directory for resolving relative paths, except those resolved against a prefab file.
[in]	Context	The Context that owns the loaded resources.
[in,out]	error	Error status. Check Error::IsOK for success.

Returns

The fully loaded ScenePrefab, or a default-constructed ScenePrefab on error.

Note

The top-level prefab has no source file, so prefab-relative ("./"-prefixed) nested prefab and shape paths written in json resolve against rootPath, not against a prefab directory. Nested prefabs that are loaded from files resolve their own "./"-prefixed paths relative to the directory containing the nested prefab file. Use LoadFromFile if you need prefab-relative resolution at the top level.

A prefab must not reference itself, directly or indirectly.

See also

LoadFromFile, ShallowLoadFromFile, ShallowLoadFromJsonString

LoadNestedPrefabs()

void superdex::prefab::LoadNestedPrefabs	(	ScenePrefab &	prefab,
		std::string_view	rootPath,
		Error &	error )

Load nested prefab files recursively.

Parameters

[in,out]	prefab	The ScenePrefab whose nested prefab references will be loaded.
[in]	rootPath	Root directory for resolving relative paths, except those resolved against a prefab file.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Use this if the file was loaded via ShallowLoadFromFile or ShallowLoadFromJsonString or if the ScenePrefab was created procedurally.

You do not need to call this after LoadFromFile or LoadFromJsonString because they load all nested content for you.

If called a second time, the nested prefabs will be reloaded. If your intention is to avoid redundant loads, then use EnsureFullyLoaded instead.

A prefab must not reference itself, directly or indirectly.

See also

EnsureFullyLoaded, LoadShapes

LoadShapes()

void superdex::prefab::LoadShapes	(	ScenePrefab &	prefab,
		std::string_view	rootPath,
		Context *	context,
		Error &	error )

Load shape files referenced by prefab and its loaded nested prefabs.

Parameters

[in,out]	prefab	The ScenePrefab whose shape references will be loaded.
[in]	rootPath	Root directory for resolving relative paths, except those resolved against a prefab file.
[in]	Context	The Context that owns the loaded resources.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Returns an error if the input prefab or any loaded nested prefab references itself, directly or indirectly.

Use this if the file was loaded via ShallowLoadFromFile or ShallowLoadFromJsonString or if the ScenePrefab was created procedurally.

You do not need to call this after LoadFromFile or LoadFromJsonString because they load all nested content for you.

Calling this function again reloads previously loaded shapes to reflect changes to shape file paths or transforms. Use EnsureFullyLoaded to avoid reloading them.

Warning

Shapes are loaded from nested prefabs only if those prefabs are already loaded. Use EnsureFullyLoaded if any nested prefabs may be unloaded.

See also

EnsureFullyLoaded, LoadNestedPrefabs, AddToScene

SaveToJsonFile()

void superdex::prefab::SaveToJsonFile	(	ScenePrefab const &	prefab,
		std::string_view	path,
		Error &	error )

Serialize a ScenePrefab to a JSON file.

Parameters

[in]	prefab	The ScenePrefab to serialize.
[in]	path	Output file path.
[in,out]	error	Error status. Check Error::IsOK for success.

Note

Does NOT serialize nested prefabs. Only the top-level prefab data is written.

Automatically creates the output directory path, as needed.

See also

SaveToJsonString

SaveToJsonString()

DynamicString superdex::prefab::SaveToJsonString	(	ScenePrefab const &	prefab,
		Error &	error )

Serialize a ScenePrefab to a JSON string.

Parameters

[in]	prefab	The ScenePrefab to serialize.
[in,out]	error	Error status. Check Error::IsOK for success.

Returns

The JSON string, or an empty string on error.

Note

Does NOT serialize nested prefabs. Only the top-level prefab data is written.

See also

SaveToJsonFile

ShallowLoadFromFile()

ScenePrefab superdex::prefab::ShallowLoadFromFile	(	std::string_view	path,
		Error &	error )

Deserialize a single ScenePrefab from a file, without loading any nested files.

Parameters

[in]	path	File path to the prefab file.
[in,out]	error	Error status. Check Error::IsOK for success.

Returns

The deserialized ScenePrefab, or a default-constructed ScenePrefab on error.

Note

Use this if you want to modify the ScenePrefab data before nested content is loaded, or if you simply want to edit and re-save the prefab file.

If you intend to add the ScenePrefab to a Scene, then you will need to load any nested prefabs and shapes first.

See also

EnsureFullyLoaded, LoadNestedPrefabs, LoadShapes, ShallowLoadFromJsonString

ShallowLoadFromJsonString()

ScenePrefab superdex::prefab::ShallowLoadFromJsonString	(	std::string_view	json,
		Error &	error )

Deserialize a single ScenePrefab from a JSON string, without loading any nested files.

Parameters

[in]	json	JSON string containing the serialized prefab.
[in,out]	error	Error status. Check Error::IsOK for success.

Returns

The deserialized ScenePrefab, or a default-constructed ScenePrefab on error.

Note

Same as ShallowLoadFromFile except that the JSON string is provided in memory.

Unlike ShallowLoadFromFile, this function is not given a source file for the top-level prefab. Its "./"-prefixed nested prefab and shape paths therefore resolve against the root path passed to LoadNestedPrefabs, LoadShapes, or EnsureFullyLoaded. Pass the prefab directory as the root path to preserve prefab-relative resolution.

See also

ShallowLoadFromFile, LoadFromJsonString