1. 무엇이 들어 있나

Common Game System이 무엇인지, 프로젝트에 제공하는 23개 서비스, 그리고 의도적으로 다루지 않는 것들.

1.1 Common Game System이란?

Common Game System(CGS)은 Unity 6.3 LTS를 위한 C# 기반 프레임워크입니다. 저장, 오디오, 입력, 씬 로딩, 타이머, 트위닝 등 모든 게임에 필요한 배관 작업을 23개의 완성된 서비스로 프로젝트에 제공합니다.

Play를 누르면 23개 서비스가 모두 자동으로 시작됩니다. 하나의 부트스트랩 컴포넌트가 여러분의 첫 스크립트가 실행되기 전에 서비스들을 등록합니다. 씬에 끌어다 놓을 것도, 구성할 것도 없습니다. 코드에서는 그저 서비스를 요청해서 쓰면 됩니다:

[SerializeField] private AudioClip clickClip;

private void OnButtonClicked()
{
    var audio = ServiceLocator.Resolve<IAudioService>();
    audio.PlaySfx(clickClip);
}

CGS는 코드로만 이루어져 있습니다. 화면에 아무것도 그리지 않으며 아트 스타일도, 장르도, 프로젝트 구조도 강요하지 않습니다. 게임은 여러분이 원하는 방식대로 계속 만드시면 됩니다 — 그 밑의 기계 장치는 CGS가 맡습니다.

1.2 CGS가 해결하는 문제

대부분의 Unity 프로젝트는 같은 방식으로 시작합니다: "Managers" 폴더. 지난 프로젝트에서 복사해 온 SaveManager. 기억을 더듬어 다시 쓴 AudioManager. 타임 스케일용 싱글턴, 페이드용 헬퍼, 반쯤 만들다 만 오브젝트 풀. 하나하나가 프로젝트마다 다시 작성되고, 테스트는 거의 되지 않으며, 매번 다르게 엮입니다.

CGS는 그 폴더의 완성본입니다. 모든 서비스는:

일관적입니다. 모든 서비스에 하나의 로케이터를 통해 같은 방식으로 접근합니다. 패턴을 한 번 익히면 23개 전부를 쓸 줄 알게 됩니다.
테스트되어 있습니다. 프레임워크는 2,600개 이상의 자동화 테스트와 함께 배포됩니다. 직접 임포트해서 실행해 볼 수도 있습니다(3장 참고).
문서화되어 있습니다. 모든 서비스는 패키지의 Documentation/Modules/ 아래에 자체 레퍼런스 페이지가 있으며, 같은 레퍼런스가 이 사이트의 서비스 레퍼런스로 온라인에도 있습니다.
교체할 수 있습니다. 모든 서비스는 인터페이스 뒤에 있습니다. 한 줄로 자체 구현으로 바꾸거나 서비스를 완전히 꺼 버릴 수 있습니다(아래 1.4절 참고).

1.3 한눈에 보는 23개 서비스

각 서비스는 인터페이스입니다. 아래 표는 게임에서 하는 역할별로 서비스를 묶은 것입니다. 각 서비스 이름은 전체 레퍼런스 페이지로 연결됩니다.

저장과 설정

서비스	게임에 해주는 일
`ISaveService`	이름 있는 슬롯을 사용하는 JSON 세이브 파일. 쓰기가 원자적이어서 크래시가 나도 기존 세이브가 손상되지 않습니다.
`IConfiguration`	세션 간에 유지되는 타입 지정 설정 그룹(오디오 볼륨, 그래픽 옵션 등).
`IAchievementService`	로컬 플레이어 통계와 업적. 통계가 임계값을 넘으면 업적이 자동으로 해금됩니다.

입력과 UI

서비스	게임에 해주는 일
`IInputService`	이름 있는 액션 맵("Gameplay", "Menu")을 통해 게임패드와 키보드 입력을 읽고, 대화형 키 리바인딩을 지원합니다.
`IInputKeyMapSource`	input actions 애셋을 공급하고 플레이어의 리바인딩 변경 사항을 저장합니다.
`IPanelStack`	UI 패널(메뉴, 다이얼로그)을 푸시/팝하고 게임패드·키보드 포커스를 올바른 패널에 유지합니다.
`ILocalizationService`	키로 표시 텍스트를 조회하고 런타임에 언어를 전환합니다 — 재시작이 필요 없습니다.

오디오, 씬, 애셋

서비스	게임에 해주는 일
`IAudioService`	AudioMixer를 통해 음악, 효과음, 음성을 재생하고 채널별 볼륨을 제어합니다.
`ISceneService`	로딩 화면, 취소, 애디티브 로드/언로드를 갖춘 비동기 씬 로딩.
`IAddressableSceneService`	빌드 목록 대신 Addressables 콘텐츠에 있는 애디티브 씬을 로드합니다.
`IAssetProvider`	Addressables 애셋을 로드하고 참조를 세어, 아무도 사용하지 않을 때에만 애셋을 해제합니다.

타이밍과 모션

