Avoid running untrusted scripts! They can compromise your system and data
For more info, read here

Time

Work with timestamps, date formatting, and time calculations.

Current Time and Formatting

time.unix

Signature: time.unix()

Description: Returns the current Unix timestamp in seconds.

Parameters: None

Returns:

  • number: The current Unix timestamp (seconds since January 1, 1970).

Example:

local current_timestamp = time.unix()
engine.log("Current Unix timestamp: " .. current_timestamp, 255, 255, 255, 255)

time.unix_ms

Signature: time.unix_ms()

Description: Returns the current Unix timestamp in milliseconds.

Parameters: None

Returns:

  • number: The current Unix timestamp in milliseconds.

Example:

local current_ms_timestamp = time.unix_ms()
engine.log("Current Unix timestamp (ms): " .. current_ms_timestamp, 255, 255, 255, 255)

-- Calculate elapsed time with millisecond precision
local start_time = time.unix_ms()
-- ... perform some operation ...
local end_time = time.unix_ms()
local elapsed_ms = end_time - start_time
engine.log("Operation took " .. elapsed_ms .. " milliseconds", 255, 255, 255, 255)

time.now_utc

Signature: time.now_utc()

Description: Returns the current UTC time as a formatted string.

Parameters: None

Returns:

  • string: The current UTC time in the format "YYYY-MM-DD HH:MM:SS".

Example:

local utc_time = time.now_utc()
engine.log("Current UTC time: " .. utc_time, 255, 255, 255, 255)

time.now_local

Signature: time.now_local()

Description: Returns the current local time as a formatted string.

Parameters: None

Returns:

  • string: The current local time in the format "YYYY-MM-DD HH:MM:SS".

Example:

local local_time = time.now_local()
engine.log("Current local time: " .. local_time, 255, 255, 255, 255)

time.format

Signature: time.format(timestamp)

Description: Converts a Unix timestamp to a local date-time string.

Parameters:

  • timestamp (number): The Unix timestamp to format.

Returns:

  • string: The formatted date-time string in the format "YYYY-MM-DD HH:MM:SS".

Example:

local timestamp = time.unix()
local formatted_time = time.format(timestamp)
engine.log("Formatted time: " .. formatted_time, 255, 255, 255, 255)

-- Format a past timestamp
local past_timestamp = timestamp - 86400 -- 24 hours ago
local yesterday = time.format(past_timestamp)
engine.log("24 hours ago: " .. yesterday, 255, 255, 255, 255)

time.format_custom

Signature: time.format_custom(timestamp, format)

Description: Formats a timestamp using a custom format string (in UTC).

Parameters:

  • timestamp (number): The Unix timestamp to format.

  • format (string): The format string using strftime() syntax.

Returns:

  • string: The formatted date-time string according to the specified format.

Example:

local timestamp = time.unix()

-- Format with various patterns
local date_only = time.format_custom(timestamp, "%Y-%m-%d")
local time_only = time.format_custom(timestamp, "%H:%M:%S")
local custom = time.format_custom(timestamp, "%A, %B %d, %Y at %I:%M %p")

engine.log("Date only: " .. date_only, 255, 255, 255, 255)
engine.log("Time only: " .. time_only, 255, 255, 255, 255)
engine.log("Custom format: " .. custom, 255, 255, 255, 255)

Comparison and Difference

time.delta

Signature: time.delta(t1, t2)

Description: Returns the difference between two timestamps in seconds.

Parameters:

  • t1 (number): The first timestamp.

  • t2 (number): The second timestamp.

Returns:

  • number: The difference between t2 and t1 in seconds (t2 - t1).

Example:

local start_time = time.unix()
-- ... perform some operation ...
local end_time = time.unix()

local elapsed = time.delta(start_time, end_time)
engine.log("Operation took " .. elapsed .. " seconds", 255, 255, 255, 255)

time.compare

Signature: time.compare(t1, t2)

Description: Compares two timestamps and returns their relative order.

Parameters:

  • t1 (number): The first timestamp.

  • t2 (number): The second timestamp.

Returns:

  • number: -1 if t1 < t2, 0 if t1 == t2, or 1 if t1 > t2.

Example:

local now = time.unix()
local then = now - 3600 -- 1 hour ago

local result = time.compare(now, then)
if result > 0 then
    engine.log("Now is later than the past timestamp", 255, 255, 255, 255)
elseif result < 0 then
    engine.log("Now is earlier than the past timestamp", 255, 255, 255, 255)
else
    engine.log("Timestamps are equal", 255, 255, 255, 255)
end

time.same_day

Signature: time.same_day(t1, t2)

