사용자 정의 모듈

Module Script에 입출력 매개변수와 파티클 속성 계산을 정의해 여러 시스템에서 재사용할 수 있는 사용자 모듈을 만듭니다.

지금까지 나이아가라의 스폰, 업데이트, 렌더링 모듈의 기본 사용법을 익히셨습니다.

이 모듈들만으로도 다양한 효과를 만들 수 있지만, 때로는 언리얼 엔진에서 기본으로 제공하는 모듈만으로는 원하는 복잡하거나 독특한 효과를 구현하기 어려울 때가 있습니다.

이럴 때 필요한 것이 바로 사용자 정의 모듈(Custom Module)입니다.

사용자 정의 모듈은 나이아가라의 확장성을 보여주는 핵심 기능 중 하나입니다.

파티클의 속성을 제어하는 로직을 직접 만들고, 이를 재사용 가능한 모듈 형태로 저장하여 다른 나이아가라 시스템에서도 활용할 수 있습니다.

마치 레고 블록을 직접 디자인하고 생산하여, 나만의 특별한 작품을 만드는 것과 비슷하다고 할 수 있습니다.

사용자 정의 모듈이란?

사용자 정의 모듈은 특정 기능을 수행하도록 비주얼 스크립트(Visual Script) 형태로 직접 제작하는 나이아가라 모듈입니다.

이는 블루프린트와 유사하게 노드 기반의 시각적인 프로그래밍 방식으로 이루어져 있어, C++ 코딩 지식 없이도 복잡한 파티클 로직을 구현할 수 있습니다.

사용자 정의 모듈을 활용하면 다음과 같은 장점을 얻을 수 있습니다.

높은 유연성: 기본 모듈로는 불가능했던 독특한 파티클 동작이나 수학적 계산을 직접 구현할 수 있습니다.
재사용성: 한 번 만든 사용자 정의 모듈은 여러 이미터나 나이아가라 시스템에서 재사용할 수 있어 작업 효율을 높입니다.
깔끔한 워크플로우: 복잡한 파티클 로직을 하나의 모듈로 캡슐화하여 이미터의 Particle Update 섹션을 더 깔끔하게 유지할 수 있습니다.

사용자 정의 모듈 생성 및 편집 과정

간단한 예시를 통해 사용자 정의 모듈을 만들고 사용하는 과정을 살펴보겠습니다.

여기서는 파티클의 수명에 따라 특정 방향으로 지그재그 움직임을 추가하는 간단한 사용자 정의 모듈을 만들어볼 것입니다.

새로운 나이아가라 모듈 에셋 생성

콘텐츠 브라우저(Content Browser)에서 원하는 폴더를 선택하고 우클릭합니다.
FX > Niagara Module을 선택합니다.
새 모듈의 이름을 NCM_ZigzagMovement (Niagara Custom Module의 약자)와 같이 지정합니다.
NCM_ZigzagMovement 에셋을 더블 클릭하여 나이아가라 모듈 에디터(Niagara Module Editor)를 엽니다. 이 에디터는 일반 나이아가라 에디터와 유사하지만, 모듈 로직을 만드는 데 집중되어 있습니다.

Parameter Map과 입출력 설정

모듈 그래프는 Input Map에서 Output Module로 이어지는 Parameter Map을 사용합니다. Map Get에서 현재 입자의 NormalizedAge·Velocity와 모듈 입력을 읽고, Map Set에서 Particles.Velocity를 씁니다.

Float 입력 ZigzagStrength: X축 속도 진폭(cm/s), 기본값 0.
Float 입력 ZigzagFrequency: 한 수명 동안 진행할 위상(라디안), 기본값 6.283185. 이 값은 초당 진동수(Hz)가 아닙니다.
입력은 해당 버전의 모듈 입력 네임스페이스(Input/Module)에 만들며 User Parameter로 자동 노출되는 것은 아닙니다.

스크립트 에디터에서 로직 구현

Map Get에서 Particles.NormalizedAge와 Particles.Velocity를 읽습니다.
NormalizedAge에 ZigzagFrequency를 곱하고 라디안 기준 Sine을 계산합니다.
Sine 결과에 ZigzagStrength를 곱해 X축 속도를 만듭니다.
현재 Velocity의 Y·Z는 유지하고 X만 계산값으로 교체한 Vector를 Map Set의 Particles.Velocity에 연결합니다. Parameter Map은 Input Map → Map Set → Output Module로 이어집니다.

