Datetime
Goblin includes a full datetime system for creating, parsing, formatting, comparing, and doing math with dates and times.
Datetime values are real Goblin values, so they can be tethered, passed to actions, returned, compared, formatted, and converted.
Current Time
Use :now() when you want the current UTC datetime.
dt | :now() dt
dt | :now() dt
now returns a datetime value.
dt | :utc_now() dt
dt | :utc_now() dt
:utc_now() is the explicit UTC form.
dt | :local_now() dt
dt | :local_now() dt
:local_now() returns the current local datetime.
Epoch Time
Epoch time is useful when you need a plain integer timestamp.
ms | :epoch_ms() ms
ms | :epoch_ms() ms
Returns the current Unix epoch time in milliseconds.
s | :epoch_s() s
s | :epoch_s() s
Returns the current Unix epoch time in seconds.
Creating Datetime Values
Create a full datetime with year, month, day, hour, minute, and second:
dt | :datetime(2026, 6, 19, 14, 30, 0) dt
dt | :datetime(2026, 6, 19, 14, 30, 0) dt
Create a date-only value:
d | :date(2026, 6, 19) d
d | :date(2026, 6, 19) d
Create a time-only value:
t | :time(14, 30, 0) t
t | :time(14, 30, 0) t
ISO Parsing and Serialization
Convert a datetime to ISO text:
dt | :datetime(2026, 6, 19, 14, 30, 0) text | :to_iso(dt) text
dt | :datetime(2026, 6, 19, 14, 30, 0) text | :to_iso(dt) text
Parse ISO text back into a datetime:
dt | :from_iso("2026-06-19T14:30:00Z") dt
dt | :from_iso("2026-06-19T14:30:00Z") dt
Epoch Conversion
Convert a datetime to epoch milliseconds:
dt | :now() ms | :to_epoch_ms(dt) ms
dt | :now() ms | :to_epoch_ms(dt) ms
Create a datetime from epoch milliseconds:
dt | :from_epoch_ms(1781898600000) dt
dt | :from_epoch_ms(1781898600000) dt
Formatting
Use formatting helpers when you want display text.
dt | :datetime(2026, 6, 19, 14, 30, 0) :text | :format_datetime(dt, "%Y-%m-%d %H:%M:%S") text
dt | :datetime(2026, 6, 19, 14, 30, 0) :text | :format_datetime(dt, "%Y-%m-%d %H:%M:%S") text
Format only the date:
text | :format_date(dt, "%Y-%m-%d") text
text | :format_date(dt, "%Y-%m-%d") text
Format only the time:
text | :format_time(dt, "%H:%M:%S") text
text | :format_time(dt, "%H:%M:%S") text
Fields
Datetime fields can be extracted directly.
dt | :datetime(2026, 6, 19, 14, 30, 45) :year(dt) /// -> 2026 :month(dt) /// -> 6 :day(dt) /// -> 19 :hour(dt) /// -> 14 :minute(dt) /// -> 30 :second(dt) /// -> 45 :weekday(dt)
dt | :datetime(2026, 6, 19, 14, 30, 45) :year(dt) /// -> 2026 :month(dt) /// -> 6 :day(dt) /// -> 19 :hour(dt) /// -> 14 :minute(dt) /// -> 30 :second(dt) /// -> 45 :weekday(dt)
Datetime Math
Add a duration:
dt | :now() later | :add_duration(dt, 3d) later
dt | :now() later | :add_duration(dt, 3d) later
Durations use Goblin’s normal duration literals.
1s 5m 2h 3d 1w
1s 5m 2h 3d 1w
Get the time since a datetime:
started | :now() elapsed | :since(started) elapsed
started | :now() elapsed | :since(started) elapsed
Get the time until a datetime:
deadline | :add_duration(:now(), 7d) remaining | :until(deadline) remaining
deadline | :add_duration(:now(), 7d) remaining | :until(deadline) remaining
Comparisons
Datetime comparisons are native.
a | :datetime(2026, 6, 19, 10, 0, 0) b | :datetime(2026, 6, 19, 12, 0, 0) a < b /// -> true a <= b /// -> true a > b /// -> false a >= b /// -> false a == b /// -> false
a | :datetime(2026, 6, 19, 10, 0, 0) b | :datetime(2026, 6, 19, 12, 0, 0) a < b /// -> true a <= b /// -> true a > b /// -> false a >= b /// -> false a == b /// -> false
This means datetimes work naturally in if, judge, sorting logic, expiration checks, cooldowns, schedules, and simulations.
Timezones
Get the timezone attached to a datetime:
dt | :local_now() zone | :timezone(dt) zone
dt | :local_now() zone | :timezone(dt) zone
Convert a datetime to another timezone:
dt | :utc_now() denver | :to_timezone(dt, "America/Denver") tokyo | :to_timezone(dt, "Asia/Tokyo")
dt | :utc_now() denver | :to_timezone(dt, "America/Denver") tokyo | :to_timezone(dt, "Asia/Tokyo")
Timezone names use standard IANA timezone names.
Examples:
"America/Denver" "America/New_York" "Europe/London" "Asia/Tokyo" "UTC"
"America/Denver" "America/New_York" "Europe/London" "Asia/Tokyo" "UTC"
Convenience Dates
Use these helpers for common date values.
today | :today() today
today | :today() today
tomorrow | :tomorrow() tomorrow
tomorrow | :tomorrow() tomorrow
yesterday | :yesterday() yesterday
yesterday | :yesterday() yesterday
Common Patterns
Expiration Check
expires_at | :from_iso("2026-06-20T00:00:00Z") if :now() > expires_at => :say("expired")
expires_at | :from_iso("2026-06-20T00:00:00Z") if :now() > expires_at => :say("expired")
Cooldown Check
last_used | :from_iso("2026-06-19T10:00:00Z") ready_at | :add_duration(last_used, 5m) if :now() >= ready_at => :say("ready")
last_used | :from_iso("2026-06-19T10:00:00Z") ready_at | :add_duration(last_used, 5m) if :now() >= ready_at => :say("ready")
Display Date
dt | :now() label | :format_datetime(dt, "%Y-%m-%d %H:%M") label
dt | :now() label | :format_datetime(dt, "%Y-%m-%d %H:%M") label
Days Until Something
event | :datetime(2026, 7, 4, 0, 0, 0) left | :until(event) left
event | :datetime(2026, 7, 4, 0, 0, 0) left | :until(event) left
Function List
:now() :epoch_ms() :epoch_s() :datetime(y, mo, d, h, m, s) :date(y, mo, d) :time(h, m, s) :to_iso(dt) :from_iso(text) :to_epoch_ms(dt) :from_epoch_ms(ms) :format_datetime(dt, pattern) :format_date(dt, pattern) :format_time(dt, pattern) :year(dt) :month(dt) :day(dt) :hour(dt) :minute(dt) :second(dt) :weekday(dt) :add_duration(dt, duration) :since(dt) :until(dt) :utc_now() :local_now() :timezone(dt) :to_timezone(dt, "America/Denver") :today() :tomorrow() :yesterday()
:now() :epoch_ms() :epoch_s() :datetime(y, mo, d, h, m, s) :date(y, mo, d) :time(h, m, s) :to_iso(dt) :from_iso(text) :to_epoch_ms(dt) :from_epoch_ms(ms) :format_datetime(dt, pattern) :format_date(dt, pattern) :format_time(dt, pattern) :year(dt) :month(dt) :day(dt) :hour(dt) :minute(dt) :second(dt) :weekday(dt) :add_duration(dt, duration) :since(dt) :until(dt) :utc_now() :local_now() :timezone(dt) :to_timezone(dt, "America/Denver") :today() :tomorrow() :yesterday()
Notes
:now() and :utc_now() return UTC datetime values.
Use ISO strings when saving datetimes to files, logs, shards, or external systems.