Spot Lights

Spot lights emit in a cone shape from a position towards a target position or tracked entity. Spot lights can have their color, intensity, angle and penumbra controlled.

Spot lights are real time lighting and will recalculate light each frame based on object in the proximity of the light. This means spot lights come at a higher performance cost than ambient or directional lighting. Use spot lights sparingly.

Spot lights positioned to emit light from holes in a cave for a more realistic lighting effects on the ground.

Creating A Spot Light

Spot lights are created as a Light instance. The pattern of spot light usage is similar to entities. You must create an instance of a Light first, then spawn the light in the world. Here's how we can do that.

const light = new Light({
  type: LightType.SPOTLIGHT,
  angle: Math.PI / 8, // Spot light angle in radians
  color: { r: 255, g: 200, b: 200 }, // A pinkish color 
  intensity: 40,
  penumbra: 0.5, // Spot light penumbra
  position: { x: 0, y: 15, z: 0 }, // Position the spot light shines from
  trackedPosition: { x: 0, y: 0, z: 0 }, // Position the spot light shines towards
});

light.spawn(world);

Spot Light Entity Attachment & Tracking

One of the powerful features of spot lights is it's ability to be attached to an entity, or a fixed position, while the light shines towards a tracked position or tracked entity.

We can attach a spot light to an entity, and make it track another entity so that as the entities move around in the game the spot light continues to track the target relative to the attached entity's position.

const light = new Light({
  type: LightType.SPOTLIGHT,
  attachedToEntity: someEntity,
  angle: Math.PI / 8, // Spot light angle in radians
  intensity: 40,
  penumbra: 0.5, // Spot light penumbra
  trackedEntity: someOtherEntity,
});

light.spawn(world);

Alternatively, we can just as easily create our spot light at a fixed position, while tracking an entity.

const light = new Light({
  type: LightType.SPOTLIGHT,
  position: { x: -7, y: 10, z: -11 }, 
  angle: Math.PI / 8, // Spot light angle in radians
  intensity: 40,
  penumbra: 0.5, // Spot light penumbra
  trackedEntity: someOtherEntity,
});

light.spawn(world);

Positional & Tracking Updates

Spot light position, attachments and tracking properties can be updated at any point after being spawned. This allows you to create smooth movement and light tracking effects while using spotlights. The HYTOPIA client will automatically handle interpolation of these updates for smooth changes.

Diving Deeper

The Light class, which is used to create spot lights, supports a wide variety of features and is constantly evolving. If you'd like to learn move, we recommend you dig into the Light API Reference here.

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