This translation is community contributed and may not be up to date. We only maintain the English version of the documentation. Read this manual in English
Defold contiene un depurador Lua integrado con una herramienta de inspección. Junto con las herramientas de profiling integradas, es una herramienta potente que puede ayudar a encontrar la causa de errores en la lógica de tu juego o a analizar problemas de rendimiento.
La forma más sencilla de depurar tu juego en Defold es usar depuración con impresión. Usa sentencias print() o pprint() para observar variables o indicar el flujo de ejecución. Si un objeto de juego sin script se comporta de forma extraña, puedes simplemente adjuntarle un script con el único propósito de depurar. Usar cualquiera de las funciones de impresión imprimirá en la vista Console del editor y en el log del juego.
Además de imprimir, el motor también puede dibujar texto de depuración y líneas rectas en la pantalla. Esto se hace enviando mensajes al socket @render:
-- Dibuja el valor de "my_val" con texto de depuración en la pantalla
msg.post("@render:", "draw_text", { text = "My value: " .. my_val, position = vmath.vector3(200, 200, 0) })
-- Dibuja texto con color en la pantalla
local color_green = vmath.vector4(0, 1, 0, 1)
msg.post("@render:", "draw_debug_text", { text = "Custom color", position = vmath.vector3(200, 180, 0), color = color_green })
-- Dibuja una línea de depuración entre player y enemy en la pantalla
local start_p = go.get_position("player")
local end_p = go.get_position("enemy")
local color_red = vmath.vector4(1, 0, 0, 1)
msg.post("@render:", "draw_line", { start_point = start_p, end_point = end_p, color = color_red })
Los mensajes visuales de depuración agregan datos al pipeline de renderizado y se dibujan como parte del pipeline de renderizado normal.
"draw_line" agrega datos que se renderizan con la función render.draw_debug3d() en el script de renderizado."draw_text" se renderiza con /builtins/fonts/debug/always_on_top.font, que usa el material /builtins/fonts/debug/always_on_top_font.material."draw_debug_text" es igual que "draw_text", pero se renderiza con un color personalizado.Ten en cuenta que probablemente querrás actualizar estos datos en cada frame, así que enviar los mensajes en la función update() es una buena idea.
El depurador Lua está disponible en builds nativas de depuración y headless. Usa un motor de la misma versión de Defold que el editor. Las builds release y web no permiten adjuntar el depurador.
Para ejecutar el depurador, selecciona Debug ▸ Start/Attach. Esto inicia el juego con el depurador adjunto o lo adjunta a un juego que ya está en ejecución. Al iniciar un juego para depurarlo, el editor instala los breakpoints activados antes de ejecutar los scripts de inicio, de modo que puedes definir un breakpoint en init() antes del lanzamiento.
Para adjuntarlo a un dispositivo, selecciónalo en Project ▸ Targets y elige Debug ▸ Start/Attach. La conexión pausa la ejecución en la siguiente línea Lua. El editor configura automáticamente la conexión del depurador para los destinos locales y remotos compatibles. Consulta Destinos remotos para conocer los requisitos de conexión o aprende a conectar un depurador externo.

En cuanto el depurador está adjunto, tienes control de la ejecución del juego mediante los botones de control del depurador en la consola, o mediante el menú Debug:


end debajo de la línea con la llamada a la función nextspawn():

El avance paso a paso sigue las líneas del código fuente Lua. Un paso puede volver a la misma línea, por ejemplo al repetirse un bucle, por lo que no siempre avanza a la siguiente línea del archivo.
nextspawn():


Para definir o borrar un breakpoint, haz click en la columna justo a la derecha de los números de línea en el editor de código. También puedes seleccionar Edit ▸ Toggle Breakpoint desde el menú.
Enabled. Los breakpoints desactivados aparecen huecos para indicar que están inactivos.


Para editar la condición del breakpoint, haz click derecho en la columna justo a la derecha de los números de línea en el editor de código, o selecciona Edit ▸ Edit Breakpoint desde el menú.

