FAQ

가장 흔한 질문들을 신규 사용자가 보통 마주치는 순서대로 정리했습니다. 여기에 없는 문제라면 서비스 레퍼런스를 확인하거나 — 모든 서비스 페이지에 "Gotchas" 섹션이 있습니다 — 메일을 보내주세요.

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

의도된 동작입니다. CGS는 헤드리스 코드 프레임워크입니다 — 배치할 프리팹도, 구성할 매니저도 없고, 씬에 추가하려는 것도 없습니다. 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) 줄을 확인하세요 — 씬이 실행되기 전에 23개 서비스가 모두 시작되었다는 증거입니다.

전체 안내: 시작하기.

"데모나 샘플이 마우스와 키보드를 무시해요" (커맨드 콘솔에서 Enter를 눌러도 반응이 없어요)

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

해결은 클릭 한 번입니다: 이 상태일 때마다 Welcome 창에 노란 경고와 함께 Enable the new Input System (restarts the editor) 버튼이 표시됩니다. 클릭하고 에디터가 재시작되도록 두세요.

재시작은 형식적인 절차가 아니라 필수입니다. 입력 백엔드는 에디터 재시작 중에만 전환됩니다 — 설정을 바꾼 뒤에도 실행 중인 세션은 여전히 예전 백엔드일 수 있습니다. 본인(또는 팀 동료)이 설정을 직접 바꾸고 재시작을 건너뛰었다면, 에디터를 재시작할 때까지 입력은 계속 먹통입니다.

수동으로 바꾸려면: Edit > Project Settings > Player > Other Settings > Active Input Handling → "Input System Package (New)" 또는 "Both"를 선택한 뒤 에디터를 재시작하고 다시 Play를 누르세요.

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

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

"데모 씬이 없어요"

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

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

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

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

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

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

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

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

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

도움 받기

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