SceneHandling
SceneHandling
#Overview
name: SceneHandling
The value of this variable can be defined or overridden in .ini config files. 1
.ini config file referencing this setting variable.
It is referenced in 13
C++ source files.
#Summary
#Usage in the C++ source code
The purpose of SceneHandling is to control how the Datasmith importer handles the scene during the import process. It is used to determine whether to import assets only, import into the current level, or create a new level for the imported content.
This setting variable is primarily used by the Datasmith importer system, which is part of Unreal Engine’s Enterprise plugins for importing CAD and other 3D data formats.
The value of this variable is typically set in the following ways:
- As a default value in the FDatasmithImportBaseOptions constructor
- Through configuration files (as seen in the LoadDefaultSettings function)
- Programmatically, based on specific import requirements (e.g., in the DatasmithConsumer or DatasmithImportContext)
SceneHandling interacts with other import-related variables, such as bUpdateActors and bRespawnDeletedActors in the reimport options.
Developers must be aware that:
- The SceneHandling value can affect the behavior of the entire import process, including whether actors are created in the level or not.
- It can be overridden in different parts of the import process, so it’s important to verify its value at critical points.
- The AssetsOnly option prevents the creation of actors in the level, which may be desirable in some workflows but could lead to unexpected results if not properly understood.
Best practices when using this variable include:
- Clearly communicating the intended import behavior to users through UI or documentation.
- Consistently checking and setting the SceneHandling value throughout the import process to ensure the desired outcome.
- Considering the implications of each SceneHandling option on the overall project structure and workflow.
- Using the appropriate SceneHandling option based on the specific use case (e.g., AssetsOnly for importing just assets, CurrentLevel for adding to an existing scene, or NewLevel for creating a separate environment).
#Setting Variables
#References In INI files
Location: <Workspace>/Engine/Plugins/Enterprise/DatasmithImporter/Config/BaseDatasmithImporter.ini:12, section: [FileProducerImportOptions]
- INI Section:
FileProducerImportOptions
- Raw value:
CurrentLevel
- Is Array:
False
#References in C++ code
#Callsites
This variable is referenced in the following C++ source code:
#Loc: <Workspace>/Engine/Plugins/ChaosClothAssetEditor/Source/ChaosClothAssetDataflowNodes/Private/ChaosClothAsset/DatasmithImportNode.cpp:192
Scope (from outer to inner):
file
function bool FChaosClothAssetDatasmithImportNode::EvaluateImpl
Source code excerpt:
// Don't create the Actors in the level, just read the Assets
DatasmithImportContext.Options->BaseOptions.SceneHandling = EDatasmithImportScene::AssetsOnly;
constexpr EObjectFlags NewObjectFlags = RF_Public | RF_Transactional | RF_Transient | RF_Standalone;
const TSharedPtr<FJsonObject> ImportSettingsJson;
constexpr bool bIsSilent = true;
if (!DatasmithImportContext.Init(DestinationPackage->GetPathName(), NewObjectFlags, GWarn, ImportSettingsJson, bIsSilent))
#Loc: <Workspace>/Engine/Plugins/Enterprise/DatasmithContent/Source/DatasmithContent/Private/DatasmithImportOptions.cpp:17
Scope (from outer to inner):
file
function FDatasmithImportBaseOptions::FDatasmithImportBaseOptions
Source code excerpt:
FDatasmithImportBaseOptions::FDatasmithImportBaseOptions()
: SceneHandling(EDatasmithImportScene::CurrentLevel)
, bIncludeGeometry(true)
, bIncludeMaterial(true)
, bIncludeLight(true)
, bIncludeCamera(true)
, bIncludeAnimation(true)
{
#Loc: <Workspace>/Engine/Plugins/Enterprise/DatasmithContent/Source/DatasmithContent/Private/DatasmithImportOptions.cpp:48
Scope (from outer to inner):
file
function void UDatasmithImportOptions::UpdateNotDisplayedConfig
Source code excerpt:
if ( !ReimportOptions.bUpdateActors )
{
BaseOptions.SceneHandling = EDatasmithImportScene::AssetsOnly;
}
else
{
BaseOptions.SceneHandling = EDatasmithImportScene::CurrentLevel;
if ( ReimportOptions.bRespawnDeletedActors )
{
DefaultImportActorPolicy = EDatasmithImportActorPolicy::Full;
}
}
#Loc: <Workspace>/Engine/Plugins/Enterprise/DatasmithContent/Source/DatasmithContent/Public/DatasmithImportOptions.h:180
Scope: file
Source code excerpt:
/** Specifies where to put the content */
UPROPERTY(BlueprintReadWrite, Category = Import, Transient)
EDatasmithImportScene SceneHandling; // Not displayed, not saved
/** Specifies whether or not to import geometry */
UPROPERTY(config, EditAnywhere, BlueprintReadWrite, Category = Process, meta = (DisplayName = "Geometry"))
bool bIncludeGeometry;
/** Specifies whether or not to import materials and textures */
#Loc: <Workspace>/Engine/Plugins/Enterprise/DatasmithImporter/Source/DatasmithImporter/Private/ActorFactoryDatasmithScene.cpp:69
Scope (from outer to inner):
file
namespace UActorFactoryDatasmithSceneImpl
function ADatasmithSceneActor* ImportActors
Source code excerpt:
ImportContext.Options->BaseOptions = DatasmithScene->AssetImportData->BaseOptions;
ImportContext.Options->BaseOptions.SceneHandling = EDatasmithImportScene::CurrentLevel;
if (InLevel)
{
ImportContext.ActorsContext.ImportWorld = InLevel->GetWorld();
}
#Loc: <Workspace>/Engine/Plugins/Enterprise/DatasmithImporter/Source/DatasmithImporter/Private/DatasmithBlueprintLibrary.cpp:307
Scope (from outer to inner):
file
namespace DatasmithSceneElementUtil
function TArray<FDatasmithImportFactoryCreateFileResult> ImportDatasmithScenesFromFiles
Source code excerpt:
PlmXmlImportContextPtr->InitOptions(nullptr, TOptional<FString>(), true);
PlmXmlImportContextPtr->Options->BaseOptions.SceneHandling = EDatasmithImportScene::AssetsOnly;
if (TSharedPtr<IDatasmithScene> LoadedScene = ExternalSource->TryLoad())
{
TSharedRef<IDatasmithScene> PlmXmlScene = LoadedScene.ToSharedRef();
PlmXmlImportContextPtr->InitScene(PlmXmlScene);
// Inlined bool FDatasmithImportContext::SetupDestination
#Loc: <Workspace>/Engine/Plugins/Enterprise/DatasmithImporter/Source/DatasmithImporter/Private/DatasmithConsumer.cpp:718
Scope (from outer to inner):
file
function bool UDatasmithConsumer::BuildContexts
Source code excerpt:
// Update import context with consumer's data
ImportContextPtr->Options->BaseOptions.SceneHandling = EDatasmithImportScene::CurrentLevel;
ImportContextPtr->SceneAsset = DatasmithSceneWeakPtr.Get();
ImportContextPtr->ActorsContext.ImportWorld = Context.WorldPtr.Get();
ImportContextPtr->InitScene(FDatasmithSceneFactory::CreateScene(*DatasmithSceneWeakPtr->GetName()));
// Convert all incoming Datasmith scene actors as regular actors
DatasmithConsumerUtils::ConvertSceneActorsToActors( *ImportContextPtr );
#Loc: <Workspace>/Engine/Plugins/Enterprise/DatasmithImporter/Source/DatasmithImporter/Private/DatasmithFileProducer.cpp:1955
Scope (from outer to inner):
file
function void UDatasmithFileProducer::LoadDefaultSettings
Source code excerpt:
GConfig->GetBool( ImportSectionName, TEXT("IncludeAnimation"), DefaultImportOptions.bIncludeAnimation, DatasmithImporterIni);
FString SceneHandling = GConfig->GetStr( ImportSectionName, TEXT("SceneHandling"), DatasmithImporterIni);
if(SceneHandling == TEXT("NewLevel"))
{
DefaultImportOptions.SceneHandling = EDatasmithImportScene::NewLevel;
}
else if(SceneHandling == TEXT("AssetsOnly"))
{
DefaultImportOptions.SceneHandling = EDatasmithImportScene::AssetsOnly;
}
else
{
DefaultImportOptions.SceneHandling = EDatasmithImportScene::CurrentLevel;
}
}
}
FString FDatasmithFileProducerUtils::SelectFileToImport()
{
#Loc: <Workspace>/Engine/Plugins/Enterprise/DatasmithImporter/Source/DatasmithImporter/Private/DatasmithImportContext.cpp:197
Scope (from outer to inner):
file
function FDatasmithImportContext::FDatasmithImportContext
Source code excerpt:
}
// Force the SceneHandling to be on current level by default.
// Note: This is done because this option was previously persisted and can get overwritten
UE::DatasmithImporter::FSourceUri SourceUri(UE::DatasmithImporter::FSourceUri::FromFilePath(InFileName));
Options->BaseOptions.SceneHandling = EDatasmithImportScene::CurrentLevel;
Options->FileName = FPaths::GetCleanFilename(InFileName);
Options->FilePath = FPaths::ConvertRelativePathToFull(InFileName);
FileHash = FMD5Hash::HashFile(*Options->FilePath);
Options->SourceUri = SourceUri.ToString();
Options->SourceHash = FileHash;
#Loc: <Workspace>/Engine/Plugins/Enterprise/DatasmithImporter/Source/DatasmithImporter/Private/DatasmithImportContext.cpp:250
Scope (from outer to inner):
file
function FDatasmithImportContext::FDatasmithImportContext
Source code excerpt:
}
// Force the SceneHandling to be on current level by default.
// Note: This is done because this option was previously persisted and can get overwritten
Options->BaseOptions.SceneHandling = EDatasmithImportScene::CurrentLevel;
}
void FDatasmithImportContext::UpdateImportOption(UDatasmithOptionsBase* NewOption)
{
if (NewOption)
{
#Loc: <Workspace>/Engine/Plugins/Enterprise/DatasmithImporter/Source/DatasmithImporter/Private/DatasmithImportContext.cpp:391
Scope (from outer to inner):
file
function bool FDatasmithImportContext::SetupDestination
Source code excerpt:
// Check to see if there is nothing to save and act according to user's selection
// Note: The code below has been borrowed from UEditorEngine::CreateNewMapForEditing
if (Options->BaseOptions.SceneHandling == EDatasmithImportScene::NewLevel)
{
if (!bSilent)
{
// Check to see if there are unsaved data and user wants to save them
// Import will abort if user selects cancel on Save dialog
bool bPromptUserToSave = true; // Ask user if they want to save the unsaved data
#Loc: <Workspace>/Engine/Plugins/Enterprise/DatasmithImporter/Source/DatasmithImporter/Private/DatasmithImportContext.cpp:410
Scope (from outer to inner):
file
function bool FDatasmithImportContext::SetupDestination
Source code excerpt:
ActorsContext.ImportWorld = UEditorLoadingAndSavingUtils::NewBlankMap(false);
}
else if (Options->BaseOptions.SceneHandling == EDatasmithImportScene::CurrentLevel)
{
ActorsContext.ImportWorld = GWorld;
if (ActorsContext.ImportWorld == nullptr)
{
UE_LOG(LogDatasmithImport, Warning, TEXT("Import failed. There is no World/Map open in the Editor."));
return false;
#Loc: <Workspace>/Engine/Plugins/Enterprise/DatasmithImporter/Source/DatasmithImporter/Private/DatasmithImportContext.cpp:522
Scope (from outer to inner):
file
function bool FDatasmithImportContext::ShouldImportActors
Source code excerpt:
bool FDatasmithImportContext::ShouldImportActors() const
{
return ActorsContext.ImportWorld && Options->BaseOptions.SceneHandling != EDatasmithImportScene::AssetsOnly;
}
FDatasmithImportContext::FInternalReferenceCollector::FInternalReferenceCollector(FDatasmithImportContext* InImportContext)
: ImportContext(InImportContext)
{
}