2-3. 파라미터 바인딩 | UE5 Niagara Deep Dive

01

Namespace 계층 구조

5개의 파라미터 스코프

Niagara의 모든 파라미터는 Namespace로 스코프가 결정됩니다. 각 네임스페이스는 고유한 접근 권한과 수명주기를 가집니다.

Engine 읽기 전용 | DeltaTime, Owner, World 등 엔진 제공 데이터

User 읽기/쓰기 | Blueprint/인스턴스에서 외부 설정 가능

System System 그룹에서 쓰기 | 모든 Emitter에서 읽기 가능

Emitter Emitter 그룹에서 쓰기 | 해당 Emitter의 Particle에서 읽기 가능

Particles Particle 그룹에서 쓰기 | 개별 파티클 데이터

추가 네임스페이스

Namespace	용도	예시
`Transient`	한 프레임 동안만 유효한 임시 데이터	`Transient.TempForce`
`Output`	모듈의 출력 전용 네임스페이스	`Output.Module.Force`
`Module`	모듈 로컬 데이터 (Input Map의 값들)	`Module.Strength`
`StackContext`	배치 위치에 따라 자동 해석	`StackContext.Age`

Transient의 활용

Transient 네임스페이스의 데이터는 다음 프레임에 사라집니다. 중간 계산 결과나 모듈 간 임시 데이터 전달에 사용하세요. Particles 네임스페이스와 달리 메모리에 지속 저장되지 않아 성능에 유리합니다.

02

링크 규칙과 데이터 접근

읽기/쓰기 권한 규칙

Niagara에서 파라미터의 읽기와 쓰기는 엄격한 링크 규칙에 의해 관리됩니다.

실행 컨텍스트	읽기 가능	쓰기 가능
System Spawn/Update	Engine, User, System	System
Emitter Spawn/Update	Engine, User, System, Emitter	Emitter
Particle Spawn/Update	Engine, User, System, Emitter, Particles	Particles, Transient

링크 규칙 예시
// 허용되는 바인딩
Particle Update 모듈에서:
  Read: System.Age          // 상위 스코프 읽기 OK
  Read: Emitter.SpawnRate   // 상위 스코프 읽기 OK
  Read: Particles.Position  // 같은 스코프 읽기 OK
  Write: Particles.Color    // 같은 스코프 쓰기 OK

// 허용되지 않는 바인딩
Particle Update 모듈에서:
  Write: System.CustomData   // 상위 스코프 쓰기 X
  Write: Emitter.TotalCount  // 상위 스코프 쓰기 X

// Emitter Update에서 Particle 데이터 접근 불가
Emitter Update 모듈에서:
  Read: Particles.Position   // 하위 스코프 읽기 X
  // (Particle Attribute Reader Data Interface 필요)

Emitter에서 Particle 데이터 접근

Emitter Update에서 개별 파티클의 데이터를 읽으려면 Particle Attribute Reader Data Interface를 사용해야 합니다. 직접 접근은 불가능합니다. 이 제한은 병렬 처리의 데이터 안전성을 보장하기 위한 것입니다.

03

User 파라미터와 외부 노출

Blueprint에서 Niagara 파라미터 제어

User 네임스페이스의 파라미터는 Niagara System 외부, 특히 Blueprint에서 접근하여 런타임에 값을 변경할 수 있습니다.

User 파라미터 생성 및 사용
// 1. Parameters 패널에서 User 파라미터 추가
+ → Make New → User
  Name: EmitColor
  Type: LinearColor
  Default: (1.0, 0.5, 0.0, 1.0)

// 2. Initialize Particle 모듈에서 바인딩
Color → Link Inputs → User.EmitColor

// 3. Blueprint에서 런타임 제어
NiagaraComponent->SetColorParameter(
    "User.EmitColor",
    FLinearColor(0.0, 1.0, 0.0, 1.0)  // 초록색으로 변경
);

Blueprint API - 주요 함수

함수	파라미터 타입	설명
`SetFloatParameter`	float	User.파라미터명으로 float 값 설정
`SetVectorParameter`	FVector	Vector3 파라미터 설정 (위치, 방향 등)
`SetColorParameter`	FLinearColor	색상 파라미터 설정
`SetIntParameter`	int32	정수 파라미터 설정
`SetBoolParameter`	bool	불리언 파라미터 설정
`SetNiagaraVariable`	FNiagaraVariable	범용 변수 설정 (모든 타입)

