libgdx-box2dlights

name: libgdx-box2dlights description: Use when writing libGDX Java/Kotlin code involving 2D lighting with box2dlights — RayHandler, PointLight, ConeLight, DirectionalLight, ChainLight, ambient light, shadow rendering, soft shadows, light filtering, or attaching lights to Box2D bodies. Use when debugging lights not rendering, wrong light positions, lights not casting shadows, or performance issues with many lights.

libGDX box2dlights

Quick reference for box2dlights — a 2D lighting library using Box2D raycasting for shadow generation. Covers RayHandler, light types, filtering, rendering order, and PPM integration. This is a separate library, not part of core libGDX.

This is NOT the 3D Environment/lighting system. box2dlights is exclusively for 2D shadow-casting lights using Box2D fixtures as occluders.

Gradle Dependencies

// Core module
implementation "com.badlogicgames.box2dlights:box2dlights:1.5"

// ALSO requires gdx-box2d — add explicitly (do not rely on transitive dep)
implementation "com.badlogicgames.gdx:gdx-box2d:$gdxVersion"
// Plus gdx-box2d-platform natives per target platform (see libgdx-box2d skill)

// GWT/HTML5 — add sources
implementation "com.badlogicgames.box2dlights:box2dlights:1.5:sources"
// GdxDefinition.gwt.xml:
//   <inherits name="Box2DLights" />

The published 1.5 POM references libGDX 1.6.2 but works with newer versions. Always add your own gdx-box2d dependency at the correct version.

Class Hierarchy

Light (abstract) implements Disposable
  ├── PositionalLight (abstract)
  │     ├── PointLight
  │     └── ConeLight
  ├── DirectionalLight
  └── ChainLight

PositionalLight is an intermediate abstract class — many position/body methods live there.

RayHandler

Central manager. Requires a Box2D World (used for shadow raycasting). Even if you don't want shadows, you must pass a World.

// Construction — FBO defaults to Gdx.graphics.getWidth()/4 x getHeight()/4
RayHandler rayHandler = new RayHandler(world);
RayHandler rayHandler = new RayHandler(world, options);                      // RayHandlerOptions
RayHandler rayHandler = new RayHandler(world, fboWidth, fboHeight);
RayHandler rayHandler = new RayHandler(world, fboWidth, fboHeight, options); // RayHandlerOptions

RayHandlerOptions — pass to constructor for gamma correction, diffuse mode, pseudo-3D:

RayHandlerOptions options = new RayHandlerOptions();
options.setGammaCorrection(true);
options.setDiffuse(true);
RayHandler rayHandler = new RayHandler(world, fboWidth, fboHeight, options);

DO NOT use RayHandler.setGammaCorrection(boolean) or RayHandler.useDiffuseLight(boolean) — both are deprecated static methods with EMPTY BODIES (they do nothing). Use RayHandlerOptions at construction, or instance methods applyGammaCorrection(boolean) / setDiffuseLight(boolean) after construction.

Ambient light:

rayHandler.setAmbientLight(0.1f, 0.1f, 0.1f, 0.5f);  // r, g, b, a
rayHandler.setAmbientLight(new Color(0.1f, 0.1f, 0.1f, 0.5f));
rayHandler.setAmbientLight(0.3f);                       // sets ONLY alpha — NOT grayscale

Rendering — AFTER SpriteBatch, NOT inside begin/end:

// In render():
batch.begin();
// ... draw sprites ...
batch.end();

rayHandler.setCombinedMatrix(camera);   // OrthographicCamera, NOT Camera
rayHandler.updateAndRender();           // NOT render()

// UI on top (optional)
uiBatch.begin();
// ...
uiBatch.end();

setCombinedMatrix overloads:

Shadows, blur, culling:

rayHandler.setShadows(true);         // enable shadow casting (default: true)
rayHandler.setBlur(true);            // Gaussian blur on light map (default: true)
rayHandler.setBlurNum(1);            // blur passes, 1-3 safe (default: 1, 0 = no blur)
rayHandler.setCulling(true);         // skip offscreen lights (default: true)

Other methods:

