## Variables and Functions

Support
Posts: 2342
Joined: Sun Oct 02, 2011 10:49 am

### Variables and Functions

To provide some context, here is a list of variables that will be referenced throughout the following tutorial...

Variables that you may set...

px,py,pz : relative positioning of the object based on its current orientation.

ax,ay,az : relative positioning of the object based on original orientation.

* Units of measure are in inches so if you work in meters for example, you will need to convert your variables back to inches before the script ends.

rx,ry,rz : relative rotation of the object in degrees.

CamPosX, CamPosY, CamPosZ : relative positioning (in inches) of the camera.

CamRotX, CamRotY, CamRotZ : relative rotation (in degrees) of the camera.

fps : the number frames per seconds as you have defined in the animation settings.

cf : the current frame number starting at 1.

sec : the current seconds for the current frame, it's the same as sec = cf / fps

inx : is the index of the instanced object in the list of objects. This is mainly used to randomize movements by some instances and not others. For example, if you load an asset like the Asteroid Rock and have 500 of them, they all share the same script, so you could use inx to perform some actions on some of them, such as those with an odd index number could rotate, and those with even index number will move.

Here is a list of functions (we will go into their details later) you can use to manipulate your object...

Code: Select all

``````Accelerate(AccPerSec, AccUnit, StartAt, EndAt)
Pitch(Angle, StartAt, EndAt)
Roll(Angle, StartAt, EndAt)
Yaw(Angle, StartAt, EndAt)
SetLight(LightID, TurnOn)
Hide
UnHide
``````
and here are other functions (we will go into their details later) you can use beside the normal functions found in the Pascal language...

Code: Select all

``````Power(base,exponent)
modulus(X, Y)
Cycle(value, range)
Random
Mix(x,y, a)
Min(x,y)
Max(x,y)
``````
Naming convention of the variables...

The suffixes "x," "y," and "z" in terms like "px," "ry," and "CamRotZ," indicate the axis that the variable will affect. In Sketchup, the axis position and orientation are displayed in colors, with red representing the x-axis, green representing the y-axis, and blue representing the z-axis.

The positioning variables...

"px," "py," and "pz" are affected by the current orientation. For example, if the z-axis is up, but the object has been rotated 90 degrees so that the z-axis is now horizontal, setting "pz" will move the object horizontally instead of up or down. This is known as the local coordinates.

On the other hand, "ax," "ay," and "az" use the world coordinates, which is the Sketchup origin. In world coordinates, x is left/right, y is forward/back, and z is up and down, regardless of the object's orientation.

The rotation variables...

"rx", "ry", and "rz" represent the amount of rotation in degrees to apply to the local coordinates. It's important to note that this rotation is relative and not absolute. For example, if you set rx to 1, it will rotate your object by 1 degree on every frame. After 30 frames, it will have rotated by 30 degrees.

Now, let's explain the functions. But before that, it's important to understand the commonly used "StartAt" and "EndAt" parameters. These parameters represent the seconds at which the action performed by the function will start and end, respectively. The "Angle" parameter is in degrees.

Accelerate(AccPerSec, AccUnit, StartAt, EndAt)

AccPerSec : the acceleration value such as 144 for an acceleration of 144 units per seconds.

AccUnit : The units used, can be Inches, Feet, Millimeters, Centimeters or Meters.

Example...

Code: Select all

``````// start acceleration of 30 meters per second starting at 2 seconds into the animation until 10 seconds into the animation and then keep a steady speed.
Accelerate(30, meters, 2, 10);
``````
Pitch(Angle, StartAt, EndAt) will automatically and gradually set the rotation variable "rx" for the time frame specified by StartAt and EndAt so that it has rotated by "Angle" by the time it reaches EndAt.

Roll(Angle, StartAt, EndAt) is the same as above but will set "ry" instead.

Yaw(Angle, StartAt, EndAt) is the same as above but will set "rz" instead.

SetLight(LightID, TurnOn) is used to tuen on and off emitters.

LightID is the name of the material that is an emitter or the sub emitter name which can be found in the emitter's object list when more than one light share the same material. You need to encapsulate the name in double quotes. If your material is named Headlights, you need to set this parameter to "Headlights" and if you use an object which most of them are named numerically, you still need the quotes, like "40.12".

TurnOn can be either True or False

Example...

Code: Select all

``````// Turn off the headlights...
``````
BlinkLight(LightID, bps, StartAt, EndAt) is used to blink/flash an emitter on and off at a specific rate per second (bps : blinks per second).

Hide : to hide the object.

UnHide : to unhide the object.

Now the other set of functions...

Power(base,exponent) will return "base" raised to the power of "exponent". For example...

Code: Select all

``````x := power(sec, 3);
// if sec is 2.5 then x will equal to 15.625
``````
Modulus(X, Y) returns the remainder of a division operation between X and Y.