También puedes cambiar valores mediante asignaciones, por ejemplo self.score = 100 en una entrada donde self esté disponible. El código evaluado tiene los mismos efectos sobre el estado del juego que el código ejecutado por el propio juego.
_G para inspeccionar las variables globales, y las tablas o self para inspeccionar sus campos. El editor conserva las rutas expandidas, la selección y la posición de desplazamiento al avanzar, cambiar de entrada o actualizar tras una evaluación, mientras obtiene los valores actuales.El motor proporciona un servidor nativo de Debug Adapter Protocol (DAP) a través de TCP. Para usar un cliente DAP externo, inicia el listener en un motor nativo de Defold de depuración o headless y conecta el cliente a la dirección y el puerto del motor. El editor configura automáticamente el listener cuando usas Debug ▸ Start/Attach.
El editor actual no puede conectarse a motores antiguos que solo admiten MobDebug. En las versiones actuales no se necesita ni está disponible la llamada require "builtins.scripts.mobdebug".
Primero crea una build de tu proyecto. Desde el directorio del proyecto que contiene build/default/game.projectc, ejecuta el motor nativo de depuración con estos valores de configuración al iniciar:
dmengine --config=debugger.enabled=1 \
--config=debugger.port=8172 --config=debugger.wait=1
Conecta tu cliente DAP a 127.0.0.1:8172. El motor espera a que el cliente configure los breakpoints antes de ejecutar los scripts de inicio.
| Ajuste | Valor predeterminado | Propósito |
|---|---|---|
debugger.enabled |
0 |
Establécelo en 1 para iniciar el listener al arrancar el motor. |
debugger.address |
127.0.0.1 |
Dirección IPv4 en la que se escuchan conexiones. El valor predeterminado acepta conexiones desde la misma computadora. |
debugger.port |
8172 |
Puerto TCP de escucha. Usa 0 para seleccionar un puerto disponible. |
debugger.wait |
0 |
Establécelo en 1 para esperar a que el cliente del depurador configure la sesión antes de ejecutar los scripts de inicio. |
También puedes agregar estos valores a la sección Debugger de game.project. El editor configura automáticamente el listener para Debug ▸ Start/Attach, por lo que solo necesitas configurarlo manualmente cuando lo inicias por tu cuenta.
El log del motor indica la dirección y el puerto seleccionados. Con debugger.wait=0, el juego se inicia inmediatamente y puedes adjuntar el depurador después. Con debugger.wait=1, espera hasta que el cliente termine de configurar la sesión, incluidos los breakpoints. En los lanzamientos locales de depuración, el editor selecciona automáticamente un puerto disponible.
Al desconectar un cliente se reanuda la ejecución y el listener queda disponible para otra conexión. Desconectar mientras se espera la configuración de inicio también libera al motor. Si el listener no puede iniciarse, el motor registra el error y continúa arrancando; puedes reintentarlo desde Lua con debugger.start(0) para seleccionar un puerto disponible.
Para activar el listener desde un script sin reiniciar el juego:
if debugger then
local port = debugger.start(0)
print("DAP listener port:", port)
end
debugger.start([port [, address]]) devuelve inmediatamente el puerto de escucha. No espera a un cliente ni pausa el juego. Los argumentos omitidos usan debugger.port y debugger.address; pasar 0 selecciona un puerto disponible. Las llamadas sucesivas devuelven el puerto del listener existente y no cambian su dirección ni su puerto. Los motores nativos de depuración y headless proporcionan el módulo debugger.
El puerto debe ser un entero entre 0 y 65535. Pasa nil como primer argumento para cambiar solo la dirección. Los argumentos no válidos o un fallo al vincular el listener generan un error Lua.
Para conectar directamente desde otra computadora, vincula el listener a la interfaz IPv4 del dispositivo o a 0.0.0.0 (todas las interfaces IPv4). Por ejemplo, usa debugger.start(8172, "0.0.0.0") o agrega --config=debugger.address=0.0.0.0 al comando de inicio anterior. Conecta el cliente a la dirección IP real del dispositivo y permite el acceso TCP al puerto de escucha. 0.0.0.0 es una dirección de vinculación, no la dirección que debes introducir en el cliente.
El editor Defold solicita esta vinculación remota automáticamente y usa el puerto 8172 + project.instance_index para destinos remotos. No puede descubrir un puerto remoto seleccionado dinámicamente. Si ya iniciaste el listener remoto en localhost o en otro puerto, reinicia el motor antes de adjuntarlo desde el editor.
El depurador puede evaluar Lua y no tiene autenticación. Activa el acceso remoto únicamente en una red de desarrollo de confianza.
Usa un cliente que permita adjuntarse directamente a un servidor DAP por TCP. Configura su correspondencia de archivos fuente con la carpeta que contiene game.project (el argumento DAP localRoot de attach). Inicia primero el listener del motor y después adjunta el cliente.
Instala la extensión Lua Debug (actboy168.lua-debug), abre en VS Code la carpeta que contiene game.project y agrega esta configuración a .vscode/launch.json:
{
"version": "0.2.0",
"configurations": [
{
"name": "Attach to Defold Lua",
"type": "lua",
"request": "attach",
"address": "127.0.0.1:8172",
"debugServer": 8172,
"localRoot": "${workspaceFolder}",
"stopOnEntry": false
}
]
}
Si VS Code abre un archivo .script, .gui_script o .render_script como texto sin formato, selecciona Lua en el indicador de lenguaje de la barra de estado antes de definir breakpoints.
Define un breakpoint, por ejemplo en la función init() de un script. Inicia el motor con el comando de inicio anterior y selecciona Attach to Defold Lua en la vista Run and Debug de VS Code. Con debugger.wait=1, el motor ejecuta los scripts de inicio después de que el cliente instale los breakpoints. Establece stopOnEntry en true si también quieres pausar en la siguiente línea Lua después de adjuntarlo.
El ajuste debugServer de VS Code conecta directamente con el listener TCP local del motor. El campo address es obligatorio en la configuración de attach de la extensión Lua Debug. Si cambias el puerto de escucha, actualiza ambos campos. localRoot debe apuntar a la carpeta del proyecto para que el cliente pueda asociar los nombres de código fuente Lua del motor con tus archivos.
Para un motor remoto, reenvía su puerto DAP a localhost y coloca el puerto reenviado en ambos campos, o usa un cliente DAP que se conecte directamente al host remoto.

