FlixelAssetManager

View source

interface

org.flixelgdx.asset.FlixelAssetManager

public interface FlixelAssetManager extends FlixelDestroyable, Disposable

Asset manager interface for FlixelGDX.

This is the public seam used by sprites and other runtime systems. The default implementation is FlixelDefaultAssetManager. Access via Flixel.assets.

Basic workflow:

// Loading state: queue assets
Flixel.assets.load("player.png");
Flixel.assets.load("music/bg.mp3");

// Each frame until done
Flixel.assets.update();

// Game state: get and retain a handle
FlixelAsset<FlixelGraphic> graphic = Flixel.assets.get("player.png");
graphic.retain();

// Use the content
sprite.loadGraphic(graphic.get());

// Release when done (e.g. in destroy())
graphic.release();

FlixelAssetManager.load(String) infers the asset type from the file extension using the per-manager loader registry (FlixelAssetManager.registerLoader(...)). Prefer it over explicit type parameters for common asset types. Use FlixelAssetManager.registerLoader(...) to add custom extensions.

Path keys are normalized (collapsed slashes, unified separators) via FlixelAssetPaths.normalizeAssetPath(String) so duplicate slashes or backslashes do not cause mismatches on web builds or other backends where paths are compared literally.

For advanced libGDX interop (custom loaders, asset descriptors, raw API access), use FlixelAssetManager.getManager() to reach the underlying AssetManager directly.

Methods

load(String)

public void load(String path)

Queues an asset for loading using the file extension to select a loader from the registry.

Call FlixelAssetManager.update() each frame (or FlixelAssetManager.finishLoading() to block) until loading completes, then retrieve the handle with FlixelAssetManager.get(String).

Parameters:

Name	Description
path	Asset path (e.g. "images/player.png").

Throws:

Type	Description
IllegalArgumentException	if the path has no extension or no loader is registered.

---

load(String, boolean)

public void load(String path, boolean persist)

Like FlixelAssetManager.load(String), but marks the first handle created for this key as persistent. Persistent handles survive FlixelAssetManager.clearNonPersist() when their reference count is zero.

Parameters:

Name	Description
path	Asset path.
persist	When true, the first handle created for this path is persistent.

---

get(String)

public FlixelAsset<T> get(String path)

Returns the FlixelAsset handle for path, creating it if it does not exist.

The handle's content is resolved lazily: FlixelAsset.get() fetches the data once loading completes or triggers a synchronous load if needed. Call FlixelAssetManager.load(String) in a loading state first to avoid mid-frame stalls.

Multiple calls with the same path return the same cached handle. Call FlixelAsset.retain() when you take ownership and FlixelAsset.release() when done so the manager can track which assets are still in use.

The return type is inferred from the loader registered for the path's extension. The cast is unchecked internally; passing the wrong type variable at the call site will produce a ClassCastException at runtime if the inferred type does not match.

Parameters:

Name	Description
path	Asset path.

Returns: The cached or newly created handle; never null.

Throws:

Type	Description
IllegalArgumentException	if no loader is registered for the path's extension.

---

peek(String)

public FlixelAsset<?> peek(String path)

Returns the cached FlixelAsset handle for path without creating one.

Use this for read-only checks, for example to see if a shared resource is already registered before creating it. Does not change the reference count.

Parameters:

Name	Description
path	Asset path.

Returns: The cached handle, or null if none exists.

---

registerLoader(String, Class<?>, FlixelAssetLoader<T>)

public void registerLoader(String extension, Class<?> rawType, FlixelAssetLoader<T> loader)

Registers a loader for a file extension. The rawType is what libGDX's AssetManager will load under the hood (e.g. Texture for image files). The loader wraps the path into a FlixelAsset handle.

Example: adding a custom config extension that loads text:

Flixel.assets.registerLoader(".cfg", String.class,
    (assets, path) -> new FlixelDefaultAsset<>(assets, path, String.class));

