> 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/fundamentos-de-conteudo-3d/particle-system.md).

# Sistema de Partículas

Adicione efeitos de partículas como fogo, chuva, faíscas e auras mágicas à sua scene

Os sistemas de partículas permitem criar efeitos visuais dinâmicos emitindo e animando grandes quantidades de pequenos sprites. Use-os para criar fogo, fumaça, chuva, neve, faíscas, auras mágicas, explosões e muitos outros efeitos que seriam impraticáveis de obter com meshes estáticos.

## Adicionar um sistema de partículas

Para adicionar um sistema de partículas à sua cena, crie uma entidade e associe a ela o componente `ParticleSystem` .

```ts
import { engine, Transform, ParticleSystem } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

const emitter = engine.addEntity()

Transform.create(emitter, {
	position: Vector3.create(8, 1, 8),
})

ParticleSystem.create(emitter, {})
```

Sem definir propriedades, o componente usa todos os valores predefinidos: um emissor pontual que lança 10 partículas por segundo, com uma duração de vida de 5 segundos para cada partícula.

## Formas do emissor

A forma do emissor determina onde as partículas surgem. Estão disponíveis quatro formas através dos auxiliares `ParticleSystem.Shape` .

### Ponto

As partículas surgem de um único ponto (a posição da entidade). Esta é a forma predefinida quando nenhuma forma é especificada.

```ts
ParticleSystem.create(emitter, {
	shape: ParticleSystem.Shape.Point(),
})
```

### Esfera

As partículas surgem na superfície ou no interior de uma esfera.

```ts
ParticleSystem.create(emitter, {
	shape: ParticleSystem.Shape.Sphere({ radius: 2 }),
})
```

### Cone

As partículas surgem na base de um cone e deslocam-se para fora, na direção do cone. `angle` é o semiângulo em graus; `radius` é o raio da base em metros. Para orientar a direção do cone, defina a rotação da entidade `Transform`.

```ts
ParticleSystem.create(emitter, {
	shape: ParticleSystem.Shape.Cone({ angle: 25, radius: 1 }),
})
```

### Caixa

As partículas surgem em qualquer ponto dentro do volume de uma caixa.

```ts
ParticleSystem.create(emitter, {
	shape: ParticleSystem.Shape.Box({ size: Vector3.create(3, 1, 3) }),
})
```

## Propriedades de emissão

Controle quantas partículas são criadas e durante quanto tempo vivem.

| Propriedade    | Predefinição | Descrição                                                     |
| -------------- | ------------ | ------------------------------------------------------------- |
| `rate`         | `10`         | Número de partículas emitidas por segundo (emissão contínua). |
| `maxParticles` | `1000`       | Limite máximo de partículas vivas em simultâneo.              |
| `lifetime`     | `5`          | Tempo de vida de cada partícula, em segundos.                 |
| `active`       | `true`       | Indica se o sistema está a emitir partículas novas.           |

```ts
ParticleSystem.create(emitter, {
	rate: 50,
	maxParticles: 500,
	lifetime: 3,
})
```

## Movimento

### Gravidade

A `gravity` A propriedade é um multiplicador aplicado à gravidade da cena (-9.81 m/s²). Defina-o como `0` para fazer as partículas flutuarem no mesmo lugar, um valor negativo para impulsioná-las para cima ou um valor positivo para acelerá-las para baixo.

```ts
ParticleSystem.create(emitter, {
	gravity: -0.5, // particles float slowly upward
})
```

### Velocidade inicial

`initialVelocitySpeed` é um `FloatRange` que define um mínimo e um máximo para o intervalo aleatório de velocidade com que cada partícula é lançada (em m/s). Ambos os valores são, por padrão, `1`.

```ts
ParticleSystem.create(emitter, {
	initialVelocitySpeed: { start: 2, end: 8 },
})
```

### Força adicional

Um vetor de força constante aplicado a todas as partículas a cada frame, além da gravidade. Útil para efeitos de vento ou magnetismo.

```ts
ParticleSystem.create(emitter, {
	additionalForce: Vector3.create(0.5, 0, 0), // constant sideways push
})
```

### Limitação de velocidade

Use `limitVelocity` para limitar a velocidade máxima das partículas e, opcionalmente, atenuar o excesso de velocidade a cada frame.

```ts
ParticleSystem.create(emitter, {
	limitVelocity: {
		speed: 5, // maximum allowed speed in m/s
		dampen: 0.8, // fraction of excess velocity removed per frame
	},
})
```

## Propriedades visuais

### Cor

`initialColor` define a cor da partícula ao nascer, escolhida aleatoriamente dentro do intervalo especificado. `colorOverTime` faz a cor da partícula transitar gradualmente do valor `start` para o valor `end` ao longo do tempo de vida da partícula. Ambos aceitam um `ColorRange` com um valor de `start` e um valor de `end` .

