Guida per lo sviluppatore

Tabella dei contenuti:

• 1 · introduzione
• 2 · Struttura del progetto
• 2.1 · Per cominciare
• 2.2 · Stati di gioco
• 3 · Gestione della grafica
• 3.1 · Disegnare grafica semplice
• 3.2 · Utilizzo degli sprite
• 4 · Entità di gioco
• 4.1 · Gestione delle entità di gioco
• 4.2 · Definizione di una entità
• 4.3 · Tipologie e stati di una entità
• 4.4 · Animare le entità
• 4.5 · Rimozione di una entità
• 4.6 · L'entità Player
• 5 · Gestione dei font
• 5.1 · Utilizzo dei font e scrittura
• 5.2 · Utilizzo del sistema Typewriter
• 6 · Gestione del sonoro
• 6.1 · Stati di gioco e sonoro
• 6.2 · Caricare ed eseguire effetti sonori e musiche
• 6.3 · Pulizia delle risorse sonore allocate
• 7 · Gestione dell'input
• 7.1 · Utilizzo del gamepad virtuale
• 7.2 · Definizione di cheat
• 7.3 · Utilizzo del mouse virtuale
• 8 · Gestione dei punteggi
• 8.1 · Gestione incrementale dei punteggi
• 9 · Gestione dei livelli
• 9.1 · Struttura di un livello
• 9.2 · Caricamento di un livello da file
• 9.3 · Disegno di un livello
• 10 · Gestione delle collisioni
• 10.1 · Rect Collision
• 10.2 · Tile Collision
• 11 · Gestione delle visuali
• 11.1 · Scrolling libero
• 11.2 · Scrolling pigro
• 11.3 · Monitoraggio dell'area di scrolling
• 12 · Gestione dei timer
• 13 · Gestione degli eventi di gioco
• 13.1 · Tipologie di evento
• 13.2 · Definizione di un evento generico
• 13.3 · Definizione di un evento di warp
• 13.4 · Definizione di un evento di dialogo
• 14 · Menú di gioco
• 14.1 · Tipologie di menú
• 14.2 · Struttura di un menú
• 14.3 · Struttura dei contenuti del menú (Item)
• 14.4 · Definizione di un oggetto Menú
• 14.4a · Menú classico
• 14.4b · Menú a tabella
• 14.4c · Menú a pagine
• 14.5 · Gestione dei menú
• 14.6 · Aggiunta dinamica di elementi al menú
• 14.7 · Aggiunta statica di elementi al menú
• 14.8 · Eliminazione di un Menú
• 15 · Gestione degli FPS

1 · introduzione

2 · Struttura del progetto

2.1 · Per cominciare

/**
 * Prima di liberare le risorse dal sistema bisogna terminare il ciclo
 * principale del programma
 **/
void quitGame()
{
	quit = 1;
}

int main(int argc, char *argv[])
{

    // Inizializzazione sistemi interni SDL
    if(SDL_Init(SDL_INIT_VIDEO | SDL_INIT_JOYSTICK) != 0)
    {
        fprintf(stderr, "Can't initialize SDL: %s\n", SDL_GetError());
        exit(-1);
    }
    atexit(SDL_Quit);

    // Inizializzazione schermo
    #ifdef DOUBLE_SCREEN

        double_screen = SDL_SetVideoMode(SCREEN_WIDTH*2, SCREEN_HEIGHT*2, 
                        0, SDL_HWSURFACE);
        if(double_screen == NULL)
        {
            fprintf(stderr, "Can't initialize SDL: %s\n", SDL_GetError());
            exit(-1);
        }
        
        screen = SDL_CreateRGBSurface(0,SCREEN_WIDTH,SCREEN_HEIGHT,32,0,0,0,0);
            
    #else

        screen = SDL_SetVideoMode(SCREEN_WIDTH, SCREEN_HEIGHT, 0, SDL_HWSURFACE);
        if(screen == NULL)
        {
            fprintf(stderr, "Can't initialize SDL: %s\n", SDL_GetError());
            exit(-1);
        }

    #endif
	
    //Inizializzazione sottosistemi RetroGear
    init();

    //Parametri definiti dal programmatore
    mainInit();

    //Main game loop
    mainLoop();

    //Pulizia delle risorse allocate
    cleanUp();

    return 0;
}

void init()
{
    //FPS per il gioco
    fps.frequency= 1000 / 100;

    quit = 0;
    Game.status = GAME;
    curr_menu = &main_menu;
	
    //Inizializzazione dei sottosistemi di gioco
    initFont();
    initAudio();
    initScore();
    initController();

    initTypewriter(&typewriter, FONT_W, (SCREEN_HEIGHT/2)+56, SCREEN_WIDTH-(FONT_W*3));
    initTransition(TILESIZE, transition_lines);

    setCurrentPlayer(&Player);
    initPlayer(curr_player);

    //Inizializzazione del livello
    initLevel();
    loadLevel(&level, "main");

    initCamera(&camera);
}

void extInit()
{
	SDL_WM_SetCaption("RetroGame", "RetroGame");
	
	initMenu(menuptr, 1, 30, 10, "main", NULL, NULL);
	addMenuItem(menuptr, createItem(1,"New Game", white, doPreGame));
	addMenuItem(menuptr, createItem(5,"Quit", white, quitGame));
	alignMenuCenter(menuptr);
	alignMenuBottom(menuptr);
}

2.2 · Stati di gioco

void mainLoop()
{
	while(!quit)
	{
		keyboardInput();
		
		unsigned int maxl = 256;
		fps.now = SDL_GetTicks();
		fps.dtime += fps.now - fps.then;
		fps.then = fps.now;

		while (--maxl && fps.dtime >= LOGICMS)
		{
			switch(Game.status)
			{
				case MENU:
				 doTitleScreen();
				break;
				
				case PREGAME:
				 doPreGame();
				break;

				case GAME:
				 doGame();
				break;

				case LOST:
				 doLogic();
				break;

				case WIN:
				 doWin();
				break;

				case GAMEOVER:
				 doGameOver();
				break;

				case EDITOR:
				 doEditor();
				break;
			}

			fps.now = SDL_GetTicks();
			fps.dtime += fps.now - fps.then - LOGICMS;
			fps.then = fps.now;
		}
		
		// Gestisce gli stati di disegno sullo schermo
		draw();
		
		SDL_Delay(1);
	 }
}

• MENU
  
  Si occupa di gestire lo schermo dei titoli, ed eventuali menù di gioco.
  
• PREGAME
  Schermata di pre-gioco, momento in cui si potranno mostrare al giocatore informazioni sommarie come numero del livello, vite disponibili ed altro, un po' come nei giochi di Super Mario Bros.
  La funzione viene presentata con un timer interno per gestire in modo automatico il passaggio allo status GAME.


• GAME
  Il gioco vero e proprio, qui dentro verrano gestite tutte le logiche inerenti al gioco, definite dal programmatore.
  
  In generale gestisce tutte le singole entità di gioco attive presenti in lista, gestisce gli input del giocatore e aggiorna lo stato del giocatore, oltre che all'occorrenza gestire anche entità di punteggio o quant'altro si voglia. (Si veda il capitolo riguardante le Entità per maggiori informazioni)


• LOST
  Gestisce il momento in cui il giocatore perde una vita, ad esempio quando entra in contatto con un nemico del livello.
  Lo status è pensato per agevolare lo sviluppatore nella realizzazione di logiche particolari per questi momenti, senza dover intasare lo status di GAME con controlli a cascata.
  Ovviamente il tutto è a discapito del programmatore.