rayHandler.resizeFBO(newWidth, newHeight);   // resize internal FBOs
rayHandler.removeAll();                       // dispose and remove all lights
rayHandler.setWorld(newWorld);                // change Box2D world
rayHandler.setLightMapRendering(false);       // disable auto lightmap draw (for custom rendering)
rayHandler.getLightMapTexture();               // get lightmap as Texture for custom rendering
rayHandler.pointAtLight(worldX, worldY);      // is point inside any light?
rayHandler.pointAtShadow(worldX, worldY);     // is point in shadow?
rayHandler.dispose();                          // MUST call — disposes all lights, FBOs, shaders

Gotchas:

• updateAndRender() must be called OUTSIDE any batch.begin()/batch.end() block. RayHandler uses its own FBO and blend state internally.
• setCombinedMatrix takes OrthographicCamera, not the base Camera class. For a generic Camera, use the 5-arg Matrix4 overload.
• setAmbientLight(float) sets only the alpha channel, not a uniform grayscale. Use the 4-float or Color overload for full control.
• The FBO defaults to 1/4 screen resolution. Call resizeFBO() if you resize the window or need sharper lights.
• All light coordinates are in Box2D meters, not pixels. Use the same PPM convention as your Box2D world (see libgdx-box2d skill).

Light Types

PointLight

Omnidirectional light radiating from a point.

PointLight light = new PointLight(rayHandler, rays, color, distance, x, y);
// rays: more = smoother shadows, more expensive. 8-32 mobile, 64-128 desktop.
// distance: in meters (Box2D world units)
// x, y: in meters

// Minimal constructor (defaults: Color(0.75, 0.75, 0.5, 0.75), distance=15, position=0,0)
PointLight light = new PointLight(rayHandler, rays);

setDirection() is a deprecated no-op on PointLight — it radiates in all directions.

ConeLight

Directional spotlight with a cone angle.

ConeLight light = new ConeLight(rayHandler, rays, color, distance, x, y,
                                directionDegrees, coneDegrees);
// directionDegrees: center direction of the cone
// coneDegrees: HALF-angle of the cone (total arc = coneDegrees * 2), clamped [0, 180]

light.setDirection(degrees);
light.setConeDegree(halfAngle);     // HALF-angle, NOT full cone width
light.getConeDegree();

Gotcha: coneDegrees is the half-angle. Setting coneDegree=45 creates a 90-degree cone.

DirectionalLight

Parallel rays covering the entire screen (like sunlight).

DirectionalLight light = new DirectionalLight(rayHandler, rays, color, directionDegrees);
// No position or distance parameters — covers the whole viewport

light.setDirection(degrees);
light.setIgnoreBody(body);   // ignore a specific body's fixtures during raycasting (null to clear)

setPosition(), setDistance(), attachToBody() are all deprecated no-ops on DirectionalLight. getX()/getY() always return 0.

ChainLight

Emits light along a chain of vertices (e.g., for lava flows, light strips).

float[] vertices = {x1,y1, x2,y2, x3,y3, ...};  // pairs of (x,y) in meters
ChainLight light = new ChainLight(rayHandler, rays, color, distance, rayDirection, vertices);
// rayDirection: 1 = rays go left of chain, -1 = rays go right

// Modify chain at runtime:
light.chain.clear();
light.chain.addAll(newVertices);
light.updateChain();              // MUST call after modifying chain

setDirection() is a deprecated no-op on ChainLight.

Light Base Class API

All light types inherit these methods from Light:

// Position (PointLight, ConeLight, ChainLight only — no-op on DirectionalLight)
light.setPosition(x, y);              // meters
light.setPosition(new Vector2(x, y));
light.getX();
light.getY();

// Appearance
light.setColor(new Color(1, 0.8f, 0.6f, 1));
light.setColor(r, g, b, a);
light.setDistance(distMeters);         // light radius in meters

// Shadows
light.setSoft(true);                   // soft shadow edges
light.setSoftnessLength(2.5f);         // soft shadow penumbra length in world units
light.setXray(false);                  // true = light passes through all fixtures (no shadows)
light.setStaticLight(false);           // true = skip per-frame raycasting (~90% CPU savings)

// State
light.setActive(true);                 // toggle on/off
light.remove();                        // remove from RayHandler and dispose
light.remove(false);                   // remove without disposing (can re-add later)
light.dispose();

