Skip to content

SceneObject Guide

Jump to bottom
Mike Lilligreen edited this page Feb 9, 2014 · 3 revisions

NOTE: This guide is still a work in progress. The field listings are correct but some are still missing descriptions.

Introduction

All scene objects are known engine types that allow instances to be created at runtime. The "SceneObject" is the most basic object that can be added to a Scene. It contains all of the core properties for position, size, layering, physics, etc. It also has a few properties that control rendering but these are used only in children objects like Sprite. A SceneObject itself is invisible and can only be seen using debug rendering.

TorqueScript Bindings

Exposed Fields

The SceneObject type exposes the following fields in addition to those it inherits. Shown are the equivalent methods available that perform the same action in setting and getting the respective field:

  • Lifetime
  • setLifetime (float) / getLifetime
  • SceneLayer
  • setSceneLayer (int) / getSceneLayer
  • SceneLayerDepth
  • setSceneLayerDepth (float) / getSceneLayerDepth
  • SceneGroup
  • setSceneGroup (int) / getSceneGroup
  • Size
  • setSize (float) / getSize
  • Position
  • setPosition (float) / getPosition
  • Angle
  • setAngle (float) / getAngle
  • FixedAngle
  • setFixedAngle (float) / getFixedAngle
  • BodyType
  • setBodyType (enum) / getBodyType
  • Active
  • setActive (bool) / getActive
  • Awake
  • setAwake (bool) / getAwake
  • Bullet
  • setBullet (bool) / getBullet
  • SleepingAllowed
  • setSleepingAllowed (bool) / getSleepingAllowed
  • CollisionGroups
  • setCollisionGroups (int) / getCollisionGroups
  • CollisionLayers
  • setCollisionLayers (int) / getCollisionLayers
  • CollisionSuppress
  • setCollisionSuppress (bool) / getCollisionSuppress
  • GatherContacts
  • setGatherContacts (bool) / getGatherContacts
  • DefaultDensity
  • setDefaultDensity (float) / getDefaultDensity
  • DefaultFriction
  • setDefaultFriction (float) / getDefaultFriction
  • DefaultRestitution
  • setDefaultRestitution (float) / getDefaultRestitution
  • LinearVelocity
  • setLinearVelocity (float) / getLinearVelocity
  • AngularVelocity
  • setAngularVelocity (float) / getAngularVelocity
  • LinearDamping
  • setLinearDamping (float) / getLinearDamping
  • AngularDamping
  • setAngularDamping (float) / getAngularDamping
  • GravityScale
  • setGravityScale (float) / getGravityScale
  • Visible
  • setVisible (bool) / getVisible
  • BlendMode
  • getBlendMode (bool) / getBlendMode
  • SrcBlendFactor
  • setSrcBlendFactor (enum) / getSrcBlendFactor
  • DstBlendFactor
  • setDstBlendFactor (enum) / getDstBlendFactor
  • BlendColor
  • setBlendColor (float) or (stockColorName) / getBlendColor
  • AlphaTest
  • setAlphaTest (float) / getAlphaTest
  • SortPoint
  • setSortPoint (float) / getSortPoint
  • RenderGroup
  • setRenderGroup (string) / getRenderGroup
  • UseInputEvents
  • setUseInputEvents (bool) / getUseInputEvents
  • PickingAllowed
  • setPickingAllowed (bool) / getPickingAllowed
  • UpdateCallback
  • setUpdateCallback (bool) / getUpdateCallback
  • CollisionCallback
  • setCollisionCallback (bool) / getCollisionCallback
  • SleepingCallback
  • setSleepingCallback (bool) / getSleepingCallback
  • Scene
  • addToScene (scene) / removeFromScene (scene) / getScene

The following is a complete description of each of these fields.

Lifetime (float)

Sets the objects lifetime. This is the amount of time, in seconds, before the object is automatically deleted. By default, objects have an "infinite" life and are only deleted when manually scripted to do so or when the Scene they are contained within is destroyed.

%object = new SceneObject();
%object.Lifetime = 10;

SceneLayer (int)

