2.1. GDScript Code Example

Example 1: Basic Time System

extends Node
## Example 1: Basic Time System
##
## This example demonstrates:
## - Basic time unit registration (seconds, minutes, hours, days)
## - Time formatting and display
## - Pause/resume functionality
## - Time scale manipulation
## - Setting specific time values


var time_tick: TimeTick


func _ready() -> void:
	print("\nEXAMPLE 1: Basic Time System\n")
	
	# Create and initialize TimeTick
	time_tick = TimeTick.new()
	time_tick.initialize(0.1)  # Every 0.1 second, a new tick will be triggered.
	
	# Build standard time hierarchy
	# 1 tick = 1 second (virtual second, not real), wraps 0-59
	time_tick.register_time_unit("second", "tick", 1, 60, 0)
	# 60 seconds = 1 minute, wraps 0-59
	time_tick.register_time_unit("minute", "second", 60, 60, 0)
	# 60 minutes = 1 hour, wraps 0-23
	time_tick.register_time_unit("hour", "minute", 60, 24, 0)
	# 24 hours = 1 day, starts at day 1, no wrap
	time_tick.register_time_unit("day", "hour", 24, -1, 1)
	
	# Connect to signals
	time_tick.time_unit_changed.connect(_on_time_unit_changed)
	
	print("Standard time system initialized!")
	print("Time units: second, minute, hour, day")
	print("Time scale: 50x for demonstration\n")
	
	time_tick.set_time_scale(50.0)
	
	# Demonstrate setting specific time
	await get_tree().create_timer(2.0).timeout
	print("\n--- Setting time to 23:58:45 ---")
	time_tick.set_time_units({
		"hour": 23,
		"minute": 58,
		"second": 45
	})
	
	# Demonstrate pause/resume
	await get_tree().create_timer(4.0).timeout
	print("\n--- Pausing time")
	time_tick.pause()
	
	await get_tree().create_timer(2.0).timeout
	print("--- Resuming time")
	time_tick.resume()
	
	# Demonstrate time scale changes
	await get_tree().create_timer(3.0).timeout
	print("\n--- Increasing time scale to 200x")
	time_tick.set_time_scale(200.0)


func _on_time_unit_changed(unit_name: String, new_value: int, old_value: int) -> void:
	# Print formatted time every minute
	if unit_name == "minute":
		var formatted = time_tick.get_formatted_time_padded(["hour", "minute", "second"], ":")
		var day = time_tick.get_time_unit("day")
		print("[Day %d] %s" % [day, formatted])
	
	# Special message when day changes
	elif unit_name == "day":
		print("\n--- NEW DAY! Day %d → Day %d\n" % [old_value, new_value])


func _exit_tree() -> void:
	if time_tick:
		time_tick.shutdown()

Example 2: Advanced Time Units

extends Node
## Example 2: Advanced Time Units
##
## This example demonstrates:
## - Custom calendars with non-standard time units
## - Variable step amounts (accelerated time progression)
## - Multiple independent event timers
## - Unit counters and overflow tracking
## - Max value wrapping behavior


var time_tick: TimeTick


func _ready() -> void:
	print("\nEXAMPLE 2: Advanced Time Units\n")
	
	# Create and initialize TimeTick
	time_tick = TimeTick.new()
	time_tick.initialize(0.05)
	
	# 28-hour day, wraps 0-27
	time_tick.register_time_unit("hour", "tick", 1, 28, 0)
	# 10-day week (1-10), starts at day 1
	time_tick.register_time_unit("day", "hour", 28, 11, 1)
	# 4-week month (1-4), starts at week 1
	time_tick.register_time_unit("week", "day", 10, 5, 1)
	# 4-month year (1-4), starts at month 1
	time_tick.register_time_unit("month", "week", 4, 5, 1)
	# Starts at year 1000, no wrap
	time_tick.register_time_unit("year", "month", 4, -1, 1000)
	
	# Set starting year after registration
	time_tick.set_time_unit_starting_value("year", 1000)
	
	# Every 28 hours, no wrap
	time_tick.register_time_unit("harvest_timer", "hour", 28)
	# Every 15 days, no wrap
	time_tick.register_time_unit("market_day", "day", 15)
	# Every 28 days, no wrap
	time_tick.register_time_unit("moon_cycle", "day", 28)
	
	# Connect to signals
	time_tick.time_unit_changed.connect(_on_time_unit_changed)
	
	print("Custom Fantasy Calendar Initialized!")
	print("- 28 hours per day")
	print("- 10 days per week")
	print("- 4 weeks per month")
	print("- 12 months per year")
	print("\nSpecial Events:")
	print("- Harvest: Every 28 hours")
	print("- Market Day: Every 15 days")
	print("- Moon Cycle: Every 28 days\n")
	
	time_tick.set_time_scale(20.0)
	time_tick.pause()
	
	# Query available units
	await get_tree().create_timer(0.1).timeout
	var unit_names = time_tick.get_time_unit_names()
	print("\n--- Available Time Units")
	for unit_name in unit_names:
		var value = time_tick.get_time_unit(unit_name)
		print("  %s: %d" % [unit_name, value])
	
	await get_tree().create_timer(0.5).timeout
	time_tick.resume()


