ES/Introducción a la Programación de GUI

Una importante caracteristica de MTA:SA es la posibilidad de programar GUIs propias (Graphics User Interface que traducido seria, Interfaz Grafica del Usuario). Una GUI consiste en ventanas, botones, cajas de edición, entre otras cosas.... Estos pueden ser mostrados mientras el jugador esta en el juego, y es usado para tener interacción con el usuario en lugar de los típicos comandos.

Consola de Administración

Un tutorial para hacer una ventana de ingreso

En este tutorial nosotros haremos una simple ventana de ingreso, con dos cajas de edición y un botón. La ventana aparecerá cuando el jugador ingrese al juego, y cuando el botón sea apretado, el jugador aparecerá. El tutorial continuara el modo que hicimos en Introducción a LUA (Si tu continuaste de la pagina anterior, tendrás que remover o comentar la linea donde se encuentra la función spawnPlayer, porque estaremos reemplazando eso con una GUI alternativa en este tutorial). También daremos una mirada a lo que es la programación en el cliente.

Dibujando la ventana

Toda GUI se debe hacer en el cliente. Esto tambien es una buena practica para tener todos los archivos de cliente en carpetas separadas.

Busca el directorio /Tu servidor MTA/mods/deathmatch/resources/myserver/, y crea una carpeta llamada "cliente". En la carpeta cliente, crea un archivo de texto y llamalo "gui.lua".

En este archivo escribiremos una función que dibuje la ventana. Para crear la ventana usaremos guiCreateWindow:

function createLoginWindow()
	-- definimos las coordenadas X,Y donde se creara la ventana
	local X = 0.375
	local Y = 0.375
	-- definimos el tamaño de la ventana (El ancho y el alto)
	local Width = 0.25
	local Height = 0.25
	-- Creamos la ventana y la grabamos su valor de elemento en la variable 'wdwLogin'
	-- Apreta en el nombre de la función para leer su definición
	wdwLogin = guiCreateWindow(X, Y, Width, Height, "Porfavor ingrese", true)
end

Relativo y absoluto

Notese que el argumento final pasado a la función guiCreateWindow en el ejemplo de arriba es true. Esto indica que las coordenadas y las dimensiones de la ventana son relativas, queriendo decir que son un porcentaje del tamaño total de la pantalla. Queriendo decir que el lado izquierdo de la pantalla es 0 y el lado derecho es 1. Una posición X de 0.5, representaría el centro de la pantalla. Similarmente, si la parte de arriba de la pantalla es 0 y la de abajo es 1, entonces una posición en Y de 0.2 seria un 20% abajo de la pantalla. Este mismo principio se aplica al ancho y alto también. (Con un ancho de 0.5, quiere decir que la ventana tendrá un ancho de la mitad de la pantalla)

La alternativa a usar valores relativos es usar absolutos (Pasando false en vez de true a guiCreateWindow)). Los valores absolutos son calculados como el numero total de pixeles de la esquina superior-izquierda de su padre (Si no se especifica un elemento padre, entonces el padre seria la pantalla en si). Si asumimos una resolución de 1920x1200, El lado izquierdo empezaría con 0 pixeles y el lado derecho tendría 1920 pixeles, una posición X de 960 representaría el centro de la pantalla. Similarmente, si el lado superior de la pantalla empieza 0 pixeles y el lado inferior termina con 1920 pixeles, una posición Y de 20 seria 20 pixeles bajo el lado superior de la pantalla. El mismo principio se aplica al ancho y al alto. Tu puedes usar guiGetScreenSize y un poco de matemáticas para calcular algunas posiciones absolutas.

Las diferencias entre usar valores relativos y absolutos es un poco simple; Una GUI creada con valores absolutos siempre tendrá el mismo tamaño y posición, mientras que una GUI creada usando valores relativos siempre sera un porcentaje del tamaño de su padre.

El valor absoluto es generalmente mas fácil de mantener cuando se edita un código a mano, aunque tu opción del tipo depende de la situación para que lo estas usando.

