Reference API Roblox

Engine API

Website

Related

Reference API Roblox

Lighting

The Lighting service controls global lighting in an experience. It includes a range of adjustable properties that you can use to change how lighting appears and interacts with other objects.

This class is not creatable. Instances of this class cannot be created with Instance.new.
This class is a service. It is a singleton that may be acquired with GetService.
Tags: [NotCreatable, Service]

Member index 29

HistoryMember
553Ambient: Color3
553Brightness: float
553ClockTime: float
553ColorShift_Bottom: Color3
553ColorShift_Top: Color3
553EnvironmentDiffuseScale: float
553EnvironmentSpecularScale: float
553ExposureCompensation: float
553FogColor: Color3
553FogEnd: float
553FogStart: float
553GeographicLatitude: float
553GlobalShadows: bool
653LightingStyle: LightingStyle
553OutdoorAmbient: Color3
553Outlines: bool
653PrioritizeLightingQuality: bool
553ShadowColor: Color3
553ShadowSoftness: float
631Technology: Technology
553TimeOfDay: string
645GetMinutesAfterMidnight(): double
645GetMoonDirection(): Vector3
462GetMoonPhase(): float
645GetSunDirection(): Vector3
573SetMinutesAfterMidnight(minutes: double): null
645getMinutesAfterMidnight(): double
573setMinutesAfterMidnight(minutes: double): null
462LightingChanged(skyChanged: bool)
inherited from Instance
553Archivable: bool
635Capabilities: SecurityCapabilities
553Name: string
553Parent: Instance
635Sandboxed: bool
616UniqueId: UniqueId
576AddTag(tag: string): null
573ClearAllChildren(): null
462Clone(): Instance
573Destroy(): null
486FindFirstAncestor(name: string): Instance
486FindFirstAncestorOfClass(className: string): Instance
486FindFirstAncestorWhichIsA(className: string): Instance
486FindFirstChild(name: string, recursive: bool = false): Instance
486FindFirstChildOfClass(className: string): Instance
486FindFirstChildWhichIsA(className: string, recursive: bool = false): Instance
486FindFirstDescendant(name: string): Instance
563GetActor(): Actor
486GetAttribute(attribute: string): Variant
462GetAttributeChangedSignal(attribute: string): RBXScriptSignal
631GetAttributes(): Dictionary
648GetChildren(): Instances
462GetDebugId(scopeLength: int = 4): string
486GetDescendants(): Array
486GetFullName(): string
641GetStyled(name: string): Variant
657GetStyledPropertyChangedSignal(property: string): RBXScriptSignal
576GetTags(): Array
576HasTag(tag: string): bool
486IsAncestorOf(descendant: Instance): bool
486IsDescendantOf(ancestor: Instance): bool
580IsPropertyModified(name: string): bool
573Remove(): null
576RemoveTag(tag: string): null
580ResetPropertyToDefault(name: string): null
573SetAttribute(attribute: string, value: Variant): null
462WaitForChild(childName: string, timeOut: double): Instance
648children(): Instances
553clone(): Instance
573destroy(): null
553findFirstChild(name: string, recursive: bool = false): Instance
648getChildren(): Instances
553isDescendantOf(ancestor: Instance): bool
573remove(): null
462AncestryChanged(child: Instance, parent: Instance)
462AttributeChanged(attribute: string)
462ChildAdded(child: Instance)
462ChildRemoved(child: Instance)
462DescendantAdded(descendant: Instance)
462DescendantRemoving(descendant: Instance)
500Destroying()
657StyledPropertiesChanged()
553childAdded(child: Instance)
inherited from Object
647ClassName: string
647className: string
647GetPropertyChangedSignal(property: string): RBXScriptSignal
647IsA(className: string): bool
650isA(className: string): bool
647Changed(property: string)

Removed member index 4

HistoryMember
653Intent: Intent
433LegacyOutlines: bool
653Quality: Quality

Description

