# Sprites

## Overview

This guide provides an overview of sprites and some of their associated commands.

## What is a sprite?

Sprites sit at the core of AGK and are used as a way of representing images on screen.

## How do I create a sprite?

A sprite can be created by calling the CreateSprite command:

    CreateSprite ( id, image )
    id = CreateSprite ( image )

    void CreateSprite ( UINT id, UINT image );
    UINT CreateSprite ( UINT image );

A sprite can be created by either assigning an ID number manually or having it provided to you automatically. The next step is to provide an ID number of an image. The image gets attached to the sprite and will later be drawn on screen. Please note that ID numbers are unique for a command set. Therefore it's feasible to have a sprite ID of 1 along with an image ID of 1.

Here's one approach to creating a sprite. This example loads an image into ID slot 1. This is followed by a call to CreateSprite, passing in an ID number of 1 for the sprite and also letting the command know that we'll be attaching image 1 to this sprite.

    LoadImage ( 1, "myImage.png" )
    CreateSprite ( 1, 1 )

    agk::LoadImage ( 1, "myImage.png" );
    agk::CreateSprite ( 1, 1 );

This alternative method demonstrates how an image can be loaded and a sprite created with automatically assigned ID numbers:

    image = LoadImage ( "myImage.png" )
    sprite = CreateSprite ( image )

    image = agk::LoadImage ( "myImage.png" );
    sprite = agk::CreateSprite ( image );

## How can I position a sprite?

The main command for setting a sprite's position is called SetSpritePosition. This command takes 3 parameters:

- ID
- X position
- Y position

The ID number refers to the ID of the sprite you want to position, while the X and Y positions will refer to percentages or screen coordinates.

When using the percentage based system, to position a sprite at 25% along the X axis and 75% along the Y axis:

    LoadImage ( 1, "myImage.png" )
    CreateSprite ( 1, 1 )
    SetSpritePosition ( 1, 25, 75 )

    agk::LoadImage ( 1, "myImage.png" );
    agk::CreateSprite ( 1, 1 );
    agk::SetSpritePosition ( 1, 25, 75 );

If a virtual resolution was being used, the above code would be setting the sprites position to 25 pixels along the X axis and 75 pixels down the Y axis.

## How can I set the visibility of a sprite?

A sprite will be visible as soon as it has been created. For times when you need to alter the visibility use the command SetSpriteVisible. This command takes 2 parameters:

- ID
- visible state

The ID number refers to the ID of the sprite you want to alter, while a visible state of 0 will hide the sprite and a state of 1 will show it.

## How can I delete a sprite?

Call the DeleteSprite command to remove a sprite:

    DeleteSprite ( id )

    void DeleteSprite ( UINT id );

This command only requires the ID number of the sprite you want to delete. Here's an example of creating a sprite and deleting it:

    LoadImage ( 1, "myImage.png" )
    CreateSprite ( 1, 1 )
    DeleteSprite ( 1 )

    agk::LoadImage ( 1, "myImage.png" );
    agk::CreateSprite ( 1, 1 );
    agk::DeleteSprite ( 1 );