# Tutorial

### Using Sprites

SGE does offer some easy functions for handling your sprite data.

There are several ways how you can handle sprites:

- SGESPRITE - A sprite which can have several images playing at a user definalbe speed (frames per seconds)
- SGESPRITEGROUP - A container to easy up handling of larger groups of sprites (e.g. colliding the player sprite against a horde of enemies)

From now on all examples will assume you have a SGEFILE open called myfile.

### SGESPRITE

There are two functions for loading images. One to add a single image, it adds images to the end of the animation, and one to load a full range of images in one step.

To create a animated sprite and add single images you would do:

    SGESPRITE *player=sgeSpriteNew();
    sgeSpriteAddFile(player, myfile, "data/playerframeone.png");
    sgeSpriteAddFile(player, myfile, "data/playerframetwo.png");

To ease up loading, you can load a range of images in one step. The files have to be named with a numeric value, e.g. player001.png, player002,png, player003.png ....

You would load a range of images like this:

    SGESPRITE *player=sgeSpriteNew();
    sgeSpriteAddFileRange(player, myfile, "data/player%03d.png, 1, 20);

This would load images from player001.png to player020.png. The format of the filename string is as it would be for printf, in this case, %03d means, insert a number with 3 digits and leading with zeros, from 1 to 20.

To draw the sprites use:

    sgeSpriteDraw(myanimatedsprite, screen);
    sgeSpriteDrawXY(myanimatedsprite, 100, 50, screen);

The first would draw the sprite on its internal x/y coordinates, whereas the second draws it on a specific x/y coordinate to the screen

To detect collision between sprites, there are two functions:

    sgeSpriteCollide(animsprite1, snimsprite2);

Which does a pixel exact collision detection and returns 1 if sprites are colliding

    sgeSpriteBoxCollide(animsprite1, snimsprite2);

Which does a bounding box collision detection. It is faster than pixel exact collision detection, so if you dont need pixel exact collision, you should use this function.

To free resources of a animated sprite call:

    sgeSpriteDestroy(myanimatedsprite);

### SGESPRITEGROUP

Spritegroups are a easy way to handle a bunch of sprites that are belonging to a certain group, e.g. bullets, enemies, players.

After creating a spritegroup by calling:

    SGESPRITEGROUP *mygroup=sgeSpriteGroupNew();

...you can add simple sprites with:

    sgeSpriteGroupAddSprite(mygroup, mysprite);

To draw a whole sprite group at once, just call:

    sgeSpriteGroupDraw(mygroup);

Collision detection provides 3 functions, one for checking if two groups collide:

    sgeSpriteGroupCollide(mygroup, myothergroup);

one for checking, if a simple sprite collides against a group:

    sgeSpriteGroupCollideSprite(mygroup, mysprite);

To free resources of a sprite group call:

    sgeSpriteGroupDestroy(mygroup);