Skip to main content

SunPositionUtils

Utility to position the sun and to retrieve sun information specific to Roblox.

Note this is not an accurate guess of where the sun would be on earth, but rather the computation to compute where Roblox is rendering the sun given the lighting properties set.

https://raw.githubusercontent.com/iryl1/RBX_DOCUMENTATIONS/c0db57fedf0540db2cd9eb65404ad258c3e21295/lighting.md

Functions​

getGeographicalLatitudeFromDirection​

</>
SunPositionUtils.getGeographicalLatitudeFromDirection(direction: Vector3) → number

Gets the geographical latitude from a vector pointing at the sun.

getClockTimeFromDirection​

</>
SunPositionUtils.getClockTimeFromDirection(direction: Vector3) → number

Gets the clock time for the given direction.

getClockTimeFromMoonDirection​

</>
SunPositionUtils.getClockTimeFromMoonDirection(direction: Vector3) → number

Gets the clock time from the given moon direction.

getDirection​

</>
SunPositionUtils.getDirection(
azimuthRad: number,
altitudeRad: number,
north: Vector3?
) → number

Gets the direction the sun should be facing given the azimuth and altitude

getSunPosition​

</>
SunPositionUtils.getSunPosition(
clockTime: number,
geoLatitude: number
) → (
Vector3,--

Sun position

Vector3--

Moon position

)

Estimates the sun position given the clockTime and geographical latitude.

getLightSourceBrightness​

</>
SunPositionUtils.getLightSourceBrightness(sunPositionData: SunPositionData) → number

A single float in [0.1, 1.0] that scales overall scene brightness. peaks at noon (1.0), bottoms out at midnight (0.1). derived directly from the sun's y position, which is itself just a function of clock time.

getLightSourceType​

</>
SunPositionUtils.getLightSourceType(sunPositionData: SunPositionData) → GlobalLightSourceType

Whether the sun or moon is the active light source. This is what actually tints shadows and direct illumination

getLightSourceDirection​

</>
SunPositionUtils.getLightSourceDirection(sunPositionData: SunPositionData) → Vector3

Gets the direction of the active light source (sun or moon). this is what actually tints shadows and direct illumination

getLightColor​

</>
SunPositionUtils.getLightColor(clockTime: number) → Color3

The color of the active light source (sun or moon). this is what actually tints shadows and direct illumination

getDiffuseAmbient​

</>
SunPositionUtils.getDiffuseAmbient(clockTime: number) → Color3

The diffuse component of ambient — softer than direct light but still contributes to scene brightness. peaks at full white during the day.

getSkyAmbientBottom​

</>
SunPositionUtils.getSkyAmbientBottom(
clockTime: number,
environmentDiffuseScale: number
) → Color3

The sky's contribution to ambient — this is what gives the sky its color cast on surfaces. ramps up around sunrise, stays on through sunset, then cuts out.

This is the bottom color

getSkyAmbientTop​

</>
SunPositionUtils.getSkyAmbientTop(
clockTime: number,
environmentDiffuseScale: number
) → Color3

a second sky ambient spline — this one has a wider ramp and contributes additional sky color. the difference between skyAmbientBottom and skyAmbientTop gives you the gradient from horizon to zenith.

This is the top color

getSunImageBrightness​

</>
SunPositionUtils.getSunImageBrightness(sunPositionData: SunPositionData) → number

Gets the sun image brightness

getMoonImageBrightness​

</>
SunPositionUtils.getMoonImageBrightness(
sunPositionData: SunPositionData,
environmentDiffuseScale: number
) → number

Gets the moon image brightness

getSkyboxGradient​

</>
SunPositionUtils.getSkyboxGradient(
clockTime: number,
environmentDiffuseScale: number
) → ColorSequence

Gets the sky ambient color sequence, which is a sunset glow during certain times of the day.

computeViewportLighting​

</>
SunPositionUtils.computeViewportLighting(args: ViewportLightingArgs) → ViewportLighting

Compute viewport lighting to match Roblox lighting