```ts
import { Color4 } from '@dcl/sdk/math'

ParticleSystem.create(emitter, {
	initialColor: {
		start: Color4.create(1, 0.5, 0, 1), // orange
		end: Color4.create(1, 1, 0, 1), // yellow
	},
	colorOverTime: {
		start: Color4.create(0.5, 0, 0, 0.5), // dim red, half transparent
		end: Color4.create(0, 0, 0, 0), // fully transparent (fade out)
	},
})
```

Note que o 4.º valor de um `Color4` é o *alpha*. Se definir a cor final com um alpha de 0, as partículas desaparecerão gradualmente, tornando-se invisíveis, o que costuma produzir um bom efeito.

### Tamanho

`initialSize` e `sizeOverTime` são `FloatRange` valores. `initialSize` controla a escala da partícula ao surgir, escolhida aleatoriamente dentro do intervalo indicado. `sizeOverTime` faz com que a escala da partícula transite gradualmente de `start` para o valor `end` ao longo da vida útil da partícula. Um valor de `1` equivale ao tamanho original da textura.

```ts
ParticleSystem.create(emitter, {
	initialSize: { start: 0.1, end: 0.3 },
	sizeOverTime: { start: 0.5, end: 1.0 }, // crescer ao longo da vida útil
})
```

{% hint style="warning" %}
**📔 Nota**: A `scale` da entidade `Transform` não afeta a escala das partículas.
{% endhint %}

### Textura

Por predefinição, as partículas são renderizadas como quadrados brancos. Forneça uma textura para usar uma imagem personalizada.

```ts
ParticleSystem.create(emitter, {
	texture: { src: 'assets/scene/Images/spark.png' },
})
```

### Modo de mistura

Controla como a cor da partícula é composta com a cena ao fundo.

| Valor                                  | Descrição                                                                   |
| -------------------------------------- | --------------------------------------------------------------------------- |
| `ParticleSystemBlendMode.PSB_ALPHA`    | Transparência padrão (predefinição).                                        |
| `ParticleSystemBlendMode.PSB_ADD`      | Mistura aditiva — as partículas iluminam a cena. Ideal para fogo e brilhos. |
| `ParticleSystemBlendMode.PSB_MULTIPLY` | Multiplica a cor da partícula pela cor da cena ao fundo.                    |

```ts
import { ParticleSystemBlendMode } from '@dcl/sdk/ecs'

ParticleSystem.create(emitter, {
	texture: { src: 'assets/scene/textures/ember.png' },
	blendMode: ParticleSystemBlendMode.PSB_ADD,
})
```

### Billboard

Quando `billboard` é `true` (a predefinição), cada partícula está sempre virada para a câmara, independentemente da orientação do emissor. Defina como `false` para partículas que devem rodopiar no espaço 3D.

```ts
ParticleSystem.create(emitter, {
	billboard: false,
})
```

## Rotação

### Rotação inicial e rotação ao longo do tempo

`initialRotation` é a orientação da partícula quando surge. `rotationOverTime` é uma velocidade angular por eixo aplicada a cada segundo. Ambos aceitam um `Quaternion`.

```ts
import { Quaternion } from '@dcl/sdk/math'

ParticleSystem.create(emitter, {
	initialRotation: Quaternion.fromEulerDegrees(0, 0, 45),
	rotationOverTime: Quaternion.fromEulerDegrees(0, 0, 90), // rodar 90°/s no eixo Z
})
```

{% hint style="warning" %}
**📔 Nota**: Se `billboard` estiver definido como `true`, as partículas só rodam num eixo, mantendo sempre a orientação voltada para a câmara.
{% endhint %}

### Virado na direção do movimento

Quando `faceTravelDirection` é `true`, cada partícula roda automaticamente para apontar na direção do seu movimento, como um asteroide ou uma folha a cair no ar.

```ts
ParticleSystem.create(emitter, {
	faceTravelDirection: true,
	billboard: false,
})
```

{% hint style="warning" %}
**📔 Nota**: Se `faceTravelDirection` for true, o valor de `billboard` é ignorado.
{% endhint %}

## Animação de sprite sheet

Pode animar partículas tratando uma textura como uma grelha de fotogramas de animação. Especifique o número de colunas e linhas na grelha e a velocidade de reprodução.

```ts
ParticleSystem.create(emitter, {
	texture: { src: 'assets/scene/textures/flame-sheet.png' },
	spriteSheet: {
		tilesX: 4, // 4 columns
		tilesY: 3, // 3 rows  (12 frames total)
		framesPerSecond: 12,
	},
})
```

## Controlo da reprodução

O sistema de partículas pode estar num de três estados, controlados por `playbackState`.

| Valor                                    | Descrição                                                     |
| ---------------------------------------- | ------------------------------------------------------------- |
| `ParticleSystemPlaybackState.PS_PLAYING` | A emitir ativamente (predefinição).                           |
| `ParticleSystemPlaybackState.PS_PAUSED`  | Imobiliza todas as partículas atuais e interrompe a emissão.  |
| `ParticleSystemPlaybackState.PS_STOPPED` | Interrompe a emissão e remove todas as partículas existentes. |

