파티클 시스템

불, 비, 불꽃, 마법 오라 같은 파티클 효과를 씬에 추가합니다

파티클 시스템을 사용하면 수많은 작은 스프라이트를 방출하고 애니메이션하여 동적인 시각 효과를 만들 수 있습니다. 불, 연기, 비, 눈, 불꽃, 마법 오라, 폭발 등 정적인 메시로는 구현하기 비현실적인 다양한 효과를 만드는 데 활용하세요.

파티클 시스템 추가

씬에 파티클 시스템을 추가하려면 엔티티를 만들고 다음을 연결하세요 ParticleSystem 컴포넌트를 추가해야 합니다.

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

속성을 하나도 설정하지 않으면 이 컴포넌트는 모든 기본값을 사용합니다. 즉, 초당 10개의 파티클을 발사하는 점 형태 이미터와 5초의 파티클 수명을 사용합니다.

이미터 형태

이미터 형태는 파티클이 어디에서 생성될지를 결정합니다. 네 가지 형태를 다음을 통해 사용할 수 있습니다 ParticleSystem.Shape 헬퍼.

포인트

파티클은 단일 지점(엔티티의 위치)에서 생성됩니다. 형태를 지정하지 않으면 이것이 기본값입니다.

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

구체

파티클은 구의 표면 또는 내부에서 생성됩니다.

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

원뿔

파티클은 원뿔의 밑면에서 생성되어 원뿔 방향으로 바깥쪽으로 이동합니다. angle 은 각도의 반각(도)입니다; 반경 는 밑면 반지름(미터)입니다. 원뿔의 방향을 맞추려면 엔티티의 Transform.

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

상자

파티클은 박스 볼륨 내부 어디에서나 생성됩니다.

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

방출 속성

얼마나 많은 파티클이 생성되고 얼마나 오래 살아 있는지 제어합니다.

속성	기본값	설명
rate	10	초당 방출되는 파티클 수(연속).
maxParticles	1000	동시에 살아 있을 수 있는 파티클의 최대 한도입니다.
lifetime	5	각 파티클의 수명(초)입니다.
active	true	시스템이 새 파티클을 활발하게 방출하는지 여부입니다.

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

모션

중력

이 gravity 속성은 씬의 중력(-9.81 m/s²)에 적용되는 배율입니다. 이를 0 로 설정하면 파티클이 제자리에서 떠 있게 하고, 음수 값으로 설정하면 위로 밀어 올리며, 양수 값으로 설정하면 아래로 가속합니다.

ParticleSystem.create(emitter, {
	gravity: -0.5, // 파티클이 천천히 위로 떠오름
})

초기 속도

initialVelocitySpeed 는 FloatRange 이며 각 파티클이 발사되는 무작위 속도 범위의 최소값과 최대값을 설정합니다(단위: m/s). 두 값의 기본값은 1.

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

추가 힘

중력 외에 모든 파티클에 매 프레임 적용되는 일정한 힘 벡터입니다. 바람이나 자기 효과에 유용합니다.

ParticleSystem.create(emitter, {
	additionalForce: Vector3.create(0.5, 0, 0), // 일정한 측면 밀기
})

속도 제한

다음을 사용하세요 limitVelocity 를 사용하면 파티클의 최대 속도를 제한하고 필요에 따라 매 프레임 초과 속도를 감쇠할 수 있습니다.

ParticleSystem.create(emitter, {
	limitVelocity: {
		speed: 5, // 허용되는 최대 속도(m/s)
		dampen: 0.8, // 프레임마다 제거되는 초과 속도의 비율
	},
})

시각적 속성

색상

initialColor 지정된 범위 내에서 무작위로 선택된 생성 시점의 파티클 색상을 설정합니다. colorOverTime 파티클의 색상이 다음에서 점진적으로 전환되게 합니다 start 에 추가됩니다. end 값으로, 파티클 수명 동안 전환됩니다. 둘 다 다음을 받습니다 ColorRange 및 start 과 end 값.

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

ParticleSystem.create(emitter, {
	initialColor: {
		start: Color4.create(1, 0.5, 0, 1), // 주황색
		end: Color4.create(1, 1, 0, 1), // 노란색
	},
	colorOverTime: {
		start: Color4.create(0.5, 0, 0, 0.5), // 어두운 빨간색, 반투명
		end: Color4.create(0, 0, 0, 0), // 완전히 투명(페이드아웃)
	},
})

