Conexiones con API

Conectar un videojuego con datos del mundo real es una de las técnicas más poderosas para crear experiencias inmersivas. En esta lección se explica paso a paso cómo realizar un web request desde Unity para obtener información climática en tiempo real y, con esos datos, modificar el clima dentro del juego.

¿Qué es Open Weather y cómo obtener acceso a su API?

Para traer datos meteorológicos reales se utiliza Open Weather Map [0:17], una plataforma que ofrece una API gratuita con ciertas condiciones de uso. El proceso para configurarla es directo:

• Ir a openweathermap.org y registrarse.
• Acceder a la pestaña API y buscar Current weather data [0:36].
• Suscribirse al servicio gratuito y hacer clic en Get API key.
• En la sección My API keys del perfil se genera una llave única.

Esta API key funciona como una credencial que identifica al usuario ante el servicio. Es fundamental no compartirla, ya que un tercero podría hacer un uso indebido de ella [1:16].

Una vez obtenida la llave, en la documentación (API doc) se encuentra la estructura de la URL de llamada. Esta URL requiere dos parámetros esenciales: el nombre de la ciudad y la API key [1:38].

¿Cómo se configura un web request en Unity?

De vuelta en Unity, se crea una carpeta llamada Weather con un script denominado WeatherChange [1:55]. Este script será el responsable de comunicarse con la API externa y gestionar la respuesta.

¿Qué librerías se necesitan?

Para habilitar la comunicación con servicios web, es necesario importar el namespace UnityEngine.Networking [2:10]. También se requieren System.Collections y System.Collections.Generic para trabajar con los enumeradores.

¿Qué es un IEnumerator y por qué se usa aquí?

Un IEnumerator es un tipo especial de método capaz de realizar esperas dentro de su ciclo de ejecución [2:20]. Esto resulta indispensable cuando el juego necesita comunicarse con una API externa, ya que la respuesta no llega de forma instantánea. Mientras los datos viajan por la red, el enumerador mantiene la ejecución pausada hasta recibir una respuesta o detectar un error.

Dentro de este método, llamado GetWeather, se construye el request:

• Se crea una variable UnityWebRequest www usando UnityWebRequest.Get() [2:58].
• Como parámetro se pasa la URL de la documentación de Open Weather, reemplazando el nombre de ciudad (por ejemplo, Bogota) y la API key personal [3:23].
• Se utiliza yield return www.SendWebRequest() para esperar la respuesta del servidor [3:52].

¿Cómo se maneja la respuesta del servidor?

Una vez que llega la respuesta, se evalúa si fue exitosa o no:

• Si www.result no es igual a UnityWebRequest.Result.Success, se muestra el error con Debug.LogError(www.error) [4:08].
• Si la respuesta es satisfactoria, se imprime el contenido con Debug.Log(www.downloadHandler.text) [4:28]. Los datos llegan en formato de texto, listos para ser procesados.

¿Cómo se ejecuta la corrutina desde Unity?

El IEnumerator no se ejecuta por sí solo; debe invocarse desde algún punto del ciclo de vida del script. Para ello se utiliza el método Start() junto con StartCoroutine [4:55]:

csharp void Start() { StartCoroutine(GetWeather()); }

En la escena de Unity se crea un GameObject vacío llamado Weather Manager y se le asigna el componente WeatherChange [4:43]. Al presionar Play, el juego realiza la solicitud a la API y muestra los datos climáticos en la consola.

El concepto de StartCoroutine es clave: es la función de Unity que permite lanzar un enumerador como una corrutina, es decir, un proceso que puede pausarse y reanudarse sin bloquear el resto del juego.

Con los datos ya disponibles en Unity, el siguiente paso es interpretarlos. La información que llega del servidor viene en formato JSON, y su lectura y aplicación para modificar el clima del juego se aborda en la clase siguiente [5:14].

¿Ya probaste conectar tu juego con alguna API externa? Comparte tu experiencia y las dificultades que encontraste en los comentarios.