object.<...>

Return to Introduction  Previous page  Next page

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.

 

light

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.

camera

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.

emitter

A collection of properties if the object is of type 'emitter'.

path

A collection of properties to control the object's movement along a path.

ui

A collection of properties to control the object's appearance for user interface purposes.

physics

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

 

system



Copyright ©2004 Worldweaver Ltd. DX Studio Home