Para propósitos de esta introducción usaremos valores relativos. (Aunque recomiendo usar absolutos)

Añadiendo los componentes

Ahora agregaremos las etiquetas de texto (Diciendo "Usuario:" y "Contraseña:", Cajas de edición (Para ingresar los datos) y un botón para ingresar.

Para crear el botón usaremos guiCreateButton, y para crear las cajas de edición usaremos guiCreateEdit:

Nota que estamos escribiendo mas codigo de nuestra existente función 'createLoginWindow'. Esto no es una nueva función y esta pensada a reemplazar la que tu ya tenias.

function createLoginWindow()
	local X = 0.375
	local Y = 0.375
	local Width = 0.25
	local Height = 0.25
	wdwLogin = guiCreateWindow(X, Y, Width, Height, "Porfavor Ingrese", true)
	
	-- definimos las coordenadas X,Y de nuestra primera etiqueta
	X = 0.0825
	Y = 0.2
	-- definimos el ancho y el alto de nuestra primera etiqueta
	Width = 0.25
	Height = 0.25
	-- Creamos la primera etiqueta, nota que el argumento final es 'wdwLogin' significando la ventana que creamos arriba es el padre de
	-- esta etiqueta (asique todos los valores de posición y tamaño son relativos a la posición de esa ventana)
	guiCreateLabel(X, Y, Width, Height, "Usuario", true, wdwLogin)
	-- alteramos el valor Y, para que la segunda etiqueta este un poco mas abajo de la primera
	Y = 0.5
	guiCreateLabel(X, Y, Width, Height, "Contraseña", true, wdwLogin)
	

	X = 0.415
	Y = 0.2
	Width = 0.5
	Height = 0.15
	edtUser = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
	Y = 0.5
	edtPass = guiCreateEdit(X, Y, Width, Height, "", true, wdwLogin)
	-- Ponemos el maximo de caracteres que se pueden escribir en las cajas a 50
	guiEditSetMaxLength(edtUser, 50)
	guiEditSetMaxLength(edtPass, 50)
	
	X = 0.415
	Y = 0.7
	Width = 0.25
	Height = 0.2
	btnLogin = guiCreateButton(X, Y, Width, Height, "Ingresar", true, wdwLogin)
	
	-- Hacer la ventana invisible
	guiSetVisible(wdwLogin, false)
end

Nota que todo componente GUI creado es un hijo de la ventana, esto se hace espeficicando el elemento padre (wdwLogin, en este caso) cuando se crea el componente.

Esto es muy util porque no solo hace pensar que todos sus componentes estan unidos a la ventana y que se van a mover con ella, sino que ademas todo cambio hecho a la ventana padre seran aplicados arbol abajo a todos sus elementos hijos. Por ejemplo, ahora podemos esconder todos los elementos GUI que creamos con solo esconder la ventana:

guiSetVisible(wdwLogin, false) --esconde todos los elementos GUI que hicimos para poderlos mostrar al jugador en el momento apropiado

Uso de la función anterior

La función createLoginWindow ha sido completada, pero no hará nada hasta procesarlo. Es recomendable hacer todo el GUI cuando el resource del cliente se inicie, ocultarlo, y mostrarle al jugador cuando sea necesario. Por lo tanto, vamos a escribir un "event handler" para "onClientResourceStart" para crear la ventana:

-- esto significa que se iniciará cuando el propio resource se inicie
addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()), 
	function ()
		createLoginWindow()
	end
)	

Como en la ventana han de registrarse, la ventana se mostrará cuando el jugador entre al juego. Para esto, se puede usar el mismo evento, "onClientResourceStart", con lo que podemos modificar el código anterior para mostrar la ventana:

Tenga en cuenta que ahora estamos escribiendo más código para nuestro actual 'onClientResourceStart'.Este no es un nuevo evento, está destinado a reemplazar el qué ya tienes.