Description: Returns true if both timestamps fall on the same calendar day.

Parameters:

  • t1 (number): The first timestamp.

  • t2 (number): The second timestamp.

Returns:

  • boolean: true if the timestamps are on the same calendar day, false otherwise.

Example:

local now = time.unix()
local earlier_today = now - 3600 -- 1 hour ago
local yesterday = now - 86400 -- 24 hours ago

if time.same_day(now, earlier_today) then
    engine.log("Now and 1 hour ago are on the same day", 255, 255, 255, 255)
else
    engine.log("Now and 1 hour ago are on different days", 255, 255, 255, 255)
end

if time.same_day(now, yesterday) then
    engine.log("Now and yesterday are on the same day", 255, 255, 255, 255)
else
    engine.log("Now and yesterday are on different days", 255, 255, 255, 255)
end

time.diff_table

Signature: time.diff_table(t1, t2)

Description: Returns a breakdown of the time difference in days, hours, minutes, and seconds.

Parameters:

  • t1 (number): The first timestamp.

  • t2 (number): The second timestamp.

Returns:

  • table: A table with the following fields:

    • days (number): Number of days difference.

    • hours (number): Number of hours difference (0-23).

    • minutes (number): Number of minutes difference (0-59).

    • seconds (number): Number of seconds difference (0-59).

    • total_seconds (number): Total difference in seconds.

Example:

local now = time.unix()
local past = now - 123456 -- Some time in the past

local diff = time.diff_table(past, now)
engine.log("Time difference:", 255, 255, 255, 255)
engine.log("  Days: " .. diff.days, 255, 255, 255, 255)
engine.log("  Hours: " .. diff.hours, 255, 255, 255, 255)
engine.log("  Minutes: " .. diff.minutes, 255, 255, 255, 255)
engine.log("  Seconds: " .. diff.seconds, 255, 255, 255, 255)
engine.log("  Total seconds: " .. diff.total_seconds, 255, 255, 255, 255)

time.between

Signature: time.between(now, start, end)

Description: Checks if a timestamp falls within a time range.

Parameters:

  • now (number): The timestamp to check.

  • start (number): The start of the time range.

  • end (number): The end of the time range.

Returns:

  • boolean: true if now falls between start and end (inclusive), false otherwise.

Example:

local now = time.unix()
local start = now - 3600 -- 1 hour ago
local end_time = now + 3600 -- 1 hour from now

if time.between(now, start, end_time) then
    engine.log("Current time is within the specified range", 255, 255, 255, 255)
else
    engine.log("Current time is outside the specified range", 255, 255, 255, 255)
end

-- Check if a specific timestamp is in an event window
local event_start = time.timestamp_utc(2023, 12, 24, 0, 0, 0) -- Christmas Eve
local event_end = time.timestamp_utc(2023, 12, 26, 0, 0, 0) -- Day after Christmas
if time.between(now, event_start, event_end) then
    engine.log("Christmas event is active!", 255, 0, 0, 255)
end

Date Info and Conversion

time.weekday

Signature: time.weekday(timestamp)

Description: Gets the day of the week from a timestamp.

Parameters:

  • timestamp (number): The Unix timestamp.

Returns:

  • number: The day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday).

Example:

local now = time.unix()
local day = time.weekday(now)
local day_names = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"}

engine.log("Today is " .. day_names[day+1], 255, 255, 255, 255)

time.day_of_year

Signature: time.day_of_year(timestamp)

Description: Returns the day number within the year (1-366).

Parameters:

  • timestamp (number): The Unix timestamp.

Returns:

  • number: The day of the year (1-366).

Example:

local now = time.unix()
local day_num = time.day_of_year(now)
engine.log("Day of year: " .. day_num, 255, 255, 255, 255)

-- Calculate days left in the year
local year_info = time.year_month_day(now)
local days_in_year = time.is_leap_year(now) and 366 or 365
local days_left = days_in_year - day_num
engine.log("Days left in " .. year_info.year .. ": " .. days_left, 255, 255, 255, 255)

time.year_month_day

Signature: time.year_month_day(timestamp)

Description: Returns a table with year, month, and day components.

Parameters:

  • timestamp (number): The Unix timestamp.

Returns:

  • table: A table with the following fields:

    • year (number): The year.

    • month (number): The month (1-12).

    • day (number): The day of the month (1-31).

Example:

local now = time.unix()
local date = time.year_month_day(now)

engine.log("Current date:", 255, 255, 255, 255)
engine.log("  Year: " .. date.year, 255, 255, 255, 255)
engine.log("  Month: " .. date.month, 255, 255, 255, 255)
engine.log("  Day: " .. date.day, 255, 255, 255, 255)

