Hoser v1.0 Keyscript copyright 1995 Spectral Imaging

Creator Peter Watje
	   Compuserve Address : 74453,225
	   Internet Address   : peterw@blarg.com

The hoser script is particle animation script.  It will allow you take a list of objects and explode, spray, 
or jitter them.  It is free to distribute freely with the only restrictions being that if you make changes to 
the script that you feel are worth while please repost it to the compuserve Autodesk/Scripts forum or 
send them directly to me.  Also I would like to see any animation/stills that you create that you think are 
cool you can either send them to my compuserve account, internet address, or just post them to the 
Autodesk forum.  Other than that this script has your basic disclaimer that you can't sell it and I am not 
responsible for any damage that it may create. 

This script is basically just an object accelerator.  You give it a list of objects, a center point, the initial 
starting velocity, and some other values.  It then calculates the trajectory of each object based on these 
parameters.  It works really well in conjunction with Metaballs, Vapor, and Bones.  It has basic collision 
detection.  The below figure is the main dialog that controlls the keyscript.

 


Object Name are the objects that are to be accelarated.  The script uses the name of objects to determine 
which ones are to be affected.  For example if you put Object in this field and and 10 in the number of 
objects field.  The objects that would be affected by the script would be Object, Object01, Object02, .. 
Object09.  Note : the the first object has no number.  The P button next to the field will bring up a 
selector box so that you chose an object.

Center Object is the name of the object to be used to compute the angles at which the objects will be 
accelerated when Center Launch or Center Jitter is active.  This object will act as the center of the 
explosion to compute the angles and velocity of the other objects.

Number of Objects is the number of objects to be accelerated.

Initial Velocity is the initial velocity for each object.  Note the initial velocity of the object is in 3D 
Studio units per frame.  The initial velocity is also effected by fall off.

Gravity is the gravity that will affect the object in unit/frame^2.  A negative gravity is downward 
direction and positive is up.

Elasticity is how much the object will bounce.  If this set to 0 the object will not bounce.  If the value is 
1 the object will not lose any height when bounces.

Collision Reduction is the friction of the object.  A value of 0 means that as soon as the object hits and 
object it stops.  A value  of 1 means that the object will roll indefinitely.

Fall Off is how much initial velocity is decreased based on how far away the object is from the center.  
A fall off of 0 means that their is no decrease in initial velocity.  A fall off 1 means that the object 
farthest away will have no initial velocity and the closest object will have a 100% of the initial velocity 
with every object in between getting an appropriate velocity based on there distance.  Note putting a 
value greater than 1 or less than 0 will produce upredictable result.

Random Angle is used to add randomness to the angle of each object when it is launched.  The field is in 
degrees.

Random Velocity is used to add randomness to the velocity of each object when is is launch.  The field 
is in units/frame.

Number Per Frame is the number of objects per frame that are affected.  So if you set this value to 20 
the first frame the first 20 objects are release at frame 2 the next 20 are released and so on.  If you want 
the spray effect set this value to less than the total number of objects.  If you want an explode effect set 
this value equal to the total number of objects used.

Sample Rate determine how acurrate the data is computed.  The smaller the number the more 
calculations and longer calculation times, but it builds a more accurate trajectory.  This mainly has to do 
with collision detection.  If yoiu are doing no collision detection you can set this to 1 or greater.  
Basically this how many  times  the trajectory is computed.  So if you put a value of 1 the it computes a 
trajectory for every frame.  If you use a value of 2 it computes a trajectory point for every other frame.  
If you use a value 0.25 there are four computations for each frame. 

Random Launch/Center Launch button is toggle button that switches between using the center object to 
determine the angle that the object is released at or whether the angle is completely random.

Acceleration is the initial acceleration of the object.
Note this feature has just been added and is not fully tested.

Stop Acceleration is the frame where the object stop accelerating.  This a relative value.  So if you put 
10 in here and the object starts moving at frame 10 the acceleration will stop at frame 20.
Note this feature has just been added and is not fully tested.

