SpriteLibrary

# Sprite Class

A Sprite is an animated image that has a size, position, rotation, and possible vector It tracks where in the animation sequence it is, can report colisions, etc. This SpriteController draws, moves, and deals with most graphical aspects of the sprites for you.
Inheritance Hierarchy
System
Object
SpriteLibrary
Sprite

Namespace: SpriteLibrary
Assembly: SpriteLibrary (in SpriteLibrary.dll) Version: 1.0.0.5 (1.0.0.5)
Syntax
C#
Copy

    public class Sprite

The Sprite type exposes the following members.

Constructors

| Name | Description
--- | --- | ---
| Sprite(Sprite, Boolean) | Create a Sprite that is based off of the specified sprite. Clone the Sprite except that we set SpriteName = "" and OrigSpriteName = the OldSprite.SpriteName. That way we know that the sprite was duplicated from the original, and we can still distinguish the original from the duplicate.
| Sprite(SpriteController, Image) | Generate a new single-frame sprite from the specified image.
| Sprite(SpriteController, Image, Size) | Generate a new sprite. It takes the image and the width and height. If there are multiple images of that width and height in the image, an animation is created.
| Sprite(SpriteController, Image, Int32, Int32) | Generate a new sprite. It takes the image and the width and height. If there are multiple images of that width and height in the image, an animation is created.
| Sprite(SpriteController, Image, Int32, Int32, Int32) | Generate a new sprite. It takes a width, height, and the duration in Milliseconds for each frame
| Sprite(Point, SpriteController, Image, Int32, Int32, Int32, Int32) | Create a Sprite from an animation image, specifying the number of consecutive frames to grab.

Top
Properties

| Name | Description
--- | --- | ---
| AnimationCount | The number of animations this sprite has

AnimationDone

Report whether or not the animation has been completed. When you tell a Sprite to AnimateOnce, this will report "false" until the animation sequence has been finished. At that time, the value will be "True." The tricky bit is that this is a boolean. If you have not told a sprite to animate once, it will always return "false." If a sprite is paused, this returns "false." The only time this returns "true" is when you tell a sprite to animate once, or animate a few times, and those times have completed. At that time, this will report "True". If you have a sprite with only one frame, it may not look like it is "animating", but it is. It is simply animating that one frame over and over. So, AnimationDone reports false, unless you have told it to animate_once.

| AnimationIndex | Get or set the animation nimber. It is best to change the animation using ChangeAnimation. It is safer.
| AutomaticallyMoves | Determine if the sprite automatically moves (you need to give it a direction [using one of the SetSpriteDirection functions] and speed [MovementSpeed = X] also)
| BaseImageLocation | The sprite location as found on the base image. This is usually the easiest location to use.

Destroying

If the Sprite is in the middle of being Destroyed, this is set to true. When a Sprite is Destroyed, it needs to erase itself and do some house-cleaning before it actually vanishes. During this time, you may not want to use it. It is always a good thing to verify a Sprite is not in the middle of being destroyed before you do something important with it. To Destroy a Sprite, use the Sprite.Destroy() function.

| FrameIndex | This is the frame of the current animation sequence. You can use this if you need to figure out what frame index to resume something at, or something like that.
| GetSize | Return the size of the sprite in reference to the image on which it is drawn. To get the size of the Sprite in relation to the PictureBox, use GetVisibleSize
| GetVisibleSize | Return the relative size of the Sprite in relation to the PictureBox. If the box has been stretched or shrunk, that affects the visible size of the sprite.
| HasBeenDrawn | Report whether or not this Sprite has been drawn. If it has, then it needs to be erased at some point in time.
| ID | The Sprite ID as specified by the sprite controller.
| MovingToPoint | Tells us if we are in the process of doing a MoveTo operation. This boolean should be the opposite of SpriteReachedEndpoint, but that boolean is poorly named. This is usually the easier one to use.

Opacity

Set the opacity of the sprite. The value should be between 0 and 1. 1 is solid, 0 is transparent. Sometimes you want to drag a sprite around the map, or show a sprite that "could be there." Setting the sprite opacity is usually how you do that. One warning, however. The opacity value takes effect the next time it is drawn. If the sprite is animating rapidly, it will take effect nearly emmediately. If it is not animating, not moving, or just sitting there, then it may not take effect for quite some time.

