Flixel

class

org.flixelgdx.Flixel

public final class Flixel

The static singleton entry point and global manager for the FlixelGDX framework.

This class exposes core services, settings, and utility methods needed to develop games and interactive applications using FlixelGDX. Nearly all main gameplay logic interacts with Flixel via this class, either to control the playback loop, switch states/scenes, access global systems (input, audio, asset management, logging, debugging), or modify global properties.

Core Responsibilities

State Management: Switches between FlixelState instances to manage major scenes in your game.
Input Handling: Provides access to the keyboard manager (Flixel.keys) for polling key states and input events.
Sound System: Exposes a global Flixel.sound manager for playing music and sound effects.
Asset Loading: Offers a unified Flixel.assets interface for loading, caching, and retrieving textures, sounds, and data.
Host integration: Desktop notifications and task attention via Flixel.host. Separate from blocking FlixelAlerter.info(String, String) dialogs.
Window control: Transparency helpers and desktop window tweaks via Flixel.window.
Logging and Debugging: Centralizes log output through Flixel.log, and supplies tools for in-game watches and performance tracking.
Camera and Drawing Context: Handles the active camera selection and global antialiasing options.
Signals and Events: Emits signals for state switches, updates, and critical events.
Frame timers: FlixelTimer.getGlobalManager() is stepped from FlixelGame. Use FlixelTimer.wait(float, FlixelTimerListener) or start(...) on the manager. Flixel.timeScale scales timer elapsed only (not the whole game loop).

Typical Usage

// Switch states.
Flixel.switchState(new MyGameState());

// Play a sound.
Flixel.sound.play("explosion.mp3");

// Check if a key is pressed.
if (Flixel.keys.justPressed(FlixelKeys.SPACE)) {
  // Jump!
}

// Check if a mouse button is pressed.
if (Flixel.mouse.justPressed(FlixelMouseButton.LEFT)) {
  // Left mouse button was just pressed!
}

// Log diagnostic information.
Flixel.info("Player has reached checkpoint.");
Flixel.warn("Player is low on health.");
Flixel.error("Game crashed!");

// Load an asset.
Flixel.assets.load("player.png");

// Use the global signal system.
Flixel.Signals.preStateSwitch.add(data -> {
  Flixel.info("Now switching to state: " + data.state().toString());
});

Design Notes

The Flixel class is not meant to be instantiated. It should be interacted with strictly via its static fields and methods.
Custom configuration and subsystems can be plugged in by replacing or augmenting the static references, e.g., custom FlixelLogger or FlixelStackTraceProvider for advanced logging.
All engine systems are globally accessible through this class to simplify game logic implementation.

Threading

All Flixel APIs, unless otherwise noted, are intended to be called from the main libGDX rendering thread.

Lifecycle

The Flixel singleton is initialized by the internal game bootstrap sequence. Applications should not attempt to reinitialize or replace this class directly.

Fields

MIN_ELAPSED

public static final float MIN_ELAPSED = 1.0E-6f

Minimum allowed elapsed time in seconds for one frame. FlixelGame clamps the raw libGDX delta to at least this value so a zero-delta does not break motion and timers.

MAX_ELAPSED

public static final float MAX_ELAPSED = 0.1f

Maximum allowed elapsed time in seconds for one frame. FlixelGame clamps the raw libGDX delta to at most this value so a long hitch does not move physics too far in one step.

applyAntialiasingOnStateAdd

public static boolean applyAntialiasingOnStateAdd

Automatically applies the globally set antialiasing value for any member added to the current FlixelState.

Note that when this value is set to true, any FlixelSprite's / FlixelAntialiasable's antialiasing property will be ignored.

game

public static FlixelGame game

The active FlixelGame instance driving the game lifecycle.

This reference is set during Flixel.initialize(FlixelGame) before any other system is brought up. It exposes the main render loop, the camera list, window dimensions, and low-level controls such as fullscreen toggling and framerate caps.

