8. 문제 해결과 FAQ

가장 흔한 질문들을 신규 사용자가 보통 마주치는 순서대로 정리했습니다. 여기에 없는 문제라면 서비스 레퍼런스를 확인하세요 — 모든 서비스에 "Gotchas" 섹션이 있는 자체 페이지가 있습니다(같은 페이지가 프로젝트의 Documentation/Modules/ 아래에도 배포됩니다) — 또는 메일을 보내주세요(8.9절).

8.1 "패키지를 임포트했는데 씬에 아무것도 나타나지 않아요"

의도된 동작입니다. 프레임워크는 씬 오브젝트가 아니라 코드입니다 — 배치할 프리팹도, 구성할 매니저도 없습니다. Play를 누르는 순간 스스로 시작됩니다. 동작을 보려면:

• Welcome 창을 여세요: Tools > Common Game System > Welcome(Window > Common Game System > Welcome에도 있습니다). 임포트 후 한 번 저절로 열리며, 두 메뉴 항목 모두 언제든 다시 열어 줍니다.
• 그 창 상단의 Open Demo Scene을 클릭하고 Play를 누르세요. Motion Lab 데모가 트윈, 타이머, 일시정지에도 멈추지 않는 클럭 시스템을 아무 설정 없이 실시간으로 보여줍니다.
• 또는 그냥 아무 씬에서나 Play를 누르고 Console에서 bootstrap complete (v2.1.0, 23 services) 줄을 확인하세요.

8.2 "에디터가 새 Input System 때문에 재시작하겠다고 물어봐요"

예라고 답하세요. 이 프롬프트는 프로젝트에서 Input System 패키지를 처음 활성화할 때 Unity가 표시하며, 입력 백엔드는 재시작 중에만 전환될 수 있습니다. 재시작해도 프로젝트와 패키지에는 아무 영향이 없습니다. 재시작 후에도 Welcome 창은 위의 두 메뉴에서 계속 열 수 있고, 모든 것이 중단한 자리에서 이어집니다.

8.3 "데모나 샘플이 마우스와 키보드를 무시해요" (콘솔에서 Enter를 입력해도 아무 일도 없어요)

프로젝트가 아직 예전 입력 백엔드에 있는 것입니다. Input System 패키지를 설치해도 백엔드는 전환되지 않으며, 새 프로젝트에서는 "Input Manager (Old)"에 머물러 있습니다 — 그래서 데모 씬, UI 샘플, 커맨드 콘솔이 아무 입력도 받지 못한 채 조용히 있게 됩니다.

해결은 클릭 한 번입니다: 이 상태일 때마다 Welcome 창에 Enable the new Input System (restarts the editor) 버튼과 함께 노란 경고가 표시됩니다. 클릭하고, 에디터가 재시작되게 두고, 다시 Play를 누르세요. 수동으로 하려면: Edit > Project Settings > Player > Other Settings > Active Input Handling → "Input System Package (New)" 또는 "Both", 그다음 에디터를 재시작하세요.

재시작은 선택이 아니라 필수입니다: 설정을 바꾼 뒤에도 실행 중인 에디터 세션은 여전히 예전 백엔드일 수 있습니다. 입력이 여전히 죽어 있는 것 같다면, 다른 것을 디버깅하기 전에 에디터부터 재시작하세요.

8.4 "데모 씬이 없어요"

Motion Lab 데모는 버튼과 슬라이더를 위해 Unity 내장 uGUI 패키지(com.unity.ugui)가 필요합니다. 이 패키지가 프로젝트에서 제거되었다면 데모의 스크립트가 스스로 컴파일에서 빠지므로 씬이 실행될 수 없습니다. Package Manager에서 uGUI를 다시 설치하면 데모가 돌아옵니다. 어느 쪽이든 프레임워크 자체는 영향을 받지 않습니다 — uGUI 없이도 모든 서비스가 시작되고 동작합니다(7.2장 참고).

8.5 "에디터에서는 저장이 되는데 IL2CPP 빌드에서는 세이브가 사라져요"

세이브 클래스가 빌드에서 스트리핑되고 있는 것입니다. IL2CPP는 사용되지 않는 것처럼 보이는 클래스를 제거하는데, 직렬화 용도로만 존재하는 클래스가 딱 그렇게 보입니다. Assets/ 아래에 세이브 데이터 클래스를 나열한 link.xml 파일을 추가하세요 — 복사해서 쓸 수 있는 파일을 포함한 완전한 레시피가 6.3장에 있습니다. 커스텀 설정 그룹에도 같은 해결법이 적용됩니다.

8.6 "2,600개 이상의 자동화 테스트는 어디에 있나요?"

의도적으로 숨겨져 있습니다. 2,600개 이상의 자동화 테스트 스위트는 Unity가 임포트하지 않는 폴더에 담겨 패키지 안에 함께 배포되므로, 프로젝트의 컴파일 시간이나 어수선함을 전혀 늘리지 않습니다. 직접 실행하려면: Welcome 창을 열고 푸터의 Import framework tests를 클릭하세요. 그러면 Unity의 Test Runner(Window > General > Test Runner)에 테스트가 나타납니다. 이 과정은 전적으로 선택 사항입니다 — 스위트는 릴리스 전에 이미 통과했습니다. 전체 안내는 3.4장을 보세요.

8.7 "URP, HDRP, 빌트인 렌더러에서도 작동하나요?"

네, 셋 다 됩니다. 프레임워크는 아무것도 그리지 않으며 셰이더도, 머티리얼도, 렌더 파이프라인 코드도 포함하지 않습니다. 제공하는 것은 로직입니다: 저장, 타이밍, 이벤트, 입력 라우팅, 오디오 믹싱, 그리고 나머지 서비스들. 게임을 무엇으로 렌더링하든 프레임워크에게는 보이지 않으므로, 파이프라인을 업그레이드해도 프레임워크는 전혀 영향을 받지 않습니다.

8.8 "콘솔에 Unknown action map 'ui.panel'이라고 떠요"

UI 패널 스택이 메뉴 입력 맵을 활성화하려 했지만, 여러분의 입력 애셋에 해당 맵이 정의되어 있지 않은 것입니다. .inputactions 애셋에 정확히 ui.panel과 ui.modal이라는 이름(소문자, 점 포함)의 액션 맵 두 개를 추가하고, 6.2장에 나온 대로 애셋을 연결하세요.

8.9 도움 받기

• 이메일: yoop80075@gmail.com — Unity 버전과, 있다면 bootstrap complete로 시작하는 Console 줄을 함께 보내주세요.
• 이 매뉴얼: 패키지 안 Documentation/CGS-Manual.pdf로 배포되며, 온라인에서는 시작하기에서 시작합니다.
• 서비스 레퍼런스: 서비스별로 쉽게 풀어 쓴 페이지 하나씩 — 온라인 문서 색인 또는 프로젝트의 Documentation/Modules/(예: Modules/SaveLoad.md) — 각각 전체 API, 동작하는 예제, 알려진 주의사항이 담겨 있습니다.
• 체인지로그: 패키지 루트의 CHANGELOG.md에 버전별 변경 사항이 정리되어 있습니다.
• 퀵 링크: Welcome 창의 링크 줄(Manual, Documentation, Changelog, Module Reference)에서 위의 모든 것을 바로 열 수 있습니다.