Open 3D Engine AzToolsFramework API Reference 25.05.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
Public Member Functions | List of all members
AzToolsFramework::Prefab::PrefabPublicInterface Class Referenceabstract

#include <PrefabPublicInterface.h>

Inherited by AzToolsFramework::Prefab::PrefabPublicHandler.

Public Member Functions

 AZ_RTTI (PrefabPublicInterface, "{931AAE9D-C775-4818-9070-A2DA69489CBE}")
 
virtual CreatePrefabResult CreatePrefabInDisk (const EntityIdList &entityIds, AZ::IO::PathView filePath)=0
 
virtual CreatePrefabResult CreatePrefabAndSaveToDisk (const EntityIdList &entityIds, AZ::IO::PathView filePath)=0
 
virtual CreatePrefabResult CreatePrefabInMemory (const EntityIdList &entityIds, AZ::IO::PathView filePath)=0
 
virtual InstantiatePrefabResult InstantiatePrefab (AZStd::string_view filePath, AZ::EntityId parentId, const AZ::Transform &transform)=0
 
virtual InstantiatePrefabResult InstantiatePrefab (AZStd::string_view filePath, AZ::EntityId parentId, const AZ::Vector3 &position)=0
 
virtual PrefabOperationResult SavePrefab (AZ::IO::Path filePath)=0
 
virtual PrefabEntityResult CreateEntity (AZ::EntityId parentId, const AZ::Vector3 &position)=0
 
virtual PrefabOperationResult GenerateUndoNodesForEntityChangeAndUpdateCache (AZ::EntityId entityId, UndoSystem::URSequencePoint *parentUndoBatch)=0
 
virtual bool IsOwnedByPrefabInstance (AZ::EntityId entityId) const =0
 
virtual bool IsOwnedByProceduralPrefabInstance (AZ::EntityId entityId) const =0
 
virtual bool IsInstanceContainerEntity (AZ::EntityId entityId) const =0
 
virtual bool IsLevelInstanceContainerEntity (AZ::EntityId entityId) const =0
 
virtual bool EntitiesBelongToSameInstance (const EntityIdList &entityIds) const =0
 
virtual AZ::EntityId GetInstanceContainerEntityId (AZ::EntityId entityId) const =0
 
virtual AZ::EntityId GetLevelInstanceContainerEntityId () const =0
 
virtual AZ::IO::Path GetOwningInstancePrefabPath (AZ::EntityId entityId) const =0
 
virtual PrefabRequestResult HasUnsavedChanges (AZ::IO::Path prefabFilePath) const =0
 
virtual PrefabOperationResult DeleteEntitiesAndAllDescendantsInInstance (const EntityIdList &entityIds)=0
 
virtual DuplicatePrefabResult DuplicateEntitiesInInstance (const EntityIdList &entityIds)=0
 
virtual PrefabOperationResult DetachPrefab (const AZ::EntityId &containerEntityId)=0
 
virtual PrefabOperationResult DetachPrefabAndRemoveContainerEntity (const AZ::EntityId &containerEntityId)=0
 

Detailed Description

PrefabPublicInterface Interface to expose Prefab functionality directly to UI and Scripting. Functions will correctly call the Undo/Redo system under the hood.

Member Function Documentation

◆ CreateEntity()

virtual PrefabEntityResult AzToolsFramework::Prefab::PrefabPublicInterface::CreateEntity ( AZ::EntityId  parentId,
const AZ::Vector3 &  position 
)
pure virtual

Creates a new entity under the entity with id 'parentId' and propagates a change to the template of the owning instance of parentId.

Parameters
parentIdThe id of the parent entity to parent the newly added entity under.
positionThe transform position of the entity being added.
Returns
Returns the entityId of the newly created entity, or an error message if the operation failed.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ CreatePrefabAndSaveToDisk()

virtual CreatePrefabResult AzToolsFramework::Prefab::PrefabPublicInterface::CreatePrefabAndSaveToDisk ( const EntityIdList &  entityIds,
AZ::IO::PathView  filePath 
)
pure virtual

Create a prefab out of the entities provided, at the path provided, and save it in disk immediately. Automatically detects descendants of entities, and discerns between entities and child instances. Note: It calls CreatePrefabInMemory internally and then saves the new template in disk.

Parameters
entityIdsThe entities that should form the new prefab (along with their descendants).
filePathThe absolute path for the new prefab file.
Returns
An outcome object with an entityId of the new prefab's container entity; on failure, it comes with an error message detailing the cause of the error.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ CreatePrefabInDisk()

virtual CreatePrefabResult AzToolsFramework::Prefab::PrefabPublicInterface::CreatePrefabInDisk ( const EntityIdList &  entityIds,
AZ::IO::PathView  filePath 
)
pure virtual

