ASprite.NET-Getting Started

ASprite.NET is a partial port of the ActiveX control ASpriteCE which was designed for eVB. Partial because it is missing the functions for scrolling, tiling, and some other goodies. The entire VB.NET source code for ASprite.NET is included in the distribution, and you are free to use it for your projects, commercial or otherwise.

While ASprite.NET was "targeted" for Smart Device Extensions, it is entirely possible to use the classes on a desktop version of the .NET framework. In fact, the applications you build should run unchanged on the desktop!

The Bounce Sample

"Bounce" is a sample application that ships with the ASprite.NET distribution. It's not a full game, but does demonstrate many of the elements of a sprite-based game - such as sprite definition, movement, and collision detection.

To examine and execute the Bounce sample, follow these steps:

Make sure you have a copy of Visual Studio 2003 or better with Smart Device Extensions capability.
Download ASprite.NET, and uncompress the ZIP contents to a folder.
Open the ASpriteNet.sln solution file.
Run the project by selecting Debug/Start from VS.NET.

When "Bounce" is running, you can click the "Add Sprite" button to add a Sprite to the GameWindow. Sprites bounce off the edges of the screen at random angles. When two sprites collide, they explode in a cloud of green smoke. Additionally, you may "tap" on a sprite using the stylus (or the mouse in the emulator) to make the sprite explode.

Hello, ASprite.NET

As a quick introduction to coding with ASprite.NET, we'll define an animated sprite and display it over a background. We'll also add some simple input using the mouse/stylus.

We'll use the starfield at left as a background and animate the "star" sprite above. Note that the star sprite consists of 8 frames - each 16x15 pixels in size.

1. To begin, create a new VB.NET Smart Device Application project:

2. Select "Pocket PC" and "Windows Application"

3. Save the backdrop.jpg and star.gif images above to the same directory that you saved your project in under Step 1.

4. Add the backdrop.jpg and star.gif images to your project by right-clicking your project in the Solution Explorer and selecting Add/Add Existing Item

5. Set the "Build Action" property in the Properties Window to "Embedded Resource" for both backdrop.jpg and star.gif. This will cause these files to be built into the EXE file of your application.

6. Add the ASprite.NET project to your references by right-clicking the "References" folder in Solution Explorer, then selecting "Add Reference." Browse to the ASpriteDotNet\bin\Release folder of the distribution and select ASpriteDotNet.dll. You may receive a warning "The reference...may or may not be valid..." which you can ignore.

7. Add an import statement for ASpriteCE, and declare a GameWindow and Sprite object within your Form class, like so:

Imports SpriteHand.ASprite                           ' <--- Add this line!

Public Class Form1
    Inherits System.Windows.Forms.Form
    Friend WithEvents MainMenu1 As System.Windows.Forms.MainMenu

    Protected WithEvents GameWindow1 As GameWindow   ' <--- Add this line!
    Private m_sprStar As Sprite                      ' <--- Add this line!
    ...

8. Add the following code to implement the Load event for your form:

Private Sub Form1_Load(ByVal sender As Object, ByVal e As System.EventArgs) Handles MyBase.Load
    ' create the Game Window
    GameWindow1 = New GameWindow
    Me.Controls.Add(GameWindow1)
    With GameWindow1
        .Size = New Size(Me.Width, Me.Height)
        .Left = 0
        .Top = 0
        .DrawInit(Me, 0, 0)
    End With

    ' Set up the background. NOTE that the Embedded bitmap 
    ' name takes the format ProjectName.filename.ext!!!
    Dim bmBackDrop As Bitmap = New System.Drawing.Bitmap( _
	  System.Reflection.Assembly.GetExecutingAssembly.GetManifestResourceStream( _
	  "HelloASpriteCE.backdrop.jpg"))
    GameWindow1.DrawBackgroundImage(bmBackDrop, 0, 0)
    GameWindow1.DrawSetTransparentColor(0, 0, 0)

    ' define a Star Sprite
    Dim bmStar As Bitmap = New System.Drawing.Bitmap( _
	  System.Reflection.Assembly.GetExecutingAssembly.GetManifestResourceStream( _
	  "HelloASpriteCE.star.gif"))
    m_sprStar = New Sprite(bmStar, 0, 0, 8, 16, 15, 8)
    m_sprStar.FrameSpeed = 1
    GameWindow1.SpriteAdd(m_sprStar)

    ' Start up the GameWindow Timer - shooting for 50 frames per second
    GameWindow1.TimerStartTimer(20)
End Sub

4. OK, we're all ready to try the application! Select Debug/Start from the VS.NET menu. When your form executes, you should see a star sprite animated at the top left corner of the starfield backdrop.

Moving Sprites and Detecting Collisions

To move a sprite, use the Velocity and Direction properites of the Sprite object:

sprX.Velocity = 5
sprX.Direction = 20

Direction is a value from 0 to 359 degrees, with 0 degrees pointing right at the 3 o'clock position. Velocity is the number of pixels the sprite will be moved for each TimerFired event (as set by TimerStartTimer)

When the movement of two sprites causes them to collide, the GameWindow object fires a SpriteCollision event, passing the two sprites involved in the collision. In some cases, you may also want to detect when the stylus is tapped or moved over a sprite - use the GameWindows's SpriteCollisionMouse event for this.

The Direction Property for the Sprite class is depicted above.

Getting Input from the User

You can respond to key events using the KeyDown event on the GameWindow, and Mouse/Stylus events using the Mouse events exposed. For example, to make our Star Sprite move toward the mouse when clicked, we could add this code:

    Private Sub GameWindow1_MouseDown(ByVal sender As Object, _
		ByVal e As System.Windows.Forms.MouseEventArgs) Handles GameWindow1.MouseDown
        m_sprStar.Direction = Utility.GetAngleBetween(m_sprStar.X, m_sprStar.Y, e.X, e.Y)
        m_sprStar.Velocity = 5
    End Sub

    Private Sub GameWindow1_MouseUp(ByVal sender As Object, _
		ByVal e As System.Windows.Forms.MouseEventArgs) Handles GameWindow1.MouseUp
        m_sprStar.Velocity = 0
    End Sub

Distributing your Application

The ASprite.NET classes and code are free to distribute in your applications. They should operate under almost any implementation of the .NET framework, since they are based on almost all managed code (the one exception is the Sound class which makes a few P/Invoke's).

Summary

This gave a quick overview of what the classes in ASprite.NET provide. Note that all of the source code is included, so feel free to extend the code to your needs. If you have any questions, visit the Message Board for help!