Início Rápido do SDK

Introdução ao SDK do Decentraland

O Decentraland SDK é uma ferramenta poderosa que permite criar ou aprimorar suas cenas escrevendo código em TypeScript (JavaScript + Types).

💡 Tip: Se preferir criar suas cenas apenas com ferramentas no-code, veja Scene Editor in Creator Hub.

Este tutorial orienta você sobre como se configurar e mostra os conceitos básicos para escrever código em uma cena do Decentraland.

Instale o Creator Hub

O Creator Hub permite que você construa, visualize e publique cenas do Decentraland. Baixe o Creator Hub aqui.

Para editar o código da sua cena, você também deve instalar Visual Studio Code, se ainda não o tiver.

Leia Guia de instalação para mais detalhes sobre a instalação do Creator Hub.

Crie sua primeira cena

Para criar sua primeira cena, siga estes passos.

1. Abra o Creator Hub.

2. Selecione a Scenes guia, e clique Criar Cena.

   

   
   
3. Você poderá então escolher entre diferentes templates iniciais. Para este exercício, escolha o Cena Vazia.

Esta etapa pode levar alguns minutos. Ela popula sua pasta com o conjunto padrão de arquivos para uma cena básica.

Quando isso terminar, você verá a grade vazia da sua cena.

Adicione itens a partir dos asset packs

Explore o Asset packs na seção inferior do Scene Editor no Creator Hub, arraste alguns itens e ajuste suas posições. Para este tutorial, quaisquer itens servirão por enquanto.

Para colocar um item, clique e arraste-o do menu do asset pack para um local na sua cena na tela.

Um item já colocado pode ser clicado e arrastado para reposicioná-lo livremente. Veja Scene editor essentials para mais detalhes.

💡 Tip: Cubra toda a cena com um item de ground. Itens do tipo Ground têm um ícone de balde de tinta. Se você arrastar um desses para sua cena, ele cobre todo o ground da sua cena com cópias desse item.

Executar uma pré-visualização

Clique no Visualizar botão no menu superior para carregar sua cena dentro do Decentraland. Você agora pode explorar a cena como um avatar do Decentraland.

Saiba mais sobre a visualização da cena em pré-visualizar uma cena.

💡 Tip: Você pode manter a janela de pré-visualização aberta enquanto continua trabalhando na sua cena, e ela será atualizada cada vez que você fizer uma alteração no Scene Editor.

Assets 3D personalizados

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

1. Clique no sinal de mais no canto superior direito da seção Asset Packs da UI do Scene Editor.

2. Arraste o avocado.glb arquivo para a região na UI do Scene Editor e clique Import.

   

   
   

Agora você pode encontrar o avocado.glb modelo na Local Assets guia, dentro da Scene pasta. Arraste-o para sua cena, como faria com qualquer item dos Asset Packs.

Edite o código da cena

As próximas seções descrevem como você pode editar o código da sua cena, dando muito mais liberdade como criador.

Clique no <> Código botão no menu superior para abrir seu projeto de cena no Visual Studio Code.

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

Isso abre uma janela separada com o Visual Studio Code. Na margem esquerda você pode navegar pelos arquivos e pela estrutura de pastas do seu projeto.

Abra o index.ts arquivo dentro da pasta src na sua cena. Seu conteúdo deve se parecer com isto:

Versões do SDK
import { engine } from '@dcl/sdk/ecs'

export function main() {}

As duas primeiras linhas tratam de import declarações. Elas buscam referências a coisas que estão definidas em outros arquivos, para que possam ser usadas neste arquivo. Você não precisará lidar diretamente com essas linhas neste tutorial, mas note que a lista de coisas sendo importadas crescerá conforme você escrever seu código.

Observe que este arquivo define uma função chamada main(). Esta função é o ponto de entrada da cena, qualquer código que você colocar ali será executado quando a cena for carregada pela primeira vez. Se você escrever linhas de código fora dessa função, elas nunca serão executadas.

Na seção anterior mostramos como você pode facilmente arrastar o modelo 3D personalizado de abacate para sua cena de forma no-code. Agora adicionaremos um segundo abacate, para ver como alcançar o mesmo escrevendo código.