Show raw api
{
    "functions": [
        {
            "name": "getGeographicalLatitudeFromDirection",
            "desc": "Gets the geographical latitude from a vector pointing at the sun.",
            "params": [
                {
                    "name": "direction",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 37,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getClockTimeFromDirection",
            "desc": "Gets the clock time for the given direction.",
            "params": [
                {
                    "name": "direction",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 52,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getClockTimeFromMoonDirection",
            "desc": "Gets the clock time from the given moon direction.",
            "params": [
                {
                    "name": "direction",
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 64,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getDirection",
            "desc": "Gets the direction the sun should be facing given the azimuth and altitude",
            "params": [
                {
                    "name": "azimuthRad",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "altitudeRad",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "north",
                    "desc": "",
                    "lua_type": "Vector3?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 78,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getSunPosition",
            "desc": "Estimates the sun position given the clockTime and geographical latitude.",
            "params": [
                {
                    "name": "clockTime",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "geoLatitude",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "Sun position",
                    "lua_type": "Vector3"
                },
                {
                    "desc": "Moon position",
                    "lua_type": "Vector3"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 126,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getLightSourceBrightness",
            "desc": "A single float in `[0.1, 1.0]` that scales overall scene brightness. peaks at noon (`1.0`), bottoms out at midnight (`0.1`). derived directly from the sun's y position, which is itself just a function of clock time.",
            "params": [
                {
                    "name": "sunPositionData",
                    "desc": "",
                    "lua_type": "SunPositionData"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 134,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getLightSourceType",
            "desc": "Whether the sun or moon is the active light source. This is what actually tints shadows and direct illumination",
            "params": [
                {
                    "name": "sunPositionData",
                    "desc": "",
                    "lua_type": "SunPositionData"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "GlobalLightSourceType"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 151,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getLightSourceDirection",
            "desc": "Gets the direction of the active light source (sun or moon). this is what actually tints shadows and direct illumination",
            "params": [
                {
                    "name": "sunPositionData",
                    "desc": "",
                    "lua_type": "SunPositionData"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Vector3"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 167,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getLightColor",
            "desc": "The color of the active light source (sun or moon). this is what actually tints shadows and direct illumination",
            "params": [
                {
                    "name": "clockTime",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Color3\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 218,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getDiffuseAmbient",
            "desc": "The diffuse component of ambient — softer than direct light but still contributes to scene brightness. peaks at full white during the day.",
            "params": [
                {
                    "name": "clockTime",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Color3\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 251,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getSkyAmbientBottom",
            "desc": "The sky's contribution to ambient — this is what gives the sky its color cast on surfaces. ramps up around sunrise, stays on through sunset, then cuts out.\n\nThis is the bottom color",
            "params": [
                {
                    "name": "clockTime",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "environmentDiffuseScale",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Color3\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 260,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getSkyAmbientTop",
            "desc": "a second sky ambient spline — this one has a wider ramp and contributes additional sky color. the difference between `skyAmbientBottom` and `skyAmbientTop` gives you the gradient from horizon to zenith.\n\nThis is the top color",
            "params": [
                {
                    "name": "clockTime",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "environmentDiffuseScale",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Color3\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 296,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getSunImageBrightness",
            "desc": "Gets the sun image brightness",
            "params": [
                {
                    "name": "sunPositionData",
                    "desc": "",
                    "lua_type": "SunPositionData"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 334,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getMoonImageBrightness",
            "desc": "Gets the moon image brightness",
            "params": [
                {
                    "name": "sunPositionData",
                    "desc": "",
                    "lua_type": "SunPositionData"
                },
                {
                    "name": "environmentDiffuseScale",
                    "desc": "",
                    "lua_type": "number\n"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "number\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 343,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "getSkyboxGradient",
            "desc": "Gets the sky ambient color sequence, which is a sunset glow during certain times of the day.",
            "params": [
                {
                    "name": "clockTime",
                    "desc": "",
                    "lua_type": "number"
                },
                {
                    "name": "environmentDiffuseScale",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "ColorSequence\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 356,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        },
        {
            "name": "computeViewportLighting",
            "desc": "Compute viewport lighting to match Roblox lighting",
            "params": [
                {
                    "name": "args",
                    "desc": "",
                    "lua_type": "ViewportLightingArgs"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "ViewportLighting\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 384,
                "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "SunPositionUtils",
    "desc": "Utility to position the sun and to retrieve sun information specific to Roblox.\n\nNote this is not an accurate guess of where the sun would be on earth, but rather\nthe computation to compute where Roblox is rendering the sun given the lighting\nproperties set.\n\nhttps://raw.githubusercontent.com/iryl1/RBX_DOCUMENTATIONS/c0db57fedf0540db2cd9eb65404ad258c3e21295/lighting.md",
    "source": {
        "line": 13,
        "path": "src/sunpositionutils/src/Shared/SunPositionUtils.lua"
    }
}