프로젝트 소개

CDG Unity Modular Framework는 반복해서 쓰는 Unity 런타임 기능과 에디터 도구를 10개 UPM 패키지로 나눈 1인 개발 프로젝트입니다. 게임별 코드를 분리하고, 필요한 기능을 패키지 단위로 설치할 수 있게 구성했습니다. 아래에 소개한 10개 저장소는 모두 v1.0.0 태그가 있습니다.

항목 내용
환경 Unity · C# · Unity Package Manager · Unity Test Framework
담당 패키지 인터페이스·런타임·에디터 도구 구현, 샘플·테스트·설치 문서 작성
대표 사용 흐름 EditorTools로 프로젝트 참조를 검사하고, Data에서 입력을 검증한 뒤 에셋에 적용하며, Pooling과 Map Generation으로 런타임 기능을 구성

패키지 구성

패키지 담당 기능
Core 성공·실패와 오류 정보를 담는 Result 계열 타입
EditorTools Missing Script와 끊어진 직렬화 참조 검사 및 위치 탐색
Pooling 프리팹 객체 대여·반환, 비활성 보관 수 및 생명주기 관리
Data 런타임 데이터 정의와 CSV·JSON 가져오기 및 검증
Save 저장·복원, 슬롯과 백업 처리
UI 화면 전환과 입력 차단, 뷰 등록·검증 도구
Audio 오디오 카탈로그, 재생과 소스 수명 관리
Scene 단일·가산 씬 로딩과 활성 씬 제어
Map Generation 시드 기반 방·복도 생성, 구조 검증, 에디터 적용
Quest 퀘스트 정의·진행 상태와 카탈로그 편집·검증

EditorTools의 검사 창 화면 설명과 설치 링크는 하단의 General Editor Tools 항목에 있습니다.

핵심 코드

EditorTools · 깨진 참조의 위치를 검사 결과에 기록

컴포넌트의 직렬화 속성을 순회하고, 깨진 참조를 찾으면 에셋 경로·컴포넌트·프로퍼티 경로를 결과에 담습니다. 결과 목록에서 어떤 참조를 확인해야 하는지 추적할 수 있습니다.

        private static void ValidateComponent(GameObject gameObject, Component component, string assetPath, ICollection<ValidationIssue> issues)
        {
            SerializedObject serializedObject = new SerializedObject(component);
            serializedObject.Update();

            SerializedProperty iterator = serializedObject.GetIterator();

            while (iterator.Next(true))
            {
                if (!SerializedReferenceUtility.IsBrokenObjectReference(iterator))
                {
                    continue;
                }

                ValidationLocation location = ValidationLocationFactory.Create(
                    gameObject,
                    component,
                    assetPath,
                    iterator.propertyPath);

                issues.Add(new ValidationIssue(
                    ValidationIssueType.BrokenSerializedReference,
                    "삭제된 Unity Object를 참조하는 Serialized Reference가 발견되었습니다.",
                    location));
            }
        }

원본 BrokenSerializedReferenceRule.cs · 39–64행 · 컴포넌트 직렬화 속성 검사 메서드 전체.

Pooling · 대여·반환 상태와 보관 한도

반환 객체의 소유권과 대여 상태를 확인한 뒤 비활성화합니다. 보관 한도 이내면 다시 사용할 수 있게 스택에 넣고, 한도를 넘으면 소유 목록에서 제거하고 파괴합니다.

        public void Release(GameObject instance)
        {
            ThrowIfDisposed();

            if (ReferenceEquals(instance, null))
            {
                throw new ArgumentNullException(nameof(instance));
            }

            if (instance == null)
            {
                RemoveTrackedReference(instance);
                throw new InvalidOperationException("이미 Destroy된 GameObject는 Pool에 반환할 수 없습니다.");
            }

            if (!ownedObjects.Contains(instance))
            {
                throw new InvalidOperationException("이 GameObject는 해당 Pool에서 생성된 객체가 아닙니다.");
            }

            if (!inUseObjects.Remove(instance))
            {
                throw new InvalidOperationException("이 GameObject는 현재 해당 Pool에서 대여 중인 객체가 아닙니다.");
            }

            instance.SetActive(false);

            if (inactiveObjects.Count < maxInactiveCount)
            {
                instance.transform.SetParent(GetAvailableParent(), true);
                inactiveObjects.Push(instance);
                return;
            }

            ownedObjects.Remove(instance);
            UnityEngine.Object.Destroy(instance);
        }

원본 GameObjectPool.cs · 108–144행 · 대여 객체를 반환하는 메서드 전체.

Data · CSV를 검증 가능한 후보로 변환

행의 열 수와 헤더가 맞는지 확인하고 매퍼를 호출합니다. 실패하면 행 번호와 오류를 반환합니다. 모든 행을 변환한 뒤에만 가져오기 후보를 반환합니다.

            List<T> entries = new List<T>(document.Count - 1);

            for (int index = 1; index < document.Count; index++)
            {
                CsvRow row = document[index];

                if (row.Count != header.Count)
                {
                    return CreateFailure(
                        $"CSV {row.StartLine}행의 열 수가 헤더와 일치하지 않습니다. 헤더: {header.Count}, 데이터 행: {row.Count}");
                }

                Result<T> mapResult = rowMapper.Map(header, row);

                if (mapResult == null)
                {
                    return CreateFailure(
                        $"CSV {row.StartLine}행 변환 결과가 null입니다.");
                }

                if (mapResult.IsFailure)
                {
                    return CreateFailure(
                        $"CSV {row.StartLine}행 데이터 변환에 실패했습니다. {mapResult.Error.Message}");
                }

                entries.Add(mapResult.Value);
            }

            return Result<DataImportCandidate<T>>.Success(
                new DataImportCandidate<T>(entries));
        }

원본 CsvDataImporter.cs · 69–100행 · 행 변환과 후보 생성 구간. 앞부분의 CSV 파싱과 헤더 검사는 생략했습니다.

Map Generation · 시드 기반으로 방과 복도 생성