사용자 정의 모듈

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

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

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

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

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

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

단계	정해야 할 것	결과물	검토 기준
문제 정의	반복되는 동작과 적용 대상	모듈로 뺄 책임	여러 효과에서 재사용할 가치가 있는가
입력 설계	노출할 값과 기본값	User/Emitter/Particle 입력	외부에서 조절해야 할 값만 열었는가
계산 그래프	노드 흐름과 타입	중간 계산 결과	컴파일 경고와 자동 변환이 없는가
출력 작성	덮어쓸 파티클 속성	Position, Color, Velocity 등	다른 모듈과 쓰기 순서가 충돌하지 않는가
배포	이름, 카테고리, 설명	재사용 가능한 모듈	다른 이미터에서 바로 의미가 보이는가

사용자 정의 모듈이란?

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

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

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

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

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

구분	예시	좋은 설계	피해야 할 상태
User 입력	User.Color, User.Strength	시스템 외부에서 조정할 값만 노출	필요 없는 값까지 모두 공개
Emitter 입력	Emitter.SpawnRate	이미터 범위의 기준값 읽기	다른 이미터 값과 혼동
Particle 입력	Particle.Position, Particle.Age	현재 파티클 상태를 계산 재료로 사용	쓰기 전후 순서 불명확
Local 값	중간 계산 결과	모듈 내부에서만 사용	이름이 공개 값처럼 보임
Output	Particle.Color, Particle.Velocity	최종 쓰기 속성과 순서 명시	다른 모듈이 다시 덮어씀

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

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

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

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

모듈 입력(Input) 및 출력(Output) 설정

모듈 에디터의 개요(Overview) 패널에서 Module을 선택합니다.
디테일(Details) 패널에서 Inputs와 Outputs 섹션을 찾습니다.
Outputs에 Particles.Velocity를 추가합니다. (기본적으로 있을 수 있습니다.) 우리는 이 모듈에서 파티클의 속도를 변경할 것이므로, 변경된 속도 값을 출력해야 합니다.
- + 버튼을 누르고 Add Output을 선택한 후 Particles.Velocity를 찾아 추가합니다.
Inputs에 ZigzagStrength (Float), ZigzagFrequency (Float) 두 개의 사용자 정의 입력을 추가합니다. 이는 모듈 외부에서 제어할 수 있는 파라미터가 됩니다.
- + 버튼을 누르고 Add Input을 선택한 후 New Input을 선택합니다.
- Name을 ZigzagStrength, Type을 Float으로 설정합니다.
- 같은 방식으로 ZigzagFrequency (Float)를 추가합니다.

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

스크립트 에디터(Script Editor) 패널로 이동합니다. 이곳에서 노드 기반의 비주얼 스크립트를 작성합니다.
기본적으로 Set New or Existing Parameter 노드가 Particles.Velocity와 연결되어 있을 것입니다. 만약 없다면, Output 노드에서 Particles.Velocity 핀을 드래그하여 Set New or Existing Parameter 노드를 생성합니다.
이제 파티클의 수명(Particles.NormalizedAge)을 기반으로 사인파(sine wave)를 생성하여 지그재그 움직임을 만들어낼 것입니다.
빈 공간에 우클릭하고 NormalizedAge를 검색하여 Get Particles.NormalizedAge 노드를 추가합니다.
* (곱하기) 노드를 추가하고, Get Particles.NormalizedAge의 출력을 첫 번째 입력에 연결합니다. 두 번째 입력에는 ZigzagFrequency (우클릭 -> Get Niagara Parameter -> ZigzagFrequency)를 연결합니다.
Sine 노드를 추가하고, * 노드의 출력을 Sine 노드의 입력에 연결합니다.
* (곱하기) 노드를 하나 더 추가하여 Sine 노드의 출력을 첫 번째 입력에 연결합니다. 두 번째 입력에는 ZigzagStrength를 연결합니다.
이제 최종 * 노드의 출력을 Set New or Existing Parameter 노드의 Velocity 입력(XYZ 중 하나, 예를 들어 X에 연결하여 좌우 지그재그)에 연결합니다. Append Vector 노드를 사용해 특정 축에만 값을 더할 수도 있습니다.
Tip: 간단하게 초기 속도를 설정하는 Add Velocity 노드를 사용하여 그 위에 지그재그 값을 더하는 방식으로 구현할 수도 있습니다. 이 경우, Set New or Existing Parameter 대신 Add (벡터 + 벡터) 노드를 사용합니다.

(Get Particles.NormalizedAge) ---[ * ]--- (Get ZigzagFrequency)
                                    |
                                  [ Sine ]
                                    |
                                  [ * ]--- (Get ZigzagStrength)
                                    |
