GIANTS Game Engine v4 Documentation

Table of Contents

1. Chapter 01: Overview
2. Chapter 02: SDK
   1. Runtime development key short-cuts
   2. Console Command Reference
   3. Function Reference
      1. General
      2. Entity
      3. Node
      4. Scenegraph
      5. Lighting
      6. Camera
      7. Shape
      8. Physics
      9. Spline
      10. Animation
      11. Overlays
      12. Sound
      13. Input
      14. XML
      15. Network
      16. Callbacks
   4. Foundation Reference
      1. Scenegraph
      2. Input
3. Chapter 03: Tutorials
   1. Tutorial 1 - Load i3d files and basics
   2. Tutorial 2 - Light functions, global time and rendering text
   3. Tutorial 3 - User Attributes
   4. Tutorial 4 - Timers
   5. Tutorial 5 - Physics
   6. Tutorial 6 - Overlays
   7. Tutorial 7 - Audio
4. Chapter 04: Editor
   1. Viewport
   2. Scenegraph
   3. Attributes
   4. Toolbar
   5. Terrain
   6. User Attributes
   7. Scripting
   8. Terrain Editing
   9. Replace Dialog
   10. Interactive Placement
   11. Other functionality
   12. Key short-cuts
5. Chapter 05: Debugger
   1. Overview
   2. Interface
      1. Menu and Toolbars
      2. Main text editor panel
      3. File browser panel
      4. Variable overview panel
      5. Additional information panel
   3. Tutorial
      1. Setup
      2. Debugging
      3. Stepping
   4. Keyboard short-cuts
6. Chapter 06: Exporter
   1. Autodesk Maya¹ i3d exporter
      1. Material export options
   2. Autodesk 3ds MAX² i3d exporter
   3. Blender i3d exporter
7. Chapter 07: Content Creation - Artwork Guide
   1. Autodesk Maya
   2. Autodesk 3DS MAX
   3. Texturing
8. Chapter 08: I3D Format
   1. Introduction
   2. Features
   3. Overview
   4. Specification
      1. General Layout
      2. Materials
      3. Shapes
      4. Dynamics
      5. Scenegraph
      6. Animation
   5. Example file
   6. Test Scenes

Graphics

• Flexible culling, sorting and rendering
• Particle systems
• Level-of-detail (hierarchy, geometry and shader)
• Dynamic shader generation
• Dynamic directional, point, spot and ambient lights
• Dynamic shadows
• Reflections and refractions
• Customizable shaders
• Multi layered terrain
• Scene graph representation
• Flexible foliage system

Physics

• Rigid Body physics
• Advanced character control
• Articulated vehicle dynamics
• Ragdoll dynamics
• Customizable joints
• Triggers
• Contact reports
• Automated collision geometry generation

Animations

• Hierarchical scene graph animation
• Skeleton animation
• Animation sequence blending and interpolation
• Animation sequence instancing

Artificial Intelligence

• Automated navigation mesh generation
• Path finding
• Containment queries

Tools

• Flexible and powerful content pipeline tool chain
• Full featured editor
• 3D modeling tool exporters (including animation, hierarchy, physics, materials, shaders and user attributes)
  • Autodesk Maya
  • Autodesk 3ds MAX
  • Blender
• Remote runtime target debugger
  • Connection via TCP/IP
  • Script debugger
  • Physics debugger

Miscellaneous

• Streaming support
• Generic scripting support (LUA, Small, Python, ...)
• Unicode support
• Networking support
  • Peer-to-peer or Client/Server
  • NAT Traversal
• Flexible XML-based file formats
• Multi-Threading support
• Multi-platform
• 3D audio support
• Detailed runtime stats and profiling system
• Extensive documentation and tutorials

enableFramerateLimit

Enable/disable frame per second limiter

exit, quit or q

Quits application

framerateLimitFPS

Frame per second limit attribute

globalClipDistance

Global clipping distance. Additional distance clipping per object (at center of object).

globalCullOverride

Global cull override. If true no visibility culling is used.

listEntities

Print detailed entity list

listResources

Print detailed resource list

reload

Reloads resource with given name

reloadAll

Reload all resources with given type

showDebugAudioSource

Show debug audio sources

showDebugLightSources

Show debug lights

showDebugRendering

Show debug rendering. Global switch for all debug rendering.

showShapeBoundingVolume

Show shape bounding volumes

showTransformGroupFrames

Show debug transform group frames

showFps

Show frames per second

sortGeometry

Sort render queue by material sort id

parallelRenderingAndPhysics

Enable parallel rendering and physics

Function Reference

General Function Reference

print

Print to console

function print(arg1, ...)

any type	arg1	variable to print
any type	...	variable to print

source

Source script file

function source(filename)

string

filename

name of script file

requestExit

Request application to exit at the end of this frame

function requestExit()

renderText