addEventHandler("onClientResourceStart", getResourceRootElement(getThisResource()), 
	function ()
		-- crear el registro con sus componentes dentro de la ventana
		createLoginWindow()

		-- emitir un mensaje de bienvenida al jugador
                outputChatBox("Welcome to My MTA:SA Server, please log in.")

		-- si la interfaz gráfica de usuario se creó correctamente, a continuación, mostrar la interfaz gráfica de usuario para el jugador
	        if (wdwLogin ~= nil) then
			guiSetVisible(wdwLogin, true)
		else
			-- si la interfaz gráfica no se ha creado correctamente, se lo dirá al jugador
			outputChatBox("An unexpected error has occurred and the log in GUI has not been created.")
	        end 

		-- mostrar el cursor al jugador ( para que pueda seleccionar y pulsar los botones )
	        showCursor(true)
		-- establecer el foco de entrada en la interfaz gráfica de usuario, permitiendo a los jugadores (por ejemplo) al pulsar 'T' sin que salga la apertura en el chat
	        guiSetInputEnabled(true)
	end
)	

Tenga en cuenta que tenemos un sencillo "control de seguridad" antes de hacer la ventana visible, por lo que en el caso improbable de que la ventana no se haya creado, es decir wdwLogin no es un elemento válido, no se obtiene un error y simplemente se informa al jugador de lo que ha sucedido . En el siguiente paso, vamos a crear la funcionalidad del botón para el botón "Iniciar sesión".

Scripteando el boton

Ahora que tenemos creado nuestro GUI and se lo hemos mostrado a un jugador, nesecitamos hacerlo funcionar.

Detectando el click

Cuando un jugador clickea en alguna parte del GUI, el evento "onClientGUIClick" sera triggeado para el componente GUI que tu clickeaste. Esto nos permite detectar facilmente cualquier click en los elemento GUI que nosotros quisimos usar. Por ejemplo, podemos adjuntar el evento con el boton "btnLogin" para agarrar algun click en el:

-- adjunta el evento onClientGUIClick a btnLogin y activa la funcion 'clientSubmitLogin'.
addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)

Que quede claro que el argumento final es pasado a "false". Esto indica que el evento solo se va a activar directamente en btnLogin, sino el evento se tiene que propagarse por todo los elementos. Ajusta esto a true mientras adjunta a los elementos GUI querra decir que algun click en cualquier elemento en el mismo se activara este evento.

Esta linea del codigo podra ahora ser añadida dentro de la funcion createLoginWindow. Esto es un error comun al intentar y adjuntar los eventos a algun elemento GUI inexistente, por lo tanto hacer que siempre el evento se adjunte despues the crear los elementos GUI (en este caso, el boton) ha sido creado:

Nota que ahora estamos escribiendo mas codigo para la existencia de la funcion 'createLoginWindow'

function createLoginWindow()
	-- crea todos los elementos GUI
	...

	-- Ahora añadimos nuevo evento onClientGUIClick al evento luego de ser creado.
	addEventHandler("onClientGUIClick", btnLogin, clientSubmitLogin, false)

Administrar el clic

Ahora para detectar cuando le damos clic al boton, tenemos que escribir código para manejar lo que suceda cuando lo pulsen. En nuestro controlador de evento onClientGUIClick, le dijimos que llamara a la función clientSubmitLogin cada vez que se hace clic en btnLogin. Por lo tanto, ahora podemos utilizar la función clientSubmitLogin para controlar lo que ocurre cuando se hace clic en el botón:

-- Crea la función y definir los parámetros 'Botón' y 'Estado'.
-- (éstos pasan automáticamente por OnClientClick)
function clientSubmitLogin(button,state)
	-- si nuestro botón "login" es clickeado con el botón izquierdo del ratón, y soltado el botón izquierdo.
	if button == "left" and state == "up" then
		-- move the input focus back onto the game (allowing players to move around, open the chatbox, etc)
		guiSetInputEnabled(false)
		-- esconde la ventana y todos sus componentes
		guiSetVisible(wdwLogin, false)
		-- esconde el cursor del ratón
		showCursor(false)
	end
end