Parameters:

Name	Description
extension	File extension with or without a leading dot (e.g. ".png" or "png").
rawType	The libGDX raw type to load.
loader	Creates handles for paths with this extension.

---

unregisterLoader(String)

public void unregisterLoader(String extension)

Removes a previously registered loader for the given extension.

Parameters:

Name	Description
extension	Same form as FlixelAssetManager.registerLoader(...).

---

register(FlixelAsset<?>)

public void register(FlixelAsset<?> asset)

Registers a caller-constructed asset handle directly with the manager cache. Use this for assets created outside the normal loading pipeline (e.g. a texture built from a Pixmap).

The handle is keyed by FlixelAsset.getPath(). If a handle is already registered under that key, it is replaced.

Parameters:

Name	Description
asset	The handle to register. Use FlixelAssetManager.allocateSyntheticKey() when no natural path exists.

---

allocateSyntheticKey()

public String allocateSyntheticKey()

Allocates a unique synthetic key for caller-created assets that have no natural path. Use with FlixelAssetManager.register(FlixelAsset<?>).

Returns: A unique key string; never null.

---

update()

public boolean update()

Processes one loading task on the underlying AssetManager.

Returns: true when all queued loading is finished.

---

update(int)

public boolean update(int millis)

Processes loading for up to millis milliseconds.

Parameters:

Name	Description
millis	Maximum time to spend updating.

Returns: true when all queued loading is finished.

---

getProgress()

public float getProgress()

Returns overall loading progress in [0, 1].

Returns: Progress fraction.

---

getLoadedAssetCount()

public default int getLoadedAssetCount()

Returns the number of assets currently tracked in the manager cache.

A steadily climbing count across state switches often means assets are being loaded without a matching FlixelAsset.release() or FlixelAssetManager.clearNonPersist() call.

Returns: Number of cached handles.

---

isLoaded(String)

public boolean isLoaded(String path)

Returns whether the asset at path is ready (content available without blocking).

Parameters:

Name	Description
path	Asset path.

Returns: true if the asset is loaded and available.

---

finishLoading()

public void finishLoading()

Blocks until all queued assets finish loading.

---

finishLoadingAsset(String)

public void finishLoadingAsset(String path)

Blocks until the specific asset at path finishes loading.

Parameters:

Name	Description
path	Asset path.

---

unload(String)

public void unload(String path)

Unloads the asset at path from the underlying libGDX AssetManager.

Parameters:

Name	Description
path	Asset key to unload.

---

getDiagnostics()

public String getDiagnostics()

Returns multi-line diagnostics: every cached handle with its path, type, reference count, persist flag, and whether the underlying libGDX asset is loaded.

Returns: Diagnostic string; never null.

---

clearNonPersist()

public void clearNonPersist()

Unloads non-persistent asset handles whose reference count is zero. Called automatically by Flixel.switchState in FlixelAssetMode.STANDARD and FlixelAssetMode.AGGRESSIVE modes.

---

clear()

public void clear()

Unloads and removes all cached asset handles, regardless of persist or reference count.

---

getGlobalPersist()

public boolean getGlobalPersist()

Returns the default FlixelAsset.isPersist() value assigned to newly created handles.

When true, new handles survive FlixelAssetManager.clearNonPersist() when unreferenced. Owned assets (e.g. textures created from a Pixmap) always use persist = false regardless of this setting.

Returns: The global persist default.

---

setGlobalPersist(boolean)

public void setGlobalPersist(boolean globalPersist)

Sets the global persist default. Does not affect handles already in the cache.

Parameters:

Name	Description
globalPersist	New default value.

---

getAssetMode()

public FlixelAssetMode getAssetMode()

Returns the active FlixelAssetMode controlling when non-persistent assets are reclaimed.

Returns: The current mode; never null.

---

setAssetMode(FlixelAssetMode)

