> 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-ko/sdk7/3d/particle-system.md).

# 파티클 시스템

불, 비, 불꽃, 마법 오라 같은 파티클 효과를 씬에 추가하세요

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

## 파티클 시스템 추가하기

씬에 파티클 시스템을 추가하려면 엔티티를 만들고 다음을 연결하세요 `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, {})
```

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

## 이미터 모양

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

### 포인트

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

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

### 구체

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

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

### 원뿔

파티클은 원뿔의 밑면에서 생성되어 원뿔의 방향으로 바깥쪽으로 이동합니다. `각도` 는 도 단위의 반각입니다; `반경` 는 미터 단위의 밑면 반지름입니다. 원뿔의 방향을 맞추려면 엔티티의 회전을 설정하세요 `Transform`.

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

### 박스

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

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

## 방출 속성

얼마나 많은 파티클이 생성되는지와 얼마나 오래 유지되는지를 제어합니다.

| 속성             | 기본값    | 설명                             |
| -------------- | ------ | ------------------------------ |
| `rate`         | `10`   | 초당 방출되는 파티클 수(연속).             |
| `maxParticles` | `1000` | 동시에 살아 있는 파티클의 최대 한도.          |
| `lifetime`     | `5`    | 각 파티클의 수명(초).                  |
| `active`       | `true` | 시스템이 새 파티클을 적극적으로 방출하고 있는지 여부. |

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

## 이동

### 중력

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

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

### 초기 속도

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

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

### 추가 힘

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

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

### 속도 제한

사용: `limitVelocity` 파티클의 최대 속도를 제한하고, 필요에 따라 매 프레임 초과 속도를 감쇠시키는 데 사용합니다.

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

## 시각적 속성

### 색상

`initialColor` 주어진 범위 내에서 무작위로 선택된 파티클의 탄생 시 색상을 설정합니다. `colorOverTime` 파티클의 색상이 `start` 가 `end` 값에서 수명 동안 서서히 변하도록 합니다. 둘 다 `ColorRange` 와 함께 `start` 및 `end` 값입니다.

```ts
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), // 완전히 투명함(서서히 사라짐)
	},
})
```

다음 사항에 유의하세요:  `Color4` 는 *alpha*. 최종 색상을 알파가 0인 값으로 설정하면 파티클은 서서히 사라져 보이지 않게 되며, 이는 종종 좋은 효과입니다.

### 크기

`initialSize` 및 `sizeOverTime` 다음과 같습니다 `FloatRange` 값. `initialSize` 주어진 범위 내에서 무작위로 선택된 파티클의 탄생 시 크기를 제어합니다. `sizeOverTime` 파티클의 크기가 `start` 가 `end` 값에서 수명 동안 서서히 변하도록 합니다. 값이 `1` 이면 원래 텍스처 크기와 같습니다.

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

{% hint style="warning" %}
**📔 참고**:  `크기` 엔티티의 `Transform` 는 파티클의 크기에 영향을 주지 않습니다.
{% endhint %}

### 텍스처

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

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

### 블렌드 모드

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

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

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

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

### 빌보드

호출될 때 `billboard` 일 때 `true` (기본값)에서는 각 파티클이 이미터의 방향과 관계없이 항상 카메라를 향합니다. 이를 `false` 3D 공간에서 회전해야 하는 파티클에 사용하세요.

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

## 회전

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

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

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

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

{% hint style="warning" %}
**📔 참고**: 만약 `billboard` 이 `true`그러면 파티클은 한 축으로만 회전하며, 항상 카메라를 향하는 방향을 유지합니다.
{% endhint %}

### 이동 방향을 향하기

호출될 때 `faceTravelDirection` 일 때 `true`각 파티클은 이동 방향을 향하도록 자동으로 회전합니다. 소행성이나 공중에서 떨어지는 나뭇잎처럼요.

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

{% hint style="warning" %}
**📔 참고**: 만약 `faceTravelDirection` 가 true이면, 값은 `billboard` 무시됩니다.
{% endhint %}

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

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

```ts
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` | 방출을 멈추고 기존 파티클을 모두 제거합니다.        |

```ts
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`) 시스템이 처음부터 실행된 것처럼 시뮬레이션하여, 플레이어가 처음 볼 때 이미 파티클이 씬을 채우도록 합니다.

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

## 버스트 방출

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

단일 파티클 시스템은 여러 버스트를 포함하는 주기를 거칠 수 있으며, 간격이나 확률을 달리하여 더 자연스럽게 느껴지게 할 수 있습니다.

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

간격을 둔 버스트로 반복되는 불꽃놀이 효과의 경우:

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

## 시뮬레이션 공간

파티클이 이미터를 기준으로 움직일지(`PSS_LOCAL`, 기본값) 아니면 생성 후 월드 좌표에서 고정된 상태로 남을지(`PSS_WORLD`).

사용: `PSS_WORLD` 뒤에 꼬리를 남겨야 하는 움직이는 이미터에 사용하세요(예: 소행성이나 로켓).

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

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

## 성능

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

* 시각적으로 임팩트가 있는 시스템을 여러 개의 영향이 작은 시스템보다 우선하세요.
* 사용: `maxParticles` 개별 시스템의 상한을 설정하려면
* 사용: `active` 또는 `playbackState` 화면 밖이나 범위 밖의 시스템을 비활성화하려면
* 짧은 `lifetime` 값은 높은 방출 `rate` 만으로 예상되는 것보다 살아 있는 파티클 수를 더 낮게 유지합니다.

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

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

## Particle Lab

세계로 들어가기 [ParticleLab.dcl.eth](decentraland://?realm=particlelab.dcl.eth\&dclenv=org) 다양한 파티클 시스템을 실험해 보세요. 파티클 시스템에 가까이 가면 UI가 사용 가능한 모든 필드를 표시하며, 씬을 다시 로드하지 않고도 실시간으로 조정할 수 있습니다. 만족하면 **Copy** 버튼을 클릭하여 해당 파티클 시스템의 코드를 클립보드에 복사하세요.

{% hint style="info" %}
**💡 팁**: 모든 `ParticleSystem` 필드를 사용하는 작동 예제는 [`0,7-particle-system`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,7-particle-system) 테스트 씬입니다. 여기에는 네 가지 이미터 모양과 `PSB_ADD`/`PSB_ALPHA`/`PSB_MULTIPLY` 블렌드 모드,  `PS_PLAYING`/`PS_PAUSED`/`PS_STOPPED` 재생 상태, 스프라이트 시트, 연속 `rate` 과 단발성 및 반복 `버스트`, 그리고 `PSS_LOCAL` 과 `PSS_WORLD` 이동하는 이미터에서.
{% 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/3d/particle-system.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.