Cuando trabajas con múltiples breakpoints en distintos scripts, la pestaña Breakpoints proporciona una vista centralizada para gestionar todos tus breakpoints en un solo lugar.
Para trabajar con breakpoints individuales:
Selecciona múltiples breakpoints usando Ctrl/Cmd+click o Shift+click, y luego haz click derecho para realizar acciones en bloque. Puedes editar condiciones en varios breakpoints simultáneamente, alternar su estado activo o eliminarlos por completo.
Los botones de la barra de herramientas te permiten activar, desactivar o alternar todos los breakpoints a la vez, lo que es útil cuando quieres ejecutar tu juego sin detenerte, pero no quieres perder sus posiciones. También puedes eliminarlos todos cuando termines tu sesión de depuración.
Lua viene con una biblioteca debug que resulta útil en algunas situaciones, especialmente si necesitas inspeccionar los detalles internos de tu entorno Lua. Puedes encontrar más información sobre ella en el capítulo sobre la Debug Library en el manual de Lua.
Si encuentras un error o si tu juego no se comporta como esperabas, aquí tienes un checklist de depuración:
Revisa la salida de la consola y verifica que no haya errores de runtime.
Agrega sentencias print a tu código para verificar que el código realmente se está ejecutando.
Si no se está ejecutando, comprueba que hayas hecho la configuración adecuada en el editor requerida para que el código se ejecute. ¿El script está agregado al objeto de juego correcto? ¿Tu script ha adquirido foco de input? ¿Los input-triggers son correctos? ¿El código del shader está agregado al material? Etc.
Si tu código depende de los valores de variables (en una sentencia if, por ejemplo), usa print con esos valores donde se usan o se comprueban, o inspecciónalos con el depurador.
A veces encontrar un bug puede ser un proceso difícil y lento, que requiere recorrer tu código poco a poco, revisar todo, acotar el código defectuoso y eliminar fuentes de error. Esto se hace mejor con un método llamado “divide y vencerás”:
¡Buena caza!
Si tienes problemas con físicas y las colisiones no funcionan como se esperaba, se recomienda activar la depuración de físicas. Marca la casilla Debug en la sección Physics del archivo game.project:

Cuando esta casilla está marcada, Defold dibujará todas las formas de colisión y los puntos de contacto de las colisiones:
