Skip to content

Game.AssetPipeline.AssetImportPipeline

Assembly: Assembly-CSharp
Namespace: Game.AssetPipeline

Type: static class

Base: System.Object

Summary:
AssetImportPipeline is the central static helper for importing art/content into Cities: Skylines 2. It implements the pipeline used by the modding toolchain to collect source files, run importer(s) and post-processors, create Geometry/Surface/Prefab objects, serialize them into the asset database, and optionally convert materials to the engine's Virtual Texturing (VT) format. The pipeline supports parallel import (configurable), progress reporting, and a number of helper utilities such as JSON schema generation for settings, VT mid‑mip cache generation, and debug instantiation of created render prefabs.

Fields

  • private static readonly ILog log
    Logger used throughout the pipeline to report info/warnings/errors.

  • private const string kMainSettings
    Constant "settings.json" used to detect project settings files.

  • public static bool useParallelImport
    Controls whether heavy import phases (models/textures) use parallelism. Default true.

  • public static ILocalAssetDatabase targetDatabase
    Database instance used to save generated assets (geometry, surfaces, VT data, etc.). Must be set before importing.

  • private static readonly ProfilerMarker s_ImportPath
    Profiler marker for the ImportPath entry point.

  • private static readonly ProfilerMarker s_ProfPostImport
    Profiler marker for post-import (main thread) work.

  • private static readonly ProfilerMarker s_ProfImportModels
    Profiler marker for model import phase.

  • private static readonly ProfilerMarker s_ProfImportTextures
    Profiler marker for texture import phase.

  • private static readonly ProfilerMarker s_ProfCreateGeomsSurfaces
    Profiler marker for creating geometries and surfaces.

  • private static readonly ProfilerMarker s_ProfImportAssetGroup
    Profiler marker for importing a single asset group.

  • private static readonly ProfilerMarker s_ProfImportDidimo
    Profiler marker for the didimo/character import pipeline.

  • private static readonly Progress s_Progress
    Internal progress tracker used for reporting progress and cancellation support.

  • private static MainThreadDispatcher s_MainThreadDispatcher
    Queue/dispatcher used to schedule tasks that must run on Unity's main thread during an import.

  • public static Action<string, Texture> OnDebugTexture
    Optional debug callback invoked when a debug texture is produced.

  • private static Material s_BackgroundMaterial
    Lazy-created material used by debug helpers (title backgrounds when instantiating prefabs in the editor).

  • private const float kBoundSize
    Layout constant used by debug instantiation.

  • private const float kHalfBoundSize
    Layout constant used by debug instantiation.

Properties

  • public static Material backgroundMaterial { get; }
    Lazily initializes and returns a simple HDRP/Unlit white Material used for background quads in prefab instantiation helpers.

  • public static bool useParallelImport
    Toggle for enabling/disabling parallel import passes (textures/models).

  • public static ILocalAssetDatabase targetDatabase
    The destination database used to add and save assets created by the pipeline.

  • public static Action<string, Texture> OnDebugTexture
    Hook to receive debug textures generated during import/post-process.

Constructors

  • static AssetImportPipeline()
    Static constructor that initializes logger, profiler markers, the progress object and warms importer/post-processor caches. Called once when the type is first used.

