Light

Light Physics Sandbox is a physics-based puzzle game built with Godot 4.5 and GDScript. Players manipulate light sources and colored blocks to collect matching flags, exploring realistic light mixing, RGB color interactions, and optical phenomena through hands-on puzzle solving.

Core Gameplay

The game revolves around an RGB color masking system: each block has a color mask (RED=1, GREEN=2, BLUE=4, WHITE=7), and can only be moved when it receives matching light. A block illuminated by red light can only be manipulated if its mask includes red — white light (all three channels) enables all blocks. This mechanic forces players to think about light composition and color mixing to solve each puzzle.

Levels are completed by collecting all flags. Each flag has a color requirement, and blocks must carry the correct light color to collect it. Victory triggers a celebration animation with scaling effects and a "Level Complete" overlay showing flag collection stats.

Three-Tier Light System

The lighting simulation runs across three complementary systems that can be swapped depending on performance needs:

• GPU Light System — Godot's native PointLight2D with pre-cached 64x64 radial gradient textures, BLEND_MODE_ADD, PCF5 shadow filtering, and dynamic intensity-based radius scaling. Optimised for high resolution and performance with a per-frame update loop that processes prism dispersion and crystal refraction.
• Enhanced Light System — A pixel-styled software system with ambient GPUParticles2D effects. Each light source emits ring-shaped edge particles at its radius boundary and sparse spray particles from its center. Includes full get_light_at_position() queries with squared-distance falloff for receiver detection.
• Hybrid Light System — An orchestrator wrapper that selects between the two above systems, providing a uniform add_light_source() / remove_light_source() API to the rest of the game.

Optics Simulation

• Prism — Splits white light into RGB components with angular dispersion (15 degree spread). Each dispersed color beam is a separate PointLight2D with ADD blending and shadow support, capped to 2-3 simultaneous dispersions for performance.
• Dichroic Filter — A semi-transparent BlockBase that passes specific color wavelengths while reflecting others. For example, a yellow filter transmits red+green while reflecting blue. Uses bitmask comparison to determine pass/reflect behaviour.
• Water Prism — Creates refraction effects by bending light 20 degrees (simplified Snell's law). Refracted beams receive the source color at boosted intensity, mimicking real-world light path bending through translucent media.
• Color Gate — A blocking gate that only allows blocks with a matching color to pass through. When a block with mismatched colour contacts the gate, it slides along the collision normal instead.

Interactive Entities

• PixelLightSource — Point lights with pixel-styled rendering (nearest-neighbour filtering on a 32x32 texture). Includes four visual layers: glow sprite with sinusoidal pulsing, pixel light core, GPU PointLight2D, edge ring particles (GPUParticles2D at radius boundary), and spray particles from center. Intensity controls both brightness and effective radius.
• SpotLight — Directional cone lights with configurable cone angle and range. Performs angle-to-block checks using Vector2.angle_to() with half-cone-angle comparison.
• BlockBase — Physics-enabled CharacterBody2D with collision detection, ray-traced shadow computation (PhysicsRayQueryParameters2D per light source), and a LightOccluder2D for casting shadows. Features smooth pick-up/drop animations (scale bounce with Tween TRANS_BACK/TRANS_ELASTIC) and a custom shader for highlight effects on hover.
• Wall — Static obstacles with configurable dimensions. Blocks slide along wall collision normals during drag, using PhysicsTestMotionParameters2D for continuous collision detection.
• CarrierBlock — A pushable block variant that can carry light color properties to distant parts of a level.
• Flag — Collectibles with colour requirements. Emits a flag_collected signal on collection, tracked by the game scene for victory condition checking.

Level Editor

A full sandbox editor built into the game. Features a toolbox for spawning entities (lights, blocks, walls, gates, flags, prisms, filters), a property panel for editing entity attributes (color, intensity, cone angle, dimensions), a scene panel for save/load and background customization, and keyboard shortcuts (Ctrl+S save, Ctrl+O load, Ctrl+N new). Background type and color data is serialized alongside entity data in the JSON level format.

Audio & UI

The game includes a global BGM manager singleton with automatic fade-in (2s) and fade-out (1.5s) transitions, loop support, and persistent volume control using logarithmic scaling (linear_to_db() conversion). The settings panel provides master volume slider and fullscreen toggle. All UI uses a pixel font theme (HYPixel9pxJ-2) applied globally through Godot's theme system.

Technical Details

• Engine: Godot 4.5 (Forward Plus renderer)
• Language: GDScript (~50+ scripts)
• Resolution: 1280x720 with canvas_items stretch mode
• Level Format: JSON with versioning (v0.6.0), dual-path loading (built-in via ResourceLoader, user levels via FileAccess)
• Data: ConfigFile for settings persistence (user://settings.cfg)
• Aesthetic: Pixel art style with nearest-neighbour texture filtering, dark color palette (clear colour #000), custom pixel font