time.is_weekend

Signature: time.is_weekend(timestamp)

Description: Returns true if the timestamp falls on Saturday or Sunday.

Parameters:

  • timestamp (number): The Unix timestamp.

Returns:

  • boolean: true if the day is Saturday or Sunday, false otherwise.

Example:

local now = time.unix()
if time.is_weekend(now) then
    engine.log("It's the weekend!", 0, 255, 0, 255)
else
    engine.log("It's a weekday", 255, 255, 255, 255)
end

time.is_leap_year

Signature: time.is_leap_year(timestamp)

Description: Checks if the year of the timestamp is a leap year.

Parameters:

  • timestamp (number): The Unix timestamp.

Returns:

  • boolean: true if it's a leap year, false otherwise.

Example:

local now = time.unix()
local date = time.year_month_day(now)

if time.is_leap_year(now) then
    engine.log(date.year .. " is a leap year", 0, 255, 0, 255)
else
    engine.log(date.year .. " is not a leap year", 255, 255, 255, 255)
end

time.days_in_month

Signature: time.days_in_month(year, month)

Description: Returns the number of days in a given month and year.

Parameters:

  • year (number): The year.

  • month (number): The month (1-12).

Returns:

  • number: The number of days in the specified month (28-31).

Example:

local now = time.unix()
local date = time.year_month_day(now)
local days = time.days_in_month(date.year, date.month)

engine.log("There are " .. days .. " days in month " .. date.month .. " of " .. date.year, 255, 255, 255, 255)

-- Check days in February for the current year
local feb_days = time.days_in_month(date.year, 2)
engine.log("February " .. date.year .. " has " .. feb_days .. " days", 255, 255, 255, 255)

time.timestamp_utc

Signature: time.timestamp_utc(year, month, day, hour, min, sec)

Description: Converts a date and time to a UTC Unix timestamp.

Parameters:

  • year (number): The year.

  • month (number): The month (1-12).

  • day (number): The day of the month (1-31).

  • hour (number): The hour (0-23).

  • min (number): The minute (0-59).

  • sec (number): The second (0-59).

Returns:

  • number: The corresponding Unix timestamp.

Example:

-- Create a timestamp for a specific date and time (UTC)
local christmas_eve = time.timestamp_utc(2023, 12, 24, 20, 0, 0) -- 8:00 PM UTC on Dec 24, 2023
engine.log("Christmas Eve timestamp: " .. christmas_eve, 255, 255, 255, 255)
engine.log("Formatted: " .. time.format(christmas_eve), 255, 255, 255, 255)

-- Create a timestamp for an upcoming event
local event_year = 2024
local event_timestamp = time.timestamp_utc(event_year, 7, 4, 18, 0, 0) -- July 4th at 6:00 PM UTC
local now = time.unix()

if now < event_timestamp then
    local diff = time.diff_table(now, event_timestamp)
    engine.log("Upcoming event in " .. diff.days .. " days, " .. diff.hours .. " hours", 255, 255, 255, 255)
end

time.add_days

Signature: time.add_days(timestamp, days)

Description: Adds (or subtracts) days to a timestamp.

Parameters:

  • timestamp (number): The Unix timestamp.

  • days (number): The number of days to add (can be negative).

Returns:

  • number: The new timestamp.

Example:

local now = time.unix()
local tomorrow = time.add_days(now, 1)
local yesterday = time.add_days(now, -1)
local next_week = time.add_days(now, 7)

engine.log("Now: " .. time.format(now), 255, 255, 255, 255)
engine.log("Tomorrow: " .. time.format(tomorrow), 255, 255, 255, 255)
engine.log("Yesterday: " .. time.format(yesterday), 255, 255, 255, 255)
engine.log("Next week: " .. time.format(next_week), 255, 255, 255, 255)

time.start_of_day

Signature: time.start_of_day(timestamp)

Description: Returns a timestamp for 00:00:00 of the day.

Parameters:

  • timestamp (number): The Unix timestamp.

Returns:

  • number: A timestamp for the start of the day (midnight 00:00:00).

Example:

local now = time.unix()
local day_start = time.start_of_day(now)

engine.log("Current time: " .. time.format(now), 255, 255, 255, 255)
engine.log("Start of day: " .. time.format(day_start), 255, 255, 255, 255)

-- Check if a value was reset today
local last_reset = 1672531200 -- Example: January 1, 2023
local today_start = time.start_of_day(now)

if last_reset < today_start then
    engine.log("Value needs to be reset (last reset was before today)", 255, 0, 0, 255)
else
    engine.log("Value already reset today", 0, 255, 0, 255)
