Salvar armas do player - Comentado

/*
* Créditos:
* Post Oficial em SSGamers - https://scriptsamp.forumeiros.com/t15975-sistema-de-salvar-armas-do-player-automatico
* Código criado por zGabriel ( https://scriptsamp.forumeiros.com/u10020 )
* Código comentado por cailir ( https://scriptsamp.forumeiros.com/u8995 ) - Para SSGamers ( https://scriptsamp.forumeiros.com )
* Não redistribua este trabalho sem incluir estes créditos!
* Várias informações sobre os comentários encontram-se no final do arquivo, junto com links de referência.
*
* Os valores entre colchetes ("[" e "]") são utilizados na referência, encontrada no final do arquivo.
*/

/*
* Não é necessário manter as notas e nem esta mensagem de licença. Apenas mantenha o primeiro bloco de comentários.
* Licença no final do arquivo, nas notas deixadas por cailir ( https://scriptsamp.forumeiros.com/u8995 ).
*/


public OnPlayerSpawn(playerid) //A funcão OnPlayerSpawn é chamada sempre que o player nasce, ou seja, após morrer e o jogador aparecer novamente ou após conectar no servidor [1]
{
    new query[50], tquery[50]; //Criamos 2 variáveis para armazenar os valores
    for (new i = 0; i <= 12; i++) //Utilizamos o for para pegar todas as armas dos jogadores, iniciando em 0 e indo até 12 (são 13 slots de armas no total) [2]
    {
        format(query, sizeof(query), "Arma%d", i), format(tquery, sizeof(tquery), "Municao%d", i); //Formatamos as variável query e tquery criadas acima como Arma%d e Municao%d, respectivamente ("%" indica que iremos utilizar uma variável neste local e "d" indica que iremos substituir por um inteiro) [3]
        GivePlayerWeapon(playerid, DOF2_GetInt(GetPlayerAccount(playerid), query), DOF2_GetInt(GetPlayerAccount(playerid), tquery));//Entregamos a arma ao jogador de id "playerid" (o jogador que está spawnando), pegando os inteiros (ID da arma e valores de munição) com DOF2_GetInt [3] da pasta dos jogadores, que é obtida através da função GetPlayerAccount [4].
    }
    return 1; //Toda função padrão deve retornar 1 (true)
}

public OnPlayerDisconnect(playerid, reason) //A função OnPlayerDisconnect irá ser chamada sempre que um jogador sair do servidor, sendo reason o motivo que o jogador desconectou [3]
{
    new weapons[13][2], query[50]; //Criamos 2 variáveis para armazenar os valores
    for (new i = 0; i <= 12; i++) //Utilizamos o for para pegar todas as armas dos jogadores, iniciando em 0 e indo até 12 (são 13 slots de armas no total)
{
        GetPlayerWeaponData(playerid, i, weapons[i][0], weapons[i][1]); //A função GetPlayerWeaponData é utilizada para pegar a munição e o ID da arma no slot [5]

        format(query, sizeof(query), "Arma%d", i); //Formatamos as variável query criada acima como Arma%d ("%" indica que iremos utilizar uma variável neste local e "d" indica que iremos substituir por um inteiro) [3]
        DOF2_SetInt(GetPlayerAccount(playerid), query, weapons[i][0]); // Utilizamos a função DOF2_SetInt para definir um valor em nosso arquivo, passando os parametros (Caminho do Arquivo), (Nome da variável), (Valor da variável). [6] [7]

        format(query, sizeof(query), "Municao%d", i); //Formatamos as variável query criada acima como Municao%d ("%" indica que iremos utilizar uma variável neste local e "d" indica que iremos substituir por um inteiro) [3]
        DOF2_SetInt(GetPlayerAccount(playerid), query, weapons[i][1]); // Utilizamos a função DOF2_SetInt para definir um valor em nosso arquivo, passando os parametros (Caminho do Arquivo), (Nome da variável), (Valor da variável). [6] [7]
        DOF2_SaveFile(); //Utilizamos a função DOF2_SaveFile para escrever o arquivo. [8]
    }
    return 1;
}

stock GetPlayerAccount(playerid) //Uma stock é uma outra forma de definir funções [4]
{
    new file[128]; //Criamos a variável file para armazenar o nome do arquivo
    format(file, sizeof(file), Pasta_Contas, PlayerName(playerid)); //Mudar a "Pasta_Contas" para pasta de contas do seu servidor! //Formatamos a variável file criada acima como Pasta_Contas [3] [7] [9]
    return file; //Retornamos o caminho do arquivo [8]
}

