Sprite

Introduction

The Sprite is a flat graphical object which is commonly used as the visuals for entities and for particles. Sprites can also be used to display tilemaps and UI, although Tiled and Gum provide more flexibility and performance. The Sprite class inherits from the PositionedObject class.

Sprites are usually created through the FlatRedBall Editor when associated with entities, although Sprites can also be created in code when dynamic visuals are needed.

Creating a Sprite in Code

In most cases, a Sprite can be created in code by instantiating it, assigning a texture, and adding it to the SpriteManager so that it is drawn. The following code assumes that TextureFile is a valid Texture2D:

// Creates a new Sprite instance
var sprite = new Sprite();
// Assigns the texture to display. 
sprite.Texture = TextureFile;
// Sets the Sprite's scale so that it renders 1:1 relative to its source Texture
sprite.TextureScale = 1;
// Adds the Sprite to the SpriteManager so that it is shown, and so that it is
// "managed" (velocity, acceleration, and attachments are maintained)
SpriteManager.AddSprite(sprite);

Once the Sprite has been created, it will persist until it is removed. If your game does not navigate to other Screens, and if you do not need to remove the Sprite, then no additional code is needed.

If you would like to remove your Sprite, you can call SpriteManager.RemoveSprite:

SpriteManager.RemoveSprite(sprite);

If you are creating a Sprite that is owned by a FlatRedBall Screen or Entity, then you will need to either:

• Explicitly call RemoveSprite when it is time to destroy the object containing the Sprite (usually CustomDestroy )

• Add the Sprite to a PositionedObjectList<Sprite> created in the FlatRedBall Editor on the container. When the container is removed, then the contents of the sprite list will automatically get removed from the engine.

Sprite Scale

For information on Scale, see the IScalable wiki entry. To match the on-screen pixel dimensions of a Sprite to its referenced Texture's pixel dimensions, see the 2D in FlatRedBall tutorial.

Texture

Sprites can be thought of as picture frames or canvases - they define how big a displayed image will be, its position, its rotation, and so on. However, the image or picture that they display is separate from the Sprite itself. This is an important realization because this often differs from other game engines where the image and the Sprite are one and the same at runtime. For more information, see the Sprite.Texture page.

Color and Alpha

For information on color and alpha operations (blending), see the IColorable wiki entry.

Z Buffered Sprites

Using a Z Buffer allows Sprites to properly overlap. For more information, see the Z Buffered Sprites wiki entry.

Particle Sprites

Particle Sprites are created through the SpriteManager just like other Sprites. Particle Sprites are created from a pool of Sprites that is created when the engine is first initiated. The following code creates a particle Sprite:

Sprite newSprite = SpriteManager.AddParticleSprite();

Particle Sprites have all of the same functionality as regular Sprites - in fact, they are just Sprites. The only difference is that there is minimal memory allocation and garbage collection so they can be useful when creating particle effects. Particle Sprites are used by Emitters.