The Lighting service controls global lighting in an experience. It includes a range of adjustable properties that you can use to change how lighting appears and interacts with other objects, as summarized in Lighting Properties.

Lighting may also contain an Atmosphere object to render realistic atmospheric effects, including particle density, haze, glare, and color. See Atmospheric Effects for details.

In addition, Lighting (along with Workspace.CurrentCamera) may contain post‑processing effects such as SunRaysEffect and BlurEffect.

History 122

Members 29

Ambient

TypeDefault
Color30.5, 0.5, 0.5

Ambient is the lighting hue applied to areas that are occluded from the sky, such as indoor areas.

Ambient defaults to [0, 0, 0] (black). As long as the red, green, and blue channels of this property do not exceed the corresponding channels in OutdoorAmbient, the change in hue will be reserved for areas occluded from the sun/moon.

Note that when GlobalShadows is disabled, there is no distinction between areas occluded from the sky and non‑occluded areas. In this case, OutdoorAmbient will be ignored and the hue from the Ambient property will be applied everywhere.

History 4

Brightness

TypeDefault
float1

The intensity of illumination in the place.

Changing this value will influence the impact of the light source (sun or moon) on the place's lighting. Note that Ambient and OutdoorAmbient can also be used to influence how bright a place appears. For example, setting OutdoorAmbient to [255, 255, 255] will make the place appear brighter than its default value of 127, 127, 127 (as it is more white).

History 4

ClockTime

TypeDefault
float14

A numerical representation (in hours) of the current time of day used by Lighting. Note that this property does not correspond with the actual time of day and will not change during gameplay unless it has been changed by a script.

For a measure of Lighting time formatted as a 24-hour string, use TimeOfDay. Changing TimeOfDay or using SetMinutesAfterMidnight() will also change this property.

This property is not replicated. Its interface does not cross the network boundary.

History 4

Tags: [NotReplicated]

ColorShift_Bottom

TypeDefault
Color30, 0, 0

The hue represented in light reflected in the opposite surfaces to those facing the sun or moon.

The surfaces of a BasePart influenced by ColorShift_Bottom depends on the position and orientation of the BasePart relative to the sun or moon's position. Where the sun is directly overhead a BasePart, the shift in color will only apply to the bottom surface.

This effect can be increased or reduced by altering Brightness.

Note that ColorShift_Top and ColorShift_Bottom will interact with the Ambient and OutdoorAmbient properties if they are greater than [0, 0, 0]. Also note that the influence of ColorShift_Bottom can be very hard to identify when GlobalShadows is enabled (default).

History 4

ColorShift_Top

TypeDefault
Color30, 0, 0

The hue represented in light reflected from surfaces facing the sun or moon.

The surfaces of a BasePart influenced by ColorShift_Top depends on the position and orientation of the BasePart relative to the sun or moon's position. Where the sun is directly overhead a BasePart, the shift in color will only apply to the top surface.

This effect can be increased or reduced by altering Brightness.

Note that ColorShift_Top and ColorShift_Bottom will interact with the Ambient and OutdoorAmbient properties if they are greater than [0, 0, 0].

History 4

EnvironmentDiffuseScale

TypeDefault
float0

Ambient light that is derived from the environment with a default of 0. This property is similar to Ambient and OutdoorAmbient but it's dynamic and can change according to the sky and time of day. When this property is increased, it's recommended to decrease Ambient and OutdoorAmbient accordingly.

History 4

EnvironmentSpecularScale

TypeDefault
float0

Specular light derived from environment with a default of 0. This property will make smooth objects reflect the environment and it is especially important to make metal look more realistic.

History 4

ExposureCompensation

TypeDefault
float0

This property determines the exposure compensation amount which applies a bias to the exposure level of the scene prior to the tonemap step. Defaults to 0 (no exposure compensation) and has a range from -5 to 5. A value of 1 indicates twice as much exposure and -1 means half as much exposure.

History 4

FogColor

TypeDefault
Color30.75, 0.75, 0.75

