Lighting Engine

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