• WIN
  Il momento in cui il giocatore vince, pensato per eseguire in modo pulito e distaccato della logica da eseguire a vittoria avvenuta del giocatore.
  Una sorta di schermo di fine gioco per intenderci, e come per il caso di LOST, agevolare il programmatore permettendogli di scrivere codice pulito e stratificato.


• GAMEOVER
  Gestione dello status di game over, in cui sarà possibile gestire in modo pulito e distaccato, tutta la logica relativa alla fase di game over, come ad esempio ripulire tutte le risorse allocate, reimpostare i valori interni del motore, azzerare punteggi e quant'altro si voglia.
  


• EDITOR
  Gestisce l'editor di livello e relativi eventi.
  In alternativa, si consiglia l'uso dell'editor ufficiale del progetto, Leveler.

    if(Game.status!=STATUS)
    {
        setGameState(STATUS);
    }

3 · Gestione della grafica

void draw()
{
	if(transition.flag_active)
	{
		doTransition();
	}
	else
	{
		clearScreen();
	
		switch(Game.status)
		{
			case MENU:
				drawTitle();
				break;
			case PREGAME:
				drawPreGame();
				break;
			case GAME:
				drawGame();
				break;
			case LOST:
				drawGame();
				break;
			case WIN:
				drawWin();
				break;
			case GAMEOVER:
				drawGameOver();
				break;
		}
	}
	
	callback_DrawSystemMessages();

	//Aggiorna lo schermo
	#ifdef DOUBLE_SCREEN
		SDL_SoftStretch(screen, NULL, double_screen, NULL);
		SDL_Flip(double_screen);
	#else
		SDL_Flip(screen);
	#endif
}

void callback_DrawSystemMessages()
{
	if(sys_message != NULL)
	{
		drawString(screen, 8, SCREEN_HEIGHT-16, sys_message, red, 0);

		if(getSeconds(sys_timer.start_time) > 3)
		{
			strcpy(sys_message, "");
			sys_timer.start_time = 0;
		}
	}
}

3.1 · Disegnare grafica semplice

SDL_Surface *screen, *tile_sheet, *alpha_sheet;

/** Colori RGB **/
static const SDL_Color white = {255, 255, 255};
static const SDL_Color black = {0, 0, 0};
static const SDL_Color cyan  = {0, 255, 255};
static const SDL_Color blue  = {0, 0, 255};
static const SDL_Color yellow  = {255, 255, 0};
static const SDL_Color purple = {255, 0, 255};
static const SDL_Color red  = {255, 0, 0};
static const SDL_Color green  = {0, 255, 0};
static const SDL_Color gray  = {192, 192, 192};

/** Colori Hex **/
#define RED 0xFF0000
#define BLUE 0x0000FF
#define GREY 0xC0C0C0
#define WHITE 0xFFFFFF
#define BLACK 0x000000
#define GREEN 0x008000
#define ORANGE 0xFF9D2E
#define PURPLE 0xFF00FF
#define YELLOW 0xFFFF00
#define COLORKEY 0x00FF00

#define SKYBLUE 0x8080FF

Uint32 get_pixel(SDL_Surface *surface, int x, int y);
void put_pixel(SDL_Surface *_ima, int x, int y, Uint32 pixel);
void replaceColor (SDL_Surface * src, Uint32 target, Uint32 replacement);
void drawFillRect(int x, int y, int w, int h, int color);
void drawRect(int x, int y, unsigned int w, unsigned int h, int color);
void drawGui(int x, int y, unsigned int w, unsigned int h, int bg, SDL_Color color);
SDL_Surface * loadImage(char *file, Uint32 key);

• get_pixel
  
  Ritorna il valore di un pixel presente alla coordinate specificate nella superficie specificata, in modo sicuro e badando al numero di byte utilizzati nella superficie.
  
• put_pixel
  
  Disegna un pixel alle coordinate specificate sulla superifice specificata, in modo sicuro e badando al numero di byte utilizzati nella superficie.
  
• replaceColor
  
  Rimpiazza un colore specifico (target) con uno un rimpiazzo (replecement) all'interno di una determinata superficie pixel per pixel.
  
• drawFillRect
  
  Disegna un rettangolo delle dimensioni specificate sulla superficie principale di sistema
  
• drawRect
  
  Disegna un rettangolo dall'interno vuoto e delle dimensioni specificate sulla superficie principale di sistema
  
• drawGui
  
  Disegna una semplice cornice utilizzando i font di sistema, utile per finestre di dialogo o menù di gioco.
• loadImage
  
  Carica un'immagine BMP specifica in una superficie e ne converte il formato in quello attuale dello schermo per un disegno più rapido
  
• getSprite
  
  Preleva un fotogramma da uno sprite sheet all'indice indicato, di dimensioni specifiche e lo mostra alle coordinate volute sulla superficie dello schermo
  

3.2 · Utilizzo degli sprite

    typedef struct _Sprite {
        SDL_Surface *surface;
        int x, y;
        int w, h;
        int index;
        float animation_timer;
        float animation_speed;
    } Sprite;

• SDL_Surface *surface
  Puntatore alla superficie grafica in cui verrà contenuta l'immagine dello sprite


• int x, y, w, h
  
  Coordinate a cui verrà disegnato lo sprites.
  Possono essere quelle di una entità, o libere, per una rappresentazione di immagini svincolate dagli oggetti di gioco.

int w, h

Dimensioni dell'immagine da rappresentare.
Nel caso di entità, saranno la dimensione del singolo fotogramma dell'entità.
int index

Indice numerico del fotogramma attualmente visualizzato.
float animation_timer

Timer utilizzato per l'avanzamento delle animazioni.
float animation_speed

Velocità dell'animazione, questo valore incrementa la variabile animation_timer.

	SDL_Rect dest;
	dest.x = 20;
	dest.y = 50;
	dest.w = 16;
	dest.h = 16;

	getSprite(skel_spr, 0, dest.w, dest.h, &dest);

skel_spr=loadImage("data/skel.bmp", 0x00FF00);

4 · Entità di gioco

4.1 · Gestione delle entità di gioco

• int type
  Tipologia della entità, come ad esempio nemico, bonus o power-up.
  L'associazione numerica Valore/Tipologia è rilegata alla variabile enumerativa OBJECTS, che dona maggiore leggibilità al codice, oltre che uno strumento comune a tutte le entità di gioco.
  
  Trova una sua utilità nei momenti in cui sia necessario controllare eventuali collisioni con determinate tipologie di oggetti, per scatenare particolari eventi.
  
  Esempio:
  Collisione Player <-> Entità COLLECTABLE -> Aumenta il punteggio del giocatore di 100 punti.
  Collisione Player <-> Entità ENEMY -> Decrementa il numero di vite del giocatore.
  
  Per maggiori informazioni riguardo la variabile OBJECTS, si consulti il capitolo 3.3 · Tipologie e stati di una entità


• int solid
  
  Flag che specifica se la entità è da considerarsi oggetto solido o meno.
  Gli oggetti solidi sono da considerarsi come ostacoli per il giocatore, oggetti impossibili da attraversare.
  Utile per gestire quei tipi di oggetti piazzati come ostacoli provvisori sul campo di gioco, e distruttibili tramite l'esecuzione di particolari azioni.


• int x, int y, int w, int h
  
  Rispettivamente, le coordinate x, y, e relativa larghezza ed altezza della entità.