Substitua o conteúdo completo do seu index.ts arquivo pelo seguinte. Essas linhas expandem a main() função e adicionam alguns imports:

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 a ela um Transform
	Transform.create(avocado2, {
		position: Vector3.create(8, 0, 8),
	})

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

Se você abrir a pré-visualização da cena novamente, agora deverá ver dois abacates: o que você adicionou no Scene Editor e o que você adicionou via código.

As linhas que você acabou de adicionar criam um novo entity, dão a ele um shape baseado no modelo 3D que você baixou, e definem sua posição e escala através da Transform.

Agora volte ao Scene Editor e selecione o primeiro abacate que você adicionou. No painel de propriedades deste item você verá que a UI para os componentes Transform e GLTF mostra as mesmas informações que no código que você acabou de escrever.

Adicione interatividade

Para tornar sua cena mais envolvente, vamos fazer com que as entidades na cena respondam às interações do jogador.

No final da main() função (antes de ser fechada pelo último }), adicione um manipulador de eventos de pointer à entidade abacate. Isso executa uma função personalizada toda vez que o jogador clicar no abacate.

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

💡 Tip: O Visual Studio Code ajuda marcando erros de sintaxe, autocompletando enquanto você escreve e até mostrando sugestões inteligentes que dependem do contexto. Você também pode clicar em um objeto para ver a definição completa de sua classe.

Se alguma das palavras que você colou estiver sublinhada em vermelho, passe o cursor sobre ela para ver se o VS Code oferece uma solução fácil. Você provavelmente terá que fazer isso para pointerEventsSystem, e InputAction.

Clicar na lâmpada sugerirá Atualizar import de @dcl/sdk/ecs. Selecione esta opção para adicionar imports no início do seu index.ts arquivo.

O pointerEventsSystem.onPointerDown() declaração define três coisas:

• O que entity os eventos de pointer atuam sobre.

• Um opts objeto com parâmetros opcionais adicionais. Neste caso incluímos qual botão usar e qual texto de dica exibir.

• Uma função, que será executada toda vez que a entidade for clicada.

Neste caso, a função que estamos executando é muito simples. É apenas uma linha e simplesmente imprime algum texto no console.

console.log('CLICKED AVOCADO')

No opts na seção, estamos definindo o button campo para que ele escute o botão do pointer (o botão esquerdo do mouse em um PC). Também estamos definindo o parâmetro hoverText para exibir um 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 chegaremos lá nos próximos passos.

Para ver a mensagem que o evento de clique está registrando, você precisará abrir o console. Para isso, abra a pré-visualização da cena novamente se ainda não a tiver em execução, e pressione a tecla ` para alternar a exibição do console. Agora cada vez que você clicar no abacate que adicionou via código, verá:

**📔 Nota**: Para que uma entidade seja clicável, ela deve ter uma geometria de collider. O modelo usado aqui já inclui uma. Veja a seçã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 função de clique faça algo mais interessante: vamos fazer o abacate desaparecer. Use `

