PT-BR/Introdução ao Scripting

	Atenção: Este artigo aguarda atualização, pois está incompleto.

O que será abordado neste artigo são os conceitos básicos de scripting, ou seja, não iremos fazer nada além do que escrever um arquivo em uma linguagem que o computador entenda. Para deixar mais claro, a linguagem de programação utilizada pelo MTA é a Lua. Antes de começar a entender como esta linguagem funciona, é preciso esclarecer o que é um recurso (resource, em inglês).

Um recurso é um componente essencial de um servidor de MTA. Este pode ser caracterizado por uma pasta ou um arquivo comprimido, no qual há um conjunto de arquivos. Dentre eles, está presente o meta.xml, que por sua vez, informa ao servidor como/quais arquivos devem ser carregados e o que estes representam dentro do jogo. Em outras palavras, podemos comparar o recurso como se fosse um "programa de computador", o qual é iniciado ou interrompido sob demanda, além disso, o servidor tem a funcionalidade de rodar não só um recurso, mas vários ao mesmo tempo.

Obs: Os recursos são comprimidos em .zip e não em .rar

Tudo relacionado a scripting tem relação com os recursos, afinal, os recursos são nada mais que, geralmente, um conjunto de scripts destinados a realizar alguma tarefa. Um recurso pode ser classificado, via o meta.xml, como um gamemode, um mapa ou qualquer outra coisa. O MTA já vem por padrão com alguns recursos interessantes que você pode, além de reaproveitá-los, adaptá-los às suas necessidades. Por exemplo, você pode editar as texturas do gamemode race para deixar-lo com a cara do seu servidor ou mudar o comportamento do modo de jogo perante a mudança de mapa.

[[{{{image}}}|link=|]]

Dica: Para facilitar seus primeiros passos na programação em linguagem Lua, é recomendado utilizar um editor de textos com highlight, ou seja, o programa vai destacar cada tipo de instrução com uma cor distinta. Isso facilita a leitura e escrita de qualquer código independente da linguagem. Muito utilizado e recomendado por nós é o Notepad++ ou LuaEdit. Há também um editor de códigos (criado por fãs do MTA) com foco na linguagem Lua para o MTA: MTA Script Editor (ainda em fase de desenvolvimento, mas você já pode testá-lo).

Criando nosso primeiro script

Neste capítulo, vamos aprender a criar um script para permitir o jogador explorar o mundo do San Andreas.

Onde estão todos os scripts?

Vamos dar uma olhada na estrutura dos scripts. Vá até a pasta de instalação do seu MTA, que por padrão é C:\Arquivo de Programas\MTA San Andreas 1.x\.

1. Navegue até a pasta /server/mods/deathmatch/resources/
   • Dentro desta há várias outras pastas no formato [nome_da_pasta]. O motivo disto está na necessidade de organizar os recursos em certas categorias.
   • Como criaremos um modo de jogo totalemente novo, abriremos a pasta [gamemodes]
   • Para que o MTA possa reconhecer nossa pasta como um recurso, criemos outra dentro de [gamemodes] com um nome de sua preferência e sem os colchetes. Nós iremos usar "myserver" neste artigo.
2. No final, o seu resultado deve ser o seguinte:

/server/mods/deathmatch/resources/[gamemodes]/myserver

Identificando seu recurso

Para que o servidor reconheça os arquivos de um determinado recurso (para carregá-los), um arquivo meta.xml deve ser criado, contendo uma lista de todo o conteúdo do recurso. O arquivo meta.xml deve ser salvo na pasta principal (nesse caso, na pasta "myserver"). Então, abra um editor de textos (recomenda-se o Notepad++) e salve-o com o nome de "meta.xml".

Entre com as seguintes linhas no arquivo meta.xml:

<meta>
     <info author="Seu_Apelido" type="gamemode" name="Meu_jogo" description="Meu primeiro recurso" />
     <script src="script.lua" />
</meta>

Na tag <info />, existem:

• "type", que indica que o recurso criado é um gamemode. Pode também ser um map (mapa), que iremos explicar depois
• "name" - o próprio nome já diz: o nome do recurso
• "description" - uma breve descrição a fim de outros jogadores e/ou donos de servidores possam saber do que se trata seu recurso

A tag <script /> indica o caminho dos arquivos (escritos em Lua) presentes no seu recurso. Criaremos no próximo passo o exemplo (script.lua).

[[{{{image}}}|link=|]]	Dica: Um gamemode é o que você precisa para criar um servidor independente, pois é um recurso que envolve toda a programação principal do jogo online.

Criando um script simples

