문제 해결

먼저 Console을 Clear한 뒤 문제를 다시 재현하고, 가장 먼저 발생한 오류를 확인하세요. 뒤에 연속으로 표시된 오류만으로는 원인을 판단하기 어려울 수 있습니다.

증상 빠른 찾기

증상	바로 확인할 항목
땀이 전혀 보이지 않음	표시 상태와 대상 확인
설치 후 메뉴가 없거나 일부만 보임	모듈·리그 조건 확인
Tuning 값을 바꿨지만 달라지지 않음	즉시 반영과 FX 적용 구분
Shader Compile 또는 Hold on이 오래 표시됨	Import·컴파일 대기
Play Mode에서 얼굴이 깨짐	Write Defaults·Face Tracking 확인
MMD 댄스 중 표정·립싱크가 작동하지 않음	MMD와 Write Defaults 확인
Unity에서는 정상인데 VRChat에서만 깨짐	업로드 단계의 Mesh 교체 확인
설치 후 기존 PhysBone이 움직이지 않음	PhysBone 및 빌드 도구 확인
Invalid localAABB가 반복됨	Exhale 상태와 얼굴 문제 분리
편집 화면에서 땀만 숨기기·1인칭 입김·부위 마스크	자주 묻는 사용 팁
완전히 제거한 뒤 다시 설치하고 싶음	제거·재설치 절차

땀이 전혀 보이지 않음

먼저 Auto Mode의 변화까지 한 번에 확인하지 말고, 수동 상태에서 표시 자체가 정상인지 확인합니다.

1. 아바타 메뉴에서 땀 켜기를 ON으로 바꿉니다.
2. 자동 모드를 OFF로 바꾸고 땀 %를 50% 또는 100%로 올립니다.
3. Setup의 바디 메쉬와 땀 적용 Element가 실제 피부 Submesh를 가리키는지 확인합니다.
4. 렌더 순서 자동 설정을 사용한다면 선택한 Body 재질의 Render Queue가 2454 이하인지 확인합니다.
5. Setup — 자동 설치 / 업데이트를 다시 실행한 뒤 Console의 첫 오류를 확인합니다.

설치 후 메뉴가 없거나 일부만 보임

설치한 모듈과 Setup에서 선택한 옵션에 따라 메뉴 항목이 자동으로 달라집니다.

1. Base만 설치했다면 파티클 하위 메뉴가 없는 것이 정상이고, Effects를 설치하지 않았다면 낙하 물방울·바닥 물자국·입김·몸 김이 생성되지 않습니다.
2. 입체기능을 탑재하지 않았다면 입체효과 (사진전용, 고부하) 메뉴가 없는 것이 정상입니다.
3. Non-Humanoid이거나 Motion Pendulum을 만들 수 없는 구성에서는 자동 모드·입김·몸 김이 생성되지 않을 수 있습니다. 자세한 조건은 호환성을 확인하세요.
4. 패키지를 새로 가져왔다면 아바타를 선택하고 Setup — 자동 설치 / 업데이트를 다시 실행합니다.

Tuning 값을 바꿨지만 반영되지 않음

Hierarchy의 아바타 루트 > RealSweat 오브젝트를 선택하고 RealSweatSystem Tuning 컴포넌트를 확인하세요.

• 전체 땀양, 물방울 크기와 패턴 밀도의 표면 외형은 호환 재질에 즉시 반영됩니다.
• 감도, 누적 곡선, 낙하 물방울·바닥 물자국·입김·몸 김과 성능 제한은 FX에 적용을 눌러야 생성된 Animator와 파티클에 반영됩니다.
• Play Mode에서 바꾼 Inspector 값은 Play Mode를 종료하면 되돌아갑니다. Edit Mode에서 값을 조절한 뒤 FX에 적용을 누르세요.

재질의 바디 Shadow Strength를 바꿨다면 FX에 적용을 다시 눌러 RealSweat 재질로 복사하세요. 자세한 구분은 튜닝 가이드를 확인하세요.

Shader Compile 또는 Hold on이 오래 표시됨

처음 UnityPackage를 가져오면 Shader Compile과 Asset Database Import가 함께 진행되어 몇 분 이상 걸릴 수 있습니다. 경량화된 런타임 셰이더라도 Editor의 Variant 컴파일 시간과는 별개입니다.

