디버깅 도구
Attribute Spreadsheet, Debug Drawing, 일반적인 문제 해결 패턴을 학습합니다.
Attribute Spreadsheet
파티클 데이터를 스프레드시트로 확인
Attribute Spreadsheet는 Niagara 에디터에서 모든 활성 파티클의 Attribute 값을 표 형태로 실시간 확인하는 도구입니다. 파티클의 Position, Velocity, Color, 커스텀 Attribute 등 모든 데이터를 한눈에 볼 수 있습니다.
// Niagara 에디터 하단 탭에서
Attribute Spreadsheet 탭 클릭
// 표시 설정:
Emitter 선택: 특정 Emitter의 파티클만 표시
Column 필터: 보고 싶은 Attribute만 선택
Sort: 특정 Attribute 기준으로 정렬
// 확인 가능한 데이터:
ParticleID | Position.X/Y/Z | Velocity.X/Y/Z | Color.R/G/B/A
Age | NormalizedAge | Lifetime | SpriteSize | Mass | ...
// 디버깅 활용:
// 1. NaN 값 확인: Position이 NaN이면 수학 에러
// 2. 범위 초과: Position이 비정상적으로 큰 값
// 3. 수명 확인: Age > Lifetime인데 살아있는 파티클
// 4. 커스텀 Attribute: 값이 예상대로 설정되었는지
Attribute Spreadsheet는 CPU Sim 파티클만 표시할 수 있습니다. GPU Sim 파티클의 데이터를 확인하려면 임시로 CPU Sim으로 전환하거나, Debug Drawing을 사용하세요.
Debug Drawing
시각적 디버그 표시
Niagara에서 파티클의 속도 벡터, 바운딩 박스, 그리드 셀 등을 시각적으로 표시하여 동작을 직관적으로 확인할 수 있습니다.
// 콘솔 명령으로 디버그 표시
fx.Niagara.Debug.DrawSystemBounds 1
// System의 바운딩 박스를 표시
fx.Niagara.Debug.DrawParticles 1
// 파티클 위치에 점 표시
// Niagara 에디터 Preview에서
Show → Bounds // 바운드 표시
Show → Particle Counts // 파티클 수 표시
// 커스텀 디버그: Scratch Pad에서 Debug Line 그리기
Draw Debug Line
{
Start: Particles.Position
End: Particles.Position + Particles.Velocity * 0.1
Color: Green
}
// 각 파티클의 속도 방향을 녹색 선으로 표시
일반적 문제와 해결
자주 발생하는 이슈와 진단 방법
| 문제 | 원인 | 해결 |
|---|---|---|
| 파티클이 보이지 않음 | 바운드 밖, 머티리얼 문제, 크기 0 | 바운드 표시 켜기. 머티리얼 Usage 확인. SpriteSize 확인. |
| 이펙트가 멈추지 않음 | Loop Behavior: Infinite | Once로 변경 또는 게임에서 Deactivate 호출 |
| 파티클이 원점에 모임 | Position이 초기화되지 않음 | Particle Spawn에서 Position 설정 모듈 확인 |
| 파티클이 순간이동 | NaN/Inf 값, 힘 계산 오류 | Attribute Spreadsheet에서 NaN 확인. 0 나누기 방지. |
| 색상이 적용되지 않음 | 머티리얼에 Particle Color 미사용 | 머티리얼에 Particle Color 노드 연결 |
| GPU Sim 컴파일 에러 | GPU 미지원 함수/DI 사용 | 에러 메시지의 호환성 경고 확인. 대안 함수 사용. |
| 이벤트가 동작하지 않음 | GPU Sim에서 이벤트 사용 | CPU Sim으로 변경 또는 Data Channel 사용 |
| 프레임 드롭 | 파티클 수 초과, 오버드로우 | stat Niagara로 진단. 파티클 수/크기 줄이기. |
// 흔한 NaN 원인: 0으로 나누기, normalize(zero vector)
// 나쁜 코드:
float3 Dir = normalize(TargetPos - Particles.Position);
// TargetPos == Particles.Position이면 NaN 발생!
// 좋은 코드:
float3 Offset = TargetPos - Particles.Position;
float Dist = length(Offset);
float3 Dir = Dist > 0.001 ? Offset / Dist : float3(0,0,1);
// 나쁜 코드:
float Ratio = Value / Divisor;
// Divisor == 0이면 Inf 또는 NaN 발생!
// 좋은 코드:
float Ratio = Divisor != 0 ? Value / Divisor : 0.0;
컴파일 에러와 경고 해석
Niagara 에디터의 에러 메시지
| 에러/경고 | 의미 | 조치 |
|---|---|---|
| "Parameter not found" | 바인딩된 파라미터가 존재하지 않음 | 파라미터 이름/네임스페이스 오타 확인 |
| "Type mismatch" | 입력/출력 타입이 불일치 | float vs Vector, int vs float 등 타입 확인 |
| "Incompatible with GPU" | GPU Sim에서 사용 불가능한 기능 | CPU Sim 전환 또는 GPU 호환 대안 사용 |
| "Missing dependency" | 모듈이 필요로 하는 선행 모듈 없음 | Solve Forces 등 필수 모듈 추가 |
| "Bounds warning" | 파티클이 바운드 밖으로 나감 | 바운드 크기 증가 또는 Fixed Bounds 설정 |
Niagara 에디터 하단의 Compilation Log 탭에서 컴파일 과정의 모든 에러와 경고를 확인할 수 있습니다. 에러를 클릭하면 해당 모듈/노드로 이동합니다. 에러가 있는 모듈은 스택에서 빨간색 아이콘으로 표시됩니다.
핵심 요약
- Attribute Spreadsheet로 CPU Sim 파티클의 모든 Attribute를 실시간 확인합니다.
- Debug Drawing으로 바운드, 속도 벡터, 그리드 셀 등을 시각적으로 표시합니다.
- NaN 방지: normalize(zero vector)와 0 나누기를 항상 체크하세요.
- "파티클이 안 보임"의 가장 흔한 원인은 바운드, 머티리얼 Usage, 크기 0입니다.
- Compilation Log에서 에러/경고를 확인하고 해당 모듈로 바로 이동할 수 있습니다.
- GPU Sim 디버깅은 CPU Sim보다 어려우므로, 문제 발생 시 임시로 CPU Sim으로 전환하여 진단하세요.
도전 과제
배운 내용을 직접 실습해보세요
Niagara Debugger의 Attribute Spreadsheet를 열어 각 파티클의 Position, Velocity, Age, Color 등 모든 속성을 실시간으로 확인하세요. 비정상적인 값(NaN, 극단값)을 가진 파티클을 필터링하세요.
fx.Niagara.Debug.Enabled=1 콘솔 명령으로 화면에 파티클 통계를 표시하세요. Debug Drawing을 활성화하여 파티클의 속도 벡터, 충돌 노말, Neighbor Grid 셀을 시각화하세요.
에디터 유틸리티 위젯으로 프로젝트의 모든 Niagara System을 순회하며, 파티클 수 한계 초과, GPU Sim 호환성, 누락된 머티리얼 등을 자동 검사하는 Validation 도구를 만드세요.