Name
SetInterval -- install a new interval function (V2.0)
Synopsis
[id] = SetInterval(id, func, ms[, userdata])
Function
This function installs a new interval function and assigns the identifier id to it. If you pass Nil in id, SetInterval() will automatically choose a vacant identifier and return it. You need to specify a Hollywood function in the func argument and the time in milliseconds that defines the interval. The function you specified will then be called again and again and again at the intervals of the specified time. For example if you specify 40 as the interval, your function will be called every 40 milliseconds which corresponds to 25 times a second (25 * 40ms = 1000ms = 1 second). This is enough for most games, intros etc.

The function you specify in func will be called for the first time when the time specified in ms has elapsed. After that your function will be called repeatedly in intervals of ms milliseconds.

You always need to use WaitEvent() in connection with this function! If you have an interval function installed, the internal Hollywood timer scheduler will trigger interval events and inform WaitEvent() to call your interval function. Intervals do not work without WaitEvent()! If you do not use WaitEvent(), your interval function will never be called. Interval functions are only called as long as you are in a WaitEvent() loop.

This function is very important because it helps you to make sure that your script runs at the same speed on every system. See Script timing for more information on this issue and also for an example.

You can install as many intervals as you want. Hollywood's internal scheduler will make sure that all interval functions are called correctly.

Please remember that Hollywood does not support multithreading. Therefore your interval functions must not block the script - otherwise the whole script will be blocked. For example, if you have two interval functions installed and one of those functions executes a Wait(100), then the whole script will be blocked for 2 seconds.

You can use the ClearInterval() call to stop an interval function.

Starting with Hollywood 3.1 there is an optional argument called userdata. The value you specify here is passed to your callback function whenever it is called. This is useful if you want to avoid working with global variables. Using the userdata argument you can easily pass data to your callback function. You can specify a value of any type in userdata. Numbers, strings, tables, and even functions can be passed as user data.

Your interval function will be called by Hollywood with one parameter. The parameter is a message table which contains the following fields:

Action:
Will be always set to Interval. This field is a string.

ID:
Will be set to the identifier of the interval that Hollywood has just called.

UserData:
Will be set to what you have specified in the userdata argument when you installed the interval.

This message is useful if you want to handle two or more intervals in the same function. The message tells you then which interval Hollywood executed. If you do not need this message, simply disregard it. For example, the interval function of the code above does not regard the message either.

Last but not least: You should really have a look at the examples that came with Hollywood. Many of them use SetInterval() to manage the timing of the script!

Inputs
id
identifier for the new interval function or Nil for auto id selection; the identifier is needed so that you can stop the interval later using the ClearInterval() command
func
Hollywood function that should be called at the intervals of the specified time
ms
intervals at which the function shall be called, e.g. 40 will call the function 25 times a second because 25 * 40ms = 1000ms = 1 second
userdata
optional: user specific data to pass to callback function (V3.1)
Results
id
optional: identifier of the interval; will only be returned when you pass Nil as argument 1 (see above)
Example
See script timing


Show TOC