Configuración

La mayoría de los proyectos no necesitan configuración: instala el plugin, inicia sesión y haz clic en Configure para tu agente. Esta página explica qué hace cada ajuste de la ventana de AI Game Developer, dónde se guardan los ajustes, cómo sobrescribirlos para la automatización y cómo se comporta el plugin en CI y en las compilaciones de jugador.

La ventana de AI Game Developer#

Ábrela con Window > AI Game Developer — MCP (Ctrl+Alt+A, o Cmd+Option+A en macOS) o con el botón AI de la barra de herramientas de la vista Scene. De arriba abajo contiene:

• Log Level, Timeout (ms) y Tool timeout (ms), además de la Version del plugin.
• Connection: el conmutador Custom / Cloud y los ajustes del modo elegido.
• Una línea temporal de conexión: Unity (con un botón Connect / Disconnect), MCP server y AI agent.
• El desplegable AI agent con el configurador de cada cliente: Model Context Protocol (MCP) con Configure / Remove, y Skills con Auto-generate y Generate.
• Contadores de Tools, Prompts y Resources, cada uno con un botón Open.
• Extensions: instala paquetes de herramientas opcionales (consulta Extensions).
• Enlaces de ayuda: Help / Talk (Discord), Bug Report (issues de GitHub) y un botón Check para diagnósticos de serialización.

Modos de conexión#

Cloud (predeterminado)#

El plugin se conecta al servidor alojado en https://ai-game.dev/mcp. No se inicia ningún servidor local y la URL no es editable. El modo Cloud requiere iniciar sesión: haz clic en Authorize junto a Cloud Token y aprueba el código de dispositivo en tu navegador, o inicia sesión una vez con unity-mcp-cli login o con la aplicación AI Game Dev. Revoke cierra la sesión en todas las herramientas de AI Game Dev de la máquina.

Custom (local o tu propio servidor)#

El plugin se conecta a la URL indicada en Server URL. De forma predeterminada es un servidor local en http://localhost:<port>, y el plugin descarga, inicia y detiene el servidor (gamedev-mcp-server) por ti. También puedes introducir la URL de un servidor MCP remoto que alojes tú. Server URL solo es editable mientras Unity está desconectado del servidor.

El modo Custom añade estos ajustes:

• MCP server: un botón Start / Stop y el estado (Running, Starting, Stopping, Downloading, o External cuando otro proceso ya sirve el puerto). Download / Retry server aparece si la descarga del binario falló.
• Transport: http (recomendado) o stdio. Con http el agente se conecta al servidor en ejecución, varios agentes pueden compartirlo y el servidor puede ejecutarse en otra máquina. Con stdio el agente lanza el servidor como su propio proceso hijo, solo un agente puede conectarse y el botón Start / Stop está deshabilitado.
• Authorization Token: none, oauth o token.
  • none: el servidor acepta cualquier conexión. Seguro solo cuando el puerto no es accesible desde otras máquinas.
  • oauth: los agentes inician sesión con su cuenta de ai-game.dev; el servidor verifica los tokens en línea.
  • token: un secreto compartido, totalmente sin conexión. Haz clic en New para generar un token y luego en Configure (o copia el token en la configuración del agente a mano).

El puerto#

El puerto local no es un valor fijo como 8080. Se deriva de la carpeta de tu proyecto: el hash SHA-256 de la ruta normalizada del proyecto, mapeado al rango 20000 a 29999. El mismo proyecto siempre obtiene el mismo puerto, y proyectos distintos obtienen puertos distintos, así que varias instancias de Unity pueden ejecutarse en paralelo. La CLI usa la misma fórmula, por lo que sus comandos encuentran el servidor correcto sin flags.

