PT-BR/Introducão ao GUI scripting

Um importante recurso do MTA:SA é capacidade de criar uma GUI (Graphical User Interface) personalizada. Uma GUI consiste em janelas, botões, caixas de edição, caixas de verificação e etc. Em outras palavras, todos os componentes presentes em janelas do Windows, por exemplo. Eles podem ser exibidos enquanto o usuário está no jogo, em vez de eles precisarem usar comandos tradicionais.

Obs: É de extrema importância dar uma olhada na Introdução a scripting porque muitas perguntas que poderão surgir neste tutorial provavelmente estão relacionados a falta de conceitos básicos de scripting.

Admin Console GUI

Tutorial: Janela de Login

Neste tutorial, vamos fazer uma janela de login bem simples, com duas caixas de entrada (input boxes) e um botão (button). A janela aparecerá quando o jogador entrar no jogo, e quando o botão de login for clicado, o jogador nasce no mapa. Usaremos o modo de jogo que foi criado no artigo Introdução a scripting. Caso tenha seguido os procedimentos desse tutorial e tem o script (script.lua), precisará remover ou comentar a linha spawnPlayer da função joinHandler, pois o jogador só será gerado no jogo quando feito o login.

Criando a janela

Todo o script em GUI deve ser feito no lado do cliente. Também é recomendado colocar esses arquivos em uma pasta separada, em prol de manter uma melhor organização.

Vá até o diretório ../server/mods/deathmatch/resources/, e crie uma pasta chamada "client". Sob o diretório /client/, crie um arquivo de texto com o nome "gui.lua".

Neste arquivo vamos escrever uma função que cria a janela. Para fazer isto, iremos utilizar guiCreateWindow:

function criarJanelaDeLogin()
	-- definir a posição X e Y
	local x = 0.375
	local y = 0.375
	-- definir a largura e altura
	local largura = 0.25
	local altura = 0.25
	-- criar a janela e defini-la na variável 'janelaLogin'
	-- clique no nome da função para ler a sua documentação
	janelaLogin = guiCreateWindow(x, y, largura, altura, "Efetue o Login", true)
end

Relativo e Absoluto

Veja que o último argumento colocado em guiCreateWindow é true. Isto indica que as coordenadas e dimensões da janela são relativas, o que significa que é uma porcentagem do tamanho total da tela. Em outras palavras, se o lado esquerdo da tela é 0, e a extrema-direita é 1. Desta maneira, a posição X valendo 0.5 representaria o ponto central da tela. De forma análoga, se a parte superior da tela é 0 e a inferior é 1, uma posição Y de 0.2 seria 20% do caminho para baixo da tela. Os mesmos princípios se aplicam para largura e altura, exemplo: Se a largura for 0.5, a janela será a metade da largura da tela.

Caso não queira utilizar valores relativos, poderá optar por absolutos ao colocar false no argumento. Os valores absolutos são calculados como o número total de pixels do canto superior esquerdo do elemento, o qual o componente GUI está subordinado. Se nenhum elemento pai for especificado, este será a própria tela. Neste caso, se tivermos uma resolução de tela de 1920x1200, o lado esquerdo será 0 pixel e o de extrema-direita, será 1920 pixels. Uma posição X de 960 representará o ponto central da tela. Similarmente, se a parte superior da tela é de 0 pixel e o fundo é de 1200, uma posição Y de 20 seria de 20 pixels para baixo a partir da parte superior da tela. Os mesmos princípios se aplicam a largura e altura. Exemplo: Caso a largura seja 50, a janela terá os exatos 50 pixels de largura. Com um pouco de matemática, e usando a função guiGetScreenSize, você poderá calcular as posições absolutas corretamente.

As diferenças entre o uso de valores relativos e absolutos é muito simples. Se for uma GUI criada usando valores absolutos, cada unidade valerá um pixel. Enquanto os valores relativos usarão a porcentagem para definir essas posições.

Absoluto é geralmente mais fácil de usar quando a edição do código for feita a mão. Entretanto, a escolha do tipo de medida dependerá da finalidade do componente GUI.

