GMS Timers Docs

	GMS2 Timers

	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------

	Purpose:
		To replace and extend Game Maker's built-in alarm system for greater readability, streamlined code and more possibilities


	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------

	Details:
		Expands the basic 'alarm' concept to 'Timers', with three different possibilities:

		- Alarm: Just like GM's alarms, runs code after an interval)
		- Interval: Repeatedly runs code after an interval)
		- Cooldown: Restores a variable to true/false after an interval to indicate cooldown is over

		Alarms and intervals can be global or local:
			Local timers will be executed in instance context (with(instance)) and destroyed when the instance is destroyed
			Global timers will be executed in TimerManager context (with(TimerManager))

		Cooldowns can only be local (tied to an instance)

	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------

	How it works:
		- Alarms and intervals
			Alarms and intervals require a callback script (and accept arguments for it).
			Using setAlarm(...) will setup an alarm and return a key for that alarm, which should be kept if further manipulation of the alarm is needed.

			Using extended creation scripts (setAlarmExt, setIntervalExt) you also get to be more specific on your timer setup.

		- Cooldowns:
			Cooldowns are different in that you need to have created a variable to hold the boolean cooldown value (true or false).
			Using setCooldown(...) you'll set that variable to its cooldown value (e.g. false) and also set a timer to restore that variable to its cooled down value (e.g. true)

	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------

	Usage Example:
		//Your object's create code
			setAlarm(60, "doThing")				//Creates a local alarm which calls script doThing in 60 frames
			setInterval(60, "doThing")			//Creates a local interval
			canDoThing = true					//Needed for cooldown

		//Mouse click event
			if (canDoThing) {
				doThing()
				setCooldown("canDoThing", 60, true)		//Sets canDoThing to false, restores it to true in 60 frames
			}

	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------

	NOTE:	Scripts which start with '__' (e.g. __createTimer()) are NOT meant to be used directly!
			Only use the following scripts:

	Generic Timer scripts:
		//Pause or resume all timers in the game (all alarms, intervals and cooldowns)
		pauseTimers()
		resumeTimers()

		//Log all timers, or all timers tied to this instance
		logTimers()
		logTimersInstance()

	----------------------------------------------------------------------------------------------------------------------------------

	Alarm scripts:
		//Creation (basic or extended)
		setAlarm(duration, callback, arg1, arg2, ...)
		setAlarmExt(alarmKey, global, duration, callback, arg1, arg2, ...)

		//The following scripts all take a 'global' parameter, based on whether you created the alarm as global or local.

		//Editing alarm variables
		setAlarmDuration(alarmKey, global, duration)	//Note: This also restarts the alarm timer with new duration
		setAlarmCallback(alarmKey, global, callback)
		setAlarmArgs(alarmKey, global, arg1, arg2, ...)
		setAlarmArgArray(alarmKey, global, argArray)

		//Pause or resume an alarm
		pauseAlarm(alarmKey, global)
		resumeAlarm(alarmKey, global)

		//Getting alarm frames left before execution
		getAlarmTimer(alarmKey, global)

		//Checking if an alarm exists
		alarmExists(alarmKey, global)

		//Deleting an alarm
		clearAlarm(alarmKey, global)

		//Deleting all alarm
		clearAlarms()

	----------------------------------------------------------------------------------------------------------------------------------

	Interval scripts:
		//Creation (basic or extended)
		setInterval(duration, callback, arg1, arg2, ...)
		setIntervalExt(intervalKey, global, duration, repetitions, callback, arg1, arg2, ...)

		//The following scripts all take a 'global' parameter, based on whether you created the interval as global or local.

		//Editing interval variables
		setIntervalDuration(intervalKey, global, duration)	//Note: This also restarts the interval timer with new duration
		setIntervalRepetitions(intervalKey, global, repetitions)
		setIntervalCallback(intervalKey, global, callback)
		setIntervalArgs(intervalKey, global, arg1, arg2, ...)
		setIntervalArgArray(intervalKey, global, argArray)

		//Pause or resume an interval
		pauseInterval(intervalKey, global)
		resumeInterval(intervalKey, global)

		//Getting interval variables
		getIntervalTimer(intervalKey, global)
		getIntervalRepetitionsLeft(intervalKey, global)

		//Checking if an interval exists
		intervalExists(intervalKey, global)

		//Deleting an interval
		clearInterval(intervalKey, global)

		//Deleting all intervals
		clearIntervals()

	----------------------------------------------------------------------------------------------------------------------------------

	Cooldown scripts:
		//NOTE: All cooldown scripts are executed in the current context, so if wish to set/edit a cooldown for another instance, use with(instance)

		//Creation (basic or extended)
		setCooldown(variableName, duration, cooledBoolValue)

		//Editing cooldown variables
		setCooldownDuration(variableName, duration)	//Note: This also restarts the cooldown timer with new duration

		//Pause or resume a cooldown
		pauseCooldown(variableName)
		resumeCooldown(variableName)

		//Getting cooldown variables
		getCooldownTimer(variableName)
		getCooldownValue(variableName)

		//Checking if a cooldown exists
		cooldownExists(variableName)

		//Deleting a cooldown
		clearCooldown(variableName)

		//Deleting all cooldowns
		clearCooldowns()

	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------

	Parameters:

		setAlarm
			duration	Frames before the callback is executed
			callback	A script to run when the timer goes off
			args		Arguments to pass to callback script

		setAlarmExt
			alarmKey	Key with which the timer is stored, allowing you to easily access it later
						(If no key passed, will be randomly generated and returned)
			global		Whether the timer is bound to an instance or not (if it is, it will be destroyed when the instance is)

		setInterval
			duration	Frames before the callback is executed
			callback	A script to run when the timer goes off
			args		Arguments to pass to callback script

		setIntervalExt
			intervalKey	Key with which the timer is stored, allowing you to easily access it later
						(If no key passed, will be randomly generated and returned)
			global		Whether the timer is bound to an instance or not (if it is, it will be destroyed when the instance is)
			repetitions	Number of times the interval will repeat (-1 is infinite)

		setCooldown
			variableName	[String] Name of the variable which stores the cooldown boolean
			duration		Frames before the cooldown is executed
			cooledValue		[Boolean] value the variable gets set to AFTER cooldown
							NOTE: The variable gets set to the opposite of this value automatically when cooldown starts

		setCooldownExt
			instance	ID of the instance the cooldown is bound to



	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------


	Important info:
		- All timers are periodically garbage collected, so if instance with timers bound to it is destroyed, those timers are deleted.

		- Callbacks are performed within creator instance scope ( with(instance) )

		- Callbacks are passed as script name string (e.g. setAlarm(60, "doThing"), NOT setAlarm(60, doThing))

		- Callbacks arguments are passed as a regular list of arguments for example:
			setAlarm(60, sayThing, "Hello ", "world")

			//Callback script
			var word1 = argument0
			var word2 = argument1
			show_debug_message(word1 + word2) //Prints "Hello world"

		- Scripts which start with '__' (e.g. __createTimer()) are NOT meant to be used directly!

		IMPORTANT: Ensure the callback script receives the correct number of arguments, either:
			- Using variable arguments (e.g. argument[0], argument[1])
			- Using the correct number of arguments as passed by setAlarm, setInterval...
		Any other behavior will result in a crash

	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------

	Updates:
		- Restructured the way global/local Timers are handled
		- Fixed bugs
		- Added logging variables to TimerManager (verbose timer setting, verbose timer clearing)
		- Added more utility scripts (alarmExists, intervalExists, ...)
		- Changed callback parameter to raw script to string because of the way GM handles script indices for extensions
		- Fixed scope in backend scripts (they now all run in with(TimerManager))

	----------------------------------------------------------------------------------------------------------------------------------

	Future updates (pending stable Game Maker 2.3 update):
		- Asset available as Extension
		- Possibility to use anonymous function callbacks instead of scripts

	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------
	----------------------------------------------------------------------------------------------------------------------------------

	Contacts:
		mikecazzarolli@gmail.com
		twitter.com/mikecazzarolli