SetTimer: Difference between revisions

From Multi Theft Auto: Wiki
Jump to navigation Jump to search
(Added a note about how clients can mess with timer speed)
(30 intermediate revisions by 19 users not shown)
Line 1: Line 1:
__NOTOC__  
__NOTOC__
This function allows you to trigger a function after a number of milliseconds have ellapsed. You can call either your own functions, or built in functions. For example, you could set a timer to spawn a player after a number of seconds had ellapsed.
{{Server client function}}
This function allows you to trigger a function after a number of milliseconds have elapsed. You can call one of your own functions or a built-in function. For example, you could set a timer to spawn a player after a number of seconds have elapsed.


Once a timer has finished repeating, it no longer exists.
Once a timer has finished repeating, it no longer exists.


==Syntax==  
'''The minimum accepted interval is 50ms.'''
 
'''Note: The speed at which a client side timer runs can be completely unreliable if a client is maliciously modifying their operating system speed, timers could run much faster or slower.'''
 
Multi Theft Auto guarantees that the timer will be triggered after ''at least'' the interval you specify. The resolution of the timer is tied to the frame rate (server side and client-side). All the overdue timers are triggered at a single point each frame. This means that if, for example, the player is running at 30 frames per second, then two timers specified to occur after 100ms and 110ms would more than likely occur during the same frame, as the difference in time between the two timers (10ms) is less than half the length of the frame (33ms). As with most timers provided by other languages, you shouldn't rely on the timer triggering at an exact point in the future.
 
==Syntax==
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
timerID setTimer ( string functionName, int time, int repeats, [var argument1, ...] )
timer setTimer ( function theFunction, int timeInterval, int timesToExecute, [ var arguments... ] )
</syntaxhighlight>  
</syntaxhighlight>  
 
{{OOP||[[Timer]]}}
===Required Arguments===  
===Required Arguments===  
*'''functionName:''' The name of the function you wish the timer to call.
*'''theFunction:''' The function you wish the timer to call.
*'''time:''' The number of milliseconds that should ellapse before the function is called. 1000 milliseconds = 1 second.
{{Note|The hidden global variable '''sourceTimer''' contains the currently executing timer userdata}}
*'''repeats:''' The number of times you want the timer to execute. 0 = infinite.
*'''timeInterval:''' The number of milliseconds that should elapse before the function is called. (the minimum is 50; 1000 milliseconds = 1 second)
*'''timesToExecute:''' The number of times you want the timer to execute, or 0 for infinite repetitions.


===Optional Arguments===  
===Optional Arguments===  
{{OptionalArg}}  
{{OptionalArg}}  
*'''argument1:''' Any arguments you wish to pass to the function can be listed after the ''repeats'' variable.
*'''arguments:''' Any arguments you wish to pass to the function can be listed after the ''timesToExecute'' argument. Note that any tables you want to pass will get cloned, whereas metatables and functions/function references in that passed table will get lost. Also changes you make in the original table before the function gets called won't get transferred.


===Returns===
===Returns===
Returns ''timerID'' if the timer was set succesfully, ''false'' if the arguments are invalid or the timer could not be set.
Returns a [[timer]] pointer if the timer was set successfully, ''false'' if the arguments are invalid or the timer could not be set.


==Example==  
==Examples==
This example will output some text after a number of seconds.
This example will output some text after a small delay.


First we define a function that we wish to be called.
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
-- define function to be called
function delayedChat ( text )
function delayedChat ( text )
outputChatBox ( "Delayed text: " .. text )
outputChatBox ( "Delayed text: " .. text )
end
end
-- set a timer so the function is called after 1 second
setTimer ( delayedChat, 1000, 1, "Hello, World!" )
</syntaxhighlight>
</syntaxhighlight>


Then we can set a timer that will call it in 1 second (1000 milliseconds) time.
1 second after the line above has been executed, the text ''Delayed text: Hello, World!'' will be displayed in the chat box.
 
