A vortex guide to sprites and things in Jamagic.

Introduction:

Hello, if you are reading this you ethier want to learn about sprites in Jamagic, or have nothing better to do .

Sprites are a very important part of Jamagic as they are a key graphics componet for 2d or even 3d games. Sprites can have pictures from an image bank, animations, or surfaces and this makes them extremely useful and powerful. If you want graphics in your Jamagic application that can be moved around or stay above a 3d world then sprites are for you!

Sprites can be compared to the active objects in the click line of products and are almost as easy to create. In this tutorial I will show you a basic program to create a sprite, changing a sprite image, changing a sprite animation, and moving it around the screen. So launch up jamagic, get a snack, and read on .

The Begining:

Before you start on this grand sprite learning adventure you will need to create a new Jamagic project. In the project create a picture that is 32X32 of a simple ball and rename it as : myBall. This will be used in all following examples.

Lets Begin!

Your first Sprite:

The following code will show you how to display the ball you just created on the screen.

_____________________________

//Creates a sprite
mySprite=New Sprite(DefaultWin,0,0,"myBall");
//loop to keep the program running
While(1);
____________________________

Run the code and note what happens, you should see a ball on the screen . If you get a "Cannot Create Sprite" error, or error 34, then you didnt create the ball, or named it as something other then myBall. if you get an error 41 or non initialized variable, then you ethier A) Deleted the startup code from the runtime int in the project directory, B) or modified the template. If this happens to occur, above the code where it creates the mySprite object, add:

____________________________
//creates a blank window
DefaultWin=New Window(640, 480);
____________________________
*IGNORE IF ALREADY IN RUNTIME INT!!*
This should correct the error.

Now that we have correct any error that might come up in the execution of this code, lets go more in depth .
____________________________
mySprite=New Sprite(DefaultWin,0,0,"myBall");
____________________________

What does this mean? well lets break it down. mySprite is the name of the variable that will point to a sprite. This variable is used later for all operations we want to do to the sprite such as moving it around . the next part : =New Sprite says that we want to create a new sprite that the variable before the equal sign will contain. The next part the DefaultWin is the window in which we want to create our sprite on. You can ignore this parameter and it will create the sprite on the current window. the next two numbers are the x,y cordinates. Try changing the two numbers and you will see the position of the sprite changes. the "myBall" says that we want to use the picture named myBall to use as our sprite .

Give yourself a pat on the back you just made your first sprite!

Images and Animations:

After creating that very cool little sprite you might be wondering "What is next? what could possibly top the absolute coolness that is that?" Well, prepare to be amazed as first we change the image for our sprite, and then the animation .

First we will change the image right after sprite creation. To make this work correctly create a new image balled "myBall2" this will be used later on for the following examples. *hint*: Make sure the myBall2 image is the same size as myBall!

Now you should have two images. each 32X32 and one named myBall and the other named myBall2. I made myBall red, and myBall2 blue. If you don't have this, go do it now before you proceed!

________________________
//Creates a sprite
mySprite=New Sprite(DefaultWin,0,0,"myBall");
//changes the sprite picture for the mySprite variable
mySprite.Set(,,"myBall2");
//loop to keep the program running
While(1);
_______________________


If you look over the code you should notice it is almost the same as the code from creating your first sprite, only it has a new line of code before the while loop. Lets break down this programming gem to learn its secrets.

______________________
mySprite.Set(,,"myBall2");
______________________

mySprite is the variable we created the sprite in earlier. The .Set is a method of the sprite (a method is something the object can do. Remember, that in jamagic after a method or a creation statement there are parenthesis and then a semicolon. the information inside the parenthesis are the parameters of the method). The ,, basically leaves the first 2 parameters of the method blank (not the best of practices but i am going it to simplfy.) these paremeters we left blank just default to the current x,y position of the sprite and we will learn about that later on. the next parameter we dont leave blank. "myBall2" tells the sprite we want to change the picture from myBall to myBall2 of the sprite.

Now that we have observed this happen right after the sprite was created lets see what happens we when throw some more programming in to the mix .

*A WARNING TO NEWBIES*: The following code may contain things you have never seen before, if you do not understand if statements and the keyboard object, please read Dr.Ians tutorial called "Hello World!".

__________________
//Creates a sprite
mySprite=New Sprite(DefaultWin,0,0,"myBall");
//loop to keep the program running
While(1)
{
//we add brackets in a while loop this time, dont be alarmed this says "do stuff in the while loop"
//this is an if statement that says basically If 1 is pushed then..
If(Keyboard.IsKeyDown("1"))
{
//changes the sprite picture for the mySprite variable to myBall
mySprite.Set(,,"myBall");
}
//this is an if statement that says basically If 2 is pushed then...
If(Keyboard.IsKeyDown("2"))
{
//changes the sprite picture for the mySprite variable to myBall2
mySprite.Set(,,"myBall2");
}
}
_______________

Starting to get a bit complex? dont worry I assure you everything has a purpose!

You will notice the code starts out like the first code we did by creating a sprite. Then we reach the while statement where instead of putting a semicolon we use brackets to tell the program to run stuff in a loop (not comments )

