-
Notifications
You must be signed in to change notification settings - Fork 138
CompositeSprite Guide
All scene objects are known engine types that allow instances to be created at runtime. The "CompositeSprite" is a powerful object that has many awesome uses. To start off with, it is derived from "SceneObject", which means it includes all the fields from that type as well as adding fields specific to itself.
A CompositeSprite is a sprite by name that is a composite of multiple other sprites "inside" it. These sprites can be placed in any location and can be of any size, orientation, blending, sort-point, scene-depth, etc. They can also be given a logical position and used as a tile layer to create what most people know as tilemaps. The following layout options are supported:
- No layout - the logical position you specify is the physical position.
- Rectilinear layout - the logical position you specify is mapped to a rectilinear position.
- Isometric layout - the logical position you specify is mapped to an isometric position.
- Custom layout - the logical position you specify is mapped (via a TorqueScript callback) to a custom position.
CompositeSprites are not just for tile mapping though. They can and should be used for creating complex composite "characters". In physics simulations, it may be tempting to join two sprites together with a weld joint for typical mounting functionality - but for a truly rigid connection you should use a CompositeSprite.
These objects are also very performant. They use batching and allow fast changes of any property of any sprite contained within them. They also provide fast render clipping for when a CompositeSprite is very large and has lots of off-screen sprites.
The CompositeSprite 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:
- DefaultSpriteStride
- setDefaultSpriteStride(float)
- getDefaultSpriteStride()
- DefaultSpriteSize
- setDefaultSpriteSize(float)
- getDefaultSpriteSize()
- DefaultSpriteAngle
- setDefaultSpriteAngle(float)
- getDefaultSpriteAngle()
- BatchLayout
- setBatchLayout(enum)
- getBatchLayout()
- BatchCulling
- setBatchCulling(bool)
- getBatchCulling()
- BatchIsolated
- setBatchIsolated(bool)
- getBatchIsolated()
- BatchSortMode
- setBatchSortMode(enum)
- getBatchSortMode()
The following is a complete description of each of these fields.
Sets the stride which scales the position at which sprites are created. This can be given as a single value which sets the stride for both the X and Y axis or two separate values to set each axis individually.
%object = new CompositeSprite();
%object.DefaultSpriteStride = "5 6";Sets the size at which sprites are created. This can be given as a single value that applies to both the width and height, or as two separate values respectively.
Sets the angle at which sprites are created in degrees.
This field sets the batch layout type. You can chose from the following options: "off", "rect", "iso", or "custom".
Sets whether the sprites are culled. For sprites that are off-screen this is considerably faster during render at the expense of memory. For small composites with only a few sprites, the overhead is probably not worth it.
Sets whether the sprites are rendered, isolated from other renderings as one separate batch or not. When in batch isolated mode, the sprites can be optionally sorted.
This field sets the batch render sort mode. The render sort mode is also used when isolated batch mode is on. The following options are available to choose from: "Off", "New", "Old", "Batch", "Group", "X", "Y", "Z", "-X", "-Y", "-Z". See the Batch Rendering Guide for more information on sorting.
Using TorqueScript and the exposed fields or methods described in the previous section, you can programmatically create and configure a CompositeSprite. 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 CompositeSprite TAML file in XML format:
<CompositeSprite
Position="-25 -25"
DefaultSpriteStride="10 10"
DefaultSpriteSize="10 10"
BatchLayout="rect">
<CompositeSprite.Sprites>
<Sprite
Image="ToyAssets:Tiles"
Frame="5"
Position="0 0"
Size="10 10"
LogicalPosition="0 0" />
<Sprite
Image="ToyAssets:Tiles"
Frame="5"
Position="10 0"
Size="10 10"
LogicalPosition="1 0" />
<Sprite
Image="ToyAssets:Tiles"
Frame="5"
Position="0 10"
Size="10 10"
LogicalPosition="0 1" />
<Sprite
Image="ToyAssets:Tiles"
Frame="5"
Position="10 10"
Size="10 10"
LogicalPosition="1 1" />
</CompositeSprite.Sprites>
</CompositeSprite>The same example in JSON format:
{
"CompositeSprite": {
"Position": "-25 -25",
"DefaultSpriteStride": "10 10",
"DefaultSpriteSize": "10 10",
"BatchLayout": "rect",
"CompositeSprite.Sprites": {
"Sprite[0]": {
"Image": "ToyAssets:Tiles",
"Frame": "5",
"Position": "0 0",
"Size": "10 10",
"LogicalPosition": "0 0"
},
"Sprite[1]": {
"Image": "ToyAssets:Tiles",
"Frame": "5",
"Position": "10 0",
"Size": "10 10",
"LogicalPosition": "1 0"
},
"Sprite[2]": {
"Image": "ToyAssets:Tiles",
"Frame": "5",
"Position": "0 10",
"Size": "10 10",
"LogicalPosition": "0 1"
},
"Sprite[3]": {
"Image": "ToyAssets:Tiles",
"Frame": "5",
"Position": "10 10",
"Size": "10 10",
"LogicalPosition": "1 1"
}
}
}
}The following methods are available to further configure and control a CompositeSprite.
Adds a sprite at the specified logical position. You must specify the correct number of arguments for the selected layout mode. The created sprite will be automatically selected.
Removes the selected sprite.
Removes all sprites in the composite.
Gets a count of all sprites in the composite.
Selects a sprite at the specified logical position.
Selects a sprite with the specified batch id.
Selects a sprite with the specified name.
Deselects any selected sprite. This is not required but can be used to stop accidental changes to sprites.
Checks whether a sprite is selected or not.
Sets the sprite image and optional frame.
Gets the sprite image.
Sets the sprite image frame.
Gets the sprite image frame.
Sets the selected sprite's frame by name instead of by number. This only works if the sprite's image is in explicit-cell mode, where each cell was given a name - see the ImageAsset Guide. A name is easier to live with than an index, because re-cutting the image doesn't silently change which picture you get.
Gets the selected sprite's named image frame.
Sets the sprite animation.
Gets the sprite animation.
Sets the sprite animation frame.
Gets the sprite animation frame.
Clears any image or animation asset from the sprite.
Sets whether the sprite is visible or not.
Gets whether the sprite is visible or not.
Sets the sprites local position.
Gets the sprites local position.
Gets the selected sprite's logical position - where it sits in the batch's own layout
scheme rather than in world units. For a batch laid out on a grid this is its cell, which is
what you gave when you added the sprite. Compare getSpriteLocalPosition, which answers in
ordinary units.
Sets the sprites local angle.
Gets the sprites local angle.
Sets the sprites depth.
Gets the sprites depth.
Sets the sprite size.
Gets the sprite size.
Sets whether the sprite is flipped along its local X axis or not.
Gets whether the sprite is flipped along its local X axis or not.
Sets whether the sprite is flipped along its local Y axis or not.
Gets whether the sprite is flipped along its local Y axis or not.
Sets the sprites sort point.
Gets the sprites sort point.
Sets the name of the render group used to sort the sprite during rendering. Defaults to nothing.
Gets the name of the render group used to sort the sprite during rendering.
Sets whether sprite blending is on or not.
Gets whether sprite blending is on or not.
Sets the sprite source blend factor. See the Blending guide for more information.
Gets the sprite source blend factor.
Sets the sprite destination blend factor. See the Blending guide for more information.
Gets the sprite destination blend factor.
Sets the sprite blend color.
Gets the sprite blend color.
Sets the sprite color alpha (transparency).
Gets the sprite color alpha (transparency).
Turns on complex color for the selected sprite: instead of one blend color over the
whole thing, each of its four corners gets its own. That is how you get a gradient across a
single sprite. Off by default, in which case the ordinary setSpriteBlendColor applies.
Whether the selected sprite is using complex color.
Sets all four corner colors at once, in that order. Each is a color in the usual forms -
"255 0 0 255" or a stock color name. Turn setSpriteUseComplexColor on first, or these
are ignored.
Gets one corner's color. The corners are numbered in the same order they are set: 0 top-left, 1 top-right, 2 bottom-right, 3 bottom-left.
Sets the sprite alpha test.
Gets the sprite alpha test.
Sets the sprite data object. This object will be persisted alongside the CompositeSprite. To clear the object, you can pass it an empty string.
Gets the sprite data object.
Attaches an arbitrary value to the selected sprite - a string of your own, meaning whatever you want it to mean. Useful for tagging one tile in a batch as special without keeping a separate lookup table alongside it.
setSpriteDataObject above does a similar job for a whole object; this one is for a plain
value.
Gets the value attached to the selected sprite.
Sets the sprite name.
Gets the sprite name.
Gets the batch id of the currently selected sprite. This is the id selectSpriteId takes,
so it is how you note down which sprite you are on and come back to it later.
Picks sprites intersecting the specified coordinates.
Picks sprites intersecting the specified area.
Picks sprites intersecting the specified ray.