Blueprint에서 Niagara 파라미터 제어 (C++)
// C++에서 User 파라미터 설정
UNiagaraComponent* NiagaraComp = FindComponentByClass<UNiagaraComponent>();

// float 파라미터
NiagaraComp->SetVariableFloat("User.SpawnRate", 100.0f);

// Vector 파라미터
NiagaraComp->SetVariableVec3("User.TargetLocation", TargetPos);

// 머티리얼 파라미터
NiagaraComp->SetVariableMaterial("User.ParticleMaterial", DynMaterial);

04

Parameter Map 디버깅

파라미터 문제를 추적하는 방법

파라미터 바인딩이 잘못되면 이펙트가 예상대로 동작하지 않습니다. Niagara는 이를 진단할 수 있는 도구를 제공합니다.

Attribute Spreadsheet

Niagara 에디터의 Attribute Spreadsheet 탭에서 모든 활성 파티클의 Attribute 값을 스프레드시트 형태로 실시간 확인할 수 있습니다.

디버깅 체크리스트
// 파라미터가 예상대로 동작하지 않을 때 확인 사항

1. 네임스페이스 확인
   // Particles.Color와 Emitter.Color는 완전히 다른 파라미터
   // Parameters 탭에서 전체 이름 확인

2. 쓰기 컨텍스트 확인
   // Particle Update에서 Emitter 네임스페이스에 쓰려고 하면 무시됨
   // 에디터에서 경고 아이콘 확인

3. 모듈 실행 순서 확인
   // 뒤에 배치된 모듈이 앞선 모듈의 값을 덮어쓸 수 있음
   // Attribute Spreadsheet에서 각 모듈 후 값 변화 추적

4. Default Value 확인
   // Module Input의 DefaultMode가 "Fail if not set"이면
   // 값이 설정되지 않았을 때 모듈이 동작하지 않음

5. Type Mismatch 확인
   // float를 Vector에 바인딩하려 하면 실패
   // 컴파일 에러 메시지 확인

Parameters 패널 활용

Parameters 패널에서 파라미터를 검색하고, 어떤 모듈이 해당 파라미터를 읽고 쓰는지 참조 관계를 확인할 수 있습니다. 파라미터 이름을 우클릭하면 해당 파라미터를 사용하는 모든 위치로 이동할 수 있습니다.

SUMMARY

핵심 요약

Niagara 파라미터는 5개의 주요 Namespace로 스코프가 구분됩니다: Engine, User, System, Emitter, Particles
링크 규칙: 하위 스코프에서 상위 스코프의 읽기는 가능하지만, 쓰기는 불가능합니다.
User 파라미터는 Blueprint에서 런타임에 제어 가능한 외부 노출 인터페이스입니다.
Transient 네임스페이스는 프레임 내 임시 데이터용으로, 다음 프레임에 사라집니다.
Attribute Spreadsheet와 Parameters 패널으로 파라미터 값을 실시간 디버깅할 수 있습니다.
Emitter에서 Particle 데이터를 읽으려면 Particle Attribute Reader Data Interface가 필요합니다.

PRACTICE

도전 과제

배운 내용을 직접 실습해보세요

실습 1: System/Emitter/Particle 스코프 파라미터

Parameters 패널에서 System 스코프(User.Color), Emitter 스코프(Emitter.SpawnRate), Particle 스코프(Particles.Velocity) 파라미터를 각각 생성하고, 모듈에서 바인딩하여 사용하세요.

실습 2: User Parameter 노출

User.Intensity(Float)와 User.EffectColor(LinearColor) 파라미터를 만들고, 블루프린트에서 SetNiagaraVariableFloat, SetNiagaraVariableLinearColor로 런타임에 값을 변경하는 시스템을 구현하세요.

심화 과제: Parameter Map을 활용한 이미터 간 통신

한 이미터에서 계산한 값(예: 파티클 총 수, 평균 위치)을 System 스코프 파라미터에 기록하고, 다른 이미터에서 이 값을 읽어 동작을 변경하는 이미터 간 데이터 공유를 구현하세요.