engine.removeEntity()` para se livrar do abacate uma vez que ele for clicado. Vamos adicionar uma linha extra ao nosso trecho:

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

Agora, quando clicado, o abacate desaparece da sua cena.

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 adicionando um tween de escala ao nosso abacate, apenas para experimentar o recurso. Adicione as seguintes linhas dentro da main() função, no final, sem mudar nada do que você já adicionou:

export function main() {
	// Código dos trechos anteriores (não alterar)
	// (...)

	// Novo código:
	Tween.setMove(avocado2, 
		Vector3.create(3, 0, 3), 
		Vector3.create(8, 0, 8), 
		5000
	)

}

💡 Tip: Ao colar isso, você pode encontrar mais palavras sublinhadas em vermelho por causa de imports faltando.

Passe o cursor sobre cada uma e clique na lâmpada, ela sugerirá Atualizar import de @dcl/sdk/ecs. Selecione esta opção para adicionar imports no início do seu index.ts arquivo.

O Tween o componente que criamos tem argumentos que fazem com que ele mude de posição, de uma posição nas coordenadas 3,0,3 da cena, para as coordenadas 8,0,8, ao longo de um período de 5000 milissegundos (5 segundos). Este movimento começará assim que a cena iniciar.

A Tween a função setMove requer as seguintes informações:

• entity: Em qual entidade trabalhar

• start: Posição inicial.

• end: Posição final.

• duration: Duração (em milissegundos) da mudança do início ao fim.

Este outro parâmetro opcional também está disponível:

• easingFunction: Que tipo de curva usar para controlar a taxa de mudança ao longo do tempo. Neste caso usamos linear, o que resulta em uma mudança constante e suave.

Podemos brincar com o parâmetro easingFunction para obter alguns efeitos interessantes. Por exemplo, podemos em vez disso usar EF_EASEINBOUNCE para executar a transição usando uma interpolação ease-in bounce, que começa com um efeito saltitante e depois vai de devagar para rápido.

💡 Tip: Você também pode usar o Tween componente para escalar ou rotacionar uma entidade ao longo de um período de tempo; esta é uma ferramenta realmente útil! Saiba mais aqui

Usando suas próprias funções

Nesta seção adicionaremos outro tween na escala do Abacate, para tornar o efeito de desaparecimento mais atraente. Mas adotaremos uma abordagem um pouco menos direta para introduzir alguns outros conceitos.

A maneira mais simples de fazer nosso abacate encolher quando clicamos nele é adicionar um tween dentro da função de eventos de pointer, em vez da linha engine.removeEntity(avocado2). Mas, em vez disso, vamos criar este tween em uma função separada que possamos reutilizar para outros itens. Assim não precisaremos escrever o mesmo código duas vezes! Nossa nova função será separada de main(), então ela não fará nada por si só, mas em breve a chamaremos.

function collect(myEntity: Entity) {

	Tween.setScale(myEntity, 
		Vector3.One(), 
		Vector3.Zero(), 
		500,
		EasingFunction.EF_EASEINBOUNCE
	)
}

Observe que o tween é adicionado a uma entidade chamada myEntity, em vez de avocado2. myEntity é realmente um placeholder, não há uma entidade com esse nome na cena. Ele vem de um parâmetro definido na função. Quando você chamar a função collect() , você pode passar qualquer entidade na cena, e ela aplicará um Tween a ela. Mais sobre isso depois.

💡 Tip: Sempre que houver código que você possa usar várias vezes na sua cena, é uma boa prática colocá-lo dentro de uma função. Dessa forma você só precisa escrevê-lo uma vez, e fica mais fácil de manter.

Aqui criamos um Tween que afeta o Escala, então agora start e end referem-se ao tamanho do abacate, não à posição. Vai de um tamanho de um para zero, durante uma duração de 500 milissegundos (meio segundo), e usa uma EASEINBOUNCE função de easing, que lhe dá um efeito saltitante divertido.

Agora vamos modificar a função que escrevemos para quando clicamos no abacate. Vamos mudar a linha que diz engine.removeEntity(avocado), e em vez disso vamos chamar a função collect() que acabamos de definir, passando uma referência para nossa entidade abacate:

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

		collect(avocado2)
	}
)

Se você agora abrir a pré-visualização da cena e clicar no abacate, deverá vê-lo desaparecer com estilo, executando um movimento divertido e saltitante.

📔 Nota: Você pode ter percebido que agora o abacate encolhe até um tamanho 0, mas ainda existe. Não cobriremos isso neste primeiro tutorial, mas em um cenário ideal você deve garantir que exclua a entidade após o tween terminar, para otimizar o desempenho da sua cena. Veja Ao finalizar um tween.

Referenciar um item do Scene Editor

Seu código também pode fazer coisas com os itens que você adicionou visualmente no Scene Editor do Creator Hub. Você pode buscar esses itens por nome no seu código, usando a função engine.getEntityOrNullByName(). Use o nome do item que você vê escrito na entity tree.

Nesta exemplo, temos uma entidade chamada Yellow Crate. Você pode usar qualquer item que quiser, apenas certifique-se de escrever seu nome exatamente como aparece na árvore de entidades.

💡 Tip: Você pode renomear entidades clicando com o botão direito e selecionando Rename na entidade na árvore de entidades.

export function main() {
	// Coisas do Abacate

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

	if (crate) {
		console.log('A caixa existe')
	}
}

No trecho acima, usamos engine.getEntityOrNullByName() para buscar uma referência a uma entidade chamada Yellow Crate. Na linha seguinte, fazemos if (crate) para garantir que realmente exista uma entidade com esse nome na cena. Se não houver, então o valor de crate será null. Veja Itens de Referência para mais informações.

💡 Tip: Todas as entidades adicionadas via Scene Editor já estarão carregadas em sua cena quando a função main() for chamada. Deve ser seguro referenciá-las nessa função, ou em outras funções que sejam chamadas indiretamente por ela.

Agora vamos adicionar um comportamento de pointer à nossa entidade Yellow Crate, assim como fizemos com o abacate.

export function main() {
	// Coisas do Abacate

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

	if (crate) {
		console.log('A caixa existe')

		pointerEventsSystem.onPointerDown(
			{
				entity: crate,
				opts: { button: InputAction.IA_POINTER, hoverText: 'Collect' },
			},
			function () {
				console.log('CAIXA CLICADA')
				collect(crate)
			}
		)
	}
}

Observe como estamos chamando a função collect() que definimos antes. Como a função é definida separadamente, só foi preciso escrever aquela linha para chamá-la!

💡 Tip: Você também pode buscar Smart Items da sua cena da mesma maneira, e fazer o que quiser com eles via código. Veja Itens de Referência para mais informações.

Mais Tutoriais

Leia coding-scenes para uma compreensão em alto nível de como as cenas do Decentraland funcionam.

Para exemplos construídos com SDK7, confira o page de Examples que contém várias cenas pequenas, todas escritas com SDK7.

Veja o Guia de desenvolvimento seção para mais instruções sobre adicionar conteúdo à sua cena.

Interaja com outros desenvolvedores

Visite O Discord do Decentraland quanto a Decentraland DAO Discord, para entrar em uma discussão animada sobre o que é possível e como!

Para depurar quaisquer problemas, incentivamos que você verifique as Solução de problemas e seções de debug na documentação. Se não encontrar uma solução lá, você pode postar issues na categoria de Suporte do SDK no Fórum Decentraland.

Você também pode postar no Stack Overflow, usando as tags decentraland ou decentraland-ecs.

Você também pode perguntar no Discord do Decentralnad. Na seção Suporte o canal #sdk é para perguntas relacionadas a código, o canal #builder-and-3d é para perguntas relacionadas a modelos 3D e arte. #code-contribution é para discutir PRs para a base de código do SDK.

No Decentraland DAO Discord você também pode obter ajuda no canal sdk-support .

Assets de Arte 3D

Uma boa experiência terá uma ótima arte 3D para acompanhá-la. Se você estiver interessado em criar esses modelos 3D por conta própria, é incentivado que o faça, veja a seção de Modelagem 3D para mais informações. Mas se preferir focar no lado de codificação ou design de jogos, você não precisa criar seus próprios assets!

Aqui estão algumas fontes para obter ótimos modelos 3D que você pode usar em uma cena do Decentraland:

• IWB Catalog

• Asset Ovi

• SketchFab

• Clara.io

• Archive3D

• SketchUp 3D Warehouse

• Thingiverse

• ShareCG

• CGTrader

Você também pode usar ferramentas de IA Generativa para gerar seus próprios modelos 3D. Confira:

• Meshy

• Luma AI

• TRipo3D

• Rodin

📔 Nota: Modelos devem estar nos .gltf ou .glb formatos suportados, e devem ter um número de triângulos, texturas e materiais que obedecem ao limitações da cena. Se estiver obtendo modelos de um site de terceiros, preste atenção às restrições de licença do conteúdo que você baixa.

Publique sua cena

Se você possuir LAND, um NAME do Decentraland, ou um nome ENS em ETH, ou tiver permissões concedidas por alguém que possua, você pode fazer upload da sua cena para o Decentraland. Veja publicação.

Outras informações úteis

• Bibliotecas

• Restrições de design para jogos

• Modelagem 3D

• Scene limitations