> 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/comecar/sdk-101.md).
# SDK Quick Start
O SDK da Decentraland é uma ferramenta poderosa que lhe permite criar ou melhorar as suas scenes escrevendo código em Typescript (Javascript + Types).
{% hint style="info" %}
**💡 Dica**: Se preferir criar as suas scenes apenas com ferramentas no-code, veja [Scene Editor no Creator Hub](https://github.com/decentraland/docs/blob/main/creator/sdk7/get-started/about-editor.md).
{% endhint %}
{% hint style="info" %}
**💡 Dica**: Também pode construir scenes descrevendo o que pretende a um assistente de IA, sem escrever código manualmente. Veja [Vibe Coding com IA](/creator/content-creator-pt/scenes-sdk7/comecar/vibe-coding.md).
{% endhint %}
Este tutorial orienta-o sobre como configurar tudo e mostra os conceitos básicos para escrever código numa scene da Decentraland.
## Instalar o Creator Hub
O Creator Hub permite-lhe construir, fazer Preview e Deploy de scenes da Decentraland. Descarregue o Creator Hub [aqui](https://decentraland.org/download/creator-hub).
Para editar o código da sua scene, também tem de instalar [Visual Studio Code](https://code.visualstudio.com/), se ainda não o tiver.
Lê [Guia de instalação](https://github.com/decentraland/docs/blob/main/creator/sdk7/get-started/editor-installation.md) para mais detalhes sobre a instalação do Creator Hub.
## Crie a sua primeira scene
Para criar a sua primeira scene, siga estes passos.
1. Abra o Creator Hub.
2. Selecione o separador **Scenes** e clique em **Create Scene**.
3. Depois pode escolher entre diferentes Templates iniciais. Para este exercício, escolha **Empty Scene**.
Este passo pode demorar alguns minutos. Ele preenche a sua pasta com o conjunto predefinido de ficheiros para uma scene básica.
Quando isso estiver concluído, verá a grelha vazia da sua scene.
## Adicione itens dos Asset packs
Explore os **Asset packs** na secção inferior do Scene Editor no Creator Hub, largue alguns itens e ajuste as suas posições. Para este tutorial, quaisquer itens servem por agora.
Para colocar um item, clica e arrasta-o do menu do asset pack para uma localização na tua scene no canvas.
Os itens já colocados podem ser clicados e arrastados para os reposicionar livremente. Veja [Fundamentos do editor de scenes](https://github.com/decentraland/docs/blob/main/creator/sdk7/get-started/scene-editor-essentials.md#position-items) para mais detalhes.
{% hint style="info" %}
**💡 Dica**: Cubra toda a scene com um item de Ground. Itens do tipo **Ground** têm um ícone de balde de tinta. Se arrastar um destes para a sua cena, ele cobre todo o Ground da sua cena com cópias deste item.
{% endhint %}
## Executar um Preview
Clique no **Preview** botão no menu superior para Load da sua scene dentro da Decentraland. Agora pode explorar a scene como um Avatar da Decentraland.
Leia mais sobre o Preview da scene em [fazer Preview de uma scene](/creator/content-creator-pt/scenes-sdk7/comecar/preview-scene.md).
{% hint style="info" %}
**💡 Dica**: Pode manter a janela de Preview aberta enquanto continua a trabalhar na sua scene, e ela será atualizada sempre que fizer uma alteração no Scene Editor.
{% endhint %}
## Assets 3D personalizados
Descarregue este modelo 3D de um abacate em formato *glb* a partir do seguinte [link](https://github.com/decentraland-scenes/avocado/raw/main/avocado-glb.zip) e descompacte-o.
1. Clique no sinal de mais no canto superior direito da secção Asset Packs da UI do Scene Editor.
2. Arraste o ficheiro **avocado.glb** para a área na UI do Scene Editor e clique em **Import**.
Agora pode encontrar o modelo **avocado.glb** na **Local Assets** tab **Scene** , dentro da pasta. Arraste-o para a sua scene, como qualquer item dos Asset Packs.
## Editar o código da scene
As próximas secções descrevem como pode editar o código da sua scene, dando-lhe muito mais liberdade como criador.
Clique no **<> Code** botão no menu superior para abrir o projeto da sua scene no Visual Studio Code.
{% hint style="warning" %}
**📔 Nota**: Instalar [Visual Studio Code](https://code.visualstudio.com/), se ainda não o tiver.
{% endhint %}
Isto abre uma janela separada com o Visual Studio Code. Na margem esquerda pode navegar pela estrutura de ficheiros e pastas do seu projeto.
Abra o `index.ts` ficheiro de dentro da pasta `src` na sua scene. O seu conteúdo deve ser assim:
```ts
import {} from '@dcl/sdk/math'
import { engine } from '@dcl/sdk/ecs'
export function main() {}
```
As duas primeiras linhas tratam de instruções de `import` . Estas obtêm referências a coisas que estão definidas noutros ficheiros, para que possam ser usadas neste ficheiro. Não precisará de lidar diretamente com estas linhas neste tutorial, mas repare que a lista de coisas obtidas irá crescer à medida que escrever o seu código.
Repare que este ficheiro define uma Function chamada `main()`. Esta Function é o ponto de entrada da scene; qualquer código que colocar aí será executado quando a scene carregar pela primeira vez. Se escrever linhas de código fora desta Function, elas nunca serão executadas.
Na secção anterior mostrámos como pode arrastar facilmente o modelo 3D personalizado do abacate para a sua scene de forma no-code. Agora vamos adicionar um segundo abacate, para ver como conseguir o mesmo escrevendo código.
Substitua todo o conteúdo do seu ficheiro `index.ts` pelo seguinte. Estas linhas expandem a Function `main()` e adicionam alguns imports:
```ts
import { Vector3 } from '@dcl/sdk/math'
import { engine, Transform, GltfContainer } from '@dcl/sdk/ecs'
export function main() {
// create a fresh new Entity
let avocado2 = engine.addEntity()
// give it a Transform
Transform.create(avocado2, {
position: Vector3.create(8, 0, 8),
})
// give it a GLTF
GltfContainer.create(avocado2, {
src: 'assets/scene/avocado.glb',
})
}
```
Se abrir novamente o Preview da scene, deverá agora ver dois abacates: o que adicionou no Scene Editor e o que adicionou via código.
As linhas que acabou de adicionar criam uma nova [entity](/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md), dão-lhe um [shape](/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/shape-components.md) com base no modelo 3D que descarregou, e [definem a sua posição e escala](/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/entity-positioning.md) através do **Transform**.
Agora volte ao Scene Editor e selecione o primeiro abacate que adicionou. No Properties panel deste item verá que a UI dos Components Transform e GLTF mostra a mesma informação que no código que acabou de escrever.
## Adicionar interatividade
Para tornar a sua scene mais envolvente, vamos fazer com que as entities da scene respondam às interações do jogador.
No fim da Function `main()` (antes de ser fechada pelo último **}**), adicione um handler de PointerEvents à entity do abacate. Isto executa uma Function personalizada sempre que o jogador clica no abacate.
```ts
pointerEventsSystem.onPointerDown(
{
entity: avocado2,
opts: { button: InputAction.IA_POINTER, hoverText: 'Collect' },
},
function () {
console.log('CLICKED AVOCADO')
}
)
```
{% hint style="info" %}
**💡 Dica**: O Visual Studio Code ajuda-o marcando erros de sintaxe, autocompletando enquanto escreve e até mostrando sugestões inteligentes que dependem do contexto. Também pode clicar num objeto para ver a definição completa da sua Class.
Se alguma das palavras que colou estiver sublinhada a vermelho, passe o cursor sobre elas para ver se o VS Studio oferece uma solução fácil. Muito provavelmente terá de o fazer para **pointerEventsSystem**e **InputAction**.
Ao clicar na lâmpada, será sugerido `Update import from @dcl/sdk/ecs`. Selecione esta opção para adicionar imports ao início do seu `index.ts` ficheiro do modelo.
{% endhint %}
O `pointerEventsSystem.onPointerDown()` A instrução define três coisas:
* Em que `entity` os PointerEvents funcionam.
* Um objeto `opts` com parâmetros adicionais opcionais. Neste caso incluímos que botão utilizar e que texto de Hint mostrar.
* Uma Function, que será executada sempre que a entity for clicada.
Neste caso, a Function que estamos a executar é muito simples. Tem apenas uma linha e limita-se a imprimir algum texto na Console.
```ts
console.log('CLICKED AVOCADO')
```
No campo `opts` na secção, estamos a definir o campo `button` para que escute o botão do ponteiro (o botão esquerdo do rato num PC). Também estamos a definir o parâmetro `hoverText` para mostrar texto personalizado. Dessa forma, os jogadores lerão o texto "collect" quando passarem o cursor sobre o abacate, e saberão o que acontecerá se clicarem nele. O abacate ainda não faz muito, mas lá chegaremos nos próximos passos.
Para ver essa mensagem que o evento de clique está a registar, terá de abrir a Console. Para o fazer, abra novamente o Preview da scene, caso ainda não o tenha em execução, e prima a tecla **\`** para alternar a apresentação da Console. Agora, sempre que clicar no abacate que adicionou via código, verá:
{% hint style="warning" %}
\*\*📔 Nota\*\*: Para uma entity ser clicável, tem de ter uma geometria de Collider. O modelo usado aqui já inclui uma. Veja a secção \[Colliders]\(../3d-modeling/colliders.md) para soluções alternativas para modelos que não incluem uma geometria de Collider.
{% endhint %}
Agora vamos fazer com que essa Function de clique faça algo mais interessante: vamos fazer o abacate desaparecer. Use \`
engine.removeEntity()\` para se livrar do abacate assim que ele for clicado. Vamos adicionar uma linha extra ao nosso snippet:
```ts
pointerEventsSystem.onPointerDown(
{
entity: avocado2,
opts: { button: InputAction.IA_POINTER, hoverText: 'Collect' },
},
function () {
console.log('CLICKED AVOCADO')
engine.removeEntity(avocado2)
}
)
```
Agora, quando for clicado, o abacate desaparece da sua scene.
## Tweens
Tweens descrevem uma transição gradual de uma posição/rotação/escala para outra, ao longo de um período de tempo.
Vamos começar por adicionar um Tween de escala ao nosso abacate, apenas para experimentar a funcionalidade. Adicione as seguintes linhas dentro da Function `main()` , no fim, sem alterar nada do que já adicionou:
```ts
export function main() {
// Code from previous snippets (do not change)
// (...)
// New code:
Tween.setMove(avocado2,
Vector3.create(3, 0, 3),
Vector3.create(8, 0, 8),
5000
)
}
```
{% hint style="info" %}
**💡 Dica**: Ao colar isto, poderá encontrar mais palavras sublinhadas a vermelho por falta de imports.
Passe o cursor sobre cada uma e clique na lâmpada; ela irá sugerir `Update import from @dcl/sdk/ecs`. Selecione esta opção para adicionar imports ao início do seu `index.ts` ficheiro do modelo.
{% endhint %}
O `Tween` O Component que criámos tem argumentos que o fazem mudar de posição, desde uma posição nas Coordinates *3,0,3* da scene, até às Coordinates *8,0,8*, ao longo de um período de 5000 milissegundos (5 segundos). Este movimento começará assim que a scene iniciar.
A `Tween` A Function setMove requer a seguinte informação:
* `entity`: Em que entity trabalhar
* `start`: Posição inicial.
* `end`: Posição final.
* `duration`: Duração (em milissegundos) da escala do início ao fim.
Este outro parâmetro opcional também está disponível:
* `easingFunction`: Que tipo de curva utilizar para controlar a taxa de mudança ao longo do tempo. Neste caso usamos linear, o que resulta numa mudança suave e constante.
Podemos brincar com o parâmetro `easingFunction` para obter alguns efeitos interessantes. Por exemplo, podemos usar `EF_EASEINBOUNCE` para realizar a transição usando uma interpolação ease-in bounce, que começa com um efeito saltitante e depois vai de lento para rápido.
{% hint style="info" %}
**💡 Dica**: Também pode usar o Component **Tween** para escalar ou rodar uma entity ao longo de um período de tempo; esta é uma ferramenta realmente útil! Saiba mais [aqui](/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/move-entities.md)
{% endhint %}
## Usar as suas próprias Functions
Nesta secção vamos adicionar outro Tween à escala do abacate, para tornar o efeito de desaparecimento mais apelativo. Mas vamos adotar uma abordagem um pouco menos direta para introduzir alguns outros conceitos.
A forma mais simples de fazer o nosso abacate encolher quando clicamos nele é adicionar um Tween dentro da Function dos PointerEvents, em vez da linha `engine.removeEntity(avocado2)`. Mas, em vez disso, vamos criar este Tween numa Function separada que depois possamos reutilizar para outros itens. Assim, não precisaremos de escrever o mesmo código duas vezes! A nossa nova Function será separada de `main()`, por isso não fará nada sozinha, mas em breve iremos chamá-la.
```ts
function collect(myEntity: Entity) {
Tween.setScale(myEntity,
Vector3.One(),
Vector3.Zero(),
500,
EasingFunction.EF_EASEINBOUNCE
)
}
```
Repare que o Tween é adicionado a uma entity chamada `myEntity`, em vez de `avocado2`. `myEntity` é apenas um placeholder; não existe nenhuma entity com esse nome na scene. Vem de um parâmetro definido na Function. Quando chama a Function `collect()` , pode passar qualquer entity da scene, e ela aplicará um `Tween` a essa entity. Mais sobre isso adiante.
{% hint style="info" %}
**💡 Dica**: Sempre que houver código que possa estar a usar várias vezes na sua scene, é uma boa prática colocá-lo dentro de uma Function. Assim só tem de o escrever uma vez, e é mais fácil de manter.
{% endhint %}
Aqui criámos um Tween que afeta a *Scale*, por isso agora `start` e `end` referem-se ao tamanho do abacate, não à posição. Vai de um tamanho de um até zero, durante 500 milissegundos (meio segundo), e usa uma Function de easing `EASEINBOUNCE` , que lhe dá um divertido efeito saltitante.
Agora vamos modificar a Function que escrevemos para quando clicamos no abacate. Vamos mudar a linha que diz `engine.removeEntity(avocado)`, e em vez disso vamos chamar a Function `collect()` que acabámos de definir, passando uma referência para a nossa entity do abacate:
```ts
pointerEventsSystem.onPointerDown(
{
entity: avocado2,
opts: { button: InputAction.IA_POINTER, hoverText: 'Collect' },
},
function () {
console.log('CLICKED AVOCADO')
collect(avocado2)
}
)
```
Se agora abrir o Preview da scene e clicar no abacate, deverá vê-lo desaparecer com estilo, fazendo um divertido movimento saltitante.
{% hint style="warning" %}
**📔 Nota**: Pode já ter percebido que agora o abacate encolhe até ao tamanho 0, mas continua a existir. Não vamos abordar isto neste primeiro tutorial, mas num cenário ideal deve garantir que elimina a entity depois de o Tween terminar, para otimizar o desempenho da sua scene. Veja [Quando o tween termina](/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/move-entities.md#on-tween-finished).
{% endhint %}
## Referenciar um item a partir do Scene Editor
O seu código também pode fazer coisas com os itens que adicionou visualmente no Scene Editor no Creator Hub. Pode obter esses itens pelo nome no seu código, usando a Function `engine.getEntityOrNullByName()`. Use o nome do item que vê escrito na [entity tree](https://github.com/decentraland/docs/blob/main/creator/sdk7/get-started/scene-editor-essentials.md#the-entity-tree).
Neste exemplo, temos uma entity chamada **Yellow Crate**. Pode usar qualquer item que queira, apenas certifique-se de que escreve o nome exatamente como aparece na entity tree.
{% hint style="info" %}
**💡 Dica**: Pode renomear entities clicando com o botão direito e selecionando **Rename** na entity da entity tree.
{% endhint %}
```ts
export function main() {
// Avocado stuff
const crate = engine.getEntityOrNullByName('Yellow Crate')
if (crate) {
console.log('The crate exists')
}
}
```
No snippet acima, usamos `engine.getEntityOrNullByName()` para obter uma referência a uma entity chamada *Yellow Crate*. Na linha seguinte, fazemos `if (crate)` para garantir que realmente existe uma entity com este nome na scene. Se não existir, então o valor de `crate` será `null`. Vê [Reference Items](https://github.com/decentraland/docs/blob/main/creator/sdk7/code/reference-items.md) para mais informações.
{% hint style="info" %}
**💡 Dica**: Todas as entities adicionadas através do Scene Editor já estarão carregadas na sua scene quando o código na Function `main()` for chamado. Deve ser seguro referenciá-las nesta Function, ou noutras Functions que sejam chamadas indiretamente por ela.
{% endhint %}
Agora vamos adicionar um comportamento de ponteiro à nossa entity Yellow Crate, tal como fizemos com o abacate.
```ts
export function main() {
// Avocado stuff
const crate = engine.getEntityOrNullByName('Yellow Crate')
if (crate) {
console.log('The crate exists')
pointerEventsSystem.onPointerDown(
{
entity: crate,
opts: { button: InputAction.IA_POINTER, hoverText: 'Collect' },
},
function () {
console.log('CLICKED CRATE')
collect(crate)
}
)
}
}
```
Repare como estamos a chamar a Function `collect()` que definimos antes. Como a Function está definida separadamente, só precisámos de escrever essa linha para a chamar!
{% hint style="info" %}
**💡 Dica**: Também pode obter [Smart Items](https://github.com/decentraland/docs/blob/main/creator/sdk7/interactivity-1/smart-items.md) da sua scene da mesma forma, e fazer o que quiser com eles via código. Veja [Reference Items](https://github.com/decentraland/docs/blob/main/creator/sdk7/code/reference-items.md) para mais informações.
{% endhint %}
## Mais tutoriais
Lê [coding-scenes](https://github.com/decentraland/docs-creator/blob/main/sdk7/getting-started/coding-scenes.md) para uma compreensão de alto nível de como funcionam as scenes da Decentraland.
Para exemplos construídos com SDK7, consulte a [página Examples](https://studios.decentraland.org/resources?sdk_version=SDK7) que contém várias pequenas scenes, todas escritas com SDK7.
Veja a secção **Guia de desenvolvimento** para mais instruções sobre como adicionar conteúdo à sua scene.
## Interaja com outros developers
Visite [The Decentraland Discord](https://dcl.gg/discord) como as [Decentraland DAO Discord](https://discord.gg/bxHtcMxUs4), para participar numa discussão animada sobre o que é possível e como!
Para fazer Debug de quaisquer problemas, recomendamos que consulte as secções [Resolução de problemas](/creator/content-creator-pt/scenes-sdk7/depuracao/troubleshooting.md) e [debug](/creator/content-creator-pt/scenes-sdk7/depuracao/debug-in-preview.md) na documentação. Se não encontrar aí uma solução, pode publicar problemas na [categoria SDK Support](https://forum.decentraland.org/c/support-sdk/11) do Decentraland Forum.
Também pode publicar no [Stack Overflow](https://stackoverflow.com/questions/ask?tags=+\[decentraland-ecs]), usando as tags `decentraland` ou `decentraland-ecs`.
Também pode perguntar no [Decentralnad Discord](https://dcl.gg/discord). Na secção **Support** , o canal **#sdk** é para questões relacionadas com código, o canal **#builder-and-3d** é para questões relacionadas com modelos 3D e arte. **#code-contribution** é para discutir PRs para a codebase do SDK.
No campo [Decentraland DAO Discord](https://discord.gg/bxHtcMxUs4) também pode obter ajuda no canal **sdk-support** .
## Assets de arte 3D
Uma boa experiência terá ótima arte 3D a acompanhá-la. Se tem vontade de criar esses modelos 3D por si mesmo, é encorajado a fazê-lo; veja a [secção 3D Modeling](/creator/content-creator-pt/modelacao-e-animacoes-3d/3d-models.md) para mais informações. Mas se preferir focar-se no lado do coding ou do game design, não precisa de criar os seus próprios assets!
Aqui estão algumas fontes para obter ótimos modelos 3D que pode usar numa scene da Decentraland:
* [IWB Catalog](https://dcl-iwb.co/)
* [Asset Ovi](https://assetovi.com/)
* [SketchFab](https://sketchfab.com/)
* [Clara.io](https://clara.io/)
* [Archive3D](https://archive3d.net/)
* [SketchUp 3D Warehouse](https://3dwarehouse.sketchup.com/)
* [Thingiverse](https://www.thingiverse.com/)
* [ShareCG](https://www.sharecg.com/)
* [CGTrader](https://cgtrader.com)
Você também pode usar ferramentas de Generative AI para gerar os seus próprios modelos 3D. Veja:
* [Meshy](https://www.meshy.ai/)
* [Luma AI](https://lumalabs.ai/genie)
* [TRipo3D](https://www.tripo3d.ai/app)
* [Rodin](https://hyper3d.ai/rodin)
{% hint style="warning" %}
**📔 Nota**: Os modelos têm de estar nos `.gltf` ou `.glb` formats suportados e devem ter um número de triangles, textures e materials que respeitem as [limitações da scene](/creator/content-creator-pt/scenes-sdk7/otimizacao/scene-limitations.md). Ao obter modelos de um site de terceiros, preste atenção às restrições de licença do conteúdo que descarrega.
{% endhint %}
## Publique a sua scene
Se possuir LAND, um NAME da Decentraland, ou um nome ENS de ETH, ou tiver permissões concedidas por alguém que os possua, pode fazer Upload da sua scene para a Decentraland. Veja [publishing](/creator/content-creator-pt/scenes-sdk7/publicacao/publishing.md).
## Outras informações úteis
* [Libraries](https://studios.decentraland.org/resources?sdk_version=SDK7\&resource_type=Library)
* [Restrições de design para jogos](/creator/content-creator-pt/scenes-sdk7/desenhar-a-experiencia/design-games.md)
* [3D modeling](/creator/content-creator-pt/modelacao-e-animacoes-3d/3d-models.md)
* [Scene limitations](/creator/content-creator-pt/scenes-sdk7/otimizacao/scene-limitations.md)
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/comecar/sdk-101.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.