> 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/escenas-sdk7/primeros-pasos/coding-scenes.md). # Fundamentos de código ## Las herramientas de desarrollo A muy alto nivel, el Decentraland **Kit de desarrollo de software** (SDK) te permite hacer lo siguiente: * Generar un proyecto predeterminado *proyecto* que contiene una escena de Decentraland, incluyendo todos los activos necesarios para renderizar y ejecutar tu contenido. * Construye, prueba y previsualiza el contenido de tu escena localmente en tu navegador web - completamente offline, y sin tener que realizar transacciones de Ethereum ni poseer LAND. * Escribe código TypeScript usando la API de Decentraland para añadir comportamiento interactivo y dinámico a la escena. * Sube el contenido de tu escena al servidor de contenido. * Vincula tus tokens LAND a la URL del contenido que has subido. Nuestro SDK incluye lo siguiente: * **El Creator Hub**: Una aplicación independiente que, entre otras cosas, te permite crear escenas con una interfaz fácil de arrastrar y soltar. Puedes ejecutar vistas previas, depurar, editar código y publicar. [Leer más](/creator/content-creator-es/scene-editor/empezar/about-editor.md) * **El ECS de Decentraland**: Un paquete de TypeScript que contiene el framework de métodos auxiliares que te permite crear experiencias interactivas. Úsalo para crear y manipular objetos en la escena y también para facilitar transacciones in-world entre players u otras aplicaciones. ( [referencia más reciente de ECS](https://github.com/decentraland/ecs-reference/blob/master/docs-latest/decentraland-ecs.md)) * **Ejemplos de escenas**: Inspírate y toma buenas prácticas de programación de los [ejemplos de escenas](https://studios.decentraland.org/resources?sdk_version=SDK7). Otras herramientas heredadas: * **El Web Editor**: Una herramienta web para crear escenas simples y publicarlas. ## Requisitos Para desarrollar una escena localmente, no necesitas poseer tokens LAND. Desarrollar y probar una escena puede hacerse completamente offline, sin necesidad de desplegar una escena en la red de Ethereum (el sistema que Decentraland usa para establecer la propiedad de LAND, de un Decentraland Name), o en el servidor de contenido. Debes tener: * **El Creator Hub**: Una aplicación independiente que, entre otras cosas, te permite crear escenas con una interfaz fácil de arrastrar y soltar. Puedes ejecutar vistas previas, depurar, editar código y publicar. [Leer más](/creator/content-creator-es/scene-editor/empezar/about-editor.md). Si planeas editar el código de la escena, también necesitarás instalar uno de los siguientes: * VS Code **Visual Studio Code**: Descárgalo [aquí](https://code.visualstudio.com/). Te ayuda a escribir código mucho más rápido y con menos errores. Un editor de código fuente marca los errores de sintaxis, autocompleta mientras escribes e incluso muestra sugerencias inteligentes que dependen del contexto en el que estés. También puedes hacer clic en un objeto del código para ver la definición completa de su clase y qué atributos admite. * Cursor **Cursor AI**: Descárgalo [aquí](https://www.cursor.com/). Un potente editor de código integrado con IA. Te permite elegir distintos modelos de IA para ayudarte a escribir código; todos son gratuitos. El asistente de IA no solo autocompleta mientras escribes, también puedes pedirle que refactorice una gran base de código, escriba documentación y más. {% hint style="info" %} **💡 Consejo**: Puedes usar asistentes de IA como Cursor, OpenDCL o Claude Code para construir escenas completas a partir de descripciones en lenguaje natural — no se requiere experiencia con TypeScript. Consulta [Vibe Coding con IA](/creator/content-creator-es/escenas-sdk7/primeros-pasos/vibe-coding.md) para empezar. {% endhint %} ## Lenguajes y sintaxis compatibles Decentraland emplea [TypeScript (.ts)](https://www.typescriptlang.org/docs/handbook/jsx.html) como lenguaje predeterminado para escribir escenas. TypeScript es un superconjunto de JavaScript, así que si estás familiarizado con JavaScript verás que es casi lo mismo, pero TypeScript incluye declaraciones de tipos. Gracias a las declaraciones de tipos, es posible tener funciones como autocompletado y mejores pistas de depuración; esto acelera los tiempos de desarrollo y permite crear una base de código más sólida. Estas funciones son componentes clave de una buena experiencia de desarrollo. Cuando se construye una escena, el código TypeScript que escribiste se compila a JavaScript minificado, para hacerlo más ligero. El código fuente original en TypeScript nunca se sube a los servidores; solo la versión JavaScript compilada. ### Otros lenguajes Puedes usar otra herramienta o lenguaje en lugar de TypeScript y compilarlo a JavaScript, siempre que tus scripts compilados estén contenidos dentro de un único archivo JavaScript que coincida con la ruta establecida en el `main` campo de tu `scene.json` archivo de la escena (por defecto *bin/index.js*). Todas las declaraciones de tipos proporcionadas están hechas en TypeScript, y otros lenguajes y transpilers no cuentan con soporte oficial. ## Escenas El contenido que despliegas en tu LAND se llama una **escena**. Una escena es un programa interactivo que renderiza contenido 3D; esto podría ser un juego, una experiencia interactiva, una galería de arte, ¡lo que quieras! Las escenas se despliegan en LAND virtual en Decentraland. LAND es un activo escaso y no fungible mantenido en un smart contract de Ethereum. Despliega en una sola **parcela**, un terreno de LAND de 16 metros por 16 metros, o en varias parcelas adyacentes. Cuando los players visitan Decentraland, descargan y renderizan el contenido de cada escena mientras recorren el mapa. Descargan las escenas cuando se alejan de ellas. También puedes ejecutar una escena localmente en tu máquina ejecutando una vista previa desde la CLI. ## Entities y Components Las escenas tridimensionales en Decentraland se basan en una [Entity-Component-System](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system) arquitectura, donde todo en una escena es una *entity*. Las Entities tienen *components*, cada component le da a la entity a la que pertenece propiedades específicas. Es probable que una entity de puerta tenga al menos un component Transform (que establece posición, rotación y escala) y otro para proporcionarle una forma. Los Components son solo un lugar para almacenar datos; no realizan ninguna acción por sí mismos. ![](/files/1670efc3f57b506ad4572b6212276c648ecf2ccd) ```ts export function main() { // Crear un entity const door = engine.addEntity() // Darle al entity una posición mediante un component Transform Transform.create(door, { position: Vector3.create(5, 1, 5), }) // Darle al entity una forma visible mediante un component GltfContainer GltfContainer.create(door, { src: 'assets/models/door.glb', }) } ``` Entities pueden anidarse dentro de otras entities para formar una estructura de árbol. Si estás familiarizado con el desarrollo web, puede resultarte útil pensar en las entities como elementos en un árbol DOM y en los components como los atributos de cada uno de estos elementos. ![](/files/23a5a8556ff44aaca10d20c42984b50f36545808) Las Entities son un concepto abstracto. Una entity es solo un id, que se usa como referencia para agrupar distintos Components. Consulta [Entities y Components](/creator/content-creator-es/escenas-sdk7/arquitectura/entities-components.md) para una mirada en profundidad a ambos conceptos y a cómo los usan las escenas de Decentraland. ### Custom Components El conjunto predeterminado de Components (como `Transform`, `GltfContainer`, `Material`, etc.) es interpretado por el engine y tiene consecuencias directas en cómo se verá la entity, su posición, si emite sonidos, etc. También puedes definir *custom components* Components personalizados para almacenar datos que podrían ser útiles para las mecánicas de tu escena. El engine no sabrá cómo interpretar lo que significan los valores de estos Components, ni tendrán consecuencias directas en cómo se renderiza la escena. Sin embargo, puedes escribir lógica en el código de tu escena para supervisar estos valores y responder a ellos. Por ejemplo, puedes definir un component personalizado "doorState" para seguir el estado abierto/cerrado de la puerta. En este caso, el component no es más que un lugar para almacenar un valor que lleva el control de este estado. Para ver la puerta abrirse y cerrarse en tu escena, luego tienes que implementar por separado la lógica que usa estos valores para afectar la rotación de la puerta, un valor del `Transform` component que el engine sí sabe interpretar. Consulta [Components personalizados](/creator/content-creator-es/escenas-sdk7/arquitectura/custom-components.md) para más información. ### Obtener entities por nombre A las entities añadidas mediante arrastrar y soltar en el Scene Editor de Creator Hub también se puede acceder mediante código para editarlas más y añadirles comportamiento. Usa `engine.getEntityOrNullByName()` para obtener una entity, pasando el nombre asignado a la entity en la UI del Scene Editor. Cada una debería tener un nombre único. ```ts function main() { const door = engine.getEntityOrNullByName('door3') } ``` Luego puedes hacer lo que quieras con esa entity, como añadir nuevos Components, modificar sus Components existentes, duplicarla o eliminarla. Consulta [Obtener entity por nombre](/creator/content-creator-es/escenas-sdk7/arquitectura/entities-components.md#get-an-entity-by-name) para más información. Si la entity es un [Smart item](/creator/content-creator-es/scene-editor/interactividad/smart-items.md), también puedes llamar a su **Actions** o suscribirte a su **Triggers** mediante código. Consulta [Elementos de referencia](/creator/content-creator-es/scene-editor/extender-con-codigo/reference-items.md). ## Systems Entities y components son lugares para almacenar información sobre los objetos de una escena. *Systems* contienen funciones que cambian la información almacenada en Components con el tiempo. Los Systems son donde implementamos la lógica del juego; realizan las acciones que necesitan actualizarse o comprobarse periódicamente en cada tick del game loop. Un System es una función pura y simple que se llama una vez en cada tick (hasta 30 veces por segundo), siguiendo el [*patrón de actualización*](http://gameprogrammingpatterns.com/update-method.html). ```ts // System básico function mySystem() { console.log('mi System está ejecutándose') } engine.addSystem(mySystem) // System con dt function mySystemDT(dt: number) { console.log('tiempo transcurrido desde el último frame: ', dt) } engine.addSystem(mySystemDT) ``` Una sola escena puede tener 0 o muchos Systems ejecutándose al mismo tiempo. Los Systems pueden encenderse o apagarse en distintos momentos durante la duración de la escena. En general, es una buena práctica mantener comportamientos independientes en Systems separados. Consulta [Systems](/creator/content-creator-es/escenas-sdk7/arquitectura/systems.md) para más detalles sobre cómo se usan los Systems en una escena. ### El bucle del juego El [bucle del juego](http://gameprogrammingpatterns.com/game-loop.html) es la columna vertebral del código de una escena de Decentraland. Recorre una parte del código a intervalos regulares y hace lo siguiente: * Escuchar la entrada del player * Actualizar la escena * Volver a renderizar la escena En la mayoría de los programas de software tradicionales, todos los eventos se desencadenan directamente por las acciones del player. Nada en el estado del programa cambiará hasta que el player haga clic en un botón, abra un menú, etc. Pero los entornos interactivos y los juegos son diferentes a eso. No todos los cambios en la escena son necesariamente causados por las acciones de un player. Tu escena podría tener objetos animados que se mueven por su cuenta o incluso personajes no jugadores con su propia IA. Algunas acciones del player también pueden requerir varios ticks para completarse; por ejemplo, si la apertura de una puerta necesita durar un segundo completo, la rotación de la puerta debe actualizarse incrementalmente unas 30 veces mientras se mueve. Llamamos a cada iteración sobre el loop un *tick*. Las escenas de Decentraland se renderizan a 30 ticks por segundo, siempre que sea posible. Si la máquina tiene dificultades para renderizar cada tick, puede resultar en actualizaciones menos frecuentes. En cada tick, la escena se actualiza; luego la escena se vuelve a renderizar, en función de los valores actualizados. En las escenas de Decentraland, no hay un game loop declarado explícitamente, sino que los [Systems](/creator/content-creator-es/escenas-sdk7/arquitectura/systems.md) Systems de la escena conforman el game loop. La compilación y el renderizado de la escena se realizan en el backend; no necesitas encargarte de eso mientras desarrollas tu escena. ## Consulta de components Puedes [consultar components](/creator/content-creator-es/escenas-sdk7/arquitectura/querying-components.md) con el método `engine.getEntitiesWith(...components)` para llevar un seguimiento de todas las entities en la scene que tengan ciertos components. A menudo tiene sentido consultar components dentro de un [system](/creator/content-creator-es/escenas-sdk7/arquitectura/systems.md)System , para luego recorrer cada una de las entities devueltas y realizar el mismo conjunto de acciones en cada una. ```ts // Define un System function boxHeightSystem(dt: number) { // consulta las entities que incluyen tanto MeshRenderer como Transform components for (const [entity] of engine.getEntitiesWith(MeshRenderer, Transform)) { const transform = Transform.get(entity) console.log('una caja está a esta altura: ', transform.position.y) } } // Añade el System al engine engine.addSystem(boxHeightSystem) ``` ## Ciclo de vida de la Scene Si empiezas a escribir líneas sueltas de código directamente en `index.ts`, tu código puede carecer de algún contexto importante. Por ejemplo, te faltará información sobre el PlayerEntity, o sobre entities que fueron añadidas mediante arrastrar y soltar en el Creator Hub. En el momento en que se leen tus líneas de código, esas cosas todavía no se han cargado. Para evitar ese escenario, siempre se recomienda escribir el código de carga inicial de tu escena usando la `main()` función (en el `index.ts` archivo) como punto de entrada. Esta función solo se ejecuta después de que todo el contexto inicial de la escena ya está cargado; esto incluye cualquier cosa añadida mediante la UI del Scene Editor. Puedes escribir tu código fuera de la `main()` función cuando: * El código es llamado indirectamente por `main()` * El código define un System, o añade un System al engine * El código está dentro de una [función async](/creator/content-creator-es/escenas-sdk7/patrones-de-programacion/async-functions.md) {% hint style="warning" %} **📔 Nota**: Para cuando el código dentro de una función async o un System se ejecuta por primera vez, todo en la escena ya está correctamente inicializado. [Custom Component](/creator/content-creator-es/escenas-sdk7/arquitectura/custom-components.md) las definiciones son una excepción; estas siempre deben escribirse fuera de la `main()` función, en un archivo separado. Necesitan ser interpretadas antes de que `main()` se ejecute. {% endhint %} ## Mutabilidad Puedes elegir trabajar con versiones mutables o inmutables (de solo lectura) de un component. La `.get()` función en un component devuelve una versión inmutable del component. Solo puedes leer sus valores, pero no cambiar ninguna de sus propiedades. El `.getMutable()` función devuelve una representación del component que te permite cambiar sus valores. Usa versiones mutables solo cuando planees hacer cambios a un component. Trabajar con versiones inmutables de Components resulta en una enorme mejora en rendimiento. ```ts // obtener una versión inmutable (solo lectura) const immutableTransform = Transform.get(myEntity) // lo siguiente NO funciona: // \timmutableTransform.position.y = 2 const mutableTransform = Transform.getMutable(myEntity) // lo siguiente SÍ cambia la posición de la entity mutableTransform.position.y = 2 ``` Consulta [mutable data](/creator/content-creator-es/escenas-sdk7/patrones-de-programacion/mutable-data.md) para ver más detalles. ## Uniéndolo todo El *engine* es lo que está entre *entities*, y *components* por un lado y *systems* por el otro. ![](/files/2d53d91bbcb09a914c9129e7842b19e99a15e11b) Todos los valores almacenados en los Components de la escena representan el estado de la escena en ese momento. Con cada tick del game loop, el engine ejecuta las funciones de cada uno de los Systems para actualizar los valores almacenados en los Components. Después de que se ejecuten todos los Systems, los Components de cada entity tendrán nuevos valores. Cuando el engine renderiza la escena, usará estos nuevos valores actualizados y los players verán cómo las entities cambian para coincidir con sus nuevos estados. ```ts export function main() { // Crear un entity const cube = engine.addEntity() // Darle al entity una posición mediante un component Transform Transform.create(cube, { position: Vector3.create(5, 1, 5), }) // Dale a la entity una forma visible mediante un component MeshRenderer MeshRenderer.setBox(cube) } // Define un System function rotationSystem(dt: number) { // consulta las entities que incluyen tanto MeshRenderer como Transform components for (const [entity] of engine.getEntitiesWith(MeshRenderer, Transform)) { const transform = Transform.getMutable(entity) transform.rotation = Quaternion.multiply( transform.rotation, Quaternion.fromAngleAxis(dt * 10, Vector3.Up()) ) } } // Añade el System al engine engine.addSystem(rotationSystem) ``` En el ejemplo anterior, una `cubo` entity y un `rotationSystem` system se añaden al engine. La `cubo` entity tiene un `Transform`, y un `MeshRenderer` component. En cada tick del game loop, el `rotationSystem` System se llama y cambia los valores de rotación en el `Transform` component de la `cubo` entidad. Tenga en cuenta que la mayor parte del código anterior se ejecuta solo una vez, al cargar la escena. La excepción es el `rotationSystem` System, que se llama en cada tick del game loop. ## Desacoplamiento de la escena Tus escenas no se ejecutan en el mismo contexto que el engine (también conocido como el main thread). Creamos el SDK de una manera que está totalmente desacoplada del rendering engine. Lo diseñamos así por razones tanto de seguridad como de rendimiento. Debido a este desacoplamiento, el código de tu escena no tiene acceso al DOM ni al objeto window, así que no puedes acceder a datos como el navegador del player o su ubicación geográfica. `window` objeto, así que no puedes acceder a datos como el navegador del player o su ubicación geográfica. El desacoplamiento funciona usando el protocolo RPC; este protocolo asigna una pequeña parte del client solo para renderizar la escena y controlar eventos. También hemos abstraído el protocolo de comunicación. Esto nos permite ejecutar las escenas localmente en un WebWorker. No queremos que los developers intervengan con los internos del engine ni siquiera que necesiten saber qué hay dentro del engine. Necesitamos garantizar una experiencia coherente para los players en todo el mapa de Decentraland, y es más probable que ocurran errores en ese nivel "bajo". Este desacoplamiento también es importante para evitar que las escenas vecinas interfieran con la experiencia de los players mientras están en la escena de otra persona. Un player podría tener varias escenas cercanas cargadas al mismo tiempo, cada una ejecutando su propio código. Algunas acciones (como abrir enlaces externos o mover al player) solo se permiten cuando el player está parado en esa escena concreta, no si la escena está cargada pero el player está fuera. ## Tree Shaking Cuando conviertes el código fuente en TypeScript al código compilado en JavaScript minificado, el proceso realiza [tree shaking](https://en.wikipedia.org/wiki/Tree_shaking) para asegurarse de que solo se conviertan las partes del código que realmente se están usando. Esto ayuda a mantener el código final de la escena lo más ligero posible. Es especialmente útil cuando se usan librerías externas, ya que a menudo estas incluyen mucha funcionalidad que no se usa y que, de otro modo, engordaría la escena. Como consecuencia del tree shaking, cualquier código que quieras que ejecute tu escena necesita ser referenciado de una forma u otra por los puntos de entrada de tu código: la `main()` función en `index.ts`. Los Systems también pueden añadirse alternativamente al engine en el `index.ts` archivo, sin hacer referencia a `main()`. Cualquier código que no esté explícita o indirectamente referenciado por estos archivos, no formará parte de la escena. Por ejemplo, supón que tienes un archivo llamado `extraContent.ts` con el siguiente contenido, la entity no se renderizará y el System no empezará a ejecutarse: ```ts // extraContent.ts const myEntity = engine.addEntity() Transform.create(myEntity, { position: { x: 8, y: 0, z: 8 }, }) MeshRenderer.setBox(myEntity) function mySystem(dt: number) { console.log('system ejecutándose') } engine.addSystem(mySystem) ``` Para hacer que se ejecute como parte de tu escena, puedes referenciar desde `index.ts` de la siguiente manera: ```ts // en extraContent.ts export function addEntities() { const myEntity = engine.addEntity() Transform.create(myEntity, { position: { x: 8, y: 0, z: 8 }, }) MeshRenderer.setBox(myEntity) } export function mySystem(dt: number) { console.log('system ejecutándose') } ///////////////////////////// // en index.ts import { addEntities, mySystem } from './extraContent' export function main() { addEntities() } engine.addSystem(mySystem) ``` La excepción a esta regla son las definiciones de custom components. Estas no deben accederse mediante el `main()` punto de entrada de la función, ya que necesitan interpretarse antes que todo lo demás. ## Imports Todas las funciones, objetos, components y otros elementos usados por la escena deben importarse en cada archivo para poder usarlos. Esto es una consecuencia de [tree-shaking](#tree-shaking), ya que evita empaquetar todo el SDK y en su lugar solo incluye las partes que usa la escena. Los snippets a lo largo de la documentación omiten las líneas de importación al comienzo de cada archivo para mantenerlos limpios, pero para que funcionen debes agregarlas a la escena. Al usar VS Studio Code para escribir tus escenas, las opciones inteligentes de autocompletado deberían encargarse de gestionar las importaciones por ti mientras escribes, sin que tengas que ser consciente de ello. Cuando pegas un snippet en tu escena, sin embargo, probablemente verás algunos elementos marcados en rojo, que no están importados en ese archivo. Para arreglar esto: * Haz clic en cada palabra subrayada * Haz clic en el icono de la bombilla a la izquierda de la línea * Seleccionar **Añadir importación desde** * Aparece una línea de importación al comienzo del archivo. ![](/files/22cc151fac4baa95b96eeaab5db5c9d0cb72a3dd) Si hay muchas cosas diferentes que importar, también puedes seleccionar **Añadir todas las importaciones que faltan** del mismo menú desplegable. Ten en cuenta que las importaciones deben hacerse en cada archivo donde se use un elemento. VS Studio Code debería poder resolver por sí solo las rutas correctas para tus importaciones. Si por cualquier motivo tiene problemas para hacerlo, un truco es pegar las siguientes sentencias de importación vacías al comienzo de tu archivo. VS Studio debería poder encargarse a partir de ahí. ```ts import {} from '@dcl/sdk/ecs' import {} from '@dcl/sdk/math' ``` ## Versiones del SDK Al desarrollar una nueva escena, usas la `@latest` versión estable del SDK de forma predeterminada. Puedes instalar la `@next` versión del SDK si quieres aprovechar o previsualizar funciones próximas que aún no han llegado a la última versión estable. Para hacerlo, abre el `package.json` archivo de tu escena y cambia las siguientes líneas: ```json "devDependencies": { "@dcl/js-runtime": "next", "@dcl/sdk": "next" }, ``` Luego ejecuta el siguiente comando en la carpeta del proyecto de tu escena: ``` npm i ``` Consulta [gestionar dependencias](/creator/content-creator-es/escenas-sdk7/bibliotecas/manage-dependencies.md) para ver más detalles. {% hint style="warning" %} **📔 Nota**: Ten en cuenta que la versión @next puede sufrir problemas de vez en cuando. La sintaxis y el nombre de las nuevas funciones podrían cambiar antes de que se publiquen en una versión estable. {% endhint %} --- # 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/escenas-sdk7/primeros-pasos/coding-scenes.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.