func _on_time_unit_changed(unit_name: String, new_value: int, old_value: int) -> void:
	match unit_name:
		"week":
			print("\n--- New Week! Week %d of Month %d\n" % [new_value, time_tick.get_time_unit("month")])
		
		"month":
			print("\n--- New Month! Month %d of Year %d\n" % [new_value, time_tick.get_time_unit("year")])
		
		"year":
			print("\n--- NEW YEAR! Year %d → Year %d\n" % [old_value, new_value])
		
		"harvest_timer":
			var hour = time_tick.get_time_unit("hour")
			var day = time_tick.get_time_unit("day")
			var week = time_tick.get_time_unit("week")
			var month = time_tick.get_time_unit("month")
			var year = time_tick.get_time_unit("year")
			print("--- Harvest Time! [Year %d, Month %d, Week %d, Day %d, Hour %d] (Harvest #%d)" % [year, month, week, day, hour, new_value])
		
		"market_day":
			var day = time_tick.get_time_unit("day")
			print("--- Market Day! (Day %d, Market #%d)" % [day, new_value])
		
		"moon_cycle":
			print("--- Full Moon Cycle Complete! (Cycle #%d)" % new_value)


func _exit_tree() -> void:
	if time_tick:
		time_tick.shutdown()

Example 3: Complex Time Units

extends Node
## Example 3: Complex Time Units
##
## This example demonstrates:
## - Complex time units (multiple conditions that must be met simultaneously)
## - Sidereal day (23h 56m 4s) vs Solar day (24h)
## - Specific time-based events (dawn, noon, dusk, midnight)
## - Lunar cycle tracking
## - Working with >= triggers (not exact matches)


var time_tick: TimeTick


