Skip to content

CompositeSprite Guide

Jump to bottom
Peter Robinson edited this page Oct 27, 2015 · 2 revisions

Introduction

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.

TorqueScript Bindings

Exposed Fields

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.

DefaultSpriteStride (float)

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";

DefaultSpriteSize (float)

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.

DefaultSpriteAngle (float)

Sets the angle at which sprites are created in degrees.

BatchLayout (enum)

This field sets the batch layout type. You can chose from the following options: "off", "rect", "iso", or "custom".

BatchCulling (bool)

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.

BatchIsolated (bool)

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.

BatchSortMode (enum)

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.

TAML Format

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"
            }
        }
    }
}

Additional API

The following methods are available to further configure and control a CompositeSprite.

addSprite (a b [c] [d] [e] [f])

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.

removeSprite ()

Removes the selected sprite.

clearSprites ()

Removes all sprites in the composite.

getSpriteCount ()

Gets a count of all sprites in the composite.

selectSprite (a b [c] [d] [e] [f])

Selects a sprite at the specified logical position.

selectSpriteId (int)

Selects a sprite with the specified batch id.

selectSpriteName (name)

Selects a sprite with the specified name.

deselectSprite ()

Deselects any selected sprite. This is not required but can be used to stop accidental changes to sprites.

isSpriteSelected ()

Checks whether a sprite is selected or not.

setSpriteImage (imageAssetId, [int imageFrame])

Sets the sprite image and optional frame.

getSpriteImage ()

Gets the sprite image.

setSpriteImageFrame (int)

Sets the sprite image frame.

getSpriteImageFrame ()

Gets the sprite image frame.

setSpriteAnimation (animationAssetId)

Sets the sprite animation.

getSpriteAnimation ()

Gets the sprite animation.

setSpriteAnimationFrame (int)

Sets the sprite animation frame.

getSpriteAnimationFrame ()

Gets the sprite animation frame.

clearSpriteAsset ()

Clears any image or animation asset from the sprite.

setSpriteVisible (bool)

Sets whether the sprite is visible or not.

getSpriteVisible ()

Gets whether the sprite is visible or not.

setSpriteLocalPosition (float localX, float local Y)

Sets the sprites local position.

getSpriteLocalPosition ()

Gets the sprites local position.

setSpriteAngle (float)

Sets the sprites local angle.

getSpriteAngle ()

Gets the sprites local angle.

setSpriteDepth (float)

Sets the sprites depth.

getSpriteDepth ()

Gets the sprites depth.

setSpriteSize (float width, [float height])

Sets the sprite size.

getSpriteSize ()

Gets the sprite size.

setSpriteFlipX (bool)

Sets whether the sprite is flipped along its local X axis or not.

getSpriteFlipX ()

Gets whether the sprite is flipped along its local X axis or not.

setSpriteFlipY (bool)

Sets whether the sprite is flipped along its local Y axis or not.

getSpriteFlipY ()

Gets whether the sprite is flipped along its local Y axis or not.

setSpriteSortPoint (float localX, float localY)

Sets the sprites sort point.

getSpriteSortPoint ()

Gets the sprites sort point.

setSpriteRenderGroup (renderGroup)

Sets the name of the render group used to sort the sprite during rendering. Defaults to nothing.

getSpriteRenderGroup ()

Gets the name of the render group used to sort the sprite during rendering.

setSpriteBlendMode (bool)

Sets whether sprite blending is on or not.

getSpriteBlendMode ()

Gets whether sprite blending is on or not.

setSpriteSrcBlendFactor (srcBlend)

Sets the sprite source blend factor. See the Blending guide for more information.

getSpriteSrcBlendFactor ()

Gets the sprite source blend factor.

setSpriteDstBlendFactor (dstBlend)

Sets the sprite destination blend factor. See the Blending guide for more information.

getSpriteDstBlendFactor ()

Gets the sprite destination blend factor.

setSpriteBlendColor (float red, float green, float blue, [float alpha]) or (stockColorName)

Sets the sprite blend color.

getSpriteBlendColor

Gets the sprite blend color.

setSpriteBlendAlpha (float alpha)

Sets the sprite color alpha (transparency).

getSpriteBlendAlpha ()

Gets the sprite color alpha (transparency).

setSpriteAlphaTest (float alpha)

Sets the sprite alpha test.

getSpriteAlphaTest ()

Gets the sprite alpha test.

setSpriteDataObject (object)

Sets the sprite data object. This object will be persisted alongside the CompositeSprite. To clear the object, you can pass it an empty string.

getSpriteDataObject ()

Gets the sprite data object.

setSpriteName (string)

Sets the sprite name.

getSpriteName ()

Gets the sprite name.

pickPoint (float X, float Y)

Picks sprites intersecting the specified coordinates.

pickArea (float startX, floatStartY, float endX, float endY)

Picks sprites intersecting the specified area.

pickRay (float startX, floatStartY, float endX, float endY)

Picks sprites intersecting the specified ray.

Clone this wiki locally