의 4번째 값은 Color4 알파 alpha입니다. 최종 색상을 알파가 0인 값으로 설정하면 파티클이 점차 사라지며 보이지 않게 되는데, 이는 종종 좋은 효과입니다.

크기

initialSize 과 sizeOverTime 는 FloatRange 값을. initialSize 지정된 범위 내에서 무작위로 선택된 생성 시점의 파티클 스케일을 제어합니다. sizeOverTime 파티클의 스케일이 다음에서 점진적으로 전환되게 합니다 start 에 추가됩니다. end 값으로, 파티클 수명 동안 전환됩니다. 값이 1 이면 원래 텍스처 크기와 같습니다.

ParticleSystem.create(emitter, {
	initialSize: { start: 0.1, end: 0.3 },
	sizeOverTime: { start: 0.5, end: 1.0 }, // 수명 동안 커짐
})

📔 참고: 크기 엔티티의 Transform 은 파티클의 스케일에 영향을 주지 않습니다.

텍스처

기본적으로 파티클은 흰색 정사각형으로 렌더링됩니다. 사용자 지정 이미지를 사용하려면 텍스처를 제공하세요.

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

블렌드 모드

파티클 색상이 뒤의 씬과 어떻게 합성될지 제어합니다.

값	설명
ParticleSystemBlendMode.PSB_ALPHA	표준 투명도(기본값).
ParticleSystemBlendMode.PSB_ADD	가산 블렌딩 — 파티클이 씬을 더 밝게 만듭니다. 불꽃과 발광 효과에 적합합니다.
ParticleSystemBlendMode.PSB_MULTIPLY	파티클 색상을 뒤의 씬과 곱합니다.

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

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

빌보드

When billboard 가 true (기본값)인 경우 각 파티클은 이미터의 방향과 관계없이 항상 카메라를 향합니다. 이를 false 로 설정하면 3D 공간에서 회전해야 하는 파티클에 적합합니다.

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

회전

초기 회전 및 시간에 따른 회전

initialRotation 는 파티클이 생성될 때의 방향입니다. rotationOverTime 는 매초 적용되는 축별 각속도입니다. 둘 다 다음을 받습니다 Quaternion.

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

ParticleSystem.create(emitter, {
	initialRotation: Quaternion.fromEulerDegrees(0, 0, 45),
	rotationOverTime: Quaternion.fromEulerDegrees(0, 0, 90), // Z축으로 초당 90° 회전
})

📔 참고: 만약 billboard 이 true그러면 파티클은 한 축으로만 회전하며, 항상 카메라를 향한 방향을 유지합니다.

이동 방향을 향하게 하기

When faceTravelDirection 가 true각 파티클은 마치 소행성이나 바람에 떨어지는 나뭇잎처럼 자동으로 이동 방향을 향하도록 회전합니다.

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

📔 참고: 만약 faceTravelDirection 이 true billboard 이면 faceTravelDirection의 값은 무시됩니다.

스프라이트 시트 애니메이션

텍스처를 애니메이션 프레임의 그리드로 취급해 파티클을 애니메이션할 수 있습니다. 시트의 열과 행 수, 재생 속도를 지정하세요.

ParticleSystem.create(emitter, {
	texture: { src: 'assets/scene/textures/flame-sheet.png' },
	spriteSheet: {
		tilesX: 4, // 4열
		tilesY: 3, // 3행(총 12프레임)
		framesPerSecond: 12,
	},
})

재생 제어

파티클 시스템은 다음이 제어하는 세 가지 상태 중 하나일 수 있습니다 playbackState.

값	설명
ParticleSystemPlaybackState.PS_PLAYING	활성 방출 중(기본값).
ParticleSystemPlaybackState.PS_PAUSED	현재 모든 파티클을 제자리에 고정하고 방출을 중지합니다.
ParticleSystemPlaybackState.PS_STOPPED	방출을 중지하고 기존 파티클을 모두 제거합니다.

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

// 플레이어가 멀어질 때 일시 중지
ParticleSystem.getMutable(emitter).playbackState =
	ParticleSystemPlaybackState.PS_PAUSED

// 재개
ParticleSystem.getMutable(emitter).playbackState =
	ParticleSystemPlaybackState.PS_PLAYING

루프 및 프리웜