A Color3 value giving the hue of Lighting fog. Note that fog properties are hidden when Lighting contains an Atmosphere object.

History 4

FogEnd

TypeDefault
float100000

The depth from the Workspace.CurrentCamera, in studs, at which fog will be completely opaque. Note that fog properties are hidden when Lighting contains an Atmosphere object.

History 4

FogStart

TypeDefault
float0

The depth from the Workspace.CurrentCamera, in studs, at which fog begins to show. Note that fog properties are hidden when Lighting contains an Atmosphere object.

History 4

GeographicLatitude

TypeDefault
float41.7332993

The geographic latitude, in degrees, of the scene, influencing the result of Lighting time on the position of the sun and moon. When calculating the position of the sun, the earth's tilt is also taken into account.

Changing GeographicLatitude will alter the position of the sun at every TimeOfDay. If you're looking to obtain the sun or moon's position, use GetSunDirection() or GetMoonDirection().

History 4

GetMinutesAfterMidnight

Parameters (0)
No parameters.
Returns (1)
double

Returns the number of minutes that have passed after midnight for the purposes of lighting. This number will be nearly identical to ClockTime multiplied by 60.

Note that this number will not always be equal to the value given in SetMinutesAfterMidnight() as it returns minutes after midnight in the current day.

History 3

GetMoonDirection

Parameters (0)
No parameters.
Returns (1)
Vector3

Returns a Vector3 representing the direction of the moon from the position (0, 0, 0). Note that when the moon has "set" and is no longer visible, the Vector3 returned by this method will continue to point towards the moon below the horizon.

GetSunDirection() is a variant of this method for obtaining the direction of the sun.

History 3

GetMoonPhase

Parameters (0)
No parameters.
Returns (1)
float

Returns the moon's current phase. There is no way to change the moon's phase so this will always return 0.75.

History 2

GetSunDirection

Parameters (0)
No parameters.
Returns (1)
Vector3

Returns a Vector3 representing the direction of the sun from the position (0, 0, 0). Note that when the sun has "set" and is no longer visible, the Vector3 returned by this method will continue to point towards the sun below the horizon.

GetMoonDirection() is a variant of this method for obtaining the direction of the moon.

History 3

GlobalShadows

TypeDefault
boolfalse

Toggles voxel-based dynamic lighting in the place. When set to true, shadows are rendered in sheltered areas depending on the position of the sun and moon. The lighting hue applied to these sheltered areas is determined by the Ambient property while the lighting hue in all other areas is determined by the OutdoorAmbient property.

When false, shadows are not drawn and no distinction is made between indoor and outdoor areas. As a result, the Ambient property determines the lighting hue and OutdoorAmbient will do nothing.

Shadows are calculated using a voxel system and each lighting voxel is 4×4×4 studs. This means objects need to be larger than 4×4×4 studs to display a realistic shadow. Shadows are also recalculated when BaseParts are moving.

History 4

LightingChanged

Parameters (1)
skyChangedbool

This event fires when a Lighting property is changed or a Sky is added or removed from Lighting, with some exceptions:

In cases where this behavior is not desired, the Object.Changed event or Object:GetPropertyChangedSignal() method can be used.

History 5

LightingStyle

TypeDefault
LightingStyleRealistic
This property is not scriptable. It cannot be accessed by script code.

History 1

Tags: [NotScriptable]

OutdoorAmbient

TypeDefault
Color30.5, 0.5, 0.5

OutdoorAmbient is the lighting hue applied to outdoor areas.

OutdoorAmbient defaults to [127, 127, 127]. As long as the red, green, and blue channels of Ambient do not exceed the corresponding channels in OutdoorAmbient, the hue of the lighting in outdoor areas will be determined by this property.

The effective OutdoorAmbient value is clamped to be greater than or equal to Ambient in all channels, meaning that if a channel of Ambient exceeds its corresponding OutdoorAmbient channel, the hue of Ambient will begin to apply to outdoor areas.

