Início rápido do SDK

Crie sua primeira scene do Decentraland com o Creator Hub, o SDK e vibe coding assistido por IA usando as SDK Skills oficiais.

Este tutorial guia você na criação da sua primeira scene, combinando as diferentes ferramentas que você tem à disposição: o Scene Editor visual do Creator Hub, código escrito à mão usando o Decentraland SDK e assistido por IA vibe coding. Você usará as três juntas e aprenderá em que cada uma se destaca.

Como eu crio uma scene do Decentraland?

Instale o Creator Hub, o aplicativo de desktop oficial para criar, visualizar e publicar scenes. É a ferramenta recomendada para criadores de todos os níveis de habilidade.
Se você usar um assistente de codificação por IA (como Claude Code, Cursor ou Copilot), instale o oficial Decentraland SDK Skills para que ele conheça padrões verificados de SDK7: npx skills add decentraland/sdk-skills
O CLI é uma alternativa para usuários avançados e fluxos de trabalho automatizados.

O restante deste tutorial percorre esse caminho recomendado passo a passo.

Instale o Creator Hub

O Creator Hub permite criar, visualizar e fazer deploy de scenes do Decentraland. Baixe o Creator Hub aqui.

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

Leia Guia de instalação para mais detalhes.

Crie sua primeira scene

Abra o Creator Hub.
Selecione a Scenes aba e clique em Nova Scene.
Escolha um template inicial. Para este exercício, escolha o Empty Scene.

Esta etapa pode levar alguns minutos. Ela preenche sua pasta com o conjunto padrão de arquivos para uma scene básica. Quando isso terminar, você verá a grade vazia da sua scene.

Adicione itens dos pacotes de assets

Explore os Asset packs na seção inferior do Scene Editor e arraste alguns itens para sua scene. Qualquer item serve por enquanto.

Itens já colocados podem ser clicados e arrastados para reposicioná-los. Veja Noções básicas do Scene Editor para mais detalhes.

💡 Dica: Cubra toda a scene com um item Ground. Itens do tipo Ground têm um ícone de balde de tinta. Se você arrastar um deles para sua scene, ele cobrirá todo o chão da sua scene com cópias deste item.

Ground

Execute uma pré-visualização

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

Você pode manter a janela de Preview aberta enquanto trabalha: ela é atualizada toda vez que você faz uma alteração. Leia mais em pré-visualizar uma scene.

assets 3D personalizados

Baixe este modelo 3D de um abacate em glb no formato do seguinte link e descompacte-o.

Arraste o avocado.glb arquivo do seu explorador de arquivos para o painel inferior do Scene Editor (o mesmo painel que contém as Asset Packs e Local Assets abas) e clique em Import.

Agora você pode encontrar o avocado.glb modelo na Local Assets aba, dentro da Scene pasta. Arraste o arquivo para sua scene, como qualquer item dos Asset Packs.

Edite o código da scene

Clique no <> 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 você tem um editor de código como Visual Studio Code ou Cursor instalado.

Na margem esquerda do seu editor de código, você pode navegar pela estrutura de arquivos e pastas do seu projeto. Abra o index.ts arquivo dentro da src pasta. O conteúdo deve se parecer com isto:

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

export function main() {}

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

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

Você já arrastou um abacate para a scene visualmente. Agora vamos adicionar um segundo, desta vez escrevendo código. Substitua todo o conteúdo do seu index.ts arquivo pelo seguinte:

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

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

	// dê a ela um Transform
	Transform.create(avocado2, {
		position: Vector3.create(8, 0, 8),
	})

	// dê a ela um GLTF
	GltfContainer.create(avocado2, {
		src: 'assets/scene/avocado.glb',
	})
}

Estas linhas criam uma nova entity, dão a ela uma forma com base no modelo 3D que você baixou, e definem sua posição por meio do Transform component.

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

Execute o preview da scene: agora você deve ver dois abacates, o que você adicionou no Scene Editor e o que você adicionou via código.

📔 Nota: O segundo abacate existe apenas no seu código. Ele aparece quando você executa a scene, mas o canvas do Scene Editor e a entity tree não conseguem exibir entities criadas em index.ts. Não se assuste se você não o vir no editor. Este é um ponto-chave a ter em mente quando você combina edição visual com código.

Ambos os abacates são construídos com as mesmas peças. Selecione o primeiro abacate no Scene Editor: o painel de propriedades mostra um Transform e um GltfContainer component com os mesmos tipos de campos que você acabou de escrever no código. São duas visões da mesma coisa.

Adicione interatividade com um Script

Vamos fazer um abacate responder ao player. Poderíamos fazer isso adicionando código no index.ts que já estávamos editando, mas em vez disso vamos usar o Script component: uma forma de anexar código diretamente a um item no Scene Editor. Ela mantém o comportamento de cada item autocontido, e você pode até reutilizar o mesmo script em vários itens.

No Scene Editor, selecione o primeiro abacate (o que você arrastou; lembre-se, o abacate somente de código não fica visível aqui).
Clique no + botão na parte superior do painel de propriedades e selecione Script para adicionar um componente Script.
Clique em + Create New Script e dê a ele o nome AvocadoScript.

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

