MaterialSearchLocation
MaterialSearchLocation
#Overview
name: MaterialSearchLocation
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 12
C++ source files.
#Summary
#Usage in the C++ source code
The purpose of MaterialSearchLocation is to specify where Unreal Engine should search for existing materials when importing assets, particularly when importing FBX files. This setting variable is primarily used in the material import and asset import systems of Unreal Engine.
Based on the callsites, this setting variable is mainly utilized by the following Unreal Engine subsystems and modules:
- Interchange Editor Plugin
- FBX Import system
- Material Import system
- Skeletal Mesh Import system
The value of this variable is typically set in the import UI (UFbxImportUI class) and is stored in the UFbxTextureImportData class. It is an enumeration of type EMaterialSearchLocation, which likely includes options such as Local, UnderParent, and possibly others.
This variable interacts with other import-related variables, such as bImportMaterials, BaseMaterialName, and various texture name variables (BaseColorName, BaseDiffuseTextureName, etc.).
Developers should be aware of the following when using this variable:
- It affects where the engine looks for existing materials during import, which can impact performance and asset organization.
- The setting can be different for different types of imports (e.g., static mesh, skeletal mesh).
- It’s part of the larger material import system and should be considered alongside other material import settings.
Best practices when using this variable include:
- Choose the appropriate search location based on your project’s asset organization to ensure efficient material reuse.
- Consistently use the same search location for similar types of imports to maintain organization.
- Consider the performance implications of wider search scopes, especially in large projects.
- Document the chosen search location in your team’s asset import guidelines to ensure consistency across the project.
- When reimporting or updating assets, be aware of how this setting might affect existing material references.
#Setting Variables
#References In INI files
Location: <Workspace>/Engine/Config/BaseEditorPerProjectUserSettings.ini:698, section: [/Script/UnrealEd.FbxTextureImportData]
- INI Section:
/Script/UnrealEd.FbxTextureImportData
- Raw value:
EMaterialSearchLocation::Local
- Is Array:
False
#References in C++ code
#Callsites
This variable is referenced in the following C++ source code:
#Loc: <Workspace>/Engine/Plugins/Interchange/Editor/Source/InterchangeEditor/Private/InterchangeFbxAssetImportDataConverter.cpp:624
Scope (from outer to inner):
file
namespace UE::Interchange::Private
function UAssetImportData* ConvertToInterchange
Source code excerpt:
//Material Options
GenericAssetPipeline->MaterialPipeline->bImportMaterials = FbxImportUI->bImportMaterials;
switch (FbxImportUI->TextureImportData->MaterialSearchLocation)
{
case EMaterialSearchLocation::Local:
GenericAssetPipeline->MaterialPipeline->SearchLocation = EInterchangeMaterialSearchLocation::Local;
break;
case EMaterialSearchLocation::UnderParent:
GenericAssetPipeline->MaterialPipeline->SearchLocation = EInterchangeMaterialSearchLocation::UnderParent;
#Loc: <Workspace>/Engine/Source/Editor/DetailCustomizations/Private/FbxImportUIDetails.cpp:625
Scope (from outer to inner):
file
function void FFbxImportUIDetails::CustomizeDetails
Source code excerpt:
if (Handle->GetProperty()->GetOwner<UObject>() == UFbxTextureImportData::StaticClass())
{
if (Handle->GetProperty()->GetFName() == GET_MEMBER_NAME_CHECKED(UFbxTextureImportData, MaterialSearchLocation))
{
MaterialLocationPropHandle = Handle;
}
}
}
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Classes/Factories/FbxTextureImportData.h:23
Scope (from outer to inner):
file
class class UFbxTextureImportData : public UFbxAssetImportData
Source code excerpt:
/** Specify where we should search for matching materials when importing */
UPROPERTY(EditAnywhere, BlueprintReadWrite, config, Category = ImportSettings, meta = (DisplayName="Search Location", OBJRestrict = "true", ImportType = "Mesh"))
EMaterialSearchLocation MaterialSearchLocation;
/** Base material to instance from when importing materials. */
UPROPERTY(EditAnywhere, BlueprintReadWrite, config, Category = Material, meta = (ImportType = "Mesh", AllowedClasses = "/Script/Engine.MaterialInterface"))
FSoftObjectPath BaseMaterialName;
/** transient, ImportUI customize helper to store if we must show or not the BaseMaterialName property. */
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Fbx/FbxMainImport.cpp:387
Scope (from outer to inner):
file
namespace UnFbx
function void ApplyImportUIToImportOptions
Source code excerpt:
InOutImportOptions.bImportMaterials = ImportUI->bImportMaterials;
InOutImportOptions.bInvertNormalMap = ImportUI->TextureImportData->bInvertNormalMaps;
InOutImportOptions.MaterialSearchLocation = ImportUI->TextureImportData->MaterialSearchLocation;
UMaterialInterface* BaseMaterialInterface = Cast<UMaterialInterface>(ImportUI->TextureImportData->BaseMaterialName.TryLoad());
if (BaseMaterialInterface) {
InOutImportOptions.BaseMaterial = BaseMaterialInterface;
InOutImportOptions.BaseColorName = ImportUI->TextureImportData->BaseColorName;
InOutImportOptions.BaseDiffuseTextureName = ImportUI->TextureImportData->BaseDiffuseTextureName;
InOutImportOptions.BaseNormalTextureName = ImportUI->TextureImportData->BaseNormalTextureName;
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Fbx/FbxMainImport.cpp:1647
Scope (from outer to inner):
file
namespace UnFbx
function bool FFbxImporter::ImportFromFile
Source code excerpt:
* @EventParam ImportUniformScale float Returns the uniform scale apply on the import data
* @EventParam MaterialBasePath string Returns the path pointing on the base material use to import material instance
* @EventParam MaterialSearchLocation string Returns the scope of the search for existing materials (if material not found it can create one depending on bImportMaterials value)
* @EventParam ReorderMaterialToFbxOrder boolean returns weather the importer should reorder the materials in the same order has the fbx file
* @EventParam AutoGenerateCollision boolean Returns whether the importer should create collision primitive
* @EventParam CombineToSingle boolean Returns whether the importer should combine all mesh part together or import many meshes
* @EventParam BakePivotInVertex boolean Returns whether the importer should bake the fbx mesh pivot into the vertex position
* @EventParam TransformVertexToAbsolute boolean Returns whether the importer should bake the global fbx node transform into the vertex position
* @EventParam ImportRigidMesh boolean Returns whether the importer should try to create a rigid mesh (static mesh import as skeletal mesh)
* @EventParam NormalImportMethod string Return if the tangents or normal should be imported or compute
* @EventParam NormalGenerationMethod string Return tangents generation method
* @EventParam CreatePhysicsAsset boolean Returns whether the importer should create the physic asset
* @EventParam ImportAnimations boolean Returns whether the importer should import also the animation
* @EventParam ImportAsSkeletalGeometry boolean Returns whether the importer should import only the geometry
* @EventParam ImportAsSkeletalSkinning boolean Returns whether the importer should import only the skinning
* @EventParam ImportMeshesInBoneHierarchy boolean Returns whether the importer should import also the mesh found in the bone hierarchy
* @EventParam ImportMorph boolean Returns whether the importer should import the morph targets
* @EventParam ImportSkeletalMeshLODs boolean Returns whether the importer should import the LODs
* @EventParam PreserveSmoothingGroups boolean Returns whether the importer should import the smoothing groups
* @EventParam UpdateSkeletonReferencePose boolean Returns whether the importer should update the skeleton reference pose
* @EventParam UseT0AsRefPose boolean Returns whether the importer should use the the animation 0 time has the reference pose
* @EventParam ThresholdPosition float Returns the threshold delta to weld vertices
* @EventParam ThresholdTangentNormal float Returns the threshold delta to weld tangents and normals
* @EventParam ThresholdUV float Returns the threshold delta to weld UVs
* @EventParam MorphThresholdPosition float Returns the morph target threshold delta to compute deltas
* @EventParam AutoComputeLodDistances boolean Returns whether the importer should set the auto compute LOD distance
* @EventParam LodNumber integer Returns the LOD number we should have after the import
* @EventParam BuildReversedIndexBuffer boolean Returns whether the importer should fill the reverse index buffer when building the static mesh
* @EventParam GenerateLightmapUVs boolean Returns whether the importer should generate light map UVs
* @EventParam ImportStaticMeshLODs boolean Returns whether the importer should import the LODs
* @EventParam RemoveDegenerates boolean Returns whether the importer should remove the degenerated triangles when building the static mesh
* @EventParam MinimumLodNumber integer Returns the minimum LOD use by the rendering
* @EventParam StaticMeshLODGroup string Returns the LOD Group settings we use to build this imported static mesh
* @EventParam VertexColorImportOption string Returns how the importer should import the vertex color
* @EventParam VertexOverrideColor string Returns the color use if we need to override the vertex color
* @EventParam AnimationLengthImportType string Returns how we choose the animation time span
* @EventParam DeleteExistingMorphTargetCurves boolean Returns whether the importer should delete the existing morph target curves
* @EventParam AnimationRange string Returns the range of animation the importer should sample if the time span is custom
* @EventParam DoNotImportCurveWithZero boolean Returns whether the importer should import curves containing only zero value
* @EventParam ImportBoneTracks boolean Returns whether the importer should import the bone tracks
* @EventParam ImportCustomAttribute boolean Returns whether the importer should import the custom attribute curves
* @EventParam PreserveLocalTransform boolean Returns whether the importer should preserve the local transform when importing the animation
* @EventParam RemoveRedundantKeys boolean Returns whether the importer should remove all redundant key in an animation
* @EventParam Resample boolean Returns whether the importer should re-sample the animation
* @EventParam SetMaterialDriveParameterOnCustomAttribute boolean Returns whether the importer should hook all custom attribute curve to unreal material attribute
* @EventParam SetMaterialDriveParameterOnCustomAttribute boolean Returns whether the importer should hook some custom attribute (having the suffix) curve to unreal material attribute
* @EventParam ResampleRate float Returns the rate the exporter is suppose to re-sample any imported animations
*
* @Owner Alexis.Matte
*/
FbxDocumentInfo* DocInfo = Scene->GetSceneInfo();
if (DocInfo)
{
if( FEngineAnalytics::IsAvailable() )
{
const static UEnum* FBXImportTypeEnum = StaticEnum<EFBXImportType>();
const static UEnum* FBXAnimationLengthImportTypeEnum = StaticEnum<EFBXAnimationLengthImportType>();
const static UEnum* MaterialSearchLocationEnum = StaticEnum<EMaterialSearchLocation>();
const static UEnum* FBXNormalGenerationMethodEnum = StaticEnum<EFBXNormalGenerationMethod::Type>();
const static UEnum* FBXNormalImportMethodEnum = StaticEnum<EFBXNormalImportMethod>();
const static UEnum* VertexColorImportOptionEnum = StaticEnum<EVertexColorImportOption::Type>();
TArray<FAnalyticsEventAttribute> Attribs;
FString LastSavedVendor(UTF8_TO_TCHAR(DocInfo->LastSaved_ApplicationVendor.Get().Buffer()));
FString LastSavedAppName(UTF8_TO_TCHAR(DocInfo->LastSaved_ApplicationName.Get().Buffer()));
FString LastSavedAppVersion(UTF8_TO_TCHAR(DocInfo->LastSaved_ApplicationVersion.Get().Buffer()));
Attribs.Add(FAnalyticsEventAttribute(TEXT("LastSaved Application Vendor"), LastSavedVendor));
Attribs.Add(FAnalyticsEventAttribute(TEXT("LastSaved Application Name"), LastSavedAppName));
Attribs.Add(FAnalyticsEventAttribute(TEXT("LastSaved Application Version"), LastSavedAppVersion));
Attribs.Add(FAnalyticsEventAttribute(TEXT("FBX Version"), FbxFileVersion));
//////////////////////////////////////////////////////////////////////////
//FBX import options
Attribs.Add(FAnalyticsEventAttribute(TEXT("GenOpt ImportType"), FBXImportTypeEnum->GetNameStringByValue(ImportOptions->ImportType)));
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Fbx/FbxMainImport.cpp:1734
Scope: file
Source code excerpt:
Attribs.Add(FAnalyticsEventAttribute(TEXT("GenOpt ImportUniformScale"), ImportOptions->ImportUniformScale));
Attribs.Add(FAnalyticsEventAttribute(TEXT("GenOpt MaterialBasePath"), ImportOptions->MaterialBasePath));
Attribs.Add(FAnalyticsEventAttribute(TEXT("GenOpt MaterialSearchLocation"), MaterialSearchLocationEnum->GetNameStringByValue((uint64)(ImportOptions->MaterialSearchLocation))));
Attribs.Add(FAnalyticsEventAttribute(TEXT("GenOpt ReorderMaterialToFbxOrder"), ImportOptions->bReorderMaterialToFbxOrder));
//We cant capture a this member, so just assign the pointer here
FBXImportOptions* CaptureImportOptions = ImportOptions;
auto AddMeshAnalytic = [&Attribs, &CaptureImportOptions]()
{
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Fbx/FbxMaterialImport.cpp:568
Scope (from outer to inner):
file
function UMaterialInterface* UnFbx::FFbxImporter::FindExistingMaterialFromFbxMaterial
Source code excerpt:
}
UMaterialInterface* UnFbx::FFbxImporter::FindExistingMaterialFromFbxMaterial(const FbxSurfaceMaterial& FbxMaterial, EMaterialSearchLocation MaterialSearchLocation)
{
// Make sure we have a parent
if (!ensure(Parent.IsValid()))
{
return nullptr;
}
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Fbx/FbxMaterialImport.cpp:599
Scope (from outer to inner):
file
function UMaterialInterface* UnFbx::FFbxImporter::FindExistingMaterialFromFbxMaterial
Source code excerpt:
{
FText Error;
FoundMaterial = UMaterialImportHelpers::FindExistingMaterialFromSearchLocation(MaterialFullName, BasePackageName, MaterialSearchLocation, Error);
if (!Error.IsEmpty())
{
AddTokenizedErrorMessage(
FTokenizedMessage::Create(EMessageSeverity::Warning,
FText::Format(LOCTEXT("FbxMaterialImport_MultipleMaterialsFound", "While importing '{0}': {1}"),
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Fbx/FbxMaterialImport.cpp:888
Scope (from outer to inner):
file
function void UnFbx::FFbxImporter::FindOrImportMaterialsFromNode
Source code excerpt:
if (FbxMaterial && UsedMaterialIndexes.Contains(MaterialIndex))
{
if (UMaterialInterface* ExistingMaterial = FindExistingMaterialFromFbxMaterial(*FbxMaterial, ImportOptions->MaterialSearchLocation))
{
MaterialImported = ExistingMaterial;
}
else if (ImportOptions->bImportMaterials)
{
//Only create a new material if we are importing them and we could not find an existing one.
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/SkinWeightsUtilities.cpp:196
Scope (from outer to inner):
file
function bool FSkinWeightsUtilities::ImportAlternateSkinWeight
Source code excerpt:
if (FbxFactory->ImportUI->TextureImportData)
{
FbxFactory->ImportUI->TextureImportData->MaterialSearchLocation = EMaterialSearchLocation::DoNotSearch;
FbxFactory->ImportUI->TextureImportData->BaseMaterialName.Reset();
}
TArray<FString> ImportFilePaths;
ImportFilePaths.Add(AbsoluteFilePath);
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Public/FbxImporter.h:170
Scope (from outer to inner):
file
namespace UnFbx
Source code excerpt:
FString BaseSpecularTextureName;
FString BaseOpacityTextureName;
EMaterialSearchLocation MaterialSearchLocation;
//If true the materials will be reorder to follow the fbx order
bool bReorderMaterialToFbxOrder;
// Skeletal Mesh options
bool bImportMorph;
bool bImportVertexAttributes;
bool bImportAnimations;
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Public/FbxImporter.h:1671
Scope: file
Source code excerpt:
* Tries to find an existing UnrealMaterial from the FbxMaterial, returns nullptr if could not find a material.
* The function will look for materials imported by the FbxFactory first,
* and then search into the asset database using the passed MaterialSearchLocation search scope.
*
* @param FbxMaterial The FbxMaterial used to search the UnrealMaterial
* @param MaterialSearchLocation The asset database search scope.
* @return The UMaterialInterfaceFound, returns nullptr if no material was found.
*/
UMaterialInterface* FindExistingMaterialFromFbxMaterial(const FbxSurfaceMaterial& FbxMaterial, EMaterialSearchLocation MaterialSearchLocation);
/**
* Create Unreal material from Fbx material.
* Only setup channels that connect to texture, and setup the UV coordinate of texture.
* If diffuse channel has no texture, one default node will be created with constant.
*
* @param KFbxSurfaceMaterial* Fbx material
* @param outUVSets
* @param bForSkeletalMesh If set to true, the material target usage will be set to "SkeletalMesh".
* @return The created material.
*/