Controlling Overlay Lights

# Course Introduction

You can use Overlay Light to both add light sources to the world and overlap multiple light sources at once. Use OverlayLightComponent and OverlayLightService to make light sources of various shapes.

# Checking Overlay Light

#### View from Scene

Use the Overlay Light (Scene-Only) button to see a Scene's Overlay Light.

[png](1768815334039499e1127879541809b4ac65049d8c739)

#### Viewing from Play

You need a method to use an Overlap Light when you enter a world. Set the `SetOverlayLightEnabled()` value to true. You need at least 1 light source to see. If there is no light source, the entire world will be dark.
    
    
    @Component
    script OverlayLightEnabler extends Component
        @ExecSpace("ServerOnly")
        method void OnBeginPlay()
            _OverlayLightService:SetOverlayLightEnabled(true)
        end
    end
    

# Types of Light Sources

There are 4 types of light sources available based on a creator's needs.

#### Spot

This is a circular light source. Control the shape of the circle by adjusting the property value. Isn't affected by `TransformComponent.Scale`. [png](1768806563088453cd1c0bd1343fb9ae6a2831c42472a)

#### Freeform

The creator can create a unique light source shape. [png](176880659998300d7ad91465c4202bd72461fd6d1977a)

#### Global

This light source affects the entire screen. The SortingLayer can't be affected by multiple Global Lights at the same time. [png](17688065857736f88865eafe848bb9ad57a593e2a3d4f)

#### Sprite

This shows the shape and color of a light source by combining the spotlight's RGBA color information that the creator chose. [png](1768806616414dd2742c352b94e2593bdb10c27eaf428)

# Main Properties

#### Light Combinations

OverlapOperation is a property that determines how the light will be visible following a preset calculation when multipe light sources overlap. This property has two values in Additive and AlphaBlend.

  * Additive: The more lights overlap, the brighter the overlap becomes. [png](17688093939099217ddd692914320ae627a2988768431)

  * AlphaBlend: The overlap is the color of the light source with the largest LightOrder value. [png](176889079569765366e3dcd9a428d94e0a4a05283396a)




#### Luminescence Control

Control a light's intensity, dimness, and scatter by changing various property values. Different light source types have different property types.

  * InnerRadius: The larger the value, the wider the area where the brightness is 100%. Used for Spot-type light sources.
  * OuterRadius: The larger the value, the wider the area where the brightness is 0%, creating a soft glow. Used for Spot-type light sources
  * SpotInnerAngle: Set the angle of a light with 100% brightness. Used for Spot-type light sources.
  * SpotOuterAngle: Set the angle of a light with 0% brightness. Used for Spot-type light sources.
  * FalloffIntensity: Set the steepness of light attenuation. Used for Spot- and Freeform-type light sources.
  * FalloffDistance: Set how far light scatters from a light source. The larger the value, the softer the scatter. Used for Freeform-type light sources.



# Controlling Light Sources

There are two ways to control the Overlay Light to suit a creator's world: OverlayLightComponent and OverlayLightService.

## OverlayLightComponent

Use OverlayLightComponent to view the shape of a light source in a Scene. The following is the easiest way to make a light source with OverlayLightComponent.

### Use Example

Create and place an entity with only a TransformComponent and use OverlayLightComponent to create and control a light source.

#### Creating a Light Source

  1. Create a new model and add TransformComponent.
  2. Access a world to create a Spot-type light source and write the following.


    
    
    @Component
    script OverlayLightSetup extends Component
        @ExecSpace("ClientOnly")
        method void OnBeginPlay()
        -- Activates the Overlay Light.
        _OverlayLightService:SetOverlayLightEnabled(true)
    
        local lightEntity = _SpawnService:SpawnByModelId("model://New_Model", "Light", Vector3.zero, self.Entity)
    
        -- Adds OverlayLightComponent to an entity.
        ---@type any
        local overlayLightComponent = lightEntity:AddComponent(OverlayLightComponent)
        end
    end
    

When you create a Freeform-type light source, you must include information about each point in that light source.
    
    
    @Component
    script OverlayLightShaper extends Component
        @ExecSpace("ClientOnly")
        method void OnBeginPlay()
        _OverlayLightService:SetOverlayLightEnabled(true)
    
        local lightEntity = _SpawnService:SpawnByModelId("model://New_Model", "Light", Vector3.zero, self.Entity)
    
        ---@type OverlayLightComponent
        local overlayLightComponent = lightEntity:AddComponent(OverlayLightComponent)
    
        -- Change the light source type to Freeform.
        overlayLightComponent.Type = OverlayLightType.Freeform
    
        -- Write the vertex list that defines a Freeform-type light source. 
        local freeformPoints = table.create(4)
        freeformPoints[1] = Vector2(1, 0)
        freeformPoints[2] = Vector2(0, 1)
        freeformPoints[3] = Vector2(-1, 0)
        freeformPoints[4] = Vector2(0, -1)
        overlayLightComponent.FreeformPoints = freeformPoints
        end
    end
    

#### Deleting Light Sources

Let's delete OverlayLightComponent to remove a light source. Add the following at the very bottom, to remove a light source after 10 seconds.
    
    
    @Component
    script DelayedOverlayRemoval extends Component
        @ExecSpace("ServerOnly")
        method void OnBeginPlay()
            wait(10)
            lightEntity:RemoveComponent(OverlayLightComponent)
        end
    end
    

## OverlayLightService

When you're using OverlayLightService, you can't view what was created in a Scene. But, since no entity is created, it will have less load than OverlayLightComponent. Creating a light source with OverlayLightService generates a serial number for each light source. You can use those serial numbers delete light sources.

### Use Example

Let's use OverlayLightService to create and control a light source.

#### Creating a Light Source
    
    
    @Component
    script FreeformOverlayLightSpawner extends Component
        @ExecSpace("ClientOnly")
        method void OnBeginPlay()
        _OverlayLightService:SetOverlayLightEnabled(true)
    
        -- Create an entity with Freeform-type light source information.
        local overlayLightInfo = FreeformTypeOverlayLightInfo(self.Entity)
    
        -- Enter information about each point in the light source's shape.
        local freeformPoints = table.create(4)
        freeformPoints[1] = Vector2(1, 1)
        freeformPoints[2] = Vector2(-1, 1)
        freeformPoints[3] = Vector2(-1, -1)
        freeformPoints[4] = Vector2(1, -1)
        overlayLightInfo.FreeformPoints = freeformPoints
    
        local serial = _OverlayLightService:SpawnFreeformTypeOverlayLight(overlayLightInfo)
        end
    end
    

> Tip If you want to control the FalloffDistance of a light source, you can do so by setting a value such as `overlayLightInfo.FalloffDistance = 2.5`.

#### Removing Light Sources

You have to use the OverlayLightService's method to delete light sources you created with OverlayLightService.
    
    
    @Component
    script OverlayLightDestroyer extends Component
        @ExecSpace("ClientOnly")
        method void OnBeginPlay()
        _OverlayLightService:DestroyOverlayLight(serial)
        end
    end