SCRIPT OBJECT REFERENCE
OBJECT FUNCTIONS
void iObjectStart(OBJ_X)
Start the specified object. Note that the target object must provide some 'startable' action.
Please see target object's help file for details on the action it performs when started.
OBJ_X = object handle.
void iObjectStop(OBJ_X)
Stop the specified object. Note that the target object must support some 'stoppable' action.
Please see target object's help file for details on the action it performs.
OBJ_X = object handle.
void iObjectSwitch(OBJ_X)
Switch the specified object (start if stopped and vice-versa).
Note that the target object must provide some 'startable/stoppable' action.
Please see target object's help file for details on the action it performs.
OBJ_X = object handle.
void iObjectShow(OBJ_X)
Show the specified object.
OBJ_X = object handle.
void iObjectHide(OBJ_X)
Hide the specified object.
OBJ_X = object handle.
void iObjectShowHideSwitch(OBJ_X)
Switch the specified object (show if hidden and vice-versa).
OBJ_X = object handle.
void iObjectReset(OBJ_X)
Re-initialize the specified object completely, to its default state, as defined in the project.
OBJ_X = object handle.
void iObjectOrientation(OBJ_X,Quaternion)
Return the current orientation for the specified object.
OBJ_X = object handle.
Quaternion = when the function returns this variable contains
the specified object's orientation.
void iObjectOrientationSet(OBJ_X,Quaternion)
Set the specified object orientation (defined as a quaternion).
OBJ_X = object handle.
Quaternion = orientation.
NOTE: this function will only work with objects that support dynamic orientation setting, like
SkinMesh, Particles, etc. Objects supporting physics do not usually work with this function.
void iObjectOrientationReset(OBJ_X,Quaternion)
Re-initialize the specified object completely, also setting its orientation (defined as a quaternion).
OBJ_X = object handle.
Quaternion = reset orientation.
NOTE: using this function on objects supporting physics, may cause unrealistic behaviors.
void iObjectLocation(OBJ_X,Vector3)
Return the current location for the specified object.
OBJ_X = object handle.
Vector3 = when the function returns this variable contains
the specified object's location.
void iObjectLocationSet(OBJ_X,Vector3)
Set the specified object to the specified position.
OBJ_X = object handle.
Vector3 = location.
NOTE: this function will only work with objects that support dynamic location setting, like
SkinMesh, Particles, etc. Objects supporting physics do not usually work with this function.
void iObjectLocationReset(OBJ_X,Vector3)
Re-initialize the specified object completely, also setting its location to the specified position.
OBJ_X = object handle.
Vector3 = reset location.
NOTE: using this function on objects supporting physics, may cause unrealistic behaviors.
void iObjectScaleSet(OBJ_X,Vector3)
Set the specified object's scale.
OBJ_X = object handle.
Vector3 = scale.
NOTE: this function will only work with objects that support dynamic scaling setting, like
SkinMesh, Sprite, etc.
float iObjectPicked(OBJ_X,Vector3)
If the specified object is mouse-clicked, this function returns the pick location distance from
the current camera (viewport). The function returns always zero if the object is a Sprite.
It returns a negative value if the specified object was not picked.
OBJ_X = object handle.
Vector3 = when the function returns, if the object was picked, then this variable contains
the world-relative coordinates of the pick location.
NOTE: when picking Sprite objects, please keep in mind that the whole original sprite-image is
used as a reference. Therefore any transparent pixels in the image can be picked.
NOTE: when picking an animated 3D object, please keep in mind that, because this function uses
the original, un-morphed geometry as a reference, picking may not be accurate.
int iObjectScan(OBJ_X,Vector3,Vector3,float,Vector3,Vector3)
Return true if the specified object was hit by the scan.
OBJ_X = object handle.
Vector3 = scan origin
Vector3 = scan direction. The length of this vector will be the length of the scanning capsule.
float = scan radius (capsule radius)
Vector3 = contact point (absolute coordinates). Return data.
Vector3 = contact normal (absolute orientation, outward from body surface). Return data.
NOTE: the scan is performed checking the specified capsule against the specified object, for
intersections. Only the intersection closer to origin is considered, in case the
capsule intersects the object at two or more points.
NOTE: this function will only work with objects supporting collision detection.
IMPORTANT: intersections within 'scan radius' from the 'scan origin' are not detected!
Make sure your scan starts 'radius' meters before the possible intersection area.
iObjectTextSet(OBJ_X,string)
Set the specified text for the specified object (for example the TextPrint object)
OBJ_X = object handle.
string = text
STRING FUNCTIONS
int iStringLen(string)
Return the lenght of the specified string, in characters
iStringUCase(string,string)
Convert a string its uppercase version.
string = result string
string = original string
NOTE: the two parameters can be the same string
iStringLCase(string,string)
Convert a string to its lowercase version.
string = result string
string = original string
NOTE: the two parameters can be the same string
iStringLeft(string,string,int)
Copy the first X characters from a string to another string.
string = result string
string = original string
int = number of characters to copy
NOTE: the first two parameters can be the same string
iStringRight(string,string,int)
Copy the last X characters from a string to another string.
string = result string
string = original string
int = number of characters to copy
NOTE: the first two parameters can be the same string
iStringMid(string,string,int,int)
Copy X characters from a string to another string, starting from the specified position.
string = result string
string = original string
int = number of characters to copy
int = position to start copying the characters from
NOTE: the first two parameters can be the same string
iStringStr(string,float,string)
Build a string converting the specified value to characters.
string = result string
float = value to convert
string = a string describing the format of the resulting string
Examples:
"%.0f" - any number of digits for the integer part, zero digits for the fraction part (e.g. 1321)
"%3.0f" - at least 3 digits for the integer part, zero digits for the fraction part (e.g. 321)
"%2.3f" - at least 2 digits for the integer part, 2 digits for the fraction part (e.g. 32.731)
"%05.1f" - at least 5 digits for the integer part, 1 digit for the fraction part. If the integer part has less than 5 digits, missing spaces are filled with zero's (e.g. 00321.3)
"%f" - any number of digits for the integer part and up to six digits for the fraction part (e.g. 1501.540)
"%g" - any number of digits for the integer part and for the fraction part (e.g. 1501.54)
"%.0f%%" - any number of digits for the integer part, zero digits for the fraction part. Also append a percent-symbol (%) to the value (e.g. 77%)
iStringVal(string)
Return the value corresponding the the value in the specified string
iStringFind(string,string,int,bool)
Return the position of a sub-string inside another string. Return -1 if the sub-string could not be found.
string = source string
string = sub-string to find
int = position to start searching from
bool = set this parameter to 'true' to make the search case-sensitive
NOTE: while this function can be used to compare strings, keep in mind that strings also support normal script expressions.
For example, 'if (myString == "foobar")...' is a valid usage. The <, >, != and + operators are also supported.
iStringReplace(string,string,string,string,bool)
Copy a string to another string also replacing all occurrence of a specified sub-string with a specified text.
string = result string
string = original string
string = sub-string to replace
string = text to use as replacement for any occurrence of sub-string found
bool = set this parameter to 'true' to make the search case-sensitive
NOTE: the first two parameters can be the same string
MATH FUNCTIONS
float iFloatRand(float,float)
Return a random float between the two specified values.
float iFloatAbs(float)
Return absolute value of specified float.
float iFloatSin(float)
Return sine of specified angle.
float = angle, in degrees
float iFloatCos(float)
Return cosine of specified angle.
float = angle, in degrees
float iFloatSqrt(float)
Return squared root of specified float.
float iFloatInterpolate(float,float,float,float,float,bool)
Given an input value (interpolation factor), return its interpolated version between
dstmin and dstmax, after comparing it against srcmin and srcmax.
That is: result = dstmin + (dstmax-dstmin)*((input-srcmin)/(srcmax-srcmin))
float = interpolation factor
float = source minimum (srcmin)
float = source maximum (srcmax)
float = destination minimum (dstmin)
float = destination maximum (dstmax)
bool = set this to 'true' to clamp the returned value within destination min. and destination max.
float iFloatTendTo(float,float,float,float,int)
float = float variable to adjust, so that it tends to a certain value.
NOTE: this variable is usually the same used as destination for the
return value. E.g. VAR = iFloatTendTo(VAR,ref,target,speed,mode)
float = referrence value. This is usually zero.
float = target value (value to tend to). Note, the value is never reached really.
float = speed, determines the time taken to reach the specified target value.
int = mode.
Use 0 to reduce variation speed when closer to the target value.
Use 1 to reduce variation speed when closer to the reference value.
Use 2 to reduce variation speed when closer to the reference and target values.
Use 3 to reduce variation speed when closer to the middle point between reference and target values.
NOTE: this function should be executed at every script loop in order to work properly
float iVectorLength(Vector3)
Return the length of the specified vector.
Vector3 = source vector
iVectorRotate(Vector3,Vector3,Quaternion)
Vector3 = transformed coordinates (vector). Return data.
Vector3 = coordinates (vector) to rotate
Quaternion = quaternion representing the rotation to apply
iVectorEulerRotate(Vector3,Vector3,float,float,float,string)
Vector3 = transformed coordinates (vector). Return data.
Vector3 = coordinates (vector) to rotate
float = first rotation. See character string below.
float = second rotation.
float = third rotation.
string = 3-character string specifying the axes and the order in which to apply
the rotations.
For example, "xyz" (apply first rotation about X axis, then second rotation about
Y axis and then third rotation about Z axis), "xzx" and "xzy" are valid strings.
iQuaternionFromAxisAngle(Quaternion,Vector3,float)
Quaternion = resulting quaternion. Return data.
Vector3 = orientation axis.
float = orientation angle.
NOTE: input orientation is expressed by an axis (the vector) and an angle of
rotation about that axis (float).
iQuaternionFromEulerAngles(Quaternion,float,float,float,string)
Quaternion = resulting quaternion. Return data.
float = first rotation. See character string below.
float = second rotation.
float = third rotation.
string = 3-character string specifying the axes and the order in which to apply
the rotations.
For example, "xyz" (apply first rotation about X axis, then second rotation about
Y axis and then third rotation about Z axis), "xzx" and "xzy" are valid strings.
iQuaternionToEulerAngles(Quaternion,float,float,float)
Quaternion = source quaternion.
float = orientation angle about world X axis. Return data.
float = orientation angle about world Y axis. Return data.
float = orientation angle about world Z axis. Return data.
NOTE: the three angles are computed so that they will define the original
orientation only if applied in the "xyz" order.
iQuaternionLookAt(Quaternion,Vector3,Vector3)
Quaternion = resulting quaternion. Return data.
It is the rotation required to orientate the Z+ vector
D3DXVECTOR3(0.0f,0.0f,1.0f) to the specified direction.
Vector3 = direction
Vector3 = up direction. For example Vector3(0,1,0)
NOTE: this function will not work properly if 'direction' and 'up'
vectors are parallel.
iQuaternionMultiply(Quaternion,Quaternion,Quaternion)
Return the orientation resulting from concatenating two given quaternion
orientations (rotations).
Quaternion = resulting orientation. Return data.
Quaternion = source orientation q1
Quaternion = source orientation q2
Imagine an unoriented object. That is, an object with its local Z+ axis parallel to
world's Z+ axis. Imagine applying to it the q2 orientation (rotating it by q2) and
then applying to it the q1 orientation. The resulting orientation is
returned in the quaternion specified as first parameter.
FILE FUNCTIONS
int iFileReadOpen(string)
Open the specified file for reading. Return -1 if the file could not be opened.
string = path to the file. If a local path is specified (e.g. ".\myFile.txt") this is relative
to the current 3D Rad folder or your compiled project folder.
int iFileWriteOpen(string)
Open the specified file for writing. Return -1 if the file could not be opened.
string = path to the file. If a local path is specified (e.g. ".\myFile.txt") this is relative
to the current 3D Rad folder or your compiled project folder.
WARNING: this function permanently deletes the specified file. Before executing a script
including this function, double check that the file path does point to the intended file.
iFileClose(int)
Close the specified file.
int = file handle returned by iFileReadOpen() or iFileWriteOpen()
float iFileValueRead(int)
Read the next value from the specified file.
int = file handle returned by iFileReadOpen() or iFileWriteOpen()
iFileValueWrite(int,float,bool)
Write (appends) the specified value to the specified file.
int = file handle returned by iFileReadOpen() or iFileWriteOpen()
float = the value to write.
bool = if this value is 'true', a caret is added after the written value.
This is necessary if you want to be able to read the value from
the file afterwards by using iFileValueRead().
int iFileByteRead(int)
Read the next byte from the specified file.
int = file handle returned by iFileReadOpen() or iFileWriteOpen()
iFileByteWrite(int,int)
Write (appends) the specified byte to the specified file.
int = file handle returned by iFileReadOpen() or iFileWriteOpen()
int = the byte to write.
MOUSE FUNCTIONS
float iMouseX()
Return mouse horizontal position, where 0.0 = left margin and a value
close to 1.0 = right margin.
Note that the output can be very close to 1.0, but always less than 1.0.
If necessary, you can compute scrren coordinates for a Sprite object as follows:
x = iMouseX()*32.0-16.0;
y = 12.0-iMouseY()*24.0;
float iMouseY()
Return mouse vertical position, where 0.0f = top margin and a value
close to 1.0f = bottom margin.
Note that the output can be very close to 1.0f, but always less than 1.0f.
See iMouseX() for more.
float iMouseZ(bool)
Return mouse wheel position.
bool = whether to return relative wheel position changes since last call to this
function (true), or the absolute wheel position since last call to
iMouseZSet() function (false).
bool iMouseButtonDown(int)
Return true if the specified mouse button is pressed
int = mouse button codes can be 0=left, 1=right, 2=middle
bool iMouseButtonClick(int)
Return true if the specified mouse button is pressed
int = mouse button codes can be 0=left, 1=right, 2=middle
NOTE: this function will return true only once. It will no longer return true until the
button is released and pressed again.
NOTE: you cannot call iMouseButtonClick() more than once per project, in any script, for the same button.
If you do so, only one call will respond to key presses. All others will always return false.
float iMouseLookX()
Return the current pitch (X axis orientation, in degrees) for the current Script object's mouselook system.
The mouselook system keeps track of mouse movements and rotates accordingly.
See also iMouseLookY(), iMouseLookSet(), iMouseLookSpeedSet(), iMouseLookYRangeSet().
float iMouseLookY()
Return the current yaw (Y axis orientation, in degrees) for the current Script object's mouselook system.
See also iMouseLookX().
iMouseLookSet(float,float)
Set the current pitch and yaw (in degrees) for the current Script object's mouselook system.
See also iMouseLookX().
iMouseLookSpeedSet(float,float)
Set the sensitivity (response speed) for the current Script object's mouselook system.
See also iMouseLookX().
iMouseLookYRangeSet(float,float)
Set the pitch limits (minimum, maximum, in degrees) for the current Script object's mouselook system.
See also iMouseLookX().
NETWORK FUNCTIONS
bool iNetServerStart(string &in,string &in,int,int,int)
Start the network system as server for the local machine.
Return false if the system could not be started for some reason.
string &in = session name. Connecting users will see this name in the list of network
games to join, when the client network system is launched on their local
machine. See iNetClientStart() for more.
string &in = player name. The name identifying the server.
int = port number.
The system port to use for network input/output data. For example, 25857.
int = game identifier. This value is used to generate a globally unique identifier
for the game application. For example 9414234 and 372 are valid ids.
The id must be identical both for iNetServerStart() and iNetClientStart() calls.
int = network buffer size, in bytes.
This function allocates memory to be used as temporary buffer for data
exchanges. 100000 bytes is usually enough.
NOTE: after calling this function, you must stop the network system before exiting
the project by calling iNetStop()
bool iNetClientStart(string &in,string &in,int,int,string &in,int,int)
Start the network system as client for the local machine.
Return false if the system could not be started for some reason.
This functions allows you to either open a standard connection dialog box
or directly connect to a defined remote server.
string &in = server IP address. For example "64.64.64.64", or "64.64.64.64:8080"
if a port number is also required.
string &in = player name. The name identifying the local client machine.
int = game identifier. See iNetServerStart() for details.
int = network buffer size, in bytes. See iNetServerStart() for details.
char* = optional dialog box title, or "" for no title.
int = remote game sequential number. If greater or equal to zero, the optional
dialog box is not shown. The specified sequential number indicates the game
to select from the list of available games on the remote server. The first
game in the list is 0, the second is 1 and so on.
NOTE: when hidden, the dialog box is still processed normally. Actually,
the system will simulate user actions, by automatically pressing the
'Search' button, selecting one game from the list and pressing 'Join'.
int = game searching timeout, in seconds (auto connect mode only).
NOTE: after calling this function, you must stop the network system before exiting
the game by calling iNetStop()
void iNetStop()
Stop the network system for the local machine, also releasing all memory resources
allocated by calls to iNetServerStart() or iNetClientStart().
void iNetStringSend(string,int,bool)
Send the specified string to one or all connected client machines.
string = string to send.
int = player identifier. Use zero to send to all players. See also iNetPlayerId().
bool = whether to send the data message as guaranteed (true) or not (false).
Guaranteed messages are ensured to arrive to the destination, even if the connection
is subject to lags and data loss, but they add overhead to the send process.
int iNetStringReceive(string)
Receive a string from the server. See iNetStringSend() for more.
Returns the number of characters received (string length + 1), or zero if nothing was received.
string = string to place the received text into.
IMPORTANT! if you call iNetStringSend() on the server you MUST call this function
at every script loop, on all client PCs.
void iNetFloatArraySend(int,int,bool)
Send the specified number of values in the global array of floats to one or all connected client machines.
The global array of floats is basically a list of values you can set by using iNetFloatArraySet()
before sending it to the clients by calling this funtion.
int = number of values to send. For example, setting this value to 7 will send the first 7 values in the array
int = player identifier. Use zero to send to all players. See also iNetPlayerId().
bool = whether to send the data message as guaranteed (true) or not (false).
Guaranteed messages are ensured to arrive to the destination, even if the connection
is subject to lags and data loss, but they add overhead to the send process.
int iNetFloatArrayReceive()
Receive data from the server and updates the global array of floats accordingly.
See iNetFloatArraySend() for more.
Returns the number of array elements received, or zero if nothing was received.
IMPORTANT! if you call iNetFloatArraySend() on the server you MUST call this function
at every script loop, on all client PCs.
void iNetFloatArraySet(int,float)
Set the value for the specified element in the global array of floats.
See iNetFloatArraySend() for more.
float iNetFloatArrayGet(int)
Read the value of the specified element in the global array of floats.
See iNetFloatArraySend() for more.
int iNetPlayersCount()
Return the current number of connected machines, including the server.
int iNetPlayerId(int)
Retrieve the player's unique ID assigned by the network system to the specified machine
and places it to the specified DWORD variable.
Return -99999 if the information couldn't be retrieved for some reason.
The return ID is required to send messages exclusively to specific players,
or to retrieve statistics data about specific machines.
int = machine to retrieve the player's ID for.
It must be a value between 0 and iNetPlayersCount()-1. Server's ID is always 0x00000000.
int iNetLocalPlayerMachine()
Return the sequential number assigned by the network system to the local machine.
int iNetPlayerMachine(int)
Return the sequential number assigned by the network system to the machine associated
with the specified player.
int = player's unique identifier.
iNetClientDisconnect(int)
Disconnect the specified client machine.
int = machine's player ID. See iNetPlayerId() for details.
NOTE: calling this function on the client machine has no effect.
BOOL iNetSessionTerminated()
Return true if the connection with the server has been lost. The local machine
should then call iNetStop() to stop the network system and free resources.
If called on the server machine, this function will return true if the network
system was stopped.
BOOL iNetPlayersChanged()
Return true if one or more client machines joined or left the session.
float iNetLag(int)
Return the specified machine lag (ping), in seconds.
int = machine ID to retrieve the lag for.
Should be a valid player's ID, as returned by iNetPlayerId().
NOTE: if this function is called on a client machine, this parameter
is ignored, and the local machine lag is returned.
int iNetBPS(int)
Return the average number of bytes per second exchanged by the specified machine
with the network of connected machines.
int = machine ID to retrieve the information for.
Should be a valid player's ID, as returned by iNetPlayerId().
NOTE: if this function is called on a client machine, this parameter
is ignored, and the information is retrieved for the local machine.
int iNetBytesSent(int)
Return the total number of bytes sent by the specified machine.
int = machine ID. See iNetBPS() for details on this parameter.
int iNetBytesReceived(int)
Return the total number of bytes received by the specified machine.
int = machine ID. See iNetBPS() for details on this parameter.
MISC FUNCTIONS
bool iInitializing()
Return true if the script is executed for the first time, after the project was launched.
This function also returns true at the next execution after the script object has beed reset by another object.
bool iDeinitializing()
Return false if the script is executed for the last time, before terminating project execution.
This function also returns true at the next execution after the script object has beed reset by another object.
iScriptStop()
Stop the Script object, preventing any further execution of the code.
The Script object can only resume execution if started by another object.
int iSystemTime(int)
Return system clock data.
int = identifier of the information to return, as follows:
0 - Year
1 - Month
2 - DayOfWeek
3 - Day
4 - Hour
5 - Minute
6 - Second
7 - Milliseconds
For example, iSystemTime(4) will return current hour.
int iDisplayWidth()
Return the current display width, in pixels.
NOTE: unless the project is compiled and running in full-screen, this function returns the Windows desktop width.
int iDisplayHeight()
Return the current display height, in pixels.
NOTE: unless the project is compiled and running in full-screen, this function returns the Windows desktop height.