phase = Particles.NormalizedAge * ZigzagFrequency
newX = sin(phase) * ZigzagStrength
Particles.Velocity = (newX, previousVelocity.y, previousVelocity.z)

위 식은 노드 연결을 설명하는 의사 코드입니다. 이전 X에 매 틱 값을 더하면 누적 가속이 되므로 이 예제에서는 X를 덮어씁니다. Strength가 0이면 기존 X를 보존하는 것이 아니라 X를 0으로 만듭니다. Particle State로 나이를 갱신한 뒤, Solve Forces and Velocity 전에 배치해 위치로 적분합니다. 초기 X 속도를 유지해야 하는 다른 효과에서는 기준 속도 저장과 합성 규칙을 별도로 설계해야 합니다.

모듈 저장: NCM_ZigzagMovement 에셋을 저장합니다. (Ctrl + S)

한 수명 동안 X 속도가 사인 한 주기를 따릅니다

한 수명의 NormalizedAge 0/.25/.5/.75/1에서 X 속도 0/+100/0/-100/0 계산이 달라진다. Y/Z 보존·X 덮어쓰기·위치 곡선 아님·끝점 미관측 가능을 명시한다.

NIAGARA · CH3-5

한 수명에 X 속도가 사인 한 주기를 따릅니다

NormalizedAge × 2π를 라디안 위상으로 사용하고 Strength=100cm/s로 정한 계산 예입니다. 그래프는 위치 궤적이 아니라 새로 쓰는 X 속도입니다.

X만 교체하고 Y·Z는 보존합니다

newX = sin(NormalizedAge × 2π) × 100

이전 X에 값을 더하지 않고 계산한 X로 덮어씁니다. Strength가 0이면 X도 0이 됩니다.

2π는 한 수명에 한 주기라는 뜻입니다. Lifetime이 2초라면 한 주기도 2초이며, 2π Hz라는 뜻이 아닙니다.

본문 조건은 Particle State 뒤, 위치 적분 전 배치입니다. 다른 힘·Drag·Velocity 작성자는 끄고 기준 거동을 비교합니다. 끝점이 실제 소멸 프레임에 보인다는 보장은 없습니다.

이 예의 조건

본문과 원 도표에 제시된 사례의 입력·조건을 사용합니다. 설명용 수치나 독립 비교 경로는 각 단계에 표시합니다.
현재 상태·값과 전환 근거의 위치는 모든 단계에서 같습니다. 조건이 맞지 않거나 실행되지 않은 경로를 성공한 동작으로 해석하지 않습니다.

관계도의 보충 설명

원 도표의 제목·노드·관계·조건·주석
범위	원문
본문·주석	한 수명 동안 X 속도가 사인 한 주기를 따릅니다
본문·주석	NormalizedAge × 2π를 라디안 위상으로 사용하고 Strength=100 cm/s로 정한 계산 예입니다. 그래프는 위치 궤적이 아니라 새로 쓰는 X 속도입니다.
관계·조건 설명	수명 진행률 0에서 0, 0.25에서 +100, 0.5에서 0, 0.75에서 -100, 1에서 0 cm/s입니다. Strength 100과 위상 2π를 사용한 수학적 속도 예입니다.
관계·조건 설명	원 도표와 동일하게 수명 진행률 0/0.25/0.5/0.75/1에서 X 속도는 0/+100/0/-100/0 cm/s다. 곡선은 위치가 아닌 속도이며 Lifetime 끝점의 실제 출력을 보장하지 않는다. Strength 100, Frequency 2pi를 사용한다.

예의 값과 변화
관찰·상황	값·보충 정보	변화·이유
나이 초반 한 수명의 진행률로 X 속도를 읽는다.	NormalizedAge: 0→0.25 X 속도: 0→+100	X 속도를 덮어쓰며 Y/Z는 보존한다.
중간·후반 0.5와 0.75에서 방향 입력이 달라진다.	0.5의 X: 0 0.75의 X: -100	속도 곡선은 위치 좌표의 곡선이 아니다.
끝점 1의 계산값은 0이지만 실제 관측은 설정에 달려 있다.	1의 X: 0 끝점 관측: Kill 설정 등에 따라 다름	나이 끝점이 항상 한 프레임 표시된다고 보장하지 않는다.