Jitter On/Off this button turns jitter on or off.  When this button is turned on all the objects will jitter 
until the release time.  Basically when an object jitters goes until it has gone farther than then the jitter 
radius.  When it reaches that point it reverses direction.

Random Jitter/Center Jitter this button toggle whether the initial jitter angle is based on the Center 
Object or is completely random.

Release Time is a relative value and when this frame is reached the object stops jittering and is launched 
based on the Random/Center Launch button.

Jitter Radius is how far away the object will travel before it reverses direction.

Radius the radius field is the radius of the object that will be used for collsion detection.  This field is 
used when the Compute Radius button is on..

Compute Radius button deteremines whether to use th radius field to detremine the object radius or to 
use the objects bounding box to compute the radius.  If the button is set to on the bounding box is used.  
If it is set to off the radius field is used.   Computing  the bounding box radius is slower than using the 
Radius field.

Load loads a DAT file that contains the information for all the fields.

Save saves the field data to DAT file so it can be used latter.

All the all button applies the script to all the frames in the animation.

Range button applies the script to frame designated in the start and end fields.

Segment button applies the script to the current segment.

Collision Types 
There are two possible ways to check collision either Planar or Object BBox.  Objects uses sphereical 
detection collision to determine if an object is hit. The radius of each object can be computed or set 
manually(manual computes faster).  The compute radius button/field determines this.

Planar

 

Planar checks to see if an object has broken a plane defined by the user and if it has it bounces that object 
appropraitely.  To turn on plane click on the appropriate button until it says on then enter the values for 
that plane.  For example if you wanted to make sure no object went below a 20 Y value turn the floor 
button on and enter 20 in the field below.  This type of collision detection computes the fastest.


Object BBox Collision 

 

BBox collision uses the bounding boxes of objects to determine object collisions (note the bounding boxes 
are all aligned to the global axis).  To add an object to the collision list just click Add and select an 
object to be used as collision object.  To remove an object click on the Remove button until it is activated 
and then click on the object to remove.  To clear the entire list click on the Clear button.  This type of 
collision detection is considerable slower than planar.  Also it checks for collision by seeing if the objects 
center is inside the collision object's bounding box.  If an object has an extremely fast velocity and the 
sample rate is turned up it has the potential to to completely miss a collision object.

Note true vertex to face collision or center to face collision maybe implemented latter.

Tutorial

Tutor 1 Explosion

This tuturial will show how to make a bunch of objects explode.  First load the TUTOR1.PRJ file.  
Notice that you have and grid of objects starting at Object and going to Object100 and an object called 
Center below the grid.  Now start up the hoser by getting into the Keyframer and pressing F9 and then 
loading up the HOSER.K3D.  Execute the script by pressing F1.  Now load up the EXPLODE.DAT file 
by selecting the Load button and then selecting the EXPLODE.DAT file.

Thing to notice about the fields is the Object Name Field is set to Object and that the Number of Objects 
field is set to 101.  This tells the script to affect objects Object  to Object100. Also notice the Number 
Per Frame is set 101 the same as the number of objects.  This make sure that all the objects are launched 
at the first frame.  If this value had been less than the Number of Objects it would have taken more than 
1 frame to launch the objects.  Go ahead and hit the OK button and wait for all the gauges to finish and 
then go back to the Keyframer and advance through the frames.  Notices how objects Object to 
Object100 move away from the center object.  

Now go back to keyscript and run the hoser script notice how all the values have been saved.  Now 
change the fall off from 0 to 1 and hit OK.  Go into Keyframer and now notice that objects that are 
farther away from the center have less velocity.  Falloff determines how much velocity is applied to an 
objects based on its distance.  A 0 fall off means that all objects will have the same velocity.  A 1 falloff 
means that the farthest objects will have no initial velocity while the closest objects will have 100% of the 
initial velocity.

