SDK Quick Start

Começar com o SDK do Decentraland

O SDK da Decentraland é uma ferramenta poderosa que lhe permite criar ou melhorar as suas scenes escrevendo código em Typescript (Javascript + Types).

💡 Dica: Se preferir criar as suas scenes apenas com ferramentas no-code, veja Scene Editor no Creator Hub.

💡 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.

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.

Para editar o código da sua scene, também tem de instalar Visual Studio Code, se ainda não o tiver.

Lê Guia de instalação 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 para mais detalhes.

💡 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.

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.

💡 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.

Assets 3D personalizados

Descarregue este modelo 3D de um abacate em formato glb a partir do seguinte link 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.

📔 Nota: Instalar Visual Studio Code, se ainda não o tiver.

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:

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:

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, dão-lhe um shape com base no modelo 3D que descarregou, e definem a sua posição e escala 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.

pointerEventsSystem.onPointerDown(
	{
		entity: avocado2,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Collect' },
	},
	function () {
		console.log('CLICKED AVOCADO')
	}
)

💡 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 pointerEventsSysteme 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.

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.

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á:

**📔 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.

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:

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:

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
	)

}

💡 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.

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.

💡 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

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.

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.

💡 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.

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:

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.

📔 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.

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.

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.

💡 Dica: Pode renomear entities clicando com o botão direito e selecionando Rename na entity da entity tree.

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 para mais informações.

💡 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.

Agora vamos adicionar um comportamento de ponteiro à nossa entity Yellow Crate, tal como fizemos com o abacate.

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!

💡 Dica: Também pode obter Smart Items da sua scene da mesma forma, e fazer o que quiser com eles via código. Veja Reference Items para mais informações.

Mais tutoriais

Lê coding-scenes 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 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 como as Decentraland DAO Discord, 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 e debug na documentação. Se não encontrar aí uma solução, pode publicar problemas na categoria SDK Support do Decentraland Forum.

Também pode publicar no Stack Overflow, usando as tags decentraland ou decentraland-ecs.

Também pode perguntar no Decentralnad 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 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 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

• Asset Ovi

• SketchFab

• Clara.io

• Archive3D

• SketchUp 3D Warehouse

• Thingiverse

• ShareCG

• CGTrader

Você também pode usar ferramentas de Generative AI para gerar os seus próprios modelos 3D. Veja:

• Meshy

• Luma AI

• TRipo3D

• Rodin

📔 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. Ao obter modelos de um site de terceiros, preste atenção às restrições de licença do conteúdo que descarrega.

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.

Outras informações úteis

• Libraries

• Restrições de design para jogos

• 3D modeling

• Scene limitations