Ahora, cuando al botón le den clic, la ventana se debera esconder y todos los controles volveran. Despues, deberemos decirle al servidor que permita spawnear al jugador.

Triggering el server

La activación del server se puede hacer usando triggerServerEvent. Esto le permite activar un evento especificado en el servidor desde el cliente. El mismo se puede hacer a la inversa usando triggerClientEvent. Aquí, nosotros usamos la función triggerServerEvent para llamar a nuestro serverEvent personalizado, denominado "submitLogin", que a su vez controla el desove del jugador serverside.

Tenga en cuenta que ahora estamos escribiendo más código para nuestra función 'clientSubmitLogin' existente. Esto no es una nueva función y está destinado a reemplazar lo que ya tienes.

function clientSubmitLogin(button,state)
	if button == "left" and state == "up" then
		-- tomar el texto introducido en el campo 'username'
		local username = guiGetText(edtUser)
		-- tomar el texto introducido en el campo 'password'
		local password = guiGetText(edtPass)

		-- si el nombre de usuario y contraseña ambos existen
		if username and password then
			-- activar el server 'submitLogin' y pasar el nombre de usuario y contraseña a la misma.
			triggerServerEvent("submitLogin", getRootElement(), username, password)

			-- ocultar la gui, ocultar el cursor y devolver el control al player
			guiSetInputEnabled(false)
			guiSetVisible(wdwLogin, false)
			showCursor(false)
		else
			-- de otro modo, presentar un mensaje para el jugador, no activar el server
			-- y no ocultar la gui
			outputChatBox("Please enter a username and password.")
		end
	end
end

Crear el evento serverside

En este punto, ahora tenemos todo el código necesario en el clienteside, por lo que abrimos el archivo 'script.lua' serverside (desde el Introduction to Scripting) u otro archivo serverside adecuado para trabajar.

En el lado del servidor, recordamos que estamos spawneando al jugador tan pronto como se loguea. Así que, en primer lugar, tendremos que definir el evento personalizado que se utilizó antes en el cliente. Esto se puede hacer usando addEvent y AddEventHandler.

-- create our loginHandler function, with username and password parameters (passed from the client gui)
function loginHandler(username,password)

end

-- define our custom event, and allow it to be triggered from the client ('true')
addEvent("submitLogin",true)
-- add an event handler so that when submitLogin is triggered, the function loginHandler is called
addEventHandler("submitLogin",root,loginHandler)

Logging in

Ahora tenemos una función que es llama a través del evento personalizado 'submitLogin', podemos empezar a trabajar en el on logging y el spawning del jugador, haciendo uso de nuestra funcion 'loginHandler':

function loginHandler(username,password)
	-- compruebe que el nombre de usuario y la contraseña son correctos
	if username == "user" and password == "apple" then
		-- el jugador se ah logueado satisfactoriamente, asi que debe spawnearlo
		if (client) then
			spawnPlayer(client, 1959.55, -1714.46, 10)
			fadeCamera(client, true)
                        setCameraTarget(client, client)
			outputChatBox("Welcome to My Server.", client)
		end
	else
		-- si el nombre de usuario o contraseña no es correcta, enviar un mensaje al player
		outputChatBox("Invalid username and password. Please re-connect and try again.",client)
        end			
end

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

Para los fines de este tutorial, se muestra un sistema de nombre de usuario y una contraseña muy básico. Por una alternativa más completa, se puede utilizar el Sistema de cuentas o una base de datos MySQL.

También tenga en cuenta el uso dela variable "client", es una variable interna que utiliza MTA para identificar al jugador que provocó el evento.

Por último, no se olvide de incluir el nuevo archivo gui.lua en el meta.xml del recurso principal, y etiquetarlo como un script de cliente:

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

En este punto, ahora tenemos una ventana de base de inicio de sesión que comprueba el nombre de usuario y la contraseña del jugador cuando se hace clic en el botón de inicio de sesión. Si son correctos, el jugador se spawneara de forma automática.

Para obtener más ayuda con la GUI, consulte la GUI tutorials.