Light Sequences
Event | Detail | Example |
|---|---|---|
_init | | |
_Timer | | |
_PlayDone | | |
Visual Pinball contains a device called the 'Light Sequencer' (or LS for short). What this basically does is take a Visual Pinball collection of lights and runs a effect though the lights (in the collection) that you would see on a commercial pinball game. The effects the Light Sequencer has are full table effects, i.e.. It doesn't allow you to cycle though lights but it does do the more complex effects which make a pinball look good without coding hundreds if not thousands of script lines.
The Light Sequencer when running takes control of the lights you specify for it to use. It does this by overlaying the effect over the lights without affecting the true state of the light. As many scripts use lights for game conditionals (i.e.. If light = on then award bonus and turn light off) the Light Sequencer ensures that your script does not need to worry about whether or not the Sequencer is currently running. It is totally transparent to your table. Changing the value of a light while a sequence is running will not actually turn a light on or off (or even to blinking), but it will remember what the current state is so when the sequence is finished, the lights will be restored to the last set state.
Multiple Light Sequencer's can be placed on the table allowing for different sections of the table to have its own effects if needed (such as split playfield's) or effects which have use a different centre point (more of this in a bit). Each Light Sequencer can have it's own collection so you can use different Sequencer's to control different parts of the table. A light can also exist in multiple collections so there is no limitations about which lights can be where.
| On the left hand tool palette, you will find a icon which looks like this. Click on it and place the element onto the table as you would do with any of the other types of table objects. When you place it onto the table, it will generate 2 icons which look like this. |
|---|
| |
|---|
If you click onto the main table element for the Light Sequencer. It will bring up the options. The light Sequencer is primary script driven so there isn't too many options to worry about in the editor Name : The objects name which is used to address the object though the script. POSITION Table X and Y Centre: The centre refernece point which the Light Sequencer uses to base all it's effects from. STATE Collection : The collection of lights / bumpers to use. (More of this in a minute). A Light Sequencer can only use a single collection and it cannot be changed during game play. If you want to use more than one collection, use multiple Light Sequencer's. Update Interval : The speed that the Light Sequencer Runs at. It is best to define this in the script as it is definable per effect. If you want all effects to run at a set speed then this is the place to do it. MISC Timer Interval : If enabled will call LightSeqName_Timer() in the script every n (interval) milliseconds. User Value : Holds any value put into it. It is not used by the Light Sequencer. | |
|---|
As mentioned above the Light Sequencer uses a collection to store the details about which lights (and bumpers) to use. If you havn't not used 'Collections' before, don't worry. The Light Sequencer only uses it as a list of lights and you don't need to know how to use them at a script level.
Open up the collection manager and click on new.. Type in the name for which to want to call the collection.
Click on 'Edit' which will bring up the following screen. In this screen select all the Lights and Bumpers that you want Light Sequencer to control when it performs an effect.
You don't need to select either 'Fire Events' or 'Suppress Events' and I recommend that you don't as if you are using Bumpers in a collection then you could accidentally turn off the hit event for them.
Things to be Careful of!
The Light Sequencer will work with any Light/Bumper placed onto the table (or the backglass) and will handle any width of table but it will NOT process lights which are placed off the table (in the table view in the editor).
The LS works by subdividing the table into 20x20 unit cells (on a default table of 1000 x 2000 units this gives 5000 cells). Only 1 light is handled per cell so if a single cell contains 2 lights then only one of them will be processed. In order to test the positioning of the lights on your table you can set the editor grid to 20 units. I checked a lot of tables and couldn't find any tables which had lights that close to each other. If you do have lights very close to each other you can always use 2 Light Sequencer's with each light in a different collection. | |
|---|
| Visual Pinball now has some editor tweaking options which you can set. One of the these options is the ability to place a small cross hair or cross in the centre of Lights and Bumpers. The cross hair is only shown for circular lights as custom definable lights already have a cross hair(or cross) which acts as the centre of the light (where the light comes from). |
|---|
By turning on the Light Centre and the layout grid (set to 20) you can check each light and ensure that there is no more than one 'cross hair' in each cell of the grid.. For example..
A standard Circular Light and Bumper. You can see exactly which grid cell it is in. | The custom shaped lights from my BK2K table (Knights Helmet). As you can see each cross hair has its own grid cell and doesn't share with another light. |
|---|
| The Light Sequencer has a centre reference point which is marked by the smaller LS icon with the cross hair in it. By centre reference I mean the point on the table which the LS uses as the centre point to base all effects on. For example the circle out effect will start at this point and circle out. Each LS can have it's own centre point to allow for different parts of the playfield to be highlighted during an effect. For example. BK2K will have some effects which use the very centre of the table as a starting point whilst other effects use the knights helmet as the start point. |
|---|
The Light Sequencer basically only follows fixed pattern effects which it has been programmed with (over 50 different effects) but each one can be tweaked slightly by specifying how fast it runs, any pauses between effects and repeating the effect.
These effects are processed as 'Head' effects. The 'Head' effect is the main effect.. For example if you are turning all the lights on from the bottom of the playfield and moving upwards. The point at which the light turns on is where the 'head' of the effect is. The head will change from frame to frame as it moves up the playfield.
Each 'Head' effect can have a 'Tail' effect which follows the 'Head' effect and inverts the state to which the 'Head' sets a light.. For example. If as above you are turning on lights moving up, then the 'Tail' will turn them off. If the 'Head' turns them off, the 'Tail' will turn them on.
The Distance at which the 'Tail' follows the 'Head' is completely upto you or you may decide not to have a tail. The 'Tail' will always run at the same speed as the 'Head' and the effect and not classified as finished until both the 'Head'' & ''Tail' have both finished.
The actual Light Sequencer is very simple to use once the collection has been set up. It only has 2 script methods '.Play' and'.StopPlay', a Property ('.UpdateInterval') and one Event ('.PlayDone') to let you know when the Sequencer has finished.
When you issue a play command. It basically puts it into a Queue. Thus you can load up the Sequencer with a heap of effects and it will process all of them. When the queue is empty it will let you know (by the '.PlayDone' Event) so you can either 'refill' the Sequencer or perform any other action your table requires. The size of the queue is 100 effects.
[Tounge Twisting Mode On] When you issue a Play command to the Light Sequencer, it puts each light in it's collection into a special state where it will remember its current lit state (either on, off or blinking) but won't actually change state if you actively change it in the script (hope that makes sense ;-). At this point only the Light Sequencer can physically change the state of the light but any changes made by you to the light in the script are remembered, just not carried out. When the Light Sequencer has finished all the effects that is has in it's queue (or you tell it to stop with the .StopPlay method) then it will give control of the lights back to you and restore them to their current real state as set by you in the script). Even while an effect is running you can (in the script) get the real value of the light and not what the Light Sequencer has set it too. This effectively means that you don't have to worry about what the Sequencer is doing to your lights if you use (like many people including myself) light states to control the control logic of your code. [/Tongue Twisting Mode Off]
The Play command has 4 parameter's. Only the first one is required (mandatory). The others don't have to be specified and/or can be skipped if required. If you don't specify them then they will use their default value. The parameters are as follows
Effect: (Required)
TailLength: (Default Value = 0)
Repeat: (Default Value = 1)
Pause: (Default Value = 0)
Examples: (These examples assume you have a Light Sequencer on your table called 'LightSeqAttract').
This command will flush the Queue and restore the lights to their correct state as set by you in the table script. It is processed immediately and the .PlayDone() event is not given to the script.
The .UpdateInterval is the speed at which the Light Sequencer will process the light effect. The smaller the value the faster the effect will run. When the .UpdateInterval has expired then the Light Sequencer will move to the next frame of the current effect it is processing.
Values are specified in Milliseconds and valid values are positive numbers as low as 1 millisecond allowing some very fast effects.
If you don't change the .UpdateInterval in the script, the Light Sequencer will processes all effects at the same speed using the 'Update Interval' property you set for the Light Sequencer in the Editor.
The .UpdateInterval property will not actively change the speed of the current effect running. It is there so specify the speed of the next effect queued by the .play command. This each effect in the queue can run at different speeds, allowing you to mix fast effects with slow effects.
Examples:
' scroll up, turning all the lights on with a tail turning them off LightSeqAttract.UpdateInterval = 10 LightSeqAttract.Play SeqUpOn,75,2 ' as about but with a shorter tail (and quicker) LightSeqAttract.UpdateInterval = 5 LightSeqAttract.Play SeqUpOn,25,2
When the light Sequencer has finished all the effects in the queue it will restore all the lights in the collection back to correct state (as per .StopPlay) and will let the script know by signalling an event for the Light Sequencer that has finished.
Example:
Sub LightSeqAttract_PlayDone() ' The Light Sequencer has finished all the effects in the attract sequence ... End Sub