Para usar otro puerto, desconecta y luego escríbelo en Server URL (por ejemplo http://localhost:25000). Los configuradores escriben el puerto que introdujiste en las configuraciones de los agentes.

El archivo de configuración#

Los ajustes se guardan por usuario en UserSettings/AI-Game-Developer-Config.json, creado en el primer inicio. Claves destacadas:

Las credenciales de Cloud no se guardan aquí; viven en ~/.ai-game-dev/credentials.json. Para empezar de cero, usa Tools > AI Game Developer > Reset Config, que restaura los valores predeterminados y recarga los scripts.

Herramientas, prompts y recursos#

El contador Tools muestra cuántas de las herramientas instaladas ve el agente, y una estimación de los tokens que ocupan en el contexto de la IA. Haz clic en Open para mostrar u ocultar herramientas individuales; las ventanas MCP Prompts y MCP Resources funcionan igual.

Una herramienta oculta no se elimina: desaparece de la lista de herramientas del agente pero sigue ejecutándose cuando se llama por su nombre. Menos herramientas visibles dejan más contexto para razonar. También puedes cambiar la visibilidad con la herramienta tool-set-visibility o desde una terminal:

unity-mcp-cli configure ./MyUnityProject --enable-tools screenshot-scene-view,script-read
unity-mcp-cli configure ./MyUnityProject --list

Overrides de entorno y de línea de comandos#

Para CI y lanzamientos por script, el plugin lee estas variables (o los argumentos de línea de comandos de Unity correspondientes) al iniciarse. Los overrides se aplican solo en memoria y nunca se escriben en el archivo de configuración.

Los argumentos de línea de comandos tienen prioridad sobre las variables de entorno. Ejemplo para un Editor en modo batch conectado a un servidor local:

Unity -batchmode -projectPath ./MyUnityProject \
  -UNITY_MCP_CLOUD_URL=http://localhost:8080 \
  -UNITY_MCP_KEEP_CONNECTED=true \
  -UNITY_MCP_AUTH_OPTION=token \
  -UNITY_MCP_TOKEN=my-secret-token

unity-mcp-cli open establece estas variables por ti; consulta la referencia de la CLI.

Deshabilitar Unity MCP en CI#

El plugin detecta entornos de CI y entonces omite la descarga del servidor y la conexión automática. Para desactivarlo por completo en trabajos de pruebas de CI habituales, usa una de las dos opciones de exclusión:

• UNITY_MCP_DISABLE=1 (o true) en el entorno del proceso que lanza Unity. El plugin omite el arranque, el registro de herramientas, la descarga del servidor, la resolución de NuGet y sus hooks del editor. Su código sigue compilándose, así que el proyecto debe seguir compilando.
• UNITY_MCP_EXCLUDE_FROM_COMPILATION como Scripting Define Symbol en Project Settings > Player > Other Settings. Esto excluye de la compilación todos los ensamblados del plugin (y las extensiones de primera parte actualizadas). Tu propio código que hace referencia a tipos del plugin necesita #if !UNITY_MCP_EXCLUDE_FROM_COMPILATION.

Ninguna de las dos se habilita automáticamente para -batchmode o -runTests, porque las sesiones MCP sin interfaz necesitan el plugin.

Compilaciones de jugador y runtime#

El ensamblado de runtime del plugin se compila para todas las plataformas, así que forma parte de tus compilaciones de jugador a menos que lo excluyas con el define anterior. Una compilación nunca se conecta por sí sola: en un juego, lo habilitas desde el código con UnityMcpPluginRuntime.Initialize(...), que es cómo expones herramientas dentro del juego a una IA (por ejemplo, un oponente de ajedrez con IA). Consulta Custom tools.

Autoalojar el servidor MCP#

El servidor es el GameDev-MCP-Server compartido, publicado también como la imagen de Docker aigamedeveloper/mcp-server:

docker run -p 8080:8080 aigamedeveloper/mcp-server

Luego configura el plugin en Custom con Server URL http://localhost:8080 (o tu host), y apunta tu agente a la misma dirección. El servidor acepta ajustes como --port, --client-transport, --authorization y --idle-timeout-seconds, o las variables de entorno MCP_PLUGIN_* correspondientes; la documentación del servidor las enumera todas.

Páginas relacionadas#

• Connecting AI clients para las configuraciones de los agentes y el inicio de sesión.
• Troubleshooting para problemas de conexión.