| PictureBoxLocation | The sprite location as found on the picture-box that this sprite is associated with. Used when dealing with mouse-clicks

Rotation

Change the rotation of the sprite, using degrees. 0 degrees is to the right. 90 is up. 180 left, 270 down. But, if your sprite was drawn facing up, then rotating it 90 degrees will have it pointing left. The angle goes counter-clockwise. The image will be scaled such that it continues to fit within the rectangle that it was originally in. This results in a little bit of shrinking at times, but you should rarely notice that.

SpriteName

The name of the sprite. Use SetSpriteName(Name) to change this name. Most Named sprites are used to define what a sprite is. Once you have created a named sprite, you usually use DuplicateSprite(String) to clone the sprite for use. The basic rule of thumb is to load your sprites from images once, and name the initial sprites. Then, when you go to use those sprites, get duplicates of them. The reason for this is because it takes more processing time to initially create the sprites than it takes to duplicate them.

| SpriteOriginName | Return the name of the sprite that this was duplicated from. A duplicated sprite will have no name, but will have a SpriteOriginName.
| SpriteReachedEndPoint | This is true unless we are using MoveTo(point) or MoveTo(list of points) to tell the sprite to move from one place to the next. This boolean tells us if it has finished or not.
| VisibleHeight | The visible Height as seen in the PictureBox. It may be stretched, or shrunk from the actual image size.
| VisibleWidth | The visible width as seen in the PictureBox. The Sprite may be stretched or shrunk from the actual image size.
| Zvalue | A number from 0 to 100. Default = 50. Higher numbers print on top of lower numbers. If you want a sprite to always be drawn on top of other sprites, give it a number higher than 50. If you want a sprite to go under other sprites, make its number lower than 50.

Top
Methods

| Name | Description
--- | --- | ---

AddAnimation(Image)

Add another animation to an existing Sprite. After you add animations, you can use ChangeAnimation to select which animation you want the specified sprite to show. For example, you may want to have Animation 0 be a guy walking left, and animation 1 is that same guy walking right. Because we do not specify the number of frames, it starts at the top-left corner and grabs as many frames as it can from the image.

AddAnimation(Image, Size)

Add another animation to an existing Sprite. After you add animations, you can use ChangeAnimation to select which animation you want the specified sprite to show. For example, you may want to have Animation 0 be a guy walking left, and animation 1 is that same guy walking right. Because we do not specify the number of frames, it starts at the top-left corner and grabs as many frames as it can from the image.

AddAnimation(Image, Int32)

Add another animation to an existing Sprite. After you add animations, you can use ChangeAnimation to select which animation you want the specified sprite to show. For example, you may want to have Animation 0 be a guy walking left, and animation 1 is that same guy walking right. Because we do not specify the number of frames, it starts at the top-left corner and grabs as many frames as it can from the image.

| AddAnimation(Int32, Int32) | Duplicate an animation, except rotated by the specified number of degrees. For example, if you have a single animation (0), and you want to rotate it by 90 degrees, it will create animation 1 with that rotation to it. In the long haul, generating a few rotated animations is less memory intensive than rotating it on demand.

AddAnimation(Image, Int32, Int32)

Add another animation to an existing Sprite. After you add animations, you can use ChangeAnimation to select which animation you want the specified sprite to show. For example, you may want to have Animation 0 be a guy walking left, and animation 1 is that same guy walking right. Because we do not specify the number of frames, it starts at the top-left corner and grabs as many frames as it can from the image.

AddAnimation(Int32, Boolean, Boolean)

Duplicate an animation, except rotated by the specified number of degrees. For example, if you have a single animation (0), and you want to rotate it by 90 degrees, it will create animation 1 with that rotation to it. In the long haul, generating a few rotated animations is less memory intensive than rotating it on demand using the MirrorHorizontally or MirrorVertically booleans.

AddAnimation(Image, Int32, Int32, Int32)

Add another animation to an existing Sprite. After you add animations, you can use ChangeAnimation to select which animation you want the specified sprite to show. For example, you may want to have Animation 0 be a guy walking left, and animation 1 is that same guy walking right. Because we do not specify the number of frames, it starts at the top-left corner and grabs as many frames as it can from the image.

AddAnimation(Point, Image, Int32, Int32, Int32, Int32)

