************************************
Features documentation - shivaEngine
************************************

Written by shiva
A (incomplete) listing of some of the events within the shivaEngine script.
Please use the table example and shivaengine.vps script.

*** Multiball. *** (Based off original code example by cold1)

Simple 2 ball multiball run off lights. Ball locks in the top right saucer, lights the bottom 
right saucer for multiball release. If made, this feature will reset for the next ball in play. 
You can easily set it up to be run by a target or other object that can turn the lock on if you like. 
The code is "LightLock1.State = LightStateBlinking"
Look for the multiball code in:

	Dim Multiball 'Tracks amount of balls on the table
	Dim Ballcount 'counts balls on table 
	Table1_Init (table start up)
	NewBall (checks and resets multiball values)(note: 2 sets of statements, at the bottom of the 
	  sub it clears the values at the end of the game and sets the Multiball and Ballcount values to 0 )
	Trough_Init (which creates a new ball):
	Drain_Hit (checks whether or not it's multiball before it goes to it's end ball routine)
	KickerLock1_Hit(First ball locked) : 
	KickerLock2_Hit (release both balls) : 
	Sub Match2() (resets the lights to off at the end of a game)

New Multiball kickers added are KickerLock1 and KickerLock2
The code itself is actually very simple. The pointers to the various subs, and rem statements in the 
code should make it quite easy to use in your own game. 
The trick with multiball is the variables, which hold the multiball value. 
It's still tough to combine Multiball into one subroutine, but following the code should explain 
how easy it actually is to have multiball in your games.

*** Multidirection kicker/ kicker warp ***

Two very common tricks, combined with the multiball feature as a example. 
If you look at the code for the two multiball kickers, you will notice that kickerLock1 will send the 
ball one way for the multiball, and kick the other way for normal use. 
It's a very simple branch statement, controlled by the multiball lights. 
As well, a 'fudge" was used, that during Multiball, LockKicker 1 actually destroys the ball locked 
there, then recreates the ball in Kicker 2, which is directly above it, and then send the ball 
on the blue ramp. That way the ball will go on to the bottom green ramp during Multiball, and end up 
on the right inner lane. This simple trick is actually used a lot in VPinMAME, to simulate lanes 
when used with timers that are "under the table" instead of building a network of ramps under the playfield.
You can also add a third variable to the kicker code to pop a ball straight up, but most designers 
still prefer this method.

*** Ramps ***

If there's anything that causes premature baldness in a table designer from pulling his hair out, 
it's the ramps in Visual Pinball. Though the latest Dogfood build of Visual Pinball made a great 
improvement in the ramps, there are still the known bugs with ramps. The ball will still fall off 
the ramp while it's real slow, and it still suffers from some rendering bugs, and sometimes the 
ball will seem to "hit" something, causing the movement of the ball to appear unnatural.
It's also still a very time consuming process to build a ramp that works, and "looks right" 
so be prepared to spend the most time working on your layout with the ramps. 

The improvements to the program has made it easier to find the problem areas in your ramps, 
usually revolving around the control points on the ramps themselves. Some little tips:

	1. add more control points. If you have a long distance between two points, at the second point, 
	   the ball may appear to hit something, affecting movement. Adding a control point in the middle 
	   usually fixes that, seems VP needs control points to be a certain maximum distance.
	2. make sure those control points are the same, either smooth or not.
	3. A very small space between the end of a ramp and another object will still cause the ball 
	  to fall between the two. When connecting the two objects together, make sure the outer lines 
	  of both objects line up with each other. The other trick is when two control points overlap 
	  exactly, they will look like a normal control point. If they do not overlap exactly, they 
	  will appear sort of "bolded"

The ramps used in this example table are color coded. The blue ramp (above the first lock kicker 
top left) is used for the multiball demonstration, and also as a example for "fudging" a upkicker.
The red left side is the main ramp, and the green ramp is a higher height ramp which 
drops The ball onto the red ramp to continue it's journey. The red ramp loops underneath 
itself using a very simple formula. The height of a VP ball is 50, plastics may be no higher than 55. 
So the first height of The ramp should be set to 60, to prevent the ball being stuck underneath, 
with a higher ramp if it intersects being double that height at 120. 

Basically, you should figure on a minimum of 60 VP units as clearance for each higher 
ramp. (60, 120, 180, 240 etc) A lot of designers use 75 units, so there's no interferance with 
other table objects like pop bumpers and gates, which have a higher set height, usually set by default at 60

*** 2 Button Targets ***

Hit once scores 500 points, lights the button for 1000 and a bonus advance. Resets at the beginning 
of each new ball. Very easy code, pretty much self explainitory.

	Sub BTarget1_Hit()
	'NewBall sub turns LightBT1 off at start of each new ball 
	    If LightBT1.State = LightStateOn then 'if LightBT1 is on
	    addscore 1000 'score 1000 points
	    AddBonus() ' add a bonus
	    Else ' if not LightBT1 is turned on
	    addscore 500 'score 500
	    LightBT1.State = LightStateOn 'switch on the light
	    End If
	End Sub
	
*** Bonus Countdown Intervals *** (Build 1.8)

Very simple actually, with 1 change in the code, and two new lines. First off, in the Sub Drain_Hit(), 
I changed the countdown interval to 400 (Half a second was a little too long)

	Sub Drain_Hit()
	BonusTimer.Interval = 400 					' and start the end of ball bonus count
    BonusTimer.Enabled = True
    End Sub
    
Then in the Bonus Countdown routine, called Sub BonusTimer_Timer(), at almost the very end of the 
subroutine, look at the code:

	Sub BonusTimer_Timer()
	bonus = bonus - 1 								' subtract the bonus we just counted from the total bonus
	BonusTimer.Interval = BonusTimer.Interval - 10	' subtract time for each count
	If BonusTimer.Interval <= 20 then BonusTimer.Interval = 20 ' Make sure the count is not less than 20
	
This basically counts down each bonus, subtract by one bonus value from the total. It then 
decreases the amount of time between each count by 1/100 th of a second for each bonus count.
To change the settings just modify the Timer interval in Sub Drain_Hit(), and if you want to 
change the amount of time between the counts, change the -10 to whatevver you want in the Sub BonusTimer_Timer().