There are 32 scene layers available in Torque 2D numbered from 0 to 31. This controls the rendering order along the Z axis, with 0 being the top most layer and 31 being the bottom most.

SceneLayerDepth

SceneGroup

Size (float)

Position (float)

See the Physics Guide for more information on this field.

Angle (float)

See the Physics Guide for more information on this field.

FixedAngle (bool)

This field determines whether the angle (specified in the Angle field) stays fixed or not. When true, the object will always dispay at this angle and no outside force from the physics simulation can change it. The default is false.

BodyType (enum)

The body type of the object is used for the physics simulation. You can choose between static, dynamic, and kinematic. The default body type is dynamic. See the Physics Guide for more information on this field.

Active (bool)

This field determines whether the object is part of the physics simulation or not. Default is true (i.e. active). See the Physics Guide for more information on this field.

Awake

Physics bodies have the ability to be either awake or asleep. The default condition is for the object to be awake. See the Physics Guide for more information on this field.

Bullet

See the Physics Guide for more information on this field.

SleepingAllowed

See the Physics Guide for more information on this field.

CollisionGroups

See the Physics Guide for more information on this field.

CollisionLayers

See the Physics Guide for more information on this field.

CollisionSuppress

See the Physics Guide for more information on this field.

GatherContacts

See the Physics Guide for more information on this field.

DefaultDensity

DefaultFriction

DefaultRestitution

LinearVelocity

AngularVelocity

LinearDamping

AngularDamping

GravityScale

See the Physics Guide for more information on this field.

Visible

BlendMode

See the Blending Guide for more information on this field.

SrcBlendFactor

See the Blending Guide for more information on this field.

DstBlendFactor

See the Blending Guide for more information on this field.

BlendColor

See the Blending Guide for more information on this field.

AlphaTest

See the Blending Guide for more information on this field.

SortPoint

RenderGroup

UseInputEvents

PickingAllowed

UpdateCallback

CollisionCallback

SleepingCallback

Scene

TAML Format

Using TorqueScript and the exposed fields or methods described in the previous section, you can programmatically create and configure a SceneObject. You can then export this type to a TAML file or even create a TAML file manually and read it into your game at an appropriate time.

Here is an example SceneObject TAML file in XML format:



The same example in JSON format:




Additional API


There are 182 script methods available to configure and control a SceneObject. Many of them are set/get methods to exposed fields as detailed above, along with variants that alter those fields in one way or another. For example, let's take the LinearVelocity field:


    

  • setLinearVelocity / getLinearVelocity - sets/gets the linear velocity for both the X and Y axis
    • 

  • setLinearVelocityX / getLinearVelocityX - sets/gets the linear velocity for the X axis only
    • 

  • setLinearVelocityY / getLinearVelocityY - sets/gets the linear velocity for the Y axis only
    • 

  • setLinearVelocityPolar / getLinearVelocityPolar - sets/gets the linear velocity using an angle and speed
    • 

  • getLinearVelocityFromWorldPoint / getLinearVelocityFromLocalPoint - gets the linear velocity from a world or local point
    • 



1 field has 10 different methods associated with it. Not all fields have this many variants though.


Another catagory of methods that fall under the SceneObject domain have to do with collision shapes and their properties. See the Physics Guide for more details on how to setup collision shapes and use them.


The following is a non-exhaustive list of methods that are available to use that don't fall into the above catagories:


attachGui (guiObject, window, [sizeControl])


Attaches a GuiControl to the object.


detachGui


Detaches any GuiControl from the object.


copyFrom (object, [copyDynamicFields])


Copies one scene object from another scene object. The object being copied needs to be of the same class as the object being copied from.


moveTo (worldPoint X/Y, speed, [autoStop], [warpToTarget])


rotateTo (angle, speed, [autoStop], [warpToTarget])


cancelMoveTo ([autoStop])


cancelRotateTo ([autoStop])


isMoveToComplete ()


isRotateToComplete ()


setDebugOn (enum)


setDebugOff (enum)


safeDelete ()


Safely deletes the object.


              


          



  
          

            


            
Clone this wiki locally