Then you will notice the two almost identical if statements. notice how i didnt create a keyboard object. You will learn that some objects in jamagic arent created but are internal to Jamagic itself. This includes the system object, the keyboard object, and the program object.

Inside the if statements we use the same code as in example 2 to change the sprite picture. in if statement one we change it to the myBall image, and in if statement 2 we change it to the myBall2 image.

Run the code and press 1 to change from picture 1, and 2 to change to picture 2. Fun .

After learning about how to change an image picture, and advanced changing an image picture, lets do one more thing before we move on to moving a sprite. Lets change the sprite animations!

Before you continue you will need to create an animation. make it 32X32 and call it MyBallAnm. You can simply copy the ball image and paste it into the animation if you so choose. Make the animation have atleast 2 frames to see the effect. Mine will have 4 going from : red,green,blue and yellow.

*NOTE*: May cause a blinking pattern if only 2 frames is used. if you are epileptic PLEASE be careful.

When working with a sprite animation it is important to remember that sprites treat images and animations just about the same so please while you can have an image and animation with the SAME NAME, it may cause problems.

Once you have your animation ready, read on.

The following code will play a sprite animation once.

____________________
//Creates a sprite
mySprite=New Sprite(DefaultWin,0,0,"myBall");
//changes the image to an ANIMATION
mySprite.Set(,,"myBallAnm");
//plays the animation
mySprite.Play();
//loop to keep the program running
While(1);
__________________

You will see that this reverts back to the second example, but uses the name of the animation instead of an image. Also notice the statement:

____________
mySprite.Play();
____________

This will play the animation. You can ignore the parameters for this second.

After you run the code though you notice a bit of a problem, it plays the animation only once! this is no good . Lets see how to alter the code to make the sprite animation play forever.

_________________
//Creates a sprite
mySprite=New Sprite(DefaultWin,0,0,"myBall");
//changes the image to an ANIMATION
mySprite.Set(,,"myBallAnm");
//plays the animation infinite
mySprite.Play(Sprite.LOOP_INFINITE);
//loop to keep the program running
While(1);
________________

Run this code and you will see it play over and over and over again . Lets find out why.

_______________
mySprite.Play(Sprite.LOOP_INFINITE);
_______________

The play method of the sprite object contains 3 parameters, but for this example we have left off the last 2. Sprite.LOOP_INFINITE is a flag of the sprite object that tells the sprite to play the animation OVER AND OVER again.

Now, after playing with changing images and animations, lets see how to acually make the object MOVE .

The holy grail- Moving a sprite :

Lets explore the endless possibilites of sprite movement .

This code moves a sprite using the arrow keys:

______________
//sets auto refresh off for the window
Defaultwin.SetAutoRefresh(OFF);
//Creates a sprite
mySprite=New Sprite(DefaultWin,0,0,"myBall");
//defines a variable called speed
speed=3;
//loop to keep the program running
While(1)
{
//makes a variable used to limit the fps
ti=System.GetElapsedTime()+30;
//if the up arrow key is pressed
If(Keyboard.IsKeyDown(Keyboard.UP))
{
mySprite.Set(,mySprite.GetY()-speed);
}
//if the down arrow key is pressed
If(Keyboard.IsKeyDown(Keyboard.DOWN))
{
mySprite.Set(,mySprite.GetY()+speed);
}
//if the right arrow key is pressed
If(Keyboard.IsKeyDown(Keyboard.RIGHT))
{
mySprite.Set(mySprite.GetX()+speed);
}
//if the left arrow key is pressed
If(Keyboard.IsKeyDown(Keyboard.LEFT))
{
mySprite.Set(mySprite.GetX()-speed);
}
//refreshes the screen manually.
Defaultwin.Refresh();
//limits fps
While(System.GetElapsedTime()<ti);
}
_________________

You will notice it starts off diffrent then the previous examples by setting autorefresh off. This is done so it is much smoother then it would be otherwise. It then creates a sprite. Next, it defines a variable called speed which is used later to move the sprite . Then the while loop happens , ti is used to limit the fps later on in the program by a while loop. Then there are the familiar if statements that we used earlier but this time for arrow keys. the first 2 if statements control the movement up and down and skip the first paremeter or X. The second just need one parameter for X and control the right and left movement .

After all of that is done the window is refreshed, and the code to limit the fps is put into play.

Run the code, and there you have it , a sprite that moves by the arrow keys. However, this uses mySprite.set 4 whole times, and doesnt have customizable controls .

For the next example we will allow our program to have customizable controls, as well as only have to use the mySprite.set variable once instead of 4 times.

To make this work correctly, you will need to change the gameinput type under settings. Change this to 2d game instead of doom type, and it will work fine. If not, you wont get very good results .

Once you have changed the gameinput type to 2d game read on .

