Particle System

Añade particle effects como fuego, lluvia, chispas y auras mágicas a tu scene

Los sistemas de partículas te permiten crear efectos visuales dinámicos emitiendo y animando grandes cantidades de pequeños sprites. Úsalos para crear fuego, humo, lluvia, nieve, chispas, auras mágicas, explosiones y muchos otros efectos que serían imprácticos de lograr con meshes estáticas.

Agregar un sistema de partículas

Para agregar un sistema de partículas a tu escena, crea una entity y adjunta el ParticleSystem component a ella.

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

Sin propiedades configuradas, el component usa todos los valores predeterminados: un emisor puntual que lanza 10 partículas por segundo hacia arriba, con una vida útil de la partícula de 5 segundos.

Formas del emisor

La forma del emisor determina dónde aparecen las partículas. Hay cuatro formas disponibles mediante los ParticleSystem.Shape helpers.

Punto

Las partículas aparecen desde un solo punto (la posición de la entity). Este es el valor predeterminado cuando no se especifica ninguna forma.

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

Esfera

Las partículas aparecen desde la superficie o el interior de una esfera.

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

Cono

Las partículas aparecen desde la base de un cono y se desplazan hacia afuera en la dirección del cono. angle es el semiángulo en grados; radius es el radio de la base en metros. Para orientar la dirección del cono, configura la rotación del Transform.

ParticleSystem.create(emitter, {
	de la entity.
})

Caja

Las partículas aparecen desde cualquier lugar dentro de un volumen de caja.

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

Propiedades de emisión

Controla cuántas partículas se crean y cuánto tiempo viven.

Propiedad	Predeterminado	Descripción
rate	10	Partículas emitidas por segundo (continuo).
maxParticles	1000	Límite máximo de partículas vivas simultáneamente.
lifetime	5	Vida útil de cada partícula en segundos.
active	true	Si el sistema está emitiendo activamente nuevas partículas.

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

Movimiento

Gravedad

El gravity property es un multiplicador aplicado a la gravedad de la escena (-9.81 m/s²). Establécelo en 0 para hacer que las partículas floten en su lugar, en un valor negativo para empujarlas hacia arriba, o en un valor positivo para acelerarlas hacia abajo.

ParticleSystem.create(emitter, {
	gravity: -0.5, // las partículas flotan lentamente hacia arriba
})

Velocidad inicial

initialVelocitySpeed es un FloatRange que establece un mínimo y un máximo para el rango de velocidad aleatoria con el que se lanza cada partícula (en m/s). Ambos valores tienen como predeterminado 1.

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

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

Fuerza adicional

Un vector de fuerza constante aplicado a todas las partículas en cada frame, además de la gravedad. Útil para efectos de viento o magnéticos.

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

Limitación de velocidad

Usa limitVelocity para limitar la velocidad máxima de las partículas y, opcionalmente, amortiguar su velocidad excedente en cada frame.

ParticleSystem.create(emitter, {
	limitVelocity: {
		speed: 5, // velocidad máxima permitida en m/s
		dampen: 0.8, // fracción de la velocidad excedente eliminada por frame
	},
})

Propiedades visuales

Color

initialColor establece el color de la partícula al nacer; colorOverTime establece su color al final de su vida útil. Ambos aceptan un ColorRange con un valor from y to el color real de nacimiento/muerte se elige aleatoriamente dentro de ese rango.

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

ParticleSystem.create(emitter, {
	initialColor: {
		start: Color4.create(1, 0.5, 0, 1), // naranja
		end: Color4.create(1, 1, 0, 1), // amarillo
	},
	colorOverTime: {
		start: Color4.create(0.5, 0, 0, 0.5), // rojo tenue, medio transparente
		end: Color4.create(0, 0, 0, 0), // completamente transparente (desvanecerse)
	},
})

Ten en cuenta que el cuarto valor en un Color4 es el alpha. Si configuras el color final como uno con un alpha de 0, las partículas se desvanecerán gradualmente y se volverán invisibles, lo cual suele ser un buen efecto.

Tamaño

initialSize y sizeOverTime son FloatRange values que controlan la escala de la partícula al nacer y al morir, respectivamente. Un valor de 1 es igual al tamaño original de la textura.

ParticleSystem.create(emitter, {
	initialSize: { start: 0.1, end: 0.3 },
	sizeOverTime: { start: 0.5, end: 1.0 }, // crecer durante la vida útil
})

📔 Nota: La scale de la Transform de la entity no afecta la escala de las partículas.

Textura

Por defecto, las partículas se renderizan como cuadrados blancos. Proporciona una texture para usar una imagen personalizada.

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

Modo de mezcla

Controla cómo se compone el color de la partícula con la escena detrás de ella.

Valor	Descripción
ParticleSystemBlendMode.PSB_ALPHA	Transparencia estándar (predeterminado).
ParticleSystemBlendMode.PSB_ADD	Mezcla aditiva — las partículas iluminan la escena. Bueno para fuego y brillos.
ParticleSystemBlendMode.PSB_MULTIPLY	Multiplica el color de la partícula con la escena detrás de ella.

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

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