1. Unity 우측 하단의 Import·Compile 진행 표시가 끝날 때까지 기다립니다.
2. Hold on 창이 Unity 코드 실행을 기다리는 동안에는 Setup이나 Material Inspector를 반복해서 누르지 않습니다.
3. 작업이 끝난 뒤 Console을 Clear하고 Setup을 한 번 실행합니다.
4. 컴파일 오류가 남는다면 가장 먼저 발생한 오류부터 해결합니다.

같은 화면에서 조작할 때마다 Hold on이 반복된다면 단순한 최초 컴파일이 아닐 수 있습니다. Console의 첫 오류와 어떤 Inspector에서 발생했는지 함께 확인하세요.

v1.0.0 또는 v1.0.1에서 v1.0.2로 업데이트

1. 아바타 Prefab 또는 Unity Project를 백업합니다.
2. v1.0.2 UnityPackage를 가져옵니다.
3. Base와 Effects를 함께 사용한다면 두 패키지의 버전을 맞춥니다.
4. 아바타를 선택하고 Setup — 자동 설치 / 업데이트를 한 번 실행합니다.
5. Play Mode에서 얼굴, 땀 토글과 Auto Mode를 확인합니다.

Play Mode에서 얼굴 표정이 깨짐

가능한 원인: 이전 버전의 Animator 구성이 Write Defaults OFF 또는 Face Tracking Animator와 충돌할 수 있습니다.

해결:

1. v1.0.2로 업데이트합니다.
2. Setup이 생성한 Merge Animator Priority와 Animator 항목을 수동 변경하지 않았는지 확인합니다.
3. Setup — 자동 설치 / 업데이트를 다시 실행합니다.
4. 얼굴 표정, 땀 토글, Auto Mode를 함께 확인합니다.

MMD 댄스 중 표정·립싱크가 작동하지 않음

1. v1.0.2로 업데이트하고 Setup — 자동 설치 / 업데이트를 한 번 실행합니다.
2. Write Defaults 호환 방식을 **자동 감지 (권장)**로 설정합니다.
3. Modular Avatar를 업데이트하고, 대상 구성에 필요하다면 MMD World Support를 활성화합니다.
4. Play Mode뿐 아니라 실제로 사용할 MMD 월드에서 표정·립싱크·땀 켜기·Auto Mode를 확인합니다.

외부 FX State가 모두 WD ON이면 v1.0.2는 생성되는 RealSweat State도 WD ON으로 맞춥니다. WD OFF, ON/OFF 혼합 또는 판정 불가 구성은 호환 구조를 유지하지만, 월드마다 FX 레이어 제어 방식이 다르므로 모든 MMD 월드에서의 동작을 보장할 수 없습니다.

RealSweat만 WD ON 호환으로 강제하면 외부 WD OFF State와 다시 ON/OFF 혼합 구성이 될 수 있습니다. 대상 아바타 또는 MMD 환경이 전체 WD ON FX를 요구한다는 것을 알고 있는 경우가 아니라면 강제 모드를 영구적인 회피책으로 사용하지 마세요.

땀 켜기 또는 자동 모드가 작동하지 않음

1. 아바타 메뉴에서 땀 켜기가 활성화되어 있는지 확인합니다.
2. 수동으로 확인할 때는 자동 모드를 끄고 땀 %를 조절합니다.
3. 자동 모드를 사용하려면 Humanoid 아바타에서 MA Bone Proxy 기반 Motion Pendulum을 만들 수 있어야 합니다. Motion Pendulum은 만들었지만 Head·Chest Anchor를 찾지 못한 경우에는 자동 모드는 유지되고 입김·몸 김 메뉴만 생성되지 않습니다.
4. Setup이 생성한 Animator, Menu, Parameters 또는 Animator 순서를 수동으로 바꾸지 않았는지 확인합니다.
5. 새 버전을 가져온 뒤 Setup — 자동 설치 / 업데이트를 다시 실행합니다.

Body가 자동 감지되지 않음

Setup의 Body Mesh 항목에 땀을 표시할 SkinnedMeshRenderer를 직접 지정하세요. Face Renderer나 의상 Renderer를 지정하지 마세요.

현재 설치 한 번당 Body Renderer 한 개를 지원합니다.

땀이 다른 재질 슬롯에 표시됨

Body에 Submesh가 여러 개 있을 수 있습니다. 땀 적용 Element에서 피부 재질이 들어 있는 정확한 슬롯을 선택한 뒤 Setup을 다시 실행하세요.

Tangent가 없다는 안내가 표시됨

