From SA-MP Wiki

Introduzione

Un concetto fondamentale dello scripting (e della programmazione in generale) è la variabile. Le variabili sono porzioni di memoria e fungono da contenitori di dati per lavorare con le istruzioni del programma. Le istruzioni, dette statement, non fanno altro che accedere e modificare le informazioni contenute nelle variabili a seconda delle esigenze, nel modo più veloce ed efficiente possibile. Un esempio di utilizzo di variabili è l'esigenza di visualizzare un messaggio contenente un'informazione sul gioco:

Ci sono degli utenti online

Senza una variabile non sarebbe possibile scrivere il numero degli utenti effettivamente online, come:

Ci sono x utenti online

Il valore della variabile "x" dipende dalle istruzioni usate. In quest'esempio, un'istruzione controlla quanti giocatori sono attualmente connessi al gioco e salva tale numero nella variabile. Le istruzioni sono moltissime e svolgono ognuna una funzione specifica. Nello script le istruzioni sono organizzate in funzioni. Ogni funzione esegue la sua routine di istruzioni in un momento determinato del gioco. Un esempio pratico è:

#include <a_samp>
 
main()
{
}
 
public OnPlayerConnect(playerid)
{
    SendClientMessage(playerid, 0x00FF0000, "Benvenuto nel server");
}

La funzione OnPlayerConnect() esegue la routine di istruzioni quando un giocatore si connette al server. L'unica istruzione usata in questo caso è SendClientMessage(), che visualizza al giocatore un messaggio di benvenuto. La funzione main() non ha un'utilità concreta nello script, ma è necessaria perché funge da entry point dello script.

Funzioni

Una funzione necessita di essere chiamata e definita. La funzione viene chiamata per iniziare l'esecuzione della sua routine di istruzioni, che altrimenti rimarrebbero inutilizzate nello script. La funzione, infine, viene definita per specificare le istruzioni da eseguire, che vengono raggruppate in un costrutto chiamato corpo della funzione. Lo script:

#include <a_samp>
 
main()
{
}
 
public OnPlayerConnect(playerid)
{
    MyFunction();
}
 
MyFunction()
{
    SendClientMessage(playerid, 0x00FF0000, "Benvenuto nel server");
}

fa esattamente la stessa cosa dell'esempio precedente, ma in questo caso compare la funzione MyFunction().

Definizione

L'istruzione

MyFunction();

chiama la funzione MyFunction(), che è definita nel codice

MyFunction()
{
    SendClientMessage(playerid, 0x00FF0000, "Benvenuto nel server");
}

OnPlayerConnect() è eseguita automaticamente dal server quindi non necessita di essere chiamata. Le funzioni di questo tipo sono chiamate callback e presentano la dicitura public prima del nome. Questa scritta rende la funzione visibile al server, perché non dipende da un'istruzione di richiamo interna allo script. L'istruzione

SendClientMessage(playerid, 0x00FF0000, "Benvenuto nel server");

chiama la funzione SendClientMessage(), la cui definizione non si trova nello script, ma in un file esterno (pawno/include/a_samp.inc). In questo file sono presenti tutte le funzioni predefinite di SA:MP, in questo modo potremo usarle senza doverle definire nello script. Il codice

#include <a_samp>

è una direttiva e fa in modo che lo script legga il contenuto di tale file.

Parametri

I parametri sono variabili usate per dare informazioni aggiuntive a una funzione. Compaiono fra le parentesi dopo il nome della funzione.

#include <a_samp>
 
main()
{
}
 
public OnPlayerConnect(playerid)
{
    MyFunction("Benvenuto nel server");
}
 
public OnPlayerDeath(playerid, killerid, reason)
{
    MyFunction("Sei morto");
}
 
MyFunction(string[])
{
    SendClientMessage(playerid, 0x00FF0000, string);
}

Ora MyFunction() presenta il parametro string. Se viene chiamato OnPlayerConnect(), viene chiamata MyFunction(), e il parametro string assume il valore "Benvenuto nel server". Il valore di tale parametro è così usato da SendClientMessage(), che visualizza così il solito messaggio di benvenuto. Se viene chiamata OnPlayerDeath(), invece, string diventa "Sei morto". Le parentesi quadre [] dopo string sono necessarie se il parametro è una stringa (o un qualunque array).

Return