Billboard

Cuando billboard es true (el valor predeterminado), cada partícula siempre mira hacia la cámara independientemente de la orientación del emisor. Establécelo en false para partículas que deban girar en el espacio 3D.

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

Rotación

Rotación inicial y rotación a lo largo del tiempo

initialRotation es la orientación de una partícula cuando aparece. rotationOverTime es una velocidad angular por eje aplicada cada segundo. Ambos aceptan un Quaternion.

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

ParticleSystem.create(emitter, {
	initialRotation: Quaternion.fromEulerDegrees(0, 0, 45),
	rotationOverTime: Quaternion.fromEulerDegrees(0, 0, 90), // girar 90°/s en Z
})

📔 Nota: Si billboard se establece en true, entonces las partículas solo rotarán en un eje, manteniendo siempre su orientación hacia la cámara.

Orientar hacia la dirección de movimiento

Cuando faceTravelDirection es true, cada partícula rota automáticamente para apuntar en su dirección de movimiento, como un asteroide o una hoja cayendo por el aire.

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

📔 Nota: Si faceTravelDirection es true, el valor de billboard se ignora.

Animación de sprite sheet

Puedes animar partículas tratando una texture como una cuadrícula de frames de animación. Especifica el número de columnas y filas en la sheet y la velocidad de reproducción.

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

Control de reproducción

El sistema de partículas puede estar en uno de tres estados controlados por playbackState.

Valor	Descripción
ParticleSystemPlaybackState.PS_PLAYING	Emitiendo activamente (predeterminado).
ParticleSystemPlaybackState.PS_PAUSED	Congela todas las partículas actuales en su lugar y deja de emitir.
ParticleSystemPlaybackState.PS_STOPPED	Deja de emitir y elimina todas las partículas existentes.

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

// Pausar cuando el jugador se aleja
ParticleSystem.getMutable(emitter).playbackState =
	ParticleSystemPlaybackState.PS_PAUSED

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

Loop y prewarm

Por defecto, el sistema se repite indefinidamente. Configura loop to false para un efecto de una sola vez que se detenga automáticamente después de que todas las partículas hayan muerto.

Configura prewarm to true (requiere loop: true) para simular el sistema como si hubiera estado ejecutándose desde el inicio, de modo que las partículas ya llenen la escena cuando el jugador la vea por primera vez.

ParticleSystem.create(emitter, {
	loop: false, // reproducir una vez y luego detener
	prewarm: false,
})

Emisión por ráfagas

Las ráfagas te permiten emitir una gran cantidad de partículas en momentos específicos en lugar de a una tasa constante. Son útiles para explosiones, fuegos artificiales u otros eventos de una sola vez.

Un solo sistema de partículas puede pasar por un ciclo con varias ráfagas, incluso con intervalos o probabilidades variables para que se sienta más natural.

ParticleSystem.create(emitter, {
	rate: 0, // deshabilitar la emisión continua
	bursts: {
		values: [
			{
				time: 0, // tiempo en segundos después de que comienza la reproducción
				count: 200, // partículas a emitir por ráfaga
				cycles: 1, // cuántas veces repetir (0 = infinito)
				interval: 0.2, // segundos entre ciclos repetidos
				probability: 1, // probabilidad de 0–1 de que la ráfaga se active en cada ciclo
			},
		],
	},
})

Para un efecto de fuegos artificiales en loop con ráfagas escalonadas:

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

Espacio de simulación

Controla si las partículas se mueven en relación con el emisor (PSS_LOCAL, predeterminado) o permanecen fijas en coordenadas del mundo después de aparecer (PSS_WORLD).

Usa PSS_WORLD para un emisor en movimiento que debe dejar una estela detrás de sí (por ejemplo, un asteroide o un cohete).

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

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

Rendimiento

El engine aplica un presupuesto de partículas por escena y reducirá automáticamente las tasas de emisión en todos los sistemas de partículas activos de la escena si el recuento total de partículas superara el límite. Planifica tus escenas en consecuencia:

• Prefiere menos systems con impacto visual alto en lugar de muchos con poco impacto.

• Usa maxParticles para limitar systems individuales.

• Usa active o playbackState para deshabilitar systems que estén fuera de la pantalla o fuera de alcance.

• Los valores lifetime cortos mantienen el recuento de partículas vivas más bajo que una emisión alta rate por sí sola sugeriría.

El engine limita el número máximo de partículas que se renderizan en cualquier momento a 1000. Si estás emitiendo más partículas que eso, es posible que no las estés viendo todas.

Ten en cuenta también que un jugador solo puede ver las partículas mientras esté dentro de tu escena. Los jugadores que estén mirando la escena desde afuera no verán ninguna partícula hasta que entren.

Particle Lab

Entra en el mundo ParticleLab.dcl.eth para experimentar con diferentes sistemas de partículas. Cuando te acerques a un sistema de partículas, la UI mostrará todos los campos disponibles; puedes ajustarlos en vivo sin necesidad de recargar la escena. Cuando estés satisfecho, haz clic en el Copy button para copiar el código de ese sistema de partículas a tu portapapeles.