Most game code never needs to touch Flixel.game directly. Prefer the specialized fields (Flixel.sound, Flixel.assets, Flixel.keys, Flixel.cameras, etc.) for day-to-day work. Reach for this field only when the high-level APIs do not cover what you need.

Example:

// Change the game's background color.
Flixel.game.bgColor.set(Color.BLUE);

cameras

public static final Array<FlixelCamera> cameras

The global list of active cameras, ordered back-to-front.

The first entry, Flixel.cameras.first(), is the main camera that the framework follows and renders to by default. Add more cameras for split-screen, picture-in-picture, or separate UI layers.

This reference is final and never null: the framework creates a default camera at startup and refreshes the list (in place) on a state switch, so it is safe to read from your state's create() onward. Mutate it through the list's own methods (for example Array.add); the array itself is never replaced.

Example:

// The main camera.
FlixelCamera main = Flixel.cameras.first();
main.follow(player);

// A second camera for a UI overlay.
Flixel.cameras.add(new FlixelCamera(Gdx.graphics.getWidth(), Gdx.graphics.getHeight()));

alert

public static FlixelAlerter alert

The platform-specific alert dialog provider.

Alert dialogs are blocking modal windows that pause execution until the user dismisses them. Reserve them for critical events (unrecoverable errors, required permission prompts) rather than routine game feedback. For non-blocking OS notifications that do not interrupt gameplay, use Flixel.host instead.

Example:

Flixel.alert.info("Hello", "Welcome to the game!");
Flixel.alert.warn("Warning", "These permissions are required to continue.");
Flixel.alert.error("Save Failed", "Could not write to disk. Check your permissions.");

state

public static FlixelState state

The currently active state.

This is the FlixelState that is updated and drawn every frame. Switch to a different state using Flixel.switchState(FlixelState); reading this field directly is useful when you need to query the current state without holding a separate reference (for example, inside a signal listener or a global utility method).

This field is null until the first call to Flixel.switchState(FlixelState).

currentStateFactory

public static Supplier<FlixelState> currentStateFactory

Factory that produces a fresh instance of the current state for Flixel.resetState().

Updated automatically whenever Flixel.switchState(...) is called. The default Flixel.switchState(FlixelState) overload supplies () -> newState automatically, so this is pre-populated after any normal state switch at no extra cost to the caller.

Set this to null to disable Flixel.resetState() for the current state, making it a no-op.

keys

public static FlixelKeyInputManager keys

The keyboard input manager for the game.

Poll key states every frame using the methods on this manager. FlixelGDX distinguishes between keys that are held down, freshly pressed on the current frame, and freshly released on the current frame, so your game logic can respond precisely to each event type.

Key constants are defined in FlixelKey. Pass any of those constants to the methods below:

FlixelKeyInputManager.pressed(int) - true while the key is held down.
FlixelKeyInputManager.justPressed(int) - true on the first frame the key is pressed.
FlixelKeyInputManager.justReleased(int) - true on the first frame the key is released.

Example:

// Check if the spacebar is held.
if (Flixel.keys.pressed(FlixelKey.SPACE)) {
  player.jump();
}

// Fire a bullet only on the first frame the key is pressed.
if (Flixel.keys.justPressed(FlixelKey.Z)) {
  player.shoot();
}

See Also: FlixelKey

sound

public static FlixelSoundManager sound

The central audio manager.

Use this manager to play sound effects and background music. It separates one-shot sound effects from long-running music tracks and exposes independent volume controls for each category plus a master volume knob that scales both.

The audio backend is platform-specific and is injected by the launcher before Flixel.initialize(FlixelGame). On all platforms, it's typically powered by miniaudio, and for web (TeaVM) it utilizes the Web Audio API.

Example:

// Play a one-shot sound effect.
Flixel.sound.play("hit.wav");

// Start looping background music at half volume.
Flixel.sound.playMusic("theme.ogg", 0.5f, true);

// Mute all audio.
Flixel.sound.setMasterVolume(0f);

assets

public static FlixelAssetManager assets

The central asset manager for the game.

