API Reference
A list of Sundial’s functions and settings, including what each argument does and what each function returns. If you’re new to Sundial, the other pages walk you through using it in your game.
Sundial
Sundial
Creates a Sundial with default colours, brightness and day/night timings. It starts at Morning with Auto Time turned off. By default, it takes over drawing the application surface until CleanUp() is called.
new Sundial(manage_application_surface)
Methods
SetGrading() | Changes the grading colour for one of the six parts of the day. |
SetGradingStrength() | Changes how strongly a grading colour affects the scene. |
SetBrightness() | Sets how bright the outdoor scene should be during the day and at night. Sundial changes the brightness smoothly between the two. |
SetIndoorGrading() | Sets the base colour used for indoor areas. The indoor mask decides which parts of the scene this affects. |
SetIndoorGradingStrength() | Changes how strongly the indoor grading colour affects the scene. |
SetIndoorDaylightInfluence() | Controls how much of the outdoor grading colour reaches indoor areas. This changes colour, not brightness. |
SetIndoorBrightness() | Sets separate day and night brightness for indoor areas. Sundial blends between them as the day passes. |
SetMask() | Uses a surface to decide which parts of the scene are indoors. Black means outdoors, white means indoors, and grey blends the two. The mask can be any size. It will be stretched to fit the scene. |
SetMaskSprite() | Uses a sprite instead of a surface for the indoor mask. Black means outdoors, white means indoors, and grey blends the two. The sprite is stretched to fit the scene. |
ClearMask() | Removes the indoor mask. The whole scene will use the outdoor grading again. |
HasMask() | Checks whether the mask you supplied still exists, whether it is a surface or a sprite. |
GetMask() | Gets the surface or sprite currently being used as the indoor mask. Use HasMask() to check whether it still exists. |
SetTimeOfDay() | Moves Sundial to a position in the day from 0 to 1. Values outside that range wrap around. If a manual jump changes the period, only the new period's callbacks run. |
GetTimeOfDay() | Gets the current position in the day as a number from 0 to 1, where 0 is Morning and 1 is the end of the day. |
SetDayPercent() | Another name for SetTimeOfDay(). Sets how far through the day Sundial is, using a number from 0 to 1. |
GetDayPercent() | Another name for GetTimeOfDay(). Gets how far through the day Sundial is. |
SetMorningTime() | Sets what time on the 24-hour clock Morning begins. This changes the clock, not the length of the day or the grading. |
GetMorningTime() | Gets the 24-hour clock time when Morning begins. |
SetTime() | Moves Sundial to a particular time on the 24-hour clock. This does not turn Auto Time on or off, and skipped periods do not get their callbacks run. |
GetTime() | Gets the current time on Sundial's 24-hour clock. |
GetHour() | Gets the hour from Sundial's current clock time. |
GetMinute() | Gets the minute from Sundial's current clock time. |
SetCycleTiming() | Changes when the different parts of the day start and how long the colour changes between them take. All six values use a fraction of the day from 0 to 1. Invalid ordering causes a fatal error. |
SetAutoTime() | Turns automatic time on or off. When enabled, Sundial advances its clock using elapsed real time. |
GetAutoTime() | Checks whether Auto Time is turned on. It can still be turned on when the time speed is set to 0. |
SetDayLength() | Sets how many real seconds a complete day takes when Auto Time is on. This also changes the speed returned by GetSpeed(). |
GetDayLength() | Gets how many real seconds a complete game day takes at the current speed. |
SetSpeed() | Sets how quickly Sundial's clock moves when Auto Time is on. This also changes its day length. Use 0 to pause it without turning Auto Time off. |
GetSpeed() | Gets the current speed of Sundial's automatic clock. |
Update() | Updates the automatic clock immediately, including any period callbacks. Normally you can leave this alone, as Draw() and getters such as GetTime() and GetPeriod() update it too. |
GetPeriod() | Gets which of the six time periods is active. These are the periods you set in the IDE, rather than Sundial's additional colour-blending phases. |
OnPeriodChanged() | Adds a function that runs when Sundial moves from one period to another. You can add more than one. |
OnPeriod() | Adds a function to run when the specified period begins. Adding another function does not replace the ones already there. |
OnMorning() | Adds a function to run when Morning begins. |
OnDay() | Adds a function to run when Day begins. |
OnAfternoon() | Adds a function to run when Afternoon begins. |
OnDusk() | Adds a function to run when Dusk begins. |
OnNight() | Adds a function to run when Night begins. |
OnDawn() | Adds a function to run when Dawn begins. |
GetSunlightAmount() | Gets Sundial's current daylight value. Sundial uses this to work out brightness, but you can use it for your own lighting, shadows or other effects. |
GetPhase() | Gets the part of the day that currently has the strongest influence on the grading. This includes Sunset, Twilight and Predawn, which are separate from the six gameplay periods. |
GetPhaseName() | Gets the name of the current grading phase, such as "sunset" or "twilight". |
Draw() | Colour grades your game and draws the result on screen. For most games, just call Draw() in Post Draw. By default, Sundial stops GameMaker from drawing your game a second time. You can also give it your own surface and choose where to draw it. The surface you give it is left unchanged. |
CleanUp() | Restores the application-surface drawing setting captured when this Sundial was created. Call this from your controller's Clean Up event when it stops presenting the game. Repeated calls are safe. Sundial does not free your surfaces or sprites. |
Changes the grading colour for one of the six parts of the day.
Changes how strongly a grading colour affects the scene.
Sets how bright the outdoor scene should be during the day and at night. Sundial changes the brightness smoothly between the two.
Sets the base colour used for indoor areas. The indoor mask decides which parts of the scene this affects.
Changes how strongly the indoor grading colour affects the scene.
Controls how much of the outdoor grading colour reaches indoor areas. This changes colour, not brightness.
Sets separate day and night brightness for indoor areas. Sundial blends between them as the day passes.
Uses a surface to decide which parts of the scene are indoors. Black means outdoors, white means indoors, and grey blends the two. The mask can be any size. It will be stretched to fit the scene.
Sundial reads its red channel but will not delete the surface for you. If GameMaker destroys it, recreate it and call SetMask() again. Uses a sprite instead of a surface for the indoor mask. Black means outdoors, white means indoors, and grey blends the two. The sprite is stretched to fit the scene.
Sundial reads its red channel, not its transparency. The sprite origin is ignored, and areas trimmed away by GameMaker count as outdoors. Sundial will not animate the mask for you. Removes the indoor mask. The whole scene will use the outdoor grading again.
Checks whether the mask you supplied still exists, whether it is a surface or a sprite.
Gets the surface or sprite currently being used as the indoor mask. Use HasMask() to check whether it still exists.
Gets the current position in the day as a number from 0 to 1, where 0 is Morning and 1 is the end of the day.
Gets Sundial's current daylight value. Sundial uses this to work out brightness, but you can use it for your own lighting, shadows or other effects.
Gets the part of the day that currently has the strongest influence on the grading. This includes Sunset, Twilight and Predawn, which are separate from the six gameplay periods.
Gets the name of the current grading phase, such as "sunset" or "twilight".
Changes when the different parts of the day start and how long the colour changes between them take. All six values use a fraction of the day from 0 to 1. Invalid ordering causes a fatal error.
Moves Sundial to a position in the day from 0 to 1. Values outside that range wrap around. If a manual jump changes the period, only the new period's callbacks run.
Turns automatic time on or off. When enabled, Sundial advances its clock using elapsed real time.
Checks whether Auto Time is turned on. It can still be turned on when the time speed is set to 0.
Sets how many real seconds a complete day takes when Auto Time is on. This also changes the speed returned by GetSpeed().
Gets how many real seconds a complete game day takes at the current speed.
Sets how quickly Sundial's clock moves when Auto Time is on. This also changes its day length. Use 0 to pause it without turning Auto Time off.
Another name for SetTimeOfDay(). Sets how far through the day Sundial is, using a number from 0 to 1.
Another name for GetTimeOfDay(). Gets how far through the day Sundial is.
Sets what time on the 24-hour clock Morning begins. This changes the clock, not the length of the day or the grading.
Gets the 24-hour clock time when Morning begins.
Moves Sundial to a particular time on the 24-hour clock. This does not turn Auto Time on or off, and skipped periods do not get their callbacks run.
sundial.SetTime(18.5); // 18:30Gets which of the six time periods is active. These are the periods you set in the IDE, rather than Sundial's additional colour-blending phases.
Adds a function that runs when Sundial moves from one period to another. You can add more than one.
eSundialPeriod values. sundial.OnPeriodChanged(function(_from, _to) {
global.current_period = _to;
});Adds a function to run when the specified period begins. Adding another function does not replace the ones already there.
Adds a function to run when Morning begins.
Adds a function to run when Day begins.
Adds a function to run when Afternoon begins.
Adds a function to run when Dusk begins.
Adds a function to run when Night begins.
Adds a function to run when Dawn begins.
Updates the automatic clock immediately, including any period callbacks. Normally you can leave this alone, as Draw() and getters such as GetTime() and GetPeriod() update it too.
Restores the application-surface drawing setting captured when this Sundial was created. Call this from your controller's Clean Up event when it stops presenting the game. Repeated calls are safe. Sundial does not free your surfaces or sprites.
Colour grades your game and draws the result on screen. For most games, just call Draw() in Post Draw. By default, Sundial stops GameMaker from drawing your game a second time. You can also give it your own surface and choose where to draw it. The surface you give it is left unchanged.
// In Post Draw, colour grade your game.
sundial.Draw();
// Or draw your own surface at a chosen position and size.
sundial.Draw(my_surface, 0, 0, 1280, 720);Starting, stopping and loading
Starts Sundial using a preset from the Visual Editor. Sundial will handle the drawing for you and keep working when you change rooms. If it's already running, calling this again won't restart the day or change the preset. Call SundialStop() first if you want to switch presets.
SundialStop() first. sundial = SundialStart();
sundial.SetDayLength(600);Stops Sundial if you started it with SundialStart(). It puts GameMaker's drawing setting back the way it was. You can call it more than once. It won't change other Sundials you created yourself or masks you supplied.
SundialStop();Loads a Sundial preset you saved using Sundial Visual Editor. Without a name, it loads whichever preset you marked as Default.
Sundial manage application-surface drawing until CleanUp() is called. False to leave your renderer's setting untouched. Defaults to true. Pass undefined for the preset name to use the default preset with this option. sundial = SundialImport();
// Or load one named preset.
winter_sundial = SundialImport("Winter");Enums
Grading colours
The six parts of the day you can give their own colours and grading strengths.
Time
The six parts of the day reported by GetPeriod() and used by functions such as OnMorning() and OnNight().
Sundial's day begins. More detailed parts of the day used by Sundial's colour changes, including Sunset, Twilight and Predawn.
Version
Symbol index
Draw() | SundialGetAutoTime() | SundialGetDayLength() | SundialGetDayPercent() | SundialGetHour() | SundialGetMask() | SundialGetMinute() | SundialGetMorningTime() | SundialGetPeriod() | SundialGetPhase() | SundialGetPhaseName() | SundialGetSpeed() | SundialGetSunlightAmount() | SundialGetTime() | SundialGetTimeOfDay() | SundialHasMask() | SundialOnAfternoon() | SundialOnDawn() | SundialOnDay() | SundialOnDusk() | SundialOnMorning() | SundialOnNight() | SundialOnPeriod() | SundialOnPeriodChanged() | SundialSetAutoTime() | SundialSetBrightness() | SundialSetCycleTiming() | SundialSetDayLength() | SundialSetDayPercent() | SundialSetGrading() | SundialSetGradingStrength() | SundialSetIndoorBrightness() | SundialSetIndoorDaylightInfluence() | SundialSetIndoorGrading() | SundialSetIndoorGradingStrength() | SundialSetMask() | SundialSetMaskSprite() | SundialSetMorningTime() | SundialSetSpeed() | SundialSetTime() | SundialSetTimeOfDay() | SundialUpdate() | SundialSUNDIAL_VERSIONmacro