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.
NOTE: if OBJ_X is an object supporting physics and made of multiple parts (like the Car object)
this function returns the orientation of the part which was selected when the Script object
was linked to the object.
void iObjectOrientationSet(OBJ_X,Quaternion)
Set the specified object orientation (defined as a quaternion).
OBJ_X = object handle.
Quaternion = orientation.
NOTE: this function may cause unstable simulation if you use it to progressively alter the orientation of a
polygon-based RigidBody, or certain rigid-body based objects like the Car object, to make them spin.
It will work as expected if used to spin box/sphere-based RigidBody objects instead.
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: this function should not be used to alter the orientation of objects while their
physics simulation is in progress, because this may affect simulation accuracy for them.
This function should only be used to initialize or reset object orientation.
NOTE: use iObjectPositionReset() if you want to also reset location.
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.
NOTE: if OBJ_X is an object supporting physics and made of multiple parts (like the Car object)
this function returns the location of the part which was selected when the Script object
was linked to the object.
void iObjectLocationSet(OBJ_X,Vector3)
Set the specified object to the specified position.
OBJ_X = object handle.
Vector3 = location.
NOTE: this function may cause unstable simulation if you use it to progressively alter the location of a
polygon-based RigidBody, or certain rigid-body based objects like the Car object, to make them move.
It will work as expected if used to move box/sphere-based RigidBody objects instead.
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: this function should not be used to alter the location of objects while their
physics simulation is in progress, because this may affect simulation accuracy for them.
This function should only be used to initialize or reset object location.
NOTE: use iObjectPositionReset() if you want to also reset orientation.
void iObjectPositionReset(OBJ_X,Quaternion,Vector3)
Re-initialize the specified object completely, also setting its position (orientation and location).
OBJ_X = object handle.
Quaternion = reset orientation.
Vector3 = reset location.
NOTE: this function should not be used to alter the position of objects while their
physics simulation is in progress, because this may affect simulation accuracy for them.
This function should only be used to initialize or reset object position.
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.
void iObjectScale(OBJ_X,Vector3)
Return the current scale for the specified SkinMesh object.
OBJ_X = SkinMesh object handle.
Vector3 = when the function returns this variable contains
the specified SkinMesh object's scale.
NOTE: this function only supports SkinMesh objects.
float iObjectKmh(OBJ_X)
Return the specified object speed, in kilometers per hour (KPH).
OBJ_X = object handle. Must be an object supporting physics, like RigidBody, Car, Ball.
NOTE: you can compute miles per hour with MPH = KPH*0.6215
To find meters per second use M/SEC = KPH*0.277778
iObjectVelocity(OBJ_X,Vector3)
Return the specified object velocity, in meters per second.
OBJ_X = object handle. Must be an object supporting physics, like RigidBody, Car, Ball.
Vector3 = velocity vector. Return data.
iObjectVelocitySet(OBJ_X,Vector3)
Set the specified object velocity, in meters per second.
OBJ_X = object handle. Must be an object supporting physics, like RigidBody, Car, Ball.
Vector3 = velocity vector.
NOTE: this function should not be used to alter the velocity of objects while their
physics simulation is in progress, because this may affect simulation accuracy for them.
This function should only be used to initialize or reset object velocity.
iObjectSpin(OBJ_X,Vector3)
Return the specified object spin.
OBJ_X = object handle. Must be an object supporting physics, like RigidBody, Car, Ball.
Vector3 = spin vector.
The vector direction is the axis of rotation (absolute).
The length of the vector is the rotation speed (spin), in degrees per second.
iObjectSpinSet(OBJ_X,Vector3)
Set the specified object spin, in degrees per second.
OBJ_X = object handle. Must be an object supporting physics, like RigidBody, Car, Ball.
Vector3 = spin vector. The direction of the vector is the spin axis. The length of the vector is the angular velocity.
NOTE: this function should not be used to alter the spin of objects while their
physics simulation is in progress, because this may affect simulation accuracy for them.
This function should only be used to initialize or reset object spin.
iObjectTorqueApply(OBJ_X,Vector3)
Apply an angular force (torque) to the specified object.
OBJ_X = object handle
Vector3 = torque.
Vector direction is the axis of rotation (absolute).
Length of the vector is angular force (torque) intensity.
NOTE: because resulting angular velocity depends on total object mass,
using iObjectAngularAccelerationApply() can be easier.
iObjectAngularAccelerationApply(OBJ_X,Vector3)
OBJ_X = object handle
Vector3 = angular acceleration, in degrees-per-second^2.
Vector direction is the axis of rotation (absolute).
Length of the vector is angular acceleration intensity.
iObjectForceApply(OBJ_X,Vector3,Vector3)
OBJ_X = object handle
Vector3 = force.
Vector3 = point the force is applied to.
Point coordinates are object-center-of-mass relative. If NULL, the
center of mass is assumed.
NOTE: resulting acceleration depends on total object mass. For example, if you apply
one-meter-long force-vector to a still object with mass=5, for one second,
the object will travel 1/5 meters (0.2f). If you apply the same force to an object with
mass=1, it will travel 1.0f meter instead.
Using iObjectAccelerationApply() is probably easier, if the application point
is the object's center of mass.
iObjectAccelerationApply(OBJ_X,Vector3)
OBJ_X = object handle
Vector3 = acceleration, in meters-per-second^2.
The length of the vector is acceleration intensity.
iObjectDampingApply(OBJ_X,float,float,float,bool,bool)
Apply damping factors individually to each axis of the specified rigid-body-based object (RigidBody, Car, PCar etc).
OBJ_X = object handle
float,float,float = damping factors for X, Y and Z axes.
Recommended damping values are between 0.0 (no damping) and 1.0 (maximum damping).
bool = set this parameter to 'true' to apply the damping factor to object's rotation.
Set it to false to apply the damping factors to object's translation.
bool = set this parameter to 'true' to use object's local axes as reference.
Set it to false to use world space axes as reference.
NOTE: this function must be called at every script loop in order to work properly.
float iObjectPicked(OBJ_X,Vector3)
If the specified object is clicked by using any mouse button, 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
iObjectParamSet(OBJ_X,int,float)
Set special internal parameters for the specified object. This function currently only supports the PCar object.
OBJ_X = object handle.
int = parameter identifier. For a complete list and an example of usage please see demo project named PCarScriptedDemo.
float = parameter value.
void iObjectRefresh(OBJ_X,string)
Change the resources (3d models, textures, etc) associated with the specified object.
This function is typically used to update SkinMesh, RigidBody, SkyBox or Sprite object
geometry/aspect run-time, for example after the new artwork has been downloaded from
a server (website) by using the iFileDownload() function.
For an example of usage, see the demo project called WebDownloadDemo.3dr
OBJ_X = object handle.
string = path to the folder containing the new resource file or files. If a local path is specified (e.g. ".\\") this is relative
to the current 3D Rad folder or your compiled project folder.
IMPORTANT: the destination object (OBJ_X parameter) will try to load the proper file or files from the specified folder.
Make sure the destination folder contains the files to be loaded with the proper names (for example, a SkinMesh
object will try to load a files named 000_mesh.x, 000_shadow.x etc).
NOTE: if the destination folder is a SoundEffect or a SoundSource object, the file path must include the file name to use
to replace the current sound.
NOTE: if the object is a SkinMesh based on frame-by-frame animation, the new
assets must provide the same number of frames.
NOTE: this function doesn't work for RigidBody objects that use a bounding sphere
for collision detection.
int iObjectBonesCount(OBJ_X)
Return the number of bones in the specified object (usually a SkinMesh).
OBJ_X = object handle.
NOTE: depending on the software used to generate the .x skinned model, the returned
value may or may not include null bones, therefore returned bone count tends to be
bigger than the number of actual bones edited in the 3d modeling application.
void iObjectBoneOrientation(OBJ_X,int,Quaternion,int)
Return specified object's bone orientation.
OBJ_X = object handle.
int = index of the bone. This value must be between 0 (first bone) and iObjectBonesCount()-1.
Each bone in the model is indexed by the software used to generate the .x
skinned model. There is no easy way to predict what index will be assigned
to a particular bone.
Quaternion = orientation. Return data.
int = orientation type.
0 = world-relative.
1 = object-relative.
2 = parent-bone relative.
iObjectBoneLocation(OBJ_X,int,Vector3,int)
Return specified object's bone location.
OBJ_X = object handle.
int = index of the bone. This value must be between 0 (first bone) and iObjectBonesCount()-1.
Each bone in the model is indexed by the software used to generate the .x
skinned model. There is no easy way to predict what index will be assigned
to a particular bone.
Vector3 = location. Return data.
int = location type.
0 = world-relative.
1 = object-relative.
2 = parent-bone relative.
void iObjectBoneOrientationSet(OBJ_X,int,Quaternion,int)
Set specified object's bone orientation.
OBJ_X = object handle.
int = index of the bone. This value must be between 0 (first bone) and iObjectBonesCount()-1.
Each bone in the model is indexed by the software used to generate the .x
skinned model. There is no easy way to predict what index will be assigned
to a particular bone.
Quaternion = orientation.
int = orientation type.
0 = world-relative.
1 = object-relative.
2 = parent-bone relative.
NOTE: this function must be called at every script loop in order to work as expected.
NOTE: for an example of usage, please see the SkinMeshBoneControlDemo.3dr sample project.
iObjectBoneLocationSet(OBJ_X,int,Vector3)
Set specified object's bone location (parent-bone relative coordinates).
OBJ_X = object handle.
int = index of the bone. This value must be between 0 (first bone) and iObjectBonesCount()-1.
Each bone in the model is indexed by the software used to generate the .x
skinned model. There is no easy way to predict what index will be assigned
to a particular bone.
Vector3 = location (parent-bone relative).
NOTE: this function must be called at every script loop in order to work as expected.
iObjectBoneScaleSet(OBJ_X,int,Vector3)
Set specified object's bone scale.
OBJ_X = object handle.
int = index of the bone. This value must be between 0 (first bone) and iObjectBonesCount()-1.
Each bone in the model is indexed by the software used to generate the .x
skinned model. There is no easy way to predict what index will be assigned
to a particular bone.
Vector3 = scale.
NOTE: this function must be called at every script loop in order to work as expected.
iObjectEnvMapFocusSet(OBJ_X,Vector3)
Set the focus location for the environment map associated with the specified SkinMesh object.
OBJ_X = SkinMesh object handle.
Vector3 = focus location, absolute coordinates.
iObjectImpostersCreate(OBJ_X,int)
Create the specified number of imposters for the object (must be SkinMesh).
Imposters are clones of the main SkinMesh object that can be placed by using the iObjectImposterSet() function.
They render faster than multiple identical SkinMesh objects because the video card doesn't have to re-load
the 3d model's data for each rendered item.
OBJ_X = SkinMesh object handle.
int = number of imposters to create.
NOTE: this function will currently only work with SkinMesh objects that have no bone-based animation.
iObjectImpostersDestroy(OBJ_X)
Remove all imposters for the specified SkinMesh object.
OBJ_X = SkinMesh object handle.
iObjectImposterSet(OBJ_X,int,Quaternion,Vector3)
Set orientation and location for the specified SkinMesh object's imposter.
OBJ_X = SkinMesh object handle.
int = imposter index
Quaternion = orientation.
Vector3 = location.
iObjectImposterGet(OBJ_X,int,Quaternion,Vector3)
Get orientation and location for the specified SkinMesh object's imposter.
This function can be used for example to copy the position of a RigidBody
imposter to the position of a SkinMesh object imposter.
OBJ_X = SkinMesh object handle.
int = imposter index
Quaternion = when the function returns this variable contains
the specified imposter's orientation.
Vector3 = when the function returns this variable contains
the specified imposter's location.
iObjectImposterScaleSet(OBJ_X,int,Vector3)
Set scaling for the specified SkinMesh object's imposter.
OBJ_X = SkinMesh object handle.
int = imposter index
Vector3 = scaling. X, Y, Z components of this vector are the local scaling factors. Original size is when the scaling factor is 1.0.
iObjectImposterHide(OBJ_X,int)
Hide the specified SkinMesh object's imposter.
OBJ_X = SkinMesh object handle.
int = imposter index
NOTE: if the imposter has a shadow, calling this function will disable it. After
showing the imposter again with iObjctImposterShow(), you will have to also call
iObjectImposterShadowEnable() to re-enable the shadow.
iObjectImposterShow(OBJ_X,int)
Show the specified SkinMesh object's imposter.
OBJ_X = SkinMesh object handle.
int = imposter index
iObjectImposterShadowEnable(OBJ_X,int,bool)
Enable/disable shadow casting for the specified SkinMesh object's imposter.
OBJ_X = SkinMesh object handle.
int = imposter index
bool = set this parameter to 'true' to enable shadows, 'false' to disable.
NOTE: calls to this function are ignored if the SkinMesh doesn't have a shadow caster itself.
NOTE: imposter shadows are faster than regular SkinMesh shadows, but they are still
a computationally expensive feature, slow for video cards with a poor fill-rate.
In some cases, enabling shadows defeats the purpose of using imposters.
iObjectImposterTorqueApply(OBJ_X,int,Vector3)
Apply an angular force (torque) to the specified object.
OBJ_X = object handle
int = imposter index
Vector3 = torque. Vector direction is the axis of rotation (absolute).
Length of the vector is angular force (torque) intensity.
NOTE: resulting angular velocity depends on total object mass.
This means that using iObjectImposterAngularAccelerationApply() may be preferable in some cases.
iObjectImposterAngularAccelerationApply(OBJ_X,int,Vector3)
OBJ_X = object handle
int = imposter index
Vector3 = angular acceleration, in degrees-per-second^2.
Vector direction is the axis of rotation (absolute).
Length of the vector is angular acceleration intensity.
iObjectImposterForceApply(OBJ_X,int,Vector3,Vector3)
OBJ_X = object handle
int = imposter index
Vector3 = force.
Vector3 = point the force is applied to.
Point coordinates are object-center-of-mass relative. If NULL, the
center of mass is assumed.
NOTE: resulting acceleration depends on total object mass. For example, if you apply
one-meter-long force-vector to a still object with mass=5, for one second,
the object will travel 1/5 meters (0.2f). If you apply the same force to an object with
mass=1, it will travel 1.0f meter instead.
This means that using iObjectImposterAccelerationApply() may be easier, if application point
is the object center of mass.
iObjectImposterAccelerationApply(OBJ_X,int,Vector3)
OBJ_X = object handle
int = imposter index
Vector3 = acceleration, in meters-per-second^2.
The length of the vector is acceleration intensity.
iObjectImposterVelocitySet(OBJ_X,int,Vector3)
Set the specified object's imposter velocity, in meters per second.
OBJ_X = object handle. Must be a RigidBody object.
int = imposter index
Vector3 = velocity vector.
NOTE: this function should not be used to alter the velocity of imposters while their
physics simulation is in progress, because this may affect simulation accuracy for them.
This function should only be used to initialize or reset imposter velocity.
NOTE: calling the function for one imposter may affect the simulation of the other imposters
in the same batch and cause a slight performance loss, during the game loop in which the
function is called.
iObjectChildTransform(OBJ_X,OBJ_Y,Vector3,Vector3)
Set angular/linear offsets for a specified object (the child) using the local space of another object (the parent) as a reference.
OBJ_X = parent object handle.
OBJ_Y = child object handle.
Vector3 = angular offset (vector components are Euler angles, x, y, z).
Vector3 = linear offset.
CUSTOM SHADER FUNCTIONS
iShaderSet(OBJ_X,string)
Assign the specified shader (or post-process shader) to the specified SkinMesh (or CamChase) object. After the call to this function,
the SkinMesh (or camera) will be rendered by using the specified shader until the function is called again
with a different shader name as parameter.
OBJ_X = SkinMesh or CamChase object handle.
string = shader name. Shaders are defined as HLSL code sections, delimited by '/*HLSLSTART name' and 'HLSLEND*/' tags,
usually at the beginning of your script code. The shader name is the string following the '/*HLSLSTART' keyword.
Please see http://www.3drad.com/custom-shaders.htm for more about writing your own shaders for 3D Rad.
IMPORTANT: the 'Use custom shaders' option, on the SkinMesh property dialog, must be
checked, before a custom shader can be applied to the SkinMesh by calling iShaderSet().
Or, if the object is a CamChase object, the 'User' option must be selected in the 'Filter' drop down list.
NOTE: the iShaderSet() function uses very little processing power and can be used to switch shader as frequently
as needed (for example to create special run-time visual effects).
iShaderStack(OBJ_X,string,float)
Add the specified post-process shader to the specified CamChase object.
All shaders will be processed in the same order as they are added (stacked).
OBJ_X = CamChase object handle.
string = shader name. If this is an empty string (""), the list of shaders added to the camera is reset (cleared).
See iShaderSet() for further information on this parameter.
float = scaling factor. If different than 1.0f, the render-target texture is resized after the pixel-shader is processed,
before it is copied to the screen (or to the next render target, which is then used as source by the next pixel-shader).
If negative (and between -1.0f and 0.0f), the pixel-shader will only operate on a smaller part of the source texture and render target.
iShaderFloatSet(OBJ_X,string,float)
Set a float variable for the HLSL shader associated with the specified SkinMesh or CamChase object.
Note that this function should be called at every script loop to work properly. Failing to do
so may cause visual artifacts.
OBJ_X = SkinMesh/CamChase object handle.
string = shader veriable name, as declared in the HLSL code header.
If this is an empty string (""), the data isn't immediately sent to the shader. Instead it is added to a buffer.
The buffer is then sent to the shader only when a non-null string is provided, in a subsequent call to any other
iShaderFloat..Set() function. This allows you to 'build' an arbitrary list of float values and send it one
go, for example to an arbitrarily long array of floats declared in the HLSL shader. For an example of usage, please see
the sample project called PostProcessStacked.3dr
float = value to set
iShaderFloat2Set(OBJ_X,string,float,float)
Same as iShaderValueSet() but allowing you to set two values at a time. This is typically used
to set a 'float2' vector variable in your HLSL code.
iShaderFloat3Set(OBJ_X,string,float,float,float)
Same as iShaderValueSet() but allowing you to set 3 values at a time. This is typically used
to set a 'float3' vector variable in your HLSL code.
iShaderFloat4Set(OBJ_X,string,float,float,float,float)
Same as iShaderValueSet() but allowing you to set 4 values at a time. This is typically used
to set a 'float4' vector variable in your HLSL code.
iShaderFloat4x3Set(OBJ_X,string,float,float,float,float,float,float,float,float,float,float,float,float)
Same as iShaderValueSet() but allowing you to set 12 values at a time. This is typically used
to set a 'float4x3' matrix variable in your HLSL code.
iShaderFloat4x4Set(OBJ_X,string,float,float,float,float,float,float,float,float,float,float,float,float,float,float,float,float)
Same as iShaderValueSet() but allowing you to set 16 values at a time. This is typically used
to set a 'float4x4' matrix variable in your HLSL code.
iShaderViewMatrixSet(OBJ_X,string,OBJ_Y)
Extract the view matrix from the specified CamChase object,
and directly pass it to the specified SkinMesh's custom shader.
In the custom shader the matrix should be declared as a 'float4x4' variable.
OBJ_X = SkinMesh object handle.
string = shader veriable name, as declared in the HLSL code header.
OBJ_Y = camera object (rendering window) to be used as a reference.
iShaderProjectionMatrixSet(OBJ_X,string,OBJ_Y)
Extract the projection matrix from the specified CamChase object,
and directly pass it to the specified SkinMesh's custom shader.
In the custom shader the matrix should be declared as a 'float4x4' variable.
OBJ_X = SkinMesh object handle.
string = shader veriable name, as declared in the HLSL code header.
OBJ_Y = camera object (rendering window) to be used as a reference.
int iShaderTextureCreate(string)
Load the specified image file and return a handle to the texture object. See also iShaderTextureSet().
string = source image file name (bmp, dds, dib, jpg, png, tga).
NOTE: creating again and again the same texture (from the same source file) will not
waste memory, even if the call to this function happens in different Script objects.
3D Rad will re-use the data already in memory, if possible.
iShaderTextureDestroy(int)
int = texture object handle. See iShaderTextureCreate().
Destroying texture objects when your project no longer uses them is not necessary because 3D Rad will do it automatically on exit.
However designing your scripts so that they always remove textures that are no longer needed is good practice
because it frees memory that can be used by other reources in your project.
iShaderTextureSet(OBJ_X,string,int)
Set a texture to be used by the HLSL shader associated with the specified SkinMesh or CamChase object.
OBJ_X = SkinMesh/CamChase object handle
string = texture name, as declared in the HLSL code header.
int = texture object handle. See iShaderTextureCreate().
STRING FUNCTIONS
int iStringLen(string)
Return the length 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 = position to start copying the characters from
int = number of characters to copy
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%)
float iStringVal(string)
Return the value corresponding 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
iPrint(string,float,float,OBJ_X)
Print the specified string by using the font and character settings as configured in the specified
TextPrint object
string = text (255 characters max). Multi-line text is supported (use '\r' to specify a new line character).
float,float = screen position. Note that resulting text location depends on source TextPrint object settings.
OBJ_X = TextPrint object handle.
NOTE: this function will only print the text once. In order to display a permanet text it must be executed
at every script loop.
iGlobalStringSet(string,int)
Set the specified element of the global array of strings.
The global array of strings can hold up to 1024 strings and is accessible by all scripts in the
project or all scripts in all projects that have been compiled together (e.g. a multi-level game).
string = string to copy to the specified array element (1024 characters max).
int = array element index (0-1023).
iGlobalStringGet(string,int)
Get the specified element of the global array of strings. See iGlobalStringSet() for more.
string = string to place the received text into.
int = array element index (0-1023).
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 = reference 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
NOTE: see project called 'TutScript6_iFloatTendTo.3dr' for an example of usage.
float iFloatTrend(float,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 = iFloatTrend(VAR,refMin,refMax,target,speed,mode)
float = minimum reference value.
float = maximum reference value.
float = target value (value to tend to). Must be between minimum and maximum reference values.
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 a reference value.
Use 2 to reduce variation speed when closer to a 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
NOTE: this function is similar to iFloatTendTo(), but the harmonic effects it produces are usually more
accurate as it relies on two reference values instead of one.
float iVectorLength(Vector3)
Return the length of the specified vector.
Vector3 = source vector
float iVectorLengthSq(Vector3)
Return the squared length of the specified vector.
Vector3 = source vector
iVectorLengthSet(Vector3,Vector3,float)
Force the length of a vector to the specified value, without changing its direction
Vector3 = transformed vector. Return data.
Vector3 = source vector
float = desired length. Set this value to 1.0f to 'normalize' a vector.
float iVectorDot(Vector3,Vector3)
Return the dot product of the specified 3d vectors.
Vector3 = first source vector
Vector3 = second source vector
iVectorCross(Vector3,Vector3,Vector3)
Return the cross product of the specified 3d vectors.
Vector3 = resulting vector. Return data.
Vector3 = first source vector
Vector3 = second 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.
iVectorCompare(Vector3,Vector3,float)
Vector3 = first vector.
Vector3 = second vector.
float = threshold.
Set this value to zero for a strict comparison (the function returns true if the vectors are identical)
or specify a positive value to check if the difference between each vector component (X,Y,Z) is within a certain threshold.
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.
iQuaternionInterpolate(Quaternion,Quaternion,Quaternion,float)
Compute an intermediate orientation from two given orientations, by a given factor.
Quaternion = resulting orientation. Return data.
Quaternion = source orientation q1
Quaternion = source orientation q2
float = if it is 0, q1 is returned. If it is 1, q2 is returned. Intermediate
values (e.g. 0.13 etc) return intermediate orientations.
iQuaternionCompare(Quaternion,Quaternion)
Return true if the quaternions are identical.
Quaternion = first quaternion.
Quaternion = second quaternion.
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 newline 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.
iFileStringRead(int,string)
Read the next string from the specified file.
int = file handle returned by iFileReadOpen() or iFileWriteOpen()
string = string to place the read text into.
iFileStringWrite(int,string,bool)
Write (appends) the specified string to the specified file.
int = file handle returned by iFileReadOpen() or iFileWriteOpen()
string = string to write.
bool = if this value is 'true', a newline is added after the written string.
This is necessary if you want to be able to read the string from
the file afterwards by using iFileStringRead().
bool iFileEOF(int)
Return true if any previous iFile...Read() call has reached the end of the file, or an error occurred.
int = file handle returned by iFileReadOpen() or iFileWriteOpen()
bool iFileExists(string)
Return true if the specified file exists
string = name of file to check. If a local path is specified (e.g. ".\\myFile.txt") this is relative
to the current 3D Rad folder or your compiled project folder.
iFileCopy(string,string)
Copy a file.
string = source file name. If a local path is specified (e.g. ".\\myFile.txt") this is relative
to the current 3D Rad folder or your compiled project folder.
string = destination file name. If a local path is specified (e.g. ".\\myFile_bak.txt") this is relative
to the current 3D Rad folder or your compiled project folder.
iFileDelete(string)
Remove the specified file.
string = name of file to delete. If a local path is specified (e.g. ".\\myFile.txt") this is relative
to the current 3D Rad folder or your compiled project folder.
iFolderCreate(string)
Create a new folder.
string = name of folder to create. If a local path is specified (e.g. ".\\myFolder") this is relative
to the current 3D Rad folder or your compiled project folder.
iFolderDelete(string)
Remove the specified folder, if it is empty.
string = name of folder to delete. If a local path is specified (e.g. ".\\myFolder") this is relative
to the current 3D Rad folder or your compiled project folder.
int iFileDownload(string,string)
Downloads a file from the specified Web location to the local computer.
Return the size of the downloaded file, or -1 if an error occurred.
string = URL of the file to download (like for example 'http://www.3drad.com/index.htm').
string = destination file name. If a local path is specified (e.g. ".\\index.htm") this is relative
to the current 3D Rad folder or your compiled project folder.
NOTE: 3D Rad processing will stop until the download is completed or it was interrupted by the user (Esc key).
int iFileDownloadPB(string,string)
Same as iFileDownload(), but displaying a progress bar during the download.
NOTE: the progress bar is shown at the lower edge of all camera windows active on the screen when the function is called.
In your compiled projects, you can customize the progress bar aspect by modifying the .\3DRad_res\system\progressBarDL.dds file.
You can also use a different image format by opening the progressBarDL.x file with an ASCII editor and changing the
'progressBarDL.dds' name to your alternate image file (must be .dds, .png, .tga, .bmp or .jpg).
int iFileSize(string)
Return the size of the specified file, or -1 if the file could not be found.
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.
iLocalFolder(string)
Place the path of the 3D Rad's installation folder (or your compiled project's folder)
into the specified string.
string = string to place the local folder into.
bool iFileOpenDialog(string,string,string)
Open the Windows file open dialog box allowing the user to browse the file system and
select a file. Return true if a file was selected, false if the dialog was canceled.
string = initial file path. When the function returns, it will be the file
path chosen by the user.
NOTE: the string must include the file name, with extension, or a generic
file name like "c:\\foobar\\*.txt". The extension must be the same as
the extension filter (see next parameter).
string = extension filter.
For example "txt" will allow only .txt files to be browsed.
Set this parameter to "*" to allow browsing of all file types.
string = dialog box title.
NOTE: Windows standard dialogs aren't supported in full-screen mode. Compiled projects that use this
function must be set to only run in windowed or maximized mode.
bool iFileSaveDialog(string,string,string)
Open the Windows' save-as dialog box allowing the user to browse the file system
and type a filename to save. Return true if a file was selected, false if the
dialog was canceled or an error occurred.
See also iFileOpenDialog().
KEYBOARD FUNCTIONS
bool iKeyDown(int)
Return true if the specified key is pressed
int = key code. Use the iKeyCode() function to find the key code for specific keyboard keys.
Set this value to -1 to check if any key is pressed
NOTE: not all keyboards allow for more than two simultaneous key presses to
be detected, unless one of them is [Ctrl] or [Alt].
int iKeyCode(string)
Return the key code corresponding to the specified description.
string = key code description (e.g. 'DIK_A', 'DIK_B', etc). The complete list of key code
descriptions can be found on the Web by searching for 'Keyboard Device Constants'.
int iTypedChar(bool)
Return the character (ASCII code) generated by the current keystroke. Return zero if
no key is pressed or there is no printable character associated with the pressed key.
Note however that it will return -1 if [Enter] is pressed and -2 if [Backspace] is pressed.
International, standard 256-code ASCII based keyboards are supported.
bool = if 'true', this function will return the character only once. It will then return
zero until the key is released. If 'false', it will keep returning the character
until the key is released.
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 screen 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().
NOTE: because this function controls the mouse location, it can be only called once per script loop and
only from one single script at a time.
float iMouseLookY()
Return the current yaw (Y axis orientation, in degrees) for the current Script object's mouselook system.
See also iMouseLookX().
NOTE: because this function controls the mouse location, it can be only called once per script loop and
only from one single script at a time.
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().
INPUT DEVICE FUNCTIONS
int iJoyCount()
Return the number of installed joysticks/gamepads/steering-wheels
bool iJoyButtonDown(int,int)
Return 'true' if the specified joystick/gamepads/steering-wheel button is pressed
int = joystick number
int = joystick button number (0-127)
float iJoyX(int)
Return position of X axis for the specified joystick/gamepads/steering-wheel.
Returned value is between -1.0 and 1.0.
int = joystick number
NOTE: never assume that the returned value is stable. For example, even if the joystick is
relaxed (centered), for some devices, the returned value may not be always zero.
See iJoyXAverage()
float iJoyY(int)
Return position of Y axis for the specified joystick. See iJoyX() for more.
float iJoyZ(int)
Return position of Z axis for the specified joystick. See iJoyX() for more.
float iJoyXAverage(int,float)
Return average position of X axis for the specified joystick/gamepads/steering-wheel.
int = joystick number
float = average computation period, in seconds. Basically, an average value is returned
after summing up direct values from the hardware for the specified period.
float iJoyYAverage(int,float)
Return average position of Y axis for the specified joystick. iJoyXAverage() for more
float iJoyZAverage(int,float)
Return average position of Z axis for the specified joystick. iJoyXAverage() for more
float iJoyU(int)
Return position of additional U axis for the specified joystick. See iJoyX() for more.
float iJoyV(int)
Return position of additional V axis for the specified joystick. See iJoyX() for more.
float iJoyPOV1/2/3/4(int)
Return direction controller state for the specified joystick. The value is in
in degrees from north (clockwise). Center position is -1.
iMidiInOpen(int,bool)
Open the specified MIDI device for input
int = MIDI device index. For example, if you have 3 MIDI devices attached to your PC, 0 will be the first MIDI device, 1 the second and 2 the third.
bool = if this value is set to 'true', a message box displaying a list of attached MIDI devices will be shown. This function is for debug purposes only.
NOTE: this function is currently experimental
bool iMidiInMessage(int,int,int)
Receive a message from the currently opened MIDI device (see iMidiInOpen() function). For an example of usage, please see the sample project
called 'MIDI_test.3dr'
NOTE: this function is currently experimental
iMidiInClose()
Closes the MIDI device opened with iMidiInOpen().
NOTE: this function is currently experimental
NETWORK FUNCTIONS
bool iNetServerStart(string,string,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 = 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 = 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,string,int,int,string,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 = server IP address. For example "64.64.64.64", or "64.64.64.64:8080"
if a port number is also required.
string = 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.
string = 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 iNetFloatArraySendEx(int,int,int,bool)
Send the specified part of 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 function.
int = index of the first value of the array to send (see also next parameter).
int = number of values to send. For example, setting the previous value to 0 and this value to 7 will send the first 7 values in the array.
Another example: setting the previous value to 3 and this value to 7 will send the fourth value in the array and the 6 values following it.
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.
NOTE: if this function is called on a client machine, the array will only be received by the server.
void iNetFloatArraySend(int,int,bool)
This function is obsolete. If called it actually calls iNetFloatArraySendEx() with the first parameter set to zero.
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.
NOTE: this function can also be called on the server, to receive arrays from client machines.
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 specified machine is no longer connected.
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 255. Server's ID is always 0x00000000.
NOTE: when called on a client, this function always returns -99999.
int iNetLocalPlayerMachine()
Return the sequential number assigned by the network system to the local machine, based on when it joined the game.
If the local machine is the server, the returned value is zero.
Return -1 if the system isn't in network mode.
NOTE: the machine number doesn't change when another player leaves the game. However if the local player leaves the game
and then joins again, it's machine number may be different.
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.
NOTE: when called on a client, this function always returns -1
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.
EXTERNAL DLL FUNCTIONS
int iDLLLoad(string)
Load the specified DLL module ad make any exposed function in it available for calling.
Return a handle to the loaded DLL module, or zero if a problem occurred.
See iDLLCall() for more.
string = DLL module file.
iDLLUnload(int)
Release the specified DLL module.
int = DLL module handle. See iDLLLoad().
bool iDLLCall(int,string,int)
Calls the specified function in the specified DLL module, passing an array of float values as parameter.
int = DLL module handle. See iDLLLoad().
string = DLL function name.
int = index of the first element of the array of floats to pass to the user DLL function. This is usually zero.
For each Script object, the array of floats is defined by default and can be accessed by using iDLLArraySet() and iDLLArrayGet().
NOTE: please see the demo project called 'iDLLCall.3dr' ('Script_Functions_Usage_Examples' sub-folder) for an example of usage.
iDLLArraySet(int,float)
Set the value for the specified element in the array of floats.
See iDLLCall() for more.
int = index of the array element to set. Must be between 0 and 16383.
float iDLLArrayGet(int)
Return the value of the specified element in the array of floats.
See iDLLCall() for more.
int = index of the array element to get. Must be between 0 and 16383.
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 been started or reset by another object.
bool iDeinitializing()
Return true if the script is executed for the last time, before terminating project execution.
This function also returns true at the last execution after the script object has been stopped by another object
or by a call to iScriptStop().
iScriptStop()
Stop the Script object, preventing any further execution of the code.
The Script object can only resume execution if started by another object.
NOTE: after this function is called, the script will execute once more.
Calling the iDeinitializing() function during this last execution,
will return true.
int iObjectHandle(int)
This special function lets you programmatically determine the OBJ_ value of a certain object from its
position in the 'Object HANDLE' window. The returned value can be passed to functions in place of the actual
OBJ_ variable.
int = index of the object to retrieve the handle for, as it appears in the 'Object HANDLE' window (Script editor),
with zero being the first item, 1 the second and so on. If this parameter is -1 the function returns the
total number of items in the 'Object HANDLE' window.
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.
iBoundingSphereFrustumCheckSet(bool)
Enable/disable quick exclusion of SkinMesh objects rendering if
their bounding spheres are outside the rendering window.
bool = 'false' to disable, 'true' to enable. Default is 'true'.
float iFrameRate(bool)
Return the current frame-rate (frames rendered per second).
bool = whether to return average frame-rate (true) or instant frame-rate (false).
NOTE: instant frame-rate is actually based on the time needed to process the last rendered frame.
To get the real instant frame-rate, clamp the returned value within 0 and 60.
iGammaSet(float,float,float,float,float,float)
Set the gamma for the full screen display (compiled project only).
float,float,float = Red, Green, Blue bias factor (> 0.0). Default brightness for each
rgb component is multiplied by the specified value. So, for example,
specifying 2.0 for all the three components will double the display
brightness. Default value is 1.0 (no bias).
float,float,float = Red, Green, Blue offset factor (between -1.0 and 1.0). The specified
value is added to the default brightness for each rgb component.
Default value is 0.0 (no offset).
NOTE: this function has no effect when called in windowed mode.
NOTE: this function is computationally expensive and should not be called at every script loop.
int iVertexShaderVersion(bool)
Return the vertex shader version supported by the hardware.
bool = set to 'false' to return the major version (e.g., return 2 if vs version is 2.0),
set to 'true' to return the minor version (e.g., return 0 if vs version is 2.0)
int iPixelShaderVersion(bool)
Return the pixel shader version supported by the hardware.
bool = set to 'false' to return the major version (e.g., return 2 if ps version is 2.0),
set to 'true' to return the minor version (e.g., return 0 if ps version is 2.0)
iRenderingEnable(bool)
bool = set to 'false' to disable the rendering of the scene, processing the simulation at the maximum speed allowed by the system.
This can be useful if you are only interested in the results of a simulation, and want to get them
as fast as possible.
Set this value to 'true' to restore rendering.
iShadowsEnable(bool)
bool = set to 'false' to disable rendering of volumetric shadows, which may dramatically improve framerate.
Set this value to 'true' to restore shadow rendering.
iEscKeyDisable()
Disable the Esc key, which normally stops a compiled project at any time and exit back to Windows.
Warning, when the Esc key is disabled, the only way to terminate a compiled project is by using
the ExitFade object.
Use iEscKeyEnable() to re-enable the Esc key.
NOTE: this function only works in a compiled project.
iSettingsDialogDisable()
Disable the startup dialog which is shown when the compiled version of your project is launched.
Note that this will only work the next time the compiled project is run.
Use iSettingsDialogEnable() to re-enable the startup dialog or to make sure it is shown, even if the user
selected 'Don't show this dialog again' on the dialog.
NOTE: this function only works in a compiled project.
iSimulationQualitySet(int)
Set physics simulation accuracy.
int = set this value to non-zero to enable reduced accuracy (typical value 20).
The lower the value, the lower the accuracy and the faster the
processing. Reduced accuracy will dramatically improve processing
speed where many joints are defined and many collisions are performed.
Set this parameter to zero to set maximum supported accuracy (default).
NOTE: setting the parameter to a negative value (eg -1) will use additional
computation to make very fast moving RigidBody objects less likely
to go through polygonal-based RigidBody objects (like walls). This feature
is computationally expensive and may cause poor frame rates.
iSimulationFrqSet(float)
Set simulation frequency (physics simulation speed).
float = simulation frequency. Normal speed is 0.016666f (1.0f/60.0f).
Decrease the value to slow down the simulation. Increase it to
speed it up.
NOTE: Script objects' loop frequency is not affected by simulation speed changes.
NOTE: while frequency can be set to zero, practically causing the simulation to pause,
because sudden changes in simulation speed cause computation errors and affect
simulation accuracy, simply setting the speed to zero and resuming it to normal
will not be a viable solution, to pause your games. You may only be able to
preserve simulation integrity by progressively adjusting simulation speed in
your scripts.
NOTE: speed change will only affect physics. It will not affect Particles, CamChase
speed, or any other effect which timing is not directly dependant on physics simulation.
bool iCommand(string)
Executes the specified Windows command (CLI).
string = command to execute.
NOTE: control will only go back to 3D Rad after the command has been completed.
NOTE: this function opens an invisible CLI window, so, if you use it to directly
launch an application, the application may be invisible as well. The
workaround is launching a batch file instead, which in turn launches the application.
bool iCommandContinue(string)
Like iCommand(), except that control will return immediately to 3D Rad's script, with the
application working in the background, until it is closed by the user or it terminates by itself.
NOTE: if the launched application cannot terminate by itself, you must use the intermediate
batch file method (see iCommand() function above), otherwise closing it manually
will not be possible, being it an invisible background application.
iExitDocumentSet(string)
Open the specified file after the program is terminated.
The document is typically an .html file, for example the user manual for your compiled project.
string = path to the file to open.
NOTE: this function only works in a compiled project.
bool i3DPointVisible(OBJ_X,Vector3)
Return TRUE if the specified 3d point is within the specified camera window.
OBJ_X = camera object
Vector3 = 3d point location
bool iSphereVisible(OBJ_X,Vector3,float)
Return TRUE if the specified sphere is within the specified camera window.
OBJ_X = camera object
Vector3 = sphere center location
float = radius
NOTE: see SkinMeshImpostersVisible demo project for an example of usage.
i3DLocationToScreen(Vector3,Vector3,OBJ_X)
Vector3 = screen location. Return data.
Resulting coordinates specify a screen location using
the same convention used for iObjectLocationSet()
when the object is a Sprite, a ValuePrint or a TextPrint object.
NOTE: if the source 3d location is outside the viewing
frustum returned 2d coordinates will be outside the screen.
NOTE: if the source 3d location is behind the camera,
returned 2d coordinates will be both 1000000000.
Vector3 = source 3d location to convert to screen coordinates.
OBJ_X = camera object to be used as a reference.
iScreenRay(Vector3,Vector3,Vector3,OBJ_X)
Return a 3d vector with origin at the specified camera location and pointing toward
the 3d location indicated by the specified screen coordinates.
Vector3 = 3d ray origin, absolute coordinates. Return data.
Vector3 = 3d ray direction. Return data.
Note that the length of this vector is random. You will typically
need a specific length for your computation. You can set the length
of a vector with iVectorLengthSet()
Vector3 = screen coordinates defining a 3d point at infinite distance
from the camera, in the virtual space.
Coordinates specify a screen location using
the same convention used for iObjectLocationSet()
when the object is a Sprite, a ValuePrint or a TextPrint object.
OBJ_X = camera object (rendering window) to be used as a reference.
bool iSpherePicked(Vector3,float,OBJ_X,Vector3)
Return true if the specified sphere is pointed by the mouse.
Vector3 = sphere center, world-relative coordinates.
float = sphere radius
OBJ_X = camera object (rendering window) to be used as a reference.
Vector3 = when the function returns true, this variable contains
the world-relative coordinates of the point indicated by
the mouse, on the sphere surface.
int iSphereSegmentIntersect(Vector3,float,Vector3,Vector3,Vector3,Vector3)
Return the number of intersection points between the specified sphere and the specified segment.
Vector3 = sphere center, world-relative coordinates.
float = sphere radius
Vector3 = location of the first vertex for the 3d line segment, world-relative coordinates.
Vector3 = location of the second vertex for the 3d line segment, world-relative coordinates.
Vector3 = when the function returns non-zero, this variable contains
the world-relative coordinates of the first intersection point.
Vector3 = when the function returns 2, this variable contains
the world-relative coordinates of the second intersection point.
bool iScreenAreaPicked(float,float,float,float,bool)
Return 'true' if the specified screen area is pointed by the mouse.
float,float = coordinates of the upper-left corner of the pickable screen area.
float,float = coordinates of the lower-right corner of the pickable screen area.
bool = if set to 'true', the function will only return 'true' once, when the left
mouse button is clicked while the area is pointed by the mouse.
NOTE: coordinates specify a screen location using
the same convention used for iObjectLocationSet()
when the object is a Sprite, a ValuePrint or a TextPrint object.
iScreenshotSave(string)
Save a screenshot as an image file in .jpg or .bmp format.
For an example of usage, please see the sample project called ScreenshotDemo.3dr
string = file path (absolute or relative) of the .jpg/.bmp file to save
NOTE: the screenshot will always be of the whole screen. It means that,
for your 3drad applications running in windowed mode, the screenshot
may include parts of the Windows desktop.
iSuperScreenshotSave(string,int)
Save a screenshot of the 3D scene as tiles. Each tile is an image with the same format as the current display.
The tiles can be combined by using a paint program or a specialized tool, to form the original
screenshot, as an unique high resolution image.
There is virtually no limit in the number of tiles you can produce for each screenshot, so there
is virtually no limit in the size, in pixels, of the final image.
string = file path (absolute or relative) of the base .jpg/.bmp file.
3D Rad will use this name as basis to name the tiles as sequence of numbered files.
int = number of tiles per dimension. For example, 3 will produce 9 tiles (3x3 grid of tiles).
NOTE: this function will not work for sprites and texts. Any 2D element on screen will not be
included to the images created. Particles active in the scene may also look slightly
different in the final image.
NOTE: this function is designed to work in full-screen or maximized mode. In Windowed mode,
because each tile will be a screenshot of the whole screen, additional editing may be
required to compose the image and obtain the finished high-resolution screenshot.