Uma das principais razões de se utilizar valores relativos é para evitar que as janelas fiquem fora da tela ou em posições indesejáveis. Uma GUI que foi feita, por exemplo, na resolução de 1080p e for posicionada no canto superior direito com valores absolutos, ficará fora da tela caso esse script fosse executado em 720p. Oras, porque posicionarei uma janela nas coordenadas (1080, 0) se a tela do sujeito só vai até 720 pixels no eixo x? Simplesmente não vai funcionar.

Neste tutorial, obviamente usaremos valores relativos para a tela de login, e seus componentes, ficarem exatamente onde é preciso.

Adicionando os componentes

Vamos adicionar:

• Textos(labels) para indicar o que é cada campo - usuário, senha
• Caixas de edição (edit boxes), para que o usuário possa inserir seus dados
• Um botão para efetuar o login

Para criar botões você deve usar guiCreateButton, e para criar caixas de edição você deve usar guiCreateEdit:

Note que agora iremos adicionar mais instruções para a função criarJanelaDeLogin. Portanto, esta não é uma nova função, e sim uma substituta da qual você já tem.

function criarJanelaDeLogin()
	local x = 0.375
	local y = 0.375
	local largura = 0.25
	local altura = 0.25
	wdwLogin = guiCreateWindow(x, y, largura, altura, "Efetue o Login", true)
	
	-- Definir as novas posições x e y para o primeiro label
	x = 0.0391
	y = 0.1979
	-- Definir o novo valor de largura e altura para o primeiro label
	largura = 0.3672
	altura = 0.25
	-- Criar o primeiro label. Note que o último argumento passado é 'wdwLogin', representando a janela
	-- Ou seja, ele será o elemento pai (parent) deste texto (label)
	-- Assim toda os valores de tamanho serão relativos a esta janela
	guiCreateLabel(x, y, largura, altura, "Usuário:", true, wdwLogin)

	-- Alterar o valor de y, assim o segundo label ficará ligeiramente abaixo do primeiro
	largura = 0.25
	y = 0.5
	guiCreateLabel(x, y, largura, altura, "Senha:", true, wdwLogin)

	-- Valores para as entradas
	x = 0.415
	y = 0.2
	largura = 0.5
	altura = 0.15
	editUsuario = guiCreateEdit(x, y, largura, altura, "", true, wdwLogin)
	Y = 0.5
	editSenha = guiCreateEdit(x, y, largura, altura, "", true, wdwLogin)

	-- Definir o tamanho máximo de caracteres do nome de usuário e a senha para 50
	guiEditSetMaxLength(editUsuario, 50)
	guiEditSetMaxLength(editSenha, 50)
	
	x = 0.415
	y = 0.7
	largura = 0.25
	altura = 0.2
	btnLogin = guiCreateButton(x, y, largura, altura, "Login", true, wdwLogin)
	
	-- Tornar a janela invisível
	guiSetVisible(wdwLogin, false)
end

Em nosso script, quando usamos a função para criar cada componente da janela, definimos a variável wdwLogin no último argumento. Isso significa que esses componentes estão contidos na janela. Em inglês dizemos que ele é um child element e a janela é um parent element..

Isto é muito útil porque não só significa que todos os componentes estão anexados à janela e irão mover-se com ela. Além disso, todas as alterações realizadas na janela serão aplicadas a todos os elementos subordinados, ou elementos filhos. Para ocultar a janela, simplesmente usaremos a função:

guiSetVisible(wdwLogin, false) -- Isso fará com que todos os elementos subordinado fiquem invisíveis também. O conjunto só será mostrado quando for preciso.

Usando a função que acabamos de fazer

A nossa função agora está completa, mas nada irá acontecer até que nós a chamamos. É Recomendado criar toda a GUI quando o recurso do cliente for iniciado, em seguida, ocultá-la e mostrar para o jogador quando necessário. Portanto, vamos adicionar um manipulador de eventos com o evento onClientResourceStart para criar a janela:

-- anexa o manipulador de eventos para o elemento raiz (root element) do recurso:
-- isto significa que ele só irá ser executado quando o próprio recurso for iniciado.
addEventHandler( "onClientResourceStart", getResourceRootElement(getThisResource()), 
	function ()
		criarJanelaDeLogin()
	end
)

Como se trata de uma janela de login, precisamos mostrar a janela quando o jogador entrar no servidor. Isto pode ser feito usando o mesmo evento, ou seja, onClientResourceStart. Agora, precisamos complementar o código anterior para que mostre a janela.