This code will allow you to move a sprite with customizable keys using the gameInput object as well as only having 1 set statement.
______________________________
//sets auto refresh off for the window
Defaultwin.SetAutoRefresh(OFF);
//Creates a sprite
mySprite=New Sprite(DefaultWin,0,0,"myBall");
//defines a variable called speed
speed=3;
//gets the default game input device
gInput=Program.GetDefaultGameInput();
//loop to keep the program running
While(1)
{
//makes a variable used to limit the fps
ti=System.GetElapsedTime()+30;
//defines a variable called v used for x movement later on
v=0;
//defines a variable called w used for y movement later on
w=0;
//sets the topVal variable to get the result if the Top key is pressed
topVal=gInput.GetDeviceValue(0,"Top");
//sets the botVal variable to get the result if the Bottom key is pressed
botVal=gInput.GetDeviceValue(0,"Bottom");
//sets the rightVal variable to get the result if the Right key is pressed
rightVal=gInput.GetDeviceValue(0,"Right");
//sets the leftVal variable to get the result if the left key is pressed
leftVal=gInput.GetDeviceValue(0,"Left");
//if statement for the topVal variable
If(topVal!=0)
{
//subtracts 1 from the w variable. it subtracts instead of sets incase you push top and bottom at once
w-=1;
}
//if statement for the botVal variable
If(botVal!=0)
{
//adds 1 to the w variable. it adds instead of sets incase you push top and bottom at once
w+=1;
}
//if statement for the rightVal variable
If(rightVal!=0)
{
//adds 1 to the v variable
v+=1;
}
//if statemetn for the leftVal variable
If(leftVal!=0)
{
//subtracts 1 to the v variable
v-=1;
}
//sets the variable to the postion based off the current x,y and if the v,w variables are positive and negative.
mySprite.Set(mySprite.GetX()+v*speed,mySprite.GetY()+w*speed);
//refreshes the screen manually.
Defaultwin.Refresh();
//limits fps
While(System.GetElapsedTime()<ti);
}
_______________________________

Its a bit long but bare with me, you will see it gets a gameinput object in the code above the while loop. Also inside the while loop it defines a v,w variable used to move the sprite. these varaibles can have a value of : -1,0,1 . if the value is 0 no movement occurs in that axis. The variables topVal,botVal,rightVal,leftVal get if the top,bottom,left,or right keys were pushed relative to how the game input object is set up. If these values are diffrent then the default value, it modifies ethier v or w by adding or subtracting to it.

Then it sets the sprite by getting the current x,y cordinates and adding v,w (which if they are negative is subtracting it allowing it to move in all the top,left directions.

Now this is all well and good, and works well. However, the code is quite long and well we probally need to make something called an object. This object will be a hero object and allow us to basically organize the code better.

______________________________

//sets auto refresh off for the window
Defaultwin.SetAutoRefresh(OFF);
//Creates a sprite
mySprite=New Sprite(DefaultWin,0,0,"myBall");
//makes a new hero object
myHero=New Hero(mySprite,3);
//loop to keep the program running
While(1)
{
//makes a variable used to limit the fps
ti=System.GetElapsedTime()+30;
//called the move method of the hero object
myHero.Move();
//refreshes the screen manually.
Defaultwin.Refresh();
//limits fps
While(System.GetElapsedTime()<ti);
}
//constructor for the hero object
Function Hero(spr,speed)
{
//makes the spr variable global to this object
This.spr=spr;
//makes the speed variable global to this object
This.speed=speed;
//gets the default game input device and makes it global to this object
This.gInput=Program.GetDefaultGameInput();
//function to call when the method move is called for this object
This.Move=Hero_Move;
}
//function for the move method of the hero object It uses the common namming system of ObjectName_MethodName
Function Hero_Move()
{
//defines a variable called v used for x movement later on
v=0;
//defines a variable called w used for y movement later on
w=0;
//sets the topVal variable to get the result if the Top key is pressed
topVal=gInput.GetDeviceValue(0,"Top");
//sets the botVal variable to get the result if the Bottom key is pressed
botVal=gInput.GetDeviceValue(0,"Bottom");
//sets the rightVal variable to get the result if the Right key is pressed
rightVal=gInput.GetDeviceValue(0,"Right");
//sets the leftVal variable to get the result if the left key is pressed
leftVal=gInput.GetDeviceValue(0,"Left");
//if statement for the topVal variable
If(topVal!=0)
{
//subtracts 1 from the w variable. it subtracts instead of sets incase you push top and bottom at once
w-=1;
}
//if statement for the botVal variable
If(botVal!=0)
{
//adds 1 to the w variable. it adds instead of sets incase you push top and bottom at once
w+=1;
}
//if statement for the rightVal variable
If(rightVal!=0)
{
//adds 1 to the v variable
v+=1;
}
//if statemetn for the leftVal variable
If(leftVal!=0)
{
//subtracts 1 to the v variable
v-=1;
}
//sets the variable to the postion based off the current x,y and if the v,w variables are positive and negative.
spr.Set(mySprite.GetX()+v*speed,mySprite.GetY()+w*speed);
}
__________________

It does the same thing but it is organized a bit better by using an object. the hero functions can be put into a new source called player if you so desire, and this code can be used over again for another project .

I hope you enjoyed my tutorial on Sprites and stuff. If you have any questions/comment please reply or send me an email at n2cartoons@hotmail.com.

Thank you for reading, and have fun with sprites!