Click or drag to resize

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
SystemObject
  SpriteLibrarySprite

Namespace:  SpriteLibrary
Assembly:  SpriteLibrary (in SpriteLibrary.dll) Version: 1.0.0.6 (1.0.0.6)
Syntax
C#
public class Sprite

The Sprite type exposes the following members.

Constructors
  NameDescription
Public methodSprite(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.
Public methodSprite(SpriteController, Image)
Generate a new single-frame sprite from the specified image.
Public methodSprite(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.
Public methodSprite(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.
Public methodSprite(SpriteController, Image, Int32, Int32, Int32)
Generate a new sprite. It takes a width, height, and the duration in Milliseconds for each frame
Public methodSprite(Point, SpriteController, Image, Int32, Int32, Int32, Int32)
Create a Sprite from an animation image, specifying the number of consecutive frames to grab.
Top
Properties
  NameDescription
Public propertyAnimationCount
The number of animations this sprite has
Public propertyAnimationDone
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.
Public propertyAnimationIndex
Get or set the animation nimber. It is best to change the animation using ChangeAnimation. It is safer.
Public propertyAutomaticallyMoves
Determine if the sprite automatically moves (you need to give it a direction [using one of the SetSpriteDirection functions] and speed [MovementSpeed = X] also)
Public propertyBaseImageLocation
The sprite location as found on the base image. This is usually the easiest location to use.
Public propertyDestroying
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.
Public propertyFrameIndex
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.
Public propertyGetSize
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
Public propertyGetVisibleSize
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.
Public propertyHasBeenDrawn
Report whether or not this Sprite has been drawn. If it has, then it needs to be erased at some point in time.
Public propertyID
The Sprite ID as specified by the sprite controller.
Public propertyMovingToPoint
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.
Public propertyOpacity
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.
Public propertyPictureBoxLocation
The sprite location as found on the picture-box that this sprite is associated with. Used when dealing with mouse-clicks
Public propertyRotation
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.
Public propertySpriteName
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.
Public propertySpriteOriginName
Return the name of the sprite that this was duplicated from. A duplicated sprite will have no name, but will have a SpriteOriginName.
Public propertySpriteReachedEndPoint
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.
Public propertyVisibleHeight
The visible Height as seen in the PictureBox. It may be stretched, or shrunk from the actual image size.
Public propertyVisibleWidth
The visible width as seen in the PictureBox. The Sprite may be stretched or shrunk from the actual image size.
Public propertyZvalue
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
  NameDescription
Public methodAddAnimation(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.
Public methodAddAnimation(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.
Public methodAddAnimation(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.
Public methodAddAnimation(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.
Public methodAddAnimation(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.
Public methodAddAnimation(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.
Public methodAddAnimation(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.
Public methodAddAnimation(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.
Public methodAnimateJustAFewTimes
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.
Public methodAnimateOnce
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.
Public methodCancelMoveTo
Cancel a MoveTo command. The sprite will stop moving, and all the waypoints will be removed.
Public methodChangeAnimation
Start a new animation index from scratch
Public methodChangeAnimationSpeed
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.
Public methodChangeFrameAnimationSpeed
Change the animation speed of a specific frame. Beware. This affects every sprite using this frame
Public methodCheckSpriteHitsSprite
Check to see if two sprites hit each-other. The sprite collision methods are not all programmed in.
Public methodConvertDegreesToRadians
Convert a number from degrees to radians.
Public methodConvertRadiansToDegrees
Convert a number from radians to degrees.
Public methodDestroy
Tell the sprite to kill itself. It will erase itself and then be removed from the spritelist. Then it will be gone forever.
Public methodEquals (Inherited from Object.)
Protected methodFinalize (Inherited from Object.)
Public methodGetAnimationSpeed
Return the animation speed of this particualar animation of the sprite.
Public methodGetFrameAnimationSpeed
Get the animation speed of a single frame.
Public methodGetHashCode (Inherited from Object.)
Public methodGetImage
return the current image frame. Warning: If you write to this image, it will affect all sprites using this frame.
Public methodGetImage(Int32, Int32)
return the frame for the given index. Warning: If you write to this image, it will affect all sprites using this frame.
Public methodGetSpriteBaseImageCenter
Return the centerpoint of the sprite, as found on the background image
Public methodGetSpriteDegrees
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.
Public methodGetSpritePictureboxCenter
Return the centerpoint of the sprite, as found on the picturebox
Public methodGetSpriteRadans
Returns the direction the sprite is currently traveling, using Radians.
Public methodGetSpriteVector
Return the current vector that the sprite is moving along
Public methodGetType (Inherited from Object.)
Public methodHideSprite
Remove the sprite from the field. This does not destroy the sprite. It simply removes it from action. Use UnhideSprite to show it again.
Public methodIsPaused
Ask if the sprite is paused using the specified sprite type (default is PauseAll)
Protected methodMemberwiseClone (Inherited from Object.)
Public methodMoveTo(ListPoint)
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.
Public methodMoveTo(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.
Public methodMoveTo(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.
Public methodPause
Pause the sprite. We can pause just the animation (and still let it move), pause movement (and let it animate), or pause everything.
Public methodPutBaseImageLocation(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
Public methodPutBaseImageLocation(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
Public methodPutPictureBoxLocation
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.
Public methodRecalcPictureBoxLocation
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.
Public methodReplaceImage
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.
Public methodReturnAdjustmentRatio
Taking into consideration how the sprite is stretched or shrunk, it returns a SpriteAdjustmentRatio that can be used to work with the sprite itself.
Public methodSendToBack
Make the sprite go behind all other sprites
Public methodSendToFront
Make the sprite show up in front of all other sprites.
Public methodSetName
Give this sprite a name. This way we can make a duplicate of it by specifying the name
Public methodSetSize
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.
Public methodSetSpriteDirection
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.
Public methodSetSpriteDirectionDegrees
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.
Public methodSetSpriteDirectionRadians
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.
Public methodSetSpriteDirectionToPoint
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.
Public methodSpriteAdjustedPoint
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.
Public methodSpriteAtImagePoint
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)
Public methodSpriteAtPictureBoxPoint
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.
Public methodSpriteCanMoveOnImage
Return true if the sprite can go to this point and still be on the drawing-board.
Public methodSpriteCanMoveOnPictureBox
Return true if the sprite can go to this point and still be on the drawing-board.
Public methodSpriteIntersectsRectangle
Check to see if the specified rectangle overlaps with the sprite.
Public methodToString (Inherited from Object.)
Public methodUnhideSprite
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
Public methodUnPause
unpause the sprite.
Top
Events
  NameDescription
Public eventCheckBeforeMove
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.
Public eventClick
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.
Public eventClickTransparent
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.
Public eventMouseEnter
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.
Public eventMouseEnterTransparent
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.
Public eventMouseHover
This event happens when the mouse moves over the sprite, and then pauses. We use the hover timing from the parent form.
Public eventMouseHoverTransparent
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.
Public eventMouseLeave
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.
Public eventMouseLeaveTransparent
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.
Public eventSpriteAnimationComplete
Only used when you tell an animation to animate once. At the end of the animation, this function fires off.
Public eventSpriteArrivedAtEndPoint
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.
Public eventSpriteArrivedAtWaypoint
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.
Public eventSpriteBeingDestroyed
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.
Public eventSpriteChangesAnimationFrames
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.
Public eventSpriteExitsPictureBox
This happens when the sprite has exited the picture box. Useful when you want to keep sprites from traveling on forever after exiting.
Public eventSpriteHitsPictureBox
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.
Public eventSpriteHitsSprite
This happens when two sprites hit each-other. The SpriteEventArgs that is returned contains the sprite that this sprite hits.
Public eventSpriteInitializes
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
  NameDescription
Public fieldCannotMoveOutsideBox
Determine if the sprite will automatically move outside the box. If not, it will hit the side of the box and stick
Public fieldMirrorHorizontally
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
Public fieldMirrorVertically
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
Public fieldMovementSpeed
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.
Public fieldpayload
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:
public class TankPayload : SpritePayload {  public int Armor; public int Speed; }
You can access the payload and retrieve the various values.
Top
See Also