Render text to viewport
See asciiToUtf8 to convert to utf8

function renderText(float x, float y, float size, string str)

float	x	x position [0, 1]
float	y	y position [0, 1]
float	size	font size
string	str	utf8 encoded string to print

setTextColor

Set the text color to be used for the following renderText calls

function setTextColor(float r, float g, float b, float a)

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

Set the text boldness to be used for the following renderText calls

function setTextBold(boolean isBold)

boolean

isBold

bold state

setTextAlignment

Set the text alignment to be used for the following renderText calls

function setTextAlignment(integer alignment)

integer

alignment

alignment (RenderText.ALIGN_LEFT, RenderText.ALIGN_CENTER or RenderText.ALIGN_RIGHT)

setTextWrapWidth

Set the text wrap width to be used for the following renderText calls

function setTextWrapWidth(float wrapWidth)

float

wrapWidth

wrap width

since v4.1.5

drawDebugPoint

Render a point. Only use for debug rendering

function drawDebugPoint(float x, float y, float z, float r, float g, float b, float a)

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]

since v4.1.5

drawDebugLine

Render a line. Only use for debug rendering

function 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)

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]

since v4.1.5

drawDebugArrow

Render an arrow. Only use for debug rendering

function 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)

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]

since v4.1.5

asciiToUtf8

Converts an ascii latin1 (ISO 88859-1) encoded string to an utf8 string

function asciiToUtf8(string asciiString)

string

asciiString

ascii string

string

utf8string

utf8 encoded string

since v4.1.5

unicodeToUtf8

Converts an unicode value to an utf8 string

function unicodeToUtf8(integer unicode)

integer

unicode

unicode value

string

utf8string

utf8 encoded string representing the unicode

since v4.1.5

utf8Strlen

Returns the length of an utf8 formated string

function utf8Strlen(string utf8string)

string

utf8string

utf8 formated string

integer

length

length of the given string

since v4.1.5

utf8Substr

Returns a sub string of an utf8 formated string

function utf8Substr(string utf8string, integer startIndex, integer length)

string	utf8string	utf8 formated string
integer	startIndex	zero based start index
integer	length	maximal length of the sub string (optional)

string

subString

utf8 formated sub string

since v4.1.5

setFog

Set fog properties

function setFog(string fogType, float startDistanceOrDensity, float endDistance, float r, float g, float b)

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	color r
float	g	color g
float	b	color b

setVolumeFog

Set volume fog properties

function setVolumeFog(string fogType, float startDistanceOrDensity, float endDistance, float yPlane, float r, float g, float b)

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	yPlane	y plane value
float	r	color r
float	g	color g
float	b	color b

wrapMousePosition

Wrap mouse position

function wrapMousePosition(float x, float y)

float	x	x coord [0, 1]
float	y	y coord [0, 1]

setShowMouseCursor

Set show mouse cursor

function setShowMouseCursor(boolean state)

boolean

state

enable state

setCaption

Set caption

function setCaption(string caption)

string

caption

application caption

loadI3DFile

Load I3D file

function loadI3DFile(string filename)

string

filename

i3d filename

integer

rootNodeId

id of root node

project

Transform vector from world space into screen space

function project(float wx, float wy, float wz)

float	wx	world space x coordinate
float	wy	world space y coordinate
float	wz	world space z coordinate

float	sx	screen space x coordinate
float	sy	screen space y coordinate
float	sz	screen space z coordinate

unProject

Transform vector from screen space into world space

function unProject(float sx, float sy, float sz)

float	sx	screen space x coordinate
float	sy	screen space y coordinate
float	sz	screen space z coordinate

float	wx	world space x coordinate
float	wy	world space y coordinate
float	wz	world space z coordinate

addTimer

Adds timer callback function

function addTimer(float time, string timerFunctionCallback, object instance)

float	time	time in milliseconds
string	triggerFunctionCallback	trigger function callback
object	instance	instance object (optional)

integer

timerId

timer id

setTimerTime

Set timer interval time

function setTimerTime(integer timerId, float time)

integer	timerId	timer id
float	time	time in milliseconds

saveScreenshot

Save screenshot

function saveScreenshot(string filename)

string

filename

filename

getAppBasePath

Get application base path

function getAppBasePath()

string

appBasePath

application base path

getUserProfileAppPath

Get user profile application path

function getUserProfileAppPath()

string

getUserProfileAppPath

user profile application path

copyFile

Get copy file

function copyFile(string sourceFile, string destinationFile, boolean overwrite)

string	sourceFile	source filename
string	destinationFile	destination filename
boolean	overwrite	overwrite file if it already exists

getFiles

Get all files of a directory

function getFiles(string path, string fileFunctionCallback, object instance)

string	path	path
string	fileFunctionCallback	file function callback
object	instance	instance object (optional)

integer

numFiles

number of files

Entity Function Reference

delete

