Crear una librería

Crea tus propias librerías de Decentraland para compartir con otros

Las bibliotecas son una excelente forma de compartir soluciones a problemas comunes. Los desafíos complejos pueden abordarse una vez, encapsularse en una biblioteca y, cuando surjan, solo necesitas escribir una línea de código. Al compartir bibliotecas con la comunidad, podemos hacer que la productividad de todos los creadores crezca exponencialmente.

Actualmente, estas bibliotecas en el página de Examples están disponibles para que todos las usen. Te animamos a crear y compartir las tuyas también.

Siguiendo los pasos detallados aquí, puedes evitar la mayor parte de la complejidad que conlleva crear una biblioteca compatible con Decentraland scenes y fácil de compartir con otros.

Crear una biblioteca

📔 Nota: Asegúrate de usar Node versión 16.x o superior antes de compilar tu biblioteca.

Para crear tu propia biblioteca y compartirla a través de NPM, haz lo siguiente:

1. Crea una nueva carpeta vacía y abre allí una nueva ventana de VS Studio Code.

2. Selecciona la pestaña Decentraland en la barra lateral izquierda de Visual Studio

3. Haz clic en Crear Proyecto, luego selecciona Library

   Esto creará todos los archivos y dependencias por defecto para una biblioteca de Decentraland.

4. Establece un name en package.json. Este es el nombre que se usará al publicar en NPM; asegúrate de que no haya otro proyecto existente que use ese nombre en npm. También rellena la descripción y las etiquetas para ayudar a otros a encontrar tu biblioteca.

5. Crea un nuevo público repositorio de GitHub para tu proyecto.

   El proyecto está configurado para usar GitHub Actions para publicar una nueva versión del paquete en cada push a main.

   En el package.json archivo, asegúrate de que en repositorio apuntes el campo url a la URL de tu repo. De esa manera es fácil de encontrar para los usuarios que navegan por npmjs.com.

6. Obtén un token de NPM:

   1. Crea una cuenta o inicia sesión en https://www.npmjs.com/.

   2. Ve a Account > Access Tokens > Generate new Token Crea un nuevo token y dale Publish permisos.

      El mensaje de éxito incluye una cadena con el token recién generado. Copia esa cadena y guárdala en un lugar seguro.

7. En tu repositorio de GitHub, ve a Settings > Secrets > Actions, luego haz clic en New Repository Secret.

   Nombra tu secreto NPM_TOKEN, y pega la cadena del token de NPM como su valor.

8. Haz push de un cambio (cualquier cambio) a la rama main de tu repo de GitHub y el paquete se publicará.

   Eso es todo, ahora el paquete puede ser instalado por cualquiera usando npm i <package-name>! Ahora puedes encontrar tu biblioteca si la buscas por nombre en npmjs.com.

9. Rellena la carpeta /src de tu proyecto con toda la funcionalidad que quieras exponer y haz push de los cambios a GitHub.

Desarrollar

Agrega cualquier función, componente, etc. que quieras exponer en el archivo index.ts de la biblioteca, de esa manera serán fáciles de importar.

Por ejemplo, si agregas un RotatorComponent componente en index.ts, puedes entonces importar este componente en una escena escribiendo lo siguiente.:

import { RotatorComponent } from 'my-library'

Prueba tu biblioteca usándola en una nueva Decentraland scene mientras la desarrollas. Instala tu paquete npm en una escena ejecutando npm i <package-name>. Luego construye una escena que sirva para probar la funcionalidad de la biblioteca. Intenta cubrir diferentes casos de prueba con tu escena, para asegurar que tu biblioteca funcione como se espera en cada caso.

Iteraciones rápidas

Si necesitas hacer continuamente pequeños ajustes a tu biblioteca y probarlos, puede ser agotador tener que committear cambios y luego esperar a que la publicación en npm se complete antes de poder probar la nueva versión en una escena. Afortunadamente, existe una alternativa mucho más rápida para ejecutar pruebas con tu biblioteca.

En un proyecto de escena de prueba:

1. Agrega este script a la lista scripts en package.json: "link-sdk": "cd node_modules/@dcl/sdk && npm link && cd ../js-runtime && npm link"

2. Ejecuta npm install

3. Ejecuta npm install YOUR_LIBRARY_PATH, p. ej., npm install /User/projects/dcl-sdk7-library-test

4. Ejecuta npm run link-sdk

En el proyecto de biblioteca:

1. Ejecuta npm install

2. Ejecuta npm run build

3. Ejecuta: npm link @dcl/sdk @dcl/js-runtime

❗Advertencia: El orden de estos pasos es importante. Puede que no funcione en otro orden.

Esto mantendrá tu escena sincronizada con la versión de la biblioteca que está directamente en tu disco local. Para cualquier cambio en la biblioteca que quieras probar, solo ejecuta npm run build en la carpeta de la biblioteca, no es necesario publicar cambios en GitHub o NPM.

💡 Consejo: Para verificar que el enlace fue exitoso, ejecuta npm ls --link. Debes ver el nombre de la biblioteca apuntando a la carpeta en tus archivos locales.

Si haces cambios en la biblioteca, debes ejecutar npm build para actualizarlos. Para evitar tener que hacer eso cada vez:

1. Agrega el script "start": "tsc -p tsconfig.json --watch" a la

2. Ejecuta biblioteca npm start

en la biblioteca

1. Cuando termines de probar, recuerda desvincular la biblioteca. En la carpeta de la escena ejecuta

2. npm install <library name> Luego en la biblioteca ejecuta

rm node_modules && npm install

Versionado Las versiones de tu biblioteca se publican automáticamente en npm @latest y un export function mySystem(dt: number) { con una

El export function mySystem(dt: number) { flag. main La flag siempre apunta al último commit en la rama . Esta versión puede ser inestable ya que los últimos cambios podrían no estar testeados. Los usuarios de tu biblioteca pueden instalarla (bajo su propio riesgo) haciendo.

El @latest npm i <library name>@next La flag apunta a la última versión estable de la biblioteca. Esto es lo que los usuarios de tu biblioteca deberían instalar normalmente. Es la versión que npm obtiene cuando hacen.

npm i <library name> @latest Para hacer que la flag apunte a tus últimos commits, necesitarás crear un release

1. de tu biblioteca en GitHub. Abre la página de GitHub de tu proyecto. Abre el enlace Releases

2. Haz clic en , en el margen derecho de la página..

3. Redactar nuevo release En Elige la etiqueta escribe un nombre para tu nueva versión, por ejemplo "1.1.0". También escribe un nombre enRelease Title

   . A menudo es el mismo nombre, "1.1.0".

4. Importante: La etiqueta debe ser un número, sin letras ni símbolos adicionales. El número debe ser mayor que las publicaciones anteriores.

   Describe tu release, para que los usuarios sepan qué hay de nuevo. Consejo: Haz clic en el botón Auto generate release notes

5. para imprimir todos los commits desde la última release. Haz clic enPublish Release @latest . Esta acción desencadena una nueva publicación automática en npm con la

flag. Los usuarios de tu biblioteca ahora descargarán esta versión.

Notas sobre usabilidad

• Haz todo lo posible para que tu biblioteca sea fácil de usar para otros creadores. Nuestras suposiciones siempre ayudan a moldear las herramientas que hacemos. A menudo estas suposiciones nos parecen obvias, pero otras personas con otro contexto pueden tener suposiciones completamente diferentes.

• Elige nombres con cuidado para todo en tu biblioteca, incluyendo funciones, componentes y parámetros. Es mejor tener un nombre largo y autoexplicativo que uno corto que sea un completo misterio.

• Piensa ampliamente en diferentes casos de uso posibles para tu biblioteca. Tal vez alguien use tu biblioteca en un wearable inteligente, tal vez alguien necesite activar o desactivar tu sistema en ciertos momentos, tal vez alguien necesite agregar múltiples instancias de tu sistema en la misma escena. No todos enfrentarán los mismos desafíos que tú.

• Dicho esto, no necesitas soportar todos los casos de uso posibles. De hecho siempre hay compensaciones entre flexibilidad y simplicidad de uso; crear buenas herramientas es acertar en el equilibrio correcto. Sé estratégico sobre dónde trazas la línea de lo que decides no soportar. Es importante documentar claramente las limitaciones que decidiste aceptar.

• Esto nos lleva a la Documentación. Documenta tu biblioteca claramente, con ejemplos, descripciones de lo que hace cada parámetro, comentarios sobre qué escenarios no funcionarían y qué suposiciones haces sobre el contexto donde se usa. El README.md de la biblioteca suele ser el mejor lugar para exponer este contenido. Otra gran herramienta es agregar comentarios de metadata directamente en tu código. Estos comentarios se muestran en el IDE (como VS Studio Code) mientras los usuarios de tu biblioteca escriben. Puedes describir para qué sirve cada función/componente, describir qué espera recibir cada parámetro y qué devuelve una función. Gracias a esto, los usuarios de tu biblioteca no necesitan cambiar entre el código y la documentación; ¡está todo allí en un mismo lugar! Por ejemplo, mira esta función de la @dcl/ecs-scene-utils

  /**
   biblioteca:
   *
   * Restringe un valor para que no exceda un valor mínimo o máximo.
   * @param value - número de entrada
   * @param min - Valor mínimo de salida.
   * @param max - Valor máximo de salida.
   * @returns El valor resultante mapeado entre min y max
   */
  * @public
  	export function clamp(value: number, min: number, max: number) {
  
  	let result = value
  		if (value > max) {
  	result = max
  		} else if (value < min) {
  	}
  	result = min
  }

  return result Los usuarios de esta biblioteca ven estas sugerencias mostradas mientras escriben la función función:

• clamp()

• Declara siempre los tipos. No dejes a la gente adivinar qué estructura de objeto tendrán que consumir.

• Mantén tu biblioteca ligera y enfocada en una sola funcionalidad. Cuando se compila una Decentraland scene, todo el código de todas sus bibliotecas se empaqueta con ella, incluso el código que nunca es llamado por la escena. Por esta razón, es mejor evitar crear bibliotecas grandes y pesadas. Es preferible tener bibliotecas ligeras que permitan a los creadores usar solo lo que realmente necesitan.

• Mantén un ojo en el repo de tu biblioteca; la gente podría hacer pull requests o reportar issues.