• int lives
  
  Tiene conto del numero di vite disponibili della entità, da poter utilizzare come energia della entità o numero di possibilità disponibili per il giocatore, a partita.


• RG_Sprite sprite
  
  Puntatore ad una struttura di tipo RG_Sprite, che rappresenta l'immagine dell'entità nella finestra di gioco. Si tenga conto che si tratta di un semplice puntatore a struttura, e che la sua valorizzazione avviene tramite apposita funzione initSprite().


• float speed
  
  La velocità dell'entità nel campo di gioco, ovvero il numero di pixel che avremo per spostamento ad ogni ciclo.


• float gravity
  
  Gravità esercitata sull'entità, questo valore agirà sull'entità di gioco come forza motrice verso il basso.


• void (*update)()
  
  Puntatore alla funzione di aggiornamento dell'entità.
  Il puntatore contiene solamente l'indirizzo di memoria di una funzione precedentemente dichiarata dal programmatore, con la logica d'azione dell'entità.
  Si veda il capitolo apposito per maggiori informazioni.

4.2 · Definizione di una entità

    #ifndef _SKEL_H
    #define _SKEL_H

    #define SKEL_SPRITE_W 16
    #define SKEL_SPRITE_H 16

    #define SKEL_W 12
    #define SKEL_H 12

    #define MIN_H_SPEED -1.0f
    #define MAX_H_SPEED 1.0f

    #define MIN_V_SPEED -1.0f
    #define MAX_V_SPEED 1.0f

    SDL_Surface *skel_spr;

    #include "entity.h"

    void skel_create(int id, int x, int y);
    void updateSkel(Entity *pobj);
    void skel_clean();

    #endif
    

    #include "skel.h"

    //Eventuale punteggio ottenibile
    #define SCORE 100
    #define TYPE 3

    static void onAnimate(Entity *pobj);
    static void onCollision(Entity *pobj);
    static void onDestroy(Entity *pobj);

    void skel_create(int id, int x, int y)
    {
        float speed = 0.8f;
        float gravity = 0.05f;
        float animation_speed = 0.05f;
        int lives = 0;

        createEntity(ENEMY, x, y, SKEL_W, SKEL_H, lives,
                     speed, gravity, &updateSkel);

        //Impostiamo lo sprite
        int sprite_diff_w = (SKEL_SPRITE_W - SKEL_W) / 2;
        int sprite_diff_h = (SKEL_SPRITE_H - SKEL_H) -1;

        //entityList_Tail è l'ultima entità creata
        if( !entityList_Tail->sprite.surface )
        {
            initSprite(&entityList_Tail->sprite,
                       entityList_Tail->x + sprite_diff_w,
                       entityList_Tail->y + sprite_diff_h,
                       SKEL_W, SKEL_H,
                       animation_speed,
                       "data/skel.bmp");
        }

        //Velocità e direzioni iniziali della entità
        entityList_Tail->hspeed = 0;
        entityList_Tail->vspeed = 1;
        
        entityList_Tail->direction_x = -1;
        entityList_Tail->direction_y = 0;
    }


    /**
     * Custom entità animator
     **/
    static void onAnimate(Entity *pobj)
    {
        pobj->sprite.animation_timer += pobj->sprite.animation_speed;

        if (pobj->sprite.animation_timer > 2)
        {
            pobj->sprite.animation_timer = 0;
        }

        pobj->sprite.index = (pobj->direction_x < 0 ? 0 : SPRITE_FRAMES)+
                              abs(pobj->sprite.animation_timer);
    }

    static void onCollision(Entity *pobj)
    {
        entità *current = entityList_Head;
        while(current!=NULL)
        {
            if(current!=pobj && current->active && 
               current->status!=KILL && current->type!=COLLECTABLE)
            {
                if(rectCollision(current->x, current->y,
                                 current->w, current->h, 
                                 (int)(pobj->x)+pobj->direction_x,
                                 pobj->y, pobj->w, pobj->h))
                {
                    pobj->direction *=-1;
                }
            }
            current=current->next;
        }
    }

    static void onDestroy(Entity *pobj)
    {
        if(getSeconds(pobj->timer[0]) >= 1)
        {
            pobj->status=DESTROY;
            pobj->visible=0;
        }
    }

    void updateSkel(Entity *pobj)
    {
        if(pobj->status==KILL)
        {
            //Indice dell'immagine dell'entità sconfitta nello sprite sheet
            pobj->frame_index = DIE;		
            onDestroy(pobj);
            return;
        }

        if(rectCollision(Player.x, Player.y, Player.w, Player.h,
                    pobj->x, pobj->y, pobj->w, pobj->h))
        {
            pobj->ystart=pobj->y;
            //Impostiamo lo status a KILL
            pobj->status=KILL;			
            pobj->direction=0;

            createScore(pobj->x+camera.offsetX, pobj->y, 0.4f);
            addScore(getScore(points_index));
            points_index++;
            
            //Salviamo il momento in cui la entità viene schiacciata
            pobj->timer[0]=fps.t;	
            return;
        }

        moveEntity_X(pobj);
        animateEntity(pobj);
        //onAnimate(pobj);  //Alternativa per le animazioni
        onCollision(pobj);
    }
    

4.3 · Tipologie e stati di una entità

typedef enum
{
    PLAYER, COLLECTABLE, ENEMY, BULLET, WALL, OBSTACLE
} ENTITY_TYPE;
    

createEntity(ENEMY, x, y, SKEL_W, SKEL_H, lives,
             speed, gravity, &updateSkel);
[...]

if(current!=pobj && current->active
   && current->status!=KILL && current->type!=COLLECTABLE)

typedef enum
{
    MOVE, ACTION, JUMP, FALL, CLIMB, STAND, BLINK, KILL, DESTROY
} ENTITY_STATUS;

4.4 · Animare le entità

enum
{
	//Left
	STANDLEFT = 0,
	WALKLEFT1 = 1,
	WALKLEFT2 = 2,
	WALKLEFT3 = 3,
	RETURN1 = 4,
	JUMPLEFT = 5,

	//Right
	STANDRIGHT = 6,
	WALKRIGHT1 = 7,
	WALKRIGHT2 = 8,
	WALKRIGHT3 = 9,
	RETURN2 = 10,
	JUMPRIGHT = 11,

	//Down
	STANDDOWN = 12,
	WALKDOWN1 = 13,
	WALKDOWN2 = 14,
	WALKDOWN3 = 15,
	RETURN3 = 16,

	//Up
	STANDUP = 18,
	WALKUP1 = 19,
	WALKUP2 = 20,
	WALKUP3 = 21,
	RETURN4 = 22,

	DIE = 17
} spriteSheet;

static void onAnimate(Entity *pobj)
{
    pobj->sprite.animation_timer += pobj->sprite.animation_speed;

    if (pobj->sprite.animation_timer > 2)
    {
        pobj->sprite.animation_timer = 0;
    }

    pobj->sprite.index = (pobj->direction_x < 0 ? 0 : SPRITE_FRAMES)+
                          abs(pobj->sprite.animation_timer);
}

4.5 · Rimozione di una entità

4.6 · L'entità Player

//Funzioni private
void playerAction();
void movePlayerStatic();
void movePlayerDynamic();

/**
 * Reimposta il giocatore ai valori di default
 * 
 * @param entity *player
 * 		Puntatore alla struttura del giocatore
 **/