This example will nest a whole function within a timer. This is nice for things like setting variables without having to call a function outside of your code block.
 
<syntaxhighlight lang="lua">
<syntaxhighlight lang="lua">
setTimer ( "delayedChat", 1000, 1, "Hello, World!" )
function mainFunction()
        outputChatBox ("Instant text!")
setTimer ( function()
outputChatBox ( "5 second delay text!" )
end, 5000, 1 )
end
 
mainFunction() --call function
</syntaxhighlight>
 
This example outputs some random text to the chat every 300000 milliseconds (5 minutes).
<syntaxhighlight lang="lua">
setTimer(function()
    outputChatBox("Text " .. math.random(1,4))
end, 300000, 0)
</syntaxhighlight>
</syntaxhighlight>
1 second after the line above has been executed, the text ''Delayed text: Hello, World!'' will be displayed in the chat box.


==See Also==
==See Also==
{{Utility functions}}
{{Utility functions}}
[[Category:Needs_Checking]]

Revision as of 21:21, 5 July 2018

This function allows you to trigger a function after a number of milliseconds have elapsed. You can call one of your own functions or a built-in function. For example, you could set a timer to spawn a player after a number of seconds have elapsed.

Once a timer has finished repeating, it no longer exists.

The minimum accepted interval is 50ms.

Note: The speed at which a client side timer runs can be completely unreliable if a client is maliciously modifying their operating system speed, timers could run much faster or slower.

Multi Theft Auto guarantees that the timer will be triggered after at least the interval you specify. The resolution of the timer is tied to the frame rate (server side and client-side). All the overdue timers are triggered at a single point each frame. This means that if, for example, the player is running at 30 frames per second, then two timers specified to occur after 100ms and 110ms would more than likely occur during the same frame, as the difference in time between the two timers (10ms) is less than half the length of the frame (33ms). As with most timers provided by other languages, you shouldn't rely on the timer triggering at an exact point in the future.

Syntax

timer setTimer ( function theFunction, int timeInterval, int timesToExecute, [ var arguments... ] )

OOP Syntax Help! I don't understand this!

Method: Timer(...)


Required Arguments

  • theFunction: The function you wish the timer to call.
[[{{{image}}}|link=|]] Note: The hidden global variable sourceTimer contains the currently executing timer userdata
  • timeInterval: The number of milliseconds that should elapse before the function is called. (the minimum is 50; 1000 milliseconds = 1 second)
  • timesToExecute: The number of times you want the timer to execute, or 0 for infinite repetitions.

Optional Arguments

NOTE: When using optional arguments, you might need to supply all arguments before the one you wish to use. For more information on optional arguments, see optional arguments.

  • arguments: Any arguments you wish to pass to the function can be listed after the timesToExecute argument. Note that any tables you want to pass will get cloned, whereas metatables and functions/function references in that passed table will get lost. Also changes you make in the original table before the function gets called won't get transferred.

Returns

Returns a timer pointer if the timer was set successfully, false if the arguments are invalid or the timer could not be set.

Examples

This example will output some text after a small delay.

-- define function to be called
function delayedChat ( text )
	outputChatBox ( "Delayed text: " .. text )
end

-- set a timer so the function is called after 1 second
setTimer ( delayedChat, 1000, 1, "Hello, World!" )

1 second after the line above has been executed, the text Delayed text: Hello, World! will be displayed in the chat box.

This example will nest a whole function within a timer. This is nice for things like setting variables without having to call a function outside of your code block.

function mainFunction()
        outputChatBox ("Instant text!")
	setTimer ( function()
		outputChatBox ( "5 second delay text!" )
	end, 5000, 1 )
end

mainFunction() --call function

This example outputs some random text to the chat every 300000 milliseconds (5 minutes).

setTimer(function()
    outputChatBox("Text " .. math.random(1,4))
end, 300000, 0)

See Also