Dedicated UDNA Asset Type

What changed

Prior to 5.8 the DNA asset was stored as an UDNAAsset — a UAssetUserData bolted onto a USkeletalMesh. In 5.8 DNA becomes its own asset, creating new DNA asset data:

• New class UDNA in RigLogicModule/Public/DNA.h (MinimalAPI, BlueprintType, meta=(DisplayName="DNA")).

• New asset definition UAssetDefinition_DNAAsset registers content browser display name, color (FColor::G…), thumbnail and source-file handling.

• New helper user-data UDNAAssetUserData (DisplayName="MetaHuman DNA Data") holds a TObjectPtr<UDNA> and is attached to the USkeletalMesh to associate a SkelMesh with its standalone DNA.

• The previous class is renamed in the UI to "Legacy MetaHuman DNA Data" (UDNAAsset); deprecation warnings flag downstream APIs.

Content Browser Actions

AssetDefinition_DNAAsset.cpp registers:

• On USkeletalMesh > MetaHuman DNA submenu:

  • Import DNA Asset: Imports a new .dna, attached as a UDNA standalone asset via UDNAImporter::ImportDNAWithPrompt.

  • Create DNA Asset: Visible only when the SkelMesh carries a legacy UDNAAsset user-data. Calls UDNAImporter::ConvertFromLegacyAssetUserData to materialize a standalone UDNA asset and rewires the user-data to the new UDNAAssetUserData.

• On UDNA:

  • Export DNA: Writes the in-memory DNA back out as a .dna file via UDNAImporter::ExportDNAWithPrompt.

Asset-registry tags now expose a "DNA" tag on each USkeletalMesh (resolved from the new UDNAAssetUserData, falling back to the legacy UDNAAsset for un-migrated content) so DNA association is searchable in the content browser.

5.8 Migration Using ConvertLegacyDNAAssets Commandlet

A headless tool for upgrading a project's MetaHuman DNA assets from 5.7 and earlier layout to the 5.8 format in a single, scriptable step.

Module: RigLogicEditor Class: UConvertLegacyDNAAssetsCommandlet Header: Engine/Plugins/Animation/RigLogic/Source/RigLogicEditor/Public/Commandlets/ConvertLegacyDNAAssetsCommandlet.h

What It Does

Unreal Engine 5.8 reorganises how MetaHuman DNA data is stored. The legacy UDNAAsset class was previously attached to a USkeletalMesh as a UAssetUserData block. Now the UDNAAsset has been split into:

• UDNA: A new top-level asset (UCLASS(BlueprintType, meta = (DisplayName = "DNA"))) saved in its own .uasset. Owns the unified IDNAReader, the editable FDNAConfig, the FRigLogicConfiguration, and supports bUseOptimizedCooking (cooked-state RigLogic dump).

• UDNAAssetUserData: A small wrapper user-data block on the USkeletalMesh that holds a TObjectPtr<UDNA> reference to the standalone asset.

The legacy UDNAAsset class still exists in 5.8 (now relabelled "Legacy MetaHuman DNA Data") and most of its API is UE_DEPRECATED(5.8). Existing assets continue to load via migration in UDNAAsset::Serialize, but new content is expected to use UDNA.

ConvertLegacyDNAAssets automates the project-wide upgrade in two phases:

Both phases reuse engine-level migration code (UDNAImporter::ConvertFromLegacyAssetUserData, UDNA::Serialize, UDNA::PreSave). The commandlet automatically inherits the engine's correctness guarantees.

Why Use It

Without this commandlet, to upgrade a project you must:

• Right-click each affected USkeletalMesh in the content browser and pick MetaHuman DNA > Create DNA Asset, repeated per character.

• Then run -run=ResavePackages to bump FDNAAssetCustomVersion.

ConvertLegacyDNAAssets does both passes headless, with source-control integration, dry-run reporting, idempotent re-runs, and an exit code suitable for CI.

Switches

The command lines -AutoCheckOut and -AutoCheckIn are supplied to the editor's stock source-control layer; they are recognised by the SCC subsystem the commandlet calls into and are useful in unattended runs.

Behaviour Details

Examples

Single-Step Upgrade (Recommended)

Migrates layout and bumps the on-disk custom version in one invocation:

UnrealEditor-Cmd.exe <Project>.uproject ^
    -run=ConvertLegacyDNAAssets ^
    -PathFilter=/Game/MetaHumans ^
    -ResaveDNA ^
    -AutoCheckOut -AutoCheckIn -Unattended ^
    -NoSplash -NullRHI -stdout -FullStdOutLogOutput

Two-Step Upgrade

This upgrade uses stock ResavePackages.

