Criar uma Biblioteca

Crie suas próprias bibliotecas Decentraland para compartilhar com outros

As bibliotecas são uma ótima forma de compartilhar soluções para problemas comuns. Desafios complexos podem ser abordados uma vez, as soluções encapsuladas em uma biblioteca e, sempre que surgirem, você só precisa escrever uma linha de código. Ao compartilhar bibliotecas com a comunidade, podemos fazer a produtividade de todos os criadores crescer exponencialmente.

Atualmente, essas bibliotecas no page de Examples estão disponíveis para todos usarem. Encorajamos você a criar e compartilhar as suas também.

Seguindo os passos detalhados aqui, você pode evitar a maior parte da complexidade que acompanha a criação de uma biblioteca compatível com scenes do Decentraland e fácil de compartilhar com outras pessoas.

Criar uma biblioteca

📔 Nota: Certifique-se de que está usando Node versão 16.x ou mais recente antes de construir sua biblioteca.

Para criar sua própria biblioteca e compartilhá-la via NPM, faça o seguinte:

1. Crie uma nova pasta vazia e abra uma nova janela do VS Studio Code nela.

2. Selecione a aba Decentraland na barra lateral esquerda do Visual Studio

3. Clique Criar Projeto, então selecione Library

   Isso criará todos os arquivos e dependências padrão para uma biblioteca do Decentraland.

4. Defina um campo name em package.json. Este é o nome que será usado ao publicar no NPM; certifique-se de que não exista algum outro projeto usando esse nome no npm. Também preencha a descrição e quaisquer tags para ajudar outros a encontrar sua biblioteca.

5. Crie um novo público repositório GitHub para seu projeto.

   O projeto está configurado para usar github actions para publicar uma nova versão do pacote a cada push para main.

   No package.json arquivo, certifique-se de que em repositório você aponte o campo url para a URL do seu repo. Dessa forma fica fácil de encontrar para usuários navegando no npmjs.com.

6. Obtenha um token NPM:

   1. Crie uma conta ou faça login em https://www.npmjs.com/.

   2. Vá para Account > Access Tokens > Generate new Token Crie um novo token, dê-lhe Publish permissões.

      A mensagem de sucesso inclui uma string para o token recém-gerado. Copie essa string e armazene-a em um local seguro.

7. No seu repositório do github, vá para Settings > Secrets > Actions, então clique em New Repository Secret.

   Nomeie seu segredo NPM_TOKEN, e cole a string do token NPM como seu valor.

8. Faça um push de uma alteração (qualquer alteração) para a branch main do seu repo no GitHub e o pacote será publicado.

   É isso, agora o pacote pode ser instalado por qualquer um usando npm i <package-name>! Você agora pode encontrar sua biblioteca se procurá-la pelo nome em npmjs.com.

9. Preencha a pasta /src do seu projeto com toda a funcionalidade que você quer expor e faça push das alterações para o GitHub.

Desenvolver

Adicione quaisquer funções, componentes, etc. que você queira expor no arquivo index.ts do projeto da biblioteca, assim eles ficam fáceis de importar.

Por exemplo, se você adicionar um RotatorComponent componente para index.ts, você então poderá importar este componente para uma scene escrevendo o seguinte:

import { RotatorComponent } from 'my-library'

Teste sua biblioteca usando-a em uma nova scene do Decentraland enquanto a desenvolve. Instale seu pacote npm em uma scene executando npm i <package-name>. Em seguida, construa uma scene que sirva para testar a funcionalidade da biblioteca. Tente cobrir diferentes casos de teste com sua scene, para garantir que sua biblioteca funcione como esperado em todos os casos.

Iterações rápidas

Se você precisa continuamente fazer pequenos ajustes na sua biblioteca e testá-los, pode ser exaustivo ter que commitar mudanças e então esperar a publicação no npm completar antes de poder experimentar a nova versão em uma scene. Felizmente, há uma alternativa muito mais rápida para executar testes com sua biblioteca.

Em um projeto de scene de teste:

1. Adicione este script à lista scripts em package.json: "link-sdk": "cd node_modules/@dcl/sdk && npm link && cd ../js-runtime && npm link"

2. Execute npm install

3. Execute npm install YOUR_LIBRARY_PATH, por exemplo, npm install /User/projects/dcl-sdk7-library-test

4. Execute npm run link-sdk

No projeto da biblioteca:

1. Execute npm install

2. Execute npm run build

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

❗Aviso: A ordem destes passos é importante. Pode não funcionar em outra ordem.

Isso manterá sua scene sincronizada com a versão da biblioteca que está diretamente no seu disco local. Para quaisquer mudanças na biblioteca que você queira testar, basta executar npm run build na pasta da biblioteca, não é necessário publicar mudanças no GitHub ou NPM.

💡 Tip: Para verificar que o link foi bem-sucedido, execute npm ls --link. Você deverá ver o nome da biblioteca apontando para a pasta nos seus arquivos locais.

Se você fizer alterações na biblioteca, deve executar npm build para atualizá-las. Para evitar ter que fazer isso toda vez:

1. Adicione o script "start": "tsc -p tsconfig.json --watch" ao

2. Execute da biblioteca npm start

na biblioteca

1. Quando terminar de testar, lembre-se de deslinkar a biblioteca. Na pasta da scene execute

2. npm install <library name> Então, na biblioteca execute

rm node_modules && npm install

Versionamento As versões da sua biblioteca são publicadas automaticamente no com um @latest e um @next npm

O @next flag. main flag sempre aponta para o último commit na branch branch. Esta versão pode ser instável, já que as últimas alterações podem não ter sido testadas. Usuários da sua biblioteca podem instalá-la (por sua própria conta e risco) fazendo.

O @latest npm i <library name>@next flag aponta para o último release estável da biblioteca. É isso que os usuários da sua biblioteca devem instalar normalmente. É a versão que o npm busca quando eles fazem.

npm i <library name> @latest Para fazer o flag apontar para seus commits mais recentes, você precisará fazer um release da sua biblioteca no GitHub.

1. Abra a página do GitHub do seu projeto. Abra o link Releases na margem direita da página.

2. Clique Draft new release.

3. Em Escolha tag escreva um nome para sua nova versão, por exemplo "1.1.0". Também escreva um nome em Release Title. Frequentemente este é o mesmo nome, "1.1.0".

   Importante: A tag deve ser um número, sem letras ou símbolos adicionais. O número deve ser maior que os releases publicados anteriormente.

4. Descreva seu release, para que os usuários saibam o que há de novo.

   Dica: Clique no botão Auto generate release notes para imprimir todos os commits desde o último release.

5. Clique em Publish Release. Esta ação aciona uma nova publicação automática no npm com o @latest flag. Usuários da sua biblioteca agora irão baixar essa versão.

Notas sobre usabilidade

Faça o possível para tornar sua biblioteca fácil de usar para outros criadores. Nossas suposições sempre ajudam a moldar as ferramentas que fazemos. Frequentemente essas suposições parecem óbvias para nós, mas outros com outro contexto podem ter suposições completamente diferentes.

• Escolha nomes cuidadosamente para tudo na sua biblioteca, incluindo funções, componentes e parâmetros. É melhor ter um nome longo e autoexplicativo do que um curto que seja um completo mistério.

• Pense amplamente sobre diferentes possíveis casos de uso para sua biblioteca. Talvez alguém use sua biblioteca em um wearable inteligente, talvez alguém precise ligar ou desligar seu sistema em determinados momentos, talvez alguém precise adicionar múltiplas instâncias do seu sistema na mesma scene. Nem todos enfrentarão os mesmos desafios que você.

• Dito isso, você não precisa suportar todos os casos de uso possíveis. Na verdade, sempre há trade-offs a fazer entre flexibilidade e simplicidade de uso; criar boas ferramentas é encontrar o equilíbrio certo. Seja estratégico sobre onde traçar a linha do que você decide não suportar. É importante documentar claramente as limitações que você escolheu adotar, porém.

• Isso nos leva à Documentação. Documente sua biblioteca de forma clara, com exemplos, descrições do que cada parâmetro faz, comentários sobre quais cenários não funcionariam e quais suposições você está fazendo sobre o contexto em que ela é usada. O README.md da biblioteca é frequentemente o melhor lugar para expor esse conteúdo.

• Outra ótima ferramenta é adicionar comentários de metadata diretamente no seu código. Esses comentários são exibidos pelo IDE (como o VS Studio Code) enquanto os usuários da sua biblioteca digitam. Você pode descrever para que serve cada função/componente, descrever o que cada parâmetro espera receber e o que uma função retorna. Graças a isso, os usuários da sua biblioteca não precisam alternar entre o código e a documentação — está tudo ali em um só lugar! Por exemplo, veja esta função da @dcl/ecs-scene-utils biblioteca:

  /**
   * Restringe (clamps) um valor para que não exceda um valor mínimo ou máximo.
   *
   * @param value - número de entrada
   * @param min - Valor mínimo de saída.
   * @param max - Valor máximo de saída.
   * @returns O valor mapeado resultante entre o min e o 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
  }

  Usuários desta biblioteca veem essas dicas exibidas enquanto digitam o clamp() :

• Sempre declare tipos. Não deixe as pessoas adivinharem qual estrutura de objeto elas terão que consumir.

• Mantenha sua biblioteca leve e focada em uma única funcionalidade. Quando uma scene do Decentraland é compilada, todo o código de todas as suas bibliotecas é empacotado com ela, inclusive código que nunca é chamado pela scene. Por essa razão, é melhor evitar criar bibliotecas grandes e volumosas. É preferível ter bibliotecas enxutas que permitam aos criadores usar somente o que realmente precisam.

• Fique de olho no repositório da sua biblioteca; pessoas podem abrir pull requests ou relatar issues.

• Inclua informações de licença no seu repo, assim outros saberão se estão livres para usar sua biblioteca. A biblioteca padrão inclui uma licença aberta Apache 2; sinta-se à vontade para mudar isso se desejar.