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, fumo, chuva, neve, faíscas, auras mágicas, explosões e muitos outros efeitos que seriam impraticáveis de conseguir com meshes estáticos.

Adicionar um sistema de partículas

Para adicionar um sistema de partículas à tua scene, cria uma entity e anexa-lhe o ParticleSystem component.

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 propriedades definidas, o component usa todos os valores por defeito: um emissor pontual que lança 10 partículas por segundo para cima, com uma vida útil da partícula de 5 segundos.

Formas do emissor

A forma do emissor determina onde as partículas aparecem. Quatro formas estão disponíveis através dos ParticleSystem.Shape helpers.

Point

As partículas aparecem a partir de um único ponto (a posição da entity). Este é o valor por defeito quando nenhuma forma é especificada.

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

Sphere

As partículas aparecem a partir da superfície ou do interior de uma esfera.

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

Cone

As partículas aparecem a partir da 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, define a rotação do Transform.

ParticleSystem.create(emitter, {
	da entity.
})

Box

As partículas aparecem a partir de qualquer ponto dentro de um volume em caixa.

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

Propriedades de emissão

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

Propriedade	Padrão	Descrição
rate	10	Partículas emitidas por segundo (contínuo).
maxParticles	1000	Limite máximo de partículas vivas simultaneamente.
lifetime	5	Tempo de vida de cada partícula em segundos.
active	true	Se o sistema está a emitir ativamente novas partículas.

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

Movimento

Gravidade

O gravity property é um multiplicador aplicado à gravidade da scene (-9.81 m/s²). Define-o como 0 para fazer as partículas flutuar no lugar, um valor negativo para as empurrar para cima, ou um valor positivo para as acelerar para baixo.

ParticleSystem.create(emitter, {
	gravity: -0.5, // as partículas flutuam lentamente para cima
})

Velocidade inicial

initialVelocitySpeed é um FloatRange que define um mínimo e um máximo para o intervalo de velocidade aleatória com que cada partícula é lançada (em m/s). Ambos os valores têm o valor por defeito de 1.

import { Vector2 } from '@dcl/sdk/math'

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

Força adicional

Uma força constante vetorial aplicada a todas as partículas em cada frame, além da gravidade. Útil para efeitos de vento ou magnéticos.

ParticleSystem.create(emitter, {
	additionalForce: Vector3.create(0.5, 0, 0), // impulso lateral constante
})

Limitação de velocidade

Usa limitVelocity para limitar a velocidade máxima das partículas e, opcionalmente, amortecer o excesso de velocidade em cada frame.

ParticleSystem.create(emitter, {
	limitVelocity: {
		speed: 5, // velocidade máxima permitida em m/s
		dampen: 0.8, // fração do excesso de velocidade removida por frame
	},
})

Propriedades visuais

Cor

initialColor define a cor da partícula ao nascer; colorOverTime define a cor no final da sua vida útil. Ambos aceitam um ColorRange com um valor from e to — a cor real no nascimento/morte é escolhida aleatoriamente dentro desse intervalo.

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

ParticleSystem.create(emitter, {
	initialColor: {
		start: Color4.create(1, 0.5, 0, 1), // laranja
		end: Color4.create(1, 1, 0, 1), // amarelo
	},
	colorOverTime: {
		start: Color4.create(0.5, 0, 0, 0.5), // vermelho escuro, meio transparente
		end: Color4.create(0, 0, 0, 0), // totalmente transparente (desvanecer)
	},
})

Nota que o 4.º valor num Color4 é o alpha. Se definires a cor final para uma com alpha 0, as partículas vão desvanecer gradualmente e tornar-se invisíveis, o que é muitas vezes um bom efeito.

Tamanho

initialSize e sizeOverTime são FloatRange values que controlam a escala da partícula no nascimento e na morte, respetivamente. Um valor de 1 é igual ao tamanho original da textura.

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

📔 Nota: A scale do Transform da entity não afeta a escala das partículas.

Texture

Por defeito, as partículas são renderizadas como quadrados brancos. Fornece uma texture para usar uma imagem personalizada.

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

Modo de blending

Controla como a cor da partícula é combinada com a scene atrás dela.

