> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/depuracion/troubleshooting.md). # Solución de problemas Soluciones para problemas comunes ## Depura con un asistente de IA Antes de profundizar en los problemas siguientes, considera pasarle el problema a un asistente de IA, como el chat de Cursor, GitHub Copilot o Claude Code. Pega el mensaje de error de la consola, o describe qué no está funcionando como se espera, y normalmente puede encontrar el problema en el código de tu scene y corregirlo por ti. Para obtener buenos resultados, asegúrate de que el asistente de IA tenga instaladas las skills de Decentraland SDK. Las skills le enseñan los patrones y restricciones del SDK, para que no adivine basándose en información genérica o desactualizada. Instálalas ejecutando este comando en el proyecto de tu scene: ```bash npx skills add decentraland/sdk-skills ``` Consulta [Vibe Coding con IA](/creator/content-creator-es/scenes-sdk7/primeros-pasos/vibe-coding.md) para obtener más detalles sobre la configuración y cómo hacer prompts a asistentes de IA. También puedes dejar que la IA depure la scene *mientras se está ejecutando*. El cliente de escritorio de Decentraland puede exponer un servidor MCP que permite a un agente tomar sus propias capturas de pantalla, leer la salida de la consola de la scene, mover al player por el entorno y hacer clic en objetos, así que en vez de que reproduzcas el bug y pegues el error, el agente lo reproduce por sí mismo, ve qué ocurre e itera hasta que se corrige. Inicia la scene con `npm run start -- --mcp` y conecta tu agente a él. Consulta [Deja que la IA vea tu scene en el mundo](/creator/content-creator-es/scenes-sdk7/primeros-pasos/vibe-coding.md#let-the-ai-see-your-scene-in-world) para ver la configuración completa, e instala la `unity-explorer-mcp` skill para que el agente conozca el flujo de trabajo: ```bash npx skills add decentraland/sdk-skills --skill unity-explorer-mcp ``` ## Problemas al ejecutar el preview #### Problema: No puedo ejecutar ningún preview de la scene, el mensaje de error menciona **Permissions denied** ni **EACCES** Tu sistema operativo no te permite editar los permisos de la carpeta donde quieres ejecutar el proyecto. Al ejecutar la scene, algunas dependencias necesitan instalarse, pero está prohibido. Debes configurar los permisos de la carpeta para permitir que tu cuenta de usuario de Windows/Mac/Linux edite los archivos en ella. Recursos útiles: * [docs.npmjs](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) * [letscodepare](https://letscodepare.com/blog/npm-resolving-eacces-permissions-denied) #### Problema: No puedo ejecutar un preview concreto de la scene, el error dice **Error: Error al compilar el proyecto** Si estás ejecutando una scene que compartieron contigo, asegúrate de que esta scene no se haya compartido incluyendo una `node_modules` ni `bin` carpeta, o un `package-lock.json` archivo. Estos archivos contienen dependencias que usan versiones específicas para tu sistema operativo y tu máquina, y deberían generarse al ejecutar la scene por primera vez. Elimina manualmente estas carpetas y este archivo, y luego ejecuta `npm run start` de nuevo. #### Problema: Ejecutar `npm run start` se ejecuta, no hay mensaje de error, pero no se abre ninguna ventana del navegador y no aparece ninguna URL en la salida para abrir el preview Asegúrate de que tu versión de Node esté actualizada. Debe ser 20 o superior. #### Problema: Ejecutar `npm run start` abre una pestaña del navegador, pero la pantalla de carga nunca termina de cargarse, o veo un banner rojo de error que dice "critical error". * Asegúrate de tener instalada en tu proyecto la versión más reciente del Decentraland SDK. Ejecuta: `npm i @dcl/sdk@latest` #### Problema: La scene se ejecuta, en la consola veo `dependencias cíclicas` advertencias. Esto se refiere a archivos de tu scene que se referencian entre sí mutuamente. Esto no necesariamente es un problema, pero no es un patrón recomendable para escribir software, ya que puede generar condiciones de carrera difíciles de depurar y otros problemas. Es probable que tu scene funcione bien a pesar de estas advertencias. Idealmente, la carga del código de tu scene debería seguir un orden secuencial claro. El código que tiene dependencias cíclicas puede sufrir el problema del huevo y la gallina, donde el compilador no sabe cuál iniciar primero. A menudo esto se resuelve sin problemas, pero es una buena práctica evitarlo. Para corregir estas dependencias, a menudo tendrás que recurrir a llamar funciones o constructores de objetos pasando referencias a entities/objects ya instanciados en los argumentos de la función; en lugar de codificar referencias a estas entities/objects en la función, que pueden o no estar ya instanciadas. ## Problemas al desplegar #### Problema: No tienes permisos para desplegar en estos parcels * Asegúrate de que el `scene.json` archivo de tu scene enumera correctamente las coordenadas donde quieres desplegar. * Asegúrate de que Metamask esté correctamente configurado para usar el wallet correcto para firmar la transacción. Este puede ser el wallet que posee los tokens LAND, o puede tener permisos de operador otorgados por el propietario. #### Problema: Ejecutar `npm run deploy` falla * Comprueba los spawn points de tu scene; las tres coordenadas x, y, z de un spawn point deben ser o bien un número o bien un rango. O las tres son números o las tres son rangos. No se admite tener rangos para unas y números para otras. Por ejemplo, esto no está admitido: `"position": {"x": [1,4], "y": 0, "z": [1,4]}` Esto sí está admitido: `"position": {"x": [1,4], "y": [0,0], "z": [1,4]}` * El servidor catalyst predeterminado al que te asignan para desplegar puede estar caído o tener problemas. Puedes forzar el `npm run deploy` comando para desplegar en un servidor catalyst específico en su lugar. Para desplegar en un servidor específico en el Decentraland Editor: 1. Abre tu scene y haz clic en **Publish** 2. Selecciona la opción **Publicar en un servidor diferente** de abajo. 3. En el dropdown, selecciona **Custom Server** 4. Introduce la dirección del servidor, por ejemplo `peer-ec1.decentraland.org` 5. Haz clic en **Publicar en servidor personalizado** 6. Aprueba la transacción como en un despliegue normal. Para hacerlo mediante la CLI: `npm run deploy -- --target-content ` Por ejemplo: `npm run deploy -- --target-content peer-ec1.decentraland.org` Consulta [catalyst-monitor](https://decentraland.github.io/catalyst-monitor/) para comprobar el estado de todos los servidores de la red catalyst. También puedes copiar las direcciones de cada uno, desde la parte superior de cada card. * Comprueba el `package.json`. Un problema común es que haya una `bundleDependencies` y también una `bundledDependencies` (con una d extra) sección. Esto a veces puede deberse a ejecutar distintas versiones de Node en el mismo proyecto en momentos diferentes, o a compartir el proyecto entre personas que lo ejecutaron con diferentes versiones de Node instaladas. Elimina `bundleDependencies`que está relacionado con versiones antiguas de Node. Asegúrate también de tener tu versión de Node actualizada, al menos la versión 20. #### Problema: Ejecutar `npm run deploy` ni `npm run build` reporta errores de tipo Es posible que tu scene tenga errores de tipo reportados por TypeScript, por ejemplo que indique que una variable determinada podría ser de tipo `any` o que `undefined` ni `null` no se permiten. Al ejecutar `npm run deploy`, también ejecuta `npm run build`, que es un poco más estricto con estas comprobaciones que `npm run start`. A diferencia de JavaScript, TypeScript aplica tipado estricto a todas las variables. Aunque tu scene esté escrita de tal manera que, por ejemplo, un cierto valor nunca vaya a ser `undefined`undefined, TypeScript necesita saber qué pasaría en ese escenario, o debes aclarar explícitamente que el valor solo puede ser, por ejemplo, una string. Como alternativa, puedes ejecutar `npm run deploy -- --skip-build` para omitir la ejecución de `npm run build`, y evitar que se ejecuten estas comprobaciones. #### Problema: He desplegado mi scene pero no veo los cambios cuando entro en Decentraland * Ten en cuenta que puede tardar unos minutos si la scene contiene assets pesados. * Mientras los 3D models de la nueva versión se convierten en asset bundles, a los players se les sirve deliberadamente la última versión de tu scene que funciona completamente. Esto suele tardar solo unos segundos, pero puede tardar más en scenes muy grandes o cuando los servers están ocupados. Puedes [comprobar el estado de conversión](/creator/content-creator-es/scene-editor/publish/publish-scene.md#check-the-conversion-status) de tu scene directamente. * Recargar la scene no es suficiente para obtener una nueva versión: una recarga reinicia el código de la scene, pero no descarga la versión recién publicada. Una vez que la conversión se complete, cierra Decentraland por completo y vuelve a abrirlo, luego entra de nuevo en la scene mediante un enlace de salto o el `/goto` comando de chat. #### Problema: Algunos players ven la nueva versión de mi scene, otros siguen viendo la antigua La conversión de los 3D models de tu scene termina en momentos distintos para cada plataforma (Windows y Mac), y el cliente de cada player también mantiene una caché local. Para comprobar si la conversión está lista para todas las plataformas, [comprobar el estado de conversión](/creator/content-creator-es/scene-editor/publish/publish-scene.md#check-the-conversion-status) y compara los `windows` y `mac` valores debajo de `assetBundles`. Una vez que ambos estén `complete`, pide a los players afectados que cierren Decentraland por completo y lo vuelvan a abrir. #### Problema: La publicación se queda atascada en la etapa Converting, el botón Jump In nunca aparece Tu scene está en cola detrás de otras scenes que se están convirtiendo, o la conversión falló. * Abrir `https://asset-bundle-registry.decentraland.org/queues/status` y busca el ID de entity de tu scene. Puedes encontrar ese ID en el `entityId` campo cuando [comprobar el estado de conversión](/creator/content-creator-es/scene-editor/publish/publish-scene.md#check-the-conversion-status) usas las coordenadas de tu scene. Si tu ID aparece en la cola, la scene está en cola y solo tienes que esperar. * Si no está en la cola, [comprobar el estado de conversión](/creator/content-creator-es/scene-editor/publish/publish-scene.md#check-the-conversion-status) de tu scene. `falló`, vuelve a publicar la scene. [reporta el problema](/creator/content-creator-es/scenes-sdk7/depuracion/report-bug.md) e incluye el ID de entity. #### Problema: Una vez desplegada, faltan algunos 3D models, aparecen negros o sin textura * Si acabas de publicar, la conversión de tus models a asset bundles quizá aún no haya terminado. Escribe `/detectabs` en la ventana de chat: los models teñidos de rojo aún no se han convertido. [Comprueba el estado de la conversión](/creator/content-creator-es/scene-editor/publish/publish-scene.md#check-the-conversion-status) y espera a que termine. * Asegúrate de que los 3D models estén todos dentro de los límites de la scene, incluso sus cajas delimitadoras. Si alguna parte de tus models se extiende más allá de estos límites al ejecutar un preview, esas partes extendidas se recortarán y no se renderizarán, tanto al ejecutar un preview como en la scene publicada. * Si las textures son el problema, ten en cuenta que las textures de los 3D models están limitadas a un tamaño máximo de 1024x1024 píxeles durante la conversión. #### Problema: La scene se ve bien de cerca, pero está rota o falta contenido cuando se ve desde lejos Las versiones de bajo Level of Detail (LOD) de tus assets, usadas para renderizar la scene desde lejos, se generan en la última etapa de la publicación y puede que aún no hayan terminado. Esto no bloquea probar tu scene de cerca. [Comprueba el estado de la conversión](/creator/content-creator-es/scene-editor/publish/publish-scene.md#check-the-conversion-status) y mira los valores de `lods`, o simplemente espera y vuelve a comprobarlo más tarde. #### Problema: Una vez desplegada, mis 3D models se ven diferentes * Si las textures se ven diferentes, ten en cuenta que las textures de los 3D models están limitadas a un tamaño máximo de 1024x1024 píxeles. Esta conversión se realiza para garantizar que Decentraland funcione sin problemas para todos. * Si los models se ven diferentes, podría haber un problema con la conversión de los models a asset bundles. Lee más sobre la compresión de asset bundles [aquí](/creator/content-creator-es/scenes-sdk7/optimizing/performance-optimization.md#asset-bundle-conversion). Para validarlo, prueba a ejecutar la scene con el parámetro de URL `&DISABLE_ASSET_BUNDLES`. Si los models se ven bien con este indicador, el problema debe estar relacionado con un bug en la conversión del model. En ese caso, [reporta el problema](/creator/content-creator-es/scenes-sdk7/depuracion/report-bug.md) reporta el problema e incluye el ID de entity de tu deployment. Ten en cuenta que la generación de versiones comprimidas de asset-bundle de tus models tarda un poco en los servers (normalmente unos minutos, más tiempo para scenes muy grandes o cuando los servers están ocupados). Puedes comprobar si los models se están cargando como asset bundles comprimidos o no escribiendo el siguiente comando en la ventana de chat `/detectabs`. Los models comprimidos se tiñen de verde, los no comprimidos se tiñen de rojo. También puedes reproducir esta conversión localmente antes de publicar, activando [los optimized assets en el preview](/creator/content-creator-es/scenes-sdk7/primeros-pasos/preview-scene.md#preview-with-optimized-assets). Esto te permite detectar y depurar estos problemas sin tener que desplegar la scene. #### Problema: Mi scene desapareció por completo * Si la scene está en un World: tu presupuesto de almacenamiento de Worlds puede haberse superado, por ejemplo después de vender o transferir NAMEs, LAND o MANA. Tienes 48 horas para liberar espacio o aumentar tu presupuesto antes de que tus Worlds queden inaccesibles. Comprueba tu presupuesto en la **Manage** pestaña del Creator Hub o en la **Worlds** del [Builder](https://decentraland.org/builder/worlds), luego vuelve a publicar. Consulta [límites de tamaño de Worlds](/creator/content-creator-es/scenes-sdk7/tipos-de-proyectos/kinds-of-project.md#size-limits). * Si la scene está en LAND: alguien con permisos de deploy puede haber publicado una nueva scene sobre tus parcels, lo que borra el contenido anterior. Consulta [sobrescritura de scene](/creator/content-creator-es/scenes-sdk7/publicacion/publishing.md#scene-overwriting). * En casos raros, el contenido que infringe la política de contenido de Decentraland puede incluirse en una denylist de los content servers. Si crees que esto sucedió por error, ponte en contacto a través del [Discord de Decentraland](https://decentraland.org/discord). #### Problema: Mi scene tiene un FPS bajo en producción, aunque en preview funciona sin problemas. El rendimiento de tu scene podría verse afectado por scenes vecinas que siguen malas prácticas, ya que también se ejecutan en paralelo. Puedes validar que este es el caso abriendo los ajustes y poniendo la línea de visión al mínimo, de modo que solo se cargue 1 parcel alrededor de tu scene actual. Puedes reducir aún más la línea de visión ejecutando tu scene con el parámetro `&LOS=0`, para no cargar ninguna scene circundante en absoluto. Si acabas de desplegar tu scene, la carga al cargar la scene también podría reducirse una vez que los servers conviertan los 3D models de la scene en compressed asset bundles. Puedes comprobar si los models se están cargando como compressed asset bundles o no escribiendo el siguiente comando en la ventana de chat `/detectabs`. Los models comprimidos se tiñen de verde, los no comprimidos se tiñen de rojo. ### Reportar un bug Si encuentras un problema que no esté en tu scene, sino con el Decentraland SDK en general, consulta [Reportar un bug](/creator/content-creator-es/scenes-sdk7/depuracion/report-bug.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/depuracion/troubleshooting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.