LogoLogo
  • Get Started
  • Getting Started
    • Initial Setup
    • Create Your First Game
    • API Reference
    • Build Your First World Map
    • Multiplayer Testing
    • Use Templates & Examples
    • Styling & Assets
      • Modeling Guidelines
      • Texturing Guidelines
      • Default Assets
  • Build Faster With AI Tools
  • SDK Guides
    • Assets
    • Audio & SFX
      • Audio Manager
    • Blocks & Chunks
      • Block Types
      • Block Type Registry
      • Chunks
      • Chunk Lattice
    • Camera
    • Chat & Commands
    • Debugging
    • Entities
      • Animations
      • Block Entities
      • Colliders & Hitbox
      • Child Entities
      • Entity Controllers
        • Base Entity Controller
        • Pathfinding Entity Controller
        • DefaultPlayer Entity Controller
        • Simple Entity Controller
      • Entity Manager
      • Model Entities
      • Movement & Pathfinding
      • Player Controlled Entities
    • Events
    • Input & Controls
    • Lighting
      • Ambient Light
      • Light Manager
      • Point Lights
      • Spot Lights
      • Sun Light (Directional)
    • Mobile
    • Persisted Data
    • Players
      • Player Manager
      • Persisted Player Data
    • Plugins
    • Physics
      • Colliders
      • Collision Groups
      • Debugging
      • Gravity
      • Raycasts
      • Rigid Bodies
    • User Interface
      • Overlay UI
      • Scene UIs
      • Scene UI Manager
    • Worlds
      • Map Data Format
  • Helpful Resources
    • HYTOPIA Architecture & Platform Overview
    • Useful Third-Party Tools
Powered by GitBook
On this page
  • Controlling Sun Light
  • Basic Day & Night Cycle Example
  • Diving Deeper
Export as PDF
  1. SDK Guides
  2. Lighting

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!

Diving Deeper

PreviousSpot LightsNextMobile

Last updated 4 months ago

The latest sun light API Reference can be found as part of the 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 .

World API Reference here
submit a feature request here
Resulting example of our day & night cycle.