기본적으로 시스템은 무한히 반복됩니다. 다음을 설정하세요 loop 를 false 파티클이 모두 사라진 후 자동으로 중지되는 일회성 효과에 사용합니다.

다음을 설정하세요 prewarm 를 true (다음이 필요합니다 loop: true) 시스템이 처음부터 실행된 것처럼 시뮬레이션하여 플레이어가 처음 볼 때 이미 파티클이 씬을 채우도록 합니다.

ParticleSystem.create(emitter, {
	loop: false, // 한 번 재생한 후 중지
	prewarm: false,
})

버스트 방출

버스트를 사용하면 일정한 속도가 아니라 특정 순간에 많은 수의 파티클을 방출할 수 있습니다. 폭발, 불꽃놀이 또는 기타 일회성 이벤트에 유용합니다.

하나의 파티클 시스템도 여러 버스트를 통해 주기를 가질 수 있으며, 간격이나 확률을 달리해 더 자연스럽게 느껴지도록 할 수 있습니다.

ParticleSystem.create(emitter, {
	rate: 0, // 연속 방출 비활성화
	bursts: {
		values: [
			{
				time: 0, // 재생이 시작된 후 시간(초)
				count: 200, // 각 버스트마다 방출할 파티클 수
				cycles: 1, // 반복 횟수(0 = 무한)
				interval: 0.2, // 반복 주기 사이의 초
				probability: 1, // 각 주기마다 버스트가 발생할 0–1 확률
			},
		],
	},
})

간헐적인 버스트가 있는 루프형 불꽃놀이 효과의 예:

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

시뮬레이션 공간

파티클이 이미터를 기준으로 움직일지(PSS_LOCAL기본값) 아니면 생성 후 월드 좌표에 고정될지(PSS_WORLD).

다음을 사용하세요 PSS_WORLD 움직이는 이미터가 뒤에 흔적을 남겨야 할 때 사용합니다(예: 소행성이나 로켓).

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

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

성능

엔진은 씬당 파티클 예산을 적용하며, 총 파티클 수가 한도를 초과할 경우 씬의 모든 활성 파티클 시스템에 대한 방출 속도를 자동으로 낮춥니다. 씬을 그에 맞게 계획하세요:

• 눈에 덜 띄는 시스템 여러 개보다 시각적으로 강한 시스템을 적게 사용하는 것이 좋습니다.

• 다음을 사용하세요 maxParticles 개별 시스템을 제한하기 위해

• 다음을 사용하세요 active 또는 playbackState 화면 밖에 있거나 범위를 벗어난 시스템을 비활성화하기 위해

• 짧은 lifetime 값은 높은 방출률만으로는 예상되는 것보다 살아 있는 파티클 수를 더 낮게 유지합니다. rate 만으로는 시사하는 것보다.

엔진은 한 번에 렌더링되는 최대 파티클 수를 1000개로 제한합니다. 그보다 더 많은 파티클을 방출하고 있다면 모든 파티클이 보이지 않을 수 있습니다.

또한 플레이어가 씬 안에 서 있을 때만 파티클을 볼 수 있다는 점을 기억하세요. 바깥에서 씬을 보고 있는 플레이어는 안으로 들어오기 전까지 어떤 파티클도 볼 수 없습니다.

파티클 랩

세계로 들어가기 ParticleLab.dcl.eth 다양한 파티클 시스템을 실험할 수 있습니다. 파티클 시스템에 가까이 가면 UI에 사용 가능한 모든 필드가 표시되며, 씬을 다시 불러올 필요 없이 실시간으로 조정할 수 있습니다. 만족하면 다음을 클릭하세요 복사 버튼을 눌러 해당 파티클 시스템의 코드를 클립보드에 복사하세요.

💡 팁: 모든 ParticleSystem 필드를 확인할 수 있는 작동 예제는 0,7-particle-system 테스트 씬을 참조하세요. 여기에는 네 가지 이미터 형태 모두, 다음이 포함됩니다 PSB_ADD/PSB_ALPHA/PSB_MULTIPLY 블렌드 모드, 다음 PS_PLAYING/PS_PAUSED/PS_STOPPED 재생 상태, 스프라이트 시트, 연속 rate 한 번만 재생하는 경우와 루프 버스트, 그리고 PSS_LOCAL 과 PSS_WORLD 움직이는 이미터에서.