For the complete documentation index, see llms.txt. This page is also available as Markdown.

Criar uma Biblioteca

Crie suas próprias bibliotecas do Decentraland para compartilhar com outras pessoas

As bibliotecas são uma excelente forma de partilhar soluções para problemas comuns. É possível resolver desafios complexos uma única vez, encapsular as soluções numa biblioteca e, sempre que surgirem, basta escrever uma linha de código. Ao partilharmos bibliotecas com a comunidade, podemos aumentar exponencialmente a produtividade de todos os criadores.

Atualmente, estas bibliotecas na página de exemplos estão disponíveis para todos utilizarem. Também incentivamos a criação e partilha das suas próprias bibliotecas.

Seguindo os passos detalhados aqui, pode evitar a maior parte da complexidade envolvida na criação de uma biblioteca compatível com as cenas do Decentraland e fácil de partilhar com outras pessoas.

Criar uma biblioteca

📔 Nota: certifique-se de que está a utilizar a versão 20 ou posterior do Node antes de compilar a sua biblioteca.

Para criar a sua própria biblioteca e partilhá-la através do NPM, siga estes passos:

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

  2. Selecione o separador Decentraland na barra lateral esquerda do Visual Studio

  3. Clique em Criar projeto, depois selecione Biblioteca

    Isto criará todos os ficheiros e dependências predefinidos para uma biblioteca do Decentraland.

  4. Defina um name único em package.json. Este é o nome que será utilizado ao publicar no NPM. Certifique-se de que não existe outro projeto com esse nome no npm. Preencha também a descrição e quaisquer etiquetas que ajudem outras pessoas a encontrar a sua biblioteca.

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

    O projeto está configurado para utilizar ações do GitHub para publicar uma nova versão do pacote a cada envio para main.

    No ficheiro package.json , certifique-se de que, em repository , define o campo url com o URL do seu repositório. Assim, será fácil encontrá-lo para quem navegar em npmjs.com.

  6. Obtenha um token do NPM:

    1. Crie uma conta ou inicie sessão em https://www.npmjs.com/.

    2. Aceda a Account > Access Tokens > Generate new Token Crie um token novo e atribua-lhe permissões de Publicação .

      A mensagem de sucesso inclui uma cadeia de caracteres correspondente ao token recém-gerado. Copie-a e guarde-a num local seguro.

  7. No seu repositório do GitHub, aceda a Settings > Secrets > Actions, depois clique em New Repository Secret.

    Dê ao segredo o nome NPM_TOKENe cole a cadeia de caracteres do token do NPM como valor.

  8. Envie uma alteração (qualquer alteração) para o ramo main do seu repositório do GitHub e o pacote será publicado.

    É isso, agora qualquer pessoa pode instalar o pacote usando npm i <package-name>! Agora, você pode encontrar sua biblioteca pesquisando pelo nome em npmjs.com.

  9. Desenvolva a /src pasta do seu projeto com todas as funcionalidades que deseja disponibilizar e envie as alterações para o GitHub.

Desenvolver

Adicione ao arquivo index.ts da biblioteca as funções, os Components etc. que deseja disponibilizar. Assim, fica fácil importá-los.

Por exemplo, se você adicionar um RotatorComponent à index.ts, você poderá importar esse Component para uma scene escrevendo o seguinte:

import { RotatorComponent } from 'my-library'

Teste sua biblioteca usando-a em uma nova scene do Decentraland durante o desenvolvimento. Instale o pacote npm na scene executando npm i <package-name>. Em seguida, crie uma scene para testar as funcionalidades da biblioteca. Experimente diferentes casos de teste na scene para garantir que a biblioteca funcione como esperado em todos eles.

Iterações rápidas

Se precisar fazer pequenos ajustes continuamente na biblioteca e testá-los, pode ser cansativo ter que enviar as alterações e esperar a publicação no npm terminar para 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 test scene:

  1. Adicione este script à lista de 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 dessas etapas é importante. Talvez não funcione se forem executadas em outra ordem.

Isso manterá sua scene sincronizada com a versão da biblioteca que está diretamente no seu disco local. Para testar quaisquer alterações na biblioteca, basta executar npm run build na pasta da biblioteca, sem precisar enviar alterações para o GitHub ou publicá-las no NPM.

💡 Dica: Para verificar se o link foi criado corretamente, execute npm ls --link. O nome da biblioteca deve apontar para a pasta nos seus arquivos locais.

Se fizer alterações na biblioteca, tem de executar npm run build para as atualizar. Para não ter de o fazer sempre:

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

  2. Execute npm start na biblioteca

Quando terminar os testes, lembre-se de desligar a ligação à biblioteca.

  1. Na pasta da scene, execute npm install <library name>

  2. Depois, na biblioteca, execute rm -rf node_modules && npm install

