feat: asset usage audit plugin
Editor tool for the LA and 3D departments: which assets each level uses, which are used nowhere, and export of a chosen set. Three modules. AssetUsageAuditCore holds the whole analysis and links no UI and no editor-only asset pipeline, so it stays runnable from a commandlet; AssetUsageAuditEditor holds the Slate panel and everything that needs UnrealEd or AssetTools; AssetUsageAuditTests holds 152 specs. Load-bearing decisions, each of which produces a wrong answer if undone: - Dependency queries are always Package + NoRequirements, never Hard. The map-to-external-actor edges the OFPA gatherer emits carry Game|Build without Hard, so a Hard query drops all 16117 external actor packages in this project. There is deliberately no Hard constant in the code. - Crossing into another map is allowed only from a level or its external actor package. Without that rule WP_Main reported 18136 assets, of which 9994 belonged to L_MainLevel, reached through the GameMode. - The verdict has five states, never a bool. The registry cannot see FMOD events, DataTable rows or string-built paths; those are Unknown, and the tool never proposes a deletion. - Copying .uasset files does not preserve references - they are stored as full package paths. Only the Migrate layout produces something Unreal can open; the others write a manifest so the graph can be rebuilt. Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,43 @@
|
||||
// NextGenium 2026. Asset Usage Audit.
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "CoreMinimal.h"
|
||||
#include "Modules/ModuleManager.h"
|
||||
|
||||
class IConsoleObject;
|
||||
class SDockTab;
|
||||
class FSpawnTabArgs;
|
||||
|
||||
ASSETUSAGEAUDITEDITOR_API DECLARE_LOG_CATEGORY_EXTERN(LogAssetUsageAuditEditor, Log, All);
|
||||
|
||||
/**
|
||||
* Editor-side host: settings, console entry points and (from phase 3) the Slate panel.
|
||||
*
|
||||
* All analysis lives in AssetUsageAuditCore. This module only drives it and presents results,
|
||||
* so a commandlet can reach exactly the same code path without dragging UI in.
|
||||
*/
|
||||
class FAssetUsageAuditEditorModule : public IModuleInterface
|
||||
{
|
||||
public:
|
||||
virtual void StartupModule() override;
|
||||
virtual void ShutdownModule() override;
|
||||
|
||||
/** Nomad tab id, also used as the invoke target from the Tools menu. */
|
||||
static const FName PanelTabId;
|
||||
|
||||
private:
|
||||
void RegisterConsoleCommands();
|
||||
void UnregisterConsoleCommands();
|
||||
|
||||
void RegisterTabSpawner();
|
||||
void UnregisterTabSpawner();
|
||||
void RegisterMenus();
|
||||
|
||||
TSharedRef<SDockTab> SpawnPanelTab(const FSpawnTabArgs& Args);
|
||||
|
||||
/** Shared implementation behind every console entry point. */
|
||||
void ExecuteAudit(const TArray<FString>& Args, bool bOnlyUnused);
|
||||
|
||||
TArray<IConsoleObject*> ConsoleCommands;
|
||||
};
|
||||
@@ -0,0 +1,61 @@
|
||||
// NextGenium 2026. Asset Usage Audit.
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "CoreMinimal.h"
|
||||
#include "Kismet/BlueprintFunctionLibrary.h"
|
||||
#include "AssetUsageAuditLibrary.generated.h"
|
||||
|
||||
/**
|
||||
* Blueprint and Python entry points for the audit.
|
||||
*
|
||||
* Phase 1 uses these as the only way to run the analysis, before the Slate panel exists. They
|
||||
* remain useful afterwards: a TA can script a one-off audit from an Editor Utility Widget without
|
||||
* touching the main tool, and the same calls drive the Python bridge.
|
||||
*
|
||||
* These are thin wrappers. All logic lives in AssetUsageAuditCore so that the panel, these
|
||||
* functions and a future commandlet cannot drift apart.
|
||||
*/
|
||||
UCLASS()
|
||||
class ASSETUSAGEAUDITEDITOR_API UAssetUsageAuditLibrary : public UBlueprintFunctionLibrary
|
||||
{
|
||||
GENERATED_BODY()
|
||||
|
||||
public:
|
||||
/**
|
||||
* Run a full audit and write JSON + CSV reports.
|
||||
*
|
||||
* @param LevelPackageNames Levels to analyse, e.g. "/Game/Space/Maps/WP_Main". Empty means all.
|
||||
* @param OutputDirectory Destination. Empty uses the configured default.
|
||||
* @param OutReportPath Absolute path of the JSON report on success.
|
||||
* @return true when both reports were written.
|
||||
*/
|
||||
UFUNCTION(BlueprintCallable, Category = "Asset Usage Audit", meta = (AutoCreateRefTerm = "LevelPackageNames"))
|
||||
static bool RunAudit(const TArray<FString>& LevelPackageNames, const FString& OutputDirectory, FString& OutReportPath);
|
||||
|
||||
/**
|
||||
* Assets reachable from one level, resolved transitively through Blueprints and other assets.
|
||||
*
|
||||
* This is the question the tool exists to answer, exposed on its own for scripting.
|
||||
*/
|
||||
UFUNCTION(BlueprintCallable, Category = "Asset Usage Audit")
|
||||
static TArray<FString> GetAssetsUsedOnLevel(const FString& LevelPackageName);
|
||||
|
||||
/**
|
||||
* Levels that use the given asset.
|
||||
*
|
||||
* Includes both a sublevel and its parent map when the asset sits in a sublevel, because the
|
||||
* parent's traversal reaches through ULevelStreaming::WorldAsset.
|
||||
*/
|
||||
UFUNCTION(BlueprintCallable, Category = "Asset Usage Audit")
|
||||
static TArray<FString> GetLevelsUsingAsset(const FString& AssetPackageName);
|
||||
|
||||
/**
|
||||
* Time a full sweep and log the breakdown.
|
||||
*
|
||||
* Exists to answer the open question in the plan: whether an in-memory graph cache is needed
|
||||
* at all. Measure before adding one.
|
||||
*/
|
||||
UFUNCTION(BlueprintCallable, Category = "Asset Usage Audit")
|
||||
static float MeasureFullSweepSeconds();
|
||||
};
|
||||
@@ -0,0 +1,90 @@
|
||||
// NextGenium 2026. Asset Usage Audit.
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "CoreMinimal.h"
|
||||
#include "AssetUsageAuditTypes.h"
|
||||
#include "Engine/DeveloperSettings.h"
|
||||
#include "AssetUsageAuditSettings.generated.h"
|
||||
|
||||
/**
|
||||
* Team-shared configuration, written to Config/DefaultEditor.ini.
|
||||
*
|
||||
* That file is Perforce-tracked (only Plugins/** is p4-ignored), so the exclusion list and the
|
||||
* type presets are reviewable and shared. Per-user state - last filter, column layout - belongs
|
||||
* in UAssetUsageAuditUserSettings instead, which stays in Saved/Config.
|
||||
*/
|
||||
UCLASS(config = Editor, defaultconfig, meta = (DisplayName = "Asset Usage Audit"))
|
||||
class ASSETUSAGEAUDITEDITOR_API UAssetUsageAuditSettings : public UDeveloperSettings
|
||||
{
|
||||
GENERATED_BODY()
|
||||
|
||||
public:
|
||||
UAssetUsageAuditSettings();
|
||||
|
||||
/** Default folder for exported files and reports. Empty means <Project>/Saved/AssetUsageAudit. */
|
||||
UPROPERTY(config, EditAnywhere, Category = "Export", meta = (ToolTip = "Default destination for exported assets and reports. Leave empty to use Saved/AssetUsageAudit."))
|
||||
FString DefaultExportDirectory;
|
||||
|
||||
/** Overwrite existing files on export, or add/increment a numeric suffix. */
|
||||
UPROPERTY(config, EditAnywhere, Category = "Export", meta = (ToolTip = "When a file of the same name already exists: replace it, or write Foo_1, Foo_2 and so on."))
|
||||
bool bOverwriteExistingFiles = false;
|
||||
|
||||
/**
|
||||
* Asset class short name -> interchange file extension, used by the "Convert" export mode.
|
||||
*
|
||||
* Empty falls back to the built-in table. Lookup follows the class hierarchy, so one entry for
|
||||
* MaterialInterface would cover every material instance. Only add a class the engine ships a
|
||||
* UExporter for: an entry with no exporter behind it produces no file and reads as a bug.
|
||||
*/
|
||||
UPROPERTY(config, EditAnywhere, Category = "Export", meta = (ToolTip = "Which file format each asset class converts to, e.g. StaticMesh -> fbx. Leave empty for the built-in defaults."))
|
||||
TMap<FString, FString> ExchangeFormatByClass;
|
||||
|
||||
/**
|
||||
* How exported files are arranged under the destination.
|
||||
*
|
||||
* Replaced an earlier bMirrorFolderStructure boolean. Adding "one folder per asset" as a second
|
||||
* boolean would have made "mirror the tree AND a folder per asset" expressible, and it means
|
||||
* nothing - the enum makes the three arrangements mutually exclusive, which they are.
|
||||
*/
|
||||
UPROPERTY(config, EditAnywhere, Category = "Export", meta = (ToolTip = "Flat: every file side by side. Mirror: recreate the /Game tree. Folder per asset: each ticked asset gets its own folder with its dependencies beside it."))
|
||||
EExportLayout ExportLayout = EExportLayout::Flat;
|
||||
|
||||
/**
|
||||
* Within each asset's folder, sort its dependencies into per-type subfolders.
|
||||
*
|
||||
* Only has an effect with the folder-per-asset layout - the other two have no per-asset folder
|
||||
* to sort inside. Folder names come from the same type presets the Types filter shows, so the
|
||||
* folders match the words used to filter.
|
||||
*/
|
||||
UPROPERTY(config, EditAnywhere, Category = "Export", meta = (EditCondition = "ExportLayout == EExportLayout::FolderPerAsset", ToolTip = "Put textures, materials and meshes into their own subfolders inside each asset's folder."))
|
||||
bool bGroupDependenciesByType = false;
|
||||
|
||||
/**
|
||||
* Package or content-relative prefixes excluded from the sweep.
|
||||
*
|
||||
* Defaults cover this project's bought content packs. Roughly 65% of the project's assets are
|
||||
* third-party, so without this the report is dominated by content nobody audits.
|
||||
*/
|
||||
UPROPERTY(config, EditAnywhere, Category = "Filtering", meta = (ToolTip = "Folders to skip entirely. Accepts /Game/... or Content/... form."))
|
||||
TArray<FString> ExcludedPackagePaths;
|
||||
|
||||
/** Roots to sweep. Empty means /Game. */
|
||||
UPROPERTY(config, EditAnywhere, Category = "Filtering", meta = (ToolTip = "Folders to analyse. Leave empty to sweep all of /Game."))
|
||||
TArray<FString> IncludedPackagePaths;
|
||||
|
||||
/** Read Config/ and Source/ for path literals the Asset Registry cannot see. */
|
||||
UPROPERTY(config, EditAnywhere, Category = "Filtering", meta = (ToolTip = "Scan Config/ and Source/ for /Game paths. Without this the project's GameMode and GameInstance report as unused, because only DefaultEngine.ini names them."))
|
||||
bool bScanIndirectReferences = true;
|
||||
|
||||
/** Hide __ExternalActors__ / __ExternalObjects__ rows; they are plumbing, not artist-facing. */
|
||||
UPROPERTY(config, EditAnywhere, Category = "Filtering", meta = (ToolTip = "Hide One File Per Actor packages from the results. They are still traversed."))
|
||||
bool bHideExternalPackages = true;
|
||||
|
||||
static const UAssetUsageAuditSettings* Get();
|
||||
|
||||
/** Resolved absolute export directory, applying the Saved/AssetUsageAudit fallback. */
|
||||
FString GetResolvedExportDirectory() const;
|
||||
|
||||
virtual FName GetCategoryName() const override;
|
||||
};
|
||||
@@ -0,0 +1,75 @@
|
||||
// NextGenium 2026. Asset Usage Audit.
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "CoreMinimal.h"
|
||||
#include "Engine/DeveloperSettings.h"
|
||||
#include "AssetUsageAuditUserSettings.generated.h"
|
||||
|
||||
/**
|
||||
* Per-user panel state, written to Saved/Config/.../EditorPerProjectUserSettings.ini.
|
||||
*
|
||||
* Separate from UAssetUsageAuditSettings on purpose. That one is DefaultConfig and lands in
|
||||
* Config/DefaultEditor.ini, which is version-controlled: exclusion lists and export formats are
|
||||
* team decisions and should be reviewable. Which types someone happened to tick last Tuesday is
|
||||
* not, and committing it would make every teammate's panel jump around on sync.
|
||||
*
|
||||
* Not shown in Project Settings - GetCategoryName is inherited but the class carries no
|
||||
* EditAnywhere properties, so there is nothing to render. This is state, not configuration.
|
||||
*/
|
||||
UCLASS(config = EditorPerProjectUserSettings)
|
||||
class ASSETUSAGEAUDITEDITOR_API UAssetUsageAuditUserSettings : public UDeveloperSettings
|
||||
{
|
||||
GENERATED_BODY()
|
||||
|
||||
public:
|
||||
static UAssetUsageAuditUserSettings* Get();
|
||||
|
||||
/** Audit scope: level packages to sweep. Empty means all levels. */
|
||||
UPROPERTY(config)
|
||||
TArray<FString> LastLevelPackages;
|
||||
|
||||
/** Short class names ticked in the type menu. */
|
||||
UPROPERTY(config)
|
||||
TArray<FString> VisibleTypeNames;
|
||||
|
||||
/** Substring filter on a Blueprint's generated class. */
|
||||
UPROPERTY(config)
|
||||
FString GeneratedClassFilter;
|
||||
|
||||
/**
|
||||
* Verdicts left visible, by name rather than by index.
|
||||
*
|
||||
* Names because the enum will gain values: an index saved today would silently mean a different
|
||||
* verdict after the next one is inserted, and the user would find their filter quietly changed.
|
||||
*/
|
||||
UPROPERTY(config)
|
||||
TArray<FString> VisibleVerdictNames;
|
||||
|
||||
/** EAuditViewMode as an integer. Validated on load. */
|
||||
UPROPERTY(config)
|
||||
int32 ViewMode = 0;
|
||||
|
||||
/** EFileExportMode as an integer. Validated on load. */
|
||||
UPROPERTY(config)
|
||||
int32 ExportMode = 0;
|
||||
|
||||
/** EReferenceStrengthFilter as an integer. Validated on load. */
|
||||
UPROPERTY(config)
|
||||
int32 ReferenceStrength = 0;
|
||||
|
||||
/** EAssetUsageProvenance bitmask that a row must carry. */
|
||||
UPROPERTY(config)
|
||||
int32 RequiredProvenance = 0;
|
||||
|
||||
/** Whether the export pulls in referenced assets. */
|
||||
UPROPERTY(config)
|
||||
bool bIncludeDependencies = true;
|
||||
|
||||
/**
|
||||
* Deliberately absent: the search box.
|
||||
*
|
||||
* Restoring it would reopen the panel showing nothing, with the reason sitting in a text field
|
||||
* the user is not looking at. A filter that hides everything must be something they just typed.
|
||||
*/
|
||||
};
|
||||
Reference in New Issue
Block a user