Tutorial scripting (8 Noiembrie 2013)

[KronoS eXtream]

TUTORIAL SCRIPTING

Autor: KronoS # GG
Contribuitori: -
O parte din material este:

• preluat si tradus de pe http://wiki.amxmodx.org/
• adaptat dupa Daniela Saru

Daca acest tutorial apare in alte parti fara ca numele autorului si al contribuitorilor sa fie pastrate, nu voi mai adauga informatii noi.

Am facut acest tutorial cu scopul de a ii ajuta pe cei ce vor sa scripteze sau sa inteleaga bazele limbajului Pawn, mai ales ca sunt foarte putine tutoriale in limba romana.

1. Informatii de baza (Modificat pe 12 Octombrie 2013)

| Afiseaza codul

Pluginurile AmxModX sunt realizate folosind limbajul de programare Pawn (cunoscut ca si Small).Codul este scris intr-un editor de text (precum Notepad, Notepad++, AMXX Studio etc.) si salvat ca fisier cu extensia .sma (fisier sursa de plugin AmxModX).Acesta trebuie compilat pentru a se obtine un fisier cu extensia .amxx (pluginul in sine).

Programarea pluginurilor in limbajul Pawn este relativ usoara deoarece nu exista unele notiuni care se gasesc in limbajele de programare mai avansate.

2. Compilarea unui plugin (Modificat pe 26 Octombrie 2013)

| Afiseaza codul

Compilarea reprezinta procesul prin care codul sursa scris intr-un limbaj de programare (in cazul nostru Small sau Pawn) este tradus in cod obiect, ce poate fi apoi executat.



In cazul surselor de pluginuri amxmodx, compilarea se poate face online sau local (aceasta fiind metoda recomandata).Compilarea online se face accesand link-ul http://www.amxmodx.org/webcompiler.cgi .Aici puteti posta codul in casuta de text special amenajata, precum si numele care doriti sa-l atribuiti fisierului, sau, puteti selecta sursa direct din calculator.Dupa apasarea butonului Compile va incepe compilarea pluginului, urmata de link-ul de descarcare al pluginului (cu extensia .amxx) sau de erori si avertismente in cazul in care sunt gasite greseli la nivelul codului.Compilarea locala se poate face daca aveti instalat modul AmxModX in calculator.Va duceti in folderul
[code]addons/amxmodx/scripting[/code]
si puneti acolo fisierul sursa (exemplu: plugin.sma), apoi trageti iconita acestuia peste fisierul compile.exe tinand apasat Click stanga.Astfel, o sa apara o consola ce o sa returneze erorile si avertismentele sau va informeaza ca a decurs cu succes compilarea.Pluginul compilat il gasiti in folderul
[code]addons/amxmodx/scripting/compiled[/code]
(exemplu: plugin.amxx)

3. Notatii si vocabular in limbajul Pawn (Modificat pe 27 Octombrie 2013)

| Afiseaza codul

Vocabularul limbajului Pawn este format din simboluri de baza, clasificate in trei mari categorii:
[list][*]literele alfabetului englez
[*]cifre arabe: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
[*]simboluri speciale (operatori si delimitatori): . ; , : ? " ( ) [ ] { } < > ! | / _ # % & ^ + - * =[/list]

Tot in categoria simbolurilor speciale se incadreaza si cuvintele rezervate, numite si cuvinte-cheie, care au un inteles bine stabilit si nu pot fi folosite de catre scripteri decat in contextul permis de catre sintaxa limbajului Pawn.Din lista cuvintelor-cheie fac parte urmatoarele: case, const, else, enum, float, for, if, return, sizeof, static, switch, while, public, iar lista poate continua.

Scrierea unui plugin cu ajutorul limbajului Pawn este similara scrierii de fraze in limbaj natural.Se folosesc combinatii de cuvinte si separatori.Cuvintele pot fi:
[list][*]simboluri speciale
[*]identificatori obisnuiti sau predefiniti
[*]constante[/list]
Separatorii se incadreaza in una din urmatoarele categorii:
[list][*]spatiu
[*]comentariu
[*]sfarsit de linie[/list]