void initPlayer(entity *player)
{
    player->type = PLAYER;
    player->visible = 1;
    player->flag_active = 1;
    player->w= PLAYER_W;
    player->h= PLAYER_H;
    player->lives = 3;
    Player.speed = 0.05f;

    //Differenza tra dimensioni del giocatore e sprite
    int sprite_diff_w = (PLAYER_SPRITE_W - PLAYER_W) / 2;
    int sprite_diff_h = (PLAYER_SPRITE_H - PLAYER_H) -1;

	if( !player->sprite.surface )
	{
        initSprite(&player->sprite, player->x-sprite_diff_w,
                   player->y-sprite_diff_h, 16, 16, 0.09f, "data/player.bmp");
	}

	player->hspeed = 0;
	player->vspeed = 0;
    
        Player.gravity=0.1f;
    
	player->direction_x = 1;
	player->direction_y = 0;
}

void setPlayerPosition(int x, int y)
{
	curr_player->x = x;
	curr_player->y = y;
	curr_player->xstart = x;
	curr_player->ystart = y;
}

void playerExtraLife()
{
	curr_player->lives++;
	playSound(extralife_snd);
}

void playerAction()
{
	curr_player->sprite.index = 0;	//Action sprite index
	//Action time
	//Action function	
}

/**
 * Principale funzione di aggiornamento per il giocatore
 **/
void updatePlayer()
{
    scrollCameraX(&camera, curr_player->x);
    scrollCameraY(&camera, curr_player->y);

    animateEntity(curr_player, 0);
    movePlayerStatic();
}

/**
 * Move the player with dynamic speed
 **/
void movePlayerDynamic()
{
	/**
     * Movimento orizontale
     **/

	if (curr_gamepad->button_Left)
	{
		Player.direction_x = -1;
        Player.status = MOVE;

        Player.hspeed += Player.speed * Player.direction_x;
	}
	
	[...]

	/**
     * Movimento verticale
     **/
	if (curr_gamepad->button_A==PRESSED)// && !lockjump)
	{
        curr_gamepad->button_A = LOCKED;
        if(!isEntityOnFloor(&Player))
        {
            return;
        }

		//if the player isn't jumping already
		Player.vspeed = -2.6f;		//jump!
	}

	[...]

    doEntityGravity(&Player);
}

/**
 * Move the player with dynamic speed
 **/
void movePlayerStatic()
{
    RG_Point *point = NULL;

    //Move only if there's no obstacles
    //TODO: To be tested
    point = tileCollision(&Player, Player.x+Player.hspeed, Player.y);
    if( point != NULL )
    {
        Player.x += Player.hspeed;
        Player.y += Player.vspeed;
    }
    
    //Se il giocatore non è allineato con la griglia
	if(!isInTile(Player.x,Player.y))
	 return;
    
	//horizontal
	if (curr_gamepad->button_Left)
	{
		Player.direction_x = -1;
        Player.direction_y = 0;
        
        Player.hspeed = -1.0f;
	}
	
	[...]
}

void drawPlayer()
{
    if(Game.status < GAME) return;

    int dest_x = (int)curr_player->x-2 - camera.offsetX;
    int dest_y = (int)curr_player->y+1 - camera.offsetY;

    drawSprite(&curr_player->sprite, dest_x, dest_y);
	
    [...]
}

	if(!isInTile(Player.x,Player.y))
        return;

    #define MIN_H_SPEED -1.0f
    #define MAX_H_SPEED 1.0f

    #define MIN_V_SPEED -1.0f
    #define MAX_V_SPEED 1.0f

4.7 · Gestione multigiocatore

entity Player[2];
entity *curr_player;

5 · Gestione dei font

5.1 · Utilizzo dei font e scrittura

• int dest_x, int dest_y
  
  Destinazione in cui si andrà a copiare il contenuto di origine


• int asciicode
  
  Il valore decimale del singolo carattere


• SDL_Color color
  
  Struttura contenente i valori RGB di colore da usare per la superficie.

int dest_x, int dest_y

Rispettivamente, le coordinate x, y a cui andare a disegnare il testo

• char *text
  
  La stringa da disegnare nella superficie video specificata.


• SDL_Color color
  
  Il colore da utilizzare per il testo.
  Il parametro viene gestito dalla funzione drawChar().


• int alpha
  
  Flag per l'attivazione della trasparenza nello sfondo dei carattteri.
  Il parametro viene gestito dalla funzione drawChar().

	//Esempio di cursore per menù di gioco
	drawChar(screen, menuptr->items[menuptr->curr_item].x-10, 
			 menuptr->items[menuptr->curr_item].y, '*', white, 1);

	//Esempio su come mostrare il numero di vite rimaste al giocatore
	sprintf(message,"%d", Player.lives);
	drawString(screen, 115, 117, message, white, 1);

	//Esempio di testo libero
	drawString(screen, 10, 20, "Hello World!", white, 1);

	

5.2 · Utilizzo del sistema Typewriter

6 · Gestione del sonoro

void initAudio()
{
	audio_rate = 22050;			//Frequenza di playback
	audio_format = AUDIO_S16; 	//Formato dell'audio
	audio_channels = 2;			//2 canali = stereo
	audio_buffers = 4096;		//Dimensione del buffer per i file sonori
	
	//Inizializzazione SDL_Mixer
	if(Mix_OpenAudio(audio_rate, audio_format, audio_channels, audio_buffers)) {
		printf("Unable to initialize audio: %s\n", Mix_GetError());
		exit(1);
	}

	//Caricamente effetti sonori
	collectable_snd = loadSound("snd/collectable.wav");
	stomp_snd = loadSound("snd/stomp.wav");
	jump_snd = loadSound("snd/jump.wav");
	action_snd = loadSound("snd/action.wav");
	extralife_snd = loadSound("snd/extra_life.wav");

	//Caricamento musiche
	title_music = loadMusic("snd/title_theme.wav");
	pregame_music = loadMusic("snd/pregame_theme.wav");
	game_music = loadMusic("snd/level_theme.wav");
	gameover_music = loadMusic("snd/gameover_theme.wav");
	goal_music = loadMusic("snd/goal.wav");
}
	

• collectable_snd - Il suono di default per gli oggetti di tipo COLLECTABLE.
• stomp_snd - Il suono di default per l'azione/status STOMP di una entità.
• action_snd - Il suono di default da eseguire per lo status ACTION di una entità.
• extralife_snd - Il suono di default da eseguire per il conseguimento di una vita extra.

• title_music - Musica da eseguire nello status di gioco MENU.
• pregame_music - Musica da eseguire nello status di gioco PREGAME.
• game_music - Musica da eseguire nello status di gioco GAME.
• gameover_music - Musica da eseguire nello status di gioco LOST.
• goal_music - Musica da eseguire nello status di gioco WIN.

6.1 · Stati di gioco e sonoro

	if(!isMusicPlaying())
	{
		playMusic(title_music, 0);
	}
	

void doPreGame()
{
	if(Game.status!=PREGAME)
	{
		setGameState(PREGAME);
	}

	//Stop any music from the game
	if(isMusicPlaying())
	{
		pauseMusic();
	}

	if(getSeconds(timer.start_time) > 2)
	{
		//Reset generic timer
		timer.start_time = 0;
		//Let's play!
		setGameState(GAME);
		playMusic(game_music, 0);
		return;
	}
	
	if(Player.lives==0)
	{
		playMusic(gameover_music, 0);
		setGameState(GAMEOVER);
		return;
	}
}
	

6.2 · Caricare ed eseguire effetti sonori e musiche

my_snd = loadSound("snd/sound.wav");

my_music = loadMusic("snd/music.wav");