Versionamento

As versões da sua biblioteca são publicadas automaticamente no npm com uma flag @latest e uma flag @next .

A flag @next aponta sempre para o último commit na branch main . Esta versão pode ser instável, uma vez que as alterações mais recentes podem não ter sido testadas. Os utilizadores da sua biblioteca podem instalá-la (por sua conta e risco) executando npm i <library name>@next.

A flag @latest aponta para a última versão estável da biblioteca. É esta a versão que os utilizadores da sua biblioteca devem instalar normalmente. É a versão que o npm obtém quando executam npm i <library name>.

Para fazer com que a flag @latest aponte para os seus commits mais recentes, terá de criar uma versão da sua biblioteca no GitHub.

  1. Abra a página do seu projeto no GitHub. Abra a ligação Releases , na margem direita da página.

  2. Clique em Draft new release.

  3. Em Chose tag escreva um nome para a nova versão, por exemplo, "1.1.0". Escreva também um nome em Release Title. Muitas vezes, é o mesmo nome: "1.1.0".

    Importante: a tag tem de ser um número, sem letras ou símbolos adicionais. O número tem de ser superior ao das versões publicadas anteriormente.

  4. Descreva a versão para que os utilizadores saibam o que há de novo.

    Sugestão: clique no botão Auto generate release notes para apresentar todos os commits desde a última versão.

  5. Atingir Publicar versão. Esta ação aciona uma nova publicação automática no npm com a @latest flag. Os utilizadores da sua biblioteca passarão a descarregar esta versão.

Notas sobre usabilidade

Faça o possível para que a sua biblioteca seja fácil de usar por outros criadores. As nossas suposições ajudam sempre a moldar as ferramentas que criamos. Muitas vezes, estas suposições parecem óbvias para nós, mas outras pessoas, com um contexto diferente, podem ter suposições completamente distintas.

  • Escolha cuidadosamente os nomes de tudo na sua biblioteca, incluindo funções, Components e parâmetros. É preferível um nome comprido que se explique por si só a um nome curto que seja um completo mistério.

  • Pense de forma abrangente nos diferentes casos de utilização possíveis para a sua biblioteca. Talvez alguém a use num wearable inteligente, talvez alguém precise de ativar ou desativar o seu sistema em determinados momentos, talvez alguém precise de adicionar várias instâncias do seu sistema à mesma Scene. Nem todos enfrentarão os mesmos desafios que você.

  • Dito isto, não precisa de suportar todos os casos de utilização possíveis. Na verdade, há sempre compromissos entre flexibilidade e simplicidade de utilização; criar boas ferramentas consiste em encontrar o equilíbrio certo. Seja estratégico quanto aos limites que define para aquilo que opta por não suportar. No entanto, é importante documentar claramente as limitações que decidiu impor.

  • Isto leva-nos à documentação. Documente a sua biblioteca de forma clara, incluindo exemplos, descrições da função de cada parâmetro, comentários sobre os cenários que não funcionarão e as suposições que está a fazer sobre o contexto em que será utilizada. O README.md da biblioteca é muitas vezes o melhor lugar para apresentar este conteúdo.

  • Outra excelente ferramenta é adicionar comentários de metadados diretamente ao seu código. Estes comentários são apresentados pelo IDE (como o VS Studio Code) enquanto os utilizadores escrevem. Pode descrever a finalidade de cada função/Component, o que cada parâmetro deve receber e o que uma função devolve. Graças a isto, os utilizadores da sua biblioteca não precisam de alternar entre o código e a documentação: está tudo num só lugar! Por exemplo, veja esta função da biblioteca @dcl/ecs-scene-utils :

    Os utilizadores desta biblioteca veem estas sugestões enquanto escrevem a função clamp() :

  • Declare sempre os tipos. Não deixe as pessoas a adivinhar que estrutura de objeto terão de utilizar.

  • Mantenha a sua biblioteca leve e focada numa única funcionalidade. Quando uma Scene de Decentraland é compilada, todo o código de todas as bibliotecas é incluído, até mesmo o código que nunca é chamado pela Scene. Por este motivo, é melhor evitar criar bibliotecas grandes e pesadas. É preferível ter bibliotecas enxutas, que permitam aos criadores usar apenas aquilo de que realmente precisam.

  • Acompanhe o repositório da sua biblioteca; as pessoas podem enviar pull requests ou comunicar problemas.

  • Inclua informações sobre a licença no seu repositório, para que outras pessoas saibam se podem usar a sua biblioteca. A licença predefinida da biblioteca é a licença Apache 2, de código aberto; pode alterá-la se quiser.

Atualizado