> 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/arquitetura/custom-components.md).

# Components Personalizados

Crie um component personalizado para lidar com dados específicos relacionados a uma entity

Os dados sobre uma entidade são armazenados nos seus [Components](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md). O SDK do Decentraland disponibiliza uma série de Components base que gerem diferentes aspetos de uma entidade, como a posição, a forma, o Material, etc. O Engine sabe como interpretar as informações contidas nestes Components e altera a forma como a entidade é renderizada assim que os respetivos valores mudam.

Se a lógica da sua Scene exigir o armazenamento de informações sobre uma entidade que não sejam geridas pelos Components predefinidos do SDK, pode criar um tipo de Component personalizado na sua Scene. Depois, pode criar [Systems](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md) que detetam alterações nestes Components e respondem em conformidade.

## Sobre a definição de Components

Para definir um novo Component, use `engine.defineComponent`. Cada Component precisa do seguinte:

* Um **componentName**: um identificador de texto único que o SDK utiliza internamente para identificar este tipo de Component. Pode ser qualquer texto, desde que seja único.
* Um **schema**: uma classe que define a estrutura dos dados contidos no Component.
* **valores predefinidos** *(opcional)*: um objeto que contém os valores predefinidos a utilizar para inicializar uma cópia do Component quando estes não forem fornecidos.

```ts
export const WheelSpinComponent = engine.defineComponent('wheelSpinComponent', {
	spinning: Schemas.Boolean,
	speed: Schemas.Float,
})
```

{% hint style="warning" %}
**📔 Nota**: os Components personalizados têm de ser sempre escritos fora da função `main()` , num ficheiro separado. Têm de ser interpretados antes da execução de `main()` . O local recomendado para os guardar é numa pasta `/components` dentro de `/src`, cada um no seu próprio ficheiro. Assim, é mais fácil reutilizá-los em projetos futuros.
{% endhint %}

Depois de definir um Component personalizado, pode criar instâncias desse Component que façam referência a entidades na Scene. Ao criar uma instância de um Component, fornece valores para cada um dos campos do schema do Component. Os valores têm de corresponder aos tipos declarados de cada campo.

```ts
// Criar Entities
const wheel1 = engine.addEntity()
const wheel2 = engine.addEntity()

// Create instances of the component
WheelSpinComponent.create(wheel1, {
	spinning: true,
	speed: 10,
})

WheelSpinComponent.create(wheel2, {
	spinning: false,
	speed: 0,
})
```

Cada entidade à qual é adicionado o Component recebe uma nova cópia deste, que contém dados específicos dessa entidade.

O seu Component personalizado também pode disponibilizar as outras funções comuns existentes nos restantes Components:

```ts
// Fetch a read only instance of the component from an entity
const readOnlyInstance = MyCustomComponent.get(myEntity)

// Fetch a mutable instance of the component from an entity
const mutableInstance = MyCustomComponent.getMutable(myEntity)

// Delete an entity's instance of the component
MyCustomComponent.deleteFrom(myEntity)
```

## Sobre o componentName

Cada Component tem de ter um nome ou identificador único que o distinga internamente. Não precisa de utilizar este identificador interno noutro local do código. Uma boa prática é usar o mesmo nome atribuído ao Component, mas começado por uma letra minúscula. O mais importante é que este identificador seja único no projeto.

Ao criar componentes que serão partilhados como parte de uma biblioteca, tenha em atenção que os nomes dos componentes da sua biblioteca não podem coincidir com os nomes de componentes do projeto onde ela será utilizada nem com os de outras bibliotecas também utilizadas por esse projeto. Para evitar o risco de conflitos, a prática recomendada é incluir o nome da biblioteca como parte da `componentName` string. Pode seguir esta fórmula: `${packageName}::${componentName}`. Por exemplo, se criar uma biblioteca`MyUtilities` que inclui um componente `MoveEntity` , defina o `componentName` desse componente como `MyUtilities::moveEntity`.

## Componentes como flags

Pode querer adicionar um componente que simplesmente assinale uma Entity para a distinguir das outras, sem o utilizar para armazenar dados. Para isso, deixe o schema como um objeto vazio.