public void setAssetMode(FlixelAssetMode mode)

Sets the active asset management mode. Takes effect on the next FlixelAsset.release() call or the next Flixel.switchState, whichever comes first.

Parameters:

Name	Description
mode	The new mode; must not be null.

---

resolveAudioPath(String)

public String resolveAudioPath(String path)

Resolves an internal audio path to an absolute filesystem path suitable for native backends. Results are cached after the first call.

Parameters:

Name	Description
path	Internal asset path.

Returns: Resolved absolute path; never null.

---

extractAssetPath(String)

public String extractAssetPath(String path)

Converts an internal path to an absolute filesystem path, extracting to a temp file when the asset lives inside a JAR.

Parameters:

Name	Description
path	Internal asset path.

Returns: Absolute path; never null.

---

onAssetReleased(FlixelAsset<?>)

public default void onAssetReleased(FlixelAsset<?> handle)

Called by FlixelAsset.release() when a handle's reference count reaches zero.

In FlixelAssetMode.AGGRESSIVE mode the default implementation triggers an immediate eviction. In other modes this is a no-op; cleanup happens at state-switch time via FlixelAssetManager.clearNonPersist().

Parameters:

Name	Description
handle	The handle whose reference count just reached zero.

---

getManager()

public AssetManager getManager()

Returns the underlying libGDX AssetManager for advanced use such as custom loaders, asset descriptors, or raw API access not covered by this interface.

Returns: The underlying manager; never null.

---

enableCompressedTextures()

public void enableCompressedTextures()

Registers a KTX2/Basis Universal texture loader so .png requests transparently use a compressed .ktx2 sibling when one exists next to the requested path.

FlixelGame.create() calls this automatically on every backend, after the platform application object has created a GL context (this method queries Gdx.gl for supported compressed texture formats, so it cannot run any earlier). Calling it on a backend without the Basis Universal transcoder natives available is harmless but pointless, since FlixelGraphic only looks for a .ktx2 sibling after this has been called, and no .ktx2 files exist unless the org.flixelgdx.basisu Gradle plugin compressed them into the build. Idempotent: calling it more than once has no additional effect.

See Also: .isCompressedTexturesEnabled

---

isCompressedTexturesEnabled()

public boolean isCompressedTexturesEnabled()

Returns whether FlixelAssetManager.enableCompressedTextures() has been called on this manager.

Returns: true if compressed .ktx2 textures are recognized by this manager.

---

setKtx2LoaderInstaller(FlixelKtx2LoaderInstaller)

public void setKtx2LoaderInstaller(FlixelKtx2LoaderInstaller installer)

Registers the platform installer that adds the KTX2 (Basis Universal) texture loader.

Called once by a platform launcher that bundles the basisu natives (the desktop and Android launchers do this). The core module must never reference the loader directly: Basis Universal disposes native byte buffers through BufferUtils.isUnsafeByteBuffer(...), a method TeaVM cannot compile, so a direct reference would fail the entire web build during reachability analysis. Routing the registration through this installer keeps the compressed-texture code out of the shared module, so platforms without it (such as web) simply leave the feature unsupported.

Parameters:

Name	Description
installer	The installer to run when compressed textures are enabled, or null to leave them unsupported.

---

resolveTexturePath(String)

public String resolveTexturePath(String path)

Resolves path to the key that should be used with the underlying libGDX AssetManager for a texture load, returning a .ktx2 sibling instead of path when FlixelAssetManager.enableCompressedTextures() has been called and that sibling exists. Every part of the framework that needs to know whether a texture path has a compressed variant (loading, unloading, checking load state) should go through this method rather than re-implementing the check, so the compressed/plain decision is made in exactly one place. Results are cached, since a path's compressed-sibling status never changes at runtime.

Parameters:

Name	Description
path	Normalized asset path.

Returns: The path to use with the underlying AssetManager.

See Also: .enableCompressedTextures

---