Delete Entity/Object

function delete(integer objectId)

integer

objectId

object id

getClassName

Get class name of object

function getClassName(integer objectId)

integer

objectId

object id

string

className

class name of object

addDeleteListener

Add a delete listener

function addDeleteListener(integer objectId, string deleteFunctionCallback, object targetObject)

integer	objectId	object id
string	deleteFunctionCallback	delete listener function callback, is called when the entity is deleted
object	targetObject	target object (optional), the callback function is called as a member function of targetObject

integer

listenerId

id to the created callback, must be given to removeDeleteListener

removeDeleteListener

Remove a delete listener. Note: it is important to call removeDeleteListener for each addDeleteListener call to avoid memory leaks

function removeDeleteListener(integer objectId, integer listenerId)

integer	objectId	object id
integer	listenerId	id of the delete listener

Node Function Reference

getParent

Get parent id

function getParent(integer objectId)

integer

objectId

object id

integer

parentId

parent id

link

Link node to another node

function link(integer parentNodeId, integer childNodeId)

integer	parentNodeId	id of parent node
integer	childNodeId	id of child node

unlink

Unlink node from parent

function unlink(integer objectId)

integer

objectId

object id

getNumOfChildren

Get number of children

function getNumOfChildren(integer objectId)

integer

objectId

object id

integer

numOfChildren

number of children

getChildAt

Get child id at given index

function getChildAt(integer objectId, integer index)

integer	objectId	object id
integer	index	index of child

integer

childId

id of child node

getChild

Get child id

function getChild(integer objectId, string childName)

integer	objectId	object id
string	childName	child name

integer

childId

id of child node

getName

Get object name

function getName(integer objectId)

integer

objectId

object id

string

objectName

object name

setName

Set object name

function setName(integer objectId, string objectName)

integer	objectId	object id
string	objectName	new object name

removeChildAt

Remove child at given index

function removeChildAt(integer objectId, integer index)

integer	objectId	object id
integer	index	index of child

Scenegraph Function Reference

createTransformGroup

Create transform group

function createTransformGroup(string transformName)

string

transformName

name of transform object

integer

transformId

id of transform object

setTranslation

Set translation of a transform object

function setTranslation(integer transformId, float x, float y, float z)

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

Get translation of a transform object

function getTranslation(integer transformId)

integer

transformId

id of transform object

float	x	x value of translation
float	y	y value of translation
float	z	z value of translation

getWorldTranslation

Get world translation of a transform object

function getWorldTranslation(integer transformId)

integer

transformId

id of transform object

float	x	x value of world translation
float	y	y value of world translation
float	z	z value of world translation

setRotation

Set euler rotation of a transform object. Order ZY'X''

function setRotation(integer transformId, float x, float y, float z)

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

Get rotation of a transform object

function getRotation(integer transformId)

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)

getWorldRotation

Get world rotation of a transform object

function getWorldRotation(integer transformId)

integer

transformId

id of transform object

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

Set the direction of an object, the positive z-axis points towards the given direction. The y-axis lies in the direction-up-plane.

function setDirection(integer transformId, float x, float y, float z, float upX, float upY, float upZ)

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	upY	z value of up vector

setScale

Set scale of a transform object

function setScale(integer transformId, float x, float y, float z)

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

Get scale of a transform object

function getScale(integer transformId)

integer

transformId

id of transform object

float	x	x value of scale
float	y	y value of scale
float	z	z value of scale

setVisibility

Set transform object visibility

function setVisibility(integer transformId, boolean visibility)

integer	transformId	id of transform object
boolean	visibility	visibility state

getVisibility

Get transform object visibility

function getVisibility(integer transformId)

integer

transformId

id of transform object

boolean

visibility

visibility state

clone

Clone scenegraph object

function clone(integer objectId, boolean groupUnderParent)

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

id

cloneId

id of clone object

setRootNode

Set scenegraph root node used by the given viewport

function setRootNode(integer rootNodeId, integer viewportIndex)

integer	rootNodeId	id of new root node
integer	viewportIndex	the index of the viewport [0-7]

getRootNode

Get scenegraph root node used by the given viewport

function getRootNode(integer viewportIndex)

integer

viewportIndex

the index of the viewport [0-7]

integer

rootNodeId

id of the root node

localToWorld

Local space to world space transformation

function localToWorld(integer transformId, float x, float y, float z)

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

float	x	x value of world position
float	y	y value of world position
float	z	z value of world position

localDirectionToWorld

Local space to world space transformation, only direction without translation

function localDirectionToWorld(integer transformId, float x, float y, float z)

integer	transformId	id of transform object
float	x	x value of local direction
float	y	y value of local direction
float	z	z value of local direction

float	x	x value of world direction
float	y	y value of world direction
float	z	z value of world direction

worldToLocal

World space to local space transformation

function worldToLocal(integer transformId, float x, float y, float z)

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