Before going back into the keyscript for the next tutorial first click on the Window Zoom Icon and line it 
up with to top the object called floor from the front view. Notice that at the top of the screen the Y value 
reads about -264.  Now go back into the keyscript and run the hose script again. We now do some basic 
collision.  Press the Planar collision button will turn on the Planar Collision Detection and bring up a 
parameter dialog box .  This dialog box allows you to establish basic plane collision detection.  Click on 
the Floor button until it turns on and then type -264 in the field below.  By doing this you are telling the 
script that no object's Y value will go below -264.  This can done for all the other axis by turning on or 
off the appropriate buttons and setting there values.  Hit OK to close the dialog and now we are back to 
main dialog.  Now we need to set the objects radius we can do this by hand or have the script figure it 
out.  Since I know the obects radius is 20 enter this value in the Radius field (note this not the Jitter 
Radius field and then turn the Compute Radius button to off.  Now hit OK and go back to Keyframer and 
notice that now the object bounce when they go past a Y value of -264.

Other things to try are setting a different elasticity to get different bounce height,  set the random velocity 
or random angle to randomize the effect, or play with different intitial velocities and gravities.

Tutor 2 Spray

This tutorial will show how to create a stream of objects as if the were being streamed from a hose.  
First load TUTOR2.PRJ.  Notice that there 100 objects called Liquid to Liquid99 and they are all stacked 
in the same place.  Now go into the Keyscripter and execute the HOSER.K3D script.  Load the 
SPRAY.DAT file into hoser.

Notice now that the Number Per Frame is set to 8.  By doing this only 8 objects will released per frame 
instead them all being released at once. Go ahead and hit the OK button and let the script execute.  Go 
into the keyramer and see now that the objects stream from their initial location.

Now go back into the HOSER script and we will do some bounding box collision.  Click on the Object 
Bbox Collsion button which will turn on the bounding box collision and bring a parameter dialog.  This 
parameter dialog box allows you to add and remove object from a list which will be used for collision 
detection.  Click on the Add button which will bring up a an object selector dialog box and select the 
objects Floor and Floor0 and hit OK.  These 2 objects now will show up in the list of objects that  will 
be checked for collisions.  Hit OK again to close the Bound Box collision dialog box, and then execute 
the script by hitting OK again.   Go into the keyframer and notice now that the objects bounce off the 
collision objects.

Other interesting effects that can be genereted by moving the center objec while the objects are spraying.  
Execute the same script again but change the center object to Center and notice now that the objects 
stream out in s spiral type pattern.


Tutor 3 Jitter


This tutorial will show how to jitter objects.  First load TUTOR23PRJ.  Now go into the Keyscripter and 
execute the HOSER.K3D script.  Load the JITTER.DAT file into hoser.  Things to notice is that the 
Jitter Button is On.  The Jitter Radius is set to 5, which means that the object will move 5 units then 
change direction. The Jitter Release frame is 80 which means that the object will stop jittering after 80 
frames, relative to its start time.  Other things to note is that the objects actually accelerates instead of 
having a constant velocity, which is set by the Acceleration field.  It stop accelerating after 50 frames 
from which it started which is set by the stop Acceleration field.



Tips and Tricks


Some usefull tricks that I have learned are always start with small values and work your way up.  
Sometime if you start with a large value in field you get starnge results.  If you plan to affect a lot objects 
start by only affecting  a few (so you dont havee long computation times) until you get the right motion 
then apply it to all the objects.


Warning

Keyscripting is not blazing fast I tried to put guages on operations that take a while but sometime with 
very large file with lots of keydata you may get long delays where nothing may seem to be happening.  
Be patient it is probably just computing something.

Do not use excessive velocity with collision detections unpredictable results may occur.

For planar collision do not have objects thats start that violate a plane, such as starting an object below a 
floor plane.

There is no way to tell if an object or file exist so if you enter a name of an object that does not exist you 
will get an error.

Sometimes you will get a divide by zero error I am in the process of trying track all these down.  If you 
do get a divide by zero object usually moving the center object a little bit will resolve the  problem.



Things that maybe added:

Object Center/Vertex to Object Face collision non 90 degree

Maybe assign individual attributes to individual objects so that you may objects with different 
acceleration, velocities, etc.

Tumbling

Conversion to IPAS KXP.


If you have any question or comments I can be contacted at

	   Peter Watje
	   Compuserve Address : 74453,225
	   Internet Address   : peterw@blarg.com

