Skip to content

Dynamic Lighting

Dynamic lighting in LITIENGINE uses LightSource entities to illuminate the game world in real-time. This creates atmospheric effects like torches, lamps, and spell glow.

How Dynamic Lighting Works

  1. Ambient Light: A base illumination level for the entire map
  2. Light Sources: Point lights that illuminate surrounding areas
  3. Shadows: Static geometry can cast shadows from light sources
  4. Color Blending: Multiple light colors blend together

Ambient Light

Set the base illumination for an environment:

// Set ambient light color (affects entire map)
Color ambient = new Color(60, 60, 80); // Dim blue-ish ambient
Game.world().environment().setAmbientLight(ambient);

Or configure in config.properties:

gfx_ambientLight=3d3d50
gfx_ambientAlpha=0.8

Creating Light Sources

Via utiLITI

  1. Add a LightSource entity to your map
  2. Configure intensity, color, and shape in the Properties panel

Via Code

LightSource torch = new LightSource();
torch.setLocation(100, 100);
torch.setIntensity(150); // Light radius
torch.setColor(Color.ORANGE); // Light color
torch.setShape(LightSource.ELLIPSE); // Light shape

// Add to environment
Game.world().environment().add(torch);

Light Properties

Intensity

Controls the radius of illumination:

light.setIntensity(100); // Small light
light.setIntensity(200); // Medium light
light.setIntensity(400); // Large light

Color

// Warm light (torch)
light.setColor(Color.ORANGE);

// Cool light (magic)
light.setColor(Color.CYAN);

// Dim light
light.setColor(new Color(200, 150, 100));

// Bright white
light.setColor(Color.WHITE);

Shape

// Circular/ellipse light
light.setShape(LightSource.ELLIPSE);

// Rectangular light
light.setShape(LightSource.RECTANGLE);

Flickering

Add flickering effect for torches and fire:

// Enable flicker
light.setFlicker(true);
light.setFlickerIntensity(0.2f); // 20% intensity variation
light.setFlickerSpeed(100); // Flicker interval in ms

Shadow Casting

Static collision boxes can cast shadows:

Enable in utiLITI

  1. Select a CollisionBox
  2. Enable Shadow Casting in properties
  3. Set shadow type

Via Code

CollisionBox wall = new CollisionBox();
wall.setCastShadow(true);

Dynamic Light Behavior

Moving Lights

Lights can follow entities:

public class TorchBearer extends Creature {
  private LightSource torchLight;

  @Override
  public void update() {
    super.update();
    // Light follows entity
    torchLight.setLocation(this.getCenter());
  }
}

Toggling Lights

// Turn light on/off
light.setActive(false);
light.setActive(true);

// Check state
boolean isOn = light.isActive();

Animated Lights

Pulsing or animated lighting:

Game.loop().attach(() -> {
  float pulse = (float) Math.sin(Game.time().now() / 200.0) * 0.3f + 0.7f;
  light.setIntensity((int)(150 * pulse));
});

Performance Considerations

Dynamic lighting is computationally expensive:

  1. Limit light count: Fewer lights = better performance
  2. Use appropriate intensity: Smaller lights are faster to calculate
  3. Disable when not needed: Turn off lights in inactive areas
  4. Consider static lighting: Use static lighting where possible

Configuration

# Enable/disable dynamic lighting
gfx_enableDynamicShadows=true

# Ambient light settings
gfx_ambientLight=3d3d50
gfx_ambientAlpha=0.8

See Also

Programmatic LightSource Management

You can spawn, configure, and animate LightSource entities at runtime in pure Java:

package com.example.game.lighting;

import de.gurkenlabs.litiengine.Game;
import de.gurkenlabs.litiengine.entities.LightSource;
import java.awt.Color;
import java.awt.geom.Point2D;

public class TorchLight {
  public static LightSource createTorch(double x, double y) {
    // 1. Create a radial ellipse light source (radius = 120, warm amber color)
    Color warmGlow = new Color(255, 180, 50, 180);
    LightSource torch = new LightSource(120, warmGlow, LightSource.Type.ELLIPSE);
    torch.setLocation(x, y);

    // 2. Add to active environment
    Game.world().environment().add(torch);

    // 3. Add ambient world darkness (RGBA)
    Game.world().environment().getAmbientLight().setColor(new Color(10, 15, 25, 220));

    return torch;
  }
}

Animating Light Flicker

// Create a flickering torch flame effect in your game loop
Game.loop().attach(Game.world().environment(), () -> {
  int jitter = (int) (Math.random() * 8) - 4;
  torch.setRadius(120 + jitter);
});