Introduction

The Top, Bottom, Left, and Right properties return the X or Y values (as appropriate) of the edges of the Sprite in absolute coordinates. These values are equal to adding half of the width or height to the X or Y of the Sprite, but are provided for convenience.

Getting values

The following code example shows how to use the four edge values to position four Sprites. It assumes a Sprite named LogoSprite:

Circle topCircle = ShapeManager.AddCircle();
topCircle.Radius = 16;
topCircle.Y = LogoSprite.Top;

Circle bottomCircle = ShapeManager.AddCircle();
bottomCircle.Radius = 16;
bottomCircle.Y = LogoSprite.Bottom;

Circle leftCircle = ShapeManager.AddCircle();
leftCircle.Radius = 16;
leftCircle.X = LogoSprite.Left;

Circle rightCircle = ShapeManager.AddCircle();
rightCircle.Radius = 16;
rightCircle.X = LogoSprite.Right;

The AnimationChains property defines the AnimationChains used by the Sprite. This can be assigned in code or in the FlatRedBall Editor. For more information on working with AnimationChains in code, see the IAnimationChainAnimatable AnimationChains page.

Introduction

Many situations in game development can be simplified by changing the origin of an object (such as a Sprite). For example, you may make a tank turret Sprite, but the turret should not necessarily rotate around its center, but rather about the "base" of the turret. Another example may be a game where the player controls a character (such as a 2D platformer). In this situation you may want to make the origin of the Character at his feet. Unfortunatley, Sprites cannot have their origin simply changed. The center of a Sprite defines its rotation and the Scale values measure from the middle of the Sprite outward. However, shifting the origin can easily be simulated by using a PositionedObject as a parent and setting relative values.

For Glue Users

If you are using Glue, then most of your Sprites are probably already attached to Entities, which are PositionedObjects. Therefore, if you want to re-define the "center" of a Sprite, simply open the SpriteEditor for the given Entity and reposition the Sprite. The Sprite will be positioned with an offset so that the Sprite will be offset from the Entity's position.

For code users

If you are using code, then you will want to do the following:

1. Create a PositionedObject

2. Attach the Sprite to the PositionedObject

3. Set the offset using relative values

4. Control using the Entity

For example, your code may look like this:

// Assuming mySprite is a valid Sprite:
PositionedObject parent = new PositionedObject();
mySprite.AttachTo(parent, false);
mySprite.RelativeX = 3; // this gives the Sprite an X offset of 3 units
mySprite.RelativeY = 2; // this gives the Sprite a Y offset of 2 units
SpriteManager.AddPositionedObject(parent); // this makes the PositionedObject updated
// Now simply control "parent" and the Sprite will follow

Introduction

The Alpha value controls the opacity of a Sprite. A value of 1 (default) results in a fully-opaque Sprite, while a value of 0 is a fully-transparent Sprite. For more information see the Alpha property on IColorable. Sprite Alpha can be also be set in Glue directly and through states. Sprites can also be made fully invisible by setting the FlatRedBall.Sprite.Visible property to false.

Code Example

The following shows how to make a Sprite fully transparent:

SpriteInstance.Alpha = 0;

The following shows how to make a Sprite fully opaque:

SpriteInstance.Alpha = 1;

The following shows how to make a Sprite half opaque:

SpriteInstance.Alpha = .5f;

Sprite implements the IAnimationChainAnimatable interface. For more information, see the IAnimationChainAnimatable.CurrentFrameIndex page.

Sets the current AnimationChain based on its name. The AnimationChain must be part of the Sprite's AnimationChains. For more information on working with the CurrentChainName property, see the IAnimationChainAnimatable CurrentChainName page.

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.

The JustCycled returns true when the Sprite has just finished its animation and has cycled (returned from the last frame to the first). This can be used to perform logic when a Sprite has looped its animation. For more information, see the IAnimationChainAnimatable.JustCycled page.

