Lighting Engine - UQcsse3200/2026-studio-2 GitHub Wiki

Lighting System

Overview

The lighting system uses Box2DLights to provide dynamic lighting and shadow effects in the game. The system is built around a LightingEngine that manages all light sources through a centralized RayHandler.

Architecture

Core Components

LightingEngine

The main engine that processes all lighting calculations and rendering. It manages:

  • Ray handler setup and configuration
  • Ambient light levels
  • Rendering pipeline integration
LightingEngine engine = new LightingEngine(camera, physicsWorld);
engine.setAmbientLight(0.9f);  // 90% brightness
engine.render();  // Render all lights

LightingService

A global service that provides access to the LightingEngine through the ServiceLocator.

LightingService lightingService = new LightingService(camera, world);
ServiceLocator.registerLightingService(lightingService);

// Access from anywhere
LightingService service = ServiceLocator.getLightingService();
RayHandler rayHandler = service.getEngine().getRayHandler();

PointLightComponent

An entity component that creates a point light source. Can be added to any entity to make it emit light.

Key features:

  • Configurable ray count (affects quality vs performance)
  • Custom color and distance
  • Active/inactive toggling
  • Automatic position synchronization with entity
  • Softness and contact filter settings
Entity light = new Entity();
light.addComponent(new PointLightComponent(
    rayHandler,
    128,  // rays
    Color.YELLOW,
    4f    // distance
));

LightFactory

Factory class for creating light entities with preset configurations.

Entity pointLight = LightFactory.createPointLight();

Lighting Defaults

LightingDefaults provides consistent configuration across the system:

Property Value Purpose
AMBIENT_LIGHT 0.9f Base lighting level (adjustable via settings)
BLUR_NUM 3 Blur passes for shadow softness
RAYS 128 Ray count for light quality
DIST 4f Default light distance
NORMAL_COLOR golden/warm tint Default light color

Integration with Game Screens

The lighting engine is integrated into all game screens:

  1. Registration: Each screen creates a LightingService and registers it.

    LightingService lightingService =
    new LightingService(renderer.getCamera(), physicsEngine.getWorld());
ServiceLocator.registerLightingService(lightingService);
lightingEngine = lightingService.getEngine();

  2. Rendering: The engine is rendered after game objects.

    renderer.render(lightingEngine);

  3. Cleanup: The engine is disposed when the screen is disposed.

    lightingEngine.dispose();

Integrated screens:

  • MainGameScreen
  • LevelsGameScreen
  • Level2GameScreen
  • SandboxGameScreen

Light Sources

Arrow Projectiles

Each arrow type emits a colored light matching its visual appearance:

Arrow Type Color RGB Values
Fire Arrow Orange-red (0.55, 0.05, 0.02)
Ice Arrow Blue (0.05, 0.25, 0.65)
Poison Arrow Purple (0.20, 0.05, 0.25)
Poison Potion Purple (0.20, 0.05, 0.25)

These lights are automatically added to projectiles when created via ProjectileFactory.

User Settings

Brightness can be adjusted through the user settings:

UserSettings.Settings settings = UserSettings.get();
settings.brightnessValue = 0.7f;  // 70% brightness

// Stored for persistence
DisplaySettings displayMode = new DisplaySettings();
displayMode.brightness = 0.7f;

Dependencies

  • Box2DLights: com.badlogicgames.box2dlights:box2dlights
  • libGDX: physics and rendering backend
  • Physics World: required for ray casting and occlusion

Performance Considerations

  • Ray count: Higher RAYS values improve shadow quality but impact performance.
  • Ambient light: Lower values create more dramatic shadows.
  • Blur: Enabled by default (3 passes) for smooth shadow edges.
  • Contact filter: Lights are filtered to avoid casting shadows through ground layers.

Class Diagram