Use this manager to load, cache, and retrieve any external resource your game needs: textures, audio clips, fonts, JSON data files, and more. The manager tracks which assets have been loaded so the same file is never loaded twice and automatically unloads non-persistent assets when states switch, freeing GPU and heap memory between scenes.

Assets marked persistent (see FlixelAssetManager.load(String, boolean)) survive state switches and are ideal for shared resources such as a global UI atlas or a music track that spans multiple states.

Example:

// Load a texture and retrieve it.
Flixel.assets.load("player.png");
FlixelGraphic tex = Flixel.assets.get<FlixelGraphic>("player.png").get();

// Mark an asset persistent so it survives state switches.
Flixel.assets.setPersist("shared_ui_atlas.png", true);

watch

public static FlixelDebugWatchManager watch

The debug watch manager for the game.

A watch is a named, live value that the debug overlay displays while the game runs. Watches are an efficient way to inspect frame-by-frame state (player position, health, physics variables) without scattering temporary log statements throughout your code.

Add a watch with a name and a supplier lambda; the overlay calls the supplier every frame to refresh the displayed value. Remove watches you no longer need to keep the overlay clean. Suppliers are never called when the overlay is hidden, so there is no runtime cost in release builds.

Example:

// Show the player's position live in the debug overlay.
Flixel.watch.add("Player X", player::getX);
Flixel.watch.add("Player Y", player::getY);
Flixel.watch.add("Total Score", () -> orbs + gemsAmount);

// Remove a watch when it is no longer needed.
Flixel.watch.remove("Player X");

debug

public static FlixelDebugManager debug

The central debug manager for the game.

The debug manager is the primary interface to FlixelGDX's built-in debugging toolset. It bridges game code and the active FlixelDebugOverlay without requiring a direct reference to the overlay or even knowing whether one is installed. All methods are safe to call in any build and no-op gracefully when the game is not running in debug mode.

Key capabilities:

Visibility toggle: Call FlixelDebugManager.toggleVisible() or FlixelDebugManager.setVisible(boolean) to show or hide the overlay at runtime.
Draw debug: FlixelDebugManager.setDrawDebug(boolean) enables bounding-box and collision-shape visualization over every live object in the current state.
Custom commands: Register interactive console commands with FlixelDebugManager.registerCommand(String, Consumer<FlixelDebugCommandArgs>) to run arbitrary game code from the debug overlay's input line.

The overlay itself is created by a factory set before the game starts. Desktop launchers typically supply a richer overlay (for example, one built with Dear ImGui), while headless or web builds fall back to FlixelHeadlessDebugOverlay. Use Flixel.setDebugOverlay(Supplier<FlixelDebugOverlay>) to install a custom factory before Flixel.initialize(FlixelGame).

Example:

// Show the debug overlay when the game starts (debug mode only).
Flixel.debug.setVisible(true);

// Draw bounding boxes over all objects.
Flixel.debug.setDrawDebug(true);

// Register a custom console command.
Flixel.debug.registerCommand("god", args -> player.setInvincible(true));

save

public static FlixelSave save

The preferences-based save data helper for the game.

FlixelSave wraps libGDX's Preferences system to provide a simple key-value store that persists between sessions. It is backed by platform-native storage: a .prefs file on desktop, browser localStorage on web, and the equivalent on mobile.

Call FlixelSave.bind(String, String) once before using any other method to open (or create) the named preferences file. After that, read and write values directly through the FlixelSave.data map, then flush them to disk with FlixelSave.flush().

Example:

// Open the save file (typically in FlixelState.create()).
Flixel.save.bind("MySaveFile", "slot1");

// Read and write a high score.
int prevBest = (int) Flixel.save.data.get("highScore", 0);
if (score > prevBest) {
  Flixel.save.data.put("highScore", score);
  Flixel.save.flush();
}

mouse

public static FlixelMouseManager mouse

The mouse and pointer input manager for the game.

