Skip to main content

Assets

Flixel.assets is a FlixelAssetManager that wraps libGDX's AssetManager as a loading engine and keeps a single unified cache of FlixelAsset<T> handles at runtime. Every asset type — images, audio, text — is retrieved through the same interface. It is the right tool for games that need to control when assets are loaded and released rather than keeping everything in memory for the lifetime of the game.

The FlixelAsset handle​

Every asset the manager returns is a FlixelAsset<T>, where T is the wrapper type game code actually uses. Images return FlixelAsset<FlixelGraphic>; audio sources return FlixelAsset<FlixelSoundSource>; text files return FlixelAsset<String>. Call handle.get() to access the content.

FlixelGraphic implements FlixelAsset<FlixelGraphic> directly, so handle.get() returns the graphic itself and there is no extra unwrapping step. Use graphic.getTexture() only when you need the raw libGDX Texture (for example, to split a spritesheet by hand).

Loading assets​

// Queue assets for async loading. The file extension selects the loader automatically.
Flixel.assets.load("textures/tileset.png");
Flixel.assets.load("audio/music/stage1.ogg");

// Mark an asset as persistent so it survives state switches even at zero references.
Flixel.assets.load("textures/ui/hud.png", true);

// Update all queued loads (use only inside a loading state).
if (!Flixel.assets.update()) {
  progressBar.setValue(Flixel.assets.getProgress());
}

Retrieving and releasing assets​

get(path) returns a FlixelAsset<T> handle and loads synchronously if the asset was not queued ahead of time. Call retain() when you take ownership and release() when you are done -- the manager uses the reference count to decide when it is safe to unload the underlying data.

// Retrieve a handle and take ownership. If not already loaded, this blocks.
// Prefer loading in a loading state first to avoid mid-frame stalls.
FlixelAsset<FlixelGraphic> handle = Flixel.assets.get("textures/tileset.png");
handle.retain();
FlixelGraphic graphic = handle.get();

// Access the raw texture if you need it (for manual splitting, etc.).
Texture tex = graphic.getTexture();

// Release in destroy() to let the manager unload it at the next state switch.
handle.release();

Use peek(path) for a non-owning read that does not change the reference count — useful for checking whether a shared resource is already registered before creating it.

Loading state pattern​

For large games, use a dedicated loading state that shows a progress bar:

public class LoadingState extends FlixelState {

  private FlixelBar progressBar;

  @Override
  public void create() {
    super.create();

    Flixel.assets.load("textures/level1.png");
    Flixel.assets.load("audio/music/level1.ogg");
    // ... more queued loads

    float barW = Flixel.getViewWidth() * 0.6f;
    float barH = 20f;
    progressBar = new FlixelBar(
        (Flixel.getViewWidth() - barW) / 2f,
        (Flixel.getViewHeight() - barH) / 2f,
        barW,
        barH);
    progressBar.setTrack(() -> Flixel.assets.getProgress());
    add(progressBar);
  }

  @Override
  public void update(float elapsed) {
    super.update(elapsed);
    if (Flixel.assets.update()) {
      Flixel.switchState(new PlayState());
    }
  }
}

Custom asset types​

Register a loader for any file extension you need. The FlixelAssetLoader functional interface takes the manager and the path and returns a fully constructed FlixelAsset<T> handle:

// Load .cfg files as plain text strings.
Flixel.assets.registerLoader(".cfg", String.class,
    (assets, path) -> new FlixelDefaultAsset<>(assets, path, String.class));

// Now load and retrieve exactly like any built-in type.
Flixel.assets.load("data/settings.cfg");
Flixel.assets.finishLoading();
FlixelAsset<String> cfg = Flixel.assets.get("data/settings.cfg");
String text = cfg.get();

Asset modes​

FlixelAssetMode controls when unreferenced, non-persistent assets are reclaimed. Set it once in your game's setup:

ModeWhen assets are freed
LAZYNever automatically — you call clearNonPersist() or clear() yourself.
STANDARDOn every Flixel.switchState(...) call (the default).
AGGRESSIVEImmediately when an asset's reference count drops to zero.
Flixel.assets.setAssetMode(FlixelAssetMode.AGGRESSIVE);

AGGRESSIVE is best for games with many short-lived assets where you want immediate GPU memory reclaim. STANDARD is the safe default for most games. LAZY gives you full manual control.