Add another animation to an existing Sprite. After you add animations, you can use ChangeAnimation to select which animation you want the specified sprite to show. For example, you may want to have Animation 0 be a guy walking left, and animation 1 is that same guy walking right. Because we do not specify the number of frames, it starts at the top-left corner and grabs as many frames as it can from the image.

AnimateJustAFewTimes

Start a new animation. It will complete the animation the number of times you specify. For example, if your sprite is walking, and one animation is one step, specifying 4 here will result in your sprite taking 4 steps and then the animation stops. You will want to make sure you are checking for when the animation stops, using the SpriteAnimationComplete event, checking the Sprite.AnimationDone flag.

| AnimateOnce | Start a new animation, but do it just once. You can use AnimateJustAFewTimes(1) to the same effect. Or, you can use AnimateJustAFewTimes with a different number. The SpriteAnimationComplete event will fire off when the animation completes. The variable, Sprite.AnimationDone will be true once the animation finishes animating.
| CancelMoveTo | Cancel a MoveTo command. The sprite will stop moving, and all the waypoints will be removed.
| ChangeAnimation | Start a new animation index from scratch
| ChangeAnimationSpeed | Change the animation speed of a particular animation. This looks at the first frame and compares that frame to the speed specified. It adjusts all the animations by the same percentage.
| ChangeFrameAnimationSpeed | Change the animation speed of a specific frame. Beware. This affects every sprite using this frame
| CheckSpriteHitsSprite | Check to see if two sprites hit each-other. The sprite collision methods are not all programmed in.
| ConvertDegreesToRadians | Convert a number from degrees to radians.
| ConvertRadiansToDegrees | Convert a number from radians to degrees.
| Destroy | Tell the sprite to kill itself. It will erase itself and then be removed from the spritelist. Then it will be gone forever.
| Equals | (Inherited from Object.)
| Finalize | (Inherited from Object.)
| GetAnimationSpeed | Return the animation speed of this particualar animation of the sprite.
| GetFrameAnimationSpeed | Get the animation speed of a single frame.
| GetHashCode | (Inherited from Object.)
| GetImage | return the current image frame. Warning: If you write to this image, it will affect all sprites using this frame.
| GetImage(Int32, Int32) | return the frame for the given index. Warning: If you write to this image, it will affect all sprites using this frame.
| GetSpriteBaseImageCenter | Return the centerpoint of the sprite, as found on the background image

GetSpriteDegrees

Get the direction that the sprite is traveling in in degrees. You may want to use Math.Round on the results. The value returned is usually just a tiny bit off from what you set it with. For example, if you set the sprite movement direction to be 270 degrees (down), this function may return it as 269.999992. Rounding the number will give it back to you at probably the same direction you set it as.

| GetSpritePictureboxCenter | Return the centerpoint of the sprite, as found on the picturebox
| GetSpriteRadans | Returns the direction the sprite is currently traveling, using Radians.
| GetSpriteVector | Return the current vector that the sprite is moving along
| GetType | (Inherited from Object.)
| HideSprite | Remove the sprite from the field. This does not destroy the sprite. It simply removes it from action. Use UnhideSprite to show it again.
| IsPaused | Ask if the sprite is paused using the specified sprite type (default is PauseAll)
| MemberwiseClone | (Inherited from Object.)

MoveTo(List
Point
)

Tell the sprite to move towards each point in turn. The sprite will move in a straight line until the first point. From there it moves to the next point, until it has reached the last point. Every time it reaches a point, the SpriteArrivedAtWaypoint event is triggered. When it reaches the final point in the list, the SpriteArrivedAtEndPoint event is triggered. While the sprite is moving, the SpriteReachedEndPoint attribute is set to false. When it has arrived, it is set to true.