func _ready() -> void:
	print("\nEXAMPLE 3: Complex Time Units\n")
	
	# Create and initialize TimeTick
	time_tick = TimeTick.new()
	time_tick.initialize(0.05)
	
	# Wraps 0-59
	time_tick.register_time_unit("second", "tick", 1, 60, 0)
	# 60 seconds = 1 minute, wraps 0-59
	time_tick.register_time_unit("minute", "second", 60, 60, 0)
	# 60 minutes = 1 hour, wraps 0-23
	time_tick.register_time_unit("hour", "minute", 60, 24, 0)
	
	# Fast seconds for demo
	time_tick.set_time_unit_step("second", 10)
	
	# No wrap
	time_tick.register_time_unit("solar_day", "hour", 24)
	
	# COMPLEX UNIT: Sidereal day (23h 56m 4s)
	# Triggers when hour >= 23 AND minute >= 56 AND second >= 4
	var sidereal_conditions = {
		"hour": 23,
		"minute": 56,
		"second": 4
	}
    # Search for sidereal day to understand what it is.
	time_tick.register_complex_time_unit("sidereal_day", sidereal_conditions)
	
	# COMPLEX UNITS: Time-of-day events
	var dawn_time = {"hour": 6, "minute": 0, "second": 0}
	var noon_time = {"hour": 12, "minute": 0, "second": 0}
	var dusk_time = {"hour": 18, "minute": 0, "second": 0}
	var midnight_time = {"hour": 0, "minute": 0, "second": 0}
	
	time_tick.register_complex_time_unit("dawn_event", dawn_time)
	time_tick.register_complex_time_unit("noon_event", noon_time)
	time_tick.register_complex_time_unit("dusk_event", dusk_time)
	time_tick.register_complex_time_unit("midnight_event", midnight_time)
	
	# COMPLEX UNIT: Lunar synodic month (29d 12h 44m 3s)
	# Note: This would require a 'day' unit to work properly
	# Wrap 0-29 for demo
	time_tick.register_time_unit("day", "hour", 24, 30, 0)
	var lunar_month_conditions = {
		"day": 29,
		"hour": 12,
		"minute": 44,
		"second": 3
	}
	time_tick.register_complex_time_unit("lunar_month", lunar_month_conditions)
	
	# Connect to signals
	time_tick.time_unit_changed.connect(_on_time_unit_changed)
	
	print("Complex Time Units Demonstration")
	print("\nStandard Units:")
	print("  - Solar Day: 24 hours")
	print("\nComplex Units:")
	print("  - Sidereal Day: Triggers at 23:56:04")
	print("  - Dawn: Triggers at 06:00:00")
	print("  - Noon: Triggers at 12:00:00")
	print("  - Dusk: Triggers at 18:00:00")
	print("  - Midnight: Triggers at 00:00:00")
	print("  - Lunar Month: Triggers at Day 29, 12:44:03")
	print("\nNote: Complex units trigger when ALL conditions are >= required values")
	print("      This means they work with any step amount!\n")
	
	time_tick.set_time_scale(500.0)
	
	# Start near a trigger point to demonstrate
	await get_tree().create_timer(1.0).timeout
	print("--- Jumping to 23:55:00 to watch sidereal day trigger\n")
	time_tick.set_time_units({
		"hour": 23,
		"minute": 55,
		"second": 0
	})


func _on_time_unit_changed(unit_name: String, new_value: int, old_value: int) -> void:
	var hour = time_tick.get_time_unit("hour")
	var minute = time_tick.get_time_unit("minute")
	var second = time_tick.get_time_unit("second")
	var day = time_tick.get_time_unit("day")
	
	match unit_name:
		"sidereal_day":
			var solar = time_tick.get_time_unit("solar_day")
			print("\n--- SIDEREAL DAY COMPLETE! (%02d:%02d:%02d)" % [hour, minute, second])
			print("   Sidereal: %d → %d" % [old_value, new_value])
			print("   Solar Days: %d (for comparison)" % solar)
			print("   → %d more sidereal day(s) than solar days\n" % (new_value - solar))
		
		"solar_day":
			var sidereal = time_tick.get_time_unit("sidereal_day")
			print("\n--- SOLAR DAY COMPLETE! (24:00:00)")
			print("   Solar: %d → %d" % [old_value, new_value])
			print("   Sidereal Days: %d (for comparison)" % sidereal)
			print("   → After 365 days, sidereal days will be 1 ahead!\n")
		
		"dawn_event":
			print("\n--- DAWN! (%02d:%02d:%02d)" % [hour, minute, second])
			print("   → The sun rises, day begins\n")
		
		"noon_event":
			print("\n--- NOON! (%02d:%02d:%02d)" % [hour, minute, second])
			print("   → The sun is at its peak\n")
		
		"dusk_event":
			print("\n--- DUSK! (%02d:%02d:%02d)" % [hour, minute, second])
			print("   → The sun sets, night begins\n")
		
		"midnight_event":
			print("\n--- MIDNIGHT! (%02d:%02d:%02d)" % [hour, minute, second])
			print("   → The witching hour, deepest night\n")
		
		"lunar_month":
			print("\n--- LUNAR MONTH COMPLETE! (Day %d at %02d:%02d:%02d)" % [day, hour, minute, second])
			print("   → Month: %d → %d" % [old_value, new_value])
			print("   → One synodic month (29d 12h 44m 3s) has passed\n")
		
		"minute":
			# Print current time every 10 minutes to show progression
			if minute % 10 == 0:
				var formatted = "%02d:%02d:%02d" % [hour, minute, second]
				var solar = time_tick.get_time_unit("solar_day")
				var sidereal = time_tick.get_time_unit("sidereal_day")
				print("[Day %d] %s | Solar: %d | Sidereal: %d" % [day, formatted, solar, sidereal])


func _exit_tree() -> void:
	if time_tick:
		time_tick.shutdown()