In general it is not recommended to inherit from the Sprite class. This can reslt in cluttered interfaces and improper instantiation of objects. Instead, we recommend using the Entity pattern for your game objects. However, if you are sure that inheriting from the Sprite class is the only solution to your problem, you can do so by instantiating an object using your derived class, then adding it to the SpriteManager. Assuming DerivedSprite is a class which inherits from the Sprite class, the following code can be used to add a newly created instance of the derived class to the SpriteManager and assign its texture.

DerivedSprite derivedSprite = new DerivedSprite();
derivedSprite.Texture = FlatRedBallServices.Load<Texture2D>("redball.bmp");
SpriteManager.AddSprite(derivedSprite);

Controls the playback speed of animations when the Sprite is displaying an AnimationChain. For more information, see the IAnimationChainAnimatable AnimationSpeed page.

For information on ColorOperation, see the IColorable.ColorOperation page.

Introduction

The AnimateSelf function updates advances a Sprite through its animation (if it is animated) and updates the Sprite's Texture and texture coordinates according to its current animation. Sprites which are updated automatically (default) will automatically have this function called by the SpriteManager. Typically you only need to manually call this if a Sprite has been converted to manually updated, but it should still be animated.

Code Example

Typicalily the AnimateSelf function takes the TimeManager.CurrentTime value. The following code would animate a Sprite:

// assuming the Sprite SpriteInstance exists:
SpriteInstance.AnimateSelf(TimeManager.CurrentTime);

OBSOLETE The PixelSize property is an obsolete property which was commonly used prior to summer 2013. The TextureScale property has replaced the PixelSize property. The PixelSize property is equivalent to TexutureScale/2. The PixelSize property was originally created to work well with ScaleX and ScaleY values, but since then FlatRedBall.Sprite.TextureScale, Width, and Height have replaced PixelSize, ScaleX, and ScaleY as the most common ways to interact with a Sprite.

Introduction

The IgnoreAnimationChainTextureFlip property can be used to control whether a Sprite's FlipHorizontal and FlipVertical values are changed by the current AnimationChain. This value defaults to true, meaning that a Sprite's current AnimationChain will overwrite the Sprite's FlipHorizontal and FlipVertical when the frame changes. In other words, if IgnoreAnimationChainTextureFlip is true (default value), and a Sprite is using an AnimationChain, then the FlipHorizontal and FlipVertical will be overwritten by the AnimationChain so they should not be manually set.

Code Example

The following code assigns a Sprite instance's CurrentChainName property to "Walk" , but tells the sprite to not apply the AnimationFrame.FlipHorizontal value:

// assume SpriteInstance is a valid Sprite with AnimationChains containing "WalkRight"

SpriteInstance.IgnoreAnimationChainTextureFlip = true;
SpriteInstance.CurrentChainName = "WalkRight";

Usage Discussion

The IgnoreAnimationChainTextureFlip value is often used to prevent an AnimationChain from controlling a Sprite instance's FlipHorizontal value. It also prevents the FlipVertical value from being modified, but FlipHorizontal value is more commonly used to face a character left or right in a side-view game. Games including characters which can face to the left or right have two options for flipping the visuals:

1. Create two AnimationChains - one facing left and one facing right. Since each frame can flip the sprite, the left and right-facing animations can use the same source images/sprite sheets.

2. Create a single AnimationChain, but control Sprite.FlipHorizontal in code.

The first approach lets the AnimationChain (.achx) file fully control the visuals of the sprite. This means that the walk left vs. walk right may simply be flipped, or it means that different animations can be created for each direction. For example, if the character carries a sword, the sword may be in front of the character when walking one direction, but behind the character when walking the other direction. The second approach can be easier to implement in code since it does not require additional content (modifications to the .achx file). Developers are encouraged to use the first approach as it does not introduce any performance penalty, and allows content to be modified without any code at a future time.

Introduction

The TopTextureCoordinate, BottomTextureCoodinate, LeftTextureCoordinate, and RightTextureCoordinate properties control the coordinates in "uv space" of the top, bottom, left, and right sides of the Sprite. In other words, these values can be used to make a Sprite draw part of a texture instead of the entire thing. These properties are often used when working on games that use sprite sheets. The default values are as follows:

• TopTextureCoordinate = 0

• BottomTextureCoordinate = 1

• LeftTextureCoordinate = 0

• RightTextureCoordinate = 1

What are "texture coordinates" and how do they compare to pixels

Texture coordinates are often used in games (not just FlatRedBall) to measure points on a texture. Texture coordinates are often displayed as two values separated by commas within parenthesis. For example:

(0, 0)

and

(.75, .25)

The texture coordinate is a coordinate which measures location on a texture, but this coordinate does not use pixels. For example, if you're used to using pixels, you may be familiar with (0,0) being the top-left of an image. If your image is 32 pixels tall and 32 pixels wide, then the bottom-right of the image would be (32, 32). In texture coordinates, the top left is (0, 0). The bottom-right is (1, 1). You can think of texture coordinates as representing a percentage. In other words, a value of 0 means 0%. 1 means 100%. A value of 0.5 means 50%. Therefore, a value of (.5, 0) means "50% of the width (starting at the left) and 0% of the height (starting at the top). Therefore, the very center of the image is (.5, .5).

Code example

Texture coordinates can be adjusted to create objects which show only part of a texture, such as health bars. The following code shows how to create a Diablo-like health meter (of course, using a red ball): Files used:

Add the following at class scope:

Sprite mFrameSprite;
Sprite mFillSprite;
float mFillRatio = 1;

Add the following to Initialize after initializing FlatRedBall:

SpriteManager.Camera.UsePixelCoordinates(false);

mFillSprite = SpriteManager.AddSprite("content/fill.png");
mFrameSprite = SpriteManager.AddSprite("content/frame.png");

// Let's make them pixel perfect.
// PixelSize is a reactive property, and it reacts
// to texture coordinate changes too.  This means that
// we just have to change the texture coordinates and the
// Sprite will automatically resize itself in our activity logic.
// How handy!
mFillSprite.PixelSize = .5f;
mFrameSprite.PixelSize = .5f;

Add the following to Update:

// .5 means it will fill up .5 of the way (50%) in 1 second
float fillSpeed = .5f;

if (InputManager.Keyboard.KeyDown(Keys.Down))
{
    mFillRatio -= fillSpeed * TimeManager.SecondDifference;
    UpdateFill();
}
else if (InputManager.Keyboard.KeyDown(Keys.Up))
{
    mFillRatio += fillSpeed * TimeManager.SecondDifference;
    UpdateFill();
}

Add UpdateFill at class scope:

 void UpdateFill()
 {
     mFillRatio = Math.Max(0, mFillRatio);
     mFillRatio = Math.Min(1, mFillRatio);
 
     mFillSprite.TopTextureCoordinate = 1 - mFillRatio;

     float bottomOfFrame = mFrameSprite.Y - mFrameSprite.ScaleY;

     mFillSprite.Y =  bottomOfFrame + mFillSprite.ScaleY;
 }

For Glue users

If you are modifying the code above to be used in an Entity, and if the Sprite you are modifying is part of the given Entity, then it is likely that the Sprite is attached to the Entity. Therefore, you will need to replace any code that gets or sets the mFillSprite's Y value with RelativeY. In the code this is done in two parts - in Initialize where mBaseY is set, and the last line in UpdateFill where the Sprite's Y is set.

Additional Information

• Clipping Sprites - A tutorial on how to clip Sprites within a rectangle.

• TextureAddressMode - The visual behavior of Sprites depends on the TextureAddressMode. See this page for information on how to use texture coordinates.

Introduction

The TopTextureCoordinate, BottomTextureCoodinate, LeftTextureCoordinate, and RightTextureCoordinate properties control the coordinates in "uv space" of the top, bottom, left, and right sides of the Sprite. In other words, these values can be used to make a Sprite draw part of a texture instead of the entire thing. These properties are often used when working on games that use sprite sheets. The default values are as follows:

• TopTextureCoordinate = 0