안전한 사본 생성 (권장)을 선택하고 설치하세요. 업로드 과정에서 다른 도구가 Body Mesh를 다시 교체하면 결과가 달라질 수 있으므로, VRChat에서도 함께 확인해야 합니다.

Unity에서는 정상인데 VRChat에서만 깨짐

업로드 과정에서 최적화 또는 Mesh 변환 도구가 Body Renderer, Mesh, Submesh 또는 재질 슬롯을 교체했을 가능성이 있습니다.

• 최종 Mesh가 땀 대상 Submesh와 재질 대응 관계를 유지하는지 확인합니다.
• 최종 Mesh 데이터에 접근할 수 있고, 땀 Submesh가 제거되지 않았는지 확인합니다.

해당 도구에 제외 기능이 있다면 Real Sweat System에서 사용하는 Body Renderer를 제외 목록에 추가하세요.

Body를 제외할 수 없는 도구와의 호환성은 보장할 수 없습니다. 아바타를 백업한 뒤 해당 도구를 끈 상태와 결과를 비교하세요.

설정을 바꾼 다음 Edit Mode에서 최종 Body를 지정하여 Setup — 자동 설치 / 업데이트를 다시 실행하고, Play Mode와 실제 VRChat 업로드 결과를 모두 확인하세요. Real Sweat System은 이후 빌드 도구가 임의로 수행하는 Mesh 교체를 자동으로 복구할 수 없습니다.

설치 후 기존 PhysBone이 움직이지 않음

Real Sweat System은 자동 모드용 PhysBone과 전용 파라미터를 RealSweat 아래에 추가합니다. 가슴 등 아바타에 이미 설정된 PhysBone을 변경하거나 삭제하는 구조가 아닙니다.

1. Console을 Clear한 뒤 Play Mode에 들어가 처음 발생한 Error 또는 Warning을 확인하세요.
2. Real Sweat System 설치 이후 빌드 과정에서 Bone·PhysBone·Animator·Parameter를 병합하거나 최적화하는 다른 도구가 있는지 확인하세요.
3. 움직이지 않는 PhysBone과 Real Sweat의 Motion Pendulum이 같은 Root Transform, Parameter 또는 처리 대상으로 합쳐지지 않았는지 확인하세요.
4. 해당 도구에 Body Renderer 제외 기능이 있다면 Real Sweat System에서 사용하는 Body Renderer를 제외 목록에 추가하세요. Body를 제외할 수 없다면 해당 도구와의 호환성을 보장할 수 없습니다.

Uninstall 후에도 기존 PhysBone이 움직이지 않는다면 Real Sweat System이 생성한 범위 밖의 변경이 남았을 가능성이 있습니다. 백업 아바타와 비교하고, 빌드 과정에서 동작하는 도구를 하나씩 분리하여 확인하세요.

Rest 데이터 재생성이 실패함

최종 Body Mesh 데이터에 접근할 수 있는지, 그리고 설치 시 선택한 Submesh가 남아 있는지 확인하세요. 업로드 도구가 Mesh를 교체한다면 변환 결과에서도 동일한 대응 관계가 유지되어야 합니다. 수동 재생성이 필요한 경우 먼저 보조 도구의 안내를 확인하세요.

입체 물방울이 의상을 뚫고 보임

RealSweatSystem Clothing Fix를 사용하거나 입체기능을 끄세요. 일반 플레이에서는 No Tess 사용을 권장합니다. 자세한 절차와 주의사항은 보조 도구를 확인하세요.

Effects만 설치했는데 Body를 요구함

정상 동작입니다. Effects Module은 낙하 물방울과 몸 김의 방출 표면을 찾기 위해 Body Mesh가 필요합니다. Effects-only 구성은 Body 재질, Mesh, Rest 데이터 또는 테셀레이션을 수정하지 않습니다.

Invalid localAABB 오류가 Exhale을 가리킴

Console에 다음 오류가 반복되고 상세 정보가 Exhale 오브젝트를 가리킬 수 있습니다.

Invalid localAABB. Object transform is corrupt.

입김을 끄면 이 오류만 사라지지만 얼굴 표정 문제는 남을 수 있습니다. Exhale Transform 상태와 Face Animator 문제는 서로 다른 원인일 수 있으므로 각각 분리해 확인하고, v1.0.1 이상에서 Setup — 자동 설치 / 업데이트를 다시 실행하세요.

첫 빌드만 실패하고 두 번째 빌드는 성공함

