DayTime Documentation

A lightweight real-time (or manual) day/night cycle & timekeeper for GameMaker.
Uses a 24-color palette for hours in the day and smoothly blends between them.
Applies background and foreground tint & saturation effect for cinematic atmosphere without losing gameplay clarity.

Overview

DayTime gives your project:

• Smooth day and night transitions

• Separate foreground and background tint/saturation effects

• Real-time sync OR fully manual time

• “Freeze” mode for static atmospheres

• Hooks for hour, day, and time-period changes

• Formatting helpers for displaying time & date

• Safe Effect Layer creation and rebuilding

You can drop in the example for immediately results, but it's highly configurable.

Creating DayTime

DayTime(_foreground_depth = -5000, _background_depth = 1)

Creates a new DayTime controller.

Arguments and return

• _foreground_depth — depth where the foreground tint + saturation layers are created

• _background_depth — depth where the background tint + saturation layers are created

• Returns: the new DayTime instance

Example

// Create or Room Start 
day = new DayTime(-100, 100); global.day.rebuild_layers(); 

Running DayTime

Call update() once per Step.

Example

// Step Event 
day.update(); 

This'll update the DayTime and give you:

• Reads real-world time (or manual time if enabled)

• Applies offsets

• Blends the palette

• Applies tint and saturation effects

• Triggers hooks if things change (hour / period / date)

Real-World vs Manual Time

use_real_time()

Returns to reading system clock time.

Arguments and return

• none

• Returns: self

set_time(hour, minute = 0, second = 0)

Switches to manual time mode and sets the time.

Arguments and return

• hour 
  0-23

• minute 
  0-59

• second 
  0-59

• Returns: self

Values are clamped safely.

Example

day.set_time(23, 45); 

freeze_now()

Locks the cycle at the current real-world time, but keeps it manual.

Arguments and return

• none

• Returns: self

Example

day.freeze_now(); 

Perfect for static ambience.

set_offsets(hour_offset = 0, min_offset = 0)

Offsets the time after reading it.

Arguments and return

• hour_offset

• min_offset

• Returns: self

Works in real-time or manual mode.

Example

// Run the game 2 hours ahead 
day.set_offsets(2, 0); 

Color Palette

set_colors(array24)

Replaces the 24-hour palette.

Arguments and return

• array24 
  array of 24 GameMaker colors

• Returns: self

First entry = midnight, index matches hour.

Example

day.set_colors(my_palette); 

Tint & Saturation Strength

set_tint_ranges(foreground_strength = .20, background_strength = .75)

Controls tint strength by layer.

Arguments and return

• foreground_strength 
  subtle wash applied to gameplay layer

• background_strength s
  trong grade behind gameplay

• Returns: self

Night smoothly increases intensity.

set_saturation_ranges(fg_day, fg_night, bg_day, bg_night)

Controls how desaturated FG/BG become at night.

Arguments and return

• fg_day

• fg_night

• bg_day

• bg_night

• Returns: self

0 = full color
1 = greyscale

Layer Setup

rebuild_layers()

Creates or repairs Effect Layers if missing.

Arguments and return

• none

• Returns: self

This is safe to call anytime.

Example

global.day.rebuild_layers(); 

DayTime will also auto-repair if a layer disappears.

Hooks & Events

set_on_hour_change(fn)

Called whenever the hour changes.

Arguments and return

• fn(new_hour, old_hour)

• Returns: self

set_on_period_change(fn)

Period changes include:

• "night"

• "dawn"

• "day"

• "dusk"

Arguments and return

• fn(new_period, old_period)

• Returns: self

set_on_day_change(fn)

Triggered when the date changes.

Arguments and return

• fn(new_date_str, old_date_str)

• Returns: self

Example usage

day.set_on_hour_change(function(n, o) {     show_debug_message("Hour: " + string(n)); }); 

Formatting Helpers

These are great for UI.

time_24()

Returns "13:07"

time_12()

Returns "1:07 PM"

date_ymd()

Returns "2025-03-07"

date_pretty(long_month = false)

Returns something like:

"Fri, Mar 7 2025"

or

"Fri, March 7 2025"

weekday_longform() / weekday_shortform()

Returns:

• "Wednesday"

• "Wed"

get_period()

Returns:

• "night"

• "dawn"

• "day"

• "dusk"

Internal State You Can Read

DayTime exposes:

• year

• month

• day

• hour

• minute

• second

• weekday_index

• weekday_long_str

• weekday_short_str

• tint_color

• night_amount (0-1)

These are updated every update() call.

Usage Pattern (Recommended)

// Create 
day = new DayTime(-100, 100);
// Room Start 
day.rebuild_layers();  
// Step
day.update(); 

Then tweak:

day.set_tint_ranges(.2, .75)     
.set_saturation_ranges(0, .12, .1, .55);