playSound(my_snd);

playMusic(my_music, 0);

void pauseMusic();
void resumeMusic();
int isMusicPlaying();

6.3 · Pulizia delle risorse sonore allocate

	destroyMusic(title_music);
	destroyMusic(pregame_music);
	destroyMusic(game_music);
	destroyMusic(goal_music);
	
	destroySound(player_die_snd);

	//Free default sounds
	destroySound(collectable_snd);
	destroySound(stomp_snd);
	destroySound(bounce_snd);
	destroySound(jump_snd);
	destroySound(action_snd);

	Mix_CloseAudio();
	

7 · Gestione dell'input

7.1 · Utilizzo del gamepad virtuale

#include "controls.h"

if (curr_gamepad->button_A)
{
    //Input continuo senza interruzioni
}
else
{
    //Input terminato
}

if (curr_gamepad->button_A)
{
    //Interrompiamo la ripetizione dell'input
    curr_gamepad->button_A = 0;
}

7.2 · Definizione di cheat

7.3 · Utilizzo del mouse virtuale

if(Mouse.leftButton)
{
//Tasto sinistro premuto
}

8 · Gestione dei punteggi

typedef struct _scoreType
{
  int xstart, ystart;   //Coordinate iniziali
  int speed;            //Velocità di movimento

  Sprite sprite;        //Sprite
  short int status;

  struct _scoreType *next;
} scoreType;

scoreType *scoreHead, *scoreTail;

enum { pts100,
       pts200,
       pts400,
       pts500,
       pts800,
       pts1000,
       pts2000,
       pts4000,
       pts5000,
       pts8000,
       pts1UP,
       pts2UP,
       pts3UP,
       pts4UP,
       pts5UP
    } SCORES;

void createScore(int x, int y, int speed, int sprite_index);

//Esempio d'uso
createScore( ((int)pobj->x-camera.offsetX),
             ((int)pobj->y-camera.offsetY),
             1,
             pts100);
addScore( 100 );

8.1 · Gestione incrementale dei punteggi

createScore( ((int)pobj->x-camera.offsetX),
             ((int)pobj->y-camera.offsetY),
             1,
             points_index);
addScore( getScore() );

static int points[] = {100, 200, 400, 500, 800, 1000, 2000, 4000, 5000, 8000};

int getScore()
{
    if(points_index>=pts1UP)
    {
        if(points_index>=pts5UP)
        {
            points_index = pts5UP;
        }

        // 1up...
        playerExtraLife(points_index);
    }
    else if(points_index<=pts8000)
    {
        //Per punteggi normali, ritorniamo il valore di punteggio
        return points[points_index++];
    }
	
	return 0;
}

9 · Gestione dei livelli

level title
level description
tile_sheet
backgroun_music.wav
0,255,255
2
7,7
0,0,0,0,0,0,0,
0,2,0,0,0,0,0,
0,0,0,0,0,0,0,
0,0,0,0,0,0,0,
0,0,0,0,0,0,0,
0,0,0,0,0,3,0,
0,0,0,0,0,0,0,

2,2,2,2,2,2,2,
2,2,2,2,2,1,2,
2,2,1,1,2,1,2,
2,2,1,1,1,1,2,
2,1,1,1,1,1,2,
2,1,1,1,1,7,2,
2,2,2,2,2,2,2,

9.2 · Caricamento di un livello da file

    loadLevel(&level, "main");

void createEntityFromMap(int id, int x, int y)
{
    col = tilesToPixels(col);
    row = tilesToPixels(row);
	
	switch(id)
	{
		case PLAYER_ID:
			setPlayerPosition(x, y);
		break;

		case 4:
			badguy_create(x, y);
		break;

		case 5:
			coin_create(x, y);
		break;
	}
}

9.3 · Disegno di un livello

• Il layer 0, SOLID_LAYER, è utilizzato per la creazione delle entità e la definizione di ostacoli (blocchi solidi) nel livello.
  
  Questo layer, non viene disegnato su schermo.
  
  


• Il layer 1, BACKG_LAYER, è utilizzato per il disegno del livello, ogni singolo valore rappresenterà un tile da disegnare, prelevato dallo sprite sheet tile_sheet.
  
  


• 
  
  Il layer 2, ALPHA_LAYER, è utilizzato per il disegno del livello, come il layer 1, ma su di uno strato superiore.
  Questo layer disegnerà ogni cosa al di sopra di ogni altro contenuto grafico presente nel gioco, comprese entità e giocatori.
  
  L'implementazione di questo layer nel file di livello è facoltativo.
  
  
• 
  
  Questo è un esempio del risultato ottenibile dal disegno di ogni singolo layer nel campo di gioco.
  
  

10 · Gestione delle collisioni

• Rect collision
• Tile collision

10.1 · Rect Collision

if(rectCollision(Player.x, Player.y, Player.w, Player.h,
		 pobj->x, pobj->y, pobj->w, pobj->h))
{
	//Un qualche tipo di azione...
}
	

10.2 · Tile Collision

RG_Point *point = NULL;     //Coordinate della collisione

if(curr_player->hspeed<0)
{
    //Collide a sinistra?
    point = tileCollision(pobj, floorf(pobj->x+pobj->hspeed), pobj->y);
    if( point != NULL )
    {
        pobj->x= point->x+TILESIZE;      //Posizioniamo la entità accanto al tile
    }
    else
    {
        pobj->x += pobj->hspeed;         //Muoviamo la entità
    }
}
    //Collide a destra?
else if(pobj->hspeed>0)
{
    point = tileCollision(pobj, ceilf(pobj->x+pobj->hspeed), pobj->y);
    if( point != NULL )
    {
        pobj->x= point->x-pobj->w;
    }
    else
    {
        pobj->x += pobj->hspeed;
    }
}
	

11 · Gestione delle visuali

#define CENTER_X ((SCREEN_WIDTH - TILESIZE) / 2)
#define CENTER_Y ((SCREEN_HEIGHT - TILESIZE) / 2)

RG_Rect camera;

// Aggiornamento posizione Camera X/Y
pcam->x += (x - pcam->x - CENTER_X);
pcam->y += (y - pcam->y - CENTER_Y);

// Aggiornamento posizione Camera max X/Y
pcam->x = (TILESIZE*curr_level->cols - SCREEN_WIDTH);
pcam->y = (TILESIZE*curr_level->rows - SCREEN_HEIGHT);

11.1 · Scrolling libero

11.2 · Scrolling pigro

///Abilita lo scrolling "pigro"
#define LAZY_SCROLL
	

11.3 · Monitoraggio dell'area di scrolling

12 · Gestione dei timer

pobj->timer[0] = fps.t;

if(get_time_elapsed(pobj->timer[0]) >= 5)
{
    //Sono passati 5 secondi
}

if(get_time_elapsed(pobj->timer[0]) >= 5000)
{
    //Sono passati 5 secondi
}
	

13 · Gestione degli eventi di gioco

typedef enum
{
    WARP_EVT, DIALOGUE_EVT, OBJECT_EVT, GENERIC_EVT
} EVENT_TYPE;

typedef struct _Event {
	char mapname[20];
	unsigned int evt_x, evt_y;
	char parameters[100];
	int flag_save;
	struct _Event *next;
} Event;

Event *eventsGeneric,   //Lista di eventi generica
      *eventsWarp;      //Lista di eventi warp

• coordinate: Coordinate dell'evento, come valori chiave univoci, per recuperare l'evento in una posizione ben specifica.
  


