VSLib Developer Guide - Timers

8.5K
0

Sharing is temporarily disabled

Left 4 Dead 2 Guide

November 2015

Timers, as you may have seen in the Your First VSLib Mutation tutorial, can be very useful for a number of things. Anywhere a delay may be necessary, timers usually play some kind of role. VSLib uses timers throughout its own code. For the developer (that's you), here's a quick, comprehensive overview of all the VSLib.Timers features.

Creating a Timer Basics

Creating a timer is simple. Here's the function prototype:


VSLib::Timers::AddTimer ( float delayInSeconds, bool repeatTimer, function functionToFire, argumentsToPass = null, unsigned int flags = 0 )


If you wanted a timer to fire a function called "noob" after 0.5 seconds, you would do the following:

function noob ( args )
{
....
}
Timers.AddTimer ( 0.5, false, noob );

Above, we created a timer that will call the noob function about 0.5 seconds from now. We set the second parameter (repeatTimer) to false, so it will only fire once. Had we set the second param to true, noob would fire every 0.5 seconds until the end of the round.

Note that every function that the timer will call must have exactly 1 parameter (that can be called anything; above, it was called args).

Stopping a Repeating Timer

Stopping From Inside The Function

What if you had a repeating timer, and you wanted to stop it? Simply return false from your function. Going back to the noob function:

function noob ( args )
{
....
// Just return false to stop the timer!
if (blah blah blah)
return false;
}
Timers.AddTimer ( 0.5, true, noob );

Stopping From Outside The Function

There is also another way that you can stop a timer. Timers.AddTimer will return the timer index (an integer) that you can use to stop the timer later. You can even remove single-fire and repeated timers before they even fire if needed.

function noob ( args )
{
....
}
::timerIndex <- Timers.AddTimer ( 0.5, true, noob );
// Just do this from somewhere to stop the timer.
Timers.RemoveTimer ( timerIndex );

Passing Arguments To Your Function

Passing Single Arguments

You can pass any argument of any type to your function. Let's say you wanted to pass an entity to your function.

// This function will break the specified entity
function BreakEntity ( entity )
{
entity.Break();
}
// Here's an entity with a targetname
Entity door ( "my_door_entity" );
// Break the door after 15 seconds
Timers.AddTimer ( 15, false, BreakEntity, door );

The code above will break an entity after the specified delay.


Passing Multiple Arguments

If you wanted to pass more than one parameter, you need to put them all into a table. Here's an example.

// Here are some different arguments:
Player somePlayer ( 1 ); // Some class
local someVar = 20; // Some integer
local anotherVar = "stuff"; // Some string
// All those different arguments can be put into a single table
local myTable = { player = somePlayer, var = someVar, var2 = anotherVar };
// This func will do stuff using the table
function DoStuff ( stuff )
{
// Set player's health to 20
stuff.player.SetHealth( stuff.var );
Utils.SayToAll ( "Set player %s health to %i", stuff.player.GetName(), stuff.var );
}
// Pass da argumentz
Timers.AddTimer ( 15, false, DoStuff, myTable );

Not bad! Basically, stick everything you need to pass into a single table and pass it.

Advanced Timer Flags

VSLib supports timer flags. Flags allow you to designate special timer properties. Currently, VSLib only has one timer property called TIMER_FLAG_KEEPALIVE, which will prevent the timer from being auto-cleared by the cache system. In most cases, one does not need to worry about timer flags; however, if the developer needs to expand the timer system with new features, the flag system base has been already created for you.