Every object has properties for position, rotation, scale, etc. You can access and modify these attributes in script.
Objects can be accessed via any of the following methods:-
object.<property> - property of the object the script is attached to.
objects.<object name>.<property> - property of the named object in the same scene as the script.
scenes.<scene name>.objects.<object name>.<property> - reference to a particular object in a particular scene from any script.
Properties
pos |
Current position of the object (Vector type). |
rot |
Current rotation of the object (Rotation type). |
scale |
Current scale of the object (Vector type). |
size |
Current size of the object (Vector type). |
timer |
A float value (in seconds) that increases with time passing. Can also be set to reset the timer. |
animation |
A string that represents the id of the current x file animation. |
sequence |
A string that represents the id of the current keyframe sequence. |
text |
For a text object, this represents the text string. |
textFont |
The font id used by a text object (font must be defined in the scene). |
textSize |
The size of the text in scene units. |
textAlign |
The alignment of the text, a string value of either "left","right", or "centre". |
textWrapWidth |
The width at which text will wrap onto multiple lines. |
visible |
Set to true if the object is to be drawn, false to hide it. |
posVelocity |
Delta position of the object per second (Vector type) |
rotVelocity |
Delta rotation of the object per second (Rotation type) |
rotvelocityOver |
A float determining how long (in seconds) the object takes to cover the rotation described in rotVelocity. This is usually 1.0, but if you want an object to rotate more quickly than 90 degrees per second, you should instead reduce this value rather than make rotVelocity any bigger. A rotation is a snapshot not a scalar value, so a full 360 rotation is back to the start, which would not then know which way to turn. |
opacity |
A float value between 0 and 1, where 0 is invisible and 1 is solid. |
fov |
Floating point value that represents the vertical field of view of a camera in radians. The default value is 0.78539. |
subgroups |
A collection of all the Subgroup objects inside a mesh object. |
effects |
A collection of all the effects applied to an object. |
posConstrain |
The id (string) of an object which is to be used to constrain the position of this object. The object to be used must have a mesh. |
posConstrainMargin |
The smallest distance this object can get to a face on the constraining object (always should be greater than zero). |
keyMoveSpeed |
Sets the speed in units per second for movement via the keyboard (float) |
keyMoveSoften |
Sets the amount to soften keyboard movement acceleration (float). |
posWorld |
Position of the object in world coordinates (not relative to the parent). |
radiusWorld |
Radius of a bounding sphere fully containing the object in world coordinates. |
boundingBoxMin |
Returns a Vector specifying the smallest world x,y,z position that the object occupies. |
boundingBoxMax |
Returns a Vector specifying the largest world x,y,z position that the object occupies. |
wireframe |
Boolean value that if true draws this object in wireframe mode (default is false). |
showBounds |
Boolean value that if true draws the bounding box around the object (default is false). |
shadowDynamicCast |
Boolean property determining when the object casts dynamic shadows on to itself or other objects. |
shadowDynamicShow |
Boolean property determining when the object shows dynamic shadows on it's surface. |
color |
Used in objects with a color, such as a light. |
animationTransitionPeriod |
Floating point value determining how quickly one animation changes to another. Defaults to 0.0 meaning the animation changes instantly. 1.0 would be over 1 second, etc. |
animationMergeTransitionPeriod |
Floating point value determining how quickly a merged animation is blended with the normal one. Defaults to 0.0 meaning the animation changes instantly. 1.0 would be over 1 second, etc. |
animationSpeed |
Floating point value that is a multiplier for the animation playbackspeed. Defaults to 1.0, 2.0 would be double speed, etc. |
faceCamera |
Set to true and the object will rotate itself automatically to face the camera. |
faceCameraLockVertical |
If faceCamera is true, this boolean value determines whether the object can rotate freely or is locked to the Y (vertical) axis. |
animationTimer |
Position of the current animation in seconds. |
offsetPos |
Usually used in conjunction with 'attach'. A Vector that will offset the position of the mesh before applying the attachment transformations. |
offsetRot |
Usually used in conjunction with 'attach'. A Rotation that will offset the rotation of the mesh before applying the attachment transformations. |
offsetScale |
Usually used in conjunction with 'attach'. A Vector that will offset the scale of the mesh before applying the attachment transformations. |
lookAt |
A string id of an object for this object to look at. Set to an empty string to stop looking. |
lookAtLockVertical |
If using lookAt and you set this to true, the lookAt operation will keep the object's Y pointing upwards. |
animationNext |
Sets the animation that will be played when the current one completes (string id). This is set to the same as 'animation' every time 'animation' is set, so you should set animationNext after. e.g. object.animation='Walk'; object.animationNext='Idle'; |
notifyCollision |
If set to true, the object will report collisions with other objects (onNotifyCollision event) with notifyCollision set to true. By default notifyCollisionCheckFaces will also be true, so a face by face comparison will be performed (you can improve the perfomance of this by using a separate low poly mesh for physics). |
notifyCollisionCheckFaces |
If set to true (and the object it's colliding with has this set to true) a face by face check will be performed. Otherwise, only the bounding box intersection check will be done. The default value is true. |
notifyCollisionTypes |
A string containing the types (mesh ids) comma separated to only check against for collision. |
alphaRef |
Integer value between 0 and 255 that can be used to override the scene's alphaRef property. If set this value determines at what level of alpha parts of the object are no longer drawn. Set higher to reduce problems with pixels around edges. |
alphaSort |
Boolean value, if true the individual faces are sorted for alpha correct drawing (slow). |
drawBackfaces |
If true the faces facing away from the camera are drawn (defaults to false). |
selectable |
If true, the object is part of the detection process for mouse input. |
selectionMask |
An integer with 31 bit resolution determining the selection mask. Bit 0 is the selectable value above (for mouse pick), but you can use the other bits as you choose. Combine with scene.selectionMask and scene.getObjectFromRay(). |
autoCursor |
If true, the cursor will be changed to a hand if the object is clickable. |
lat |
For use in the special GPS mode, this is the floating point latitude (N/S) of the object. |
lon |
For use in the special GPS mode, this is the floating point longitude of the object. |
altitude |
For use in the special GPS mode, this is the floating point altitude of the object above sea level. |
If the object is of type 'light', then this has further sub-properties; the sub-property 'type' is a string determining the type of light source, one of "point", "spot" or "directional". Booleans useLighting, useShadows, usePRT enable/disable the light for those different uses. Floats phi, theta, range, falloff, attenuation0/1/2 determine the charactistics of the light. |
|
If the object is a camera, then this has the sub-properties:- type (the type of camera in a string, "projection" or "ortho"), fovVertical (represents the vertical field of view of the projection camera in degrees - the default value is 45.0), fovHorizontal (represents the horizontal field of view in degrees), orthoZoom (a float determining the zoom of an ortho camera), lodDistanceScale (a float that is multiplied by every distance in a LOD detail calculation, so if you set it to zero every object will be drawn at maximum detail). You can also configure the listener properties for 3D sound - listenerMPU, listenerRolloff and listenerDoppler. |
|
A collection of properties if the object is of type 'emitter'. |
|
A collection of properties to control the object's movement along a path. |
|
A collection of properties to control the object's appearance for user interface purposes. |
|
A collection of properties to control the how the object is handled by the physics engine. |
|
control |
Provides access to all of the control functions and variables defined in the object if the object is of type 'control' or null if not. |
controlDefId |
A string identifier of the control definition. You can set this to set an object to be a control. |
localForward |
Vector that defines the local direction this object considers as 'forward'. Normally for a mesh this is (0,0,-1) as it's modelled facing the camera. This is used by the autoMoveXXX functions. |
localUp |
Vector that defines the local direction this object considers as 'up'. Normally this is (0,1,0). This is used by the autoMoveXXX functions. |
mesh |
Returns the Mesh attached to this model (set by object.type), or null if no mesh. |
skipUpdateWhenAreaInvisible |
Set this to true and the object won't have its onUpdate called if the area visibility settings declare it invisible. |
areaVisibility |
A string containing the effect cube object ids (comma separated) that determine where this object is visible from. |
xmlString |
A string containing all of the properties of the object and their values that can be stored in XML. Read this value to store the object, and set this value to write values back to the object. |
pivotPos |
Vector pivot position of the object in local coordinates before any other transforms are applied. |
autoMoveJumping |
Boolean that returns true if the object is in jump mode (normally set by a physics character controller). |
autoMoveFalling |
Boolean that returns true if the object is in falling mode (normally set by a physics character controller). |
drawOrder |
An integer that determines the order in which the object is drawn within the parent object. Useful in 2d to control the order in which objects are overlaid. |
maskObjectId |
For 2D bitmap objects, set this string to the other object id that you want to use as a mask for drawing this one (white pixels=show, black pixels=hide). |
crop |
For 2D bitmap objects, you can set crop properties x,y,width,height as integers in the bitmap's pixels to specify the crop rectangle. To enable cropping, set the crop.enable to true. |
Methods
createSequence("<sequence name>") |
Returns an empty keyframe Sequence object that will overwrite any existing sequence of the same name. Use this function to create run-time keyframe sequences. |
click() |
Simulates a mouse click on the object by calling the onClick() function (if present). |
animationGetArray() |
Returns a list of ids of mesh animations available for this object. |
sequenceGetArray() |
Returns a list of ids of sequences available for this object. |
subgroupGetArray() |
Returns a list of ids of all the subgroups inside a mesh object. |
canSee(objectid, [aspect, fov]) |
Used on camera objects. Pass a string identifier of an object, and it will return true if the camera can see the object. By default the function will assume the document's aspect ratio for the camera and pickup the fov from the camera itself. You can override these by optionally passing two floats for the aspect ratio and fov to use. |
shapeAddLine(vectorFrom, vectorTo, col) |
Draws a line (relative to the position of the object) between the two Vectors in the given Color. e.g. object.addShapeLine(new Vector(0,0,0), new Vector(100,0,0), new Color('#ff0000')); |
shapeAddTriangle(v0, v1, v2, col, fill) |
Draws a triangle (relative to the position of the object) between the three triangle Vectors in the given Color. If the optional fill paramter is set to true, the shape is solid. |
shapeAddRectangle(vtopleft, vtopright, vbottomleft, vbottomright, col, fill) |
Draws a rectangle (relative to the position of the object) between the four corner Vectors in the given Color. If the optional fill paramter is set to true, the shape is solid. |
shapeRemoveAll() |
Removes all shapes currently being drawn on the object. |
animationMergeAdd(id) |
Merges the given animation (by animation identifier string 'id') with the current animation on the object. |
animationMergeRemove(id) |
Removes the given animation from being merged with the current animation on the object. |
animationMergeSetPos(id,prop,play) |
Moves the animation (already added with animationMergeAdd) to the given floating point proportion along it's length 'prop' (between 0 and 1). If a boolean 'play' is set to true, it will play from this point, otherwise it will stay at this position. |
animationGetDuration(id) |
Returns the duration of the given animation in seconds. |
moveToGroup(groupid) |
Changes the group that the object is in to the one with the given string id. Set to an empty string to have no group.
|
attach(objid,subgroupid,attachpos,attachrot,attachscale) |
Attaches the pos/rot/scale of an object to another (with optional subgroup - set to an empty string to be the top level). The optional booleans attachpos/attachrot/attachscale define which properties are passed through (defaults to all true). |
attachedObjectGetArray() |
Returns an Array of Object types listing all objects currently attached to this one. |
animationSetPos(id, prop, play) |
Sets the animation position given by it's animation id string to the given amount (a float between 0 and 1 as a proportion of total play time). The optional last parameter is true or false, determining whether to play on from this point. |
sequenceSetPos(id, prop, play) |
Sets the sequence position given by it's sequence id string to the given amount (a float between 0 and 1 as a proportion of total play time). The optional last parameter is true or false, determining whether to play on from this point. |
nearestSurfacePosition(testPos) |
Returns a world position Vector of the highest point on the object below the Vector testPos. |
nearestSurfaceNormal(testPos) |
Returns a normal Vector of the normal to the surface at the highest point on the object below the Vector testPos. |
autoMoveForward(speed, force) |
All the autoMoveXXX functions allow you to control an object at a high level. The system determines whether to use physics commands or not. |
soundPlay(soundid) |
Plays the given sound attached to this object's 3D world position (sound must set to positioned in editor). |
soundStop(soundid) |
Stops the given sound if it's currently being played in this object's 3D world position. |
Accessing script functions/variables
You can also call functions defined in object script, or read/write variables. Just prefix the function/variable with 'script.' to access...
script.<variable>
script.<function>
e.g.
print(object.script.power); // print the variable 'power' defined in the script of the current object.
objects.myobj_2.script.runAway(); // call the function runAway() defined in the object myobj_2's script.
You can also change the whole script on an object at runtime by setting the object.script.sourceCode value. Note that when you change the script all variables defined in the script will be reset. onInit will not be called automatically, but you can call it manually if you need to set up your variables in that function with the call to object.script.onInit().
Examples
object.pos.x=100; // sets the x position of the object this script is written in to 100.
objects.camera_1.pos.x=200; // sets the x position of the camera_1 object to 200.
object.script.myTestFunction(); // calls the function defined in the current object.
print("Object health is "+object.script.health); // Prints the value of the variable 'health' defined in an object.
See Also


