FAQ 및 문제 해결

이 섹션에서는 WebGL 최적화 과정에서 발생하는 일반적인 문제에 대한 해결책과 자주 묻는 질문에 대한 답변을 수집합니다.

설치 및 데모 씬

Q: 데모 씬을 열었는데 모든 머티리얼과 개체가 분홍색입니다!

A: 프로젝트에서 URP를 사용하고 있지만 데모 씬은 기본적으로 BiRP로 설정되어 있기 때문입니다. WebAdaptivePerformance/Demo/Import Me (URP).unitypackage에 위치한 패키지의 압축을 풀면 됩니다. 셰이더가 자동으로 업데이트됩니다.

Q: 플러그인을 설치했지만 게임의 시각적 측면에서 전혀 변하는 것이 없습니다.

A: 다음 체크리스트를 확인하세요:

• 프로젝트 설정에서 플러그인이 활성화되어 있습니까? Scaler가 추가되고 활성화되어 있습니까?
• 원래 Unity의 그래픽 설정이 최대로 구성되어 있습니까? 이미 설정이 낮다면 플러그인이 줄일 수 있는 것은 없습니다.
• 디바이스가 부하를 완벽하게 처리하고 있으며 FPS가 안정적일 수 있습니다. Dashboard 프리팹을 씬에 추가하여 Indexer의 현재 결정을 모니터링하십시오.
• 모든 것이 올바르게 구성되었지만 효과가 없다면 저희에게 연락 주시면 문제 해결을 돕겠습니다.

해상도 및 인터페이스(UI)

Q: 해상도가 변경되지 않습니다(Resolution Scaler 비활성).

A: 가장 일반적인 두 가지 이유는 다음과 같습니다:

1. BiRP를 사용하고 RenderTextureScaling 모드인 경우: Scaler 설정의 Target Tags 배열을 확인하십시오. 게임 카메라의 이름이 다른 경우(MainCamera가 아님) 해당 태그를 입력해야 합니다. 그렇지 않으면 플러그인이 카메라를 찾을 수 없습니다.
2. NativeBrowserScaling 모드는 빌드된 WebGL 렌더링 환경에서만 작동합니다. Unity 에디터 내부에서는 아무것도 하지 않습니다.

Q: FPS가 떨어지면 내 UI도 왜곡되거나 흐려집니다!

A: BiRP에서 RenderTextureScaling을 선택했는지 확인하세요. Canvas 자체가 Screen Space - Overlay 모드로 설정되어야 합니다(또는 UI 전용 카메라를 사용해야 합니다).

Q: 표준 UI 버튼은 제대로 작동하지만 3D 객체의 마우스 클릭(사용자 정의 레이캐스트)이 엉망입니다.

A: 표준 EventSystem 이벤트는 WebScaledPhysicsRaycaster 구성 요소에 의해 완벽하게 수리됩니다. 그러나 코드로 수동 레이캐스트를 호출하는 경우(Camera.ScreenPointToRay()) 해상도가 렌더링된 화면과 일치하지 않아 클릭 위치가 어긋나게 됩니다. 이 목적을 위해 플러그인의 메서드인 WebRaycasterUtility.TryComputeScaledRay()를 사용하십시오.

측정 항목 및 시스템 동작

Q: 지연으로 인해 그래픽 품질이 떨어졌습니다. 현재 FPS가 다시 높아졌는데 그래픽이 회복되지 않습니다!

A: **안티 요요 페널티 시스템(Anti Yo-Yo Penalty System)**이 활성화되었을 가능성이 매우 큽니다. 플러그인은 불안정성(Quality flickering)을 방지하기 위해 일시적으로 시각적 향상을 차단했습니다.

• 그래픽이 더 빨리 안정화되기를 원하면 Penalty Lockout Duration 매개변수의 한계를 줄이십시오(예: 10초로 설정).
• Increase Cooldown도 확인하십시오. 대기 시간이 너무 길게 설정되어 있을 수 있습니다.

Q: 대시보드(Dashboard)는 씬이 비어 있음에도 지속적으로 CPU 병목 현상(CPU Bottleneck) 또는 Unknown을 나타냅니다.

A: 플레이어 설정(Player Settings)에서 Frame Timing Stats를 활성화하는 것을 잊지 마십시오. 그런 다음 Application.targetFrameRate = -1로 설정되어 있는지 확인하십시오. 시간 새로 고침에 대한 제한을 제거하면 브라우저의 setTimeout으로 인한 감속으로부터 메트릭을 분리하고 자유롭게 만듭니다.

Q: 캐릭터(또는 물리적 소품)가 강하게 말을 더듬거나 "랙(lags)"이 걸립니다.

A: 이것은 Physics Step Scaler의 강제 활성화로 인한 부작용입니다. 과도한 성능 저하 시 CPU 충돌을 방지하기 위해 Time.fixedDeltaTime을 조절합니다. 씬에 있는 모든 캐릭터의 Rigidbody 구성 요소 탭에 있는 Interpolate(또는 Extrapolate) 설정을 활성화하여 순수하고 유연한 전환을 보장하십시오.

Q: Shadow Scalers (그림자)가 활성화되어 있지만 성능은 계속 저하되고 그림자는 온전합니다.

A: 이러한 모듈은 실시간(Realtime) 동적 반사 및 그림자만 감독하고 작동합니다. 조명 설정이 "미리 계산됨(Baked/Lightmaps)"으로 표시되는 경우 이 기능의 영향을 받지 않습니다.

커스텀 스케일러(Custom Scalers)

Q: 내 커스텀 Scaler가 에디터 모드에서는 훌륭하게 작동하는데 WebGL 빌드 버전에서는 완전히 증발해 버립니다!

A: 정상적인 내부 절차에 따라 IL2CPP 아키텍처 통합자가 이를 불필요한 코드("dead code")로 판단하여 제거했기 때문입니다. 생성한 Custom Scaler의 기본 클래스를 선언하는 상단 여백에 [UnityEngine.Scripting.Preserve] 속성을 추가하여 강제로 포함시키십시오.