float	x	x value of local position
float	y	y value of local position
float	z	z value of local position

worldDirectionToLocal

World space to local space transformation, only direction without translation

function worldDirectionToLocal(integer transformId, float x, float y, float z)

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

float	x	x value of local direction
float	y	y value of local direction
float	z	z value of local direction

getAnimCharacterSet

Get animation character set id

function getAnimCharacterSet(integer objectId)

integer

objectId

object id

integer

animId

animation character set id

setUserAttribute

Set user attribute value

function setUserAttribute(integer objectId, string attributeName, string typeName, integer/float/boolean/string value)

integer	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

getUserAttribute

Get user attribute value

function getUserAttribute(integer objectId, string attributeName)

integer	objectId	object id
string	attributeName	name of the user attribute

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

setObjectMask

Set object mask

function setObjectMask(integer objectId, integer mask)

integer	objectId	object id
integer	mask	the object mask to set

getObjectMask

Get object mask

function getObjectMask(integer objectId)

integer

objectId

object id

integer

mask

the object mask

getTerrainHeightAtWorldPos

get the terrain height at the given position

function getTerrainHeightAtWorldPos(integer terrainId, float x, float y, float z)

integer	terrainId	terrain id
float	x	x value of the world position
float	y	y value of the world position
float	z	z value of the world position

float

heightValue

height of the terrain at the given position

Lighting Function Reference

setAmbientColor

Set global ambient color

function setAmbientColor(float r, float g, float b)

float	r	red value of ambient color
float	g	green value of ambient color
float	b	blue value of ambient color

getLightDiffuseColor

Get diffuse color of a light

function getLightDiffuseColor(integer lightId)

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

setLightDiffuseColor

Set diffuse color of a light

function setLightDiffuseColor(integer lightId, float r, float g, float b)

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

Get specular color of a light

function getLightSpecularColor(integer lightId)

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

setLightSpecularColor

Set specular color of a light

function setLightSpecularColor(integer lightId, float r, float g, float b)

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

Get range of a light

function getLightRange(integer lightId)

integer

lightId

id of light

float

range

light range

setLightRange

Set range of a light

function setLightRange(integer lightId, float range)

integer	lightId	id of light
float	range	light range

Camera Function Reference

createCamera

Create camera

function createCamera(string cameraName, float fovy, float nearClip, float farClip)

string	cameraName	camera name
float	fovy	field of view (degree)
float	nearClip	near clip
float	farClip	far clip

setCamera

Set currently used camera by the given viewport

function setCamera(integer cameraId, integer viewportIndex)

integer	cameraId	new camera id
integer	viewportIndex	the index of the viewport [0-7]

getCamera

Get currently used camera by the given viewport

function getCamera(integer viewportIndex)

integer

viewportIndex

the index of the viewport [0-7]

integer

currentCameraId

current camera id

setViewport

Set the dimensions of the given viewport

function setViewport(integer viewportIndex, float left, float top, float width, float height)

integer	viewportIndex	the index of the viewport [0-7]
float	left	the start position from the left side [0-1]
float	top	the start position from the top side [0-1]
float	width	the width of the viewport [0-1]
float	height	the height of the viewport [0-1]

since v4.1.5

setFovy

Set the field of view angle

function setFovy(integer cameraId, float fovy)

integer	cameraId	camera id
float	fovy	field of view angle (degree)

getFovy

Get the field of view angle

function getFovy(integer cameraId)

integer

cameraId

camera id

float

fovy

field of view angle (degree)

setNearClip

Set the near clip distance

function setNearClip(integer cameraId, float nearClip)

integer	cameraId	camera id
float	nearClip	near clip distance

getNearClip

Get the near clip distance

function getNearClip(integer cameraId)

integer

cameraId

camera id

float

nearClip

near clip distance

setFarClip

Set the far clip distance

function setFarClip(integer cameraId, float farClip)

integer	cameraId	camera id
float	farClip	far clip distance

getFarClip

Get the far clip distance

function getFarClip(integer cameraId)

integer

cameraId

camera id

float

farClip

far clip distance

aimCamera

Aim camera (spring/damper)

function aimCamera(integer cameraId, float x, float y, float z, float distance, float dt, float springStrength)

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

setShaderParameter

Set shader parameter

function setShaderParameter(integer shapeId, string parameterName, float x, float y, float z, float w, boolean shared)

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

Particle System Function Reference

setEmittingState

Set whether the particle system should emit new particles

function setEmittingState(integer particleSystemId, boolean state)

integer	particleSystemId	particle system id
boolean	state	if true, new particles are emitted

resetNumOfEmittedParticles

Resets the counter of emitted particles. This is used if the maxEmit attribute is set for the particle system.

function resetNumOfEmittedParticles(integer particleSystemId)

integer

particleSystemId

particle system id

since v4.1.5