Identificatorii reprezinta modalitatea de denumire a constantelor, tipurilor de date, variabilelor si functiilor.Constantele reprezinta date ale caror valori nu se modifica pe parcursul rularii pluginului.Prin contrast, variabilele reprezinta date ale caror valori pot fi modificate.

4. Structura unui plugin (de refacut!) (Modificat pe 21 Octombrie 2013)

| Afiseaza codul

Un plugin AmxModX are, in principiu, urmatoarea structura:
[list][*]Directive preprocesor/de includere
[*]Definitii de variabile globale/constante
[*]Definitii de functii[/list]

Directivele preprocesor/de includere reprezinta primele linii dintr-un program.Prin aceste directive compilatorul este anuntat sa foloseasca anumite biblioteci care contin descrierea unor functii folosite in plugin.Sintaxa directivei de includere este:
[code]#include < numele_bibliotecii >[/code]

5. Includerea fisierelor/bibliotecilor (Modificat pe 12 Octombrie 2013)

| Afiseaza codul

Includerea fisierelor/bibliotecilor se realizeaza prin doua cai:
[code]#include < fisierul >[/code]
[code]#include "fisierul"[/code]
Folosind prima cale, fisierul este cautat in directorul standard (In cazul AMXX directorul standard este include).
Folosind a doua cale, fisierul este cautat in directorul curent, apoi in cel standard (In cazul AMXX directorul curent este scripting).Aceasta forma 
Atunci cand facem un plugin AMXX, va trebui sa includem mereu biblioteca amxmodx:
[code]#include < amxmodx >[/code]
Daca pluginul contine si comenzi pentru admini, atunci va trebui sa includem si biblioteca amxmisc:
[code]#include < amxmisc >[/code]

6. Comentarii (Modificat pe 12 Octombrie 2013)

| Afiseaza codul

Comentariile sunt foarte folositoare deoarece putem adauga explicatii in sursa.Acestea sunt eficiente mai ales in sursele mari, unde exista mari sanse sa va incurcati sau sa nu mai stiti ce anume face o linie de cod.Exista doua moduri prin care puteam sa declaram comentarii:




Daca doriti sa folositi prima forma, iar comentariul se intinde pe mai multe randuri, trebuie sa adaugati // in fata fiecarui rand de comentariu:
[code]// Comentariul asta
// se intinde pe mai multe
// randuri[/code]
A doua forma este recomandata deoarece la inceputul comentariului se pune /* iar la sfarsit se pune */
Avantajul este ca nu mai trebuie sa puneti simbolurile in fata fiecarui rand:
[code]/* Comentariul asta
se intinde pe mai multe
randuri */[/code]
ATENTIE: Comentariile din sursa nu sunt citite de catre compilator

7. Variabile/Tipuri de variabile (Modificat pe 3 Noiembrie 2013)

| Afiseaza codul

Variabilele sunt structuri simple folosite pentru a manipula informatii in plugin.Fiecarei variabile i se atribuie o locatie din memoria RAM (cu alte cuvinte, variabilele mananca memorie RAM), in care se stocheaza valoarea acesteia.Puteti sa va imaginati ca o variabila este o cutie in care puteti stoca un numar.

Numele unei variabile trebuie sa contina cel mult 19 caractere si trebuie sa inceapa cu o litera.Poate sa contina simbolurile A-Z, a-z, 0-9 si _ (underscore/underline).Este important de stiut faptul ca numele variabilelor sunt case sensitive (sensibile la majuscula): var, Var, VAR, VaR sunt patru variabile diferite.
Declararea variabilelor se face folosind sintaxa:
[code]new g_VariabilaNoua;[/code]
Daca ne gandim si la exemplul de mai sus cu cutia obtinem:


Variabilele pot fi declarate la nivel global (in afara oricarei functii) sau local (in interiorul unei functii).
Alocarea memoriei in cazul variabilelor globale este statica, adica memoria alocata acestora ramane ocupata atata timp cat pluginul ruleaza!Durata de viata a variabilelor globale este cea a intregului plugin.
Exemplu in care o variabila este declarata la nivel global:
[code]#include < amxmodx >

new g_VariabilaNoua;

public plugin_init( )
{
	// instructiuni
}[/code]Diagrama:


Alocarea memoriei pentru variabilele locale este automata, memoria alocata este ocupata doar in momentul executarii functiei in care se afla acestea (la sfarsitul executiei functiei, memoria alocata pentru variabilele locale este eliberata).
Durata de viata a variabilelor locale este cea a functiei in care acestea sunt declarate.
Exemplu in care o variabila este declarata la nivel local:
[code]#include < amxmodx >

public plugin_init( )
{
	new g_VariabilaNoua;
	// instructiuni
}[/code]Diagrama:


Limbajul Pawn are doar trei tipuri de date pentru declararea variabilelor.Tipul de variabila implicit este integer, adica numar intreg.

Tipuri de variabile

Integer

Cel mai simplu tip de variabila in limbajul Pawn este integer, numar intreg.Pentru a declara o noua variabila de tip numar intreg, se foloseste operatorul new:
[code]new a;                  // Declararea variabilei libere "a"
new b = 2;              // Declararea variabilei "b" care primeste valoarea 2
new c = 3.5;            // Invalid deoarece 3.5 nu este un numar intreg
new d = "extreamcs";    // Invalid deoarece "extreamcs" nu este un numar intreg

new z = 100_000;        // Numerele ca acesta sunt suportate pentru ca valorile mari sa fie citite mai usor[/code]
Puteti declara mai multe variabile pe un singur rand:
[code]new m, n, o, p;
new x = 4, y = 6;[/code]

Float

De asemenea, o variabila poate fi declarata ca fiind de tip float, ceea ce inseamna ca poate stoca numere cu zecimale (cu virgula).
[code]new Float:a;               // Declararea variabilei libere "a" de tip float
new Float:b = 3.5;         // Declararea variabilei "b" de tip float care primeste valoarea 3.5
new Float:c = 2;           // Este valid dar compilatorul o sa dea un avertisment
new Float:d = 2.0;         // Varianta corecta a liniei de mai sus
new Float:e = "extreamcs"; // Invalid deoarece "extreamcs" nu este un numar cu zecimale[/code]

Boolean

Ultimul tip de variabila este boolean, care face ca o variabila sa aiba una din urmatoarele doua valori: false (fals) sau true (adevarat).
[code]new bool:Tutorial;          // Declararea variabilei "Tutorial" care este implicit falsa
new bool:Kronos = true;     // Declararea variabilei "Kronos" care primeste valoarea true[/code]

8. Optimizarea consumului de memorie al variabilelor (Modificat pe 12 Octombrie 2013)

| Afiseaza codul

Aceste lucruri sunt valabile si pentru vectori si siruri!
Pentru ca un plugin sa consume cat mai putina memorie RAM, sunt recomandate:
[list][*]folosirea unui numar cat mai mic de variabile globale
[*]declararea cat mai exacta a numarului de pozitii (in cazul vectorilor si al sirurilor)(Exemplu: stocarea numelui unui jucator intr-o variabila poate ocupa maxim 32 de pozitii, de aceea variabila va fi declarata ca avand 32 de pozitii, si nu un alt numar mai mare decat valoarea recomandata)[/list][/color]

9. Vectori (Modificat pe 12 Octombrie 2013)

| Afiseaza codul

Un vector este un tip simplu de date agregate.Asta inseamna ca puteti stoca multiple valori intr-o singura variabila.Un vector are aceleasi reguli si tipuri ca si o variabila normala.Diferenta intre cele doua este ca primul contine valori multiple.Un vector se defineste cu paranteze drepte, intre care se afla numarul de valori pe care acesta poate sa-l contina.
[code]new Players[ 32 ];                 // Declararea vectorului "Players" ce are 32 de pozitii[/code]
Puteti stoca valori in oricare din cele 32 de pozitii ale vectorului.Pozitiile sunt numerotate de la 0 la n-1 (in cazul de mai sus 32-1, adica 31).Orice pozitie are implicit valoarea 0.
[code]Players[ 1 ] = 7;                  // Se atribuie pozitiei 1 a vectorului "Players" valoarea 7
Players[ 2 ] = Players[ 1 ];       // Se atribuie pozitiei 2 valoarea care se afla pe pozitia 1 a vectorului