```ts
import { ParticleSystemPlaybackState } from '@dcl/sdk/ecs'

// Pause when player walks away
ParticleSystem.getMutable(emitter).playbackState =
	ParticleSystemPlaybackState.PS_PAUSED

// Resume
ParticleSystem.getMutable(emitter).playbackState =
	ParticleSystemPlaybackState.PS_PLAYING
```

### Repetição e pré-aquecimento

Por predefinição, o sistema repete indefinidamente. Defina `loop` como `false` para um efeito de execução única que para automaticamente depois de todas as partículas desaparecerem.

Defina `prewarm` como `true` (requer `loop: true`) para simular o sistema como se estivesse em execução desde o início, de modo que as partículas já preencham a cena quando o jogador a vir pela primeira vez.

```ts
ParticleSystem.create(emitter, {
	loop: false, // reproduzir uma vez e parar
	prewarm: false,
})
```

## Emissão em rajadas

As rajadas permitem emitir um grande número de partículas em momentos específicos, em vez de a uma taxa constante. São úteis para explosões, fogos de artifício ou outros eventos de execução única.

Um único sistema de partículas pode passar por um ciclo com várias rajadas, até mesmo com intervalos ou probabilidades variáveis, para criar um efeito mais natural.

```ts
ParticleSystem.create(emitter, {
	rate: 0, // desativar a emissão contínua
	bursts: {
		values: [
			{
				time: 0, // tempo em segundos após o início da reprodução
				count: 200, // partículas a emitir por rajada
				cycles: 1, // número de repetições (0 = infinito)
				interval: 0.2, // segundos entre ciclos repetidos
				probability: 1, // probabilidade de 0 a 1 de a rajada ser acionada a cada ciclo
			},
		],
	},
})
```

Para obter um efeito de fogos de artifício em loop com rajadas escalonadas:

```ts
ParticleSystem.create(emitter, {
	loop: true,
	rate: 0,
	lifetime: 2,
	bursts: {
		values: [
			{ time: 0.0, count: 80, cycles: 0, interval: 3 },
			{ time: 0.7, count: 100, cycles: 0, interval: 3 },
			{ time: 1.4, count: 60, cycles: 0, interval: 3 },
		],
	},
})
```

## Espaço de simulação

Controla se as partículas se movem em relação ao emissor (`PSS_LOCAL`, padrão) ou permanecem fixas nas coordenadas do mundo após serem geradas (`PSS_WORLD`).

Use `PSS_WORLD` para um emissor em movimento que deve deixar um rasto (por exemplo, um asteroide ou um foguetão).

```ts
import { PBParticleSystem_SimulationSpace } from '@dcl/sdk/ecs'

ParticleSystem.create(emitter, {
	simulationSpace: PBParticleSystem_SimulationSpace.PSS_WORLD,
})
```

## Desempenho

O motor impõe um limite de partículas por cena e reduz automaticamente as taxas de emissão de todos os sistemas de partículas ativos na cena se o número total de partículas ultrapassar esse limite. Planeie as suas cenas em conformidade:

* Prefira menos sistemas com grande impacto visual a muitos sistemas com pouco impacto.
* Use `maxParticles` para limitar cada sistema individualmente.
* Use `active` ou `playbackState` para desativar os sistemas que estão fora do ecrã ou fora de alcance.
* Valores curtos de `lifetime` mantêm o número de partículas ativas abaixo do que uma taxa de emissão elevada de `rate` por si só poderia sugerir.

O motor limita a 1000 o número máximo de partículas renderizadas em qualquer momento. Se estiver a emitir mais partículas do que isso, poderá não conseguir vê-las todas.

Tenha também em conta que as partículas só são visíveis para um jogador enquanto este estiver dentro da sua cena. Os jogadores que observam a cena do exterior não verão partículas até entrarem nela.

## Laboratório de partículas

Entre no mundo [ParticleLab.dcl.eth](decentraland://?realm=particlelab.dcl.eth\&dclenv=org) para experimentar diferentes sistemas de partículas. Quando se aproximar de um sistema de partículas, a UI exibirá todos os campos disponíveis; pode ajustá-los em tempo real sem precisar recarregar a cena. Quando estiver satisfeito, clique no botão **Copiar** para copiar o código desse sistema de partículas para a área de transferência.

{% hint style="info" %}
**💡 Dica**: Para ver um exemplo funcional que exercita todos os campos de `ParticleSystem` , consulte a [`0,7-particle-system`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,7-particle-system) cena de teste. Ela abrange as quatro formas de emissor, os modos de mistura `PSB_ADD`/`PSB_ALPHA`/`PSB_MULTIPLY` , os estados de reprodução `PS_PLAYING`/`PS_PAUSED`/`PS_STOPPED` , folhas de sprites, `rate` contínuo em comparação com `bursts`, de disparo único e em loop, e `PSS_LOCAL` em comparação com `PSS_WORLD` num emissor em movimento.
{% endhint %}


---

# 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/fundamentos-de-conteudo-3d/particle-system.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.