setParticleSystemTimeScale

Sets the time scale for the particle simulation.

function setParticleSystemTimeScale(integer particleSystemId, float timeScale)

integer	particleSystemId	particle system id
float	timeScale	time scale for the particle simulation

getEmitterShape

Returns the emitter shape of the particle system

function getEmitterShape(integer particleSystemId)

integer

particleSystemId

particle system id

integer

shapeId

id of the emitter shape

setEmitterShape

Sets the emitter shape of the particle system

function setEmitterShape(integer particleSystemId, integer shapeId)

integer	particleSystemId	particle system id
integer	shapeId	id of the emitter shape

Physics Function Reference

simulatePhysics

Enable/disable physics simulation

function simulatePhysics(boolean state)

boolean

state

enable simulation state

simulatePhysicsTimeScale

Time scale of physics simulation

function simulatePhysicsTimeScale(float scale)

float

scale

physics time scale

createCCT

Create character controller (y axis capsule based)

function createCCT(integer transformId, float radius, float height, float stepOffset, float slopeLimit, float skinWidth, float collisionMask, float mass)

integer	transformId	id of transform object
float	radius	radius
float	height	height
float	stepOffset	step offset
float	slopeLimit	slope limit
float	skinWidth	skin width
integer	collisionMask	collision mask
float	mass	character mass [kg]

integer

characterIndex

character index number

moveCCT

Enqueue character movement

function moveCCT(integer characterIndex, float x, float y, float z, float collisionMasks)

integer	characterIndex	character index number
float	x	x value
float	y	y value
float	z	z value
float	collisionMasks	collision masks

removeCCT

Remove character controller

function removeCCT(integer characterIndex)

integer

characterIndex

character index number

getCCTCollisionFlags

Get character controller collision flags

function getCCTCollisionFlags(integer characterIndex)

integer

characterIndex

character index number

boolean	side	side flag
boolean	up	up flag
boolean	down	down flag

raycastAll

Raycast objects

function raycastAll(float x, float y, float z, float nx, float ny, float nz, string raycastFunctionCallback, float maxDistance)

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
float	maxDistance	max distance

integer

numShapes

number of shapes hit

raycastClosest

Raycast closest object

function raycastClosest(float x, float y, float z, float nx, float ny, float nz, string raycastFunctionCallback, float maxDistance)

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
float	maxDistance	max distance

integer

numShapes

number of shapes hit

overlapSphere

Overlap sphere objects

function overlapSphere(float x, float y, float z, float radius, string overlapFunctionCallback, object targetObject)

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

integer

numShapes

number of shape overlaps

overlapBox

Overlap box objects

function overlapBox(float x, float y, float z, float rx, float ry, float rz, float ex, float ey, float ez, string overlapFunctionCallback, object targetObject)

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

integer

numShapes

number of shape overlaps

addForce

Add force to object

function addForce(integer transformId, float forceX, float forceY, float forceZ, float positionX, float positionY, float positionZ, boolean isPositionLocal)

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

Add impulse to object

function addImpulse(integer transformId, float impulseX, float impulseY, float impulseZ, float positionX, float positionY, float positionZ, boolean isPositionLocal)

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

Set joint drive. Drives orientation if position drive or angular velocity if velocity drive.

function setJointDrive(integer transformId, float angle, float valueX, float valueY, float valueZ)

integer	transformId	id of transform object
float	angle	orientation angle
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

createWheelShape

Create wheel shape

function createWheelShape(integer transformId, float positionX, float positionY, float positionZ, float radius, float suspensionTravel, float spring, float damper, float mass)

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

wheelShapeIndex

wheel shape index

setWheelShapeProps

Set wheel shape properties

function setWheelShapeProps(integer transformId, integer wheelShapeIndex, float motorTorque, float brakeTorque, float steerAngle)

integer	transformId	id of transform object
integer	wheelShapeIndex	wheel shape index
float	motorTorque	motor torque
float	brakeTorque	brake torque
float	steerAngle	steer angle

getWheelShapeAxleSpeed

Get wheel shape axle speed

function getWheelShapeAxleSpeed(integer transformId, integer wheelShapeIndex)

integer	transformId	id of transform object
integer	wheelShapeIndex	wheelShapeIndex

float

axleSpeed

axle speed

getWheelShapeContactPoint

Get wheel shape contact point

function getWheelShapeContactPoint(integer transformId, integer wheelShapeIndex)

integer	transformId	id of transform object
integer	wheelShapeIndex	wheelShapeIndex

float	x	x position
float	y	y position
float	z	z position

getWheelShapePosition

Get wheel shape position

function getWheelShapePosition(integer transformId, integer wheelShapeIndex)

integer	transformId	id of transform object
integer	wheelShapeIndex	wheelShapeIndex

float	x	x position
float	y	y position
float	z	z position

addTrigger

Adds a trigger callback function