Valor	Descrição
ParticleSystemBlendMode.PSB_ALPHA	Transparência padrão (por defeito).
ParticleSystemBlendMode.PSB_ADD	Blending aditivo — as partículas iluminam a scene. Bom para fogo e brilhos.
ParticleSystemBlendMode.PSB_MULTIPLY	Multiplica a cor da partícula com a scene atrás dela.

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

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

Billboard

Quando billboard é true (o valor por defeito), cada partícula enfrenta sempre a camera, independentemente da orientação do emissor. Define-o como false para partículas que devem rodar no espaço 3D.

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

Rotação

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

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

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
})

📔 Nota: Se billboard for definido como true, então as partículas só vão rodar num eixo, mantendo sempre a orientação voltada para a camera.

Face travel direction

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

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

📔 Nota: Se faceTravelDirection for true, o valor de billboard é ignorado.

Animação de sprite sheet

Podes animar partículas tratando uma texture como uma grelha de frames de animação. Especifica o número de colunas e linhas na sheet e a velocidade de reprodução.

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

Controlo de reprodução

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

Valor	Descrição
ParticleSystemPlaybackState.PS_PLAYING	A emitir ativamente (por defeito).
ParticleSystemPlaybackState.PS_PAUSED	Congela todas as partículas atuais no lugar e para a emissão.
ParticleSystemPlaybackState.PS_STOPPED	Pára a emissão e remove todas as partículas existentes.

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

// Pausar quando o player se afasta
ParticleSystem.getMutable(emitter).playbackState =
	ParticleSystemPlaybackState.PS_PAUSED

// Retomar
ParticleSystem.getMutable(emitter).playbackState =
	ParticleSystemPlaybackState.PS_PLAYING

Loop e prewarm

Por defeito, o sistema repete-se indefinidamente. Define loop to false para um efeito único que para automaticamente depois de todas as partículas morrerem.

Define prewarm to true (requer loop: true) para simular o sistema como se estivesse a funcionar desde o início, para que as partículas já preencham a scene quando o player a vê pela primeira vez.

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

Emissão em burst

Os bursts permitem emitir uma grande quantidade de partículas em momentos específicos em vez de a uma taxa constante. São úteis para explosões, fogo de artifício ou outros eventos únicos.

Um único sistema de partículas pode passar por um ciclo com vários bursts, até com intervalos ou probabilidades variáveis, para parecer mais natural.

ParticleSystem.create(emitter, {
	rate: 0, // desativar 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 burst
				cycles: 1, // quantas vezes repetir (0 = infinito)
				interval: 0.2, // segundos entre ciclos repetidos
				probability: 1, // probabilidade de 0–1 de o burst disparar em cada ciclo
			},
		],
	},
})

Para um efeito de fogo de artifício em loop com bursts desencontrados:

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, por defeito) ou permanecem fixas em coordenadas do mundo depois de aparecerem (PSS_WORLD).

Usa PSS_WORLD para um emissor em movimento que deve deixar um rasto atrás de si (por exemplo, um asteroide ou um foguete).

import { ParticleSystemSimulationSpace } from '@dcl/sdk/ecs'

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

Desempenho

O engine impõe um orçamento de partículas por scene e irá reduzir automaticamente as taxas de emissão em todos os sistemas de partículas ativos na scene se a contagem total de partículas exceder o limite. Planeia as tuas scenes em conformidade:

• Prefere menos sistemas com impacto visual forte em vez de muitos sistemas com pouco impacto.

• Usa maxParticles para limitar sistemas individuais.

• Usa active ou playbackState para desativar sistemas que estão fora do ecrã ou fora do alcance.

• Valores lifetime curtos mantêm a contagem de partículas vivas inferior ao que uma emissão elevada rate por si só sugere.

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

Tem também em mente que as partículas só podem ser vistas por um player enquanto este estiver dentro da tua scene. Players que estiverem a olhar para a scene do exterior não verão partículas até entrarem nela.

Particle Lab

Entra no mundo ParticleLab.dcl.eth para experimentar diferentes sistemas de partículas. Quando te aproximares de um sistema de partículas, a UI irá mostrar todos os campos disponíveis; podes ajustá-los em tempo real sem precisares de recarregar a scene. Quando estiveres satisfeito, clica no Copy button para copiar o código desse sistema de partículas para a tua área de transferência.