Editor-side import plan and catalog for Unity package assets. ImportCatalog reads asset metadata and builds dependency and issue lists by parsing materials, prefabs, scenes, terrains and models. ImportPlan represents a resolved selection snapshot with per-asset planned conversion outputs (VMDL, VMAT, VTEX, SOUND, etc.) based on options and inferred dependencies.
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading;
namespace ImportUnityPackage;
public sealed record ImportDependency( UnityAsset Asset, string Reason );
public sealed record PlannedAsset( UnityAsset Asset, bool Explicit, ImportDependency[] RequiredBy, bool Vmat, bool Tmat, bool Vmdl )
{
public bool Vtex { get; init; }
public bool Sound { get; init; }
public bool Prefab { get; init; }
public bool Scene { get; init; }
public bool Terrain { get; init; }
public bool CanCreateVmdl => Asset.Kind == UnityAssetKind.Model && !Asset.ModelInfo.CollisionOnly && !Asset.ModelInfo.Empty;
public bool CanCreateVmat => Asset.Kind == UnityAssetKind.Material && (!IsTerrainLayer || RequiredBy.Any( p => p.Asset.Kind == UnityAssetKind.Model ));
public bool IsTerrainLayer => Asset.Path.EndsWith( ".terrainlayer", StringComparison.OrdinalIgnoreCase );
public bool CanCreateVtex => Asset.Kind == UnityAssetKind.Texture && UnityImport.NeedsTextureResource( Asset.Path );
public bool CanCreateSound => Asset.Kind == UnityAssetKind.Sound;
public string OutputLabel => Asset.Kind switch
{
UnityAssetKind.Model => Asset.ModelInfo.CollisionOnly ? "Collision source (FBX)" : Asset.ModelInfo.Empty ? "Model source (no geometry)" : Vmdl ? "Model → VMDL" : "Model source",
UnityAssetKind.Material => Vmat && Tmat ? "Material → VMAT + TMAT" : Vmat ? "Material → VMAT" : Tmat ? "Terrain material → TMAT" : "Material source",
UnityAssetKind.Texture => Vtex ? "Texture → VTEX" : "Texture",
UnityAssetKind.Sound => Sound ? "Sound → SOUND" : "Sound source",
UnityAssetKind.Prefab => "Prefab → PREFAB",
UnityAssetKind.Scene => "Scene → SCENE",
UnityAssetKind.Terrain => "Terrain → TERRAIN",
_ => "Model support"
};
}
/// <summary>A selection snapshot shared by the window, importer and import report.</summary>
public sealed class ImportPlan
{
public UnityArchive Archive { get; }
public ImportOptions Options { get; }
public IReadOnlyList<PlannedAsset> Assets { get; }
public IReadOnlyList<ImportIssue> Issues { get; }
/// <summary>How long reading the package's dependency evidence (the catalog) took.</summary>
public long CatalogMilliseconds { get; init; }
readonly Dictionary<UnityAsset, PlannedAsset> byAsset;
internal ImportPlan( UnityArchive archive, ImportOptions options, PlannedAsset[] assets, ImportIssue[] issues )
{
Archive = archive; Options = options; Assets = Array.AsReadOnly( assets ); Issues = Array.AsReadOnly( issues );
byAsset = assets.ToDictionary( a => a.Asset );
}
public PlannedAsset Find( UnityAsset asset ) => byAsset.GetValueOrDefault( asset );
}
/// <summary>Read dependency evidence once, then resolve selections without disk access.</summary>
public sealed class ImportCatalog
{
readonly UnityArchive archive;
readonly Dictionary<UnityAsset, List<ImportDependency>> dependencies = new();
readonly Dictionary<UnityAsset, List<ImportIssue>> issues = new();
ImportCatalog( UnityArchive archive ) { this.archive = archive; }
long readMilliseconds;
public static ImportCatalog Read( UnityArchive archive, CancellationToken cancel = default )
{
var timer = System.Diagnostics.Stopwatch.StartNew();
var catalog = new ImportCatalog( archive );
var byGuid = archive.Assets.ToDictionary( a => a.Guid, StringComparer.OrdinalIgnoreCase );
var materials = new Dictionary<UnityAsset, UnityMaterial>();
void Issue( UnityAsset asset, string code, string message )
{
if ( !catalog.issues.TryGetValue( asset, out var list ) ) catalog.issues[asset] = list = new();
list.Add( new( asset.Path, code, message ) );
}
void Link( UnityAsset parent, UnityAsset child, string reason )
{
if ( !catalog.dependencies.TryGetValue( parent, out var list ) ) catalog.dependencies[parent] = list = new();
if ( !list.Any( d => d.Asset == child && d.Reason == reason ) ) list.Add( new( child, reason ) );
}
// OpenEXR with DWA compression cannot be read by the engine's texture compiler.
foreach ( var asset in archive.Assets.Where( a => a.Kind == UnityAssetKind.Texture && a.Path.EndsWith( ".exr", StringComparison.OrdinalIgnoreCase ) ) )
if ( UnityImageSize.ExrCompression( asset.Source ) is 8 or 9 )
Issue( asset, "unsupported-texture", "The EXR uses DWA compression, which s&box cannot read; re-save it with ZIP or PIZ compression." );
// One text per shader, so its parsed declarations are shared by every material using it.
var shaderSources = new Dictionary<string, string>( StringComparer.OrdinalIgnoreCase );
foreach ( var asset in archive.Assets.Where( a => a.Kind == UnityAssetKind.Material ) )
{
cancel.ThrowIfCancellationRequested();
try
{
var material = UnityMaterial.Parse( UnityImport.ReadText( asset.Source ) );
if ( !string.IsNullOrEmpty( material.ShaderGuid ) && byGuid.TryGetValue( material.ShaderGuid, out var shader ) && (shader.Path.EndsWith( ".shader", StringComparison.OrdinalIgnoreCase ) || shader.Path.EndsWith( ".shadergraph", StringComparison.OrdinalIgnoreCase )) )
material.ConfigureShader( shaderSources.TryGetValue( shader.Guid, out var text ) ? text : shaderSources[shader.Guid] = UnityImport.ReadText( shader.Source ), Path.GetFileNameWithoutExtension( shader.Path ) );
materials[asset] = material;
foreach ( var guid in material.Textures.Values.Distinct( StringComparer.OrdinalIgnoreCase ) )
{
if ( byGuid.TryGetValue( guid, out var texture ) && texture.Kind == UnityAssetKind.Texture ) Link( asset, texture, "Texture reference" );
// Only textures the conversion reads change the result; other missing textures are not problems.
else if ( material.Textures.Any( p => p.Value.Equals( guid, StringComparison.OrdinalIgnoreCase ) && UnityMaterial.ConvertedTextures.Contains( p.Key ) ) )
Issue( asset, "missing-texture", material.MissingTexture( guid ) );
}
}
catch ( InvalidDataException ex ) { Issue( asset, "conversion-skipped", $"Conversion skipped. {ex.Message}" ); }
}
// Prefabs and scenes depend on the models and prefabs they place.
foreach ( var asset in archive.Assets.Where( a => a.Kind is UnityAssetKind.Prefab or UnityAssetKind.Scene ) )
{
cancel.ThrowIfCancellationRequested();
if ( new FileInfo( asset.Source ).Length > 256L * 1024 * 1024 ) { Issue( asset, "conversion-skipped", "Conversion skipped. The file exceeds 256 MiB." ); continue; }
var placementText = File.ReadAllText( asset.Source );
// Renderers on meshes the importer writes itself bring their materials directly.
if ( placementText.Contains( UnityMesh.BuiltinGuid, StringComparison.OrdinalIgnoreCase ) || placementText.Contains( "--- !u!43 ", StringComparison.Ordinal ) ||
UnityPrefabConverter.PlacedAssets( placementText ).Any( g => byGuid.TryGetValue( g, out var placedAsset ) && placedAsset.Path.EndsWith( ".asset", StringComparison.OrdinalIgnoreCase ) ) )
{
try
{
foreach ( var guid in UnityPrefabConverter.GeneratedMeshMaterials( UnityYaml.Parse( placementText ), g => byGuid.TryGetValue( g, out var m ) && m.Kind == UnityAssetKind.Model ).Distinct( StringComparer.OrdinalIgnoreCase ) )
if ( byGuid.TryGetValue( guid, out var material ) && material.Kind == UnityAssetKind.Material ) Link( asset, material, "Material on a generated mesh" );
}
catch ( InvalidDataException ) { }
}
// A scene's skybox material.
foreach ( System.Text.RegularExpressions.Match sky in System.Text.RegularExpressions.Regex.Matches( placementText, @"m_SkyboxMaterial:\s*\{[^}\r\n]*guid:\s*([0-9a-fA-F]{32})" ) )
if ( byGuid.TryGetValue( sky.Groups[1].Value, out var skyMaterial ) && skyMaterial.Kind == UnityAssetKind.Material ) Link( asset, skyMaterial, "Scene skybox" );
foreach ( var guid in UnityPrefabConverter.PlacedAssets( placementText ) )
if ( byGuid.TryGetValue( guid, out var placed ) && placed != asset )
{
if ( placed.Kind == UnityAssetKind.Model ) Link( asset, placed, placed.ModelInfo.CollisionOnly ? "Collision mesh" : asset.Kind == UnityAssetKind.Scene ? "Placed in scene" : "Placed in prefab" );
else if ( placed.Kind == UnityAssetKind.Prefab ) Link( asset, placed, "Nested prefab" );
else if ( placed.Kind == UnityAssetKind.Terrain ) Link( asset, placed, asset.Kind == UnityAssetKind.Scene ? "Terrain in scene" : "Terrain in prefab" );
else if ( placed.Kind == UnityAssetKind.Sound ) Link( asset, placed, asset.Kind == UnityAssetKind.Scene ? "Played in scene" : "Played in prefab" );
}
}
// Terrains depend on their layers' materials and on the prefabs and models painted as trees.
foreach ( var asset in archive.Assets.Where( a => a.Kind == UnityAssetKind.Terrain ) )
{
cancel.ThrowIfCancellationRequested();
try
{
var terrain = asset.TerrainInfo;
foreach ( var layer in terrain.Layers )
if ( layer.HasGuid && byGuid.TryGetValue( layer.Guid, out var material ) && material.Kind == UnityAssetKind.Material ) Link( asset, material, "Terrain layer" );
foreach ( var prototype in terrain.TreePrototypes )
if ( prototype.HasGuid && byGuid.TryGetValue( prototype.Guid, out var tree ) && tree.Kind is UnityAssetKind.Prefab or UnityAssetKind.Model ) Link( asset, tree, "Tree prototype" );
}
catch ( InvalidDataException ex ) { Issue( asset, "conversion-skipped", $"Conversion skipped. {ex.Message}" ); }
}
var byName = archive.Assets.Where( a => a.Kind == UnityAssetKind.Material ).GroupBy( a => Path.GetFileNameWithoutExtension( a.Path ), StringComparer.OrdinalIgnoreCase )
.ToDictionary( g => g.Key, g => g.ToArray(), StringComparer.OrdinalIgnoreCase );
var byTexture = materials.SelectMany( m => m.Value.ColorTextureGuids.Where( byGuid.ContainsKey ).Select( g => (Name: Path.GetFileNameWithoutExtension( byGuid[g].Path ), Asset: m.Key) ) )
.GroupBy( m => m.Name, StringComparer.OrdinalIgnoreCase ).ToDictionary( g => g.Key, g => g.Select( m => m.Asset ).Distinct().ToArray(), StringComparer.OrdinalIgnoreCase );
foreach ( var asset in archive.Assets.Where( a => a.Kind == UnityAssetKind.Model ) )
{
cancel.ThrowIfCancellationRequested();
if ( asset.ModelInfo.ReadError is { } readError ) { Issue( asset, "unreadable-model", $"The model file could not be read ({readError}), so no VMDL is created." ); continue; }
if ( asset.ModelInfo.Empty ) { Issue( asset, "empty-model", "The model has no geometry, so no VMDL is created." ); continue; }
if ( asset.ModelInfo.CollisionOnly ) continue;
foreach ( var warning in asset.ModelInfo.AssignmentWarnings ) Issue( asset, "prefab-material-assignment", warning );
var referencedMaterials = new HashSet<UnityAsset>();
void Match( UnityAsset[] candidates, string reason )
{
var referenced = candidates.Where( referencedMaterials.Contains ).ToArray();
if ( referenced.Length > 0 ) candidates = referenced;
if ( candidates.Length == 1 ) Link( asset, candidates[0], reason + " (inferred)" );
else if ( candidates.Length > 1 ) Issue( asset, "ambiguous-material", $"{reason} matches multiple materials; no dependency was inferred." );
}
var refs = asset.ModelInfo.PrefabMaterials.AsEnumerable();
if ( asset.Metadata != null ) refs = refs.Concat( UnityMaterial.References( UnityImport.ReadText( asset.Metadata ) ) );
foreach ( var guid in refs.Distinct( StringComparer.OrdinalIgnoreCase ) )
if ( byGuid.TryGetValue( guid, out var dependency ) && dependency.Kind is UnityAssetKind.Material or UnityAssetKind.Texture )
{
Link( asset, dependency, "Model / prefab reference" );
if ( dependency.Kind == UnityAssetKind.Material ) referencedMaterials.Add( dependency );
}
// Every prefab variant's materials are imported, so each variant can become a material group.
foreach ( var variant in asset.ModelInfo.PrefabVariants )
foreach ( var guid in variant.Slots.Values )
if ( byGuid.TryGetValue( guid, out var material ) && material.Kind == UnityAssetKind.Material )
{
Link( asset, material, "Prefab material variant" );
referencedMaterials.Add( material );
}
var importer = asset.ModelInfo.ImporterMaterials;
foreach ( var (slot, source) in importer )
if ( byGuid.TryGetValue( source.Guid, out var material ) )
{
Link( asset, material, source.Rule == UnityModelMaterials.ExternalObject ? $"Model import remap for slot {slot}" : $"Unity material search for slot {slot}" );
referencedMaterials.Add( material );
}
foreach ( var (slot, filename) in asset.ModelInfo.MaterialAlbedoFiles.Where( p => !importer.ContainsKey( p.Key ) ) ) Match( byTexture.GetValueOrDefault( Path.GetFileNameWithoutExtension( filename ), Array.Empty<UnityAsset>() ), $"Color texture {filename}" );
foreach ( var slot in asset.ModelInfo.RenderedMaterials.Where( s => !asset.ModelInfo.PrefabSlotMaterials.ContainsKey( s ) && !asset.ModelInfo.UnresolvedPrefabSlots.Contains( s ) && !importer.ContainsKey( s ) ) ) Match( byName.GetValueOrDefault( slot, Array.Empty<UnityAsset>() ), $"Material slot {slot}" );
Match( byName.GetValueOrDefault( Path.GetFileNameWithoutExtension( asset.Path ), Array.Empty<UnityAsset>() ), "Model filename" );
}
catalog.readMilliseconds = timer.ElapsedMilliseconds;
return catalog;
}
public ImportPlan CreatePlan( ImportOptions options )
{
var explicitAssets = archive.Assets.Where( a => a.Selected && UnityImport.IsEnabled( a, options ) ).ToHashSet();
var included = new HashSet<UnityAsset>( explicitAssets );
var requiredBy = new Dictionary<UnityAsset, List<ImportDependency>>();
var queue = new Queue<UnityAsset>( included );
while ( queue.TryDequeue( out var parent ) )
{
if ( !dependencies.TryGetValue( parent, out var children ) ) continue;
foreach ( var child in children )
{
// Without materials, only the models and prefabs that prefabs and scenes place are dependencies.
if ( !options.Materials && child.Asset.Kind is not (UnityAssetKind.Model or UnityAssetKind.Prefab or UnityAssetKind.Terrain or UnityAssetKind.Sound) ) continue;
if ( !UnityImport.IsEnabled( child.Asset, options ) ) continue;
if ( !requiredBy.TryGetValue( child.Asset, out var parents ) ) requiredBy[child.Asset] = parents = new();
parents.Add( new( parent, child.Reason ) );
if ( included.Add( child.Asset ) ) queue.Enqueue( child.Asset );
}
}
var entries = included.OrderBy( a => a.Kind == UnityAssetKind.Model ? 1 : 0 ).ThenBy( a => a.Path, StringComparer.OrdinalIgnoreCase ).Select( a =>
{
var parents = requiredBy.GetValueOrDefault( a )?.ToArray() ?? Array.Empty<ImportDependency>();
var terrain = a.Path.EndsWith( ".terrainlayer", StringComparison.OrdinalIgnoreCase );
var modelUse = parents.Any( p => p.Asset.Kind == UnityAssetKind.Model );
return new PlannedAsset( a, explicitAssets.Contains( a ), parents,
a.Kind == UnityAssetKind.Material && options.Vmat && (!options.Automatic || !terrain || modelUse),
a.Kind == UnityAssetKind.Material && options.TerrainDefinitions && (options.Tmat && (!options.Automatic || options.Vmat) || options.Automatic && terrain),
a.Kind == UnityAssetKind.Model && options.Vmdl && !a.ModelInfo.CollisionOnly && !a.ModelInfo.Empty )
{
Vtex = a.Kind == UnityAssetKind.Texture && options.Vtex && UnityImport.NeedsTextureResource( a.Path ),
Sound = a.Kind == UnityAssetKind.Sound && options.Sound,
Prefab = a.Kind == UnityAssetKind.Prefab,
Scene = a.Kind == UnityAssetKind.Scene,
Terrain = a.Kind == UnityAssetKind.Terrain
};
} ).ToArray();
return new( archive, options, entries, entries.Where( a => a.Vmat || a.Tmat || a.Vmdl && options.Materials || a.Prefab || a.Scene || a.Terrain || a.Vtex || a.Asset.Kind == UnityAssetKind.Model && a.Asset.ModelInfo.Empty )
.Where( a => issues.ContainsKey( a.Asset ) ).SelectMany( a => issues[a.Asset] ).Distinct().ToArray() ) { CatalogMilliseconds = readMilliseconds };
}
}