// Collision filtering — same system as Box2D fixtures
light.setContactFilter(categoryBits, groupIndex, maskBits);  // all short
light.setContactFilter(filter);                                // Filter object
Light.setGlobalContactFilter(categoryBits, groupIndex, maskBits); // static — default for new lights

// Pseudo-3D (experimental)
light.setHeight(heightDegrees);

CRITICAL: The method is setSoftnessLength(), NOT setSoftLength(). The getter is getSoftShadowLength().

Attaching Lights to Bodies

// Basic — light follows body position and rotation
light.attachToBody(body);

// With offset (PositionalLight only — PointLight, ConeLight)
light.attachToBody(body, offsetX, offsetY);              // offset in world units
light.attachToBody(body, offsetX, offsetY, angleDegrees); // offset + direction offset

// Ignore the attached body's fixtures (light doesn't shadow its own body)
light.setIgnoreAttachedBody(true);

After attachToBody(), setPosition() is relative to the body. The body's rotation affects the offset position and the light direction.

Gotcha: setIgnoreAttachedBody() is a deprecated no-op on DirectionalLight (which cannot attach to bodies).

Collision Filtering

Lights use the same Box2D categoryBits/groupIndex/maskBits system as fixtures. A light only casts shadows from fixtures whose filters allow collision with the light's filter. Default: lights interact with all fixtures (no filtering).

// Light only blocked by walls (category 0x0008)
light.setContactFilter(
    (short) 0x0020,   // categoryBits — what the light "is"
    (short) 0,         // groupIndex
    (short) 0x0008     // maskBits — what fixtures block this light
);

Parameter order: categoryBits, groupIndex, maskBits (same order as the Box2D Filter fields, but note that groupIndex comes second here, not third).

Use Light.setGlobalContactFilter(...) to set the default filter applied to all newly created lights.

Rendering Internals

RayHandler renders into an internal FBO (default: 1/4 screen resolution, RGBA8888). The process:

1. Bind FBO, clear to black
2. Render each light's mesh into FBO with additive blending (GL_SRC_ALPHA, GL_ONE)
3. Apply Gaussian blur passes if enabled
4. Blend FBO texture onto screen backbuffer

Performance

Platform Differences

Common Mistakes

1. Calling updateAndRender() inside batch.begin()/end() — RayHandler binds its own FBO and changes blend state. Always call after batch.end().
2. Using render() instead of updateAndRender() — render() exists but only draws the lightmap without updating light raycasts. Use updateAndRender() for the standard case.
3. Using pixel coordinates for light positions — box2dlights uses Box2D's meter-based coordinate system. A light at (400, 300) means 400 meters, not pixels.
4. Forgetting setCombinedMatrix() before rendering — Lights render at wrong positions or don't appear. Must call every frame before updateAndRender().
5. Passing Camera to setCombinedMatrix() — The method requires OrthographicCamera specifically. For a generic Camera, use the 5-arg (Matrix4, x, y, vpW, vpH) overload.
6. Using deprecated static setGammaCorrection()/useDiffuseLight() — These are no-ops (empty bodies). Use RayHandlerOptions at construction or instance methods applyGammaCorrection()/setDiffuseLight().
7. Expecting setAmbientLight(0.3f) to set gray ambient — The single-float overload sets only the alpha channel. Use setAmbientLight(0.3f, 0.3f, 0.3f, 1f) for gray ambient.
8. Not disposing shapes/RayHandler — RayHandler.dispose() disposes all lights, FBOs, and shaders. Omitting it leaks GPU resources.
9. Using setSoftLength() instead of setSoftnessLength() — The method is setSoftnessLength(float). setSoftLength does not exist.
10. Setting coneDegree to the full cone angle — ConeLight.setConeDegree() takes the half-angle. A value of 45 creates a 90-degree cone.
11. Expecting setStaticLight(true) lights to follow bodies — Static lights skip updateBody(). They only recalculate when you explicitly change a property. Use for lights on static geometry only.
12. Creating/destroying lights during updateAndRender() — Like Box2D's contact callbacks, avoid modifying the light list while the handler is iterating. Create/remove lights outside the render call.