È possibile interrompere l'esecuzione di una funzione e restituire il controllo alla funzione chiamante (subito dopo l'istruzione che chiama la funzione interrotta). Questo si fa tramite un'istruzione, che è in grado anche di restituire un valore alla funzione chiamante (magari elaborato nella funzione interrotta).

#include <a_samp>
 
main()
{
}
 
public OnPlayerConnect(playerid)
{
    MyFunction(string);
    SendClientMessage(playerid, 0x00FF0000, string);
}
 
MyFunction(string[])
{
    format(string, sizeof(string), "Benvenuto nel server");
    return string;
}

Quando OnPlayerConnect() chiama MyFunction(), la funzione

format(string, sizeof(string), "Benvenuto nel server");

formatta il parametro string (in questo modo sarà "Benvenuto nel server"), poi l'istruzione

return string;

interrompe MyFunction() e restituisce il controllo a OnPlayerConnect() (la funzione che ha chiamato MyFunction()). Si passa quindi a SendClientMessage(), che visualizzerà come scritta il valore di string, ossia "Benvenuto nel server", che conosce per mezzo di return. Anziché

MyFunction(string)
SendClientMessage(playerid, 0x00FF0000, string);

è possibile scrivere direttamente

SendClientMessage(playerid, 0x00FF0000, MyFunction(string));

Variabili

Le variabili contengono dati e sono rappresentate solitamente da nomi o lettere. Esistono vari tipi di variabili, ognuna delle quali può contenere un tipo diverso di dati:

• char: variabile che contiene un carattere, come "a" o "&"
• int: variabile che contiene un numero intero, come -1 o 200
• float: variabile che contiene un numero con la virgola, come 3.5 o 0.0009
• string: variabile che contiene una stringa (variabile testuale), come "hello world"

Le variabili sono fondamentali per lo sviluppo di qualunque tipo di codice. Ad esempio:
ci sono degli utenti online

Senza una variabile non sarebbe possibile scrivere il numero degli utenti effettivamente online, come:
ci sono x utenti online

In questo caso, la variabile da usare è di tipo int (un numero).
Nel caso in cui volessimo scrivere un messaggio di benvenuto:
un utente è entrato nel server

Senza una variabile non sarebbe possibile scrivere il nome dell'utente che è entrato, come:
x è entrato nel server

La variabile da usare in questo caso è una stringa. Una stringa non è altro che un insieme di variabili di tipo char messe insieme. In termini più tecnici, è un array di char.

Array

Un array è una variabile formata da più celle di memoria, accessibili in modo dinamico. Il numero di slot (celle) di un array deve essere espressamente definito durante la dichiarazione e non può cambiare successivamente. Questo perché la memoria da dedicare alle variabili è assegnata durante la compilazione dello script. Come le variabili, anche gli array presentano un tipo. Questo significa che un array di int può contenere solo dati di tipo int, o un array di char solo dati di tipo char (in questo caso si parla di stringa).

Dichiarazione

Il codice

new MyArray[5];

crea un array formato da 5 slot. Di default, il valore di uno slot è 0, quindi il contenuto dell'array sarebbe:

new MyArray[MAX_PLAYERS]

Questo crea un array di dimensione MAX_PLAYERS. Di default, questa costante vale 500 e rappresenta il numero massimo di giocatori che un server può ospitare. Ogni slot dell'array può essere così assegnato a un giocatore specifico (identificato da un ID) e i suoi dati non interferiranno con quelli di un altro.

Inizializzazione

Assegnare un valore a uno slot è del tutto analogo alle variabili normali:

new MyArray[5];
MyArray[2] = 5;

Questo assegnerà al secondo slot il valore 5. Avremo quindi:

tenendo presente che il primo slot è MyArray[0] e non MyArray[1]. L'ordine degli slot sarà pertanto:

Accedere a MyArray[5] causerà un errore perché stai tentando di accedere a uno slot che eccede la dimensione dell'array (l'ultimo slot è, infatti, MyArray[4]).
Un modo più veloce di inizializzare un array è:

new MyArray[5] = {0, 0, 5, 0, 0}

In questo modo avremo sempre:

Strutture di controllo

Main article: Control Structures

Le strutture di controllo sono costrutti particolari che cambiano il normale flusso di esecuzione delle istruzioni di una funzione.