(Result) --------------------------|
                                    |
(Apply to Particles.Velocity) ------

이 예시는 복잡해 보일 수 있지만, 핵심은 Particles.NormalizedAge (0에서 1까지 변하는 파티클의 수명 진행률)를 사용하여 반복적인 패턴을 만드는 것입니다.

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

아래 다이어그램은 사용자 정의 모듈을 재사용 가능하게 만드는 입력, 계산, 출력의 계약 구조를 보여줍니다.

외부 입력
ZigzagStrength / Frequency
외부 입력 디테일 패널에서 조절할 값만 모듈 입력으로 노출합니다.
스크립트 계산
스크립트 계산
Particles.NormalizedAge로 수명 진행률을 읽습니다. Sine으로 반복 패턴을 만들고 폭 값을 곱합니다. 기존 속도에 더할 축 성분만 분리합니다.
파티클 출력
Particles.Velocity
파티클 출력 최종 값은 한 속성에만 쓰고, 색상이나 크기는 다른 모듈에 맡깁니다.
이름
입력명은 단위와 의미가 보이게 짧게 정합니다.
기본값
추가하자마자 효과가 튀지 않는 안전한 값을 둡니다.
책임
한 모듈이 여러 속성을 과하게 바꾸지 않게 범위를 제한합니다.

사용자 정의 모듈 사용하기

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

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

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

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

검색창에 여러분이 만든 모듈 이름 NCM_ZigzagMovement를 검색하여 추가합니다.

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

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

ZigzagStrength를 높이면 지그재그 폭이 커지고, ZigzagFrequency를 높이면 더 자주 흔들립니다.

사용자 정의 모듈 활용 팁

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

사용자 정의 모듈은 만들기보다 유지하기가 더 어려울 수 있으므로, 입력 계약과 출력 책임, 기본값, 디버깅 지점을 함께 설계하는 것이 좋습니다.

목적 한 줄
예: 수명에 따라 X축 지그재그 속도를 더한다.
입력 노출
Strength, Frequency처럼 조절할 값만 디테일 패널에 보입니다.
계산 기준
NormalizedAge, Position, Velocity 중 무엇을 읽는지 명확히 둡니다.
출력 제한
한 모듈은 가능하면 한 속성만 책임져 충돌을 줄입니다.
저장과 검증
기본값으로 추가했을 때 효과가 과격하지 않은지 확인합니다.
입력 계약
름에 의미와 단위가 보이면 나중에 다른 사람이 값을 조절하기 쉽습니다.
속성 충돌
여러 사용자 모듈이 같은 Particles.Velocity를 Set으로 덮어쓰면 순서에 따라 결과가 달라집니다.
디버깅 단서
입력값, 중간 계산값, 최종 출력값을 분리해 보면 문제 노드를 빠르게 좁힐 수 있습니다.

사용자 정의 모듈은 나이아가라의 확장성을 여는 핵심 수단입니다.

초기에는 단일 입력-출력 구조부터 시작해, 단계적으로 조건 분기와 수학 연산을 추가하는 방식이 구현 리스크를 낮춥니다.

이제 나이아가라의 기본 모듈 사용법을 마치고, 다음 장에서는 파티클 속성을 더욱 정교하게 제어하는 고급 기법을 다룹니다.

사용자 정의 모듈은 재사용을 전제로 입력 계약과 출력 책임을 작게 잡아야 유지보수가 쉬워집니다.

점검	확인할 것	통과 기준	실패 신호
이름	모듈명과 입력명	역할이 바로 읽힘	범용 이름과 약어가 많음
기본값	입력 기본 상태	연결하지 않아도 안전한 결과	기본값만으로 폭주하거나 보이지 않음
네임스페이스	User, Emitter, Particle 범위	값의 소유자가 분명함	같은 이름이 여러 범위에 섞임
컴파일	타입과 연결 상태	경고 없이 통과	자동 변환과 끊긴 핀 존재
테스트	적용 예시와 경계값	다른 이미터에서도 같은 의미	특정 효과에만 우연히 맞음

사용자 정의 모듈은 재사용성을 얻는 대신 입력과 책임을 명확히 해야 하므로, 제작 전후 판단 기준을 묶어 둡니다.

Input 외부
바꿀 값인가? Amplitude, Frequency 고정값이 많으면 재사용성이 낮다.
Output 어떤 속성
책임지는가? Particles.Velocity 여러 속성을 섞으면 추적이 어렵다.
Default 안전한 기본값인가? 0, 1
기존 속도 유지 기본값만으로 효과가 깨지면 위험하다.
Debug 중간 값
볼 수 있는가? 속성 표시, 임시 색 문제 발생 위치를 찾기 어렵다.