• BottomTextureCoordinate = 1

• LeftTextureCoordinate = 0

• RightTextureCoordinate = 1

What are "texture coordinates" and how do they compare to pixels

Texture coordinates are often used in games (not just FlatRedBall) to measure points on a texture. Texture coordinates are often displayed as two values separated by commas within parenthesis. For example:

(0, 0)

and

(.75, .25)

The texture coordinate is a coordinate which measures location on a texture, but this coordinate does not use pixels. For example, if you're used to using pixels, you may be familiar with (0,0) being the top-left of an image. If your image is 32 pixels tall and 32 pixels wide, then the bottom-right of the image would be (32, 32). In texture coordinates, the top left is (0, 0). The bottom-right is (1, 1). You can think of texture coordinates as representing a percentage. In other words, a value of 0 means 0%. 1 means 100%. A value of 0.5 means 50%. Therefore, a value of (.5, 0) means "50% of the width (starting at the left) and 0% of the height (starting at the top). Therefore, the very center of the image is (.5, .5).

Code example

Texture coordinates can be adjusted to create objects which show only part of a texture, such as health bars. The following code shows how to create a Diablo-like health meter (of course, using a red ball): Files used:

Add the following at class scope:

Sprite mFrameSprite;
Sprite mFillSprite;
float mFillRatio = 1;

Add the following to Initialize after initializing FlatRedBall:

SpriteManager.Camera.UsePixelCoordinates(false);

mFillSprite = SpriteManager.AddSprite("content/fill.png");
mFrameSprite = SpriteManager.AddSprite("content/frame.png");

// Let's make them pixel perfect.
// PixelSize is a reactive property, and it reacts
// to texture coordinate changes too.  This means that
// we just have to change the texture coordinates and the
// Sprite will automatically resize itself in our activity logic.
// How handy!
mFillSprite.PixelSize = .5f;
mFrameSprite.PixelSize = .5f;

Add the following to Update:

// .5 means it will fill up .5 of the way (50%) in 1 second
float fillSpeed = .5f;

if (InputManager.Keyboard.KeyDown(Keys.Down))
{
    mFillRatio -= fillSpeed * TimeManager.SecondDifference;
    UpdateFill();
}
else if (InputManager.Keyboard.KeyDown(Keys.Up))
{
    mFillRatio += fillSpeed * TimeManager.SecondDifference;
    UpdateFill();
}

Add UpdateFill at class scope:

 void UpdateFill()
 {
     mFillRatio = Math.Max(0, mFillRatio);
     mFillRatio = Math.Min(1, mFillRatio);
 
     mFillSprite.TopTextureCoordinate = 1 - mFillRatio;

     float bottomOfFrame = mFrameSprite.Y - mFrameSprite.ScaleY;

     mFillSprite.Y =  bottomOfFrame + mFillSprite.ScaleY;
 }

For Glue users

If you are modifying the code above to be used in an Entity, and if the Sprite you are modifying is part of the given Entity, then it is likely that the Sprite is attached to the Entity. Therefore, you will need to replace any code that gets or sets the mFillSprite's Y value with RelativeY. In the code this is done in two parts - in Initialize where mBaseY is set, and the last line in UpdateFill where the Sprite's Y is set.

Additional Information

• Clipping Sprites - A tutorial on how to clip Sprites within a rectangle.

• TextureAddressMode - The visual behavior of Sprites depends on the TextureAddressMode. See this page for information on how to use texture coordinates.

Introduction

Many FlatRedBall users often mistake "Sprites", "image files", and "Textures". This misconception can be supported by the close relationship between the three, especially since Sprites can be created as follows:

At first glance, the code above may look like it is "creating a Sprite from a bitmap." This is technically not true, and in some cases the details of what is happening behind the scenes in the above call are very important. This wiki entry discusses the differences between image files, Textures, and Sprites in an effort to reduce the confusion.

Image, Texture2D, and Sprite

Dissecting AddSprite

The following code is both very common but actually performs a lot of functinality "under the hood":