Início Rápido do SDK

Primeiros passos com o SDK do Decentraland

Este tutorial guia-o na criação da sua primeira scene, combinando as diferentes ferramentas disponíveis: o Scene Editor visual do Creator Hub, código escrito manualmente usando o Decentraland SDK e vibe coding assistido por IA vibe coding. Vai usar as três em conjunto e aprender quando cada uma se destaca.

Instalar o Creator Hub

O Creator Hub permite criar, pré-visualizar e fazer deploy de scenes Decentraland. Descarregue o Creator Hub aqui.

Para editar o código da sua scene, também precisa de um editor de código. Visual Studio Code e Cursor são ambos excelentes opções, mas qualquer editor de código serve.

Leia o guia de instalação para mais detalhes.

Crie a sua primeira scene

1. Abra o Creator Hub.

2. Selecione o separador Scenes e clique em New Scene.

   
3. Escolha um template inicial. 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 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 e arraste alguns itens para a sua scene. Por agora, qualquer item serve.

Os itens já colocados podem ser clicados e arrastados para os reposicionar. Veja Fundamentos do Scene Editor para mais detalhes.

💡 Dica: Cubra a scene inteira com um item Ground. Os itens do tipo Ground têm um ícone de balde de tinta. Se arrastar um destes para a sua scene, ele cobre todo o chão da sua scene com cópias deste item.

Executar uma pré-visualização

Clique no botão Preview no menu superior para carregar a sua scene dentro do Decentraland. Agora pode explorar a scene como um avatar do Decentraland.

Pode manter a janela de pré-visualização aberta enquanto trabalha: ela atualiza-se sempre que faz uma alteração. Leia mais em pré-visualizar uma scene.

Recursos 3D personalizados

Descarregue este modelo 3D de um abacate em glb formato a partir da seguinte ligação e descompacte-o.