end

time.end_of_day

Signature: time.end_of_day(timestamp)

Description: Returns a timestamp for 23:59:59 of the day.

Parameters:

  • timestamp (number): The Unix timestamp.

Returns:

  • number: A timestamp for the end of the day (23:59:59).

Example:

local now = time.unix()
local day_end = time.end_of_day(now)

engine.log("Current time: " .. time.format(now), 255, 255, 255, 255)
engine.log("End of day: " .. time.format(day_end), 255, 255, 255, 255)

-- Calculate seconds until the end of the day
local seconds_left = time.delta(now, day_end)
engine.log("Seconds until end of day: " .. seconds_left, 255, 255, 255, 255)

Tables and Structures

time.to_table

Signature: time.to_table(timestamp)

Description: Converts a timestamp to a local date-time table.

Parameters:

  • timestamp (number): The Unix timestamp.

Returns:

  • table: A table with the following fields:

    • year (number): The year.

    • month (number): The month (1-12).

    • day (number): The day of the month (1-31).

    • hour (number): The hour (0-23).

    • min (number): The minute (0-59).

    • sec (number): The second (0-59).

    • wday (number): The day of the week (0 = Sunday, 1 = Monday, ...).

    • yday (number): The day of the year (1-366).

    • isdst (boolean): true if Daylight Saving Time is in effect.

Example:

local now = time.unix()
local time_table = time.to_table(now)

engine.log("Time table components:", 255, 255, 255, 255)
engine.log("  Year: " .. time_table.year, 255, 255, 255, 255)
engine.log("  Month: " .. time_table.month, 255, 255, 255, 255)
engine.log("  Day: " .. time_table.day, 255, 255, 255, 255)
engine.log("  Hour: " .. time_table.hour, 255, 255, 255, 255)
engine.log("  Minute: " .. time_table.min, 255, 255, 255, 255)
engine.log("  Second: " .. time_table.sec, 255, 255, 255, 255)
engine.log("  Weekday: " .. time_table.wday, 255, 255, 255, 255)
engine.log("  Day of year: " .. time_table.yday, 255, 255, 255, 255)
engine.log("  DST active: " .. tostring(time_table.isdst), 255, 255, 255, 255)

time.from_table

Signature: time.from_table(table)

Description: Converts a local date-time table to a timestamp.

Parameters:

  • table (table): A table with date-time components (year, month, day, hour, min, sec).

Returns:

  • number: The corresponding Unix timestamp.

Example:

-- Create a time table manually
local date_time = {
    year = 2023,
    month = 12,
    day = 31,
    hour = 23,
    min = 59,
    sec = 59
}

local timestamp = time.from_table(date_time)
engine.log("New Year's Eve 2023 timestamp: " .. timestamp, 255, 255, 255, 255)
engine.log("Formatted: " .. time.format(timestamp), 255, 255, 255, 255)

-- Modify an existing time table
local now = time.unix()
local now_table = time.to_table(now)

-- Set to noon today
now_table.hour = 12
now_table.min = 0
now_table.sec = 0

local noon_timestamp = time.from_table(now_table)
engine.log("Today at noon: " .. time.format(noon_timestamp), 255, 255, 255, 255)

time.to_utc_table

Signature: time.to_utc_table(timestamp)

Description: Converts a timestamp to a UTC date-time table.

Parameters:

  • timestamp (number): The Unix timestamp.

Returns:

  • table: A table with UTC date-time components (year, month, day, etc.).

Example:

local now = time.unix()
local utc_table = time.to_utc_table(now)
local local_table = time.to_table(now)

engine.log("UTC time: " .. utc_table.hour .. ":" .. utc_table.min .. ":" .. utc_table.sec, 255, 255, 255, 255)
engine.log("Local time: " .. local_table.hour .. ":" .. local_table.min .. ":" .. local_table.sec, 255, 255, 255, 255)

time.from_utc_table

Signature: time.from_utc_table(table)

Description: Converts a UTC date-time table to a timestamp.

Parameters:

  • table (table): A table with UTC date-time components.

Returns:

  • number: The corresponding Unix timestamp.

Example:

-- Create a UTC time table
local utc_date_time = {
    year = 2023,
    month = 1,
    day = 1,
    hour = 0,
    min = 0,
    sec = 0
}

local timestamp = time.from_utc_table(utc_date_time)
engine.log("New Year 2023 UTC timestamp: " .. timestamp, 255, 255, 255, 255)
engine.log("Formatted in local time: " .. time.format(timestamp), 255, 255, 255, 255)

Validation and Info

time.is_valid

Signature: time.is_valid(timestamp)

Description: Checks if a timestamp is valid.