Observe que na tag <script /> anterior, o arquivo .lua está presente na pasta principal do recurso, e não em uma subpasta. Então precisamos salvar o script na pasta principal, assim como indicado na tag.

• Salve o seguinte código no arquivo script.lua:

local spawnX, spawnY, spawnZ = 1959.55, -1714.46, 10
function joinHandler()
	spawnPlayer(source, spawnX, spawnY, spawnZ)
	fadeCamera(source, true)
	setCameraTarget(source, source)
	outputChatBox("Bem-vindo ao meu servidor!", source)
end
addEventHandler("onPlayerJoin", getRootElement(), joinHandler)

Este script criado faz parte da esfera do servidor. Ou seja, ele é executado somente no servidor. Caso ele seja definido no cliente, cada um dos jogadores receberá o arquivo contendo o código. Mas neste exemplo, por enquanto, não necessitamos usar funções específicas do cliente. Vamos ao que interessa:

O script irá gerar o seu personagem (seu boneco) nas coordenadas (x, y, z) especificadas assim que você entrar no jogo. Note que a função fadeCamera() precisa ser usada ou, do contrário, a tela ficará preta (e você não verá nada). Outra função é a setCameraTarget(), que foca a câmera do jogo no seu personagem (do contrário, a câmera estaria virada para o céu).

A variável source representa o elemento responsável pela chamada do evento (haverá um tópico adiante sobre isso). Assim, quando um jogador entra no jogo, o evento "onPlayerJoin" é chamado e, em seguida, chama a função. O evento automaticamente define o jogador na variável source.

Se olharmos bem para o addEventHandler, veremos 3 argumentos:

• 'onPlayerJoin' - define o evento que chamará a função. No caso, esse evento é chamado assim que o jogador entra no jogo, logo, a função é executada assim que o jogador entra no jogo
• 'getRootElement()' - indica quem poderá chamar o evento. Neste caso, usamos o RootElement: um elemento pertencente ao topo da árvore que abrange todos os outros elementos do servidor. A função getRootElement() retorna justamente esse elemento do topo da árvore. Em outras palavras, todo jogador está envolvido.
• 'joinHandler' - indica o nome da função que será executada quando o evento for chamado. Vamos agora rodar nosso servidor e testar o script.

[[{{{image}}}|link=|]]	Dica: A variável source armazena sempre o elemento que chamou determinado evento. Ou seja, nem sempre source será o jogador. Cuidado com isso.

Executando o script

Para iniciar o servidor, execute o arquivo "MTA Server.exe" situado na pasta ../server/. Primeiramente, é mostrada uma lista com os principais status do seu servidor; observe o número da porta, da qual você irá precisar quando entrar no jogo. Logo após, o servidor carrega todos os recursos presentes no diretório ../server/mods/deathmatch/resources/, caso estejam corretos. E finalmente "fica pronto para aceitar conexões" (ready to accept connections!).

Antes de se conectar ao seu servidor, você precisa executar o gamemode criado. Para isso, digite no console (a janela do MTA Server.exe) o comando gamemode myserver (obs: "myserver" é o nome da pasta criada no início deste tutorial e, consequentemente, o nome do seu recurso) e pressione Enter. O servidor irá carregar o gamemode e mostrar os erros do seu script, caso existam.

Agora você pode se conectar ao seu servidor de duas maneiras:

• Clique em Quick Connect > Insira o endereço IP do servidor e o número da porta no seguinte formato - IP:Porta
• Navegue até Server Browser > Aba Local > Clique duas vezes no seu servidor.

Se tudo correr bem, seu personagem será criado nas coordenadas especificadas.

No próximo tópico iremos criar um comando para que o jogador possa gerar um veículo ao seu lado. Se preferir, embora não recomendado caso seja iniciante, você pode visitar alguns scripts mais avançados clicando aqui. Outra parte interessante da seção "Scripting", na qual obviamente você está, é Conhecendo a Interface Gráfica. Nela, se discute a criação de interfaces gráficas para seus scripts.

Criando um comando simples

Vamos voltar ao arquivo script.lua. Como foi mencionado anteriormente, criaremos agora um comando que irá gerar um carro ao lado do seu personagem. Antes de tudo, precisamos criar uma função e um evento especial, chamada addCommandHandler().

-- cria a função que será executada pelo comando.
function createVehicleForPlayer(thePlayer, command, vehicleModel)
   -- crie aqui seu veiculo e tudo mais
end

-- cria um gerenciador de comandos
addCommandHandler("createvehicle", createVehicleForPlayer)

[[{{{image}}}|link=|]]	Dica: As funções nativas do MTA são clicáveis em todo o Wiki e lhe redirecionam à páginas sobre elas.