O script é uma classe com três partes principais (comentários omitidos por 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 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 componente Script no Creator Hub. Não remova src ou entity.
start() é executado uma vez, quando a scene carrega. Use-o para a configuração: criar components, registrar tratadores de click etc.
update(dt) é executado a cada frame do jogo, aproximadamente 30 vezes por segundo. Use-o para comportamento contínuo, como movimento. dt indica quantos segundos se passaram desde o último frame.

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

Vibe code sua primeira interação

Você pode escrever o código a seguir à mão, mas este é um ótimo momento para experimentar vibe coding: descrever o que você quer a um assistente de IA e deixar que ele escreva o código. A maioria dos editores de código tem um embutido, como o chat do Cursor, o GitHub Copilot no VS Code ou Claude Code. Você também pode escrever prompts fora do seu editor de código, como com o Claude Desktop ou o Claude Code na linha de comando.

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

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

Agora tente um prompt como este:

Em AvocadoScript.ts, faça o abacate registrar uma mensagem no console quando o player clicar nele.

Você deve acabar com algo assim (ou colar 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) {}
}

Ele adicionou um comportamento de click dentro da start() função. Só precisamos definir o comportamento de click uma vez, e ele reagirá cada vez que o player clicar no item. A pointerEventsSystem.onPointerDown() instrução define três coisas:

Sobre o que entity os eventos de click funcionam: aqui this.entity, o abacate que contém o script.
Um opts objeto: qual botão usar e outros argumentos opcionais que não estamos usando agora.
Uma função que é executada toda vez que a entity é clicada.

Para ver a mensagem registrada, execute o preview e abra o console clicando no ícone no canto superior direito. Você também pode alterná-lo pressionando a ` tecla. Cada vez que você clicar no abacate, verá uma nova linha aparecer:

📔 Nota: Para uma entity ser clicável, ela deve ter uma geometria de collider. O modelo usado aqui já inclui uma. Veja Colliders para soluções alternativas para modelos que não têm.

Faça o abacate desaparecer

Vamos fazer o click fazer algo mais empolgante agora! Peça ao seu assistente de IA:

Quando o abacate 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 abacate diga "Collect".

Você deve acabar com algo assim:

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, ele 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() reduz o abacate 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 click, ele criou um método collect() Isso não é obrigatório (se sua IA colocou o tween dentro da função de click, isso também funciona), mas é uma boa prática: métodos mantêm o código legível e permitem reutilizar a mesma lógica em diferentes lugares.
Para mostrar a dica "Collect" no abacate, ele definiu isso como o hoverText valor.

Execute o preview e clique no abacate: ele deve desaparecer com estilo.

📔 Nota: O abacate encolhe até o tamanho 0, mas a entity ainda existe. O ideal é excluir a entity depois que o tween terminar, para deixar sua scene mais leve. Veja Ao terminar o tween.

Executar código a cada frame

Até agora, todo o nosso código foi executado em start(). Vamos usar update() para fazer o abacate 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())
		)
	}

Você também precisará adicionar Transform e Quaternion aos imports no topo do arquivo, 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, você pode clicar nos erros marcados pelo seu editor de código e deixá-lo adicioná-los automaticamente.

A cada frame, isso gira o abacate um pouco mais. Multiplicar por dt torna o movimento suave e independente da taxa de frames: o abacate gira a 45 graus por segundo, não importa quão rápido a máquina do player seja.

Como speed é um parâmetro do constructor, ele também aparece como um campo no componente Script no Creator Hub. Clique no ícone de atualizar no canto superior direito do componente Script para vê-lo e então ajuste o valor sem tocar em nenhum código.

Cada entity armazena seu próprio valor para o Speed campo, então vários itens podem compartilhar o mesmo script, mas se comportar de maneira diferente. Experimente: copie o abacate 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 abacate agora gira em sua própria velocidade.

Scripts podem fazer muito mais, como expor actions que outros smart items podem acionar. Veja Script component para ver o panorama completo.

Referencie um item do Scene Editor

O Script component é a maneira mais fácil de dar comportamento a um único item, mas há uma alternativa: seu código em index.ts pode buscar qualquer item que você adicionou visualmente, pelo nome, usando engine.getEntityOrNullByName(). Isso é útil quando uma parte da lógica envolve vários itens, ou quando você quer tudo em um só lugar. Use o nome que aparece na entity tree.

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

💡 Dica: Você pode renomear entities clicando com o botão direito e selecionando Rename na entity tree.

export function main() {
	// avocado2 code from before
	// (...)

	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() busca uma referência à entity chamada Yellow Crate. A if (crate) verificação garante que a entity realmente existe na scene; se não houver nenhuma entity com esse nome, crate é null. Veja Reference Items para mais informações.

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

Mais tutoriais

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

Para exemplos feitos com SDK7, confira a página de Examples, que contém várias scenes pequenas.

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

Interaja com outros desenvolvedores

Visite o Decentraland Discord e o Decentraland DAO Discord para participar numa discussão animada sobre o que é possível e como no Decentraland Discord Criadores secção.

Para depurar quaisquer problemas, verifique os Resolução de problemas e debug secções. Um assistente de IA com as competências em SDK instaladas é também um ótimo companheiro de debug: cole a mensagem de erro da console, ou descreva o que não está a comportar-se como esperado, e normalmente consegue encontrar o problema no seu código. Se não encontrar uma solução, pode publicar na categoria SDK Support no Decentraland Forum.

Recursos de arte 3D

Uma boa experiência terá excelentes arte 3D para a acompanhar. Se estiver com vontade de criar esses modelos 3D você mesmo, veja a secção de modelação 3D. Mas se preferir focar-se no lado da programação ou do design de jogos, não precisa de criar os seus próprios assets! Veja Recursos Úteis para bibliotecas de assets e ferramentas de IA que pode usar para encontrar modelos 3D para a sua scene.

Publique a sua scene

Se for proprietário de um Decentraland NAME, de um nome ETH ENS ou de LAND, ou tiver permissões concedidas por alguém que as tenha, pode carregar a sua scene para Decentraland. Veja publicação.

Outras informações úteis

AnteriorPrimeiros passos

PróximoFluxo de trabalho de desenvolvimento

Atualizado há 1 mês