Sundynamics
A module for creating easy and realistic day cycles.
Calculates the sun’s position with high accuracy using the PSA algorithm.
-
Default settings can be modified in the Config sub-module, or changed at runtime using
:SetSettings(). -
The datetime is assumed to be in UTC and can’t be before January 1, 1970, otherwise, the module won’t function properly.
-
You can also adjust settings by editing the attributes on the Client and Server instances under the main module.
-
WARNING: Attributes are generated at runtime. Modify the Client and Server instances only within their corresponding run contexts.
-
The module provides three signals: DayPassed, OnSunrise and OnSunset.
-
Lighting.ClockTimeis internally modified by the module to align the sun’s position. As a result, its values are unreliable/nonlinear. Use:GetDateTime()instead. -
The MathUtil sub-module can be configured to run natively (using --!native) for improved performance (~0.0028ms → ~0.0014ms), though it is not enabled by default because performance is already high and native code space is limited.
-
[Latitude]- The geographic latitude of the location, from -90 to 90 degrees. -
[Longitude]- The geographic longitude of the location, from -180 to 180 degrees. -
[UseDayCycleDuration]- If true, the module will use[DayCycleDuration]. If false, it will use the sum of[DaytimeDuration]and[NighttimeDuration]. -
[DayCycleDuration]- The total duration of one full day cycle in seconds. -
[DaytimeDuration]- The duration of the daytime period in seconds. -
[NighttimeDuration]- The duration of the nighttime period in seconds. -
[UseAutoSync]- If true, clients with this setting enabled will sync with the server’s state.
A client can intentionally disable this to go out of sync.
But if either the server or the client re-enables it, the client’s state will snap to the server’s. -
[StartAtRealTime]- If true, when using:Start()the module will start at the current real-world UTC time. This overrides the[StartDateTime]setting. -
[StartDateTime]- The initial UTC datetime for the module, used only if[StartAtRealTime]is false.
Server.lua
-- Autosync is ON
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Sundynamics = require(ReplicatedStorage.Sundynamics)
Sundynamics:Start()
Client.lua
-- Autosync is ON
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Sundynamics = require(ReplicatedStorage.Sundynamics)
-- Just a require
Sundynamics:Start
- Starts the day cycle.
@param bypassAutoSync: Internal use at your own risk.
Sundynamics:Stop
- Stops the day cycle.
@param bypassAutoSync: Internal use at your own risk.
Sundynamics:Reset
- Resets datetime to [StartDateTime] setting in the config.
Sundynamics:Skip
- Skips datetime by the provided [seconds] amount, negative numbers are supported.
@param second: The amount of seconds to skip.
@param relativeToDay: If true, the skip amount is relative to the total day duration instead of an absolute number of seconds.
Sundynamics:SetSettings
- Updates config's settings with the values found in the provided [settings] table.
@param settings: The table containing settings to update.
Sundynamics:SetDateTime
- Sets the current datetime to the provided [dateTime] table.
@param dateTime: The new datetime to apply.
@param ignoreSignals: If true, no signals will be fired for this change.
Sundynamics:GetDateTime
- Returns current datetime the module uses.
@param returnClone: If true, will return a clone of the datetime instead of a direct reference.
@return table: The current datetime.
Sundynamics:IsFirstDateTimeAfterSecond
- Checks if [firstDateTime] is after [secondDateTime].
@param firstDateTime: The first datetime to compare.
@param secondDateTime: The second datetime to compare.
@param outputIfEqual: The value to return if the datetimes are equal.
@return boolean|T: True if the first datetime is after the second. If the datetimes are equal, returns [outputIfEqual].
Sundynamics:IsNight
- Checks if it is currently night.
@return boolean: True if night, otherwise false.
Sundynamics:IsDay
- Checks if it is currently day.
@return boolean: True if day, otherwise false.
1.0
- Initial Release.
1.01
-
ClockTimeandTimeOfDayRoblox properties no longer have negative values.NOTE: Negative values had no impact on the behavior, you could consider this a cosmetic change.
Also, avoid usingClockTime, it might look right, but it’s not. Thats what the:GetDateTime()method is for.
1.02
- Fixed an issue where enabling
UseAutoSyncdid not restart a stopped client-side day cycle while the server-side day cycle was active. Thanks to @23sinek345 for finding the issue