//Código abaixo adicionado por cailir ( https://scriptsamp.forumeiros.com/u8995 ) como correção do código base - Verifique se sua gamemode não possui esta função definida, já que é bem comum seu uso.
forward PlayerName(playerid); //Uma forward é uma outra forma de definir funções [4.1]
public PlayerName(playerid) { //Uma forward é uma outra forma de definir funções [4.1] [9]
    new pname[MAX_PLAYER_NAME+1]; //Criamos a variável "pname" para armazenar o nome do jogador
    GetPlayerName(playerid, pname, sizeof(pname)); //A função GetPlayerName é utilizada para pegar o nome do jogador [10]
    return pname; //Retornamos o valor da variável "pname"
}

/*
* Anotações:
* [1] - A função OnPlayerSpawn é padrão do sa-mp - Link Útil: https://team.sa-mp.com/wiki/OnPlayerSpawn_PT.html

* [2] - A função for é utilizado para loops, ao utilizar em seus parenteses, por exemplo:
** (new i = 0; i <= 12; i++)
**      |        |       |-> Aumentamos a variável "i" em 1 a cada vez que rodar;
**      |        |---------> Se a variável "i" for menor ou igual a 12 (O "12" pode ser qualquer número ou variavel que represente número);
**      |------------------> Iniciamos a variável "i" com valor inicial 0;

* [3] - A função format é utilizada para inserar valores não-estaticos em variáveis, no formato de text (string), por exemplo:
** (textoPrincipal, sizeof(textoPrincipal), "String %s estatica", valor)
**       |                   |                      |               |---> A variável que queremos definir no campo %s, pode-se utilizar mais de uma separando os valores por virgulas. [3.1];
**       |                   |                      |-------------------> O texto base que será utilizado na substituição - Link Útil: https://team.sa-mp.com/wiki/Format_PT.html#Especificadores_de_formato [3.2];
**       |                   |------------------------------------------> A função sizeof é utilizada para pegar o tamanho da variável que foi indicada - Link Útil: https://team.sa-mp.com/wiki/Keywords_Operators.html#sizeof (Disponível somente em inglês);
**       |--------------------------------------------------------------> Este parametro é utilizado para indicar a variável que deve ter seu valor alterado pelo format - Link Útil: https://team.sa-mp.com/wiki/Format_PT.html ;
**
** [3.1] - O uso de vários valores é indicado com vários %, conforme nos exemplos abaixo:
*** [Ex] (textoPrincipal, sizeof(textoPrincipal), "String %s %s", valor, valorDois)
*** No exemplo acima, os paramêtros no formato acima irão incluir um espaço entre os valores das váriaveis;
*** [Ex] (textoPrincipal, sizeof(textoPrincipal), "String %s%s", valor, valorDois)
*** No exemplo acima, os paramêtros no formato acima não irão incluir espaço entre os valores das váriaveis, colocando-as lado a lado;
**
** [3.2] - Se um especificador de formato for utilizado de forma incorreta, não irá apresentar erros, e o valor será transformado para o tipo correto, por exemplo:
*** [Ex] (textoPrincipal, sizeof(textoPrincipal), "String %s", variavelQueContemUmNumero)
*** No exemplo acima, o valor da variável "variavelQueContemUmNumero" será transformado para string (%s), porém terá seu valor mostrado de forma incorreta;

* [4] - Uma stock é uma forma de definir funções, porém existem diferenças:
** [4.1] - A stock não retorna avisos de função não utilizada, e pode ser compilada contendo erros em sua sintaxe. Link Útil: ** AVISO: WIKI NÃO OFICIAL ** https://sampwiki.blast.hk/wiki/Function#Stock (Disponível somente em inglês);
** [4.2] - Uma function deve ser declarada antes, ou seja, é necessário utilizar a função "forward" ou "native" (no caso de funções definidas por plugins ou as padrões) antes de se tornarem válidas, e compilem sem erros. Link Útil: https://team.sa-mp.com/wiki/Public_functions.html#Forwarding (Disponível somente em inglês);

* [5] - A função GetPlayerWeaponData é utilizada para pegar as informações da arma do jogador (munição e ID da arma) [5.1] - Link Útil https://open.mp/docs/scripting/functions/GetPlayerWeaponData (Disponível somente em inglês);
** [5.1] - Armas antigas, ou seja, sem munição também são retornadas, caso o jogador não tenha pego outra arma no mesmo slot;

* [6] - A função DOF2_SetInt é uma função definida pela include DOF2, criada pela própria equipe do SA-MP[!!];
** O DOF2 é uma substituição para o dini, o método antigo de salvamento de arquivos no sa-mp. O DOF2 foi implementado por ser mais eficiente e rápido em sua função;
** As informações definidas pelo DOF2 ficam salvas na memória até serem aplicadas pelas funções DOF2_WriteFile ou DOF2_SaveFile (ambas desempenham a mesma ação, DOF2_SaveFile é um macro para DOF2_WriteFile).

* [7] - O valor de Pasta_Contas deve ser definido em uma #define, como no exemplo abaixo:
** #define Pasta_Contas "salvamento/contas"
** [7.1] - #define não deve incluir um ";" no final, necessitando ser definido um por linha;
*** [7.1.1] - A função define não possui documentação oficial: (Mini-Documentação abaixo)
**** [7.1.1.1] Esta mini-documentação foi criada com proposito de auxilidar desenvolvedores iniciantes e foi criada por cailir ( https://scriptsamp.forumeiros.com/u8995 ) para SSGamers ( https://scriptsamp.forumeiros.com )
****  O #define pode ser chamado de macro, por apenas substituir um conteúdo por outro, e, permitir a redução de seu código, caso seja utilizado muitas vezes. O #define apenas substitui o primeiro paramêtro pelos restantes, podendo incluir espaços e inclusive multiplas linhas, se utilizado "\" ao final de uma linha;
**** [7.1.1.3] Exemplos de usos:
***** [Ex] #define CALLBACK::%0(%1) forward %0(%1);public %0(%1)
****** O exemplo acima está definindo "CALLBACK::" como um macro para definir uma função pública;
***** [Ex] #define DOF2_SetInt_NEW(%0) DOF2_SetInt(%0);DOF2_SaveFile()
****** O exemplo acima está definindo a função "DOF2_SetInt_NEW" para ter seus parametros utilizados em "DOF2_SetInt" e, em seguida, salvar o arquivo que foi editado;
***** [Ex] #define SetInt(%0) DOF2_SetInt(%0)
****** O exemplo acima está definindo "SetInt" como a mesma função de "DOF2_SetInt", permitindo que os mesmo parametros sejam utilizados;

* [8] - A função DOF2_WriteFile é utilizada para salvar o arquivo editado. Ao definir valores utilizando o DOF2, como no DOF2_SetInt, esses valores ficam salvos na memória do servidor até ser utilizado uma função de salvamento;
** [8.1] - A função DOF2_SaveFile realiza a mesma função de DOF2_WriteFile, sendo utilizado um macro para defini-la;

* [9] - A função PlayerName é uma função popularmente utilizada para pegar o nome do jogador, em vez de substituir uma variável, como na GetPlayerName [10]. Está função deve ser definida em sua gamemode e por ser muito popular, pode ser que existam variações de seu código e nome.

* [10] - A função GetPlayerName é utilizada para pegar o nome do jogador e salva-la em uma variável. Retorna o tamanho do nome do jogador, e, caso não exista, retornará 0. O valor substituído é o do primeiro paramêtro. Link Útil: https://team.sa-mp.com/wiki/GetPlayerName_PT.html ;

* [!!] - Informações marcadas com 2 exclamações não foram confirmadas por motivos diversos, podendo estar incorretas.

* *********************************************************************************************************************************** *
* Nota do cailir ( https://scriptsamp.forumeiros.com/u8995 ) para todos os usuários da SSGamers ( https://scriptsamp.forumeiros.com ) *
* *********************************************************************************************************************************** *
* Agradeço ao zGabriel ( https://scriptsamp.forumeiros.com/u10020 ) pelo código criado e postado no fórum. Deixo o uso e modificação  *
* deste código livre, apenas peço que mantenha os créditos, pois não foi fácil comentar e acredito que não tenha sido fácil criar o   *
* mesmo, então apenas gostaria de pedir isso. Agradeço ao Weslley Script, fundador da SSGamers pelo ótimo fórum.                      *
* *********************************************************************************************************************************** *

*/