가져오기 직후에는 Shader와 Asset Database 캐시가 동시에 준비될 수 있습니다. Unity의 가져오기가 끝난 뒤 Console의 첫 오류를 해결하고 다시 빌드하세요. 두 번째 빌드가 성공했더라도 첫 오류를 무조건 무시해도 된다는 뜻은 아닙니다.

Microsoft Defender가 다운로드를 경고 또는 차단함

일부 환경에서 v1.0.0 배포 파일에 표시된 Microsoft Defender 경고는 Microsoft 재분석을 통해 오탐(False Positive)으로 확인되었으며, 관련 탐지 기준도 Microsoft 측에서 갱신되었습니다.

다만 Defender 보안 인텔리전스와 클라우드 기반 보호의 갱신 시점은 PC마다 달라, 일부 환경에서는 이전 경고가 일시적으로 남을 수 있습니다.

• Windows Security에서 Microsoft Defender 보안 인텔리전스를 최신 상태로 갱신합니다.
• BOOTH 구매 라이브러리에서 현재 버전을 다시 다운로드합니다.
• 경고가 계속되면 정확한 탐지 이름, 파일 이름과 Real Sweat System 버전을 확인합니다.

자주 묻는 사용 팁

Unity 편집 화면에서 땀만 잠시 숨기기

아바타 편집 중 표면의 땀이 시야를 가릴 때는 생성된 땀 재질의 양만 임시로 0으로 만들 수 있습니다.

1. Play Mode를 종료합니다.
2. Body Renderer의 Materials에서 Setup이 마지막에 추가한 RealSweat 재질을 선택합니다. 생성 재질은 보통 Assets/CookiTools/Generated/아바타이름 폴더에도 있습니다.
3. 재질 Inspector의 기본(Basic) > 땀 양(Sweat Amount) (_DropletAmount)에서 현재 값을 기록한 뒤 0으로 설정합니다.
4. 편집이 끝나면 기록해 둔 원래 값으로 되돌립니다. 복구는 기록값을 우선하며, 새 설치의 생성 재질은 보통 1입니다.

이 방법은 Edit Mode의 임시 미리보기 숨김입니다. RealSweatSystem Tuning의 전체 땀양 프리셋이나 아바타 메뉴의 땀 % 0%와는 다른 값입니다. 런타임 파라미터·Auto Mode·파티클 상태를 바꾸지 않으며, Play Mode와 VRChat에서는 생성된 Animation이 값을 다시 제어할 수 있습니다.

재질 슬롯을 삭제하지 마세요

Body의 RealSweat 재질 슬롯을 제거하거나 다른 재질로 교체하면 Setup의 추적과 빌드 검증이 깨질 수 있습니다. 입체기능을 탑재한 아바타에는 Tess와 No Tess 재질이 한 쌍으로 생성됩니다. 관리되는 재질 Inspector에서는 변경값이 짝 재질로 동기화되지만, 입체기능 전환 후 다시 보인다면 생성 폴더의 두 재질 값을 모두 확인하세요. 복구할 때도 두 재질을 기록해 둔 원래 값으로 되돌리세요.

본인 1인칭에서도 입김 보기 (선택·고급)

입김은 머리 쪽 이펙트이므로 본인 1인칭에서 기본적으로 보이지 않는 것이 정상입니다. 다른 사용자는 정상적으로 볼 수 있습니다.

본인 시점에서도 입김을 확인하고 싶다면 다음 방법을 선택적으로 사용할 수 있습니다.

1. Hierarchy에서 RealSweat > RealSweatFxHead > Breath > Exhale 오브젝트를 선택합니다.
2. Add Component > Modular Avatar > MA Visible Head Accessory를 추가합니다. 별도의 값 설정은 필요하지 않습니다.
3. VRChat에서 실제 1인칭 시야를 확인합니다.

RealSweatFxHead는 MA Bone Proxy를 사용하므로 편집기에서 Head 아래가 아님 경고가 보일 수 있습니다. 위의 생성 계층을 그대로 사용했다면 빌드 시 Head 아래로 이동하므로 이 경고는 무시해도 됩니다. RealSweatSystem을 Uninstall한 뒤 다시 설치했거나 Exhale 오브젝트를 다시 생성했다면 이 컴포넌트도 다시 추가해야 합니다.

카메라와 입김 파티클이 너무 가까우면 화면을 가리거나 시야에 겹쳐 보일 수 있습니다. 불편하다면 Exhale의 위치를 임의로 크게 옮기기보다 MA Visible Head Accessory 컴포넌트를 제거해 기본 상태로 복구하세요.