O3DE_DEPRECATION_NOTICE(GHI-12956) This function is marked for deprecation. Please use CreatePrefabAndSaveToDisk instead.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ CreatePrefabInMemory()

virtual CreatePrefabResult AzToolsFramework::Prefab::PrefabPublicInterface::CreatePrefabInMemory ( const EntityIdList &  entityIds,
AZ::IO::PathView  filePath 
)
pure virtual

Create a prefab out of the entities provided, at the path provided, and keep it in memory. Automatically detects descendants of entities, and discerns between entities and child instances. Note: The newly created prefab template cannot be undo/redo. Undo will not remove the templace in system.

Parameters
entityIdsThe entities that should form the new prefab (along with their descendants).
filePathThe absolute path for the new prefab file.
Returns
An outcome object with an entityId of the new prefab's container entity; on failure, it comes with an error message detailing the cause of the error.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ DeleteEntitiesAndAllDescendantsInInstance()

virtual PrefabOperationResult AzToolsFramework::Prefab::PrefabPublicInterface::DeleteEntitiesAndAllDescendantsInInstance ( const EntityIdList &  entityIds)
pure virtual

Deletes all entities and their descendants from the owning instance. Bails if the entities don't all belong to the same instance.

Parameters
entitiesThe entities to delete. Their descendants will be discovered by this function.
Returns
An outcome object; on failure, it comes with an error message detailing the cause of the error.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ DetachPrefab()

virtual PrefabOperationResult AzToolsFramework::Prefab::PrefabPublicInterface::DetachPrefab ( const AZ::EntityId &  containerEntityId)
pure virtual

If the entity id is a container entity id, detaches the prefab instance corresponding to it. This includes converting the container entity into a regular entity and putting it under the parent prefab, removing the link between this instance and the parent, removing links between this instance and its nested instances, and adding entities directly owned by this instance under the parent instance. Bails if the entity is not a container entity or belongs to the level prefab instance. Note that this function retains the container entities, unlike the below function DetachPrefabAndRemoveContainerEntity.

Parameters
containerEntityIdThe container entity id of the instance to detach.
Returns
An outcome object; on failure, it comes with an error message detailing the cause of the error.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ DetachPrefabAndRemoveContainerEntity()

virtual PrefabOperationResult AzToolsFramework::Prefab::PrefabPublicInterface::DetachPrefabAndRemoveContainerEntity ( const AZ::EntityId &  containerEntityId)
pure virtual

Does the same thing as DetachPrefab, but also removes the container entity representing the prefab instance. This re-parents anything that used to be a child of the container entity to the container entity's parent. This operation is essentially the reverse of what happens when you create a prefab (which creates a new container entity and re-parents the entities under it. Note that the previous API only had "DetachPrefab", which kept the container entities, and by way of introducing as little risk a possible in an API change, the old function retains its original behavior and name.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ DuplicateEntitiesInInstance()

virtual DuplicatePrefabResult AzToolsFramework::Prefab::PrefabPublicInterface::DuplicateEntitiesInInstance ( const EntityIdList &  entityIds)
pure virtual

Duplicates all entities in the owning instance. Bails if the entities don't all belong to the same instance.

Parameters
entitiesThe entities to duplicate.
Returns
An outcome object with a list of ids of target entities' duplicates if duplication succeeded; on failure, it comes with an error message detailing the cause of the error.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ EntitiesBelongToSameInstance()

virtual bool AzToolsFramework::Prefab::PrefabPublicInterface::EntitiesBelongToSameInstance ( const EntityIdList &  entityIds) const
pure virtual

Detects if a list of entities are under the same instance. The instance of a container entity is special cased to be the parent instance of its instance.

Parameters
entityIdsThe list of entities to query.
Returns
True if all entities in the list have the same instance, false otherwise.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ GenerateUndoNodesForEntityChangeAndUpdateCache()

virtual PrefabOperationResult AzToolsFramework::Prefab::PrefabPublicInterface::GenerateUndoNodesForEntityChangeAndUpdateCache ( AZ::EntityId  entityId,
UndoSystem::URSequencePoint *  parentUndoBatch 
)
pure virtual

Store the changes between the current entity state and its last cached state into undo/redo commands. These changes are stored as patches to the owning prefab instance template, as appropriate. The function also triggers the redo() of the nodes it creates, triggering propagation on the next tick.

Parameters
entityIdThe entity to patch.
parentUndoBatchThe undo batch the undo nodes should be parented to.
Returns
Returns Success if the node was generated correctly, or an error message otherwise.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ GetInstanceContainerEntityId()