Poll button states and screen-space coordinates every frame. Like Flixel.keys, this manager distinguishes between buttons that are currently held, just pressed this frame, and just released this frame, so your code can react precisely to each event. Button constants are defined in FlixelMouseButton.

Example:

// Fire on the first frame the left button is pressed.
if (Flixel.mouse.justPressed(FlixelMouseButton.LEFT)) {
  spawnBullet(Flixel.mouse.getWorldX(), Flixel.mouse.getWorldY());
}

// Pan the camera while the right button is held.
if (Flixel.mouse.pressed(FlixelMouseButton.RIGHT)) {
  camera.pan(Flixel.mouse.getDeltaX(), Flixel.mouse.getDeltaY());
}

See Also: FlixelMouseButton

touches

public static FlixelTouchManager touches

The multitouch input manager for the game.

Tracks up to FlixelTouchManager.DEFAULT_MAX_POINTERS simultaneous fingers. Access per-pointer state through the pre-allocated list array, or use the convenience methods for quick checks:

// React on first contact.
if (Flixel.touches.list[0].isJustPressed()) {
  spawnEffect(Flixel.touches.list[0].worldX, Flixel.touches.list[0].worldY);
}

// Check how many fingers are down.
if (Flixel.touches.count() >= 2) {
  beginPinchZoom();
}

See Also: FlixelTouchManager, FlixelTouch

gamepads

public static FlixelGamepadInputManager gamepads

The gamepad and controller input manager.

The gamepad system is disabled by default. Set FlixelGamepadInputManager.enabled to true before the game loop starts if your game needs controller support:

Flixel.gamepads.enabled = true;

FlixelGDX's gamepad system is built on the gdx-controllers extension. It abstracts physical controllers (Xbox, PlayStation, generic USB) behind a set of logical button and axis codes defined in FlixelGamepadButton, so the same game code works across different controller layouts without any platform-specific branching.

Each connected controller is identified by a zero-based index. Player 1's controller is index 0, player 2's is index 1, and so on. Query button states with FlixelGamepadInputManager.pressed(int, int), FlixelGamepadInputManager.justPressed(int, int), and FlixelGamepadInputManager.justReleased(int, int), or read analog axes with FlixelGamepadInputManager.getAxis(int, int).

Example:

// Opt in to controller support before the game loop starts.
Flixel.gamepads.enabled = true;

// Check if player 1 pressed the A button this frame.
if (Flixel.gamepads.justPressed(0, FlixelGamepadButton.A)) {
  player.jump();
}

// Read the left stick's horizontal axis for movement.
float horizontal = Flixel.gamepads.getAxis(0, FlixelGamepadButton.AXIS_LEFT_X);
player.setVelocityX(horizontal * MOVE_SPEED * elapsed);

See Also: FlixelGamepadButton

log

public static FlixelLogger log

The default logger used for game diagnostics and debugging output.

The logger formats and routes messages to the console, the in-game debug overlay, and optionally a persistent log file. It supports three severity levels: informational (FlixelLogger.info(Object)), warnings (FlixelLogger.warn(Object)), and errors (FlixelLogger.error(Object)), each visually distinguished by color in terminals that support ANSI codes.

For convenience, the three most common logging calls are promoted to static methods on Flixel itself: Flixel.info(Object), Flixel.warn(Object), and Flixel.error(String). These all delegate to this field.

Each message is automatically annotated with the calling class name and line number by the active FlixelStackTraceProvider, making it easy to trace output back to its source without a full stack dump.

To write logs to a file, call FlixelLogger.startFileLogging() after configuring FlixelLogger.setCanStoreLogs(boolean) and optionally FlixelLogger.setLogsFolder(String).

Example:

// Simple convenience wrappers on Flixel itself.
Flixel.info("Player spawned.");
Flixel.warn("Low health!");
Flixel.error("Save file corrupted.");

// Create a log with a distinguishing tag.
Flixel.info("AI", "Pathfinding recalculated.");

// Enable persistent file logging at startup.
Flixel.log.setCanStoreLogs(true);
Flixel.log.startFileLogging();