Note that when GlobalShadows is disabled, there is no distinction between areas occluded from the sky and non‑occluded areas. In this case, OutdoorAmbient will be ignored and the hue from the Ambient property will be applied everywhere.

History 4

Outlines

TypeDefault
booltrue

This property determines whether outlines are enabled or disabled in a place.

Outlines can be disabled on a global basis, using this Lighting property, or alternatively on a surface-by-surface basis for BaseParts using SurfaceType.

Although this property can be set by scripts, it recommended this property is set in Roblox Studio prior to publishing the place.

This property is deprecated. It exists only for backward compatibility, and should not be used for new work.

History 5

Tags: [Deprecated]

PrioritizeLightingQuality

TypeDefault
booltrue
This property is not scriptable. It cannot be accessed by script code.

History 1

Tags: [NotScriptable]

SetMinutesAfterMidnight

Parameters (1)
minutesdouble
Returns (1)
null

Sets TimeOfDay and ClockTime to the given number of minutes after midnight.

This method allows a numerical value to be used, for example in a day/night cycle Script, without the need to convert to a string in the format required by TimeOfDay. It also allows values greater than 24 hours to be given that correspond to times in the next day.

The following code sample includes a simple day/night cycle script. The speed of time and the initial time can be changed using the TIME_SPEED and START_TIME parameters.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
local Lighting = game:GetService("Lighting")

local TIME_SPEED = 60  -- 1 min = 1 hour
local START_TIME = 9  -- 9 AM

local minutesAfterMidnight = START_TIME * 60
local waitTime = 60 / TIME_SPEED

while true do
	minutesAfterMidnight = minutesAfterMidnight + 1

	Lighting:SetMinutesAfterMidnight(minutesAfterMidnight)

	task.wait(waitTime)
end

History 3

ShadowColor

TypeDefault
Color30.7, 0.7, 0.72

This is supposed to change the color of player shadows, but currently doesn't do anything.

This property is deprecated. It exists only for backward compatibility, and should not be used for new work.
This property is not replicated. Its interface does not cross the network boundary.

History 5

Tags: [NotReplicated, Deprecated]

ShadowSoftness

TypeDefault
float0.5

Controls how blurry the shadows are with a default of 0.2. This property only works when Technology mode is ShadowMap or Future and the device is capable of rendering shadow maps.

History 4

Technology

TypeDefault
TechnologyCompatibility

Determines the lighting system for rendering the 3D world. This property is non‑scriptable and only modifiable in Studio. See Technology for available options and Lighting Technology for detailed descriptions and visual effects of each option.

History 8

TimeOfDay

TypeDefault
string14:00:00

A 24-hour string representation of the current time of day used by Lighting. Note that this property does not correspond with the actual time of day and will not change during gameplay unless it has been changed by a script.

For a numeric measure of Lighting time, use ClockTime. Changing ClockTime or using SetMinutesAfterMidnight() will also change this property.

History 4

getMinutesAfterMidnight

Parameters (0)
No parameters.
Returns (1)
double
This function is deprecated. It exists only for backward compatibility, and should not be used for new work. GetMinutesAfterMidnight should be used instead.

History 4

Tags: [Deprecated]

setMinutesAfterMidnight

Parameters (1)
minutesdouble
Returns (1)
null
This function is deprecated. It exists only for backward compatibility, and should not be used for new work. SetMinutesAfterMidnight should be used instead.

History 4

Tags: [Deprecated]

Removed members 4

Intent

TypeDefault
IntentRealistic
This property is not scriptable. It cannot be accessed by script code.

History 2

Tags: [NotScriptable]

LegacyOutlines

TypeDefault
bool
This property is not scriptable. It cannot be accessed by script code.

History 2

Tags: [NotScriptable]

Quality

TypeDefault
QualityQuality
This property is not scriptable. It cannot be accessed by script code.

History 2

Tags: [NotScriptable]

Settings