Isto é especialmente útil ao [consultar componentes](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/querying-components.md). Um componente de flag simples pode ser usado para distinguir Entities umas das outras e evitar que o sistema percorra mais Entities do que o necessário.

```ts
export const IsEnemyFlag = engine.defineComponent('isEnemyFlag', {})
```

Pode então criar um sistema que percorra todas as Entities com este componente.

```ts
export function handleEnemies() {
	for (const [entity] of engine.getEntitiesWith(IsEnemyFlag)) {
		// fazer algo com cada Entity
	}
}

engine.addSystem(handleEnemies)
```

## Schemas dos componentes

Um schema descreve a estrutura dos dados dentro de um componente. Um componente pode armazenar tantos campos quantos quiser, mas cada um tem de estar incluído na estrutura do schema. O schema pode incluir tantos níveis de itens aninhados quantos forem necessários.

Cada campo do schema tem de incluir uma declaração de tipo. Só pode utilizar os tipos especiais de schema fornecidos pelo SDK. Por exemplo, utilize o tipo `Schemas.Boolean` em vez do tipo `boolean`. Escreva `Schemas.` e o seu IDE apresentará todas as opções disponíveis.

```ts
export const WheelSpinComponent = engine.defineComponent('WheelSpinComponent', {
	spinning: Schemas.Boolean,
	speed: Schemas.Float,
})
```

O exemplo acima define um componente cujo schema contém dois valores: um valor booleano `spinning` e um número de vírgula flutuante `speed` .

Pode optar por criar o schema inline ao definir o componente ou, para maior legibilidade, criá-lo separadamente e depois fazer referência a ele.

```ts
// Opção 1: definição inline
export const WheelSpinComponent = engine.defineComponent('WheelSpinComponent', {
	spinning: Schemas.Boolean,
	speed: Schemas.Float,
})

// Opção 2: definir o schema e o componente separadamente

//// schema
const mySchema = {
	spinning: Schemas.Boolean,
	speed: Schemas.Float,
}

//// componente
export const WheelSpinComponent = engine.defineComponent(
	'WheelSpinComponent',
	mySchema
)
```

{% hint style="info" %}
**💡 Dica**: Ao criar uma instância de um componente, as opções de preenchimento automático do Visual Studio sugerem os campos que pode adicionar ao componente quando premir *Ctrl + Space*.
{% endhint %}

### Tipos de schema predefinidos

Estão disponíveis os seguintes tipos básicos para utilização nos campos de um schema:

* `Schemas.Boolean`
* `Schemas.Byte`
* `Schemas.Double`
* `Schemas.Float`
* `Schemas.Int`
* `Schemas.Int64`
* `Schemas.Number`
* `Schemas.Short`
* `Schemas.String`
* `Schemas.Entity`

Também existem os seguintes tipos complexos. Cada um inclui uma série de propriedades aninhadas com valores numéricos.

* `Schemas.Vector3`
* `Schemas.Quaternion`
* `Schemas.Color3`
* `Schemas.Color4`

{% hint style="info" %}
**💡 Sugestão**: consulte [Tipos de geometria](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/special-types.md) e [Tipos de cor](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/color-types.md) para saber mais sobre a utilidade destes tipos de dados.
{% endhint %}