No código a seguir, vamos dar mais funcionalidade para o evento 'onClientResourceStart'. Note que não será criado um novo manipulador de eventos, este código só substituirá o que você já tem.

addEventHandler( "onClientResourceStart", getResourceRootElement(getThisResource()), 
	function ()
		-- Chamando a função para criar a janela de login e seus componentes.
		criarJanelaDeLogin()

		-- Mostrar uma mensagem de boas-vindas ao jogador.
		outputChatBox("Bem-vindo ao meu servidor do MTA:SA, por favor efetue o login.")

		-- Se a GUI foi criada com êxito, então ela será mostrada ao jogador.
		if (wdwLogin ~= nil) then
			guiSetVisible(wdwLogin, true)
		else
			-- Se a GUI não foi criada corretamente, notificaremos o jogador.
			outputChatBox("Um erro inesperado ocorreu e a janela de login não foi criada.")
		end

		-- Habilitar o cursor para o jogador, para que ele possa clicar sobre os componentes.
		showCursor(true)
		-- Definir o foco de entrada para a GUI, permitindo, por exemplo, que os jogadores pressionem 't', sem que o chatbox abra.
		guiSetInputEnabled(true)
	end
)

Note que há uma verificação preventiva antes de tornar a janela visível. Caso a janela não seja criada com êxito, isto é, se wdwLogin não for um valor válido, notificaremos ao jogador que um erro ocorreu.

Na próxima etapa, vamos dar funcionalidade ao botão de login.

Programando o botão

Agora que criamos nossa interface e a mostramos ao jogador, é preciso programá-la para que tudo funcione.

Detectando o clique

Quando o jogador clicar em qualquer parte da GUI, o evento onClientGUIClick é chamado para o componente que você clicou. Isto nos permite detectar facilmente quaisquer cliques sobre o elemento GUI que desejar. Por exemplo, podemos anexar o evento ao botão 'btnLogin' para sabermos quando ele for clicado:

-- Anexar o evento 'onClientGUIClick' para o botão btnLogin.
-- E chamar a função 'requisitarLogin' quando clicar nele.
addEventHandler("onClientGUIClick", btnLogin, requisitarLogin, false)

Observe que o último argumento é false. Isto quer dizer que o evento só será chamado para btnLogin, e não para o seu elemento pai, que é a janela. Por outro lado, se for colocado "true", o evento será chamado para o elemento pai.

Esse código agora pode ser colocado dentro da função criarJanelaDeLogin. Um erro comum, é anexar eventos para elementos GUI inexistentes, então certifique-se de sempre anexar os seus eventos depois que o elemento gui (neste caso, o botão) for criado:

No código a seguir, vamos adicionar o evento para detectar o clique, dentro da função 'criarJanelaDeLogin'.

function criarJanelaDeLogin()
	-- criar todos os nossos elementos da GUI
	...

	-- agora, adicionar o evento onClientGUIClick para o botão que acabamos de criar
	addEventHandler("onClientGUIClick", btnLogin, requisitarLogin, false)

Quando clicar no botão

Agora que podemos detectar quando o jogador clica no botão, vamos escrever o código para fazer a próxima etapa depois que o botão for clicado. No manipulador de eventos onClientClick, a função requisitarLogin sempre será chamada quando o botão btnLogin for clicado. Então, no próximo código, vamos começar a dar funcionalidade para a função requisitarLogin:

-- criar a função e definir os dois parâmetros do evento: 'button' - botão e state - estado do clique
function requisitarLogin(button,state)
	-- se o botão foi clicado com o botão esquerdo do mouse, e o estado do clique for 'up' (solto)
	if button == "left" and state == "up" then
		-- mudar o foco de entrada de volta para o jogo (permitindo ao jogador se movimentar e abrir o chat)
		guiSetInputEnabled(false)
		-- ocultar a janela e todos os componentes
		guiSetVisible(wdwLogin, false)
		-- desabilitar o cursor do mouse
		showCursor(false)
	end
end

Agora, quando o botão de login for clicado, a janela será ocultada, o cursor do mouse desabilitado e o foco de entrada será desativado. Na próxima etapa, vamos chamar o lado do servidor para permitir que o jogador seja gerado no jogo.

