-
Notifications
You must be signed in to change notification settings - Fork 137
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
- setSceneLayerDepthFront () / setSceneLayerDepthBack ()
- setSceneLayerDepthForward () / setSceneLayerDepthBackward ()
- SceneGroup
- setSceneGroup (int) / getSceneGroup
- Size
- setSize (float) / getSize
- setSizeX (float) / getSizeX — setSizeY (float) / getSizeY
- setWidth (float) / getWidth — setHeight (float) / getHeight
- Position
- setPosition (float) / getPosition
- getPositionX () / getPositionY ()
- 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
- setBlendMode (bool) / getBlendMode
- SrcBlendFactor
- setSrcBlendFactor (enum) / getSrcBlendFactor
- DstBlendFactor
- setDstBlendFactor (enum) / getDstBlendFactor
- BlendColor
- setBlendColor (float) or (stockColorName) / getBlendColor
- AlphaTest
- setAlphaTest (float) / getAlphaTest
- SortPoint
- setSortPoint (float) / getSortPoint
- setSortPointX (float) / getSortPointX — setSortPointY (float) / getSortPointY
- 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.
Where the object sits within its scene layer. SceneLayer decides which of the 32 layers an object is drawn in; SceneLayerDepth decides the order of the objects inside that one layer. A lower depth draws in front.
You usually don't want to pick a number. Four methods move an object relative to whatever else is already in the layer, which is what you actually mean most of the time:
- setSceneLayerDepthFront() - Move to the very front of this layer.
- setSceneLayerDepthBack() - Move to the very back of this layer.
- setSceneLayerDepthForward() - Move one place forward, in front of whichever object was immediately ahead.
- setSceneLayerDepthBackward() - Move one place back.
Each returns true if it actually moved the object — an object already at the front reports false when you send it forward again.
This is the "bring to front / send to back" you'd find in a drawing program. Picking up a card in a card game, or having a character walk in front of another, is this and not a layer change.
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.
Size sets how big an object is, but there are several ways to ask where its edges
actually are. All of these work in world units, not pixels.
The object's width or height on its own. setWidth (float) and setHeight (float) change
one without disturbing the other — handy when only one dimension should follow something.
getSizeX / getSizeY and setSizeX / setSizeY are the same thing under different
names; both pairs exist and either is fine.
Whether the object works out its own size. Some objects do — a Sprite showing an image, for
instance, can take its size from the image. You cannot set the size of an object that
sizes itself, so if setSize appears to do nothing, ask this first.
The object's rectangle, given as two corners rather than a position and a size.
getArea returns all four numbers as "x1 y1 x2 y2"; getAreaMin returns just the lower
left corner and getAreaMax just the upper right.
Setting the area positions and sizes the object in one call, which is convenient when you know where the corners should land — fitting an object to a room, say.
The object's axis-aligned bounding box: the smallest upright rectangle that still
contains the object once it has been rotated. Returned as "lowerX lowerY upperX upperY".
A rotated object's area and its bounding box are different rectangles — turn a long thin object 45 degrees and its bounding box grows even though the object hasn't. This is the one to use for rough "are these two anywhere near each other" tests.
Whether a world point is inside the object's oriented bounding box — the rectangle that
turns with the object, unlike getAABB. True or false.
Whether a world point is inside one particular collision shape. More precise than the box test above, since it uses the real shape.
How much area one collision shape covers. See the Physics Guide for how shapes are created and numbered.
Deletes every collision shape on the object at once, rather than removing them one at a time.
These come from the physics simulation, so they only mean anything once the object is in a Scene. Both return zero for an object that isn't, which is the usual explanation for a surprising zero.
The total mass of the body, worked out from its collision shapes and their densities. An object with no collision shapes has no mass.
How much the body resists being spun, around its own origin (in Kg-m²). The rotational equivalent of mass.
How many sounds are currently attached to and playing from this object.
Removes every GUI control attached to the object in one call. Useful when tearing an object
down — see onRemove in
the TorqueScript conventions.