:: 1) Convert legacy UDNAAsset user-data into standalone UDNA assets
UnrealEditor-Cmd.exe <Project>.uproject ^
    -run=ConvertLegacyDNAAssets ^
    -PathFilter=/Game/MetaHumans ^
    -AutoCheckOut -AutoCheckIn -Unattended

:: 2) Bump FDNAAssetCustomVersion across all DNA-bearing packages
UnrealEditor-Cmd.exe <Project>.uproject ^
    -run=ResavePackages ^
    -PackageFolder=/Game/MetaHumans ^

Dry-Run for Review

Always run a dry-run first on a real project. Reports counts and per-mesh decisions without writing anything:

UnrealEditor-Cmd.exe <Project>.uproject ^
    -run=ConvertLegacyDNAAssets ^
    -PathFilter=/Game/MetaHumans ^
    -ResaveDNA -DryRun -Verbose ^
    -Unattended -NoSplash -NullRHI -stdout -FullStdOutLogOutput

Rebuild Every UDNA

You can rebuild from the source .dna file.  For projects that want canonical configuration applied uniformly (project-default DNAConfig and RigLogicConfiguration) rather than preserving whatever legacy state was serialised:

UnrealEditor-Cmd.exe <Project>.uproject ^
    -run=ConvertLegacyDNAAssets ^
    -PathFilter=/Game/MetaHumans ^
    -ReimportFromSource -ResaveDNA ^
    -AutoCheckOut -AutoCheckIn -Unattended

When the source file is missing for a given mesh and a target <Mesh>_DNA already exists, the mesh is counted as Already migrated and skipped with a warning. When the target does not yet exist, Phase 1 falls through to in-place conversion as a graceful degradation.

Restrict to a Single Character Folder

UnrealEditor-Cmd.exe <Project>.uproject ^
    -run=ConvertLegacyDNAAssets ^
    -PathFilter=/Game/MetaHumans/Hero01 ^
    -ResaveDNA -Unattended

CI-Friendly Invocation

UnrealEditor-Cmd.exe <Project>.uproject ^
    -run=ConvertLegacyDNAAssets ^
    -PathFilter=/Game ^
    -ResaveDNA -NoSCC -Unattended ^
    -NoSplash -NullRHI -stdout -FullStdOutLogOutput
echo Exit code: %ERRORLEVEL%

A non-zero exit code indicates one or more meshes failed to convert or one or more packages failed to save. Inspect Saved\Logs\<Project>.log and grep for LogConvertLegacyDNA.

Naming convention

A converted asset takes the form <MeshName>_DNA in the same content folder as the source USkeletalMesh. For example, SKM_Hero_FaceMesh produces SKM_Hero_FaceMesh_DNA next to it. This matches the _DNA suffix used elsewhere in the engine (InterchangeDnaModule::CreateAndAttachDNAToSkeletalMesh) and is consistent with Epic's broader companion-asset suffix convention (_Skeleton, _PhysicsAsset, _Physics).

Output

A summary block is always printed at the end. Example from a clean applied run:

LogConvertLegacyDNA: Display: ConvertLegacyDNAAssets summary
LogConvertLegacyDNA: Display: Mode: APPLIED
LogConvertLegacyDNA: Display:
LogConvertLegacyDNA: Display: Phase 1 (Convert)
LogConvertLegacyDNA: Display:   Scanned                : 55
LogConvertLegacyDNA: Display:   Converted in place     : 0
LogConvertLegacyDNA: Display:   Reimported from source : 0
LogConvertLegacyDNA: Display:   Already migrated       : 0
LogConvertLegacyDNA: Display:   Skipped (no legacy)    : 55
LogConvertLegacyDNA: Display:   Failed                 : 0

See Also

Deprecations (DNA / SkelMesh APIs)

• UDNAAssetImportFactory::ImportUI / OriginalImportUI: The import-options UI is removed; the factory now reads UDNAConfigHolder from AssetImportTask > Options if present, otherwise auto-detects (§1).

• UDNAAssetImportUI: Class deprecated (renamed to UDEPRECATED_DNAAssetImportUI); the dedicated dialog (SDNAAssetImportWindow, also UE_DEPRECATED(5.8)) is gone.

• UDNAImporterLibrary::ImportSkeletalMeshDNA: Use ImportAndAttachDNA(FileName, USkeletalMesh*, bReplaceExisting).

• UDNAAsset::GetBehaviorReader() / GetGeometryReader() : Use GetDNAReader() (a single unified reader; behavior + geometry are no longer split).

• UDNAAsset::SetBehaviorReader() / SetGeometryReader(): Use SetDNAReader().

• UDNAAsset::GetDnaReaderFromAsset(): Deprecated for the same reason.