Chamando o servidor

Para chamar um evento do lado do servidor, usamos triggerServerEvent. Essa função lhe permite chamar um evento definido no lado do servidor por meio do cliente. O contrário pode ser feito usando a função triggerClientEvent. Agora vamos usar a função triggerServerEvent para chamar o evento que será feito no lado do servidor, esse evento irá controlar a função de 'spawn'.

No código a seguir, vamos complementar a função 'requisitarLogin'. Para o seu entendimento, observe os comentários pelo código.

function requisitarLogin(button,state)
	if button == "left" and state == "up" then
		-- obter o texto inserido no campo 'nomeDeUsuario'
		local nomeDeUsuario = guiGetText(editUsuario)
		-- obter o texto inserido no campo 'senha'
		local senha = guiGetText(editSenha)
		-- note que 'editUsuario' e 'editSenha' são variáveis definidas na criação do campo de edição
		
		-- se o nome de usuário e senha existem
		if nomeDeUsuario and senha then
			-- chamar o evento do servidor 'submeterLogin' e passar o nome de usuário e senha nos argumentos
			triggerServerEvent("submeterLogin", getRootElement(), nomeDeUsuario, senha)

			-- ocultar a janela, desabilitar o cursor e desativar foco de entrada
			guiSetInputEnabled(false)
			guiSetVisible(wdwLogin, false)
			showCursor(false)
		else
			-- se o nome de usuário ou senha não existir, sairá uma mensagem para o jogador,
			outputChatBox("Por favor, digite o nome de usuário e senha.", 230, 0, 0)
		end
	end
end

Criando o evento no servidor

Agora que finalizamos a parte do lado do cliente, abra seu arquivo do lado do servidor 'script.lua' (do Introdução a scripting) ou apenas crie um novo arquivo.

Lembre-se que o jogador só será gerado no jogo assim que ele logar. Então, em primeiro lugar, vamos criar o evento personalizado 'submeterLogin'. Para isso, você terá de usar as funções addEvent e addEventHandler.

-- criar função loginHandler, com os parâmetros: 'username' e 'senha' (enviado pelo lado do cliente)
function loginHandler(username,senha)

end

-- definir o evento personalizado e permitir que ele seja chamado a partir do cliente usando 'true'
addEvent("submeterLogin",true)
-- adicionar um manipulador de eventos para quando 'submeterLogin' for chamado,
-- chamar também a função 'loginHandler' que está ligada a ele
addEventHandler("submeterLogin",root,loginHandler)

Efetuando login

Agora, temos uma função que é chamada através do evento personalizado 'submeterLogin'. Para finalizar, iremos complementar a função 'loginHandler':

function loginHandler(username,senha)
	-- verificar se o nome de usuário e senha estão corretos
	if username == "user" and senha == "apple" then
		-- se o jogador foi logado com sucesso, então gerar ele no jogo
		if (client) then
			spawnPlayer(client, 1959.55, -1714.46, 10)
			fadeCamera(client, true)
			setCameraTarget(client, client)
			outputChatBox("Bem-vindo ao servidor.", client)
		end
	else
		-- se o nome de usuário ou senha não estão corretos, informar para o jogador
		outputChatBox("Nome de usuário e senha inválidos. Por favor, tente novamente.",client)
	end			
end

addEvent("submeterLogin",true)
addEventHandler("submeterLogin",root,loginHandler)

Agora você pode colocar em prática o que aprendeu neste tutorial e começar a trabalhar com login e spawn do jogador, usando a função 'loginHandler'. Note que um sistema de registro não está integrado ao tutorial. Para isso, você pode optar pelo uso do Sistema de conta nativo do MTA ou um banco de dados MySQL.

Observe também o uso da variável "client": é uma variável interna usada pelo MTA para identificar o jogador que fez o evento ser chamado.

Por fim, não se esqueça de incluir o arquivo gui.lua novo no meta.xml do recurso, e definir na tag 'type' como um script do lado do cliente:

<script src="client/gui.lua" type="client" />

Neste tutorial, criamos uma simples janela que verifica o nome de usuário e a senha quando o botão de login é pressionado. Se os dados estiverem corretos, o jogador entrará no jogo.

Para mais ajuda com GUI, consulte Tutoriais GUI (página em inglês).