서비스	게임에 해주는 일
`ITimeService`	게임플레이, UI, 백그라운드 작업을 위한 분리된 클럭. 메뉴가 계속 움직이는 동안 게임플레이를 일시정지하거나 느리게 만들 수 있습니다.
`IScheduler`	타이머: 지연 후 실행, 일정 간격마다 실행, 다음 프레임에 실행. 메인 스레드에서 작업을 실행하는 데도 쓰입니다.
`ITweenService`	31가지 이징 커브로 어떤 값이든 시간에 따라 애니메이션합니다. 게임이 일시정지되면 트윈도 일시정지됩니다.
`ITweenSequenceService`	여러 단계로 이루어진 인트로 애니메이션처럼, 트윈을 순차 또는 병렬 타임라인으로 연결합니다.

로직과 유틸리티

서비스	게임에 해주는 일
`ILogger`	흩어진 `Debug.Log` 호출을 대체하는, 카테고리별로 필터링 가능한 로깅.
`IEventBus`	타입 안전한 발행/구독. 시스템들이 직접 참조 대신 이벤트로 대화합니다.
`IDeferredBus`	이벤트를 지금 큐에 넣고 여러분이 지정한 시점에 나중에 전달합니다 — 로딩이나 컷씬 중에 유용합니다.
`IObjectPoolService`	프리팹 인스턴스(총알, 파티클)를 매번 생성·파괴하는 대신 재사용합니다.
`IRandomService`	이름 있는 스트림을 가진 시드 기반 난수. 결과가 재현 가능하고 저장/로드 후에도 유지됩니다.
`IStateMachineService`	진입, 종료, 전이 규칙을 갖춘 AI·게임 흐름용 단순 상태 기계를 만듭니다.
`IPushdownStackService`	중첩된 게임 상태를 관리합니다 — 예를 들어 게임플레이 위에 겹쳐진 일시정지 화면을 깔끔하게 걷어내는 것.
`ICommandRegistry`	개발자 콘솔과 치트를 위한 런타임 커맨드 레지스트리. 콘솔 UI는 여러분이 제공하며, 동작하는 예제가 포함되어 있습니다.

1.4 모든 서비스에는 끄기 스위치가 있다

각 서비스는 "널(null)" 쌍둥이와 함께 배포됩니다: 모든 호출을 받아들이고 아무것도 하지 않는 버전입니다. 프로젝트에 이미 오디오 솔루션이 있다면 CGS 오디오는 한 줄로 끌 수 있습니다:

ServiceLocator.Replace<IAudioService>(new NullAudio());

프레임워크의 나머지는 계속 동작합니다. 오디오 서비스와 대화하는 코드는 여전히 컴파일되고 실행됩니다 — 그저 침묵을 만들 뿐입니다. 같은 한 줄 스위치가 23개 서비스 전부에 있으며, 같은 메커니즘으로 널 버전 대신 자체 구현을 넣을 수도 있습니다(7장에 전체 목록이 있습니다).

1.5 CGS가 아닌 것

경계를 미리 알아 두면 시간이 절약됩니다:

게임플레이 콘텐츠 없음. 캐릭터, 인벤토리, 데미지 공식, 레벨은 없습니다. CGS는 메커니즘을 제공하고, 콘텐츠는 여러분의 게임이 제공합니다. (작은 RPG 모양의 샘플이 조각들을 조합하는 방법을 보여줍니다.)
렌더링 없음. CGS에는 셰이더, 머티리얼, 파이프라인 코드가 없습니다. URP, HDRP, 빌트인 파이프라인에서 동일하게 작동합니다.
싱글플레이어, PC 중심. CGS는 Windows, macOS, Linux의 싱글플레이어 게임을 대상으로 합니다. 네트워킹 레이어는 없으며 모바일·콘솔 플랫폼 작업도 없습니다.

1.6 요구 사항

Unity 6.3 LTS. CGS는 Unity 6.3 LTS에서 빌드되고 테스트되었습니다.
흔히 쓰이는 Unity 패키지 3종, 모두 선택 사항. Input System 패키지(입력 서비스가 사용), uGUI(UI 패널 스택과 데모 씬이 사용), Addressables(애셋 서비스와 어드레서블 씬 서비스가 사용). Input System과 uGUI는 새 Unity 프로젝트에 기본 포함되며, 이 패키지를 임포트하면 의존성 목록을 통해 — Addressables를 포함해 — 빠진 것이 자동으로 설치되므로 대부분의 사용자는 직접 설치할 것이 없습니다.

CGS는 일곱 개의 어셈블리로 분리되어 있습니다. 코어 어셈블리는 18개 서비스를 담고 있으며 Unity 자체 외에는 아무것에도 의존하지 않습니다. 나머지 어셈블리는 각각 선택적 패키지 하나를 감쌉니다. 패키지를 제거하면 — 예를 들어 Addressables — 해당 CGS 어셈블리가 조용히 컴파일에서 스스로 빠집니다. 프레임워크의 나머지는 그대로 컴파일되고 실행되며, uGUI가 없으면 UI 패널 스택은 안전한 무동작 서비스로 강등됩니다. 선택적 패키지가 없다는 이유로 오류 벽을 마주할 일은 결코 없습니다. 전체 어셈블리 지도는 7.1장에 있습니다.

다음: 2. 설치와 첫 5분