Por exemplo, pode utilizar estes tipos de schema num componente como este para acompanhar o movimento gradual de uma Entity. Este componente armazena uma posição inicial e uma posição final como valores Vector3, bem como a velocidade e a fração do percurso concluído como números float. Consulte [Mover Entities](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/move-entities.md#move-between-two-points) para ver a implementação completa deste exemplo.

```ts
const MoveTransportData = {
	start: Schemas.Vector3,
	end: Schemas.Vector3,
	fraction: Schemas.Float,
	speed: Schemas.Float,
}

export const LerpTransformComponent = engine.defineComponent(
	'LerpTransformComponent',
	MoveTransportData
)
```

### Tipos de array

Para definir o tipo de um campo como array, utilize `Schemas.Array()`. Passe o tipo dos elementos do array como propriedade.

```ts
const MySchema = {
	numberList: Schemas.Array(Schemas.Int),
}
```

Quando lê um campo de array com `MyComponent.get()`, o array é só de leitura. Métodos que o alteram diretamente, como `.push()`, não estão disponíveis. Utilize `MyComponent.getMutable()` quando precisar de alterar o conteúdo.

### Campos opcionais

Utilize `Schemas.Optional()` para permitir que um campo contenha um valor ou `undefined`.

```ts
const MySchema = {
	playerId: Schemas.Optional(Schemas.String),
	score: Schemas.Optional(Schemas.Int),
}
```

Apenas `undefined` é considerado «não definido». Valores falsy, como `false`, `0`, e `''` são armazenados e lidos exatamente como foram escritos.

### Tipos de esquema aninhados

Para definir o tipo de um campo como objeto, utilize `Schemas.Map()`. Passe o conteúdo deste objeto como uma propriedade. Este objeto aninhado é, essencialmente, um esquema por si só, aninhado no esquema principal.

```ts
const MySchema = {
	simpleField: Schemas.Boolean,
	myComplexField: Schemas.Map({
		nestedField1: Schemas.Boolean,
		nestedField2: Schemas.Boolean,
	}),
}
```

Em alternativa, para tornar o código mais legível e reutilizável, pode obter o mesmo resultado definindo o esquema aninhado separadamente e, em seguida, referenciando-o ao definir o esquema principal.

```ts
const MyNestedSchema = Schemas.Map({
	nestedField1: Schemas.Boolean,
	nestedField2: Schemas.Boolean,
})

const MySchema = {
	simpleField: Schemas.Boolean,
	myComplexField: MyNestedSchema,
}
```

### Tipos enum

Pode definir o tipo de um campo de um esquema como um enum. Os enums facilitam a seleção entre um número finito de opções, fornecendo valores legíveis por humanos para cada uma.

Para definir o tipo de um campo como enum, primeiro tem de definir o enum. Depois, pode referenciar o enum com `Schemas.EnumNumber` ou `Schemas.EnumString`, consoante o tipo de enum. Estas funções recebem dois parâmetros: o enum a referenciar e um valor predefinido a utilizar para este campo.

```ts
//// Enum de strings

// Definir enum
enum Color {
	Red = 'red',
	Green = 'green',
	Pink = 'pink',
}

// Definir um componente que utiliza este enum num campo
const ColorComponent = engine.defineComponent('Color', {
	color: Schemas.EnumString<Color>(Color, Color.Red),
})

// Utilizar o componente numa entidade
ColorComponent.create(engine.addEntity(), { color: Color.Green })

//// Enum numérico

// Definir enum
enum CurveType {
	LINEAR,
	EASEIN,
	EASEOUT,
}

// Definir um componente que utiliza este enum num campo
const CurveComponent = engine.defineComponent('curveComponent', {
	curve: Schemas.EnumNumber<CurveType>(CurveType, CurveType.LINEAR),
})

// Utilizar o componente numa entidade
CurveComponent.create(engine.addEntity(), { curve: CurveType.EASEIN })
```

### Tipos intercambiáveis

Pode definir o tipo de um campo num esquema para seguir um padrão `oneOf` , que permite aceitar diferentes tipos.

```ts
const MySchema = {
	myField: Schemas.OneOf({ type1: Schemas.Vector3, type2: Schemas.Quaternion }),
}

export const MyComponent = engine.defineComponent('MyComponent', MySchema)
```

Ao criar uma instância do componente, tem de especificar o tipo selecionado com `$case`, por exemplo:

```ts
MyComponent.create(myEntity, {
	myField: {
		$case: 'type1',
		value: Vector3.create(1, 1, 1),
	},
})
```

Também é válido deixar o campo sem definir. Um `OneOf` campo não tem `$case` e é lido de volta como um objeto vazio, `{}`.

### Componentes de um único tipo

Um componente não precisa conter um objeto com vários campos. Para definir um que contenha um único valor, use `engine.defineComponentFromSchema()` e passe o tipo diretamente:

```ts
// Um componente que contém um número por entidade
export const Score = engine.defineComponentFromSchema('my-scene::Score', Schemas.Int)

// Um componente que contém uma lista de números por entidade
export const History = engine.defineComponentFromSchema(
	'my-scene::History',
	Schemas.Array(Schemas.Int)
)
```

Eles se comportam como qualquer outro componente, inclusive quando o valor armazenado é falsy. Um `Score` de `0` é um componente que existe e contém `0`, não um componente ausente.

## Valores padrão

Muitas vezes, é útil ter valores padrão nos componentes, para que não seja necessário definir explicitamente cada valor sempre que você criar uma nova cópia.

A função `engine.defineComponent()` recebe um terceiro argumento, que permite passar um objeto com os valores padrão a serem usados. Esse objeto pode incluir alguns ou todos os valores do schema. Os campos não abrangidos pelos valores padrão nem pelos valores fornecidos ao inicializar uma cópia do componente são inicializados com um valor semelhante a zero, como `0`, `false`, ou com uma string vazia, dependendo do tipo.

```ts
// Definição

//// schema
const mySchema = {
	spinning: Schemas.Boolean,
	speed: Schemas.Float,
}

//// valores padrão
const myDefaultValues = {
	spinning: true,
	speed: 1,
}

//// componente
export const WheelSpinComponent = engine.defineComponent(
	'WheelSpinComponent',
	mySchema,
	myDefaultValues
)

// Uso
export function main() {
	//// Criar entidades
	const wheel = engine.addEntity()
	const wheel2 = engine.addEntity()

	//// inicializar o componente usando valores padrão
	WheelSpinComponent.create(wheel)

	//// inicializar o componente com um valor personalizado e usar os valores padrão para os demais
	WheelSpinComponent.create(wheel2, { speed: 5 })
}
```

O exemplo acima cria um componente `WheelSpinComponent` que inclui um schema e um conjunto de valores padrão. Se você inicializar uma cópia desse componente sem especificar nenhum valor, ela usará os valores definidos como padrão.

## Subscrever alterações

Um caso de utilização comum é executar uma função apenas quando os dados de um determinado componente são alterados. Use a função [OnChange](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/subscribe-to-changes.md) para evitar ter de definir um sistema e comparar explicitamente os valores antigos com os novos.

```ts
export function main() {
	//Criar entidade etc.

	WheelSpinComponent.onChange(myEntity, (componentData) => {
		if (!componentData) return
		console.log(componentData.speed)
		console.log(componentData.spinning)
	})
}
```

## Criar Systems que usam um componente

Com o componente definido e adicionado às entidades na sua cena, você pode criar [Systems](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md) para executar a lógica, utilizando os dados armazenados no componente.

```ts
// define component
export const WheelSpinComponent = engine.defineComponent('WheelSpinComponent', {
	spinning: Schemas.Boolean,
	speed: Schemas.Float,
})

// Uso
export function main() {
	// Criar Entities
	const wheel1 = engine.addEntity()
	const wheel2 = engine.addEntity()

	// Create instances of the component
	WheelSpinComponent.create(wheel1, {
		spinning: true,
		speed: 10,
	})

	WheelSpinComponent.create(wheel2, {
		spinning: false,
		speed: 0,
	})
}

// Define a system to iterate over these entities
export function spinSystem(dt: number) {
	// iterate over all entiities with a WheelSpinComponent
	for (const [entity, wheelSpin] of engine.getEntitiesWith(
		WheelSpinComponent
	)) {
		// only do something if spinning == true
		if (wheelSpin.spinning) {
			// fetch a mutable Transform component
			const transform = Transform.getMutable(entity)

			// update the rotation value accordingly
			transform.rotation = Quaternion.multiply(
				transform.rotation,
				Quaternion.fromAngleAxis(dt * wheelSpin.speed, Vector3.Up())
			)
		}
	}
}

// Adicionar o sistema ao engine
engine.addSystem(spinSystem)
```

O exemplo acima define um sistema que percorre todas as entidades que incluem o componente personalizado `wheelSpinComponent`, e as roda ligeiramente a cada tick do loop do jogo. A amplitude dessa rotação é proporcional ao valor de `speed` armazenado na instância do componente de cada entidade. O exemplo utiliza [consultas de componentes](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/querying-components.md) para obter apenas as entidades relevantes.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/custom-components.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
