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

### 원뿔

파티클은 원뿔의 밑면에서 생성되어 원뿔 방향으로 바깥쪽으로 이동합니다. `angle` 은 각도의 반각(도)입니다; `반경` 는 밑면 반지름(미터)입니다. 원뿔의 방향을 맞추려면 엔티티의 `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` 로 설정하면 파티클이 제자리에서 떠 있게 하고, 음수 값으로 설정하면 위로 밀어 올리며, 양수 값으로 설정하면 아래로 가속합니다.

```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), // 완전히 투명(페이드아웃)
	},
})
```

의 4번째 값은 `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,
})
```

### 빌보드

When `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 %}

### 이동 방향을 향하게 하기

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

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

{% hint style="warning" %}
**📔 참고**: 만약 `faceTravelDirection` 이 true `billboard` 이면 faceTravelDirection의 값은 무시됩니다.
{% 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개로 제한합니다. 그보다 더 많은 파티클을 방출하고 있다면 모든 파티클이 보이지 않을 수 있습니다.

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

## 파티클 랩

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

{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.