Particle System

Añade efectos de partículas como fuego, lluvia, chispas y auras mágicas a tu escena

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áticos.

Agregar un sistema de partículas

Para agregar un sistema de partículas a tu escena, crea una entidad y adjunta el ParticleSystem componente 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 ninguna propiedad configurada, el componente usa todos los valores predeterminados: un emisor puntual que dispara 10 partículas por segundo, con una vida útil de 5 segundos para cada partícula.

Formas del emisor

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

Punto

Las partículas aparecen desde un único punto (la posición de la entidad). 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 viajan 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, establece la rotación de la Transform.

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

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 estricto de partículas activas simultáneas.
lifetime	5	La vida útil de cada partícula en segundos.
active	true	Si el sistema está emitiendo nuevas partículas activamente.

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

Movimiento

Gravedad

La gravity la propiedad 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 valor predeterminado 1.

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 exceso de velocidad en cada frame.

ParticleSystem.create(emitter, {
	limitVelocity: {
		speed: 5, // velocidad máxima permitida en m/s
		dampen: 0.8, // fracción del exceso de velocidad que se elimina por frame
	},
})

Propiedades visuales

Color

initialColor establece el color de la partícula al nacer, elegido aleatoriamente dentro del rango dado. colorOverTime hace que el color de la partícula transicione gradualmente desde el inicio hasta el final valor a lo largo de la vida útil de la partícula. Ambos aceptan un ColorRange con un inicio y final valor.

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 de un Color4 es el alpha. Si estableces el color final con un alpha de 0, las partículas se desvanecerán gradualmente y se volverán invisibles, lo que a menudo es un buen efecto.

Tamaño

initialSize y sizeOverTime son FloatRange valores. initialSize controla la escala de la partícula al nacer, elegida aleatoriamente dentro del rango dado. sizeOverTime hace que la escala de la partícula transicione gradualmente desde el inicio hasta el final valor a lo largo de la vida útil de la partícula. 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 a lo largo de la vida útil
})

📔 Nota: El scale de la Transform de la entidad no afecta la escala de las partículas.

Texture

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. Buena para fuego y resplandores.
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 con el tiempo

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

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

ParticleSystem.create(emitter, {
	initialRotation: Quaternion.fromEulerDegrees(0, 0, 45),
	rotationOverTime: Quaternion.fromEulerDegrees(0, 0, 90), // gira 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.

Face travel direction

Cuando faceTravelDirection es true, cada partícula gira 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 fotogramas de animación. Especifica la cantidad de columnas y filas en la hoja 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 detiene la emisión.
ParticleSystemPlaybackState.PS_STOPPED	Detiene la emisión 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. Establece loop a false para un efecto de una sola vez que se detiene automáticamente después de que todas las partículas hayan desaparecido.

Establece prewarm a true (requiere loop: true) para simular el sistema como si hubiera estado funcionando desde el principio, 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 detenerse
	prewarm: false,
})

Emisión por bursts

Los bursts 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 único sistema de partículas puede pasar por un ciclo con varios bursts, incluso con intervalos o probabilidades variables, para que resulte más natural.

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

Para un efecto de fuegos artificiales en bucle con bursts escalonados:

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 { PBParticleSystem_SimulationSpace } from '@dcl/sdk/ecs'

ParticleSystem.create(emitter, {
	simulationSpace: PBParticleSystem_SimulationSpace.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 sistemas, pero visualmente impactantes, en lugar de muchos de bajo impacto.

• Usa maxParticles para limitar los sistemas individuales.

• Usa active o playbackState para desactivar los sistemas que están fuera de pantalla o fuera de alcance.

• Cortos lifetime los valores mantienen el recuento de partículas activas más bajo que una alta emisión rate por sí sola sugiere.

El engine limita la cantidad máxima de partículas que se renderizan en cualquier momento a 1000. Si estás emitiendo más partículas que eso, puede que no las estés viendo todas.

También ten en cuenta 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 al 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; podrás ajustarlos en vivo sin necesidad de recargar la escena. Cuando estés satisfecho, haz clic en el Copy botón para copiar el código de ese sistema de partículas en tu portapapeles.

💡 Consejo: Para un ejemplo funcional que pruebe cada ParticleSystem campo, consulta la 0,7-particle-system escena de prueba. Cubre las cuatro formas de emisor, los PSB_ADD/PSB_ALPHA/PSB_MULTIPLY modos de mezcla, los PS_PLAYING/PS_PAUSED/PS_STOPPED estados de reproducción, sprite sheets, emisión continua rate frente a bursts de una sola vez y en bucle bursts, y PSS_LOCAL en PSS_WORLD un emisor en movimiento.