원하지 않는 부위의 절차적 물방울 제한하기

스폰 마스크(땀 생성/소환 마스크)는 Body의 UV0에 맞춘 흑백 텍스처를 사용하여 절차적 물방울의 생성과 Tess 물방울 변위가 생길 부위를 제한합니다.

1. Body 피부 텍스처 또는 UV 레이아웃을 기준으로 흑백 이미지를 만듭니다.
2. 땀이 생성될 부위는 흰색, 제외할 부위는 검은색으로 칠하고 PNG 같은 텍스처로 Unity에 가져옵니다. 셰이더는 빨간색 채널을 읽으므로 RGB를 흑백으로 칠해야 하며, 흰색 RGB에 Alpha만 투명하게 만든 마스크는 사용할 수 없습니다.
3. 생성된 RealSweat 재질의 기본(Basic) > 스폰 마스크 > 스폰 마스크 (흰색 = 스폰)에 텍스처를 넣습니다.
4. 마스크 강도(Mask Strength)를 1로 올립니다. 기본값 0은 마스크 비활성이고, 1은 완전 적용입니다.
5. 경계가 필요하면 마스크 임계값과 마스크 경계 부드러움을 조금씩 조절합니다. 일반적인 흰색 생성 방식에서는 마스크 반전을 끈 상태로 둡니다.

완전한 흰색과 검은색으로 만들면 가장 예측하기 쉽고, 회색은 임계값과 경계 부드러움에 따라 부분적으로 처리됩니다. 입체기능을 탑재했다면 런타임에서 Tess와 No Tess가 전환되므로 두 생성 재질에 같은 마스크가 들어갔는지 확인하세요.

스폰 마스크의 적용 범위

스폰 마스크는 모든 젖은 피부 광택을 잘라 내는 하드 마스크가 아닙니다. 넓게 보이는 wet-skin sheen 일부는 마스크 밖에도 남을 수 있습니다. 또한 별도 Effects인 낙하 물방울, 바닥 물자국, 입김과 몸 김에는 이 마스크가 적용되지 않습니다.

제거·재설치

1. 아바타 Prefab 또는 Unity Project를 백업합니다.
2. Hierarchy에서 아바타 루트를 선택하고 CookiTools > RealSweatSystem Setup／Uninstall을 엽니다.
3. Uninstall 화면에서 생성 에셋까지 지울지 선택합니다. 옵션을 켜지 않으면 생성된 Bake·Material·Animation·Menu 에셋은 보존됩니다.
4. Uninstall — 제거를 눌러 아바타에서 RealSweatSystem을 제거합니다.

깨끗하게 다시 설치하려면 Base와 Effects를 같은 버전으로 가져온 뒤, 아바타를 선택하고 Setup — 자동 설치 / 업데이트를 실행하세요.

수동 개조는 자동 제거되지 않습니다

Face에 직접 추가한 재질, Rest 데이터와 Animation Curve처럼 Setup 밖에서 만든 수동 변경은 Uninstall이 추적하지 않습니다. 별도로 되돌리거나 백업한 아바타로 복원해야 합니다.

문의 시 함께 알려 줄 정보

• Real Sweat System 버전과 설치한 모듈
• Unity와 VRCSDK 버전
• 사용 아바타 및 Face Tracking 패키지 이름
• Setup 화면과 Avatar Descriptor 스크린샷
• Console을 Clear한 뒤 발생한 첫 오류 전문
• Unity Play Mode, Desktop VRChat, VR Face Tracking 중 어디에서 발생하는지
• Modular Avatar 버전
• Animator·Mesh·PhysBone을 변경하는 다른 설치 또는 최적화 도구
• Unity Edit Mode에서는 정상인지
• 정상 동작하는 환경과 문제를 재현하는 정확한 순서
• 얼굴 또는 Animator 문제라면 Play Mode 중 최종 FX Animator의 Layers 전체

아래 양식을 복사하여 사용할 수 있습니다.

Real Sweat System 버전:
구매 구성: Base / Effects / Full Pack
Unity:
VRCSDK:
Modular Avatar:
아바타:
Face Tracking 패키지(사용 시):
다른 설치·최적화 도구:

정상 동작하는 환경:
문제가 발생하는 환경:
재현 순서:
Console을 Clear한 뒤 처음 발생한 오류:

첨부:
- Setup 화면
- Avatar Descriptor
- RealSweat Hierarchy
- 해당하는 경우 Play Mode 중 최종 FX Animator Layers