GIANTS Game Engine v5 Documentation
Table of Contents
- Chapter 01: Overview
- Enable development controls
- Runtime development key short-cuts
- Console Command Reference
- Chapter 02: Editor
- Viewport
- Scenegraph
- Attributes
- Toolbar
- Terrain
- User Attributes
- Scripting
- Terrain Editing
- Replace Dialog
- Interactive Placement
- Other functionality
- Key short-cuts
- Chapter 03: Tutorials
- Tutorial 1 - Load i3d files and basics
- Tutorial 2 - Light functions, global time and rendering text
- Tutorial 3 - User Attributes
- Tutorial 4 - Timers
- Tutorial 5 - Physics
- Tutorial 6 - Overlays
- Tutorial 7 - Audio
- Chapter 04: Scripting Reference
- Function Reference
- General
- Entity
- Node
- Scenegraph
- Lighting
- Camera
- Shape
- Physics
- Spline
- Animation
- Overlays
- Sound
- Input
- XML
- Network
- Callbacks
- Foundation Reference
- Scenegraph
- Input
- Chapter 05: Exporter
-
Autodesk Maya1 i3d exporter
- Material export options
- Autodesk 3ds MAX2 i3d exporter
- Blender i3d exporter
- Chapter 06: Content Creation - Artwork Guide
- Autodesk Maya
- Autodesk 3DS MAX
- Texturing
- Chapter 07: I3D Format
- Introduction
- Features
- Overview
- Specification
- General Layout
- Materials
- Shapes
- Dynamics
- Scenegraph
- Animation
Overview
Enable development controls
Open the file game.xml and change the value of controls from false to true.
<?xml version="1.0" encoding="utf-8" standalone="no" ?>
<game>
...
<development>
<controls>true</controls>
</development>
</game>
Runtime development key short-cuts
| Key |
Function |
| ~ or ` |
Toggle console |
| F2 |
Show frame rate |
| F3 |
Toggle frame rate limiter |
| F4 |
Wireframe mode |
| F5 |
Toggle debug rendering |
| F7 |
Toggle camera |
| F8 |
Toggle stats |
Console command reference
help
Description
List all available commands
showFps
Description
Show frames per second
enableFramerateLimit
Description
Enable/disable frame per second limiter
framerateLimitFPS
Description
Frame per second limit attribute
listEntities
Description
Print detailed entity list
listResources
Description
Print detailed resource list
parallelRenderingAndPhysics
Description
Enable parallel rendering and physics
exit, quit or q
Description
Quits application
Editor
Table of Contents
- Viewport
- Scenegraph Panel
- Attributes Panel
- Toolbar
- Terrain Editing
- User Attributes
- Animation Panel
- Particle System Panel
- Spline Editing
- Scripting
- Replace Dialog
- Interactive Placement
- Other functionality
- Keyboard short-cuts
If you start up the Editor, you might not have all the panel windows open. To
open other panel windows open the menu option window and enable the panel you want.
You can adjust the width and height of the panels by dragging the outlines and if you
want to close a window you can simply press the cross right of the panel name.
Viewport
Navigation
The navigation is quite like in Maya. If you have nothing open in your editor I
suggest you quickly open a simple i3d file otherwise you won’t see much of an
effect. If its to dark in your scene just create a light by going to Create–>Light.
Some shortcuts:
LMB = Left Mouse Button
RMB = Right Mouse Button
MMB = Middle Mouse Button
Alt + LMB = Press and hold the Alt-Key and the left mouse button.
Alt + LMB rotates the camera.
Alt + RMB moves the camera forward and backward.
Alt + MMB causes the camera to pan.
If you don’t have a middle mouse button, you can press LMB and RMB instead.
View Options
By simply right-clicking into the viewport panel you get the View Options.
Sometimes it’s useful too use different cameras in a scene. You can create them
once and then with the View Options you can choose the camera to view at your
scene from different angles quickly.
You might notice that if you rotate, the camera is rotated. If you have a big
level this behaviour is very useful, but if you want to look at one particular
object this can be quite awkward. To change the rotation to Framed Rotate you
first have to select your object either by clicking on it directly or by
choosing it from the scene-graph and the framing the selected object by pressing
the F key. Now you can simply click (RMB) on the screen to open the View Options
and choose Framed Rotate. Now the camera is rotating around your the last framed object.
With solid or wireframe you can choose if you want the view shaded.
If you have large scenes, you can toggle the visibility of lights,
audio sources, physics and the cameras by checking them on the show submenu.
You can also use the Selectable submenu to toggle whether you can select
lights, audio sources or cameras.
Furthermore you can toggle the grid and the polycount on and off.
Scenegraph Panel
A very useful feature of the GIANTS Editor is the scenegraph. If you don’t
have it on the screen, just go to menu window and hit scenegraph. It is basically
the same you have in Maya. It shows all objects you have in your scene
and also the parent-child relationship between your objects.
Let’s just make a little scene with some Transform Groups. The Transform Group is
the basic building block of your scene. You can use a TransformGroup to move
all the attached objects just by moving the Transform Group since the children
inherit the transformations of the parent. To create a new Transform Group go to
Create and hit TransformGroup. Now you can see it in the Scenegraph, its name is
transform. To change the name just select it and go to the attributes panel.
At the very top of the panel you can choose the name of your object. Make two
TransformGroups and name them Parent and Child. If you move them around you see
that their transformations are independent, the movement of the parent
doesn’t affect the child. Now let’s make the appropriate relationship between
the two. Select the child in the scenegraph panel and go to Edit->Cut. Now select
your parent and hit Edit->Paste.
As you can see now, the child is now connected to the parent. If you now move
around the parent, the transformation of the child is affected too whereas the child
can be moved around without affecting the parent.
There can be 6 types of objects in your scene: Triangle Meshes, Splines,
Cameras, Transform Groups, Lights, Terrains and Audio Sources.
It is also possible to use CTRL + C to copy objets, CTRL + X to cut objects and
CTRL + V to paste objects. Notice that pasted objects are always children of the
currently selected object. If you want to paste an object on the highest hierarchy
level of the scenegraph be sure that nothing is selected in the scenegraph. This can
be achieved by clicking at an empty space in the scenegraph panel.
Attributes Panel
If you don’t see the attributes panel go to Windows->Attributes then select
an object in the scenegraph or the viewport. One important thing to notice is,
that if the background color of an attribute turns red, you entered a value that isn’t allowed.
(eg scale values other than 1 for a dynamic rigid body object) The background
color of animated attributes is yellow.
The toolbar looks like this. If your pointing on the icons with your mouse, a text with the functionality of
the tool is displayed.
Let’s quickly go through them from left to right.
File Operations
- Create a new i3d-File
- Open a i3d-File
- Open i3d in text editor
- Reload i3d
- Save the i3d-File
- Save the i3d-File as
- Import an i3d-file
History
- Undo last action
- Redo last action
Physics
If you hit the play icon, the physics will simulate.
Toggle Local- World Mode
A handy tool is the toggle Local- World Mode, it changes the orientation of the
viewport transform gizmo from the local space of your object to world space.
Grid Snapping
Use this option to snap objects to a predefined grid.
Terrain and Terrain Foliage
- Terrain Sculpt Mode
- Terrain Detail Texture Paint Mode
- Terrain Foliage Paint Mode
- Save Terrain Data
Texture Reload
- Reload all Textures
- Reload Textures of selected objects
Script Editor
Terrain Editing
To test the terrain sculpting, just open the terrain test scene. Now you have
a terrain to play with. Open the terrain editing panel with window->Terrain Editing.
(If the scenegraph panel is still open it might cut off a bit, just close it
to get more space.)
If the terrain sculpt mode is active now, you can rise or lower the surface of
your terrain by using RMB and LMB. MMB can be used to smooth and the value
defines the force with which you pull or push. What happens here is, that you
are painting a height map, that defines the height of each point of your
terrain by giving it a grey-value. The attributes Opacity, Hardness and the
Value are defining the "brush" you are painting the height map with. Just play
around with the setting. You can change the radius of the brush with the shortcuts "V" and "B"
and you can change the opacity value of the brush quickly with "N" and "M".
In the terrain texture paint mode next to the terrain sculpt icon you can
colorize your terrain with different textures.
The used texture layers are defined in the i3d-file. (If you want to change the texture layers,
you have to open the i3d with a text editor and change the layers there) Just
choose your texture and paint onto your terrain. With the Chunk vis checkbox on,
you can see exactly which texture layers you used in a chunk by what amout. You can
use as many texture layers as you want, but you are limited to a maximum of four
texture layers per chunk.
With the Terrain Foliage Paint Mode active, you can paint your foliage onto
your terrain, it`s the same thing as if you would paint onto your terrain -
not with a texture but with foliage. LMB adds foliage, RMB removes foliage.
User Attributes
The user attributes panel is typically not visible if you open the editor for
the first time. So go to Windows->User Attributes. Select an object in the
scenegraph to see its user attributes.
User Attributes can be defined in the editor and then be used in the engine
(eg. within a script). This enables you to define object specific attributes for
every object in the scene.
Animation Panel
You can preview animation sets with the animation panel.
Particle System Panel
The particle system panel allows you to edit particle systems with real time preview.
Spline Editing
You can edit splines by picking a control vertex (CV) of a spline an moving it around.
Delete or insert new control vertices with the keys delete and insert.
Scripting
Here you can execute script snippets. With ENTER, you can add new lines.
SHIFT+ENTER will execute the code in the text field.
Type in the following:
print("hello world from the GIANTS Editor");
Then hit SHIFT + ENTER and the string is printed out above.
The scripting can be useful for many things. For example you can run this script snippet to test the fog settings in
an i3d scene:
setFog("exp2", 0.002, 0, 0.8, 0.81, 0.97);
Replace Dialog
If you want to replace an object in your scene, you can go to Edit->Replace to
open the replace panel. Select the object you want to replace, then hit load.
Do likewise with the object you want to replace with and choose whether you want
to keep the User Attributes or not. Now you can replace one single object by
hitting replace or you can replace all objects that are similar to the one you
selected by hitting replace all.
Note: replace all does only work with single objects, but not with hierarchies of objects,
however the single replace function works.
This feature is quite useful because you can use it to substitute an object
reference feature within your i3d scene file.
Interactive Placement
This is a really nice feature of the editor, you should try it at least once!
To place an object on the surface of another object, you can simply select the
object you want to place and then press CTRL + B + LMB, while pointing at your
desired location. The selected object will then instantly be set to the
location you’ve chosen.
Hint: you can do this with all your objects within your scenegraph and also
with the camera or light sources. E.g. you can select the current camera and then place the
camera at a location far away, allowing for fast relocation of the camera.
If you keep the LMB pressed and hit SHIFT or CRTL you can clone the selected object
at the currect mouse position. SHIFT will just clone the object while CRTL will
add a random rotation in the Y-axis. (Useful feature if you want to
create a group with hundreds of randomly rotated objects like a forest)
Other functionality
Edit->Clear History: This clears the undo/redo history.
Edit->Move to Camera: Moves the selected object in front of the current camera
Navigation Speed: Moves the camera faster or slower. Use - and + to ajust the speed.
Keyboard short-cuts
| Key |
Function |
| Alt + LMB |
Rotate camera |
| Alt + MMB |
Pan camera |
| Alt + RMB |
Zoom camera |
| Alt + LMB + RMB |
Move camera up or down and left or right camera |
| F |
Frame selected object |
| - |
Decrease navigation speed |
| + |
Increase navigation speed |
| 4 |
Wireframe mode |
| 6 |
Shaded mode |
| Ctrl-S |
Save |
| Ctrl-Z |
Undo |
| Ctrl-W |
Replace Dialog |
| Ctrl-X |
Cut |
| Ctrl-C |
Copy |
| Ctrl-V |
Paste |
| Ctrl-Shift-C |
Copy X,Y,Z components at once |
| Ctrl-Shift-V |
Paste X,Y,Z components at once (can also be copied from a text source in the format "x y z") |
| Delete |
Delete |
| Ctrl-D |
Duplicate |
| Ctrl-F |
Move to Camera |
| Ctrl-B |
Interactive placement (hold left mouse button to move around) |
| Shift |
Interactive placement paint |
| Ctrl |
Interactive placement paint with random rotation around y axis |
| Ctrl-R |
Pick replace value in viewport (Terrain edit modes) |
| V |
Decrease brush radius |
| B |
Increase brush radius |
| N |
Decrease brush opacity |
| M |
Increase brush opacity |
| F8 |
Toggle stats |
| Shift + Enter |
Execute Script (Script Window) |
| X |
Grid Snapping |
| Delete |
Delete spline control vertex |
| Insert |
Insert new spline control vertex |
| Left |
Previous spline control vertex |
| Right |
Next spline control vertex |
| Up or Down |
First spline control vertex |
| S |
Stitch spline endpoints |
| O |
Toggle spline open/close |
| R |
Reverse spline |
Tutorials
Tutorial 1 - Basic setup and loading i3d files
The goal of this tutorial is to teach you the very basics of the GIANTS engine.
You simply load an i3d with a cube in it and then rotate the cube by using
LUA script.
Sample name: SampleI3DLoading
Script source code file: sample/i3dLoading/main.lua
The goal of this tutorial is to show you
- how the engine uses ids
- how to load i3d files
- how to access objects within a loaded i3d
- what the base callback functions of the engine are
- how to access keyboard commands
New functions in this tutorial
init()
keyEvent()
update()
rotate()
getRootNode()
loadI3DFile()
link()
getChildAt()
print()
requestExit()
The most important script file is your main.lua. It is a lua file that is
loaded and executed when your exe file is started.
The first thing you need to know is how the engine exactly knows where your
main.lua is. Well there has to be an xml file in the same folder as your exe
with exactly the same name as your exe. In this case it is named
SampleI3DLoading.xml. Open it with a text editor.
<?xml version="1.0" encoding="iso-8859-1" standalone="no" ?>
<startup>
<cmdline>game.exe -script sample/i3dLoading/main.lua</cmdline>
</startup>
In the third line you see where your main.lua is located. If you want to move
your main.lua, you have to change the path in this xml as well.
So, let's have a look at this main.lua, open it with any text editor. There
are 5 essential functions: init(), mouseEvent(), keyEvent(), update() and
draw(). Let's look at these functions in detail:
init()
init() is executed once when you start your exe. Let’s go through the function
line by line:
local worldRootNode = getRootNode();
The variable worldRootNode is defined and assigned with the result of a
function called getRootNode();
If you meet a new function and you don’t exactly know what it does, simply look
here and search for the function. Then you get
detailed information about the function. In the tutorials those function
descriptions are always blue.
Here is what you find if you search for the getRootNode function:
getRootNode
Description
Get scenegraph root node
Definition
function getRootNode()
Return Values
| integer | rootNodeId | id of the root node |
The descriptions of the functions are quite self-explanatory and can be really
helpful.
It's important to see that the GIANTS engine works with ids also called handles.
This function returns the id from the root node of your root scene graph.
Your entire world is attached to this root node. Each object you want to see
later on must be a child of this root node.
Now we need to load the i3d that contains the cube we want to rotate later on.
local sceneToLoad = loadI3DFile("sample/i3dLoading/cube.i3d");
With this function, you load an i3d file, and its id (which is an integer) is
returned. Now that we’ve got both things, the worldRootNode and the i3d we
want to load, we have to link them together, which is the next line of code.
link(getRootNode(), sceneToLoad);
Now we want the cube's id to rotate. Be aware that the i3d we've already loaded
is the whole scene which contains not only the cube, but also a light and the
camera. So now we need to know which id the cube has. Since the cube is a child
of the i3d we can use the following function:
cubeId = getChildAt(sceneToLoad, 0);
First you name the i3d that you want the child from and then you say which
child you want. 0 is the first child, 1 is the second. You need to know which
child is your cube. Just open the cube .i3d with the Editor and you can see
that the cube is the first position in your scenegraph (reading from top
down)
A very important thing you need in programming are prints. The function needed
here is simply called print(). The thing you want to print are the parameters.
Be careful with strings, they always need quotes. You can link strings and
variables by using .. as shown in the example.
print("this is a print: cube id: " .. cubeId);
You can see the printed text in the in game console. Just press tilde '~' to
make the console visible.
Now we have all the information we need, but one thing remains to be done.
Since the camera is located right in the center (inside the cube actually)
we won’t be able to see anything. So we grab the camera and move it a bit.
With the getCamera() function we first get the id of the camera, because the
setTranslation function needs to know which id has to be translated. The next
parameters are the desired x, y, z values.
setTranslation(getCamera(), 5, 10.0, 10.0);
Then we rotate the camera so that we can see our cube nicely. The function is
similar to the setTranslation but you define the rotations around the three
axes of course. You need a radian value, that’s why the functions math.rad()
are used. They convert a degree value into a radian value.
setRotation(getCamera(), math.rad(-45), math.rad(20), 0);
mouseEvent()
We don’t use this function right now, but of course you can access the mouse
commands with it.
function mouseEvent(posX, posY, isDown, isUp, button)
end;
keyEvent()
This function is used to access any keyboard commands. In this case, we only
want to know if the escape key is pressed. If this is the case, then the
program closes with the command requestExit();
function keyEvent(unicode, sym, modifier, isDown)
-- Check for escape key
if sym == Input.KEY_esc and isDown == true then
-- Request quit
requestExit();
end;
end;
update(dt)
The update function is a function that is called after every frame. The
parameter dt is the time that has passed since the last update call in
milliseconds.
So, this is the place where we can finally make our cube rotate. For this we
use the rotate(dt) function. It needs the id of the object that should rotate,
in this case the cubeId, and also the rate of rotation on the x, y and z-axis.
We just let it rotate on the x-axis with the value of 0.08 degree per
millisecond.
function update(dt)
rotate(cubeId, math.rad(0.08)*dt, 0, 0);
end;
draw()
The draw function is needed to draw something onto the screen. This will be
discussed later on.
function draw()
end;
Tutorial 2 - Light functions, global time and rendering text
wSample name: SampleLighting
Script source code file: sample/lighting/main.lua
The goal of this tutorial is to show you
- how to manipulate lights in your scene
- how to handle time
- how to print a text on the screen
New functions in this tutorial
setLightDiffuseColor()
getLightDiffuseColor()
setLightRange()
getLightRange()
renderText()
The first thing you might notice is that there are two new additional variables
that we’re going to use:
local globalTime = 0;
local lightRadius = 7;
In this, and also in further tutorials, we will just cover the new functions
and variables. So, if there is anything you don’t understand, have a look at
Tutorial 1.
init()
In the init() function we additionally store the id of the point light in the
variable pointLightId.
pointLightId = getChildAt(id, 2);
When you open the i3d file cubeWithPointLight.i3d, you can see that the light
is in third position. Since the function getChildAt()starts counting from 0,
the argument 2 points to the third child.
Set the light radius to an initial value of 7.
setLightRange(pointLightId, lightRadius);
keyEvent()
Here are two more keys: Key 1 and Key 2. When they are pressed, the functions
decreaseLightRadius and increaseLightRadius are called.
if sym == Input.KEY_1 and isDown == true then
decreaseLightRadius();
end;
if sym == Input.KEY_2 and isDown == true then
increaseLightRadius();
end;
increase- decreaseLightRadius()
These two functions change the variable lightRadius by 0.5 and then call the
lightRadius function with the new value.
function increaseLightRadius()
lightRadius = lightRadius + 0.5
setLightRange(pointLightId,lightRadius);
end;
update(dt)
Two variables are new here:
Why do we need a globalTime here? Well, we want the light to rotate around the
cube. Therefore, we need a value that constantly changes in corrrespondence
with time. Of course you could also increase a number every frame, but since
the framerate isn’t constant we also use the time which has passed since the
last frame and thus get an exact and constantly growing number that isn’t
affected by the different framerates. Remember that dt is the time passed
between the last and the actual frame in milliseconds. So, if dt is multiplied
by 0.001 you get seconds. We also need a distance to the center which is
stored in the variable radius.
globalTime = globalTime+dt*0.001;
local radius = 2;
This function handles the translation of the pointLight using the globalTime
and the radius 2.
setTranslation(pointLightId, math.sin(globalTime)*radius, 3, math.cos(globalTime)*radius);
We also change the color of the diffuse color of the light. This is done with
the setLightDiffuseColor() function. As arguments it uses the id, and then the
three values for red, green and blue as floats between 0 and 1. As r we use
the sinus of the globalTime.
setLightDiffuseColor(pointLightId, math.sin(globalTime), 0.4, 0.2);
When you execute the program, you see that there is a white box where the point
light is. This may seem a bit odd since you probably don’t want this cube to be
visible at all. When you open the file cubeWithPointLight.i3d and click on the
plus left of the light in the scene graph, you see that we have attached a
little cube to the light. We have done this to to give you a better visual
feedback on where the pointLight is. On top of that, it shows also another
important thing: as a child it inherits the translations of the parent and
thus also moves with it.
draw()
Like the update function, the draw function is executed after every frame.
First we store the rgb values of the pointLight using the getLightDiffuseColor()
function. It returns three different values. So be careful, you need to
separate the different variables by commas!
local r, g, b = getLightDiffuseColor(pointLightId);
Then we use the function renderText() to render the result directly onto the screen.
renderText
Description
Render text to viewport
Definition
function renderText(float x, float y, float size, string str)
Arguments
| float | x | x position [0, 1] |
| float | y | y position [0, 1] |
| float | size | font size |
| string | str | string to print |
When using renderText you can also weld parts together with the .. operator to
concatenate variables and strings like in the example.
renderText(0,0.95,0.05,"r value: " .. r);
renderText(0,0.90,0.05,"g value: " .. g);
renderText(0,0.85,0.05,"b value: " .. b);
The next line stores the value of the getLightRange() function in the
lightRadius variable
local lightRadius = getLightRange(pointLightId);
and then the variable is rendered onto the screen:
renderText(0,0.75,0.05,"LightRadius: " .. lightRadius);
With the last line we simply render the globalTime. Since it is a float we use
math.floor to get an integer.
renderText(0,0.65,0.05,"seconds: " .. math.floor(globalTime));
Tutorial 3 - Using user attributes
Sample name: SampleUserAttributes
Script source code file: sample/userAttributes/main.lua
The goal of this tutorial is to show you
- how to create user attributes
- how to access user attributes from script
- how to use the onCreate script callback
New functions in this tutorial
getUserAttribute()
setUserAttribute()
setScale()
translate()
Open sceneWithUserAttributes.i3d and main.lua which are located in
\sample\userAttributes.
Run the sample SampleUserAttributes.exe. You see three cubes with different
scales and one cube that is rotating. If you press 1,2 or 3, the related cube
is translated onto the y-axis and the number of translations is also
displayed.
If you look at sceneWithUserAttributes.i3d in the editor, you will see, that
all three cubes in the back have the same size.
Open the User Attributes window.
In the User Attributes window you see the name of your object, followed by the
user attributes and at the bottom there is the possibility to create new
attributes. Select the different objects to see what kind of user attributes
they have.
You’ll notice that both cubes in the back have two user attributes labeled
count and size. The bigger cube in the front only has an onCreate script
callback.
How to create new user attributes
To create your own attributes, just enter the name of your attribute and then
choose the according type of your attribute. You can choose whether your
attribute is a boolean, integer, float, a string or a script callback. Then
hit add and your attribute will appear.
Let’s have a look at the LUA code in main.lua. The very first line of code is
the creation of an empty array called cubeIdArray.
init()
You should be familiar with the first two lines, otherwise have a look at
Tutorial 1.
What follows is a for loop from 0 to 2 where the array cubeIdArray is filled
up with three new arrays containing the cubeIds of the three cubes.
Then the variable size gets filled with the result of the getUserAttributes
function. The getUserAttributes function needs the id of the object and the
name of the attribute as arguments. Be careful here, the name has to be exactly
the same as you have specified in the editor.
Finally, there is a check whether size has a value and then the function
setScale is used to scale the cube accordingly. Try to enter new size values
in the i3d and then see the result by running the program.
for index=0, 2 do
-- Get current cube id and store it for later
local cubeId = getChildAt(i3dRoot, index);
cubeIdArray[index] = {};
cubeIdArray[index].id = cubeId;
-- Get scale value from user attributes
local size = getUserAttribute(cubeId, "size");
if size ~= nil then
-- Set scale of current cube
setScale(cubeId, size, size, size);
end;
end;
keyEvent()
First we check if esc is pressed.
Then, if the keys 1,2 or 3 are pressed, the rest of the code is executed. The
id of the corresponding cube is stored within the variable cubeId. Then the
count of the cube is stored in the variable count by using the return value
of the function getUserAttribute. If the count isn’t nil, the count is
increased by one using the setUserAttribute function.
The setUserAttribute function can either be used to create new attributes or
to overwrite values of existing attributes. It uses the id of the object
(cubeId), the name of the attribute("count"), the data type(Integer) and the
new value as arguments(count+1). Finally, the corresponding cube is translated
onto the y-axis with the value 0.1 using the translate function.
if isDown == true then
-- Check for escape key
if sym == Input.KEY_esc then
-- Request quit
requestExit();
end;
-- Check for key 1 to 3
if sym >= Input.KEY_1 and sym <= Input.KEY_3 then
-- Get id of current cube
local cubeId = cubeIdArray[sym-Input.KEY_1].id;
-- Get count user attribute
local count = getUserAttribute(cubeId, "count");
if count ~= nil then
-- Set count user attribute
setUserAttribute(cubeId, "count", "Integer", count+1);
-- Translate cube a bit
translate(cubeId, 0, 0.1, 0);
end;
end;
end;
cubeOnCreate(id)
This function isn't called anywhere in the LUA code. So what is it used for?
As soon as the cube in the front gets loaded, its attribute script callback
causes the function cubeOnCreate to run once. The script also provides the id
of the object that caused the script callback. Be careful with the spelling,
the function in your LUA script has to be exactly the same as your
ScriptCallback in the i3d. What we do in the cubeOnCreate function is quite
simple: we store the id in the new variable rotatingCubeId.
function cubeOnCreate(id)
-- Store the id for later
rotatingCubeId = id;
end;
update(dt)
Here we first check if rotatingCubeId exists and then we rotate the cube using
the rotate function with the id we stored in the variable rotatingCubeId.
function update(dt)
-- Rotate cube3
if rotatingCubeId ~= nil then
rotate(rotatingCubeId, 0, 0.05, 0);
end;
end;
draw()
Here you can see how flexibly you can use the renderText function: using it
within a for loop, for welding text and variables as well as for calling
functions like the getUserAttributes in this case.
function draw()
for index=0, 2 do
renderText(0,0.95-index*0.05, 0.04,"Cube " .. index .. ": "
.. getUserAttribute(cubeIdArray[index].id, "count") .. " press key " .. index+1);
end;
end;
Tutorial 4 - Using timers
Sample name: SampleTimer
Script source code file: sample/timer/main.lua
The goal of this tutorial is to show you
- how to create and use timers
New functions in this tutorial
addTimer()
setTimerTime()
removeTimer()
Run the sample SampleTimer.exe. Only three lines of text are rendered. The
first shows you a random timer interval, the second is a string that says
that you can remove the timer with the space key and finally, there is a
line showing a flashing text :"Timer called".
Before we start looking at the code we should get a rough idea about what a
timer is, and what functionalities it has.
A timer is a simple object that has a certain set time and the name of the
callback function. As soon as the timer is activated, the defined time is
counted down to zero. When this happens, the timer calls the callback
function. This behavior can be used in various situations, for instance if
a trigger shouldn’t react immediately but only after a certain delay.
Open the the main.lua which is located in the directory /sample/timer.
At first, four variables are defined:
timerId = 0;
timerInterval = 0;
renderCount = 0;
timerRemoved = false;
init()
In the init function the first line calls the function setRandomTimerInterval.
This function simply generates a random value between 1000 and 5000 for the
variable timerInterval.
function setRandomTimerInterval()
timerInterval = math.random(1000, 5000);
end;
The variable timerInterval is used immediately because a new timer is created
with the line:
timerId = addTimer(timerInterval, "onTimer");
The variable timerId stores the Id of the new timer which is returned by the
function addTimer. Here is how this function is described in the
documentation:
addTimer
Description
Adds timer callback function
Definition
function addTimer(float time, string timerFunctionCallback, object instance)
Arguments
| float | time | time in milliseconds |
| string | triggerFunctionCallback | trigger function callback |
| object | instance | instance object (optional) |
Return Values
The first argument is the time in milliseconds and the second argument is the
function that is called when the time reaches zero. In this case, the variable
timerInterval defines how long the timer will wait, until it calls its callback
function. After this time, the function onTimer is called.
keyEvent()
If you hit the space key the timer is removed and the boolean timerRemoved is
switched to true.
if sym == Input.KEY_space then
-- Remove timer
removeTimer(timerId);
timerRemoved = true;
end;
onTimer()
This function is called as soon as the timer reaches zero.
The first line defines the variable renderCount to be 100. This defines the
number of frames the line "timer called" is rendered in the draw function
later on.
The second line defines a new timerInterval by calling the
setRandomTimerInterval function again.
The third line sets a new timer time with the new timerInterval time. The
setTimerTime function needs the id of the timer (timerId) and the new time
(timerInterval). After the timer reaches zero again, the onTimer function is
called again. You can remove a timer within the callback function by returning
false.
-- Timer callback
function onTimer()
renderCount = 100;
setRandomTimerInterval();
setTimerTime(timerId, timerInterval);
return true;
end;
draw()
First we have an if-else construct that handles the two states, i.e. whether
the timer is removed or not. Depending on the state of the boolean
timerRemoved, the different renderText functions are executed.
The string "timer called" is only called if the variable renderCount is not
zero. Remember that we set the renderCount to 100 in the onTimer function
which is the trigger callback of the timer. With each frame the renderCount
is decreased by 1.
Tutorial 5 - Objects with physics
Sample name: SamplePhysics
Script source code file: sample/physics/main.lua
The goal of this tutorial is to show you
- the difference between rigid body and no rigid body
- the difference between static, kinematic and dynamic objects
- how to create objects with physical behavior
Basically, there are two different types of objects available. Objects with
rigid body and objects without rigid body.
No rigid body
Objects with no rigid body are only rendered. They can be moved freely and
they don’t cause any collision, thus other objects can move through them.
These objects only use a minimum of the engine's performance. If you export
a new object from Maya without having changed the attributes, the rigid body
is activated by default. You should turn it off in the editor, when you don’t
need it.
Rigid body
Objects with rigid body behave like real objects. If another object with rigid
body tries to go trough it, there will be a collision. Since the used up power
of this behavior has to be calculated, it should only be used when necessary.
There are three rigid body types:
Static
These objects offer collision, but they can’t be moved, nor do they react to
gravity.
Kinematic
These objects offer collisions with dynamic objects and can be moved in a
predefined way. E.g. if you have a train that goes from A to B along a
predefined path and a collision occurs with a kinematic object, the train
will simply continue its movement, while the dynamic object will be pushed
away. If the same train hits a static or another kinematic object, nothing
will happen.
Dynamic
This kind of objects react dynamically to collisions and can't be moved
manually. The movement of dynamic objects is a result of external forces and
isn’t predefined.
Run SamplePhysics.exe.
Since it is self-explanatory, just open the sceneWithPhysics.i3d which is
located in /sample/physics to see how it is done.
You probably need to zoom out a bit to see the whole scene.
Select the different objects and look at the Rigid Body Type in the red marked
area. In this scene all objects are rigid bodies, but the Rigid Body Type is
different, depending on how their physics should react.
If you want to select a cube which is within the sphere of the
multi-selection-tool, you’ll first have to select something that is a bit
further away.
Try to change the Rigid Body Type of the different objects and see what
happens, when you run the program. To change it, simply open the dropdown
menu and select the desired Rigid Body Type. Hit enter, and don’t forget to
save your scene.
Instead of defining the physical behavior of an object in the editor, you
could specify these settings directly in Maya. Launch the i3d exporter and
open the attributes panel where you can see all the Rigid Body options
available. Just select the desired mesh, click Load Current and then set
the Rigid Body settings as you wish. Don’t forget to click Save Current
when you've done it. If you export the mesh as an i3d file, the rigid body
settings are already included. This method has the advantage that attributes
defined in Maya remain in the saved scene file. If you export the same scene
more than once, you might save time by defining it once in Maya instead of
redoing it every time in the editor.
Tutorial 6 - Rendering overlays
Sample name: SampleOverlay
Script source code file: sample/overlay/main.lua
The goal of this tutorial is to show you
- how overlays work
- how to create overlays
New functions in this tutorial:
createOverlay()
setOverlayColor()
renderOverlay()
When you run sampleOverlay.exe you see an overlay displayed on the screen. If
you click on it, its position changes randomly.
Open main.lua which is in /sample/overlay to take a look at the code.
First there are three variables: overlayId holds the id of the overlay,
overlayX and overlayY are used to define the position of the overlay.
init()
In the first line, the variable overlayId is filled with the result of the
function createOverlay which returns the id of the newly created overlay. The
documentation describes the createOverlay functions as follows:
createOverlay
Description
Create overlay object
Definition
function createOverlay(string overlayName, string textureFilename)
Arguments
| string | overlayName | overlay name |
| string | textureFilename | texture file name |
Take note that you have to use the relative path to your file.
overlayId = createOverlay("overlay", "sample/overlay/overlay.png");
The second line consists of the setOverlayColor function.
Try to comment it out by adding -- in front of the line. Save the script and
run the program. You see that this sample also works without the
setOverlayColor function. It isn’t needed to display an overlay, but it gives
you the possibility to change its appearance. Here is how it is described in
the documentation:
setOverlayColor
Description
Set overlay color
Definition
function setOverlayColor(integer overlayId, float red, float green, float blue, float alpha)
Arguments
| integer | overlayId | overlay id |
| float | red | red value |
| float | green | green value |
| float | blue | blue value |
| float | alpha | alpha value |
The used arguments in the example result in white with an opacity of 0.75.
setOverlayColor(overlayId, 1, 1, 1, 0.75);
Try the arguments 1, 0, 0, 0.75, to see the difference.
mouseEvent()
This function runs every time you move the mouse or click on it. If the mouse
is inactive this function isn’t executed. It provides the position of the
cursor, and the state of the buttons which can be used within the function.
We first check, if the state of a mouse button is down, which is done by the
isDown part of the if-construct. The rest of the if-construct is a simple hit
test, it checks whether the cursor is within the overlay or not. If the
if-construct returns true, you have clicked on the button. Then the overlayX
and overlayY values are overwritten with a random number between 0.05 and
0.8.
function mouseEvent(posX, posY, isDown, isUp, button)
-- Check if overlay has been clicked
if isDown and posX > overlayX and posX < overlayX+0.16 and
posY > overlayY and posY < overlayY+0.04 then
overlayX = math.random(50, 800)/1000;
overlayY = math.random(50, 900)/1000;
end;
end;
draw()
What happens here is essential : try commenting out the renderOverlay function
once. If you run the sample now, nothing will be rendered at all. This function
is needed to render an overlay. This allows you to display or hide components
(e.g. menu options) depending on the state of your program.
Here is how the function is described in the documentation:
renderOverlay
Description
Render overlay
Definition
function renderOverlay(integer overlayId, float x1, float y1, float width, float height)
Arguments
| integer | overlayId | overlay id |
| float | x | x position [0,1] |
| float | y | y position [0,1] |
| float | width | width [0,1] |
| float | height | height [0,1] |
A width and height of 1 means that the overlay has exactly the size of the screen.
Since overlayX and overlayY change when you click on the overlay, it is
instantly rendered in the new position.
function draw()
-- Render overlay
renderOverlay(overlayId, overlayX, overlayY, 0.16, 0.04);
end;
Tutorial 7 - Playing audio samples
Sample name: SampleAudio
Script source code file: sample/audio/main.lua
The goal of this tutorial is to show you
- how to use audio samples
- the difference between 2d and 3d sounds
New functions in this tutorial
createSample()
loadSample()
playSample()
Run sampleAudio.exe. Every two seconds you should hear a "pling" and if you
press space you should hear a water splash.
Open main.lua which is in /sample/audio to see the code of this example.
First there are three variables: time, sample1Id and sample2Id
init()
The first line creates a sample using the createSample function and stores the
id in the variable sample1Id. The only argument here is the name of the
sample.
sample1Id = createSample("sample1");
The sample is like an empty shell which needs filling with an audio file.
That’s what the second line does. It needs the id of the sample and the
filename as arguments. The last argument is a boolean and defines whether
your sound is 3D or not.
3D sounds can be placed in your scene. They are surrounded by a sphere which
defines the distance over which the sound can be heard. The closer you get to
the sound the louder it is.
A 2D sound simply plays at full volume when it is triggered.
For the filename you need to indicate the relative path.
loadSample(sample1Id, "sample/audio/sample1.wav", false);
keyEvent()
If you press the space key, the sample2 is played via the playSample function.
Here is how this function is described in the documentation:
playSample
Description
Play sample object
Definition
function playSample(integer objectId, integer loops, float volume, float offset)
Arguments
| integer | objectId | id of sample object |
| integer | loops | number of loops [0,n] 0 = endless looping |
| float | volume | volume [0,1] |
| float | offset | offset in milliseconds |
The offset defines from which position within the sample it starts playing.
E.g. if you define an offset of 3000, the first three seconds of your sample
are cut off the first time the sample gets played.
if sym == Input.KEY_space then
playSample(sample2Id, 1, 1, 0);
end;
update()
First the time is increased and if it is larger than 2000 milliseconds the
sample1 is played and the time is reset to 0.
function update(dt)
time = time + dt;
if time > 2000 then
playSample(sample1Id, 1, 1, 0);
time = 0;
end;
end;
Scripting
Function Reference
General Function Reference
print
Description
Print to console
Definition
print(any type arg1,any type ...)
Arguments
| any type |
arg1 |
|
| any type |
... |
|
source
Description
Source script file
Definition
source(string filename,ref environment)
Arguments
| string |
filename |
name of script file |
| ref |
environment |
ref to custom environment |
requestExit
Description
Request application to exit at the end of this frame
Definition
requestExit()
drawDebugPoint
Description
Render a point. Only use for debug rendering
Definition
drawDebugPoint(float x,float y,float z,float r,float g,float b,float a)
Arguments
| float |
x |
x position |
| float |
y |
y position |
| float |
z |
z position |
| float |
r |
red color component [0, 1] |
| float |
g |
green color component [0, 1] |
| float |
b |
blue color component [0, 1] |
| float |
a |
alpha color component [0, 1] |
drawDebugLine
Description
Render a line. Only use for debug rendering
Definition
drawDebugLine(float x0,float y0,float z0,float r0,float g0,float b0,float x1,float y1,float z1,float r1,float g1,float b1)
Arguments
| float |
x0 |
start x position |
| float |
y0 |
start y position |
| float |
z0 |
start z position |
| float |
r0 |
start red color component [0, 1] |
| float |
g0 |
start green color component [0, 1] |
| float |
b0 |
start blue color component [0, 1] |
| float |
x1 |
end x position |
| float |
y1 |
end y position |
| float |
z1 |
end z position |
| float |
r1 |
end red color component [0, 1] |
| float |
g1 |
end green color component [0, 1] |
| float |
b1 |
end blue color component [0, 1] |
drawDebugArrow
Description
Render an arrow. Only use for debug rendering
Definition
drawDebugArrow(float x,float y,float z,float dirX,float
dirY,float dirZ,float tangX,float tangY,float tangZ,float r,float
g,float b)
Arguments
| float |
x |
x position |
| float |
y |
y position |
| float |
z |
z position |
| float |
dirX |
direction x coordinate |
| float |
dirY |
direction y coordinate |
| float |
dirZ |
direction z coordinate |
| float |
tangX |
tangential x direction |
| float |
tangY |
tangential y direction |
| float |
tangZ |
tangential z direction |
| float |
r |
red color component [0, 1] |
| float |
g |
green color component [0, 1] |
| float |
b |
blue color component [0, 1] |
asciiToUtf8
Description
Converts an ascii latin1 (ISO 88859-1) encoded string to an utf8 string
Definition
asciiToUtf8(string asciiString)
Arguments
| string |
asciiString |
ascii string |
Return Values
| string |
utf8string |
utf8 encoded string |
unicodeToUtf8
Description
Converts an unicode value to an utf8 string
Definition
unicodeToUtf8(integer unicode)
Arguments
| integer |
unicode |
unicode value |
Return Values
| string |
utf8string |
utf8 encoded string representing the unicode |
utf8ToUnicode
Description
Converts an utf8 string to unicode
Definition
utf8ToUnicode(string utf8string)
Arguments
| string |
utf8string |
utf8 encoded string |
Return Values
| integer |
unicode |
unicode value |
| integer |
utf8Len |
length of the given string |
utf8Strlen
Description
Returns the length of an utf8 formated string
Definition
utf8Strlen(string utf8string)
Arguments
| string |
utf8string |
utf8 formated string |
Return Values
| integer |
length |
length of the given string |
utf8Substr
Description
Returns a sub string of an utf8 formated string
Definition
utf8Substr(string utf8string,integer startIndex,integer length)
Arguments
| string |
utf8string |
utf8 formated string |
| integer |
startIndex |
zero based start index |
| integer |
length |
maximal length of the sub string (optional) |
Return Values
| string |
subString |
utf8 formated sub string |
utf8ToUpper
Description
Returns a upper case string of an utf8 formated string
Definition
utf8ToUpper(string utf8string)
Arguments
| string |
utf8string |
utf8 formated string |
Return Values
| string |
utf8string |
upper case string of the given string |
utf8ToLower
Description
Returns a lower case string of an utf8 formated string
Definition
utf8ToLower(string utf8string)
Arguments
| string |
utf8string |
utf8 formated string |
Return Values
| string |
utf8string |
lower case string of the given string |
setFog
Description
Set fog properties
Definition
setFog(string fogType,float startDistanceOrDensity,float endDistance,float r,float g,float b)
Arguments
| string |
fogType |
fog type ("none", "linear", "exp" or "exp2") |
| float |
startDistanceOrDensity |
start distance (linear) or density (exp and exp2) |
| float |
endDistance |
end distance (linear) |
| float |
r |
red color component [0, 1] |
| float |
g |
green color component [0, 1] |
| float |
b |
blue color component [0, 1] |
wrapMousePosition
Description
Wrap mouse position
Definition
wrapMousePosition(float x,float y)
Arguments
| float |
x |
x coord [0, 1] |
| float |
y |
x coord [0, 1] |
setShowMouseCursor
Description
Set show mouse cursor
Definition
setShowMouseCursor(boolean state)
Arguments
| boolean |
state |
enable state |
setCaption
Description
Set caption
Definition
setCaption(string caption)
Arguments
| string |
caption |
application caption |
loadI3DFile
Description
Load I3D file
Definition
loadI3DFile(string filename,boolean addPhysics,boolean callOnCreate,boolean verbose)
Arguments
| string |
filename |
i3d filename |
| boolean |
addPhysics |
add node to physics |
| boolean |
callOnCreate |
call onCreate |
| boolean |
verbose |
verbose mode |
Return Values
| integer |
rootNodeId |
id of root node |
project
Description
Transform vector from world space into screen space
Definition
project(float wx,float wy,float wz)
Arguments
| float |
wx |
world space x coordinate |
| float |
wy |
world space y coordinate |
| float |
wz |
world space z coordinate |
Return Values
| float |
sx |
screen space x coordinate |
| float |
sy |
screen space y coordinate |
| float |
sz |
screen space z coordinate |
unProject
Description
Transform vector from screen space into world space
Definition
unProject(float sx,float sy,float sz)
Arguments
| float |
sx |
screen space x coordinate |
| float |
sy |
screen space y coordinate |
| float |
sz |
screen space z coordinate |
Return Values
| float |
wx |
world space x coordinate |
| float |
wy |
world space y coordinate |
| float |
wz |
world space z coordinate |
saveScreenshot
Description
Save screenshot
Definition
saveScreenshot(string filename)
Arguments
Entity Function Reference
delete
Description
Delete Entity/Object
Definition
delete(integer objectId)
Arguments
| integer |
objectId |
object id |
getClassName
Description
Get class name of object
Definition
getClassName(integer objectId)
Arguments
| integer |
objectId |
object id |
Return Values
| string |
className |
class name of object |
getClassId
Description
Get class name of object
Definition
getClassId(integer objectId)
Arguments
| integer |
objectId |
object id |
Return Values
getHasClassId
Description
Get has class id
Definition
getHasClassId(integer objectId,integer classId)
Arguments
| integer |
objectId |
object id |
| integer |
classId |
class id |
Return Values
| boolean |
hasClassId |
has class id |
Node Function Reference
getParent
Description
Get parent id
Definition
getParent(integer objectId)
Arguments
| integer |
objectId |
object id |
Return Values
| integer |
parentId |
parent id |
link
Description
Link node to another node
Definition
link(integer parentNodeId,integer childNodeId,integer index)
Arguments
| integer |
parentNodeId |
id of parent node |
| integer |
childNodeId |
id of child node |
| integer |
index |
insert index (optional) |
unlink
Description
Unlink node from parent
Definition
unlink(integer objectId)
Arguments
| integer |
objectId |
object id |
getNumOfChildren
Description
Get number of children
Definition
getNumOfChildren(integer objectId)
Arguments
| integer |
objectId |
object id |
Return Values
| integer |
numOfChildren |
number of children |
getChildAt
Description
Get child id at given index
Definition
getChildAt(integer objectId,integer index)
Arguments
| integer |
objectId |
object id |
| integer |
index |
index of child |
Return Values
| integer |
childId |
id of child node |
getChild
Description
Get child id
Definition
getChild(integer objectId,string childName)
Arguments
| integer |
objectId |
object id |
| string |
childName |
child name |
Return Values
| integer |
childId |
id of child node |
getChildIndex
Description
Get child index
Definition
getChildIndex()
Return Values
| integer |
childIndex |
index of child node |
getName
Description
Get object name
Definition
getName(integer objectId)
Arguments
| integer |
objectId |
object id |
Return Values
| string |
objectName |
object name |
setName
Description
Set object name
Definition
setName(integer objectId,string objectName)
Arguments
| integer |
objectId |
object id |
| string |
objectName |
new object name |
Node Function Reference
createTransformGroup
Description
Create transform group
Definition
createTransformGroup(string transformName)
Arguments
| string |
transformName |
name of transform object |
Return Values
| integer |
transformId |
id of transform object |
setTranslation
Description
Set translation of a transform object
Definition
setTranslation(integer transformId,float x,float y,float z)
Arguments
| integer |
transformId |
id of transform object |
| float |
x |
x value of translation |
| float |
y |
y value of translation |
| float |
z |
z value of translation |
getTranslation
Description
Get translation of a transform object
Definition
getTranslation(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| float |
x |
x value of translation |
| float |
y |
y value of translation |
| float |
z |
z value of translation |
getWorldTranslation
Description
Get world translation of a transform object
Definition
getWorldTranslation(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| float |
x |
x value of world translation |
| float |
y |
y value of world translation |
| float |
z |
z value of world translation |
localToWorld
Description
Local space to world space transformation
Definition
localToWorld(integer transformId,float x,float y,float z)
Arguments
| integer |
transformId |
id of transform object |
| float |
x |
x value of local position |
| float |
y |
y value of local position |
| float |
z |
z value of local position |
Return Values
| float |
x |
x value of world position |
| float |
y |
y value of world position |
| float |
z |
z value of world position |
localDirectionToWorld
Description
Local space to world space transformation, only direction without translation
Definition
localDirectionToWorld(integer transformId,float x,float y,float z)
Arguments
| integer |
transformId |
id of transform object |
| float |
x |
x value of local position |
| float |
y |
y value of local position |
| float |
z |
z value of local position |
Return Values
| float |
x |
x value of world direction |
| float |
y |
y value of world direction |
| float |
z |
z value of world direction |
worldToLocal
Description
World space to local space transformation
Definition
worldToLocal(integer transformId,float x,float y,float z)
Arguments
| integer |
transformId |
id of transform object |
| float |
x |
x value of world position |
| float |
y |
y value of world position |
| float |
z |
z value of world position |
Return Values
| float |
x |
x value of local direction |
| float |
y |
y value of local direction |
| float |
z |
z value of local direction |
worldDirectionToLocal
Description
World space to local space transformation, only direction without translation
Definition
worldDirectionToLocal(integer transformId,float x,float y,float z)
Arguments
| integer |
transformId |
id of transform object |
| float |
x |
x value of world direction |
| float |
y |
y value of world direction |
| float |
z |
z value of world direction |
Return Values
| float |
x |
x value of local direction |
| float |
y |
y value of local direction |
| float |
z |
z value of local direction |
localToLocal
Description
Local space to local space transformation
Definition
localToLocal(integer transformId,integer targetTransformId,float x,float y,float z)
Arguments
| integer |
transformId |
id of transform object |
| integer |
targetTransformId |
id of target transform object |
| float |
x |
x value of local direction |
| float |
y |
y value of local direction |
| float |
z |
z value of local direction |
Return Values
| float |
x |
x value of local direction |
| float |
y |
y value of local direction |
| float |
z |
z value of local direction |
localDirectionToLocal
Description
Local space to local space transformation, only direction without translation
Definition
localDirectionToLocal(integer transformId,integer targetTransformId,float x,float y,float z)
Arguments
| integer |
transformId |
id of transform object |
| integer |
targetTransformId |
id of target transform object |
| float |
x |
x value of local direction |
| float |
y |
y value of local direction |
| float |
z |
z value of local direction |
Return Values
| float |
x |
x value of local direction |
| float |
y |
y value of local direction |
| float |
z |
z value of local direction |
rotateAboutLocalAxis
Description
Rotate about local axis
Definition
rotateAboutLocalAxis(integer transformId,float rotation,float x,float y,float z)
Arguments
| integer |
transformId |
id of transform object |
| float |
rotation |
angle in radians |
| float |
x |
x value of local axis |
| float |
y |
y value of local axis |
| float |
z |
z value of local axis |
setRotation
Description
Set euler rotation of a transform object. Order ZY'X''
Definition
setRotation(integer transformId,float x,float y,float z)
Arguments
| integer |
transformId |
id of transform object |
| float |
x |
x value of rotation (radian units) |
| float |
y |
y value of rotation (radian units) |
| float |
z |
z value of rotation (radian units) |
getRotation
Description
Get rotation of a transform object
Definition
getRotation(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| float |
x |
x value of rotation (radian units) |
| float |
y |
y value of rotation (radian units) |
| float |
z |
z value of rotation (radian units) |
getWorldRotation
Description
Get world rotation of a transform object
Definition
getWorldRotation(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| float |
x |
x value of world rotation (radian units) |
| float |
y |
y value of world rotation (radian units) |
| float |
z |
z value of world rotation (radian units) |
setDirection
Description
Set the direction of an object, the positive z-axis
points towards the given direction. The y-axis lies in the
direction-up-plane.
Definition
setDirection(integer transformId,float x,float y,float z,float upX,float upY,float upZ)
Arguments
| integer |
transformId |
id of transform object |
| float |
x |
x value of direction |
| float |
y |
y value of direction |
| float |
z |
z value of direction |
| float |
upX |
x value of up vector |
| float |
upY |
y value of up vector |
| float |
upZ |
z value of up vector |
setScale
Description
Set scale of a transform object
Definition
setScale(integer transformId,float x,float y,float z)
Arguments
| integer |
transformId |
id of transform object |
| float |
x |
x value of scale |
| float |
y |
y value of scale |
| float |
z |
z value of scale |
getScale
Description
Get scale of a transform object
Definition
getScale(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| float |
x |
x value of scale |
| float |
y |
y value of scale |
| float |
z |
z value of scale |
setVisibility
Description
Set transform object visibility
Definition
setVisibility(integer transformId,boolean visibility)
Arguments
| integer |
transformId |
id of transform object |
| boolean |
visibility |
visibility state |
getVisibility
Description
Get transform object visibility
Definition
getVisibility(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| boolean |
visibility |
visibility state |
clone
Description
Clone scenegraph object
Definition
clone(id objectId,boolean groupUnderParent,boolean callOnCreate,boolean addPhysics)
Arguments
| id |
objectId |
id of scenegraph object |
| boolean |
groupUnderParent |
if true the clone will be linked to the the same parent as objectId, otherwise it is not linked to the scenegraph |
| boolean |
callOnCreate |
call onCreate |
| boolean |
addPhysics |
add node to physics |
Return Values
| id |
cloneId |
id of clone object |
getUserAttribute
Description
Get user attribute value
Definition
getUserAttribute(id objectId,string attributeName)
Arguments
| id |
objectId |
object id |
| string |
attributeName |
name of the user attribute |
Return Values
| integer/float/boolean/string |
attributeValue |
value of the user attribute, return type is the type of the attribute. Returns nil if attributeName doest not exist |
setUserAttribute
Description
Set user attribute value
Definition
setUserAttribute(id objectId,string attributeName,string typeName,integer/float/boolean/string value)
Arguments
| id |
objectId |
object id |
| string |
attributeName |
name of the user attribute |
| string |
typeName |
name of the type ("Integer", "Float", "String", "Boolean") |
| integer/float/boolean/string |
value |
value of the user attribute, must match typeName |
getAnimCharacterSet
Description
Get animation character set id
Definition
getAnimCharacterSet(id objectId)
Arguments
Return Values
| integer |
animId |
animation character set id |
setObjectMask
Description
Set object mask
Definition
setObjectMask(id objectId,integer mask)
Arguments
| id |
objectId |
object id |
| integer |
mask |
the object mask to set |
getObjectMask
Description
Get object mask
Definition
getObjectMask(id objectId)
Arguments
Return Values
| integer |
mask |
the object mask |
setClipDistance
Description
Set object clip distance
Definition
setClipDistance(id objectId,float distance)
Arguments
| id |
objectId |
object id |
| float |
distance |
clip distance |
getClipDistance
Description
Get object clip distance
Definition
getClipDistance(id objectId)
Arguments
Return Values
| float |
distance |
clip distance |
getEffectiveClipDistance
Description
Get effective object clip distance
Definition
getEffectiveClipDistance(id objectId)
Arguments
Return Values
| float |
distance |
effective clip distance |
setMinClipDistance
Description
Set minimum clip distance
Definition
setMinClipDistance(id objectId,float minDist)
Arguments
| id |
objectId |
object id |
| float |
minDist |
minimum clip distance |
getMinClipDistance
Description
Get minimum clip distance
Definition
getMinClipDistance(id objectId)
Arguments
Return Values
| float |
minDist |
minimum clip distance |
getEffectiveMinClipDistance
Description
Get effective minimum clip distance
Definition
getEffectiveMinClipDistance(id objectId)
Arguments
Return Values
| float |
minDist |
effective minimum clip distance |
Node Function Reference
getLightDiffuseColor
Description
Get diffuse color of a light
Definition
getLightDiffuseColor(integer lightId)
Arguments
| integer |
lightId |
id of light |
Return Values
| float |
r |
red value of diffuse color |
| float |
g |
green value of diffuse color |
| float |
b |
blue value of diffuse color |
setLightDiffuseColor
Description
Set diffuse color of a light
Definition
setLightDiffuseColor(integer lightId,float r,float g,float b)
Arguments
| integer |
lightId |
id of light |
| float |
r |
red value of diffuse color |
| float |
g |
green value of diffuse color |
| float |
b |
blue value of diffuse color |
getLightSpecularColor
Description
Get specular color of a light
Definition
getLightSpecularColor(integer lightId)
Arguments
| integer |
lightId |
id of light |
Return Values
| float |
r |
red value of specular color |
| float |
g |
green value of specular color |
| float |
b |
blue value of specular color |
setLightSpecularColor
Description
Set specular color of a light
Definition
setLightSpecularColor(integer lightId,float r,float g,float b)
Arguments
| integer |
lightId |
id of light |
| float |
r |
red value of specular color |
| float |
g |
green value of specular color |
| float |
b |
blue value of specular color |
getLightRange
Description
Get range of a light
Definition
getLightRange(integer lightId)
Arguments
| integer |
lightId |
id of light |
Return Values
setLightRange
Description
Set range of a light
Definition
setLightRange(integer lightId,float range)
Arguments
| integer |
lightId |
id of light |
| float |
range |
light range |
Camera Function Reference
createCamera
Description
Create camera
Definition
createCamera(string cameraName,float fovy,float nearClip,float farClip)
Arguments
| string |
cameraName |
camera name |
| float |
fovy |
field of view angle (degree) |
| float |
nearClip |
near clip |
| float |
farClip |
far clip |
setFovy
Description
Set the field of view angle
Definition
setFovy(integer cameraId,float fovy)
Arguments
| integer |
cameraId |
camera id |
| float |
fovy |
field of view angle (degree) |
getFovy
Description
Get the field of view angle
Definition
getFovy(integer cameraId)
Arguments
| integer |
cameraId |
camera id |
Return Values
| float |
fovy |
field of view angle (degree) |
setNearClip
Description
Set the near clip distance
Definition
setNearClip(integer cameraId,float nearClip)
Arguments
| integer |
cameraId |
camera id |
| float |
nearClip |
near clip distance |
getNearClip
Description
Set the near clip distance
Definition
getNearClip(integer cameraId)
Arguments
| integer |
cameraId |
camera id |
Return Values
| float |
nearClip |
near clip distance |
setFarClip
Description
Set the far clip distance
Definition
setFarClip(integer cameraId,float farClip)
Arguments
| integer |
cameraId |
camera id |
| float |
farClip |
far clip distance |
getFarClip
Description
Get the far clip distance
Definition
getFarClip(integer cameraId)
Arguments
| integer |
cameraId |
camera id |
Return Values
| float |
farClip |
far clip distance |
aimCamera
Description
Aim camera (spring/damper)
Definition
aimCamera(integer cameraId,float x,float y,float z,float distance,float dt,float springStrength)
Arguments
| integer |
cameraId |
camera id |
| float |
x |
target x coordinate |
| float |
y |
target y coordinate |
| float |
z |
target z coordinate |
| float |
distance |
distance from target |
| float |
dt |
delta time |
| float |
springStrength |
spring strength |
Shape Function Reference
getGeometry
Description
Get shape geometry id
Definition
getGeometry(integer shapeId)
Arguments
Return Values
| integer |
geometryId |
geometry id |
setShaderParameter
Description
Set shader parameter
Definition
setShaderParameter(integer shapeId,string parameterName,float x,float y,float z,float w,boolean shared)
Arguments
| integer |
shapeId |
shape id |
| string |
parameterName |
the name of the parameter |
| float |
x |
x value |
| float |
y |
y value |
| float |
z |
z value |
| float |
w |
w value |
| boolean |
shared |
if true, the value is applied to all shapes with the same material |
getShaderParameter
Description
Get shader parameter
Definition
getShaderParameter(integer shapeId,string parameterName)
Arguments
| integer |
shapeId |
shape id |
| string |
parameterName |
the name of the parameter |
Return Values
| float |
x |
x value |
| float |
y |
y value |
| float |
z |
z value |
| float |
w |
w value |
getHasShaderParameter
Description
Get hash shader parameter
Definition
getHasShaderParameter(integer shapeId,string parameterName)
Arguments
| integer |
shapeId |
shape id |
| string |
parameterName |
the name of the parameter |
Return Values
| boolean |
hasParam |
has parameter |
setReflectionMapObjectMask
Description
Set reflection object mask
Definition
setReflectionMapObjectMask(integer shapeId,integer mask,boolean isShared)
Arguments
| integer |
shapeId |
shape id |
| integer |
mask |
the mask |
| boolean |
isShared |
is shared parameter |
getNumMaterials
Description
Get number of materials
Definition
getNumMaterials(integer shapeId)
Arguments
Return Values
| integer |
numMaterials |
number of materials |
getMaterial
Description
Get material by index
Definition
getMaterial(integer shapeId,integer materialIdx)
Arguments
| integer |
shapeId |
shape id |
| integer |
materialIdx |
index of attached material |
Return Values
| integer |
materialId |
id of material |
setMaterial
Description
Set material by index
Definition
setMaterial(integer shapeId,integer materialId,integer material index)
Arguments
| integer |
shapeId |
shape id |
| integer |
materialId |
id of material |
| integer |
material index |
index of material |
getSplitType
Description
Get split type
Definition
getSplitType(integer shapeId)
Arguments
Return Values
| integer |
splitType |
split type |
createFillPlaneShape
Description
Creates a fill plane shape based on shapeId
Definition
createFillPlaneShape(integer shapeId,string
shapeName,float volume,float deltaMax,float maxSurfaceAngle,float
maxPhysicalSurfaceAngle,float maxSubDivEdgeLength,boolean
createSidePlanes)
Arguments
| integer |
shapeId |
shape id |
| string |
shapeName |
name of shape |
| float |
volume |
volume of the fill plane shape (m^3) |
| float |
deltaMax |
value of how much the fill plane can be excessed (in meter) |
| float |
maxSurfaceAngle |
maximum surface angle (geometric tuning value in radian) |
| float |
maxPhysicalSurfaceAngle |
maximum physical surface angle (this is usually material dependent in radian) |
| float |
maxSubDivEdgeLength |
defines the maximum edge-length of the subdivision surface (in meter) |
| boolean |
createSidePlanes |
state of side plane creation |
Return Values
| integer |
fillPlaneShapeId |
id of fill plane shape type |
fillPlaneAdd
Description
Add material/volume to a fill plane
Definition
fillPlaneAdd(integer fillPlaneId,float dTvolume,float
x,float y,float z,float dx1,float dy1,float dz1,float dx2,float
dy2,float dz2)
Arguments
| integer |
fillPlaneId |
id of fill plane |
| float |
dTvolume |
delta volume (m^3) |
| float |
x |
x position in world space |
| float |
y |
y position in world space |
| float |
z |
z position in world space |
| float |
dx1 |
frame x position in world space |
| float |
dy1 |
frame y position in world space |
| float |
dz1 |
frame z position in world space |
| float |
dx2 |
frame x position in world space |
| float |
dy2 |
frame y position in world space |
| float |
dz2 |
frame z position in world space |
findPolyline
Description
find nearest polyline
Definition
findPolyline(integer fillPlaneId,float x,float z)
Arguments
| integer |
fillPlaneId |
id of fill plane |
| float |
x |
x position in local space |
| float |
z |
z position in local space |
Return Values
| integer |
polyLineId |
id of polyLineId |
setPolylineTranslation
Description
translate polylines
Definition
setPolylineTranslation(integer fillPlaneId,integer polyLineIdx,float dx,float dz)
Arguments
| integer |
fillPlaneId |
id of fill plane |
| integer |
polyLineIdx |
polyline index |
| float |
dx |
x value of translation |
| float |
dz |
z value of translation |
getFillPlaneHeightAtLocalPos
Description
Get the fill plane height at a specific position
Definition
getFillPlaneHeightAtLocalPos(integer fillPlaneId,float x,float z)
Arguments
| integer |
fillPlaneId |
id of fill plane |
| float |
x |
x value of position |
| float |
z |
x value of position |
setFillPlaneMaxPhysicalSurfaceAngle
Description
Set fill plane physical surface angle
Definition
setFillPlaneMaxPhysicalSurfaceAngle(integer fillPlaneId,float physicalSurfAngle)
Arguments
| integer |
fillPlaneId |
id of fill plane |
| float |
physicalSurfAngle |
value of physical surface angle (in radian) |
Particle System Function Reference
setEmittingState
Description
Set whether the particle system should emit new particles
Definition
setEmittingState(integer particleSystemId,boolean state)
Arguments
| integer |
particleSystemId |
particle system id |
| boolean |
state |
if true, new particles are emitted |
setEmitCountScale
Description
Set particle system count scale
Definition
setEmitCountScale(integer particleSystemId,float countScale)
Arguments
| integer |
particleSystemId |
particle system id |
| float |
countScale |
value of count scale |
resetNumOfEmittedParticles
Description
Resets the counter of emitted particles. This is used if the maxEmit attribute is set for the particle system.
Definition
resetNumOfEmittedParticles(integer particleSystemId)
Arguments
| integer |
particleSystemId |
particle system id |
resetEmitStartTimer
Description
Resets the start timer of emitted particles.
Definition
resetEmitStartTimer(integer particleSystemId,float timer scale)
Arguments
| integer |
particleSystemId |
particle system id |
| float |
timer scale |
time scale (default is 1) |
resetEmitStopTimer
Description
Resets the stop timer of emitted particles.
Definition
resetEmitStopTimer(integer particleSystemId,float timer scale)
Arguments
| integer |
particleSystemId |
particle system id |
| float |
timer scale |
time scale (default is 1) |
getEmitStartTime
Description
Get emitter starting time.
Definition
getEmitStartTime(integer particleSystemId)
Arguments
| integer |
particleSystemId |
particle system id |
Return Values
| float |
emitStartTime |
emitter start time |
setEmitStartTime
Description
Set emitter starting time.
Definition
setEmitStartTime(integer particleSystemId,float emitStartTime)
Arguments
| integer |
particleSystemId |
particle system id |
| float |
emitStartTime |
emitter start time |
getEmitStopTime
Description
Get emitter stop time.
Definition
getEmitStopTime(integer particleSystemId)
Arguments
| integer |
particleSystemId |
particle system id |
Return Values
| float |
emitStopTime |
emitter stop time |
setEmitStopTime
Description
Set emitter stop time.
Definition
setEmitStopTime(integer particleSystemId,float emitStopTime)
Arguments
| integer |
particleSystemId |
particle system id |
| float |
emitStopTime |
emitter stop time |
setParticleSystemTimeScale
Description
Sets the time scale for the particle simulation.
Definition
setParticleSystemTimeScale(integer particleSystemId,float timeScale)
Arguments
| integer |
particleSystemId |
particle system id |
| float |
timeScale |
time scale for the particle simulation |
getParticleSystemLifespan
Description
Get particle system life span.
Definition
getParticleSystemLifespan(integer particleSystemId)
Arguments
| integer |
particleSystemId |
particle system id |
Return Values
| float |
lifeSpan |
value of life span |
setParticleSystemLifespan
Description
Set particle system life span.
Definition
setParticleSystemLifespan(integer particleSystemId,float lifeSpan,boolean keepBlendTimes)
Arguments
| integer |
particleSystemId |
particle system id |
| float |
lifeSpan |
value of life span |
| boolean |
keepBlendTimes |
if true, blend times are kept |
setParticleSystemLifespan
Description
Set particle system life span.
Definition
setParticleSystemLifespan(integer particleSystemId,float lifeSpan,boolean keepBlendTimes)
Arguments
| integer |
particleSystemId |
particle system id |
| float |
lifeSpan |
value of life span |
| boolean |
keepBlendTimes |
if true, blend times are kept |
getParticleSystemAverageSpeed
Description
Get particle system average speed.
Definition
getParticleSystemAverageSpeed(integer particleSystemId)
Arguments
| integer |
particleSystemId |
particle system id |
Return Values
| float |
normalSpeed |
value of normal speed |
| float |
tangentSpeed |
value of tangential speed |
getEmitterShape
Description
Returns the emitter shape of the particle system
Definition
getEmitterShape(integer particleSystemId)
Arguments
| integer |
particleSystemId |
particle system id |
Return Values
| integer |
shapeId |
id of the emitter shape |
setEmitterShape
Description
Sets the emitter shape of the particle system
Definition
setEmitterShape(integer particleSystemId,integer shapeId)
Arguments
| integer |
particleSystemId |
particle system id |
| integer |
shapeId |
id of the emitter shape |
addParticleSystemSimulationTime
Description
add particle system simulation time
Definition
addParticleSystemSimulationTime(integer particleSystemId,float dt)
Arguments
| integer |
particleSystemId |
particle system id |
| float |
dt |
value of simulation time to be added |
Physics Function Reference
simulatePhysics
Description
Enable/disable physics simulation
Definition
simulatePhysics(boolean state)
Arguments
| boolean |
state |
enable simulation state |
simulatePhysicsTimeScale
Description
Time scale of physics simulation
Definition
simulatePhysicsTimeScale(float scale)
Arguments
| float |
scale |
physics time scale |
createCCT
Description
Create character controller (y axis capsule based)
Definition
createCCT(integer transformId,float radius,float
height,float stepOffset,float slopeLimit,float skinWidth,integer
collisionMask,float mass)
Arguments
| integer |
transformId |
id of transform object |
| float |
radius |
physics time scale |
| float |
height |
physics time scale |
| float |
stepOffset |
physics time scale |
| float |
slopeLimit |
physics time scale |
| float |
skinWidth |
skin width |
| integer |
collisionMask |
collision mask |
| float |
mass |
character mass [kg] |
Return Values
| integer |
characterIndex |
character index numbe |
moveCCT
Description
Enqueue character movement
Definition
moveCCT(integer characterIndex,float x,float y,float z,float collisionMasks)
Arguments
| integer |
characterIndex |
character index number |
| float |
x |
x value |
| float |
y |
y value |
| float |
z |
z value |
| float |
collisionMasks |
collision masks |
removeCCT
Description
Remove character controller
Definition
removeCCT(integer characterIndex)
Arguments
| integer |
characterIndex |
character index number |
getCCTCollisionFlags
Description
Get character controller collision flags
Definition
getCCTCollisionFlags(integer characterIndex)
Arguments
| integer |
characterIndex |
character index number |
Return Values
| boolean |
side |
side flag |
| boolean |
up |
up flag |
| boolean |
down |
down flag |
raycastAll
Description
Raycast objects, see raycast callback function
Definition
raycastAll(float x,float y,float z,float nx,float
ny,float nz,string raycastFunctionCallback,float maxDistance,object
targetObject,integer collisionMask,boolean generateNormal)
Arguments
| float |
x |
origin x |
| float |
y |
origin y |
| float |
z |
origin z |
| float |
nx |
direction x |
| float |
ny |
direction y |
| float |
nz |
direction z |
| string |
raycastFunctionCallback |
raycast function callback. See raycast callback function function |
| float |
maxDistance |
max distance |
| object |
targetObject |
target object (optional), the callback function is called as a member function of targetObject (default nil) |
| integer |
collisionMask |
collision mask (optional), the mask to filter colliding objects (default 0xFFFFFFFF) |
| boolean |
generateNormal |
generate normal (optional), if set and true, the
normal at the collision point is passed as arguments to the callback
function (default false) |
Return Values
| integer |
numShapes |
number of shapes hit |
raycastClosest
Description
Raycast closest object, see raycast callback function
Definition
raycastClosest(float x,float y,float z,float nx,float
ny,float nz,string raycastFunctionCallback,float maxDistance,object
targetObject,integer collisionMask,boolean generateNormal)
Arguments
| float |
x |
origin x |
| float |
y |
origin y |
| float |
z |
origin z |
| float |
nx |
direction x |
| float |
ny |
direction y |
| float |
nz |
direction z |
| string |
raycastFunctionCallback |
raycast function callback. See raycast callback function function |
| float |
maxDistance |
max distance |
| object |
targetObject |
target object (optional), the callback function is called as a member function of targetObject (default nil) |
| integer |
collisionMask |
collision mask (optional), the mask to filter colliding objects (default 0xFFFFFFFF) |
| boolean |
generateNormal |
generate normal (optional), if set and true, the
normal at the collision point is passed as arguments to the callback
function (default false) |
Return Values
| integer |
numShapes |
number of shapes hit |
overlapSphere
Description
Overlap sphere objects
Definition
overlapSphere(float x,float y,float z,float radius,string overlapFunctionCallback,object targetObject)
Arguments
| float |
x |
center x |
| float |
y |
center y |
| float |
z |
center z |
| float |
radius |
radius |
| string |
overlapFunctionCallback |
overlap function callback |
| object |
targetObject |
target object (optional), the callback function is called as a member function of targetObject |
Return Values
| integer |
numShapes |
number of shape overlaps |
overlapBox
Description
Overlap box objects
Definition
overlapBox(float x,float y,float z,float rx,float
ry,float rz,float ex,float ey,float ez,string
overlapFunctionCallback,object targetObject)
Arguments
| float |
x |
center x |
| float |
y |
center y |
| float |
z |
center z |
| float |
rx |
rotation x |
| float |
ry |
rotation y |
| float |
rz |
rotation z |
| float |
ex |
extent x |
| float |
ey |
extent y |
| float |
ez |
extent z |
| string |
overlapFunctionCallback |
overlap function callback |
| object |
targetObject |
target object (optional), the callback function is called as a member function of targetObject |
Return Values
| integer |
numShapes |
number of shape overlaps |
addForce
Description
Add force to object
Definition
addForce(integer transformId,float forceX,float
forceY,float forceZ,float positionX,float positionY,float
positionZ,boolean isPositionLocal)
Arguments
| integer |
transformId |
id of transform object |
| float |
forceX |
force x |
| float |
forceY |
force y |
| float |
forceZ |
force z |
| float |
positionX |
position x |
| float |
positionY |
position y |
| float |
positionZ |
position z |
| boolean |
isPositionLocal |
is position local |
addImpulse
Description
Add impulse to object
Definition
addImpulse(integer transformId,float impulseX,float
impulseY,float impulseZ,float positionX,float positionY,float
positionZ,boolean isPositionLocal)
Arguments
| integer |
transformId |
id of transform object |
| float |
impulseX |
impulse x |
| float |
impulseY |
impulse y |
| float |
impulseZ |
impulse z |
| float |
positionX |
position x |
| float |
positionY |
position y |
| float |
positionZ |
position z |
| boolean |
isPositionLocal |
is position local |
setJointDrive
Description
Set joint drive. Drives orientation if position drive or angular velocity if velocity drive.
Definition
setJointDrive(integer transformId,boolean isLinear,boolean isPosition,float valueX,float valueY,float valueZ,float angle)
Arguments
| integer |
transformId |
id of transform object |
| boolean |
isLinear |
is linear |
| boolean |
isPosition |
is position |
| float |
valueX |
orientation axis x or angular velocity x |
| float |
valueY |
orientation axis y or angular velocity y |
| float |
valueZ |
orientation axis z or angular velocity z |
| float |
angle |
orientation angle |
createWheelShape
Description
Create wheel shape
Definition
createWheelShape(integer transformId,float
positionX,float positionY,float positionZ,float radius,float
suspensionTravel,float spring,float damper,float mass,integer
collisionMask,integer wheelShapeIndex)
Arguments
| integer |
transformId |
id of transform object |
| float |
positionX |
position x |
| float |
positionY |
position y |
| float |
positionZ |
position z |
| float |
radius |
radius |
| float |
suspensionTravel |
suspension travel |
| float |
spring |
spring |
| float |
damper |
damper |
| float |
mass |
mass |
| integer |
collisionMask |
collision mask |
| integer |
wheelShapeIndex |
wheel shape index |
Return Values
| integer |
wheelShapeIndex |
wheel shape index |
setWheelShapeProps
Description
Set wheel shape properties
Definition
setWheelShapeProps(integer transformId,integer wheelShapeIndex,float motorTorque,float brakeTorque,float steerAngle)
Arguments
| integer |
transformId |
id of transform object |
| integer |
wheelShapeIndex |
wheel shape index |
| float |
motorTorque |
motor torque |
| float |
brakeTorque |
brake torque |
| float |
steerAngle |
steer angle |
setWheelShapeTireFriction
Description
Set wheel shape tire friction
Definition
setWheelShapeTireFriction(integer transformId,integer
wheelShapeIndex,float maxLongStiffness,float maxLatStiffness,float
maxLatStiffnessTireLoad,float frictionMultiplier)
Arguments
| integer |
transformId |
id of transform object |
| integer |
wheelShapeIndex |
wheel shape index |
| float |
maxLongStiffness |
longitudal stiffness [t/rad] (force per slip ratio) |
| float |
maxLatStiffness |
peak lateral stiffness [t/rad] (force per slip angle) |
| float |
maxLatStiffnessTireLoad |
tire load at which the peak lateral stiffness is reached [t] |
| float |
frictionMultiplier |
friction multiplier modeling ground friction properties |
setWheelShapeForcePoint
Description
Set wheel shape force point
Definition
setWheelShapeForcePoint(integer transformId,integer wheelShapeIndex,float positionX,float positionY,float positionZ)
Arguments
| integer |
transformId |
id of transform object |
| integer |
wheelShapeIndex |
wheel shape index |
| float |
positionX |
position x |
| float |
positionY |
position y |
| float |
positionZ |
position z |
getWheelShapeAxleSpeed
Description
Get wheel shape axle speed
Definition
getWheelShapeAxleSpeed(integer transformId,integer wheelShapeIndex)
Arguments
| integer |
transformId |
id of transform object |
| integer |
wheelShapeIndex |
wheel shape index |
Return Values
| float |
axleSpeed |
axle speed |
getWheelShapeContactPoint
Description
Get wheel shape contact point
Definition
getWheelShapeContactPoint(integer transformId,integer wheelShapeIndex)
Arguments
| integer |
transformId |
id of transform object |
| integer |
wheelShapeIndex |
wheel shape index |
Return Values
| float |
positionX |
position x |
| float |
positionY |
position y |
| float |
positionZ |
position z |
| float |
contactSkinWidth |
skinWidth of contact object |
getWheelShapePosition
Description
Get wheel shape contact point
Definition
getWheelShapePosition(integer transformId,integer wheelShapeIndex)
Arguments
| integer |
transformId |
id of transform object |
| integer |
wheelShapeIndex |
wheel shape index |
Return Values
| float |
positionX |
position x |
| float |
positionY |
position y |
| float |
positionZ |
position z |
| float |
rotation |
rotation |
computeWheelShapeTireForces
Description
Calculate wheel shape tire forces
Definition
computeWheelShapeTireForces(integer transformId,integer wheelShapeIndex,float longSlipRatio,float latSlipAngle,float tireLoad)
Arguments
| integer |
transformId |
id of transform object |
| integer |
wheelShapeIndex |
wheel shape index |
| float |
longSlipRatio |
longitudal slip ratio |
| float |
latSlipAngle |
lateral slip angle |
| float |
tireLoad |
tire load |
Return Values
| float |
longForce |
longitudal force |
| float |
latForce |
lateral force |
getWheelShapeContactObject
Description
Get wheel shape contact object
Definition
getWheelShapeContactObject(integer transformId,integer wheelShapeIndex)
Arguments
| integer |
transformId |
id of transform object |
| integer |
wheelShapeIndex |
wheel shape index |
Return Values
| integer |
wheelShapeContactObject |
wheel shape contact object |
getWheelShapeContactNormal
Description
Get wheel shape contact normal
Definition
getWheelShapeContactNormal(integer transformId,integer wheelShapeIndex)
Arguments
| integer |
transformId |
id of transform object |
| integer |
wheelShapeIndex |
wheel shape index |
Return Values
| float |
x |
x value of contact normal |
| float |
y |
y value of contact normal |
| float |
z |
z value of contact normal |
getWheelShapeContactForce
Description
Get wheel shape contact force
Definition
getWheelShapeContactForce(integer transformId,integer wheelShapeIndex)
Arguments
| integer |
transformId |
id of transform object |
| integer |
wheelShapeIndex |
wheel shape index |
Return Values
| float |
contactForce |
contact force |
getWheelShapeSlip
Description
Get wheel shape slip
Definition
getWheelShapeSlip(integer transformId,integer wheelShapeIndex)
Arguments
| integer |
transformId |
id of transform object |
| integer |
wheelShapeIndex |
wheel shape index |
Return Values
| float |
wheelShapeSlip |
longitudal slip |
| float |
wheelShapeSlip |
lateral slip |
getLinearVelocity
Description
Get linear velocity of transform object
Definition
getLinearVelocity(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| float |
velocityX |
x value of velocity |
| float |
velocityY |
y value of velocity |
| float |
velocityZ |
z value of velocity |
setLinearVelocity
Description
Set linear velocity of transform object
Definition
setLinearVelocity(integer transformId,float velocityX,float velocityY,float velocityZ)
Arguments
| integer |
transformId |
id of transform object |
| float |
velocityX |
x value of velocity |
| float |
velocityY |
y value of velocity |
| float |
velocityZ |
z value of velocity |
getAngularVelocity
Description
Get angular velocity of transform object
Definition
getAngularVelocity(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| float |
velocityX |
x value of angular velocity |
| float |
velocityY |
y value of angular velocity |
| float |
velocityZ |
z value of angular velocity |
setAngularVelocity
Description
Set angular velocity of transform object
Definition
setAngularVelocity(integer transformId,float velocityX,float velocityY,float velocityZ)
Arguments
| integer |
transformId |
id of transform object |
| float |
velocityX |
x value of angular velocity |
| float |
velocityY |
y value of angular velocity |
| float |
velocityZ |
z value of angular velocity |
getVelocityAtWorldPos
Description
Get velocity at world position of transform object
Definition
getVelocityAtWorldPos(integer transformId,float positionX,float positionY,float positionZ)
Arguments
| integer |
transformId |
id of transform object |
| float |
positionX |
x value of world position |
| float |
positionY |
y value of world position |
| float |
positionZ |
z value of world position |
Return Values
| float |
velocityX |
x value of velocity |
| float |
velocityY |
y value of velocity |
| float |
velocityZ |
z value of velocity |
getVelocityAtLocalPos
Description
Get velocity at local position of transform object
Definition
getVelocityAtLocalPos(integer transformId,float positionX,float positionY,float positionZ)
Arguments
| integer |
transformId |
id of transform object |
| float |
positionX |
x value of local position |
| float |
positionY |
y value of local position |
| float |
positionZ |
z value of local position |
Return Values
| float |
velocityX |
x value of velocity |
| float |
velocityY |
y value of velocity |
| float |
velocityZ |
z value of velocity |
addVehicleLink
Description
Add vehicle link
Definition
addVehicleLink(integer transformId,integer transformId2)
Arguments
| integer |
transformId |
id of transform object |
| integer |
transformId2 |
id of second transform object |
addDifferential
Description
Add differential
Definition
addDifferential(integer transformId,integer index0,boolean isWheel0,integer index1,boolean isWheel1,float ratio,float bias)
Arguments
| integer |
transformId |
id of transform object |
| integer |
index0 |
|
| boolean |
isWheel0 |
is wheel state |
| integer |
index1 |
|
| boolean |
isWheel1 |
is wheel state |
| float |
ratio |
ratio |
| float |
bias |
bias |
updateDifferential
Description
update differential
Definition
updateDifferential(integer transformId,integer index,float ratio,float bias)
Arguments
| integer |
transformId |
id of transform object |
| integer |
index |
|
| float |
ratio |
ratio |
| float |
bias |
bias |
removeAllDifferentials
Description
remove all differential
Definition
removeAllDifferentials(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
setVehicleProps
Description
Set vehicle properties
Definition
setVehicleProps(integer transformId,float torque,float maxDriveSpeed,float gearRatio,float maxClutchTorque)
Arguments
| integer |
transformId |
id of transform object |
| float |
torque |
torque |
| float |
maxDriveSpeed |
maximum driving speed |
| float |
gearRatio |
gear ratio |
| float |
maxClutchTorque |
maximum clutch torque |
getMotorRotationSpeed
Description
Set vehicle properties
Definition
getMotorRotationSpeed(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| float |
motorRotSpeed |
motor rotation speed |
| float |
clutchRotSpeed |
clutch rotation speed |
| float |
motorLoad |
maximum motor load |
setRigidBodyType
Description
Set rigid body type
Definition
setRigidBodyType(integer transformId,string type)
Arguments
| integer |
transformId |
id of transform object |
| string |
type |
rigid body type ("Static", "Dynamic", "Kinematic" or "NoRigidBody") |
getRigidBodyType
Description
Get rigid body type
Definition
getRigidBodyType(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| string |
type |
rigid body type ("Static", "Dynamic", "Kinematic" or "NoRigidBody") |
addToPhysics
Description
Add to physics
Definition
addToPhysics(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
removeFromPhysics
Description
Remove from physics
Definition
removeFromPhysics(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
setCollisionMask
Description
Set collision mask
Definition
setCollisionMask(integer transformId,integer mask)
Arguments
| integer |
transformId |
id of transform object |
| integer |
mask |
collision mask |
getCollisionMask
Description
Get collision mask
Definition
getCollisionMask(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| integer |
mask |
collision mask |
getCenterOfMass
Description
Get center of mass
Definition
getCenterOfMass(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| float |
x |
x position |
| float |
y |
y position |
| float |
z |
z position |
setCenterOfMass
Description
Set center of mass
Definition
setCenterOfMass(integer transformId,float x,float y,float z)
Arguments
| integer |
transformId |
id of transform object |
| float |
x |
x position |
| float |
y |
y position |
| float |
z |
z position |
setSolverIterationCount
Description
Set solver iteration count
Definition
setSolverIterationCount(integer transformId,integer count)
Arguments
| integer |
transformId |
id of transform object |
| integer |
count |
number of iteration |
setMass
Description
Set mass
Definition
setMass(integer transformId,float mass)
Arguments
| integer |
transformId |
id of transform object |
| float |
mass |
mass |
getMass
Description
Get mass
Definition
getMass(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
getDensity
Description
Get density
Definition
getDensity(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
getVolume
Description
Get volume
Definition
getVolume(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
getLinearDamping
Description
Get linear damping
Definition
getLinearDamping(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| float |
linearDamping |
linear damping |
setLinearDamping
Description
Set linear damping
Definition
setLinearDamping(integer transformId,float linearDamping)
Arguments
| integer |
transformId |
id of transform object |
| float |
linearDamping |
linear damping |
getAngularDamping
Description
Get angular damping
Definition
getAngularDamping(integer transformId)
Arguments
| integer |
transformId |
id of transform object |
Return Values
| float |
angularDamping |
angular damping |
setAngularDamping
Description
Set angular damping
Definition
setAngularDamping(integer transformId,float angularDamping)
Arguments
| integer |
transformId |
id of transform object |
| float |
angularDamping |
angular damping |
Spline Function Reference
getSplinePosition
Description
Get spline position
Definition
getSplinePosition(integer shapeId,float time)
Arguments
| integer |
shapeId |
id of curve shape object |
| float |
time |
time [0,1] |
Return Values
| float |
x |
x coordinate |
| float |
y |
y coordinate |
| float |
z |
z coordinate |
getSplineOrientation
Description
Get spline orientation
Definition
getSplineOrientation(integer shapeId,float time,float upDirX,float upDirY,float upDirZ)
Arguments
| integer |
shapeId |
id of curve shape object |
| float |
time |
time [0,1] |
| float |
upDirX |
up direction x coordinate |
| float |
upDirY |
up direction y coordinate |
| float |
upDirZ |
up direction z coordinate |
Return Values
| float |
rx |
x rotation |
| float |
ry |
y rotation |
| float |
rz |
z rotation |
getSplineLength
Description
Get spline length
Definition
getSplineLength(integer shapeId)
Arguments
| integer |
shapeId |
id of curve shape object |
Return Values
| float |
length |
length of spline |
getSplineNumOfCV
Description
Get number of spline control vertices
Definition
getSplineNumOfCV(integer shapeId)
Arguments
| integer |
shapeId |
id of curve shape object |
Return Values
| integer |
num |
number of spline control vertices |
getSplineCV
Description
Get spline control vertex
Definition
getSplineCV(integer shapeId,integer index)
Arguments
| integer |
shapeId |
id of curve shape object |
| integer |
index |
control vertex index |
Return Values
| float |
x |
control vertex x coordinate |
| float |
y |
control vertex y coordinate |
| float |
z |
control vertex z coordinate |
Animation Function Reference
getAnimCharacterSet
Description
Returns the character set driving the transform group
Definition
getAnimCharacterSet(integer transformId)
Arguments
| integer |
transformId |
id of transform group |
Return Values
| integer |
id |
id of character set object, 0 if no character set is assigned to the transform group |
enableAnimTrack
Description
Enable animation track
Definition
enableAnimTrack(integer characterSetId,integer track)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
track |
track number |
disableAnimTrack
Description
Disable animation track
Definition
disableAnimTrack(integer characterSetId,integer track)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
track |
track number |
isAnimTrackEnabled
Description
Is animation track enabled
Definition
isAnimTrackEnabled(integer characterSetId,integer track)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
track |
track number |
Return Values
| boolean |
state |
enable state |
setAnimTrackSpeedScale
Description
Set animation track speed scale
Definition
setAnimTrackSpeedScale(integer characterSetId,integer track,float speedScale)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
track |
track number |
| float |
speedScale |
speed scale |
setAnimTrackLoopState
Description
Set animation track loop state
Definition
setAnimTrackLoopState(integer characterSetId,integer track,boolean loopState)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
track |
track number |
| boolean |
loopState |
loop state |
setAnimTrackTime
Description
Set animation track time
Definition
setAnimTrackTime(integer characterSetId,integer track,float time,boolean immediateUpdate (optional))
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
track |
track number |
| float |
time |
time |
| boolean |
immediateUpdate (optional) |
if set to true, the animation is updated
immediately, otherwise it is only updated the next frame. For
performance reasons, only set this to true if you really need the
immediate update. |
getAnimTrackTime
Description
Get animation track loop state
Definition
getAnimTrackTime(integer characterSetId,integer track)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
track |
track number |
Return Values
getAnimClipDuration
Description
Get the duration of the clip at the given index
Definition
getAnimClipDuration(integer characterSetId,integer index)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
index |
clip index |
Return Values
setAnimTrackBlendWeight
Description
Set animation track blend weight
Definition
setAnimTrackBlendWeight(integer characterSetId,integer track,float weight)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
track |
track number |
| float |
weight |
blend weight |
getAnimTrackBlendWeight
Description
Get animation track blend weight
Definition
getAnimTrackBlendWeight(integer characterSetId,integer track)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
track |
track number |
Return Values
| float |
weight |
blend weight |
getAnimClipIndex
Description
Returns the index of the clip with the given name
Definition
getAnimClipIndex(integer characterSetId,string clipName)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| string |
clipName |
the name of the clip to find |
Return Values
| integer |
index |
index of the clip, -1 if clip was not found |
assignAnimTrackClip
Description
Assign clip to animation track
Definition
assignAnimTrackClip(integer characterSetId,integer track,float clipIndex)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
track |
track number |
| float |
clipIndex |
clip index number |
isAnimTrackClipAssigned
Description
Is clip assigned to animation track
Definition
isAnimTrackClipAssigned(integer characterSetId,integer track)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
track |
track number |
Return Values
| boolean |
state |
assigned state |
getAnimTrackAssignedClip
Description
Get animation track assigned clip index number
Definition
getAnimTrackAssignedClip(integer characterSetId,integer track)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
track |
track number |
Return Values
| integer |
clipIndex |
clip index number |
clearAnimTrackClip
Description
Clear animation track clip assignment
Definition
clearAnimTrackClip(integer characterSetId,integer track)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
| integer |
track |
track number |
getAnimNumOfClips
Description
Get number of clips
Definition
getAnimNumOfClips(integer characterSetId)
Arguments
| integer |
characterSetId |
id of CharacterSet object |
Return Values
| integer |
clips |
number of clips |
Overlays Function Reference
createImageOverlay
Description
Create overlay object
Definition
createImageOverlay(string textureFilename)
Arguments
| string |
textureFilename |
texture file name |
setOverlayColor
Description
Set overlay color
Definition
setOverlayColor(integer overlayId,float red,float green,float blue,float alpha)
Arguments
| integer |
overlayId |
texture file name |
| float |
red |
red value |
| float |
green |
green value |
| float |
blue |
blue value |
| float |
alpha |
alpha value |
setOverlayUVs
Description
Set overlay uv coordinates
Definition
setOverlayUVs(integer overlayId,float v0,float u0,float v1,float u1,float v2,float u2,float v3,float u3)
Arguments
| integer |
overlayId |
texture file name |
| float |
v0 |
v0 texture coordinate |
| float |
u0 |
u0 texture coordinate |
| float |
v1 |
v1 texture coordinate |
| float |
u1 |
u1 texture coordinate |
| float |
v2 |
v2 texture coordinate |
| float |
u2 |
u2 texture coordinate |
| float |
v3 |
v3 texture coordinate |
| float |
u3 |
u3 texture coordinate |
renderOverlay
Description
Render overlay
Definition
renderOverlay(integer overlayId,float x,float y,float width,float height)
Arguments
| integer |
overlayId |
texture file name |
| float |
x |
x position [0,1] |
| float |
y |
y position [0,1] |
| float |
width |
width [0,1] |
| float |
height |
height [0,1] |
createVideoOverlay
Description
Create video overlay object
Definition
createVideoOverlay(string videoFilename,boolean loopVideo,float soundVolume)
Arguments
| string |
videoFilename |
video file name |
| boolean |
loopVideo |
loop video |
| float |
soundVolume |
sound volume [0,1] |
playVideoOverlay
Description
Play video overlay object
Definition
playVideoOverlay(integer videoOverlayId)
Arguments
| integer |
videoOverlayId |
overlay id |
stopVideoOverlay
Description
Stop video overlay object
Definition
stopVideoOverlay(integer videoOverlayId)
Arguments
| integer |
videoOverlayId |
overlay id |
updateVideoOverlay
Description
Update video overlay object
Definition
updateVideoOverlay(integer videoOverlayId)
Arguments
| integer |
videoOverlayId |
overlay id |
getVideoOverlayDuration
Description
Get video overlay duration
Definition
getVideoOverlayDuration(integer videoOverlayId)
Arguments
| integer |
videoOverlayId |
overlay id |
Return Values
| float |
videoDuration |
video duration in milliseconds |
getVideoOverlayCurrentTime
Description
Get video overlay current time
Definition
getVideoOverlayCurrentTime(integer videoOverlayId)
Arguments
| integer |
videoOverlayId |
overlay id |
Return Values
| float |
videoCurrentTime |
video current time in milliseconds |
setVideoOverlayPosition
Description
Set video overlay current position
Definition
setVideoOverlayPosition(integer videoOverlayId,float position)
Arguments
| integer |
videoOverlayId |
overlay id |
| float |
position |
position [0, 1] |
isVideoOverlayPlaying
Description
Get is video overlay playing
Definition
isVideoOverlayPlaying(integer videoOverlayId)
Arguments
| integer |
videoOverlayId |
overlay id |
Return Values
| boolean |
isVideoOverlayPlaying |
is video overlay playing |
setVideoOverlayVolume
Description
Set video overlay volume
Definition
setVideoOverlayVolume(integer videoOverlayId,float volume)
Arguments
| integer |
videoOverlayId |
overlay id |
| float |
volume |
volume [0, 1] |
Sound Function Reference
createSample
Description
Create sample object
Definition
createSample(string objectName)
Arguments
| string |
objectName |
sample object name |
Return Values
| integer |
sampleId |
id of the created sample |
loadSample
Description
Load sample object
Definition
loadSample(integer objectId,integer sampleFilename,boolean b3DSound)
Arguments
| integer |
objectId |
id of sample object |
| integer |
sampleFilename |
Sample filename (.wav) |
| boolean |
b3DSound |
true=enables 3D Sound-Rendering, false=disables 3D Sound-Rendering |
playSample
Description
Play sample object
Definition
playSample(integer objectId,integer loops,float volume,float offset)
Arguments
| integer |
objectId |
id of sample object |
| integer |
loops |
number of loops [0,n] 0 = endless looping |
| float |
volume |
volume [0,1] |
| float |
offset |
offset in milliseconds |
stopSample
Description
Stop sample object
Definition
stopSample(integer objectId)
Arguments
| integer |
objectId |
id of sample object |
setSamplePitch
Description
Set sample pitch
Definition
setSamplePitch(integer objectId,float pitch)
Arguments
| integer |
objectId |
id of sample object |
| float |
pitch |
pitch value [0.5-2.0] |
getSamplePitch
Description
Set sample pitch
Definition
getSamplePitch(integer objectId)
Arguments
| integer |
objectId |
id of sample object |
Return Values
| float |
pitch |
pitch of sample object |
setSampleVolume
Description
Set sample volume
Definition
setSampleVolume(integer objectId,float volume)
Arguments
| integer |
objectId |
id of sample object |
| float |
volume |
volume value |
getSampleVolume
Description
Get sample volume
Definition
getSampleVolume(integer objectId)
Arguments
| integer |
objectId |
id of sample object |
Return Values
| float |
volume |
volume value |
getSampleDuration
Description
Get sample duration
Definition
getSampleDuration(integer objectId)
Arguments
| integer |
objectId |
id of sample object |
Return Values
| float |
duration |
duration value |
setSampleVelocity
Description
Set velocity of a sample object
Definition
setSampleVelocity(integer objectId,float x,float y,float z)
Arguments
| integer |
objectId |
id of sample object |
| float |
x |
velocity value towards x value |
| float |
y |
velocity value towards y value |
| float |
z |
velocity value towards z value |
getSampleVelocity
Description
Get velocity of a sample object
Definition
getSampleVelocity(integer objectId)
Arguments
| integer |
objectId |
id of sample object |
Return Values
| float |
x |
velocity value towards x value |
| float |
y |
velocity value towards y value |
| float |
z |
velocity value towards z value |
createStreamedSample
Description
Create streamed sample object
Definition
createStreamedSample(string objectName)
Arguments
| string |
objectName |
streamed sample object name |
Return Values
| integer |
sampleId |
id of the created sample |
loadStreamedSample
Description
Load streamed sample object
Definition
loadStreamedSample(integer objectId,string bgmusicFilename)
Arguments
| integer |
objectId |
id of streamed sample object |
| string |
bgmusicFilename |
streamed sample filename (.ogg) |
playStreamedSample
Description
Play streamed sample object
Definition
playStreamedSample(integer objectId,integer repeat)
Arguments
| integer |
objectId |
id of streamed sample object |
| integer |
repeat |
number of recurrences. 0 means endless loop |
pauseStreamedSample
Description
Pause streamed sample object
Definition
pauseStreamedSample(integer objectId)
Arguments
| integer |
objectId |
id of streamed sample object |
resumeStreamedSample
Description
Resume streamed sample
Definition
resumeStreamedSample(integer objectId)
Arguments
| integer |
objectId |
id of streamed sample object |
stopStreamedSample
Description
Stop streamed sample
Definition
stopStreamedSample(integer objectId)
Arguments
| integer |
objectId |
id of streamed sample object |
setStreamedSampleVolume
Description
Set streamed sample volume
Definition
setStreamedSampleVolume(integer objectId,float volume)
Arguments
| integer |
objectId |
id of streamed sample object |
| float |
volume |
volume value |
getStreamedSampleVolume
Description
Get streamed sample volume
Definition
getStreamedSampleVolume(integer objectId)
Arguments
| integer |
objectId |
id of streamed sample object |
Return Values
| float |
volume |
volume value |
createAudioSource
Description
Create audio source object for 3D sounds
Definition
createAudioSource(string audioSourceName,string sampleFilename,float radius,float innerRadius,float volume,integer loops)
Arguments
| string |
audioSourceName |
audio source name |
| string |
sampleFilename |
sample file name (.wav or .ogg) |
| float |
radius |
radius |
| float |
innerRadius |
inner radius |
| float |
volume |
volume [0,1] |
| integer |
loops |
number of loops |
getAudioSourceSample
Description
Gets the sample id of an audio source
Definition
getAudioSourceSample(id objectId)
Arguments
| id |
objectId |
id of the audio source |
Return Values
| integer |
sampleId |
sample id |
Input Function Reference
getNumOfGamepads
Description
Get number of joysticks/gampads
Definition
getNumOfGamepads()
Return Values
| integer |
numOfGamepads |
number of joysticks/gampads |
getGamepadName
Description
Get name of joystick/gampad
Definition
getGamepadName(integer gamepadIndex)
Arguments
| integer |
gamepadIndex |
joystick/gampad index |
Return Values
| string |
gamepadName |
name of joystick/gampad |
getInputAxis
Description
Get joystick/gampad axis value
Definition
getInputAxis(integer axisNumber,integer gamepadIndex)
Arguments
| integer |
axisNumber |
axis number [0=Input.AXIS_1, 5=Input.AXIS_6] |
| integer |
gamepadIndex |
joystick/gampad index |
Return Values
| float |
axisValue |
axis value [-1, 1] |
getInputButton
Description
Get joystick/gampad button value
Definition
getInputButton(integer buttonNumber,integer gamepadIndex)
Arguments
| integer |
buttonNumber |
button number [0=Input.BUTTON_1, 15==Input.BUTTON_16] |
| integer |
gamepadIndex |
joystick/gampad index |
Return Values
| float |
buttonValue |
button value [0, 1] |
getGamepadButtonLabel
Description
Get joystick/gampad button label
Definition
getGamepadButtonLabel(integer buttonNumber,integer gamepadIndex)
Arguments
| integer |
buttonNumber |
button number [0=Input.BUTTON_1, 15==Input.BUTTON_16] |
| integer |
gamepadIndex |
joystick/gampad index |
Return Values
| string |
buttonLabel |
button label |
getGamepadAxisLabel
Description
Get joystick/gampad axis label
Definition
getGamepadAxisLabel(integer axisNumber,integer gamepadIndex)
Arguments
| integer |
axisNumber |
axis number [0=Input.AXIS_1, 5=Input.AXIS_6] |
| integer |
gamepadIndex |
joystick/gampad index |
Return Values
| string |
axisLabel |
axis label |
setGamepadVibration
Description
Set joystick/gampad vibration
Definition
setGamepadVibration(integer low,integer high,integer duration,integer gamepadIndex)
Arguments
| integer |
low |
low |
| integer |
high |
high |
| integer |
duration |
duration |
| integer |
gamepadIndex |
joystick/gampad index |
setGamepadDeadzone
Description
Set joystick/gampad vibration
Definition
setGamepadDeadzone(float deadZone,integer gamepadIndex)
Arguments
| float |
deadZone |
dead zone |
| integer |
gamepadIndex |
joystick/gampad index |
XML Function Reference
XML Path
XML paths used in the getXML... and setXML... functions have the following format:
node1.node2.....nodeN
or
node1.node2.....nodeN#attribute.
Example:
<test>
<test1 attr="test">
This is some text
</test1>
</test>
To get the attribute "attr", use the path test.test1#attr.
To get the content of test1, use the path test.test1.
createXMLFile
Description
Create an empty XML file
Definition
createXMLFile(string objectName,string filename,string rootNodeName)
Arguments
| string |
objectName |
internal name for the object created |
| string |
filename |
filename (full path) |
| string |
rootNodeName |
name of the root node |
Return Values
| integer |
objectId |
object id |
loadXMLFile
Description
Load XML file
Definition
loadXMLFile(string objectName,string filename)
Arguments
| string |
objectName |
internal name for the object created |
| string |
filename |
filename (full path) |
Return Values
| integer |
objectId |
object id |
saveXMLFile
Description
Save XML file
Definition
saveXMLFile(integer objectId)
Arguments
| integer |
objectId |
object id |
getXMLInt
Description
Get XML file integer attribute. See XML Path
Definition
getXMLInt(integer objectId,string attributePath)
Arguments
| integer |
objectId |
object id |
| string |
attributePath |
attribute path |
Return Values
| integer |
value |
attribute value |
getXMLFloat
Description
Get XML file float attribute. See XML Path
Definition
getXMLFloat(integer objectId,string attributePath)
Arguments
| integer |
objectId |
object id |
| string |
attributePath |
attribute path |
Return Values
| float |
value |
attribute value |
getXMLBool
Description
Get XML file boolean attribute. See XML Path
Definition
getXMLBool(integer objectId,string attributePath)
Arguments
| integer |
objectId |
object id |
| string |
attributePath |
attribute path |
Return Values
| boolean |
value |
attribute value |
getXMLString
Description
Get XML file string attribute. See XML Path
Definition
getXMLString(integer objectId,string attributePath)
Arguments
| integer |
objectId |
object id |
| string |
attributePath |
attribute path |
Return Values
| string |
value |
attribute value |
setXMLInt
Description
Set XML file integer attribute. See XML Path
Definition
setXMLInt(integer objectId,string attributePath,integer value)
Arguments
| integer |
objectId |
object id |
| string |
attributePath |
attribute path |
| integer |
value |
value |
setXMLFloat
Description
Set XML file float attribute. See XML Path
Definition
setXMLFloat(integer objectId,string attributePath,float value)
Arguments
| integer |
objectId |
object id |
| string |
attributePath |
attribute path |
| float |
value |
value |
setXMLBool
Description
Set XML file boolean attribute. See XML Path
Definition
setXMLBool(integer objectId,string attributePath,boolean value)
Arguments
| integer |
objectId |
object id |
| string |
attributePath |
attribute path |
| boolean |
value |
value |
setXMLString
Description
Set XML file string attribute. See XML Path
Definition
setXMLString(integer objectId,string attributePath,string value)
Arguments
| integer |
objectId |
object id |
| string |
attributePath |
attribute path |
| string |
value |
value |
hasXMLProperty
Description
Returns if an XML path is available in the file. See XML Path
Definition
hasXMLProperty(integer objectId,string attributePath)
Arguments
| integer |
objectId |
object id |
| string |
attributePath |
path to a node or an attribute |
Return Values
| boolean |
value |
is the given property available in the xml file |
Notes
available since 4.1.5
removeXMLProperty
Description
Removes xml property. See XML Path
Definition
removeXMLProperty(integer objectId,string propertyPath)
Arguments
| integer |
objectId |
object id |
| string |
propertyPath |
path to a node or an attribute |
Return Values
| boolean |
succeeded |
removal state |
Notes
available since 6.0.0
Network Function Reference
streamWriteBool
Description
Stream write boolean
Definition
streamWriteBool(integer streamId,boolean value)
Arguments
| integer |
streamId |
stream id |
| boolean |
value |
value |
streamWriteInt8
Description
Stream write 8bit signed integer
Definition
streamWriteInt8(integer streamId,integer value)
Arguments
| integer |
streamId |
stream id |
| integer |
value |
value [-127, 127] |
streamWriteInt16
Description
Stream write 16bit signed integer
Definition
streamWriteInt16(integer streamId,integer value)
Arguments
| integer |
streamId |
stream id |
| integer |
value |
value [-32768, 32768] |
streamWriteInt32
Description
Stream write 32bit signed integer
Definition
streamWriteInt32(integer streamId,integer value)
Arguments
| integer |
streamId |
stream id |
| integer |
value |
value |
streamWriteIntN
Description
Stream write N bit signed integer. 0<N<32.
Definition
streamWriteIntN(integer streamId,integer value,integer numberofBits)
Arguments
| integer |
streamId |
stream id |
| integer |
value |
value [-2^(N-1), 2^(N-1)] |
| integer |
numberofBits |
number of bits |
streamWriteFloat32
Description
Stream write 32bit float
Definition
streamWriteFloat32(integer streamId,float value)
Arguments
| integer |
streamId |
stream id |
| float |
value |
value |
streamWriteString
Description
Stream write string
Definition
streamWriteString(integer streamId,string value)
Arguments
| integer |
streamId |
stream id |
| string |
value |
value, max 64k characters |
streamReadBool
Description
Stream read boolean
Definition
streamReadBool(integer streamId)
Arguments
| integer |
streamId |
stream id |
Return Values
streamReadInt8
Description
Stream read 8bit signed integer
Definition
streamReadInt8(integer streamId)
Arguments
| integer |
streamId |
stream id |
Return Values
streamReadInt16
Description
Stream read 16bit signed integer
Definition
streamReadInt16(integer streamId)
Arguments
| integer |
streamId |
stream id |
Return Values
streamReadInt32
Description
Stream read 32bit signed integer
Definition
streamReadInt32(integer streamId)
Arguments
| integer |
streamId |
stream id |
Return Values
streamReadIntN
Description
Stream read 32bit signed integer
Definition
streamReadIntN(integer streamId,integer numberofBits)
Arguments
| integer |
streamId |
stream id |
| integer |
numberofBits |
number of bits |
Return Values
streamReadFloat32
Description
Stream read 32bit float
Definition
streamReadFloat32(integer streamId)
Arguments
| integer |
streamId |
stream id |
Return Values
streamReadString
Description
Stream read 32bit float
Definition
streamReadString(integer streamId)
Arguments
| integer |
streamId |
stream id |
Return Values
streamGetNumOfUnreadBits
Description
Stream get number of unread bits
Definition
streamGetNumOfUnreadBits(integer streamId)
Arguments
| integer |
streamId |
stream id |
Return Values
| integer |
value |
number of unread bit |
streamGetReadOffset
Description
Stream get read offset
Definition
streamGetReadOffset(integer streamId)
Arguments
| integer |
streamId |
stream id |
Return Values
| integer |
offset |
Read offset |
streamSetReadOffset
Description
Sets the read pointer to the given offset in bytes
Definition
streamSetReadOffset(integer streamId,integer offset)
Arguments
| integer |
streamId |
stream id |
| integer |
offset |
read offset in bytes |
streamGetWriteOffset
Description
Returns the write pointer offset in bytes
Definition
streamGetWriteOffset(integer streamId)
Arguments
| integer |
streamId |
stream id |
Return Values
| integer |
offset |
Write offset |
streamSetWriteOffset
Description
Sets the write pointer to the given offset in bytes
Definition
streamSetWriteOffset(integer streamId,integer offset)
Arguments
| integer |
streamId |
stream id |
| integer |
offset |
write offset in bytes |
Callbacks Function Reference
Default callbacks
init
Description
This function is called once on startup. Create and load objects here.
Definition
init(string args)
Arguments
| string |
args |
command line arguments |
Return Values
| boolean |
success |
return true if successful |
keyEvent
Description
This function is called when a key event occurs.
Definition
keyEvent(float unicode,float sym,float modifier,boolean isDown)
Arguments
| float |
unicode |
unicode value |
| float |
sym |
sym key |
| float |
modifier |
key modifier |
| boolean |
isDown |
is down state |
mouseEvent
Description
This function is called when a mouse event occurs.
Definition
mouseEvent(float posX,float posY,boolean isDown,boolean isUp,float button)
Arguments
| float |
posX |
x position [0,1] |
| float |
posY |
y position [0,1] |
| boolean |
isDown |
is down state |
| boolean |
isUp |
is up state |
| float |
button |
button number |
update
Description
This function is called once per frame to update game state.
Definition
update(float dt)
Arguments
| float |
dt |
time between this frame and last frame in milliseconds |
draw
Description
This function is called once per frame to draw game objects. Call render functions here.
Definition
draw()
Custom callbacks
trigger callback
Description
This function is called when a trigger event occurs.
Definition
function triggerFunctionName(integer triggerId, string otherId, boolean onEnter, boolean onLeave, boolean onStay)
Arguments
| integer | triggerId | id of the trigger node |
| integer | otherId | id of the other node |
| boolean | onEnter | on enter state |
| boolean | onLeave | on leave state |
| boolean | onStay | on stay state |
contact callback
Description
This function is called when a contact event occurs.
Definition
function onContact(integer objectId, integer otherObjectId, boolean isStart, float normalForce, float tangentialForce)
Arguments
| integer | objectId | id of the object |
| integer | otherObjectId | id of the other object |
| boolean | isStart | is start touch |
| float | normalForce | normal contact force |
| float | tangentialForce | tangential contact force |
raycast callback
Description
This function is called when a raycast hit event occurs.
See raycastAll and raycastClosest
Definition
function raycastFunctionName(integer hitObjectId, float
x, float y, float z, float distance, float nx, float ny, float nz,
integer subShapeIndex)
Arguments
| integer | hitObjectId | id of the hit node |
| float | x | world impact x |
| float | y | world impact y |
| float | z | world impact z |
| float | distance | distance |
| float | nx | world normal x (only valid if generateNormal was true) |
| float | ny | world normal y (only valid if generateNormal was true) |
| float | nz | world normal z (only valid if generateNormal was true) |
| integer | subShapeIndex | sub shape index of destructible object. Negative if normal rigid body (check for subShapeIndex >= 0) |
Return Values
| boolean | continue | continue raycasting |
create callback
Description
Create callbacks are called during i3d loads.
Definition
function createFunctionName(integer objectId)
Arguments
| integer | objectId | id of the object |
timer callback
Description
This function is called when a timer event occurs.
Definition
function timerFunctionName()
Return Values
| boolean | keepTimer | return false if the timer should be removed |
packet received callback
Description
This function is called when a network packet was received.
Definition
function packetReceived(packetType, timestamp, streamId)
Arguments
| integer | packetType | type of the packet. All available types are stored in the Network table |
| integer | timestamp | timestamp of when the packet was sent |
| integer | streamId | id of the stream containing the packet data |
Text Rendering Reference
renderText
Description
Render text to viewport. See asciiToUtf8 to convert to utf8
Definition
renderText(float x,float y,float size,string str)
Arguments
| float |
x |
x position [0, 1] |
| float |
y |
y position [0, 1] |
| float |
size |
font size |
| string |
str |
utf8 encoded string to print |
setTextColor
Description
Set the text color to be used for the following renderText calls
Definition
setTextColor(float r,float g,float b,float a)
Arguments
| float |
r |
red color component [0, 1] |
| float |
g |
green color component [0, 1] |
| float |
b |
blue color component [0, 1] |
| float |
a |
alpha (opacity) [0, 1] |
setTextBold
Description
Set the text boldness to be used for the following renderText calls
Definition
setTextBold(boolean isBold)
Arguments
| boolean |
isBold |
bold state |
setTextAlignment
Description
Set the text alignment to be used for the following renderText calls
Definition
setTextAlignment(integer alignment)
Arguments
| integer |
alignment |
alignment (RenderText.ALIGN_LEFT, RenderText.ALIGN_CENTER or RenderText.ALIGN_RIGHT) |
setTextWidthScale
Description
Set the text scale width to be used for the following renderText calls
Definition
setTextWidthScale(float scaleWidth)
Arguments
| float |
scaleWidth |
scale width |
setTextWidthScale
Description
Set the text scale width to be used for the following renderText calls
Definition
setTextWidthScale(float scaleWidth)
Arguments
| float |
scaleWidth |
scale width |
getTextWidth
Description
Get text width
Definition
getTextWidth(float fontSize,string utf8string)
Arguments
| float |
fontSize |
font size |
| string |
utf8string |
utf8 encoded string |
Return Values
| float |
textWidth |
text width |
getTextHeight
Description
Get text height
Definition
getTextHeight(float fontSize,string utf8string)
Arguments
| float |
fontSize |
font size |
| string |
utf8string |
utf8 encoded string |
Return Values
| float |
textHeight |
text height |
| int |
numLines |
number of lines |
getTextLength
Description
Get text length
Definition
getTextLength(float fontSize,string utf8string,integer maxNumLines)
Arguments
| float |
fontSize |
font size |
| string |
utf8string |
utf8 encoded string |
| integer |
maxNumLines |
max numbers of lines |
Return Values
| integer |
numChars |
number of characters |
getTextLineLength
Description
Get text length
Definition
getTextLineLength(float fontSize,string utf8string,float maxWidth)
Arguments
| float |
fontSize |
font size |
| string |
utf8string |
utf8 encoded string |
| float |
maxWidth |
max width |
Return Values
| integer |
numChars |
number of characters |
Terrain Detail Transform Group Reference
setDensityNewTypeIndexMode
Description
TODO
Definition
setDensityNewTypeIndexMode(integer transformId,integer newTypeIndexMode)
Arguments
| integer |
transformId |
id of transform object |
| integer |
newTypeIndexMode |
0=UPDATE_INDEX,1=KEEP_INDEX,2=SET_INDEX_TO_ZERO |
setDensityTypeIndexCompareMode
Description
TODO
Definition
setDensityTypeIndexCompareMode(integer transformId,integer indexComopareMode)
Arguments
| integer |
transformId |
id of transform object |
| integer |
indexComopareMode |
0=TYPE_COMPARE_EQUAL, 1=TYPE_COMPARE_NOTEQUAL, 2=TYPE_COMPARE_NONE |