Parameters:

  • timestamp (number): The Unix timestamp to check.

Returns:

  • boolean: true if the timestamp is valid, false otherwise.

Example:

local valid_time = time.unix()
local invalid_time = -62167219200 -- Before Unix epoch minimum

if time.is_valid(valid_time) then
    engine.log("Current time is valid", 0, 255, 0, 255)
else
    engine.log("Current time is invalid", 255, 0, 0, 255)
end

if time.is_valid(invalid_time) then
    engine.log("Test time is valid", 0, 255, 0, 255)
else
    engine.log("Test time is invalid", 255, 0, 0, 255)
end

time.is_dst

Signature: time.is_dst(timestamp)

Description: Returns true if the timestamp is in Daylight Saving Time.

Parameters:

  • timestamp (number): The Unix timestamp.

Returns:

  • boolean: true if DST is in effect, false otherwise.

Example:

local now = time.unix()
if time.is_dst(now) then
    engine.log("Daylight Saving Time is currently in effect", 0, 255, 0, 255)
else
    engine.log("Standard Time is currently in effect", 255, 255, 255, 255)
end

-- Check DST for different times of year
local summer = time.timestamp_utc(2023, 7, 1, 12, 0, 0)
local winter = time.timestamp_utc(2023, 1, 1, 12, 0, 0)

engine.log("July 1: DST = " .. tostring(time.is_dst(summer)), 255, 255, 255, 255)
engine.log("January 1: DST = " .. tostring(time.is_dst(winter)), 255, 255, 255, 255)

time.utc_offset

Signature: time.utc_offset()

Description: Returns the local time offset from UTC in seconds.

Parameters: None

Returns:

  • number: The offset in seconds from UTC for the local time zone.

Example:

local offset_seconds = time.utc_offset()
local offset_hours = offset_seconds / 3600

engine.log("UTC offset: " .. offset_seconds .. " seconds", 255, 255, 255, 255)
engine.log("UTC offset: " .. offset_hours .. " hours", 255, 255, 255, 255)

time.get_timezone

Signature: time.get_timezone()

Description: Returns the time zone string (e.g., "UTC-03:00").

Parameters: None

Returns:

  • string: The time zone string.

Example:

local timezone = time.get_timezone()
engine.log("Current timezone: " .. timezone, 255, 255, 255, 255)

Utilities and Constants

time.seconds_to_hhmmss

Signature: time.seconds_to_hhmmss(seconds)

Description: Converts seconds to a formatted HH:MM:SS string.

Parameters:

  • seconds (number): The number of seconds.

Returns:

  • string: The formatted time string in HH:MM:SS format.

Example:

local seconds = 3661 -- 1 hour, 1 minute, 1 second
local formatted = time.seconds_to_hhmmss(seconds)
engine.log(seconds .. " seconds = " .. formatted, 255, 255, 255, 255)

-- Use in a countdown
local remaining = 7200 -- 2 hours
engine.log("Time remaining: " .. time.seconds_to_hhmmss(remaining), 255, 255, 255, 255)

Time Constants

The Time API provides several useful constants:

  • time.SECONDS_PER_MINUTE - 60

  • time.SECONDS_PER_HOUR - 3600

  • time.SECONDS_PER_DAY - 86400

  • time.DAYS_PER_WEEK - 7

  • time.WEEKDAY_NAMES - Table of weekday names (1 = Sunday, 7 = Saturday)

  • time.MONTH_NAMES - Table of month names (1 = January, 12 = December)

  • time.MONTH_DAYS - Days in each month (non-leap year)

  • time.MONTH_DAYS_LEAP - Days in each month (leap year)

  • time.MONTH_NAME_TO_INDEX - Maps month names to numeric indexes

Example:

-- Use time constants for calculations
local minutes = 42
local seconds = minutes * time.SECONDS_PER_MINUTE
engine.log(minutes .. " minutes = " .. seconds .. " seconds", 255, 255, 255, 255)

local now = time.unix()
local weekday_idx = time.weekday(now) + 1 -- Adjust from 0-based to 1-based
local month_idx = time.to_table(now).month

engine.log("Today is " .. time.WEEKDAY_NAMES[weekday_idx], 255, 255, 255, 255)
engine.log("Current month is " .. time.MONTH_NAMES[month_idx], 255, 255, 255, 255)

-- Convert month name to index
local month_name = "July"
local month_num = time.MONTH_NAME_TO_INDEX[month_name]
engine.log(month_name .. " is month #" .. month_num, 255, 255, 255, 255)
PreviousMathNextVector Types (vec2, vec3, vec4)

Last updated

Was this helpful?