[Tutorial] Pawn.CMD — Guia definitivo

[White_Blue]

1. Introdução ao plugin e ao tutorial
Tenho notado em uma pesquisa rápida aqui no fórum que não há um tutorial definitivo sobre Pawn.CMD. Se você está procurando por um tutorial que mostre tudo, desde como começar, como fazer comandos básicos e mostre todas as callbacks e recursos importantes do Pawn.CMD, veio ao local certo.

Falando um pouco sobre o plugin, não quero me aprofundar muito nisso pois não é tão importante para o tutorial, mas o Pawn.CMD é o plugin de processamento de comandos mais simples e rápido do SA-MP. Que é mantido e desenvolvido por um conhecido contribuidor da comunidade de SA-MP conhecido pelo nome katursis.


Gráfico de comparação com outros plugins

2. Instalação e primeiro comando
Vamos começar instalando o plugin, para isso vá até a página do Github oficial do autor(Clique aqui para ir para a página) e baixe a versão mais recente(No momento que escrevo esse tutorial, a versão mais recente é a 3.4.0, lembre-se de baixar a versão 3.4.0, não a versão 3.4.0 omp, pois vejo muita gente confundindo a versão para o omp(Open Multiplayer) com a versão para o SA-MP e acaba por gerar erros) após isso abra o arquivo .rar(Ou .tar se você usa linux como SO) e arraste o plugin .dll(Ou .so caso você use linux) para a pasta de plugins do seu servidor e arraste a include .inc para a pasta de includes do seu editor de código.

Após a instalação, vamos podemos criar o nosso primeiro comando usando Pawn.CMD:

A sintaxe é simples: CMD:comando(playerid, &params[]) // O E comercial(&) representa que o parâmetro é opcional, ou seja, apenas adicione o parâmetro params quando for usá-lo.

Exemplo:

Código PHP:

#include <a_samp> // Incluímos a include principal do SA-MP
#include <Pawn.CMD> // Agora incluímos a include do Pawn.CMD

CMD:helloworld(playerid) /* Podemos começar com o clássico hello world! */ {
    SendClientMessage(playerid, 0xFFFFFFAA, "Hello world!"); // Manda uma mensagem para o jogador(playerid) com a cor branca e com o conteúdo "Hello World".
    return 1; // E pronto, simples assim você fez o seu primeiro comando!
} 


3. Callbacks
Pode não parecer, mas o Pawn.CMD tem várias funções, vou me aprofundar nas mais importantes aqui(Caso você queira saber mais, leia o readme.md do repositório oficial do Pawn.CMD).

Vamos começar com as callbacks:

Código PHP:

// Essas são as callbacks que o Pawn.CMD tem:
forward PC_OnInit();
forward OnPlayerCommandReceived(playerid, cmd[], params[], flags);
forward OnPlayerCommandPerformed(playerid, cmd[], params[], result, flags); 


1ª - OnPlayerCommandPerformed:
Essa registra o evento de quando o comando é executado pelo servidor.

Essa que talvez seja a que você mais irá usar na sua gamemode, por ela passam todos os comandos que são digitados pelos jogadores, sendo possível realizar verificações, como se o comando que foi digitado é existente ou não.

Exemplo:

Código PHP:

public OnPlayerCommandPerformed(playerid, cmd[], params[], result, flags) {
       if(result == -1) /* Se o result for negativo, significa que o comando não existe */ {
         SendClientMessage(playerid, 0xFF0000AA, "Comando inexistente."); // Retorna uma mensagem de erro para o jogador, já que o comando não existe.
       }
       return 1;
} 


Parâmetros:
playerid - Representa o ID do jogador que executou o comando;
cmd[] - Representa o comando executado(Podendo retornar o nome do comando em forma de string ou fazer verificações mais específicas);
params[] - Representa os parâmetros passados pelo jogador no comando;
result - Representa o resultado do comando como o nome sugere(Retorna -1 caso o comando for inválido e retorna 0 caso o comando for válido);
flags - Representa os sinalizadores do comando, nunca vi ninguém usar esse parâmetro, mas é bem útil, pois pode ser usado para passar parâmetros adicionais(Como /ban -all por exemplo, isso faria com que o comando pudesse banir à todos online como um parâmetro opcional).