Methods

  • public static void SetReportCallback(Func<string, string, float, bool> progressCallback)
    Sets or resets the progress/cancellation callback used during long-running import operations.

  • public static async Task ImportPath(string projectRootPath, IEnumerable<string> relativePaths, ImportMode importMode, bool convertToVT, Func<string, string, float, bool> progressCallback = null, IPrefabFactory prefabFactory = null)
    Main high-level entry. Collects source assets under projectRootPath, runs importers/post-processors, schedules main-thread serialization and prefab creation tasks, optionally converts surfaces to VT. Reports progress via the callback and returns when the whole import completes.

  • private static Colossal.AssetPipeline.Settings ImportSettings(SourceAssetCollector.AssetGroup<SourceAssetCollector.Asset> assetGroup, (Report.ImportStep step, Report.Asset asset) report)
    Loads and returns pipeline settings for an asset group, falling back to defaults and expanding them if no settings.json was provided.

  • private static SourceAssetCollector.AssetGroup<IAsset> CreateAssetGroupFromSettings(string projectRootPath, Colossal.AssetPipeline.Settings settings, SourceAssetCollector.AssetGroup<SourceAssetCollector.Asset> assetGroup, Report.Asset assetReport)
    Builds the collection of IAsset (typed assets) for the group based on settings. Also injects shared/fallback shader assets declared in settings.

  • private static void ImportTextures(Colossal.AssetPipeline.Settings settings, string relativeRootPath, SourceAssetCollector.AssetGroup<IAsset> assetGroup, Func<Colossal.AssetPipeline.TextureAsset, bool> predicate, (Report.ImportStep step, Report.Asset asset) report)
    Imports textures using configured TextureImporter and runs any texture post-processors. Collects stats (file format, NPOT, bpp, etc.).

  • private static void ImportModels(Colossal.AssetPipeline.Settings settings, string relativeRootPath, SourceAssetCollector.AssetGroup<IAsset> assetGroup, (Report.ImportStep step, Report.Asset asset) report)
    Imports models using ModelImporter, attaches model post processors and model-surface post processors when applicable.

  • private static void ImportDidimo(Colossal.AssetPipeline.Settings settings, SourceAssetCollector.AssetGroup<IAsset> assetGroup, (Report.ImportStep step, Report.Asset asset) report)
    Specialized importer flow for Didimo character assets (animations + didimo data).

  • private static void CreateGeometriesAndSurfaces(Colossal.AssetPipeline.Settings settings, string relativeRootPath, SourceAssetCollector.AssetGroup<IAsset> assetGroup, out Action<string, ImportMode, Report, HashSet<SurfaceAsset>, IPrefabFactory> postImportOperations, (Report parent, Report.Asset asset) report)
    Builds Geometry and Surface objects from imported models and textures. Collects geometry LODs and surfaces, runs geometry post-processors, and returns a postImportOperations delegate which performs main-thread serialization and prefab creation.

  • private static void CreateDidimoAssets(Colossal.AssetPipeline.Settings settings, string relativeRootPath, SourceAssetCollector.AssetGroup<IAsset> assetGroup, out Action<string, ImportMode, Report, HashSet<SurfaceAsset>, IPrefabFactory> postImportOperations, (Report parent, Report.ImportStep step, Report.Asset asset) report)
    Builds character assets (RenderPrefabs, CharacterStyles, CharacterGroups) from Didimo import output, including animation/alignment handling and generating animation assets in the database. Returns a postImportOperations delegate for finalization.

  • private static bool ImportAssetGroup(string projectRootPath, string relativeRootPath, SourceAssetCollector.AssetGroup<SourceAssetCollector.Asset> assetGroup, out List<List<Colossal.AssetPipeline.LOD>> lods, out Action<string, ImportMode, Report, HashSet<SurfaceAsset>, IPrefabFactory> postImportOperations, Report report, Report.Asset assetReport)
    Imports a single asset group: loads settings, creates asset group, runs texture/model import and geometry/surface/didimo pipelines depending on configured pipeline.

  • private static IReadOnlyList<(RenderPrefab prefab, Report.Prefab report)> CreateRenderPrefab(Colossal.AssetPipeline.Settings settings, string sourcePath, IReadOnlyList<Colossal.AssetPipeline.LOD> asset, ImportMode importMode, Report report, HashSet<SurfaceAsset> VTMaterials, IPrefabFactory prefabFactory = null)
    Creates RenderPrefab objects from a single asset LOD list, serializes Geometry/Surface assets into the targetDatabase when requested (geometry/textures), and sets up per-prefab components.

  • private static void CreateRenderPrefabs(Colossal.AssetPipeline.Settings settings, string sourcePath, IReadOnlyList<List<Colossal.AssetPipeline.LOD>> assets, ImportMode importMode, Report report, HashSet<SurfaceAsset> VTMaterials, IPrefabFactory prefabFactory = null)
    Orchestrates creation of all RenderPrefabs for a logical asset and runs SetupLODs and SetupComponents.

  • private static void SetupLODs(Colossal.AssetPipeline.Settings settings, IReadOnlyList<(RenderPrefab prefab, Report.Prefab report)> meshPrefabs)
    Adds and links LOD components (LodProperties) between created render prefabs.

  • private static void SetupComponents(Colossal.AssetPipeline.Settings settings, RenderPrefab meshPrefab, Colossal.AssetPipeline.LOD lod, Report.Prefab report)
    Hook to attach components such as EmissiveProperties or ProceduralAnimationProperties based on settings and LOD content.

  • private static void SetupEmissiveComponent(...) (two overloads)
    Inspect surfaces for emissive textures/layers and fill or warn about EmissiveProperties on the prefab.

  • private static void SetupProceduralAnimationComponent(Colossal.AssetPipeline.Settings settings, RenderPrefab meshPrefab, Colossal.AssetPipeline.LOD lod, Report.Prefab report)
    Extracts skinning/bone info from geometry and creates ProceduralAnimationProperties.BoneInfo entries on the prefab. Warns when skeletal data is missing or inconsistent.

  • private static bool IsLODsValid(IReadOnlyList<List<Colossal.AssetPipeline.LOD>> assets)
    Validates that produced LODs contain at least geometry or surfaces and that they are valid.

  • private static void DisposeLODs(IReadOnlyList<IReadOnlyList<Colossal.AssetPipeline.LOD>> assets)
    Disposes temporary geometry/surface resources created during import.

  • private static TTo CastStruct<TFrom, TTo>(TFrom s) where TFrom : struct where TTo : struct
    Utility performing reinterpret-cast between unmanaged structs using UnsafeUtility.

  • private unsafe static NativeArray<byte> FromManagedArray<T>(T[] array) where T : unmanaged
    Copies a managed unmanaged-type array into a NativeArray (used when building mesh attribute buffers).

  • private unsafe static NativeArray<byte> FromManagedArray<T>(T[] array, int offset, int elementSize, int countPerElement) where T : unmanaged
    Overload which supports interleaved copies with stride.

  • private static string AdjustNamingConvention(string input)
    Utility creating Pascal-like names from underscored names (used to normalize names from external sources like Didimo).

  • public static IEnumerable<ISettingable> GetImportChainFor(Colossal.AssetPipeline.Settings settings, SourceAssetCollector.Asset asset, ReportBase report)
    Returns the chain of importer + post-processors that would be executed for a given source asset according to current caches/settings. Useful for diagnostics or GUI display.

  • public static IDictionary<SourceAssetCollector.AssetGroup<SourceAssetCollector.Asset>, Colossal.AssetPipeline.Settings> CollectDataToImport(string projectRootPath, string[] assetPaths, Report report)
    Convenience for collecting and grouping paths into asset groups, returning their resolved settings without performing full import.

  • public static void GenerateJSONSchema()
    Builds and logs a JSON schema describing settings types and post-processor settings. Useful for editor integration and validating settings.json files.

  • public static void InstantiateRenderPrefabs<T>(IEnumerable<(T prefab, string sourcePath)> prefabs, bool smartInstantiate, bool ignoreLODs) where T : PrefabBase
    Editor/debug helper to instantiate visual representations of RenderPrefabs in the scene. Supports "smart" layout grouped by source project and creates debug titles/backgrounds.

  • public static Dictionary<Colossal.IO.AssetDatabase.TextureAsset, List<SurfaceAsset>> GetTextureReferenceCount(IEnumerable<SurfaceAsset> surfaces, out int surfaceCount)
    Collects texture -> list of surfaces references to compute sharing and assist VT conversion decisions.

  • public static void ProcessSurfacesForVT(IEnumerable<SurfaceAsset> surfacesToConvert, IEnumerable<SurfaceAsset> surfaces, bool force, Report.ImportStep report)
    Top-level VT workflow: Convert surfaces to VT (ConvertSurfacesToVT), build the mid-mip cache, hide VT source textures and resave the cache.

  • public static void ConvertSurfacesToVT(IEnumerable<SurfaceAsset> surfacesToConvert, IEnumerable<SurfaceAsset> allSurfaces, bool writeVTSettings, int tileSize, int midMipsCount, int mipBias, bool force, Report.ImportStep report)
    Actual conversion implementation which validates uniform texture sizes, material support, and writes converted VT surfaces to disk/database. Optionally writes VT settings file.

  • public static void BuildMidMipsCache(IEnumerable<SurfaceAsset> surfaces, int tileSize, int midMipsCount, ILocalAssetDatabase database)
    Builds and serializes a MidMipCache asset used by the VT system from a set of converted VT surface assets. This is a heavy operation that groups and atlases mid mips.

  • public static async Task ApplyVTMipBias(IAssetDatabase database, int mipBias, int tileSize, int midMipCount, string folder)
    Rebuilds VT preprocessed textures (VTTextureAsset) with a different mip bias and writes them to a transient local database/folder. Schedules main-thread actions via the internal dispatcher and awaits completion.

  • public static void HideVTSourceTextures(IEnumerable<SurfaceAsset> surfaces)
    Scans and logs which texture assets will be hidden/duplicated due to VT conversion (VT materials reference preprocessed textures that will be replaced).

  • private static string GetSettings() (helper)
    Builds a combined JSON-if/then description for all available importer/post-processor default settings for use in the schema generator.

  • Other various private helpers for naming, path resolution, progress/main-thread queue execution and small utilities used across the pipeline.