• parametri: Stringa contenente informazioni di varia natura, nel formato char *,int,int. Lunghezza massima consentita: 100 caratteri.
  

13.2 · Tipologie di evento

13.3 · Definizione di un evento generico

• Event **pEvent: Puntatore al nodo principale della lista, da passare per deferenziazione (&eventList).
  


• char *mapname: Nome della file di livello di appartenenza dell'evento.
  


• unsigned int evt_x, unsigned int evt_y: Coordinate dell'evento, punto specifico in cui l'evento risiede ed in cui le entità di gioco devono trovarsi per scatenarlo.
  
• char *parameters: Stringa contenente informazioni di varia natura, a discrezione del programmatore. Lunghezza massima consentita: 100 caratteri.
  


• int flag_saves: Flag per la permanenza dell'evento durante la transizione da un livello di gioco ad un altro.
  

void playerThink()
{
    int col, row;
    //Posizione attuale in tile
    col = pixelsToTiles( Player.x );
    row = pixelsToTiles( Player.y );

    //Controlliamo la presenza di un punto di transizione
    if(curr_level->map[SOLID_LAYER][row][col] == WARP)
    {
        //Richiediamo l'evento, se presente, il puntatore sarà diverso da NULL
        Event *warp = getEvent(eventsWarp, curr_level->name, col, row);
        
        if(warp)
        {
            unsigned int dest_x, dest_y;
            char dest_map[10];

            /**
             * Il parametro dell'evento è nel formato "char*,int,int"
             * La stringa "%[^,]" significa "Leggi sino a che non incontri una virgola"
             **/
            sscanf(warp->parameters, "%[^','],%d,%d", dest_map, &dest_x, &dest_y);

            //Eseguiamo azioni di routine e facciamo uso dei parametri recuperati
            cleanEntities();
            loadLevel(curr_level, dest_map);
            initCamera(&camera);
            setPlayerPosition(dest_x, dest_y);
        }
    }

    think = 1;
}

13.4 · Definizione di un evento di warp

Esempio: 3,4,underground,1,2

1. Eseguire un effetto grafico di transizione ed un effetto sonoro, entrambi impostati di default
2. Ripulire la lista delle entità allocate
3. Caricare il nuovo file di livello
4. Inizializzare l'oggetto Camera
5. Impostare le coordinate del giocatore nel nuovo livello

void playerThink()
{
    int col, row;
    //Posizione attuale in tile
    col = pixelsToTiles( Player.x );
    row = pixelsToTiles( Player.y );

    //Controlliamo la presenza di un punto di transizione
    if(curr_level->map[SOLID_LAYER][row][col] == WARP)
    {
        //Richiediamo l'evento, se presente, il puntatore sarà diverso da NULL
        Event *warp = getEvent(eventsWarp, curr_level->name, col, row);
        
        if(warp)
        {
            unsigned int dest_x, dest_y;
            char dest_map[10];

            /**
             * Il parametro dell'evento è nel formato "char*,int,int"
             * La stringa "%[^,]" significa "Leggi sino a che non incontri una virgola"
             **/
            sscanf(warp->parameters, "%[^','],%d,%d", dest_map, &dest_x, &dest_y);

            //Eseguiamo azioni di routine e facciamo uso dei parametri recuperati
            cleanEntities();
            loadLevel(curr_level, dest_map);
            initCamera(&camera);
            setPlayerPosition(dest_x, dest_y);
        }
    }

    think = 1;
}

13.5 · Definizione di un evento di dialogo

Esempio: 3,4,Welcome to\nRetrogear\nKingdom!

static void onCollision(Entity *pobj)
{
    /**
     * Interact with the player
     * 
     * Preventing the Player walk on us
     * Handle talking request
     **/
    if(rectCollision(curr_player->x+curr_player->direction_x, curr_player->y+curr_player->direction_y,
                     curr_player->w+curr_player->direction_x, curr_player->h+curr_player->direction_y, 
                     pobj->x, pobj->y, pobj->w, pobj->h))
    {
        if(!flag_onDialog && (curr_gamepad->button_A) )
        {
            initDialog_from_file(pobj->x, pobj->y, curr_level->name);
        }
    }
}

if(!flag_onDialog && (curr_gamepad->button_A) )
{
    char text[] = "Hello world!";
    initDialog(text, NULL);
}

14 · Menú di gioco

• Una struttura per la definizione dei menú
• Una struttura per la definizione dei contenuti
• Funzioni standard per l'interazione
• Funzioni standard per il disegno delle varie tipologie di menù
• Funzioni standard per l'assegnazione veloce è pratica di parametri specifici dei menù
• Un menù di default per lo schermo dei titoli
• Un puntatore globale per la gestione del menù attualmente in uso da parte del giocatore
• Un ciclo proprio per l'esecuzione automatica delle funzioni di gestione e disegno all'interno dei vari status di gioco

typedef struct _Menu {
	int flag_active, flag_title, flag_border;
	int x, y;
	unsigned int w, h;
	char name[20];
	char cursor;
	int rows, cols;
	unsigned int page_start;
	int num_items, max_items;
	int curr_item;
	SDL_Color color;
	struct _Item *items;
	struct _Menu *previous, *next;
	void (*update)();
	void (*draw)();
} Menu;

typedef struct _Item
{
	int flag_used;
	int x, y;
	char name[15];
	//~ char *description;
	int	value;
	SDL_Color color;
	void (*func)();
	//Icon stuff
	//~ SDL_Surface *icon;
	//~ float frame_index, animation_speed;
} Item;

Menu main_menu, *curr_menu;

15.1 · Tipologie di menú

• Menú Classico
  
  Un classico menú di gioco, i cui elementi sono disposti verticalmente uno sotto l'altro.
  
• Menú a Tabella
  
  Come il menú classico, ma con elementi disposti su piú colonne.


• Menú a Pagine
  
  Visivamente identico al menú classico, questo menú mostra i propri contenuti a "pagine", mostrando un numero di elementi in colonna alla volta, permettendo di scorrere gli elementi lateralmente e mostrando una pratica freccia lampeggiande sul bordo inferiore ad indicare la presenza di altre "pagine".

15.2 · Struttura di un menú

• int flag_active
  
  Flag per l'attivazione/disattivazione di un menú, puó assumere i seguenti stati:
  • -1: Menú persistente - E' lo status in cui un Menú risulta visibile, ma non attivo per l'interazione con l'utente.
    Il menú continuerà ad essere visibile nel gioco ad oltranza, ma l'interazione sarà disponibile solo al momento della sua riattivazione.
  • 0: Menú invisibile/inattivo - E' lo status in cui un Menú risulta chiuso, ma ancora presente in memoria e quindi riutilizzabile.
  • 1: Menú visibile/attivo - E' lo status in cui un Menú risulta visibile e vi è permessa l'interazione.


• int flag_title
  
  Flag per mostrare/nascondere il nome del menù.
  Se il menú usa la funzione di default per il disegno, con questo flag si potrà abilitiare o disabilitare il disegno del nome del menú nella posizione di default (bordo alto del menú)
  Valore di default: 0;


• int flag_border
  
  Flag per mostrare/nascondere il bordo del menù.
  Se il menú usa la funzione di default per il disegno, con questo flag si potrà abilitiare o disabilitare il disegno del bordo del menú
  Valore di default: 1;


• int x, y
  
  Le coordinate del menú.
  


• int w, h
  
  Larghezza e altezza del menú.
  