| MoveTo(Point) | Tell the Sprite to move towards a destination. You need to give the sprite a MovementSpeed and tell the sprite that it can automatically move. But the sprite will begin a journey towards that point at the MovementSpeed you have set. When it gets to the point, the SpriteArrivedAtEndPoint event will fire off. Also, the SpriteReachedEnd bool will be true.
| MoveTo(Sprite) | Move to where the destination sprite currently is at. This is a dumb move. It does not take into consideration the movement direction of the destination sprite. So the moving sprite does need to be moving a bit faster than the sprite you are trying to hit for it to do so.
| Pause | Pause the sprite. We can pause just the animation (and still let it move), pause movement (and let it animate), or pause everything.
| PutBaseImageLocation(Point) | Put the Sprite at a specified location, using the dimentions of the BackgroundImage. Unless you are using coordinates you have gotten from a mouse-click, this is how you want to place a Sprite somewhere. It is the easiest way to track things. But, if you are doing something using mouse-click coordinates, you want to use PutPictureBoxLocation
| PutBaseImageLocation(Double, Double) | Put the Sprite at a specified location, using the dimentions of the BackgroundImage. Unless you are using coordinates you have gotten from a mouse-click, this is how you want to place a Sprite somewhere. It is the easiest way to track things. But, if you are doing something using mouse-click coordinates, you want to use PutPictureBoxLocation
| PutPictureBoxLocation | Put the Sprite at a specified location, using the dimentions of the PictureBox. You want to use this if you got your X/Y position from a mouse-click. Otherwise, this is the harder way to track things, particularly if your window can resize. Use PutBaseImageLocation instead.
| RecalcPictureBoxLocation | Done when the box resizes. We need to recompute the picturebox location. The resize function automatically calls this. You should never need to do so.
| ReplaceImage | Replace a sprite image. It will replace the current frame unless you specify both an animation and the frame within the animation you wish to replace. Warning: This replaces the image_frame for every sprite that uses that is based off the same image.
| ReturnAdjustmentRatio | Taking into consideration how the sprite is stretched or shrunk, it returns a SpriteAdjustmentRatio that can be used to work with the sprite itself.
| SendToBack | Make the sprite go behind all other sprites
| SendToFront | Make the sprite show up in front of all other sprites.
| SetName | Give this sprite a name. This way we can make a duplicate of it by specifying the name
| SetSize | Resize the sprite using the base image coordinates. The width and height specified are relative to the size of the background image, not the picturebox.
| SetSpriteDirection | Set the sprite direction using a vector. The vector may contain a speed as well as the movement delta (amount of x shift, and amount of y shift.) If so, this function may also affect the movement speed Most people prefer to use SetSpriteDirectionDegrees instead of using vectors.
| SetSpriteDirectionDegrees | Given a "degree" (from 0 to 360, set the direction that the sprite moves automatically. 0 is right, 90 is up, 180 is left and 270 is down.
| SetSpriteDirectionRadians | Set the sprite direction using Radians. Most people do not want to use this. Use SetSpriteDirectionDegrees instead unless you like math and know what you are doing with Radians.

SetSpriteDirectionToPoint

Sets the Sprite Moving towards a given point. You are responsible to do something with it once it gets there. If you want it to automatically stop upon reaching it, use MoveTo instead. Actually, the MoveTo function works a lot better than this one. Because of integer rounding and a few other things, this function is a little bit imprecise. If you send it towards a point, it will go in that general direction. The MoveTo function will perpetually recalculate its way to the destination point and actually reach that point. SetSpriteDirectionToPoint will sort-of head in the direction of the point. But MoveTo will go to that point.

| SpriteAdjustedPoint | Because sprites are scaled (shrunk or stretched), this function finds the point within the sprite that is specified by the location. this function is used by a number of internal processes, but may be useful to you. But probably not.
| SpriteAtImagePoint | Check to see if the sprite exists at the point specified. The point given is in coordinates used by the image (not the PictureBox, use SpriteAtPictureBox for that)
| SpriteAtPictureBoxPoint | Return true or false, asking if the specifiec sprite is at the point on the picturebox. You can use this with a mouse-click to see if you are clicking on a sprite. Use the SpriteCollisionMethod "transparent" to see if you have clicked on an actual pixel of the sprite instead of just within the sprite rectangle.
| SpriteCanMoveOnImage | Return true if the sprite can go to this point and still be on the drawing-board.
| SpriteCanMoveOnPictureBox | Return true if the sprite can go to this point and still be on the drawing-board.
| SpriteIntersectsRectangle | Check to see if the specified rectangle overlaps with the sprite.
| ToString | (Inherited from Object.)
| UnhideSprite | Make the sprite reappear. If you have not positioned it yet, it will show up at the top corner. It is best to only use this when you have hidden it using HideSprite
| UnPause | unpause the sprite.

Top
Events

| Name | Description
--- | --- | ---
| CheckBeforeMove | This event fires off before a sprite is drawn. Use it if you have constraints. You can change the location or cancel the move entirely.
| Click | This event happens when someone clicks on the sprite (on the rectangle in which the sprite is). If you want the event to fire off only when someone clicks on the visible part of the sprite, use ClickTransparent instead.
| ClickTransparent | This event happens when someone clicks on the sprite (on the sprite image itself). If the sprite is sometimes hidden, but you want the click to work even if it is not visible at that instant, use Click instead.
| MouseEnter | When the mouse moves over the sprite. Use this for a menu, when you want the menu item to glow when the mouse is over the menu item sprite.
| MouseEnterTransparent | When the mouse moves over a non-transparent portoin of the sprite. Use this for a menu, when you want the menu item to glow when the mouse is over the menu item sprite.
| MouseHover | This event happens when the mouse moves over the sprite, and then pauses. We use the hover timing from the parent form.
| MouseHoverTransparent | This event happens when the mouse moves over a non-transparent portion of the sprite, and then pauses. We use the hover timing from the parent form.
| MouseLeave | When the mouse moves off the sprite. Use this for a menu, when you want the menu item to stop glowing when the mouse moves away from the menu item sprite.
| MouseLeaveTransparent | When the mouse moves off the non-transparent portion of the sprite. Use this for a menu, when you want the menu item to stop glowing when the mouse moves away from the menu item sprite.
| SpriteAnimationComplete | Only used when you tell an animation to animate once. At the end of the animation, this function fires off.
| SpriteArrivedAtEndPoint | An event for when you tell a Sprite to MoveTo(Point) a specific point, or, when you tell the Sprite to MoveTo(list of points). When the Sprite has reached the final destination, the Sprite fires off this event.
| SpriteArrivedAtWaypoint | When you tell a sprite to MoveTo(list of points), this fires off every time it gets to one of the points. When it gets to the final point, only the SpriteAtEndPoint event fires off.
| SpriteBeingDestroyed | The Sprite has just been told to be destroyed. You might want to do some cleanup. If you need to destroy some payload data, or tell something to cleanup after the sprite this is where to do that.
| SpriteChangesAnimationFrames | When the frame of an animation changes. If you want to have something happen every time the foot of your monster comes down, when the swing of your sword is at certain points, etc. Check to see that the Animaton and FrameIndex are what you expect them to be.
| SpriteExitsPictureBox | This happens when the sprite has exited the picture box. Useful when you want to keep sprites from traveling on forever after exiting.
| SpriteHitsPictureBox | This happens when the sprite hits the border of the picture-box. Useful for when you want to have shots explode when they hit the side.
| SpriteHitsSprite | This happens when two sprites hit each-other. The SpriteEventArgs that is returned contains the sprite that this sprite hits.
| SpriteInitializes | This event happens right after the sprite is created. Use this to immediately set a sprite to animate once or something like that.

Top
Fields

| Name | Description
--- | --- | ---
| CannotMoveOutsideBox | Determine if the sprite will automatically move outside the box. If not, it will hit the side of the box and stick
| MirrorHorizontally | Flip the image when it gets printed. If your sprite is walking left, flipping it will make it look like it is going right. This works great for many things. But, if your program is gobbling memory or CPU, you may need to consider using Sprite.AddAnimation
| MirrorVertically | Flip the image when it gets printed. If your sprite looks like it is facing up, doing this will make it look like it faces down. This works great for many things. But, if your program is gobbling memory or CPU, you may need to consider using Sprite.AddAnimation

MovementSpeed

The movement speed of the sprite. To make a Sprite move, you need to set the MovementSpeed, the direction (using SetSpriteDirection(Vector), SetSpriteDirectionToPoint(Point), SetSpriteDirectionRadians(Double), or SetSpriteDirectionDegrees(Double)), and the AutomaticallyMoves property. The speed is calculated in pixels per amount of time. A higher number is faster than a lower number.

payload

A Sprite can hold a payload. Use this to store extra information about the various Sprites. Health, Armor, Shoot time, etc. But, to store information in the payload, you need to make a new class of SpritePayload. The syntax for doing so is:
Copy

    public class TankPayload : SpritePayload {  public int Armor; public int Speed; }

You can access the payload and retrieve the various values.

Top
See Also

#### Reference

SpriteLibrary Namespace