The transformId must have set the trigger flag and must be a static or a kinematic rigid body.
The given triggerFunctionCallback is called, whenever a dynamic or kinematic body enters or leaves the region defined by the trigger geometry. Static objects do not trigger an event.
See "trigger callback" in section "Custom callbacks"

function addTrigger(integer transformId, string triggerFunctionCallback, object targetObject)

integer	transformId	id of transform object
string	triggerFunctionCallback	trigger function callback
object	targetObject	target object (optional), the callback function is called as a member function of targetObject

removeTrigger

Removes trigger callback function

function removeTrigger(integer transformId)

integer

transformId

id of transform object

addContactReport

Adds contact report callback function
See contact callback function

function addContactReport(integer transformId, float forceThreshold, string contactReportFunctionCallback, object targetObject)

integer	transformId	id of transform object
float	forceThreshold	force threshold
string	contactFunctionCallback	contact report function callback
object	targetObject	target object (optional), the callback function is called as a member function of targetObject

removeContactReport

Removes contact report callback function

function removeContactReport(integer transformId)

integer

transformId

id of transform object

getRigidBodyType

Get rigid body type

function getRigidBodyType(integer transformId)

integer

transformId

id of transform object

string

type

rigid body type ("Static", "Dynamic", "Kinematic" or "NoRigidBody")

setRigidBodyType

Set rigid body type

function setRigidBodyType(integer transformId, string type)

integer	transformId	id of transform object
string	type	rigid body type ("Static", "Dynamic", "Kinematic" or "NoRigidBody")

getCollisionMask

Get collision mask

function getCollisionMask(integer transformId)

integer

transformId

id of transform object

integer

mask

collision mask

setCollisionMask

Set collision mask

function setCollisionMask(integer transformId, integer mask)

integer	transformId	id of transform object
integer	mask	collision mask

getCenterOfMass

Get center of mass

function getCenterOfMass(integer transformId)

integer

transformId

id of transform object

float	x	x position
float	y	y position
float	z	z position

setCenterOfMass

Set center of mass

function setCenterOfMass(integer transformId, float x, float y, float z)

integer	transformId	id of transform object
float	x	x position
float	y	y position
float	z	z position

getMass

Get mass

function getMass(integer transformId)

integer

transformId

id of transform object

float

mass

mass

setMass

Set mass

function setMass(integer transformId, float mass)

integer	transformId	id of transform object
float	mass	mass

Destruction Function Reference

getHasDestructionShape

Returns if the given destruction shape index exists

function getHasDestructionShape(integer shapeId, integer destructionShapeIndex)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape

boolean

hasShape

true if a shape with the given index exists, otherwise false

getDestructionShapeWorldTranslation

Get world translation of the given destruction shape

function getDestructionShapeWorldTranslation(integer shapeId, integer destructionShapeIndex, boolean physicalPosition)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape
boolean	physicalPosition	if true, the translation of the physics object is returned, otherwise the translation of the visual representation

float	x	x world coordinate
float	y	y world coordinate
float	z	z world coordinate

destructionShapeLocalToWorld

Destruction shape local space to world space transformation

function destructionShapeLocalToWorld(integer shapeId, integer destructionShapeIndex, boolean physicalPosition, float x, float y, float z)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape
boolean	physicalPosition	if true, the translation of the physics object is returned, otherwise the translation of the visual representation
float	x	x value of local position
float	y	y value of local position
float	z	z value of local position

float	x	x world coordinate
float	y	y world coordinate
float	z	z world coordinate

destructionShapeWorldToLocal

Destruction shape world space to local space transformation

function destructionShapeWorldToLocal(integer shapeId, integer destructionShapeIndex, boolean physicalPosition, float x, float y, float z)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape
boolean	physicalPosition	if true, the translation of the physics object is returned, otherwise the translation of the visual representation
float	x	x value of world position
float	y	y value of world position
float	z	z value of world position

float	x	x value of local position
float	y	y value of local position
float	z	z value of local position

destructionShapeLocalDirectionToWorld

Destruction shape local space to world space transformation, only direction without translation

function destructionShapeLocalDirectionToWorld(integer shapeId, integer destructionShapeIndex, boolean physicalPosition, float x, float y, float z)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape
boolean	physicalPosition	if true, the direction of the physics object is returned, otherwise the direction of the visual representation
float	x	x value of world direction
float	y	y value of world direction
float	z	z value of world direction

float	x	x value of local direction
float	y	y value of local direction
float	z	z value of local direction

destructionShapeWorldDirectionToLocal

Destruction shape world space to local space transformation, only direction without translation

function destructionShapeWorldDirectionToLocal(integer shapeId, integer destructionShapeIndex, boolean physicalPosition, float x, float y, float z)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape
boolean	physicalPosition	if true, the direction of the physics object is returned, otherwise the direction of the visual representation
float	x	x value of world direction
float	y	y value of world direction
float	z	z value of world direction