2ª OnPlayerCommandReceived
Como o nome sugere, essa callback registra evento de quando o comando é recebido pelo servidor.

Pode ser usada para fazer verificações de flood e registrar comandos por exemplo.

Exemplo:

Código PHP:

public OnPlayerCommandReceived(playerid, cmd[], params[], flags) {
       static command[256]; // Declara a string 'command'

       for(new i = 0; i < MAX_PLAYERS; i++) /* Faz um loop para percorrer todos os jogadores */ {
        if(!IsPlayerConnected(i) || !IsPlayerAdmin(i)) continue; // Caso o jogador não estiver conectado ou não estiver logado na RCON, o loop pula esses jogadores e continua a percorrer
        format(command, sizeof(command), "Comando recebido: %s - Comando performado por: %s[%d]", cmd, GetPlayerNameEx(playerid), playerid); // Formata a string 'command' com o comando recebido e o nome e ID do jogador
        SendClientMessage(i, 0xFFFFFFAA, command); // Envia a mensagem contendo a string 'command' com o comando recebido para todos os logados na RCON
       }
       return 1;
}

GetPlayerNameEx(playerid) /* Função para retornar o nome do jogador de forma mais prática */ {
    static Name[MAX_PLAYER_NAME]
    GetPlayerName(playerid, Name, MAX_PLAYER_NAME);
    return Name;
} 


Parâmetros:
playerid - Representa o ID do jogador à executar o comando;
cmd[] - Representa o comando à ser executado em forma de string;
flags - Representa os parâmetros opcionais do comando recebido(Caso houver).

3ª PC_OnInit
Como o nome sugere, essa callback é executada assim que o plugin Pawn.CMD é carregado.

Exemplo:

Código PHP:

public PC_OnInit() {
      printf("Pawn.CMD carregado!");      
      return 1;
} 


Parâmetros:
- Essa callback não possui nenhum parâmetro.

4. Funções
Nota: Como foi dito, eu não irei me aprofundar tanto nas funções(Até por que tem bastante delas), caso queira saber mais, você pode acessar o readme.md do Pawn.CMD que contém todas as funções clicando aqui.

1: callcmd
Essa função executa um comando em outro lugar do código(Eu acho ela bem útil e poupa bastante tempo).

Exemplo:

Código PHP:

// Em algum lugar do código...
CMD:meunome(playerid) {
    new Nome[128]; // Declarando a variável nome
    format(Nome, sizeof(Nome), "Meu nome é: %s", GetPlayerNameEx(playerid)); // Formata a variável nome contendo o nome do jogador.
    SendClientMessage(playerid, 0xFFFFFFAA, Nome); // Retorna a string 'Nome' para o playerid com a cor branca.
    return 1;
}

GetPlayerNameEx(playerid) /* Função para retornar o nome do jogador de forma prática */ {
   static Name[MAX_PLAYER_NAME];
   GetPlayerName(playerid, Name, MAX_PLAYER_NAME);
   return Name;
}

public OnPlayerConnect(playerid) /* Quando o jogador se conectar: */ {
      callcmd::meunome(playerid); // Executa o comando meunome na callback OnPlayerConnect.
      return 1;
} 


Sintaxe:

Código PHP:

callcmd::comando(playerid, &params[]) 


2: PC_EmulateCommand
Emula um comando que não necessariamente foi digitado por aquele jogador.

Exemplo:

Código PHP:

CMD:kickarme(playerid) {
    Kick(playerid);
    return 1;
}

CMD:emularcomando(playerid) {
    PC_EmulateCommand(playerid, "/kickarme"); // Emula o comando para o jogador 'playerid'.
    return 1;
} 


Sintaxe:

Código PHP:

PC_EmulateCommand(playerid, command[]) 


5. Observações finais e fontes
Espero que esse tutorial tenha te ensinado de vez a como dominar o Pawn.CMD que é um plugin bem poderoso. Lembrando que eu não citei todas as funções que o Pawn.CMD tem, citei apenas as mais importantes para esse tutorial não ficar mais extenso do que já está.

Caso tenha qualquer sugestão para a melhoria desse tópico, sinta-se livre para sugerir.

Fontes e referências:
https://github.com/katursis/Pawn.CMD - Referência das funções do plugin
https://portalsamp.com/showthread.php?tid=108 - Inspiração para esse tutorial