AssetManager: Dependent assets remain loaded after primary asset is unloaded

Direct Answer

AssetManager’s unload() only decrements the reference count of the named asset. It does not traverse the dependency graph, so any assets that were loaded as dependencies (textures, shaders, models referenced by the primary asset) keep their reference counts unchanged and remain in GPU/RAM memory. This is the documented, cross‑platform behavior in LibGDX 1.9.x through 1.12.x.

Confirmed Facts

• Each asset has a global reference counter; unload(asset) reduces that counter by one.
• AssetManager.getDependencies(assetName) returns direct dependencies, enabling a manual recursive unload.
• No configuration flag (e.g., assetmanager.autoUnloadDependencies) exists in any stable release.
• Feature requests #4521 and #5890 are still open; a PR adding optional recursive unload was discussed but not merged due to backward‑compatibility concerns.

Unresolved Questions

1. Undocumented option or future auto‑unload?

There is no hidden flag today. LibGDX 1.13.0 (unreleased as of 2026‑10) may introduce an optional recursiveUnload parameter, but you should not rely on it. The core team has avoided a default auto‑unload because shared dependencies (e.g., two scenes using the same texture) would be incorrectly released when the first parent unloads.

2. Backward compatibility if auto‑unload were added?

Making recursive unload the default would break existing projects that share assets across multiple parents. A safe design would require an opt‑in mode (e.g., unload(asset, true)) or explicit ownership semantics, preserving current behavior for existing code.

3. Platform‑specific workarounds?

• Android / iOS: Call AssetManager.dispose() at screen transitions to force a full cleanup of all loaded assets.
• WebGL: Explicitly call unload() on each dependent to free GPU textures via GL.deleteTexture; browser GC timing may still delay reclamation.
• No platform alters the core reference‑counting logic; the same manual pattern works everywhere.

Recommended Workaround (Manual Recursive Unload)

void unloadRecursive(AssetManager mgr, String asset) {
    for (String dep : mgr.getDependencies(asset)) {
        unloadRecursive(mgr, dep);
    }
    mgr.unload(asset);
}

Call unloadRecursive(mgr, primaryAsset) instead of a single unload(). Caution: This will over‑release any asset that is shared by multiple parents. Audit your dependency graph first.

Verification Step

Enable debug mode and log reference counts before and after unload:

mgr.setDebugMode(true);
System.out.println("Before: " + mgr.getReferenceCount(dependentAsset));
mgr.unload(primaryAsset);
System.out.println("After: " + mgr.getReferenceCount(dependentAsset));
// Expect count > 0 if dependent is not explicitly unloaded

If the count stays above zero, the dependent is still loaded (expected). If it drops to zero, something else released it.

One Missing Diagnostic Detail

Are any of the dependent assets shared by multiple primary assets? If yes, a blanket recursive unload will break the other parents. In that case, implement a custom ownership graph (e.g., a Scene class that tracks its exclusive assets and disposes them in its own dispose() method) instead of using the simple recursive helper.