window

public static FlixelWindow window

Desktop window integration for transparency helpers, opacity control, and OS-level window tweaks.

On desktop (LWJGL3), this field is replaced by a real implementation before Flixel.initialize(FlixelGame) runs. On an unknown platform it falls back to FlixelNoopWindow, which silently ignores every call, so you can always write Flixel.window.setOpacity(0.8f) without wrapping it in a platform check.

Typical uses include transparent window backgrounds for overlay-style applications, programmatic window repositioning, and toggling window decorations (title bar, border) at runtime.

Example:

// Make the window semi-transparent.
Flixel.window.setOpacity(0.85f);

// Remove the title bar and border.
Flixel.window.setDecorated(false);

host

public static FlixelHostIntegration host

Host OS integration for toast notifications and taskbar attention signals.

On desktop (LWJGL3), this field is replaced by a platform-specific implementation before Flixel.initialize(FlixelGame) runs. On all other platforms it falls back to FlixelNoopHostIntegration, so calls are always safe to make regardless of platform.

This is distinct from the blocking alert dialogs exposed by FlixelAlerter.info(String, String): host notifications appear as non-intrusive OS toasts (system tray popups, notification center entries) and do not interrupt gameplay. Taskbar attention requests flash the game's taskbar button to draw the user's eye after the window has been minimized or sent to the background.

Example:

// Show a non-blocking OS notification when a download finishes.
Flixel.host.sendNotification("Download complete", "Your level pack is ready to play.");

// Flash the taskbar button to get the user's attention.
Flixel.host.requestAttention();

haptics

public static FlixelHaptics haptics

Haptic (vibration) feedback for mobile devices.

On platforms without a vibration motor (desktop, web) this defaults to a silent no-op, so all calls are always safe to make. Check FlixelHaptics.isSupported() first if your game logic needs to know whether feedback will actually fire.

Example:

// Short pulse when the player takes damage.
Flixel.haptics.vibrate(60);

// Repeating heartbeat pattern (restarts from index 0) while a timer is critical.
Flixel.haptics.vibrate(new long[] { 0, 80, 120, 80, 600 }, 0);

// Cancel when the timer ends.
Flixel.haptics.cancel();

See Also: FlixelHaptics

timeScale

public static float timeScale

Global timescale applied to the game's update loop each frame.

1f is normal speed; values below 1f slow the game down, values above 1f speed it up. The raw platform delta is clamped to [Flixel.MIN_ELAPSED, Flixel.MAX_ELAPSED] first, then multiplied by this value before being stored in Flixel.elapsed and passed to update(). All systems that read Flixel.getElapsed() (such as physics, animations, tweens, timers, and camera follow) are affected uniformly.

The debug overlay's Controls panel exposes a slider for this value at runtime (range 0.1x to 4.0x).

stackTraceProvider

public static FlixelStackTraceProvider stackTraceProvider

System used to detect where a log comes from when a log is created.

logFileHandler

public static FlixelLogFileHandler logFileHandler

Platform-specific handler for writing log output to a file. May be null on platforms that do not support file logging (e.g., web/TeaVM).

logConsoleSink

public static FlixelLogConsoleSink logConsoleSink

When non-null, FlixelLogger sends each console line here instead of System.out (for example, styled output in the browser). Set before Flixel.initialize(FlixelGame).

soundFactory

public static Factory soundFactory

Platform-specific factory for creating sounds, groups, and effect nodes. Set by the launcher before Flixel.initialize(FlixelGame).

Methods

initialize(FlixelGame)

public static void initialize(FlixelGame gameInstance)

Initializes the entire Flixel system.

This gets called BEFORE FlixelGame.create() is executed. It sets up every core system that Flixel needs to work, such as FlixelAssetManager, audio system, key input manager, logger, backend systems for different platforms, and more.

Parameters:

Name	Description
`gameInstance`	The FlixelGame instance to use.

Throws:

Type	Description
`IllegalStateException`	If Flixel has already been initialized.