virtual AZ::EntityId AzToolsFramework::Prefab::PrefabPublicInterface::GetInstanceContainerEntityId ( AZ::EntityId  entityId) const
pure virtual

Gets the entity id for the instance container of the owning instance.

Parameters
entityIdThe id of the entity to query.
Returns
The entity id of the instance container owning the queried entity.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ GetLevelInstanceContainerEntityId()

virtual AZ::EntityId AzToolsFramework::Prefab::PrefabPublicInterface::GetLevelInstanceContainerEntityId ( ) const
pure virtual

Gets the entity id for the instance container of the level instance.

Returns
The entity id of the instance container for the currently loaded level.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ GetOwningInstancePrefabPath()

virtual AZ::IO::Path AzToolsFramework::Prefab::PrefabPublicInterface::GetOwningInstancePrefabPath ( AZ::EntityId  entityId) const
pure virtual

Get the file path to the prefab file for the prefab instance owning the entity provided.

Parameters
entityIdThe id for the entity being queried.
Returns
Returns the path to the prefab, or an empty path if the entity is owned by the level.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ HasUnsavedChanges()

virtual PrefabRequestResult AzToolsFramework::Prefab::PrefabPublicInterface::HasUnsavedChanges ( AZ::IO::Path  prefabFilePath) const
pure virtual

Gets whether the prefab has unsaved changes.

Parameters
filePathThe path to the prefab to query.
Returns
Returns true if the prefab has unsaved changes, false otherwise. If path is invalid, returns an error message.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ InstantiatePrefab() [1/2]

virtual InstantiatePrefabResult AzToolsFramework::Prefab::PrefabPublicInterface::InstantiatePrefab ( AZStd::string_view  filePath,
AZ::EntityId  parentId,
const AZ::Transform &  transform 
)
pure virtual

Instantiate a prefab from a prefab file.

Parameters
filePathThe path to the prefab file to instantiate.
parentIdThe entity id the prefab should be a child of in the transform hierarchy.
transformThe transform in world space the prefab should be instantiated in.
Returns
An outcome object with an entityId of the new prefab's container entity; on failure, it comes with an error message detailing the cause of the error.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ InstantiatePrefab() [2/2]

virtual InstantiatePrefabResult AzToolsFramework::Prefab::PrefabPublicInterface::InstantiatePrefab ( AZStd::string_view  filePath,
AZ::EntityId  parentId,
const AZ::Vector3 &  position 
)
pure virtual

Instantiate a prefab from a prefab file.

Parameters
filePathThe path to the prefab file to instantiate.
parentIdThe entity id the prefab should be a child of in the transform hierarchy.
positionThe position in world space the prefab should be instantiated in.
Returns
An outcome object with an entityId of the new prefab's container entity; on failure, it comes with an error message detailing the cause of the error.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ IsInstanceContainerEntity()

virtual bool AzToolsFramework::Prefab::PrefabPublicInterface::IsInstanceContainerEntity ( AZ::EntityId  entityId) const
pure virtual

Detects if an entity is the container entity for its owning prefab instance.

Parameters
entityIdThe entity to query.
Returns
True if the entity is the container entity for its owning prefab instance, false otherwise.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ IsLevelInstanceContainerEntity()

virtual bool AzToolsFramework::Prefab::PrefabPublicInterface::IsLevelInstanceContainerEntity ( AZ::EntityId  entityId) const
pure virtual

Detects if an entity is the container entity for the level prefab instance.

Parameters
entityIdThe entity to query.
Returns
True if the entity is the container entity for the level prefab instance, false otherwise.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ IsOwnedByPrefabInstance()

virtual bool AzToolsFramework::Prefab::PrefabPublicInterface::IsOwnedByPrefabInstance ( AZ::EntityId  entityId) const
pure virtual

Detects if an entity is owned by a prefab.

Parameters
entityIdThe entity to query.
Returns
True if the entity is owned by a prefab instance, false otherwise.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ IsOwnedByProceduralPrefabInstance()

virtual bool AzToolsFramework::Prefab::PrefabPublicInterface::IsOwnedByProceduralPrefabInstance ( AZ::EntityId  entityId) const
pure virtual

Detects if an entity is owned by a procedural prefab.

Parameters
entityIdThe entity to query.
Returns
True if the entity is owned by a procedural prefab instance, false otherwise.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

◆ SavePrefab()

virtual PrefabOperationResult AzToolsFramework::Prefab::PrefabPublicInterface::SavePrefab ( AZ::IO::Path  filePath)
pure virtual

Saves changes to prefab to disk.

Parameters
filePathThe path to the prefab to save.
Returns
Returns Success if the file was saved, or an error message otherwise.

Implemented in AzToolsFramework::Prefab::PrefabPublicHandler.

The documentation for this class was generated from the following file: