Inicio rápido del SDK
Comenzando con el Decentraland SDK
El SDK de Decentraland es una herramienta poderosa que te permite crear o mejorar tus escenas escribiendo código en TypeScript (JavaScript + Types).
💡 Consejo: Si prefieres crear tus escenas únicamente con herramientas sin código, consulta Scene Editor in Creator Hub.
Este tutorial te guía en cómo configurarlo y te muestra los conceptos básicos para escribir código en una escena de Decentraland.
Instalar el Creator Hub
El Creator Hub te permite construir, previsualizar y desplegar escenas de Decentraland. Descarga el Creator Hub aquí.
Para editar el código de tu escena, también debes instalar Visual Studio Code, si aún no lo tienes.
Lee Guía de instalación para más detalles sobre la instalación del Creator Hub.
Crea tu primera escena
Para crear tu primera escena, sigue estos pasos.
Abre el Creator Hub.
Selecciona la Escenas pestaña, y haz clic en Create Scene.
Luego puedes elegir entre diferentes plantillas iniciales. Para este ejercicio, elige la Empty Scene.
Este paso puede tardar un par de minutos. Rellena tu carpeta con el conjunto predeterminado de archivos para una escena básica.
Una vez hecho eso, verás la cuadrícula vacía de tu escena.
Agrega elementos desde los asset packs
Explora los Asset packs en la sección inferior del Scene Editor en Creator Hub, arrastra un par de elementos y ajusta sus posiciones. Para el propósito de este tutorial, cualquier elemento servirá por ahora.
Para colocar un elemento, haz clic y arrástralo desde el menú del asset pack hacia una ubicación en tu escena en el lienzo.
Los elementos ya colocados se pueden hacer clic y arrastrar para reposicionarlos libremente. Ver Scene editor essentials para más detalles.
💡 Consejo: Cubre toda la escena con un elemento de ground. Los elementos del tipo Ground tienen un icono de cubeta de pintura. Si arrastras uno de estos a tu escena, cubre todo el terreno de tu escena con copias de este elemento.
Ejecutar una previsualización
Haz clic en el Previsualizar botón en el menú superior para cargar tu escena dentro de Decentraland. Ahora puedes explorar la escena como un avatar de Decentraland.
Lee más sobre la previsualización de la escena en preview a scene.
💡 Consejo: Puedes mantener la ventana de previsualización abierta mientras sigues trabajando en tu escena, y se actualizará cada vez que hagas un cambio en el Scene Editor.
Assets 3D personalizados
Descarga este modelo 3D de un aguacate en glb formato desde el siguiente enlace y descomprímelo.
Haz clic en el signo más en la esquina superior derecha de la sección Asset Packs de la interfaz del Scene Editor.
Arrastra el avocado.glb archivo sobre la región de la interfaz del Scene Editor y haz clic en Import.
Ahora puedes encontrar el avocado.glb modelo en la Local Assets pestaña, dentro de la carpeta Scene . Arrástralo a tu escena, como con cualquier elemento de los Asset Packs.
Edita el código de la escena
Las siguientes secciones describen cómo puedes editar el código de tu escena, dándote mucha más libertad como creador.
Haz clic en el <> Code botón en el menú superior para abrir tu proyecto de escena en Visual Studio Code.
📔 Nota: Instalar Visual Studio Code, si aún no lo tienes.
Esto abre una ventana separada con Visual Studio Code. En el margen izquierdo puedes navegar los archivos y la estructura de carpetas de tu proyecto.
Abre el index.ts archivo desde dentro de la carpeta src en tu escena. Su contenido debería verse así:
Las dos primeras líneas tratan con import declaraciones. Estas obtienen referencias a cosas que están definidas en otros archivos, para que puedan usarse en este archivo. No necesitarás ocuparte de estas líneas directamente en este tutorial, pero observa que la lista de cosas que se obtienen crecerá a medida que escribas tu código.
Observa que este archivo define una función llamada main(). Esta función es el punto de entrada de la escena; cualquier código que pongas allí se ejecutará cuando la escena se cargue por primera vez. Si escribes líneas de código fuera de esta función, nunca se ejecutarán.
En la sección anterior mostramos cómo puedes arrastrar fácilmente el modelo 3D personalizado de aguacate a tu escena de forma no code. Ahora añadiremos un segundo aguacate, para ver cómo lograr lo mismo escribiendo código.
Reemplaza el contenido completo de tu archivo index.ts con lo siguiente. Estas líneas amplían la función main() y añaden un par de imports:
Si vuelves a abrir la previsualización de la escena, ahora deberías ver dos aguacates: el que añadiste en el Scene Editor y el que añadiste mediante código.
Las líneas que acabas de añadir crean un nuevo entity, le dan un shape basado en el modelo 3D que descargaste, y establecen su posición y escala a través del Transform.
Ahora vuelve al Scene Editor y selecciona el primer aguacate que añadiste. En el panel de propiedades de este elemento verás que la UI para los componentes Transform y GLTF muestra la misma información que en el código que acabas de escribir.
Añadir interactividad
Para hacer tu escena más atractiva, hagamos que las entidades en la escena respondan a las interacciones del jugador.
Al final de la función main() (before it's closed by the last }), añade un manejador de eventos de pointer al entity avocado. Esto ejecuta una función personalizada cada vez que el jugador hace clic en el aguacate.
💡 Consejo: Visual Studio Code te ayuda marcando errores de sintaxis, autocompletando mientras escribes e incluso mostrando sugerencias inteligentes que dependen del contexto. También puedes hacer clic en un objeto para ver la definición completa de su clase.
Si alguna de las palabras que pegaste está subrayada en rojo, pasa el cursor sobre ellas para ver si VS Code ofrece una solución fácil. Probablemente tendrás que hacer esto para pointerEventsSystem, y InputAction.
Hacer clic en la bombilla sugerirá Update import from @dcl/sdk/ecs. Selecciona esta opción para añadir imports al inicio de tu index.ts archivo.
El pointerEventsSystem.onPointerDown() la declaración define tres cosas:
Qué
entityen qué funcionan los eventos de pointer.Un
optsobjeto con parámetros adicionales opcionales. En este caso incluimos qué botón usar y qué texto de pista mostrar.Una función, que se ejecutará cada vez que la entidad sea clickeada.
En este caso, la función que ejecutamos es muy simple. Es solo una línea y simplemente imprime texto en la consola.
En el opts En esta sección, estamos estableciendo el campo button para que escuche el botón del pointer (el botón izquierdo del ratón en un PC). También estamos estableciendo el parámetro hoverText para mostrar texto personalizado. De ese modo, los jugadores leerán el texto "collect" cuando pasen el cursor sobre el aguacate, y sabrán qué sucederá si hacen clic en él. El aguacate todavía no hace mucho, pero llegaremos ahí en los siguientes pasos.
Para ver ese mensaje que el evento de clic está registrando, necesitarás abrir la consola. Para hacer esto, abre la previsualización de la escena de nuevo si no la tienes ya en ejecución, y presiona la tecla ` para alternar la visualización de la consola. Ahora cada vez que hagas clic en el aguacate que añadiste mediante código, verás:
**📔 Nota**: Para que una entidad sea clickeable, debe tener una geometría de collider. El modelo usado aquí ya incluye una. Consulta la sección [Colliders](../3d-modeling/colliders.md) para soluciones para modelos que no incluyen una geometría de collider.
Ahora hagamos que esa función de clic haga algo más interesante: que el aguacate desaparezca. Usa `
engine.removeEntity()` para deshacerte del aguacate una vez que se haga clic. Añadamos una línea extra a nuestro fragmento:
Ahora, al hacer clic, el aguacate desaparece de tu escena.
Tweens
Los tweens describen una transición gradual de una posición/rotación/escala a otra, durante un período de tiempo.
Empecemos añadiendo un tween de escala a nuestro aguacate, solo para probar la función. Añade las siguientes líneas dentro de la función, al final, sin cambiar nada de lo que ya agregaste: main() function, at the end, without changing anything of what you already added:
💡 Consejo: Al pegar esto, podrías encontrar más palabras subrayadas en rojo debido a imports faltantes.
Pasa el cursor sobre cada una y haz clic en la bombilla; sugerirá Update import from @dcl/sdk/ecs. Selecciona esta opción para añadir imports al inicio de tu index.ts archivo.
El Tween el componente que creamos tiene argumentos que hacen que cambie de posición, desde una posición en las coordenadas 3,0,3 de la escena, a las coordenadas 8,0,8, durante un período de 5000 milisegundos (5 segundos). Este movimiento comenzará tan pronto como la escena inicie.
A Tween la función setMove requiere la siguiente información:
entity: Qué entidad en la que trabajarstart: Posición inicial.end: Posición final.duration: Duración (en milisegundos) del inicio al final del escalado.
Este otro parámetro opcional también está disponible:
easingFunction: Qué tipo de curva usar para controlar la tasa de cambio en el tiempo. En este caso usamos linear, lo que resulta en un cambio constante y suave.
Podemos jugar con el parámetro easingFunction para obtener algunos efectos interesantes. Por ejemplo, en su lugar podemos usar EF_EASEINBOUNCE para realizar la transición usando una interpolación ease-in bounce, que comienza con un efecto rebote y luego va de lento a rápido.
💡 Consejo: También puedes usar el componente Tween para escalar o rotar una entidad durante un período de tiempo; ¡esta es una herramienta realmente útil! Aprende más aquí
Usando tus propias funciones
En esta sección añadiremos otro tween sobre la escala del aguacate, para que el efecto de desaparición se vea más atractivo. Pero tomaremos un enfoque ligeramente menos directo para introducir algunos otros conceptos.
La forma más simple de hacer que nuestro aguacate se encoja cuando hacemos clic en él es añadir un tween dentro de la función de eventos de pointer, en lugar de la línea engine.removeEntity(avocado2). Pero en su lugar, creemos este tween en una función separada que luego podamos reutilizar para otros elementos. De esa manera no tendremos que escribir el mismo código dos veces. Nuestra nueva función será independiente de main(), así que no hará nada por sí sola, pero pronto la llamaremos.
Observa que el tween se añade a una entidad nombrada myEntity, en lugar de avocado2. myEntity es realmente un marcador de posición; no hay una entidad con ese nombre en la escena. Proviene de un parámetro definido en la función. Cuando llamas a la función collect() , puedes pasar cualquier entidad de la escena y se le aplicará un Tween Más sobre eso más adelante.
💡 Consejo: Siempre que haya código que puedas usar varias veces en tu escena, es una buena práctica ponerlo dentro de una función. De ese modo solo tienes que escribirlo una vez y es más fácil de mantener.
Aquí creamos un Tween que afecta la Escala, así que ahora start y end se refiere al tamaño del aguacate, no a la posición. Va de un tamaño de uno a cero, en una duración de 500 milisegundos (medio segundo), y usa una función de easing EASEINBOUNCE que le da un divertido efecto de rebote.
Ahora modifiquemos la función que escribimos para cuando hacemos clic en el aguacate. Cambiemos la línea que dice engine.removeEntity(avocado), y en su lugar llamemos a la función collect() que acabamos de definir, pasando una referencia a nuestra entidad aguacate:
Si ahora abres la previsualización de la escena y haces clic en el aguacate, deberías verlo desaparecer con estilo, realizando un movimiento divertido y saltarín.
📔 Nota: Puede que hayas deducido que ahora el aguacate se encoge hasta un tamaño de 0, pero aún existe. No cubriremos esto en este primer tutorial, pero en un escenario ideal deberías asegurarte de eliminar la entidad después de que el tween termine, para optimizar el rendimiento de tu escena. Consulta Al finalizar un tween.
Referenciar un elemento desde el Scene Editor
Tu código también puede hacer cosas con los elementos que añadiste visualmente en el Scene Editor en Creator Hub. Puedes obtener estos elementos por nombre en tu código, usando la función engine.getEntityOrNullByName(). Usa el nombre del elemento tal y como lo ves escrito en el entity tree.
En este ejemplo, tenemos una entidad llamada Yellow Crate. Puedes usar cualquier elemento que quieras; solo asegúrate de escribir su nombre exactamente como aparece en el entity tree.
💡 Consejo: Puedes renombrar entidades haciendo clic derecho y seleccionando Rename en la entidad del entity tree.
En el fragmento anterior, usamos engine.getEntityOrNullByName() para obtener una referencia a una entidad llamada Yellow Crate. En la línea siguiente, hacemos if (crate) para asegurarnos de que realmente exista una entidad con ese nombre en la escena. Si no existe, entonces el valor de crate será null. Ver Referencia Items para más información.
💡 Consejo: Todas las entidades añadidas vía el Scene Editor ya estarán cargadas en tu escena para cuando se llame a la función main() . Debería ser seguro referenciarlas en esta función, o en otras funciones que sean llamadas indirectamente por ella.
Ahora añadamos un comportamiento de pointer a nuestra entidad Yellow Crate, tal como hicimos con el aguacate.
Observa cómo estamos llamando a la función collect() que definimos antes. Dado que la función está definida por separado, ¡solo necesitábamos escribir esa línea para llamarla!
💡 Consejo: También puedes obtener Smart Items desde tu escena de la misma manera, y hacer con ellos lo que quieras mediante código. Consulta Referencia Items para más información.
Más tutoriales
Lee coding-scenes para una comprensión de alto nivel de cómo funcionan las escenas de Decentraland.
Para ejemplos construidos con SDK7, revisa la página de Examples que contiene varias escenas pequeñas, todas escritas con SDK7.
Consulta la sección Development guide para más instrucciones sobre cómo añadir contenido a tu escena.
Interactúa con otros desarrolladores
Visita The Decentraland Discord y el Decentraland DAO Discord, para unirte a una animada discusión sobre lo que es posible y cómo hacerlo.
Para depurar cualquier problema, te recomendamos que consultes las secciones de Solución de problemas y debug en la documentación. Si no encuentras una solución allí, puedes publicar incidencias en la categoría SDK Support category en el foro de Decentraland.
También puedes publicar en Stack Overflow, usando las etiquetas decentraland o decentraland-ecs.
También puedes preguntar en el Decentralnad Discord. En la sección Support , el canal #sdk es para preguntas relacionadas con código, el canal #builder-and-3d es para preguntas relacionadas con modelos 3D y arte. #code-contribution es para discutir PRs al código base del SDK.
En el Decentraland DAO Discord también puedes obtener ayuda en el canal sdk-support .
Assets de Arte 3D
Una buena experiencia tendrá un gran arte 3D que la acompañe. Si te interesa crear esos modelos 3D tú mismo, te animamos a hacerlo; consulta la sección 3D Modeling section para más información. Pero si prefieres centrarte en la programación o el diseño de juegos, ¡no necesitas crear tus propios assets!
Aquí hay algunas fuentes para obtener excelentes modelos 3D que puedes usar en una escena de Decentraland:
También puedes usar herramientas de IA generativa para generar tus propios modelos 3D. Consulta:
📔 Nota: Los modelos deben estar en los formatos soportados .gltf o .glb , y deben tener un número de triángulos, texturas y materiales que se adhieran a las limitaciones de la escena. Si obtienes modelos de un sitio de terceros, presta atención a las restricciones de licencia del contenido que descargues.
Publica tu escena
Si eres propietario de LAND, un NAME de Decentraland, o un nombre ENS en ETH, o tienes permisos otorgados por alguien que lo sea, puedes subir tu escena a Decentraland. Consulta publicación.
Otra información útil
Última actualización