• char name
  
  Stringa contenente il nome del menú.
  Larghezza massima: 20 caratteri compreso il terminatore di stringa.


• char cursor
  
  Carattere rappresentate il cursore degli elementi nel menú.
  Questo carattere è rappresentato tramite il font standard di RetroGear, è possibile valorizzare la variabile anche con un valore ASCII.


• int rows, cols
  
  Rispettivamente, numero di righe e colonne del menú.
  Queste variabili tengono conto del numero di righe e colonne occupate nel menú da parte degli Items inseriti.


• unsigned int page_start
  
  Variabile di supporto per la paginazione dei menú.
  Questa variabile tiene conto della posizione del primo Item per la pagina corrente, partendo da esso, disegna gli elementi successivi per il numero di righe assegnate al menú.
  


• int num_items
  
  Variabile contenente il numero di elementi presenti nel menú.
  Questa variabile è incrementata/decrementata in automatico all'aggiunta o rimozione di una voce dal menú.


• int max_items
  
  Variabile contenente il numero massimo di elementi inseribili nel menú.
  Un valore pari a -1 indica un menú senza limiti di inserimenti, 0 che non accetta alcun elemento.


• int curr_item
  
  Variabile contenente l'elemento attualmente selezionato nel menú.
  


• SDL_Color color
  
  Colore da utilizzare per testi e bordi del menú.
  


• struct _Item *items
  
  Puntatore a struttura di tipo Item, contenente le voci presenti nel menú.
  


• struct _Menu *previous, *next
  
  Puntatori a strutture di tipo Menu, per menù padre e figlo nel caso si necessiti di associarne.
  


• void (*update)()
  
  Puntatore alla funzione di gestione del menù.
  


• void void (*draw)()
  
  Puntatore alla funzione di disegno del menù
  

15.3 · Struttura dei contenuti del menú (Item)

• int flag_used
  
  Flag per segnalare l'inizializzazione o meno di un Item, usato nel caso di array statici di tipo Item per l'assegnazione al primo oggetto libero.


• int x, y
  
  Coordinate dell'elemento.
  Di default, il sistema imposta queste coordinate in base alla posizione assunta dall'oggetto Menu che le andrà a contenere, tramite apposite funzioni, tutta via potranno assumere qualunque valore a discrezione del programmatore.


• char name[15]
  
  Stringa contenente il testo della voce di menù.
  


• char * description;
  
  Stringa contenente una descrizione della voce di menù.
  Questo valore è opzionale, in quanto attualmente nessuna funzione di gestione standard di RetroGear se ne prende carico di gestione, ma nulla vieta al programmatore di implementarne una eventuale gestione all'interno della logica del proprio gioco.


• int value;
  
  Valore numerico intero assegnato alla voce di menù.
  Questo valore è considerato come proprietà della voce, alla quale il programmatore potrà fare riferimento tramite le apposite variabili ausiliari della struttura Menu (curr_item) ed intendere la voce come oggetto di inventario del giocatore.


• SDL_Color color;
  
  Colore del testo da applicare alla voce durante la fase di disegno.
  


• void (*func)();
  
  Puntatore a funzione di callback per la voce di menù.
  Utilizzando le funzioni standard di interazione con i menù di gioco, su pressione del tasto BUTTON_A, verrà eseguita una logica associata alla voce di menù, definibile dal programmatore.



15.4 · Definizione di un oggetto Menú

Definire un oggetto di tipo Menu richiede semplicemente la dichiarazione di una variabile di tipo Menu e successivamente l'inizializzazione tramite apposita funzione.


Menu my_menu;
	
//Inizializzazione standard
initMenu(&my_menu, NULL, 30, 10, "Menu", -1, white, NULL, NULL,
	 &menuInput, &drawMenuClassic);
	

In questo esempio è stato dichiarato un nuovo menú, chiamato my_menu, ed inizializzato tramite la funzione initMenu, dichiarata in menu.h.

La funzione initMenu è una funzione generica a cui poter passare in completa libertà e a discrezione del programmatore, tutti i valori fondamentali per l'inizializzazione corretta di un oggetto Menu, permettendo all'occorrenza di assegnare funzioni di logica definite in un secondo momento dal programmatore, ed ampliare così sulla base delle proprie esigenze il motore di gioco con menù personalizzati.

Nel caso si voglia un menú di tipo classico, si faccia riferimento alla funzione initClassiMenu, o alle apposite funzioni dedicate per la tipologia di menù voluta.

15.3a · Menú classico

La maggior parte delle tipologie di menù disponibili in RetroGear, di base sono tutti menu di tipo Classico, le differenze applicate su questa base, riguardano la disposizione degli elementi, e talvolta le modalità di interazione e disegno.

L'inizializzazione di un menu classico, avviene tramite la funzione initClassicMenu:

initClassicMenu(&my_menu, NULL, 30, 10, "Menu", -1, white, NULL, NULL);
	

Questa funzione accetta in argomento i seguenti valori:
• Menu* pmenu
  
  Puntatore (o referenza) alla struttura Menu da inizializzare.
• Item* pitem
  
  Puntatore (o referenza) alla struttura Item contenente gli elementi del menú.
  Se impostato a NULL, il menú viene considerato dinamico, in caso contrario statico.
  Nel caso di menú statici, vengono applicati controlli sul numero di elementi da gestire, verranno acccettati solo array di elementi con almeno un Item.
• int x, y
  
  I valori di coordinate del menú.
  Questi valori saranno punto di partenza per la disposizione e il disegno dei vari elementi del menú, nonché del bordo dello stesso.
• char *name
  
  Il nome del menú, che all'occorrenza verrà monstrato nella posizione di default (bordo alto).
• int max_items
  
  Numero totale di elementi che andranno gestiti nel menú.
  Un valore pari a -1 indica un menú senza limiti di item, 0 che non accetta alcun elemento.
• SDL_Color color
  
  Colore di default per il menú.
• Menu *parent
  
  Puntatore (o referenza) alla struttura Menu padre.
  Utilizzato nel caso di menú in sequenza, per permettere il ritono al menú precedente alla chiusura.
• Menu *child
  
  Puntatore (o referenza) alla struttura Menu figlio.
  Utilizzato nel caso di menú in sequenza, per permettere l'accesso a menú successivi.
Una volta inizializzata la struttura di menù classico, vi si potranno applicare stili di visualizzazione e di comportamento come segue:

//Disposizione a tabella degli elementi
setMenuTable(&my_menu, 4, 2, 4*FONT_W, 1);

//Disposizione a pagine degli elementi (5 per pagina)
setMenuPaginator(&my_menu, 5);

//Impostare un nuovo cursore per gli elementi
setMenuCursor(&my_menu, '*');
	

15.3b · Menú a tabella

Per avere un menù a tabella, una volta inizializzata correttamente la struttura Menu tramite la funzione initClassicMenu, ed aggiunti gli items, si può utilizzare la funzione setMenuTable come segue:

//Disposizione a tabella degli elementi
setMenuTable(&my_menu, 4, 2, 4*FONT_W, 1);
	

Questa funzione accetta in argomento i seguenti valori:
• Menu* pmenu
  
  Puntatore (o referenza) alla struttura Menu a cui applicare lo stile.
• int rows
  
  Numero di righe.
• int cols
  
  Numero di colonne.
• int col_width
  
  Larghezza di una colonna espressa in pixel.
  Nell'esempio si calcola 4 pixel per la larghezza di un carattere (8 pixel), totale 4 lettere (totale 32 pix3l).
