Sun Light (Directional)

Sun light (Also known as directional light) is a single light source that shines from a relative position across the entirety of a world.

Controlling Sun Light

The sun light, which is called directional light, is controlled through a World instance. We're able to control its color, intensity and position.

The sun light's properties can be changed at anytime during gameplay.

Here's how we can change a world's sun light color.

world.setDirectionalLightColor({ r: 255, g: 0, b: 0 }); // A red sun light

Here's how we can change a world's sun light intensity. Intensity can be a value from 0 to 1+, with 1 being the default brightness, and anything above that being additional brightness.

world.setDirectionalLightIntensity(10); // Very bright lighting

And finally, here's how can update the sun light's position that the light of it directionally emits from across a world.

world.setDirectionalLightPosition({ x: 500, y: 100, z: 200 });

Basic Day & Night Cycle Example

Here's how we can use ambient & sun light (directional light) to create a day and night cycle for a world.

// Create a day/night cycle (60 second period)
let time = 0;
const updateRate = world.simulation.timestepS * 8; // update lighting every 8 ticks
const cycleLengthS = 60; // 60 seconds
const CYCLE_STEP = updateRate / cycleLengthS; // 60 fps * 60 seconds
const SUN_ORBIT_RADIUS = 100;
    
setInterval(() => {
  time = (time + CYCLE_STEP) % 1;
  const angle = time * Math.PI * 2;
    
  // Sun position
  const sunY = Math.sin(angle) * SUN_ORBIT_RADIUS;
  const sunZ = Math.cos(angle) * SUN_ORBIT_RADIUS;
    
  // Smooth transition factor (0 to 1)
  const dayProgress = (Math.sin(angle) + 1) / 2; // Normalized to 0-1 range for smooth transitions

  // Interpolate light intensities
  const directionalIntensity = 0.1 + (dayProgress * 0.7); // Smoothly varies between 0.1 and 0.8
  const ambientIntensity = 0.2 + (dayProgress * 0.8); // Smoothly varies between 0.2 and 1

  // Interpolate colors
  const directionalColor = {
    r: 64 + (dayProgress * 191), // 64 to 255
    g: 64 + (dayProgress * 191), // 64 to 255
    b: 128 + (dayProgress * 127), // 128 to 255
  };

  const ambientColor = {
    r: 40 + (dayProgress * 215), // 40 to 255
    g: 40 + (dayProgress * 215), // 40 to 255
    b: 80 + (dayProgress * 175), // 80 to 255
  };

  // Update lighting
  world.setDirectionalLightPosition({ x: 0, y: sunY, z: sunZ });
  world.setDirectionalLightIntensity(directionalIntensity);
  world.setDirectionalLightColor(directionalColor);
  world.setAmbientLightIntensity(ambientIntensity);
  world.setAmbientLightColor(ambientColor);
}, updateRate * 1000);

Here's what our day/night cycle looks like!

Resulting example of our day & night cycle.

Diving Deeper

The latest sun light API Reference can be found as part of the World API Reference here as directional lighting.

If there are features that we don't currently support for sun light that you'd like to see added to the HYTOPIA SDK, you can submit a feature request here.