Usage Example

// Example: Import a list of relative asset folders into a target local database.
// Must set AssetImportPipeline.targetDatabase to an ILocalAssetDatabase (e.g. AssetDatabase.game or a transient database).

AssetImportPipeline.targetDatabase = AssetDatabase.game;
AssetImportPipeline.useParallelImport = true;

// Optional progress callback (title, description, progressFraction) -> return true to cancel
AssetImportPipeline.SetReportCallback((title, desc, fraction) =>
{
    Debug.Log($"{title}: {desc} ({fraction:P0})");
    return false; // return true to request cancellation
});

// Import synchronously from an async context (await)
await AssetImportPipeline.ImportPath(
    projectRootPath: "C:/MyProjects/MyArtProject",
    relativePaths: new[] { "Props/Bench", "Props/Lamp" },
    importMode: ImportMode.Geometry | ImportMode.Textures,
    convertToVT: true,
    progressCallback: null,
    prefabFactory: null
);

// After import, you can instantiate generated RenderPrefabs in the scene for preview:
var prefabs = AssetDatabase.game.GetAssets(default(SearchFilter<RenderPrefab>))
    .Select(p => (prefab: p.Load(), sourcePath: p.name)); // simplified example
AssetImportPipeline.InstantiateRenderPrefabs(prefabs, smartInstantiate: true, ignoreLODs: true);