나이아가라 스크립트 기본 개념
노드·매개변수·네임스페이스·데이터 타입으로 Module Script의 입력과 파티클 속성 계산 흐름을 구성합니다.
사용자 정의 모듈에서 노드를 이어 지그재그 모듈을 만들어 봤지만, 그때는 노드가 왜 그렇게 이어지는지보다 결과를 만드는 데 집중했습니다. 효과의 동작을 직접 설계하려면 그 노드 그래프, 즉 나이아가라 스크립트(Niagara Script)가 어떤 규칙으로 값을 읽고 쓰는지 알아야 합니다. 나이아가라 스크립트는 블루프린트처럼 노드를 연결하는 방식이라 코드를 많이 써 본 적이 없어도 다룰 수 있습니다. 이 글에서는 스크립트를 이루는 노드와 파라미터, 네임스페이스, 데이터 타입을 살펴보고, 파라미터 맵을 따라 값이 읽히고 쓰이는 흐름을 숫자로 따라가 봅니다.
노드로 값을 계산하는 스크립트
나이아가라 스크립트는 스크립트 에디터(Script Editor)에서 작업하는 비주얼 프로그래밍 공간입니다. Initialize Particle, Add Velocity, Scale Color 같은 기본 모듈도 안을 열어 보면 이 스크립트로 되어 있고, 사용자 정의 모듈도 같은 공간에서 로직을 만듭니다.
스크립트의 핵심 개념은 데이터 흐름(data flow)입니다. 각 노드는 더하기나 곱하기, 벡터 만들기, 값 꺼내기 같은 연산을 하나씩 하고, 그 결과를 다음 노드로 넘깁니다. 이렇게 이어진 흐름이 입자의 최종 속성을 계산합니다.
스크립트를 이루는 요소
노드
노드(node)는 스크립트를 이루는 가장 기본적인 단위로, 저마다 정해진 기능이나 연산을 합니다. 노드의 왼쪽에 있는 입력 핀(input pin)은 다른 노드에서 데이터를 받거나 값을 직접 입력받고, 오른쪽에 있는 출력 핀(output pin)은 노드가 처리한 결과를 내보냅니다. 한 노드의 출력 핀과 다른 노드의 입력 핀을 연결선(wire)으로 이으면 데이터가 흐르는 길이 생깁니다.
파라미터
파라미터(parameter)는 입자가 가진 속성, 예를 들어 Particles.Color, Particles.Position, Particles.Velocity나, 시스템과 이미터의 속성인 System.Age, Emitter.Age 같은 값을 가리킵니다. 스크립트에서 파라미터를 다루는 대표적인 노드는 둘입니다. Map Get은 들어온 파라미터 맵에서 Particles.Color나 Particles.Position 같은 값을 꺼내고, Map Set은 계산한 값을 속성에 써 넣은 파라미터 맵을 다음으로 넘깁니다.
네임스페이스
나이아가라의 파라미터는 네임스페이스(namespace)로 구분해 관리합니다. 이름 앞에 붙은 네임스페이스를 보면 그 값이 어디서 왔고 어느 범위에 속하는지 알 수 있습니다. 주요 네임스페이스는 다음과 같습니다.
Particles.: 입자 하나하나의 속성입니다.Particles.Position,Particles.Color,Particles.Lifetime이 그 예입니다.System.: 나이아가라 시스템 전체의 속성입니다.System.Age,System.LoopCount가 그 예입니다.Emitter.: 이미터 하나의 속성입니다.Emitter.Age,Emitter.ExecutionState가 그 예입니다.User.: 블루프린트나 C++ 같은 바깥에서 넘겨받는 사용자 파라미터입니다.User.MyCustomValue가 그 예입니다.Engine.: 언리얼 엔진이 제공하는 값입니다. 지난 프레임부터 흐른 시간인Engine.DeltaTime이 그 예입니다.Local.: 스크립트 안에서 잠깐 쓰는 지역 변수입니다.
네임스페이스 덕분에 어떤 파라미터가 어느 범위(scope)에서 정의되고 쓰이는지 분명히 알 수 있고, 이름이 같은 파라미터가 다른 범위에 있어도 서로 부딪히지 않습니다.
데이터 타입
모든 파라미터와 핀은 정해진 데이터 타입을 가지며, 맞는 타입끼리만 연결할 수 있습니다. 자주 쓰는 타입은 다음과 같습니다.
Float: 소수점이 있는 숫자 하나입니다.1.5나3.14같은 값입니다.Int32: 정수입니다.1이나100같은 값입니다.Vector2: X, Y 두 성분의 값입니다.Vector: X, Y, Z 세 성분의 값으로, 속도나 방향에 씁니다. 위치에는 넓은 월드의 좌표를 다루는Position타입을 따로 쓰므로, 좌표 공간과 변환을 확인합니다.Vector4: X, Y, Z, W 네 성분의 값입니다.Color: RGBA 색입니다.Quat: 회전을 나타내는 쿼터니언입니다.Bool: 참이나 거짓입니다.Enum: 미리 정해 둔 목록 가운데 하나를 고르는 열거형입니다.
Color와 쿼터니언은 Vector4와 성분 수가 같지만, 각각 색과 회전이라는 뜻을 가진 별도의 타입입니다. 성분 수가 같다고 서로 바꿔 쓰지 않습니다.
스크립트 에디터에서 작업하기
스택에서 모듈을 선택하면 선택 패널에 그 모듈의 입력 설정이 보입니다. 내부 그래프를 보려면 스택의 모듈 이름을 더블 클릭하거나 그 스크립트 에셋을 엽니다. 엔진에 들어 있는 기본 모듈은 여러 효과가 함께 쓰므로, 실습에서 그래프를 고칠 때는 기본 모듈 대신 새 스크래치 패드 모듈을 만들어 씁니다.
그래프의 빈 곳을 오른쪽 클릭하면 노드 검색창이 나타나고, 여기서 Add, Multiply, Sine, Make Vector, Map Get 같은 노드를 찾아 추가합니다. 노드의 출력 핀을 클릭한 채 끌어 다른 노드의 입력 핀에 놓으면 연결선이 생기며, 데이터가 흐르는 길을 눈으로 확인할 수 있습니다. 노드에 직접 값을 넣어야 할 때는 그 노드를 선택해 나타나는 속성에서 값을 바꿉니다.
파라미터 맵으로 읽고 쓰기
모듈 그래프의 기본 연결은 Input Map에서 Map Set을 거쳐 Output Module로 이어지는 선입니다. 그 옆으로 Map Get이 입력 맵에서 필요한 속성을 꺼내고, 연산 노드가 그 값을 계산해 Map Set의 해당 속성 핀에 연결합니다. 출력 노드는 바뀐 맵을 다음 모듈로 넘깁니다.
Parameter Map과 값 계산의 연결
입력 Velocity 100/빨강→Map Get→0.5를 곱해 50 계산→Map Set 기록→뒤 모듈 50/색 유지라는 본문 실제 값 전달 사례이다. 값 계산만으로 쓰기가 일어나지 않음을 드러낸다.
NIAGARA · CH5-1
읽어 계산한 값을 변경된 맵에 기록합니다
Parameter Map은 속성 집합을 전달합니다. Map Get이 꺼낸 값은 계산 뒤 Map Set의 속성 입력에 연결하고, 변경된 맵을 다음 모듈로 넘깁니다.
왼쪽 선 · Parameter Map
Input Map을 Map Set에 전달합니다. Map Set은 받은 맵의 해당 속성을 새 값으로 기록합니다.
오른쪽 선 · 계산할 값
Map Get으로 필요한 속성을 읽고 연산한 결과를 Map Set의 해당 속성 핀에 연결합니다.
아래 선 · 변경된 맵
Output Module로 전달해 뒤 모듈이 읽을 수 있게 합니다. 앞뒤 작성자와 Spawn/Update 실행 범위를 함께 확인합니다.
연결선은 데이터 전달입니다. 왼쪽은 속성 집합인 맵, 오른쪽은 읽어 계산한 값이며 Exec/Do 실행 핀이 아닙니다.
이 예의 조건
- 본문과 원 도표에 제시된 사례의 입력·조건을 사용합니다. 설명용 수치나 독립 비교 경로는 각 단계에 표시합니다.
- 현재 상태·값과 전환 근거의 위치는 모든 단계에서 같습니다. 조건이 맞지 않거나 실행되지 않은 경로를 성공한 동작으로 해석하지 않습니다.
| 관찰·상황 | 값·보충 정보 | 변화·이유 |
|---|---|---|
| Map 입력 현재 Velocity 100과 빨강을 읽는다. |
|
|
| 계산 0.5를 곱해 50을 만든다. |
|
|
| Map Set 뒤 50을 기록하면 뒤 모듈이 50을 읽는다. |
|
|
Parameter Map과 값 계산의 연결
입력 Velocity 100/빨강→Map Get→0.5를 곱해 50 계산→Map Set 기록→뒤 모듈 50/색 유지라는 본문 실제 값 전달 사례이다. 값 계산만으로 쓰기가 일어나지 않음을 드러낸다.
NIAGARA · CH5-1
읽어 계산한 값을 변경된 맵에 기록합니다
Parameter Map은 속성 집합을 전달합니다. Map Get이 꺼낸 값은 계산 뒤 Map Set의 속성 입력에 연결하고, 변경된 맵을 다음 모듈로 넘깁니다.
왼쪽 선 · Parameter Map
Input Map을 Map Set에 전달합니다. Map Set은 받은 맵의 해당 속성을 새 값으로 기록합니다.
오른쪽 선 · 계산할 값
Map Get으로 필요한 속성을 읽고 연산한 결과를 Map Set의 해당 속성 핀에 연결합니다.
아래 선 · 변경된 맵
Output Module로 전달해 뒤 모듈이 읽을 수 있게 합니다. 앞뒤 작성자와 Spawn/Update 실행 범위를 함께 확인합니다.
연결선은 데이터 전달입니다. 왼쪽은 속성 집합인 맵, 오른쪽은 읽어 계산한 값이며 Exec/Do 실행 핀이 아닙니다.
이 예의 조건
- 본문과 원 도표에 제시된 사례의 입력·조건을 사용합니다. 설명용 수치나 독립 비교 경로는 각 단계에 표시합니다.
- 현재 상태·값과 전환 근거의 위치는 모든 단계에서 같습니다. 조건이 맞지 않거나 실행되지 않은 경로를 성공한 동작으로 해석하지 않습니다.
| 관찰·상황 | 값·보충 정보 | 변화·이유 |
|---|---|---|
| Map 입력 현재 Velocity 100과 빨강을 읽는다. |
|
|
| 계산 0.5를 곱해 50을 만든다. |
|
|
| Map Set 뒤 50을 기록하면 뒤 모듈이 50을 읽는다. |
|
|
위 그림은 파라미터 맵과 계산할 값이 흐르는 두 경로를 구분해 보여 줍니다. 왼쪽 선은 Input Map에서 Map Set으로 바로 이어지는 파라미터 맵으로, 입자의 속성을 모두 담은 집합입니다. 오른쪽 선은 Map Get이 같은 입력 맵에서 필요한 속성을 읽고, 연산 노드가 새 값을 계산해 Map Set의 해당 속성 핀에 넣는 경로입니다. Map Set은 받은 맵에서 그 속성만 새 값으로 바꿔 쓰고, 아래쪽 선을 따라 바뀐 맵이 Output Module로 넘어가 뒤의 모듈이 읽을 수 있게 됩니다.
그림 아래의 설명처럼 이 연결선은 데이터가 전달되는 길이며, 비주얼 스크립팅 기본 개념에서 다루는 블루프린트의 Exec나 Do 같은 실행 핀이 아닙니다. 모든 나이아가라 스크립트가 Evaluate 같은 시작 노드를 가지는 것도 아닙니다. 그래서 그래프를 읽을 때는 모듈이 Spawn과 Update 가운데 어디에 놓였는지와, 스택의 앞뒤 모듈이 어떤 값을 읽고 쓰는지를 함께 확인합니다.
이 흐름을 숫자로 따라가 봅니다. 앞의 모듈이 속도 (100, 0, 0)cm/s와 빨간색을 써 두었다고 합시다. 스크래치 패드 모듈의 Map Get에서 속도를 읽고 0.5를 곱하면 (50, 0, 0)cm/s가 됩니다. 이 결과를 Map Set의 속도 입력에 연결하고 입력 맵도 Map Set으로 넘깁니다. 그러면 뒤의 모듈이 출력 맵에서 읽는 속도는 (50, 0, 0)cm/s이고, 색은 이 모듈에서 새로 쓰지 않았으므로 입력 맵의 빨간색을 그대로 이어받습니다.
흔한 실수는 Map Get에서 꺼낸 값으로 계산만 해 두고 Map Set에 연결하지 않는 것입니다. 그렇게 하면 계산 결과는 어디에도 쓰이지 않으므로 속도는 바뀌지 않습니다.
정리
- 나이아가라 스크립트는 노드가 연산한 결과를 다음 노드로 넘기는 데이터 흐름으로 입자의 속성을 계산하며, 기본 모듈도 이 스크립트로 되어 있습니다.
- 파라미터는
Particles.,System.,Emitter.,User.,Engine.,Local.같은 네임스페이스로 값이 속한 범위를 구분합니다. - 맞는 데이터 타입끼리만 연결할 수 있으며, 위치에는
Position타입을 쓰고Color나 쿼터니언을 성분 수만 보고Vector4와 바꿔 쓰지 않습니다. - 모듈 그래프는
Input Map에서Map Set을 거쳐Output Module로 맵을 넘기고,Map Get으로 읽어 계산한 값을Map Set의 속성 핀에 씁니다. - 연결선은 실행 순서가 아니라 데이터 전달이며,
Map Set에 연결하지 않은 계산은 속성을 바꾸지 않습니다.
연습 문제
1. 다음 모듈이 읽을 값
입력 속도가 (80, 0, 0)cm/s이고 이 모듈의 배율을 0.25로 바꿨습니다. 색 입력은 건드리지 않았고, 뒤쪽에 속도나 색을 쓰는 다른 모듈도 없습니다. 출력 맵의 속도와 색은 어떻게 될까요? 같은 모듈을 Particle Update에 두어 다음 틱에도 실행한다면, 다음 입력은 초기 속도와 바로 앞의 출력 가운데 어느 쪽일까요?
해설 보기
속도는 80 × 0.25 = 20이므로 (20, 0, 0)cm/s이고, 색은 이 모듈이 쓰지 않았으므로 입력 맵의 값을 그대로 이어받습니다.
지금 속도를 읽는 Update 모듈은 다음 틱에 바로 앞의 출력을 읽습니다. 그래서 다음 틱에는 (20, 0, 0)cm/s를 읽어 다시 0.25를 곱해 (5, 0, 0)cm/s로 줄입니다. 같은 모듈을 Particle Spawn에 한 번 두었다면 생성 순간의 속도만 정할 뿐, 이런 틱마다의 반복은 일어나지 않습니다.
2. 계산했는데 바뀌지 않는 속도
스크래치 패드 모듈에서 Map Get으로 Particles.Velocity를 읽어 2를 곱하는 Multiply 노드까지 만들었는데, 미리보기의 속도가 그대로입니다. 무엇이 빠졌을까요?
해설 보기
Multiply의 결과를 Map Set의 Particles.Velocity 입력에 연결하지 않았을 가능성이 큽니다. Map Get으로 꺼내 계산한 값은 Map Set으로 맵에 써야 다음 모듈이 읽을 수 있습니다.
연결했는데도 그대로라면 Map Set이 Output Module로 이어져 있는지, 그리고 이 모듈보다 아래에서 속도를 다시 쓰는 모듈이 없는지 확인합니다.
3. 네임스페이스로 범위 알아보기
Particles.Lifetime, Emitter.Age, User.Intensity, Engine.DeltaTime 네 파라미터를 보고, 각각 어디서 온 값이고 어느 범위에 속하는지 설명해 보세요.
해설 보기
Particles.Lifetime은 입자 하나하나가 가진 수명이므로 입자마다 값이 다를 수 있습니다. Emitter.Age는 이미터 하나가 시작된 뒤 흐른 시간으로, 그 이미터의 모든 입자가 같은 값을 봅니다.
User.Intensity는 블루프린트나 C++, 컴포넌트의 설정 같은 바깥에서 넘겨받는 사용자 파라미터이며, 시스템 인스턴스마다 값이 다를 수 있습니다. Engine.DeltaTime은 엔진이 제공하는 값으로, 지난 프레임부터 흐른 시간을 나타냅니다.
Map Get과 Map Set으로 파라미터 맵을 다루는 예는 Epic의 스크래치 패드 모듈 문서에서 확인할 수 있습니다.
다음 글 기본 수학 함수와 벡터 연산에서는 이 파라미터 맵의 흐름에 더하기와 곱하기, 사인, 벡터의 길이와 정규화 같은 수학 연산을 연결해 봅니다.