Arraste o ficheiro avocado.glb da sua aplicação de exploração de ficheiros para o painel inferior do Scene Editor (o mesmo painel que contém os separadores Asset Packs e Local Assets e clique em Import.

Agora pode encontrar o avocado.glb modelo no Local Assets separador, dentro da pasta Scene Arraste o ficheiro para a sua scene, como qualquer item dos Asset Packs.

Edite o código da scene

Clique no botão <> Code botão no menu superior para abrir o projeto da sua scene no seu editor de código.

📔 Nota: Se nada abrir, certifique-se de que tem instalado um editor de código como Visual Studio Code ou Cursor .

Na margem esquerda do seu editor de código pode navegar pela estrutura de ficheiros e pastas do seu projeto. Abra o ficheiro index.ts dentro da pasta src . O conteúdo deverá ser assim:

import {} from '@dcl/sdk/math'
import { engine } from '@dcl/sdk/ecs'

export function main() {}

As scenes Decentraland são escritas em TypeScript, usando o Decentraland SDK: uma biblioteca com tudo o que precisa para posicionar conteúdo 3D, adicionar interatividade e controlar o que acontece na sua scene.

Este ficheiro define uma função chamada main(), que é o ponto de entrada da scene: qualquer código que colocar aí é executado quando a scene carrega pela primeira vez.

Já arrastou um avocado para a scene visualmente. Agora vamos adicionar um segundo, desta vez escrevendo código. Substitua todo o conteúdo do seu index.ts ficheiro com o seguinte:

import { Vector3 } from '@dcl/sdk/math'
import { engine, Transform, GltfContainer } from '@dcl/sdk/ecs'

export function main() {
	// criar uma nova Entity
	let avocado2 = engine.addEntity()

	// dar-lhe um Transform
	Transform.create(avocado2, {
		position: Vector3.create(8, 0, 8),
	})

	// dar-lhe um GLTF
	GltfContainer.create(avocado2, {
		src: 'assets/scene/avocado.glb',
	})
}

Estas linhas criam uma nova entity, dão-lhe uma shape baseada no modelo 3D que descarregou e definem a sua posição através do componente Transform. entity, dão-lhe um shape baseada no modelo 3D que descarregou e definem a sua posição através do Transform component.

Como regra geral, o código que escreve em index.ts deve ficar todo dentro de main() main() (ou noutras funções referenciadas indiretamente por main). Veja Ciclo de vida da scene para mais detalhes.

Execute a pré-visualização da scene: agora deverá ver dois avocados, o que adicionou no Scene Editor e o que adicionou via código.

📔 Nota: O segundo avocado existe apenas no seu código. Ele aparece quando executa a scene, mas o canvas e a entity tree do Scene Editor não conseguem mostrar entities criadas em index.ts. Não se assuste se não o vir no editor. Isto é algo importante a ter em mente quando mistura edição visual com código.

Ambos os avocados são construídos a partir das mesmas peças. Selecione o primeiro avocado no Scene Editor: o properties panel mostra um Transform e um GltfContainer component com os mesmos tipos de campos que acabou de escrever em código. São duas vistas da mesma coisa.

Adicione interatividade com um Script

Vamos fazer um avocado reagir ao jogador. Poderíamos fazê-lo adicionando código ao index.ts que já estávamos a editar, mas em vez disso vamos usar o Script component: uma forma de anexar código diretamente a um item no Scene Editor. Mantém o comportamento de cada item autocontido, e até pode reutilizar o mesmo script em vários itens.

1. No Scene Editor, selecione o primeiro avocado (o que arrastou; lembre-se, o avocado apenas com código não é visível aqui).

2. Clique no botão + botão no topo do properties panel e selecione Script para adicionar um Script component.

3. Clique + Create New Script e dê-lhe o nome AvocadoScript.

1. Clique no botão <> Code no botão do Script component para abrir o novo ficheiro no seu editor de código.

O script é uma class com três partes principais (comentários cortados para brevidade):

import { engine, Entity } from '@dcl/sdk/ecs'
import {} from '@dcl/sdk/math'

export class AvocadoScript {
	constructor(
		public src: string, // NÃO REMOVA
		public entity: Entity, // NÃO REMOVA
		// Adicione as suas entradas personalizadas abaixo
	) {}

	start() {
		// Chamado uma vez, quando a scene carrega
	}

	update(dt: number) {
		// Chamado em cada frame
	}
}

• O constructor define parâmetros que aparecem como campos editáveis no Script component no Creator Hub. Não remova src ou entity.

• start() é executado uma vez, quando a scene carrega. Use-o para configuração: criar components, registar handlers de clique, etc.

• update(dt) é executado em cada frame do jogo, aproximadamente 30 vezes por segundo. Use-o para comportamento contínuo, como movimento. dt indica quantos segundos passaram desde o último frame.

Dentro da class, this.entity refere-se sempre à entity que contém o Script component: neste caso, o seu avocado. É isto que torna os scripts reutilizáveis: anexe o mesmo script a dez itens, e cada um age sobre si próprio.

Codifique a sua primeira interação com vibe coding

Pode escrever o código seguinte manualmente, mas este é um ótimo momento para experimentar vibe codingvibe coding: descrever o que quer a um assistente de IA e deixá-lo escrever o código. A maioria dos editores de código tem um integrado, como o chat do Cursor, o GitHub Copilot no VS Code, ou Claude Code. Também pode escrever prompts fora do seu editor de código, como com o Claude Desktop ou o Claude Code na linha de comandos.

Antes do seu primeiro prompt, instale as Decentraland SDK skills, para que a IA conheça os padrões do SDK e cometa muito menos erros:

npx skills add decentraland/sdk-skills

Estas skills são documentos de referência que a IA consulta sempre que não tem certeza de como fazer algo com o SDK, por isso escreve código correto em vez de adivinhar. Veja Vibe Coding with AI para opções de configuração e dicas de prompting.

Agora experimente um prompt como este:

Em AvocadoScript.ts, faça com que o avocado escreva uma mensagem na consola quando o jogador clicar nele.

Deverá acabar com algo parecido com isto (ou cole-o você mesmo):

import { engine, Entity, pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
import {} from '@dcl/sdk/math'

export class AvocadoScript {
	constructor(
		public src: string,
		public entity: Entity,
	) {}

	start() {
		pointerEventsSystem.onPointerDown(
			{
				entity: this.entity,
				opts: { button: InputAction.IA_POINTER },
			},
			() => {
				console.log('CLICKED AVOCADO')
			}
		)
	}

	update(dt: number) {}
}

Adicionou algum comportamento de clique dentro da função. start() Só precisamos de definir o comportamento de clique uma vez, e ele reagirá sempre que o jogador clicar no item. A declaração pointerEventsSystem.onPointerDown() define três coisas:

• O entity Em que os eventos de clique funcionam: aqui this.entityo avocado que contém o script.

• Um objeto opts o botão a usar e outros argumentos opcionais que não estamos a usar agora.

• Uma função que é executada sempre que a entity é clicada.

Para ver a mensagem registada, execute a pré-visualização e abra a consola clicando no ícone no canto superior direito. Também pode alterná-la premindo a tecla ` Cada vez que clicar no avocado, verá aparecer uma nova linha:

📔 Nota: Para uma entity ser clicável, precisa de uma geometria collider. O modelo usado aqui já inclui uma. Veja Colliders para soluções alternativas para modelos que não a tenham.

Faça o avocado desaparecer

Vamos fazer com que o clique faça agora algo mais emocionante! Peça ao seu assistente de IA:

Quando o avocado for clicado, faça-o desaparecer. Quero que ele desapareça com uma animação elástica de encolhimento. Também quero que a dica que vejo ao apontar para o avocado diga "Collect".

Deverá acabar com algo parecido com isto:

import { engine, Entity, pointerEventsSystem, InputAction, Tween, EasingFunction } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

export class AvocadoScript {
	constructor(
		public src: string,
		public entity: Entity,
	) {}

	start() {
		pointerEventsSystem.onPointerDown(
			{
				entity: this.entity,
				opts: { button: InputAction.IA_POINTER, hoverText: 'Collect' },
			},
			() => {
				this.collect()
			}
		)
	}

	collect() {
		Tween.setScale(
			this.entity,
			Vector3.One(),
			Vector3.Zero(),
			500,
			EasingFunction.EF_EASEINBOUNCE
		)
	}

	update(dt: number) {}
}

Vamos analisar o que a IA fez.

• Para fazer a animação elástica, usou um Tween. Um tween descreve uma transição gradual da posição, rotação ou escala de uma entity ao longo do tempo. Aqui Tween.setScale() encolhe o avocado do tamanho completo (Vector3.One()) para nada (Vector3.Zero()) ao longo de 500 milissegundos, usando uma curva de easing elástica. Saiba mais sobre tweens em mover entities.

• Em vez de escrever o tween diretamente dentro da função de clique, criou um método separado collect() Isto não é obrigatório (se a IA colocar o tween dentro da função de clique, também funciona), mas é boa prática: métodos mantêm o código legível e permitem reutilizar a mesma lógica em diferentes locais.

• Para mostrar a dica "Collect" no avocado, definiu isso como o valor de hoverText .

Execute a pré-visualização e clique no avocado: ele deve desaparecer com estilo.

📔 Nota: O avocado encolhe até ao tamanho 0, mas a entity continua a existir. Idealmente, deve eliminar a entity depois de o tween terminar, para manter a sua scene mais leve. Veja Ao terminar o tween.

Executar código em cada frame

Até agora, todo o nosso código foi executado em start(). Vamos usar update() para fazer o avocado girar continuamente. Substitua o constructor e update() por:

	constructor(
		public src: string,
		public entity: Entity,
		public speed: number = 45,
	) {}

	update(dt: number) {
		const transform = Transform.getMutable(this.entity)
		transform.rotation = Quaternion.multiply(
			transform.rotation,
			Quaternion.fromAngleAxis(this.speed * dt, Vector3.Up())
		)
	}

Também terá de adicionar Transform e Quaternion aos imports no topo do ficheiro, para que fiquem assim:

import { engine, Entity, pointerEventsSystem, InputAction, Tween, EasingFunction, Transform } from '@dcl/sdk/ecs'
import { Vector3, Quaternion } from '@dcl/sdk/math'

💡 Dica: Em vez de editar os imports manualmente, pode clicar nos erros assinalados pelo seu editor de código e deixá-lo adicioná-los automaticamente.

A cada frame, isto roda o avocado um pouco mais. Multiplicar por dt torna o movimento suave e independente da taxa de frames: o avocado roda a 45 graus por segundo, independentemente da rapidez com que a máquina do jogador funcione.

Porque speed é um parâmetro do constructor, também aparece como um campo no Script component no Creator Hub. Clique no ícone de atualização no canto superior direito do Script component para o ver e depois ajuste o valor sem tocar em qualquer código.

Botão de atualização

Cada entity armazena o seu próprio valor para o campo Speed por isso vários itens podem partilhar o mesmo script mas comportar-se de forma diferente. Experimente: copie o avocado com Ctrl + C e Ctrl + V, mova a cópia para que os dois não se sobreponham e defina uma velocidade diferente em cada um. Cada avocado gira agora à sua própria taxa.

Os scripts podem fazer muito mais, como expor ações que outros smart items podem desencadear. Veja Script component para o quadro completo.

Referenciar um item do Scene Editor

O Script component é a forma mais fácil de dar comportamento a um único item, mas há uma alternativa: o seu código em index.ts pode obter qualquer item que tenha adicionado visualmente, pelo nome, usando engine.getEntityOrNullByName(). Isto é útil quando uma peça de lógica envolve vários itens, ou quando quer tudo num só lugar. Use o nome que aparece na entity tree.

Neste exemplo, usamos uma entity chamada Yellow Crate. Pode usar qualquer item, basta escrever o nome exatamente como aparece na entity tree.

💡 Dica: Pode renomear entities fazendo clique direito e selecionando Rename na entity tree.

export function main() {
	// código do avocado2 de antes
	// (...)

	const crate = engine.getEntityOrNullByName('Yellow Crate')

	if (crate) {
		pointerEventsSystem.onPointerDown(
			{
				entity: crate,
				opts: { button: InputAction.IA_POINTER, hoverText: 'Open' },
			},
			function () {
				console.log('CLICKED CRATE')
			}
		)
	}
}

Aqui engine.getEntityOrNullByName() obtém uma referência à entity chamada Yellow Crate. O if (crate) verifica garante que a entity existe realmente na scene; se não houver nenhuma entity com esse nome, crate é null. Veja Itens de referência para mais informações.

💡 Dica: Todas as entities adicionadas através do Scene Editor já estão carregadas quando main() é executado, por isso é seguro referenciá-las aí ou em funções chamadas indiretamente por main().

Mais tutoriais

Leia Programar scenes para uma compreensão geral de como as scenes Decentraland funcionam.

Para exemplos construídos com SDK7, consulte a página de exemplos, que contém várias scenes pequenas.

Veja a secção guia de desenvolvimento para mais instruções sobre como adicionar conteúdo à sua scene.

Interaja com outros desenvolvedores

Visite o Decentraland Discord e o Discord da Decentraland DAO para participar de uma discussão animada sobre o que é possível e como no Discord da Decentraland Criadores seção.

Para depurar quaisquer problemas, consulte a Solução de problemas e depuração seções. Um assistente de IA com as habilidades de SDK instaladas também é um ótimo companheiro de depuração: cole a mensagem de erro do console ou descreva o que não está se comportando como esperado, e ele normalmente consegue encontrar o problema no seu código. Se você não encontrar uma solução, pode postar na categoria de Suporte do SDK no Fórum da Decentraland.

Recursos de arte 3D

Uma boa experiência terá uma ótima arte 3D para acompanhá-la. Se você tiver interesse em criar esses modelos 3D por conta própria, veja a seção de modelagem 3D. Mas, se você preferir se concentrar na parte de programação ou de design de jogos, não precisa criar seus próprios assets! Veja Recursos úteis para bibliotecas de assets e ferramentas de IA que você pode usar para obter modelos 3D para sua scene.

Publicar sua scene

Se você possui um Decentraland NAME, um nome ETH ENS ou LAND, ou tem permissões concedidas por alguém que os possua, você pode enviar sua scene para a Decentraland. Veja publicação.

Outras informações úteis

• Vibe Coding with AI

• Fluxo de trabalho de desenvolvimento

• Edição de Scenes

• Fundamentos do Scene Editor

• Restrições de design para jogos

• modelagem 3D

• Limitações da scene