float	x	x value of local direction
float	y	y value of local direction
float	z	z value of local direction

getDestructionShapeCenterOfMass

Get the destruction shape center of mass

function getDestructionShapeCenterOfMass(integer shapeId, integer destructionShapeIndex)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape

float	x	x value of local position of the center of mass
float	y	y value of local position of the center of mass
float	z	z value of local position of the center of mass

getDestructionShapeMass

Get the destruction shape mass

function getDestructionShapeMass(integer shapeId, integer destructionShapeIndex)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape

float

mass

mass of the destruction shape

getDestructionShapeLinearVelocity

Get world space destruction shape linear velocity

function getDestructionShapeLinearVelocity(integer shapeId, integer destructionShapeIndex)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape

float	x	x value of velocity
float	y	y value of velocity
float	z	z value of velocity

getDestructionShapeAngularVelocity

Get world space destruction shape angular velocity

function getDestructionShapeAngularVelocity(integer shapeId, integer destructionShapeIndex)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape

float	x	x value of angular velocity
float	y	y value of angular velocity
float	z	z value of angular velocity

getDestructionMaxDamage

Get the maximal damage each destruction shape of the shape can receive until it breaks

function getDestructionMaxDamage(integer shapeId)

integer

shapeId

id of the shape

float

maxDamage

maximal damage

getDestructionShapeDamage

Get the current damage value of the given destruction shape

function getDestructionShapeDamage(integer shapeId, integer destructionShapeIndex)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape

float

damage

damage of the destruction shape

getDestructionShapeDamageRatio

Get the current damage ratio [0,1] of the given destruction shape

function getDestructionShapeDamageRatio(integer shapeId, integer destructionShapeIndex)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape

float

damageRatio

damageRatio [0,1] of the destruction shape

addDestructionShapeDamage

Add damage to the given destruction shape

function addDestructionShapeDamage(integer shapeId, integer destructionShapeIndex, float damage)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape
float	damage	amount of damage

deleteDestructionShape

Delete the given destruction shape

function deleteDestructionShape(integer shapeId, integer destructionShapeIndex)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape

getNumDestructionJoints

Get the number of joints the given shape has

function getNumDestructionJoints(integer shapeId)

integer

shapeId

id of the shape

integer

numJoints

number of joints between the destruction shapes

getNumRemainingDestructionJoints

Get the number of unbroken joints, the given shape currently has

function getNumRemainingDestructionJoints(integer shapeId)

integer

shapeId

id of the shape

integer

numRemainingJoints

number of unbroken joints between the destruction shapes

addDestructionShapeForce

Add force to the given destruction shape

function addDestructionShapeForce(integer shapeId, integer destructionShapeIndex, float x, float y, float z)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape
float	x	x value of world space force
float	y	y value of world space force
float	z	z value of world space force

addDestructionShapeImpulse

Add impulse to the given destruction shape

function addDestructionShapeImpulse(integer shapeId, integer destructionShapeIndex, float x, float y, float z)

integer	shapeId	id of the shape
integer	destructionShapeIndex	index of the destruction shape
float	x	x value of world space impulse
float	y	y value of world space impulse
float	z	z value of world space impulse

Spline Function Reference

getSplinePosition

Get spline position

function getSplinePosition(integer shapeId, float time)

integer	shapeId	id of curve shape object
float	time	time [0,1]

float	x	x coordinate
float	y	y coordinate
float	z	z coordinate

getSplineOrientation

Get spline orientation

function getSplineOrientation(integer shapeId, float time, float upDirX, float upDirY, float upDirZ)

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

float	rx	x rotation
float	ry	y rotation
float	rz	z rotation

getSplineLength

Get spline length

function getSplineLength(integer shapeId)

integer

shapeId

id of curve shape object

float

length

length of spline

getSplineNumOfCV

Get number of spline control vertices

function getSplineNumOfCV(integer shapeId)

integer

shapeId

id of curve shape object

integer

num

number of spline control vertices

getSplineCV

Get spline control vertex

function getSplineCV(integer shapeId, float time)

integer	shapeId	id of curve shape object
integer	index	control vertex index

float	x	control vertex x coordinate
float	y	control vertex y coordinate
float	z	control vertex z coordinate

Animation Function Reference

getAnimCharacterSet

Returns the character set driving the transform group

function getAnimCharacterSet(integer transformId)

integer

transformId

id of transform group

integer

id

id of character set object, 0 if no character set is assigned to the transform group

enableAnimTrack

Enable animation track

function enableAnimTrack(integer characterSetId, integer track)

integer	characterSetId	id of CharacterSet object
integer	track	track number

disableAnimTrack

Disable animation track

function disableAnimTrack(string characterSetId, integer track)