한 수명 동안 X 속도가 사인 한 주기를 따릅니다

한 수명의 NormalizedAge 0/.25/.5/.75/1에서 X 속도 0/+100/0/-100/0 계산이 달라진다. Y/Z 보존·X 덮어쓰기·위치 곡선 아님·끝점 미관측 가능을 명시한다.

NIAGARA · CH3-5

한 수명에 X 속도가 사인 한 주기를 따릅니다

NormalizedAge × 2π를 라디안 위상으로 사용하고 Strength=100cm/s로 정한 계산 예입니다. 그래프는 위치 궤적이 아니라 새로 쓰는 X 속도입니다.

X만 교체하고 Y·Z는 보존합니다

newX = sin(NormalizedAge × 2π) × 100

이전 X에 값을 더하지 않고 계산한 X로 덮어씁니다. Strength가 0이면 X도 0이 됩니다.

2π는 한 수명에 한 주기라는 뜻입니다. Lifetime이 2초라면 한 주기도 2초이며, 2π Hz라는 뜻이 아닙니다.

이 예의 조건

본문과 원 도표에 제시된 사례의 입력·조건을 사용합니다. 설명용 수치나 독립 비교 경로는 각 단계에 표시합니다.
현재 상태·값과 전환 근거의 위치는 모든 단계에서 같습니다. 조건이 맞지 않거나 실행되지 않은 경로를 성공한 동작으로 해석하지 않습니다.

관계도의 보충 설명

원 도표의 제목·노드·관계·조건·주석
범위	원문
본문·주석	한 수명 동안 X 속도가 사인 한 주기를 따릅니다
본문·주석	NormalizedAge × 2π를 라디안 위상으로 사용하고 Strength=100 cm/s로 정한 계산 예입니다. 그래프는 위치 궤적이 아니라 새로 쓰는 X 속도입니다.
관계·조건 설명	수명 진행률 0에서 0, 0.25에서 +100, 0.5에서 0, 0.75에서 -100, 1에서 0 cm/s입니다. Strength 100과 위상 2π를 사용한 수학적 속도 예입니다.
관계·조건 설명	원 도표와 동일하게 수명 진행률 0/0.25/0.5/0.75/1에서 X 속도는 0/+100/0/-100/0 cm/s다. 곡선은 위치가 아닌 속도이며 Lifetime 끝점의 실제 출력을 보장하지 않는다. Strength 100, Frequency 2pi를 사용한다.

예의 값과 변화
관찰·상황	값·보충 정보	변화·이유
나이 초반 한 수명의 진행률로 X 속도를 읽는다.	NormalizedAge: 0→0.25 X 속도: 0→+100	X 속도를 덮어쓰며 Y/Z는 보존한다.
중간·후반 0.5와 0.75에서 방향 입력이 달라진다.	0.5의 X: 0 0.75의 X: -100	속도 곡선은 위치 좌표의 곡선이 아니다.
끝점 1의 계산값은 0이지만 실제 관측은 설정에 달려 있다.	1의 X: 0 끝점 관측: Kill 설정 등에 따라 다름	나이 끝점이 항상 한 프레임 표시된다고 보장하지 않는다.

예시: 노드 계산의 중간값 확인하기

그림처럼 ZigzagStrength=100cm/s, ZigzagFrequency=2π이고 고정 Lifetime=2초라고 합시다. 나이 0.5초에는 NormalizedAge=0.5 ÷ 2 = 0.25, 위상은 0.25 × 2π = π/2, Sine은 1이므로 새 X 속도는 +100 cm/s입니다. 나이 1.5초에는 진행률 0.75에서 Sine이 -1이므로 -100 cm/s입니다. 이전 Y=20, Z=30이라면 이 모듈을 지난 벡터는 각각 (100, 20, 30), (-100, 20, 30)입니다. X 속도의 부호가 바뀐다는 계산이며, X 위치가 곧바로 ±100 cm가 된다는 뜻은 아닙니다.

