SHARE
TWEET

GMS Timers Docs

RedKnight91 Feb 27th, 2020 (edited) 187 Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
  1.     GMS2 Timers
  2.    
  3.     ----------------------------------------------------------------------------------------------------------------------------------
  4.     ----------------------------------------------------------------------------------------------------------------------------------
  5.     ----------------------------------------------------------------------------------------------------------------------------------
  6.    
  7.     Purpose:
  8.         To replace and extend Game Maker's built-in alarm system for greater readability, streamlined code and more possibilities
  9.    
  10.    
  11.     ----------------------------------------------------------------------------------------------------------------------------------
  12.     ----------------------------------------------------------------------------------------------------------------------------------
  13.     ----------------------------------------------------------------------------------------------------------------------------------
  14.    
  15.     Details:
  16.         Expands the basic 'alarm' concept to 'Timers', with three different possibilities:
  17.        
  18.         - Alarm: Just like GM's alarms, runs code after an interval)
  19.         - Interval: Repeatedly runs code after an interval)
  20.         - Cooldown: Restores a variable to true/false after an interval to indicate cooldown is over
  21.    
  22.         Alarms and intervals can be global or local:
  23.             Local timers will be executed in instance context (with(instance)) and destroyed when the instance is destroyed
  24.             Global timers will be executed in TimerManager context (with(TimerManager))
  25.            
  26.         Cooldowns can only be local (tied to an instance)
  27.    
  28.     ----------------------------------------------------------------------------------------------------------------------------------
  29.     ----------------------------------------------------------------------------------------------------------------------------------
  30.     ----------------------------------------------------------------------------------------------------------------------------------
  31.    
  32.     How it works:
  33.         - Alarms and intervals
  34.             Alarms and intervals require a callback script (and accept arguments for it).
  35.             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.
  36.    
  37.             Using extended creation scripts (setAlarmExt, setIntervalExt) you also get to be more specific on your timer setup.
  38.            
  39.         - Cooldowns:
  40.             Cooldowns are different in that you need to have created a variable to hold the boolean cooldown value (true or false).
  41.             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)
  42.        
  43.     ----------------------------------------------------------------------------------------------------------------------------------
  44.     ----------------------------------------------------------------------------------------------------------------------------------
  45.     ----------------------------------------------------------------------------------------------------------------------------------
  46.    
  47.     Usage Example:
  48.         //Your object's create code
  49.             setAlarm(60, "doThing")             //Creates a local alarm which calls script doThing in 60 frames
  50.             setInterval(60, "doThing")          //Creates a local interval
  51.             canDoThing = true                   //Needed for cooldown
  52.        
  53.         //Mouse click event
  54.             if (canDoThing) {
  55.                 doThing()
  56.                 setCooldown("canDoThing", 60, true)     //Sets canDoThing to false, restores it to true in 60 frames
  57.             }
  58.    
  59.     ----------------------------------------------------------------------------------------------------------------------------------
  60.     ----------------------------------------------------------------------------------------------------------------------------------
  61.     ----------------------------------------------------------------------------------------------------------------------------------
  62.    
  63.     NOTE:   Scripts which start with '__' (e.g. __createTimer()) are NOT meant to be used directly!
  64.             Only use the following scripts:
  65.    
  66.     Generic Timer scripts:
  67.         //Pause or resume all timers in the game (all alarms, intervals and cooldowns)
  68.         pauseTimers()          
  69.         resumeTimers()
  70.        
  71.         //Log all timers, or all timers tied to this instance
  72.         logTimers()
  73.         logTimersInstance()
  74.        
  75.     ----------------------------------------------------------------------------------------------------------------------------------
  76.    
  77.     Alarm scripts: 
  78.         //Creation (basic or extended)
  79.         setAlarm(duration, callback, arg1, arg2, ...)
  80.         setAlarmExt(alarmKey, global, duration, callback, arg1, arg2, ...)
  81.        
  82.         //The following scripts all take a 'global' parameter, based on whether you created the alarm as global or local.
  83.        
  84.         //Editing alarm variables
  85.         setAlarmDuration(alarmKey, global, duration)    //Note: This also restarts the alarm timer with new duration
  86.         setAlarmCallback(alarmKey, global, callback)
  87.         setAlarmArgs(alarmKey, global, arg1, arg2, ...)
  88.         setAlarmArgArray(alarmKey, global, argArray)
  89.        
  90.         //Pause or resume an alarm
  91.         pauseAlarm(alarmKey, global)
  92.         resumeAlarm(alarmKey, global)
  93.        
  94.         //Getting alarm frames left before execution
  95.         getAlarmTimer(alarmKey, global)
  96.        
  97.         //Checking if an alarm exists
  98.         alarmExists(alarmKey, global)
  99.        
  100.         //Deleting an alarm
  101.         clearAlarm(alarmKey, global)
  102.        
  103.         //Deleting all alarm
  104.         clearAlarms()
  105.        
  106.     ----------------------------------------------------------------------------------------------------------------------------------
  107.  
  108.     Interval scripts:
  109.         //Creation (basic or extended)
  110.         setInterval(duration, callback, arg1, arg2, ...)
  111.         setIntervalExt(intervalKey, global, duration, repetitions, callback, arg1, arg2, ...)
  112.        
  113.         //The following scripts all take a 'global' parameter, based on whether you created the interval as global or local.
  114.        
  115.         //Editing interval variables
  116.         setIntervalDuration(intervalKey, global, duration)  //Note: This also restarts the interval timer with new duration
  117.         setIntervalRepetitions(intervalKey, global, repetitions)
  118.         setIntervalCallback(intervalKey, global, callback)
  119.         setIntervalArgs(intervalKey, global, arg1, arg2, ...)
  120.         setIntervalArgArray(intervalKey, global, argArray)
  121.        
  122.         //Pause or resume an interval
  123.         pauseInterval(intervalKey, global)
  124.         resumeInterval(intervalKey, global)
  125.        
  126.         //Getting interval variables
  127.         getIntervalTimer(intervalKey, global)
  128.         getIntervalRepetitionsLeft(intervalKey, global)
  129.        
  130.         //Checking if an interval exists
  131.         intervalExists(intervalKey, global)
  132.        
  133.         //Deleting an interval
  134.         clearInterval(intervalKey, global)
  135.        
  136.         //Deleting all intervals
  137.         clearIntervals()
  138.        
  139.     ----------------------------------------------------------------------------------------------------------------------------------
  140.    
  141.     Cooldown scripts:
  142.         //NOTE: All cooldown scripts are executed in the current context, so if wish to set/edit a cooldown for another instance, use with(instance)
  143.    
  144.         //Creation (basic or extended)
  145.         setCooldown(variableName, duration, cooledBoolValue)
  146.        
  147.         //Editing cooldown variables
  148.         setCooldownDuration(variableName, duration) //Note: This also restarts the cooldown timer with new duration
  149.        
  150.         //Pause or resume a cooldown
  151.         pauseCooldown(variableName)
  152.         resumeCooldown(variableName)
  153.        
  154.         //Getting cooldown variables
  155.         getCooldownTimer(variableName)
  156.         getCooldownValue(variableName)
  157.        
  158.         //Checking if a cooldown exists
  159.         cooldownExists(variableName)
  160.        
  161.         //Deleting a cooldown
  162.         clearCooldown(variableName)    
  163.        
  164.         //Deleting all cooldowns
  165.         clearCooldowns()           
  166.        
  167.     ----------------------------------------------------------------------------------------------------------------------------------
  168.     ----------------------------------------------------------------------------------------------------------------------------------
  169.     ----------------------------------------------------------------------------------------------------------------------------------
  170.    
  171.     Parameters:
  172.    
  173.         setAlarm
  174.             duration    Frames before the callback is executed
  175.             callback    A script to run when the timer goes off
  176.             args        Arguments to pass to callback script
  177.            
  178.         setAlarmExt
  179.             alarmKey    Key with which the timer is stored, allowing you to easily access it later
  180.                         (If no key passed, will be randomly generated and returned)
  181.             global      Whether the timer is bound to an instance or not (if it is, it will be destroyed when the instance is)
  182.            
  183.         setInterval
  184.             duration    Frames before the callback is executed
  185.             callback    A script to run when the timer goes off
  186.             args        Arguments to pass to callback script
  187.            
  188.         setIntervalExt
  189.             intervalKey Key with which the timer is stored, allowing you to easily access it later
  190.                         (If no key passed, will be randomly generated and returned)
  191.             global      Whether the timer is bound to an instance or not (if it is, it will be destroyed when the instance is)
  192.             repetitions Number of times the interval will repeat (-1 is infinite)
  193.            
  194.         setCooldown
  195.             variableName    [String] Name of the variable which stores the cooldown boolean
  196.             duration        Frames before the cooldown is executed
  197.             cooledValue     [Boolean] value the variable gets set to AFTER cooldown
  198.                             NOTE: The variable gets set to the opposite of this value automatically when cooldown starts
  199.        
  200.         setCooldownExt
  201.             instance    ID of the instance the cooldown is bound to
  202.            
  203.        
  204.                
  205.     ----------------------------------------------------------------------------------------------------------------------------------
  206.     ----------------------------------------------------------------------------------------------------------------------------------
  207.     ----------------------------------------------------------------------------------------------------------------------------------
  208.        
  209.        
  210.     Important info:
  211.         - All timers are periodically garbage collected, so if instance with timers bound to it is destroyed, those timers are deleted.
  212.        
  213.         - Callbacks are performed within creator instance scope ( with(instance) )
  214.  
  215.         - Callbacks are passed as script name string (e.g. setAlarm(60, "doThing"), NOT setAlarm(60, doThing))
  216.        
  217.         - Callbacks arguments are passed as a regular list of arguments for example:
  218.             setAlarm(60, sayThing, "Hello ", "world")
  219.            
  220.             //Callback script
  221.             var word1 = argument0
  222.             var word2 = argument1
  223.             show_debug_message(word1 + word2) //Prints "Hello world"
  224.            
  225.         - Scripts which start with '__' (e.g. __createTimer()) are NOT meant to be used directly!
  226.        
  227.         IMPORTANT: Ensure the callback script receives the correct number of arguments, either:
  228.             - Using variable arguments (e.g. argument[0], argument[1])
  229.             - Using the correct number of arguments as passed by setAlarm, setInterval...
  230.         Any other behavior will result in a crash
  231.    
  232.     ----------------------------------------------------------------------------------------------------------------------------------
  233.     ----------------------------------------------------------------------------------------------------------------------------------
  234.     ----------------------------------------------------------------------------------------------------------------------------------
  235.    
  236.     Updates:
  237.         - Restructured the way global/local Timers are handled
  238.         - Fixed bugs
  239.         - Added logging variables to TimerManager (verbose timer setting, verbose timer clearing)
  240.         - Added more utility scripts (alarmExists, intervalExists, ...)
  241.         - Changed callback parameter to raw script to string because of the way GM handles script indices for extensions
  242.         - Fixed scope in backend scripts (they now all run in with(TimerManager))
  243.        
  244.     ----------------------------------------------------------------------------------------------------------------------------------
  245.    
  246.     Future updates (pending stable Game Maker 2.3 update):
  247.         - Asset available as Extension
  248.         - Possibility to use anonymous function callbacks instead of scripts
  249.        
  250.     ----------------------------------------------------------------------------------------------------------------------------------
  251.     ----------------------------------------------------------------------------------------------------------------------------------
  252.     ----------------------------------------------------------------------------------------------------------------------------------
  253.    
  254.     Contacts:
  255.         mikecazzarolli@gmail.com
  256.         twitter.com/mikecazzarolli
RAW Paste Data
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy. OK, I Understand
Top