string	characterSetId	name of CharacterSet object
integer	track	track number

isAnimTrackEnabled

Is animation track enabled

function isAnimTrackEnabled(integer characterSetId, integer track)

integer	characterSetId	id of CharacterSet object
integer	track	track number

bool

state

enable state

setAnimTrackSpeedScale

Set animation track speed scale

function setAnimTrackSpeedScale(integer characterSetId, integer track, float speedScale)

integer	characterSetId	id of CharacterSet object
integer	track	track number
float	speedScale	speed scale

setAnimTrackLoopState

Set animation track loop state

function setAnimTrackLoopState(integer characterSetId, integer track, bool loopState)

integer	characterSetId	id of CharacterSet object
integer	track	track number
bool	loopState	loop scale

setAnimTrackTime

Set animation track time

function setAnimTrackTime(integer characterSetId, integer track, float time)

integer	characterSetId	id of CharacterSet object
integer	track	track number
float	time	time
bool	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

Get animation track time

function getAnimTrackTime(integer characterSetId, integer track)

integer	characterSetId	id of CharacterSet object
integer	track	track number

float

time

current time

getAnimClipDuration

Get the duration of the clip at the given index

function getAnimClipDuration(integer characterSetId, integer index)

integer	characterSetId	id of CharacterSet object
integer	index	clip index

float

duration

clip duration

setAnimTrackBlendWeight

Set animation track blend weight

function setAnimTrackBlendWeight(integer characterSetId, integer track, float weight)

integer	characterSetId	id of CharacterSet object
integer	track	track number
float	weight	blend weight

getAnimTrackBlendWeight

Get animation track blend weight

function getAnimTrackBlendWeight(integer characterSetId, integer track)

integer	characterSetId	id of CharacterSet object
integer	track	track number

float

weight

blend weight

getAnimClipIndex

Returns the index of the clip with the given name

function getAnimClipIndex(integer characterSetId, string clipName)

integer	characterSetId	id of CharacterSet object
string	clipName	the name of the clip to find

integer

index

index of the clip, -1 if clip was not found

assignAnimTrackClip

Assign clip to animation track

function assignAnimTrackClip(integer characterSetId, integer track, float clipIndex)

integer	characterSetId	id of CharacterSet object
integer	track	track number
float	clipIndex	clip index number

isAnimTrackClipAssigned

Is clip assigned to animation track

function isAnimTrackClipAssigned(integer characterSetId, integer track)

integer	characterSetId	id of CharacterSet object
integer	track	track number

bool

state

assigned state

getAnimTrackAssignedClip

Get animation track assigned clip index number

function getAnimTrackAssignedClip(integer characterSetId, integer track)

integer	characterSetId	id of CharacterSet object
integer	track	track number

float

clipIndex

clip index number

clearAnimTrackClip

Clear animation track clip assignment

function clearAnimTrackClip(integer characterSetId, integer track)

integer	characterSetId	id of CharacterSet object
integer	track	track number

getAnimNumOfClips

Get number of clips

function getAnimNumOfClips(integer characterSetId)

integer

characterSetId

id of CharacterSet object

float

clips

number of clips

Overlays Function Reference

createOverlay

Create image overlay object

function createOverlay(string overlayName, string textureFilename)

string	overlayName	overlay name
string	textureFilename	texture file name

deprecated, use createImageOverlay

createImageOverlay

Create overlay object

function createImageOverlay(string textureFilename)

string

textureFilename

texture file name

since v4.1.3

setOverlayColor

Set overlay color

function setOverlayColor(integer overlayId, float red, float green, float blue, float alpha)

integer	overlayId	overlay id
float	red	red value
float	green	green value
float	blue	blue value
float	alpha	alpha value

setOverlayUVs

Set overlay uv coordinates

function setOverlayUVs(integer overlayId, float u0, float v0, float u1, float v1, float u2, float v2, float u3, float v3)

integer	overlayId	overlay id
float	v0	v0 texture coodinate
float	u0	u0 texture coodinate
float	v1	v1 texture coodinate
float	u1	u1 texture coodinate
float	v2	v2 texture coodinate
float	u2	u2 texture coodinate
float	v3	v3 texture coodinate
float	u3	u3 texture coodinate

renderOverlay

Render overlay

function renderOverlay(integer overlayId, float x1, float y1, float width, float height)

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]

createVideoOverlay

Create video overlay object

function createVideoOverlay(string videoFilename, bool loopVideo, float soundVolume)

string	videoFilename	video file name
bool	loopVideo	loop video
float	soundVolume	sound volume [0,1]

since v4.1.3

playVideoOverlay

Play video overlay object

function playVideoOverlay(integer videoOverlayId)

integer

videoOverlayId

overlay id

since v4.1.3

stopVideoOverlay

Stop video overlay object

function stopVideoOverlay(integer videoOverlayId)

integer

videoOverlayId

overlay id