// Linia de cod de mai jos este incorecta.Desi vectorul are 32 de pozitii declarate, ultima pozitie este 31, numerotarea incepand de la 0
Players[ 32 ] = 15;

// Linia de cod de mai jos este incorecte.Pozitiile sunt numerotate de la 0 in sus.
Players[ -1 ] = 13;

// Codul de mai jos este incorect deoarece a trebuie sa fie un numar constant.
new a = 5;
new Array[ a ]

// Codul de mai jos reprezinta varianta corecta a celui de mai sus
const a = 5;
new Array[ a ];

// Vectorii pot fi declarati cu date implicite
new Array[ 4 ] = { 0, 1, 2, 3 };

// Puteti folosi si constante simbolice
#define POZITII 4
new Array[ POZITII ];

// Puteti folosi si celelalte doua tipuri de date: float si boolean
new Float:numere[ 4 ] = { 0.0, 1.3, 2.5, 5.6 };
new bool:codat[ 2 ] = { true, false };[/code]

10. Siruri (Modificat pe 12 Octombrie 2013)

| Afiseaza codul

Cei care au experienta probabil au remarcat ca lipseste un tip de date important, caracterele.Acestea se numesc siruri si in limbajul Pawn sunt, tehnic vorbind, numere.Un sir este un vector de numere care sunt traduse in simboluri ASCII (caractere).
[code]// Declararea sirului "SirComunitate" ce contine cuvantul eXtreamCS
// Acest sir are 10 pozitii, 9 din ele fiind reprezentate de literele ce alcatuiesc
// cuvantul eXtreamCS iar ultima pozitie este rezervata numarului 0, care spune
// compilatorului ca acesta este un sir

new SirComunitate[ ] = "eXtreamCS";[/code]

11. Operatori si expresii (Modificat pe 8 Noiembrie 2013)

| Afiseaza codul

Limbajul Pawn permite folosirea unui numar mare de operatori.Un operator se reprezinta cu ajutorul unuia sau a doua caractere speciale alaturate, numite operanzi (exemple: = sau != etc.).

Tipuri de operatori:
[list][*]unari - folosesc un singur operand
[*]binari - folosesc doi operanzi[/list]

O expresie este o combinatie de operanzi si operatori scrisa astfel incat, respectand regulile limbajului de programare, sa conduca la calcularea unei valori unice.La fel ca si in matematica, ordinea efectuarii operatiilor in cadrul unei expresii este stabilita de prioritatea operatorilor, care poate fi modificata prin utilizarea parantezelor rotunde pe oricat de multe niveluri este necesar.Spre deosebire de matematica, nu este permisa folosirea in expresii a parantezelor drepte sau a acoladelor pentru modificarea ordinii de efectuare a operatiilor.

Atunci cand intr-o expresie apar operatori cu aceeasi prioritate, ordinea de efectuare a operatiilor este impusa de ordinea de asociere a operatorilor.In general, aceasta este de la stanga la dreapta dar exista si doua exceptii, operatorii unari si operatorii de atribuire, in cazul carora ordinea de asociere este de la dreapta la stanga.

12. Constante simbolice (Modificat pe 12 Octombrie 2013)

| Afiseaza codul

Definirea constantelor simbolice se face astfel:
[code]#define Numele_Constantei Valoarea_Constantei[/code]
Acest lucru face ca in toata sursa, constanta definita mai sus sa fie inlocuita cu valoarea atribuita (exceptie comentariile).
Scopul acestora este de a usura editarea surselor.
Exemplu:
[code]#define Nume_Comunitate eXtreamCS[/code]

13. Functii/Declararea unei functii (Modificat pe 12 Octombrie 2013)

| Afiseaza codul

O functie reprezinta un set de instructiuni apelabil din alte parti ale pluginului (apelarea unei functii inseamna executarea acesteia).Functiile ajuta la structurarea pluginului in unitati logice.O functie este alcatuita din antet (ce cuprinde tipul functiei, numele acesteia precum si parametrii (daca exista)) si corp (ce cuprinde instructiunile functiei).Antetul arata astfel:
[code]tipul_functie numele_functiei( parametrii )[/code]
In cazul pluginurilor AMXX, functiile sunt adesea de tipul public
Parametrii se separa cu virgule.
Exemplu de functie fara parametrii:
[code]public Exemplu_Functie( )[/code]
Exemplu de functie cu parametrii:
[code]public Exemplu_Functie( parametrul1, parametrul2 )[/code]

