SimpleAssetCleaner User Manual

SimpleAssetCleaner automatically identifies and removes unreferenced assets in Unreal Engine projects to keep repositories tidy.

Important: This plugin can delete assets from version control. Read carefully before use.

Compatibility: Unreal Engine 5.2–5.8

• Only assets in the project’s /Content/ folder (/Game/ path)

• Plugin assets such as /PluginName/Content/
• Engine assets
• Code files (C++ headers/source files)
• References outside /Content/

The plugin uses reference-chain analysis:

1. Root assets - Always considered “in use,” such as maps, Blueprints, and DataAssets
2. Reference chains - Assets directly or indirectly referenced by roots are considered “in use”
3. Unreferenced assets - Assets unreachable from every root are cleaned up

• Triggered when opening the version control submission dialog
• Checks only newly added files
• Reverts unreferenced files from version control
• Local copies are safe - Files are not deleted from disk

When submitting a changelist, the plugin automatically checks dependencies of assets being submitted. If dependent files are not yet under version control, a dialog lists them. Select the dependencies to add using checkboxes; confirming automatically adds them to version control.

• Trigger: Automatically when submitting a changelist
• Detection: Files depended on by pending assets that are not yet under version control
• Operation: A dialog lists untracked dependencies; select and confirm to add them
• Toggle: Enable or disable this through “Enable Auto Add Dependencies” in settings

Right-click folders or assets in the Content Browser and choose the Simple Asset Cleaner submenu for these features:

Scans assets in the selection and displays unreferenced assets with checkboxes. Cleanup runs after the user selects and confirms them.

• Supports selecting one or multiple files or folders
• Newly added files: reverted, with local copies retained
• Tracked files: deleted from both server and local disk

Checks dependencies of selected assets, finds files outside version control, and lists them for user confirmation before adding them.

• Supports selecting one or multiple files or folders

The context menu acts precisely on the selection, making it suitable for everyday cleanup and dependency checks on particular directories or assets.

Location: Editor > Project Settings > General > Simple Asset Cleaner

The plugin automatically wraps your version control provider in a proxy to monitor submissions.

Do not select a proxy provider manually!

• Always select your actual version control provider, such as Perforce, Git, or SVN
• The plugin wraps it automatically in the background
• Selecting a proxy directly may cause problems

Correct settings:

• Use: Perforce, Git, Subversion, etc.
• Avoid: Perforce_Proxy, Git_Proxy, or any provider ending in _Proxy

• Default: Enabled
• Function: Check references before submission
• Behavior: Revert unreferenced newly added files, preserving local files
• Recommendation: Keep enabled for everyday use

• Default: Enabled
• Function: Automatically detect untracked dependency files during submission
• Behavior: A dialog lists untracked dependencies; selected files are added after confirmation
• Recommendation: Keep enabled to prevent missing dependencies from breaking other team members’ builds

• Default: English
• Options: Chinese / English
• Function: Switch the language of all UI text and logs
• Behavior: Takes effect immediately without restarting the editor

• Default: Disabled
• Function: Detailed logs for debugging
• Recommendation: Enable only when troubleshooting

• Default: UWorld (map files)
• Function: Assets of these types, including parent/derived classes, are treated as roots
• Example:
  • UWorld - Maps (.umap) and derived types
  • UDataAsset - DataAssets and derived types
• Note: Parent classes and all derived classes are automatically included

• Function: Manually designate individual assets as roots
• Example: /Game/Core/GameMode.GameMode
• Purpose: Critical assets not covered by Root Asset Classes

• Function: All assets under these paths are treated as roots
• Example: /Game/Essential/, /Game/Core/
• Purpose: Protect entire system folders from cleanup

When reporting issues, provide:

• Unreal Engine version
• Version control system (Perforce/Git/SVN)
• Plugin settings screenshot
• Log output with verbose logging enabled

Compatibility: Unreal Engine 5.2–5.8 | Tested on Windows; theoretically supports all platforms

Remember: Start conservatively. Assets can always be deleted, but restoration requires version control history!

For usage questions or collaboration inquiries, visit the contact page.

• Contact: Contact and Collaboration

Identifies candidate unreferenced assets using roots and reference relationships, with entry points for submission handling and full cleanup.

1. Copy the plugin folder into your project’s Plugins directory

   YourProject/
   └── Plugins/
       └── SimpleAssetCleaner/

2. Open the project and search for SimpleAssetCleaner under Edit > Plugins

3. Enable it and restart the editor

Open project settings: Editor > Project Settings > General > Simple Asset Cleaner

Automatic cleanup toggle:

Configure the root assets and protected paths to retain before checking Enable Auto Clean.

With default configuration, the plugin:

• Uses all maps as root assets
• Automatically checks and cleans on submission
• Protects plugin and engine assets outside the project

Advanced configuration (recommended for teams):

1. Configure root asset types

Add to Root Asset Classes:

• UWorld - Maps (included by default)
• UBlueprint - Blueprint classes, if Blueprints are core assets
• UDataAsset - DataAssets, if the project has substantial configuration data

2. Add protected paths

