-
Notifications
You must be signed in to change notification settings - Fork 1.6k
SceneObject Guide
NOTE: This guide is still a work in progress. The field listings are correct but some are still missing descriptions.
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.
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
- CollisionOneWay
- setCollisionOneWay (bool) / getCollisionOneWay
The following is a complete description of each of these fields.
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;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.
See the Physics Guide for more information on this field.
See the Physics Guide for more information on this field.
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.
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.
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.
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.
See the Physics Guide for more information on this field.
See the Physics Guide for more information on this field.
See the Physics Guide for more information on this field.
See the Physics Guide for more information on this field.
See the Physics Guide for more information on this field.
See the Physics Guide for more information on this field.
See the Physics Guide for more information on this field.
See the Blending Guide for more information on this field.
See the Blending Guide for more information on this field.
See the Blending Guide for more information on this field.
See the Blending Guide for more information on this field.
See the Blending Guide for more information on this field.
Get or sets if one way collisions will be used for edge or chain shapes connected to this object.
Besides sounding cool, chronological target functions are functions that gradually change some value of the object until it arrives at a target value. There are currently four categories of these functions to change the object's position, rotation, blend color, and size.
Moves an object in the direction of the point at a certain speed. If autoStop is true then object will stop when it is within a certain distance of the point. If snapToTarget is true then the object will be placed at the point when it is within a certain distance of the point. And finally you can set that distance with the margin. Finally, a callback is issued when the object reaches the point.
You should note that the object can be stopped from reaching the point by other forces such as a collision for example. The object will continue to check to see if it has reach the point unless it starts moving away from the point. If it starts to move away then it will give up and no longer check to see if it has reached the point.
Cancels a previous MoveTo command. MoveTo commands are automatically cancelled if the object starts to move away from the target position. If the autoStop is true then the object will stop.
Returns true if the object is not currently seeking a target position.
Rotates an object toward a certain angle given in degrees at a given rotational velocity. If autoStop is true then the object will stop rotating when it reaches the desired angle. When first called the object will calculate the amount of time it should take to finish the rotation. If warpToTarget is true then it will automatically set the object's angle to the desired angle after the correct amount of time has passed. A callback is issued when the object reaches the target angle.
It is possible for other forces to slow or otherwise affect the rotation of the object. In these cases, warpToTarget could cause the object to "jump" to a certain angle.
Cancels a previous RotateTo command. If autoStop is true then the object will stop rotating.
Returns true if the object is not currently waiting for a rotateTo command to complete.
Sets the rate at which the blend color values will change per second until they reach the target color. Color values will continue to change until the fade is canceled or they arrive at the target color. A callback is produced when the target color is reached.
This function will set the rate of each color value to the same rate so some values might arrive at the target color value before the others. This might cause the blend color of the object not to smoothly adjust from one color to another.
Sets the amount of time in milliseconds that each color value will take to reach the target color. Color values will continue to change until the fade is canceled or they arrive at the target color. A callback is produced when the target color is reached.
Since all color values arrive at the target color at the same time, this might lead to a smoother fade from one color to another.
Stops an object from fading any further to reach the target color.
Returns true if an object is not currently fading towards a target color.
Sets the rate at which the size of an object will change in the x and y directions until it reaches a target size. The size will continue to change by the rate until both values have reached the correct size even if the size is changed directly again. A callback will be produced when both values reach the target size.
This will not affect the size of collision shapes attached to the object. Collision shapes will need to be removed and recreated to change their size so use with caution.
Sets the amount of time in milliseconds that both size values will take to reach the target size. This sets the rates for each value so that they both arrive at the target at approximately the same time, however, it is possible to change the size directly again, which will change the amount of time it takes to reach the target size. When both values reach the target size a callback will be produced.
This will not affect the size of collision shapes attached to the object. Collision shapes will need to be removed and recreated to change their size so use with caution.
Stops an object from growing any further to reach the target size.
Returns true if an object is not currently growing towards a target size.
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:
There are nearly 200 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 category 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:
Attaches a GuiControl to the object.
Detaches any GuiControl from the object.
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.
Sets debug flags for the object to on as determined by the enum.
Sets debug flags for the object to off as determined by the enum.
Safely deletes the object.