14. Functia plugin_init( ) (Modificat pe 12 Octombrie 2013)

| Afiseaza codul

Functia plugin_init( ) reprezinta functia principala a pluginului, in care se inregistreaza pluginul, comenzile, eventurile folosite etc.Ea este apelata imediat dupa schimbarea hartii.
Functia este de tip public, fara parametrii si se declara astfel:
[code]public plugin_init( )[/code]

15. Inregistrarea pluginului (Modificat pe 12 Octombrie 2013)

| Afiseaza codul

Inregistrarea pluginului se face cu scopul de a identifica usor pluginul atunci cand tastam amxx plugins in consola serverului.De asemenea, aceasta ofera si informatii precum numele pluginului, versiunea, precum si autorul acestuia.
Inregistrarea pluginurilor se face prin intermediul native-ului register_plugin( ... )
[code]register_plugin( "Numele pluginului", "Versiunea", "Autorul" );[/code]
Exemplu:
[code]register_plugin( "Plugin de test", "1.0", "KronoS # GG" );[/code]
Pluginurile pot fi inregistrate in oricare din urmatoarele functii:
[code]plugin_init( )

plugin_precache( )[/code]
Exemplu:
[code]public plugin_init( )
{
	register_plugin( "Plugin de test", "1.0", "KronoS # GG" );
}[/code]
sau
[code]public plugin_precache( )
{
	register_plugin( "Plugin de test", "1.0", "KronoS # GG" );
}[/code]
Puteti folosi si constante simbolice:
[code]#define PLUGIN "Plugin de test"
#define VERSIUNE "1.0"
#define AUTOR "KronoS # GG"

public plugin_init( )
{
	register_plugin( PLUGIN, VERSIUNE, AUTOR );
}[/code]

Pagina in lucru...

[KronoS eXtream]

Post rezervat!

[ReaD1nG]

Frumos GG :X

[Ulquiorra]

genial :) cred ca o sa mai postez si eu unu zilele astea.. ( e mare lenea.. )

[KronoS eXtream]

genial :) cred ca o sa mai postez si eu unu zilele astea.. ( e mare lenea.. )

Daca doresti sa contribui la acest tutorial (vei primi credite pentru tot ce faci) te astept pe PM :)

[KronoS eXtream]

Am adaugat informatii despre vectori si inregistrarea pluginurilor.

[munir]

Faci o treaba superba Kronos, tine-o tot asa.

[ReaD1nG]

Mai bine faci si un tutorial cum se pune un tag :) ca vreau sa vad mereu cand fac acest lucru nu imi merge :)

[KronoS eXtream]

Mai bine faci si un tutorial cum se pune un tag :) ca vreau sa vad mereu cand fac acest lucru nu imi merge :)

Tag-ul se defineste ca fiind o constanta simbolica :) Sau doar ca o simpla constanta

Code: Select all

#define Tag "[Tag]"

sau

Code: Select all

new const g_Tag[ ] = "[Tag]";

Code: Select all

client_print( 0, print_chat, "%s Mesaj", Tag );
client_print( 0, print_chat, "%s Mesaj", g_Tag );

[CryWolf]

pff... foarte bine man :) ce nu erau astfel de tutoriale cand am inceput si eu sa mai invat cate ceva, acum aproape ca le dai mura-n gura sa fii prea inchis la minte sa nu realizezi cat de mult te ajuta un astfel de tutorial

[aurelian121]

imposibil sa nu fi fost astfel de tutoriale, daca ai folosit amxx studio are help-ul care te duce la http://www.amxmodx.org/doc/ si ai acolo tutoriale

[KronoS eXtream]

imposibil sa nu fi fost astfel de tutoriale, daca ai folosit amxx studio are help-ul care te duce la http://www.amxmodx.org/doc/ si ai acolo tutoriale

... mai ales ca sunt foarte putine tutoriale in limba romana