Add to Additional Root Paths:

• /Game/Core/ - Core systems directory
• /Game/Config/ - Configuration directory
• /Game/Managers/ - Manager directory

3. Optionally enable verbose logging

On first use, enable Enable Verbose Logging to observe the plugin. Once familiar, disable it to reduce log output.

Daily work:
Check candidate unreferenced assets according to configuration during submission and review the results.

Deep cleanup:
To clean the entire project, click Clean All Source Control Assets in settings.

With automatic cleanup enabled, the tool processes files during submission using reference-analysis results.

Workflow:

1. Work normally, creating or modifying assets
2. Add assets to version control (Add to Source Control)
3. Open the submission dialog to prepare a submission
4. The plugin automatically detects in the background which assets are unreferenced
5. Unreferenced assets are automatically removed from the submission list (reverted)
6. The submission dialog shows only files that actually need to be submitted

Typical scenario:

An artist tests 10 materials, but only 2 are ultimately used in the scene. During submission, the plugin identifies and reverts the 8 unreferenced materials, leaving a clean submission list.

Besides daily automatic cleanup, SimpleAssetCleaner offers full cleanup for periodic maintenance or major version changes.

Use cases:

• Cleanup before a major project version change
• Taking over a legacy project and removing accumulated unused content
• Regular maintenance to keep the repository healthy

Procedure:

1. Open Editor > Project Settings > General > Simple Asset Cleaner
2. Click Clean All Source Control Assets
3. Wait for scanning to finish; a progress bar is shown
4. Review logs to see which assets were cleaned

Safety measures:

Important reminder:

Full cleanup deletes submitted unreferenced files. Before using it:

• Ensure complete version control history is available for recovery
• Try it on a test branch first
• Communicate with team members in advance

SimpleAssetCleaner uses “root assets” to determine whether assets are in use.

What is a root asset?

Root assets are the most central assets in your project, such as:

• Map files (.umap)
• Main Blueprint classes, such as GameMode and PlayerController
• Configuration data tables

Starting from these roots, the plugin tracks all directly or indirectly referenced assets. Assets on these reference chains are retained; others are considered unreferenced.

Three configuration methods:

1. Root Asset Classes

Specify which asset types are roots. UWorld (maps) is included by default.

Common configurations:

• UWorld - All maps (included by default)
• UBlueprint - All Blueprint classes
• UDataAsset - All DataAssets
• UDataTable - All data tables

2. Custom Root Assets

Manually designate particular assets as roots, useful for important assets of less common types.

For example:

• /Game/Core/MainGameMode - Main game mode
• /Game/Config/GlobalSettings - Global configuration

3. Additional Root Paths

Protect all assets in an entire directory. These assets and everything they reference are retained.

For example:

• /Game/Core/ - Core systems directory
• /Game/Config/ - Configuration directory
• /Game/Essential/ - Essential assets directory

How it works:

Map A (root asset)
  ├─ References material M1
  │   └─ References texture T1 ✅ Retain
  └─ References Blueprint BP1
      └─ References material M2 ✅ Retain

Material M3 ❌ Not referenced by any root → Clean up

The plugin provides optional verbose logging for debugging and monitoring.

Enable it:
Check Enable Verbose Logging in project settings

Logs include:

• Files scanned
• Unreferenced assets detected
• Cleanup operations performed
• Reference-chain tracing for debugging

Enable verbose logging on first use or when problems arise to understand the plugin’s operation.

✅ Recommended practices:

• Automatic cleanup configuration - Review settings periodically as project assets change
• Define roots and protection scope first - Cover maps, Blueprints, configuration assets, and directories that must be retained
• Add asset types gradually - Determine which types are core assets, such as Blueprints and data tables
• Protect critical directories - Prevent accidental deletion of core systems
• Enable verbose logging on first use - Observe how the plugin works

⚠️ Notes:

• Try it on a test branch first - Check that cleanup matches expectations
• Ensure version control recovery before full cleanup - Keep at least one recoverable commit
• Use consistent team configuration - Put configuration files under version control so all members use the same rules
• Review configuration periodically - Core asset types may change as the project evolves

SimpleAssetCleaner supports all version control systems supported by Unreal Engine:

• ✅ Perforce
• ✅ Git
• ✅ SVN
• ✅ Plastic SCM
• ✅ Other systems integrated through the UE API

Configuration points:

Choose your actual provider, such as Perforce, Git, or Subversion, under Editor > Preferences > Source Control.

⚠️ Important: Do not choose options ending in _Proxy, such as Perforce_Proxy. These are internal plugin implementations and are handled automatically.

SimpleAssetCleaner analyzes and cleans only assets in the project Content directory (/Game/ path).

Assets outside cleanup scope:

• ❌ Plugin assets, such as /YourPlugin/Content/
• ❌ Engine assets (/Engine/ path)
• ❌ C++ code files (.h, .cpp)
• ❌ External references (files outside Content)

Assets retained through root configuration:

• ✅ Assets of configured root types
• ✅ Assets listed as custom roots
• ✅ All assets under root paths
• ✅ Assets directly or indirectly referenced by any of the above