LibGDX AssetManager: Architecture Note on Asynchronous Loading and Lifecycle Management

Requirements

Non-blocking loading of textures, sounds and other resources with deterministic disposal across desktop, Android and iOS backends using a shared Java API.

Smallest Suitable Design

A single application-scoped AssetManager owned by the core application is sufficient for most projects. Screens hold explicit references to assets they need.

1. Instantiate AssetManager in the core application class.
2. Queue assets with manager.load(path, AssetType.class). This is non-blocking.
3. Drive loading with manager.update() once per frame on the render thread.
4. Retrieve only after manager.isLoaded(path) is true or update returns true.
5. Release with manager.dispose() on application exit or context loss.

Trust and Data Boundaries

AssetManager bridges untrusted file system, classpath or network input to native OpenGL resource creation. It resolves FileHandle but does not sanitize asset content. Validation of file integrity and size limits must occur before load. Paths must be internal, e.g. textures/hero.png, to avoid desktop working directory assumptions that break on Android.

Operational Checks

Poll progress with manager.getProgress(). Handle errors via AssetErrorListener. Verify isLoaded before get to avoid exceptions. Ensure dispose is called on pause or context loss.

// In Screen.show
assetManager.load(PLAYER_TEXTURE_PATH, Texture.class);
assetManager.load(JUMP_SOUND_PATH, Sound.class);

// In render loop
if (assetManager.update()) {
  state = GameState.PLAYING;
} else {
  float progress = assetManager.getProgress();
}

Failure Modes

Out of memory on low-end mobile devices when the global set is too large. Missing or misnamed assets cause runtime errors if isLoaded is not checked. GL context loss on Android invalidates GPU handles; textures must be reloaded rather than assumed persistent. Reference counting is manual in practice; retaining a reference without dispose leaks native GPU memory.

Conditions That Change the Design

Hot reload during development requires a separate manager or file watch. Streaming large worlds needs per-chunk managers with unload on distance. Per-screen isolation is warranted when asset sets are disjoint and memory pressure is high. In those cases use manager.unload(path) or create scoped managers.