독립 계산하기

고정 Lifetime=4초, ZigzagFrequency=2π, ZigzagStrength=50cm/s인 입자가 3초 동안 살아 있습니다. 이전 Y=5, Z=-10이고 다른 힘·Drag·속도 설정 모듈은 꺼져 있습니다. NormalizedAge·위상·새 속도 벡터를 구하고, 같은 조건에서 Strength만 0으로 바꾸면 X가 이전 값으로 돌아가는지도 판단해 보세요.

진행률·위상·덮어쓰기의 풀이

진행률은 3 ÷ 4 = 0.75, 위상은 3π/2, Sine은 -1이므로 새 벡터는 (-50, 5, -10) cm/s입니다. Strength=0이면 계산한 X=0으로 덮어쓰므로 이전 X를 복원하지 않습니다. Frequency=2π는 이번 4초 수명 동안 한 주기이며 초당 한 주기나 2π Hz라는 뜻도 아닙니다.

사용자 정의 모듈 사용하기

이제 만든 사용자 정의 모듈을 기존 나이아가라 시스템에 적용해 보겠습니다.

이전에 만들었던 NS_BasicSpawn (또는 다른 나이아가라 시스템)을 엽니다.

개요(Overview) 패널에서 파티클 업데이트 효과를 추가하고 싶은 이미터를 선택합니다.

Particle Update 섹션 아래의 + 버튼을 클릭합니다.

검색창에 여러분이 만든 모듈 이름 NCM_ZigzagMovement를 입력해 검색한 뒤 추가합니다.

모듈이 추가되면, 디테일(Details) 패널에서 여러분이 정의했던 ZigzagStrength와 ZigzagFrequency 속성을 볼 수 있습니다.

이 값들을 조절하면서 뷰포트에서 파티클의 움직임이 어떻게 변하는지 확인해 보세요.

ZigzagStrength는 좌우 속도 진폭이며, 실제 이동 폭은 위상 진행 속도와 Lifetime에도 좌우됩니다. ZigzagFrequency = 2π는 한 수명에 사인 한 주기입니다. 다른 힘·Drag·속도 설정 모듈은 끄고 먼저 기준 거동을 비교합니다.

사용자 정의 모듈 활용 팁

주석 달기: 복잡한 스크립트를 만들 때는 C 키를 눌러 주석 상자를 추가하여 각 부분의 역할을 설명하는 것이 좋습니다.
입력 매개변수 사용: 실제 사용자가 바꿔야 하는 값만 입력으로 노출하고 이름·단위·기본값을 설명합니다.
계산 순서: 스크립트 에디터에서 노드 간의 데이터 흐름과 계산 순서를 명확히 이해하는 것이 중요합니다.
디버깅: 문제가 발생하면 디버거를 사용하여 파티클의 속성 변화를 추적하고, 어떤 노드에서 문제가 발생했는지 파악하세요.

모듈의 사용 범위를 Particle Update로 설정하고 라이브러리 노출·카테고리·설명을 확인합니다. 다른 이미터에 넣을 때는 X 속도를 덮어쓰는 책임과 선행 Particle State, 후행 위치 적분 조건을 함께 전달합니다.

Scratch Pad로 먼저 만든 경우에는 다른 에셋에서 재사용할 모듈 에셋으로 내보낼 수 있습니다. 공식 Scratch Pad 예제는 Map Get과 Map Set으로 읽기와 쓰기를 구분합니다.

사용자 정의 모듈이란?

사용자 정의 모듈 생성 및 편집 과정

한 수명 동안 X 속도가 사인 한 주기를 따릅니다

한 수명에 X 속도가 사인 한 주기를 따릅니다

X만 교체하고 Y·Z는 보존합니다

이 예의 조건

한 수명 동안 X 속도가 사인 한 주기를 따릅니다

한 수명에 X 속도가 사인 한 주기를 따릅니다

X만 교체하고 Y·Z는 보존합니다

이 예의 조건

관계도의 보충 설명

사용자 정의 모듈 사용하기

사용자 정의 모듈 활용 팁

이 페이지 목차

이 페이지 목차