> 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-pt/scenes-sdk7/bibliotecas/create-libraries.md).

# 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](https://studios.decentraland.org/resources?sdk_version=SDK7\&resource_type=Library) 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](https://www.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\_TOKEN**e 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](https://www.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` :

  ```ts
  /**
   * Limita um valor para que não ultrapasse 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 resultante, mapeado entre min e 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
  }
  ```

  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.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/bibliotecas/create-libraries.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