• int row_spacing
  
  Spazio tra una riga e l'altra, espresso in pixel.
Il giocatore potrà interagire con gli elementi di menù muovendosi liberamente in quattro direzioni.
Tutto il sistema di gestione e disegno del menù, sarà preso in carico da funzioni dichiarate all'interno di RetroGear, ed assegnate in automatico al menù dalla funzione setMenuTable.
L'utilizzo della funzione setMenuTable su oggetti Menu privi di items, o non iniziliazziati, crea errori di memoria, l'utilizzo deve essere anticipato dall'aggiunta di oggetti Item valorizzati, all'interno dell'oggetto Menu.

15.3c · Menú a pagine

Il menù a pagine è un menù classico, i cui elementi sono visualizzati un numero di righe alla volta, e percorribili in quattro direzioni.

Per realizzare un menù a pagine, basterà inizializzare un menù classico e successivamente richiamare la funzione setMenuPaginator, dichiarata nel file menu_paginator.h.

setMenuPaginator(&my_menu, 5);
	

Questa funzione accetta in argomento i seguenti valori:
• Menu* pmenu
  
  Puntatore (o referenza) alla struttura Menu a cui applicare lo stile.
• int rows
  
  Numero di righe da mostrare per pagina.
Prendendo in considerazione un menù formato da 10 elementi, impaginato con 5 righe alla volta, verranno mostrati i primi 5 elementi nel caso in cui il cursore di selezione si trovi tra il primo e il quinto elemento, ed una pratica freccia lampeggiante sul bordo basso, a segnalare la presenza di altre pagine.
Nel caso in cui il cursore si trovi tra il sesto e il decimo elemento, verranno mostrati gli elementi da 6 a 10, e la freccia lampeggiante svanirà, in quanto non vi saranno altre pagine da mostrare.
Tutto il sistema di gestione e disegno del menù, sarà preso in carico da funzioni dichiarate all'interno di RetroGear, ed assegnate in automatico al menù dalla funzione setMenuPaginator.
L'utilizzo della funzione setMenuPaginator su oggetti Menu privi di items, o non iniziliazziati, crea errori di memoria, l'utilizzo deve essere anticipato dall'aggiunta di oggetti Item valorizzati, all'interno dell'oggetto Menu.

15.5 · Gestione dei Menú

Ogni menù di gioco dichiarato in RetroGear, può essere attivato e reso utilizzabile tramite la funzione menuInput, dichiarata nel file menu.h, che prendendo in argomento un puntatore (o referenza) ad una struttura di tipo Menu, si prenderà carico di richiamare per noi la funzione di aggiornamento (update) assegnata a tale struttura Menu.

void doTitleScreen()
{
	//Rendiamo utilizzabile un solo menù abilitandone l'interazione
	menuInput(&title_menu);
}
	

Nel caso avessimo una lista linkata di oggetti Menù, potremmo ricorrere alla funzione doMenu, che cliclerà ogni menù figlio impostato negli appositi puntatori all'interno della struttura:


void doGame()
{
	//Rendiamo utilizzabili i menù di gioco 
	//nello status GAME abilitandone l'interazione
	doMenu(&game_menu);
}
	

La funzione standard, intesa per l'interazione con un singolo menù di gioco è menuInput, la quale però prevede solo una interazione con tipici menù di gioco, dotati di validi elementi Item e strutturati su righe e colonne.
La funzione doMenu permette l'interazione anche di un singolo menù, delegando però il tutto alla funzione di aggiornamento assegnata alla variabile update della struttura.


L'utilizzo della funzione menuInput, non richiama la funzione assegnata alla variabile update della struttura Menu passata in argomento, ma si limita solamente a fornire solo un'interazione standard con il menù.
E' consigliabile utilizzare la funzione doMenu o in alternativa richiamare direttamente il puntatore a funzione dall'istanza stessa, per assicurarsi che l'interazione fornita si quella idonea e prevista per il menù in uso.

Il menù attualmente in uso da parte del giocatore è accessibile tramite il puntatore curr_menu, definito nel file menu.h.
Questo puntatore può essere passato in argomento sia alla funzione menuInput che alla funzione doMenu, che in questo ultimo caso eseguirà in cascata dal menù puntato in avanti, tutti i menù collegati come figli, uno dopo l'altro.

doMenu(curr_menu);
	

15.6 · Aggiunta dinamica di elementi al Menú

Per creare dinamicamente un oggetto di tipo Item ed aggiungerlo ad un oggetto di tipo Menu, insieme ad eventuali Item già presenti, si ricorre alla funzione addMenuItem.

addMenuItem(&my_menu, "my item", NULL, white, &doSomething);
	

La funzione addMenuItem, accetta in argomento un puntatore (o referenza) ad una struttura di tipo Menu, e nome, descrizione, colore e funzione di callback per l'oggetto Item che verrà allocato dinamicamente all'interno della struttura Menu.
Nel caso in cui vi siano già elementi di tipo Item nella struttura Menu passata in argomento, la funzione addMenuItem riallocherà dinamicamente tutti gli elementi di tipo Item sottoforma di array, appendendo il nuovo oggetto al fondo.

Dato che questi elementi sono allocati dinamicamente, bisognerà ricordarsi di deallocarli dalla memoria a fine programma. (Vedi 15.8 · Eliminazione di elementi da un Menú).

15.7 · Aggiunta statica di di elementi al Menú

Nel caso non volessimo allocare dinamicamente le voci di uno o più menù, potremmo raccoglierle in array statico di tipo Item ed assegnarle alle nostre strutture Menu. L'aggiunta di una voce ad un array statico di tipo Item, prevede l'uso della funzione addStaticMenuItem, la quale prenderà in argomento i dati essenziali alla creazione di un oggetto Item, e ciclerà l'array di tipo Item interessato, alla ricerca di una posizione libera in cui piazzare l'elemento.

#define TOTAL 20

//Inizializziamo un menù classico e passiamo in argomento l'array degli elementi
initClassicMenu(&my_menu, items_array, 10, 20, "Items", TOTAL, white, NULL, NULL);

//Inizializziamo l'array degli elementi prima dell'uso
initStaticMenuItems(quest_items, TOTAL_ITEMS);	

//Aggiungiamo un elemento statico al nostro array
addStaticMenuItem(&my_menu, "Item 1", 0, NULL, white, &doSomething);
	

In un array statico di tipo Item, una posizione libera è determinata dal suo valore flag_used impostato a -1.
Questo tipo di elementi non richiede alcuna operazione di deallocazione dalla memoria a fine esecuzione dell'applicazione, da parte del programmatore, ne permette la possibilità di aggiunte dinamiche.

15.8 · Eliminazione di elementi da un Menú

La deallocazione di elementi Item da un oggetto di tipo Menu avviene tramite la funzione destroyMenu, la quale prendendo in argomento un puntatore (o referenza) ad una struttura di tipo Menu, cicla ogni singolo oggetto di tipo Item allocato dinamicamente e puntato dalla variabile interna della struttura: struct _Item *items;.


destroyMenu(&:my_menu);
	

Di default questa funzione è richiamata nella funzione cleanUp del motore di gioco, dichiarata nel file util.c, ed impostata per la pulizia del menù standard main_menu.

destroyMenu(&main_menu);
		

Crediti

Alcuni elementi grafici presenti in questo documento, provengono dalla collezione libera OpenGameArt, in particolare dai seguenti autori, che si ringraziano per averla resa disponibile:



Autore	Descrizione
Jason-Em	Classic hero and baddies pack Items and elements