Unity SpriteAtlas V2
Unity 프로젝트에서 아틀라스를 스크립팅하기 위한 에디터-안전 절차적 지식을 제공합니다. V2는 에디터 저작과 런타임 접근을 엄격하게 분리합니다.
⚠️ 중요한 V2 원칙:
SpriteAtlas는 런타임 전용입니다.SpriteAtlasAsset은 에디터 전용입니다. 컨텍스트를 절대 혼합하지 마세요. 항상 V2를 사용하세요.
🚨 중요: 구현 전 필수 확인 및 사용자 입력
코드를 생성하기 전에 항상 다음 확인을 수행하고 질문을 하세요:
코드를 작성하기 전에 제공된 리소스를 읽으세요 (필수)
이 스킬은 resources/ 아래에 작동하는 C# 코드를 제공합니다. 잘못된 아틀라스 코드는 거의 항상 이를 먼저 읽지 않고 작성된 코드입니다. 선택한 경로에 대한 파일을 열고, 그런 다음 작성하세요.
| 이 경로를 선택하는 경우 | 먼저 읽을 파일 |
|---|---|
| 모든 아틀라스 작업 | resources/authoringvsruntime.cs, references/common-errors.md |
| 프리빌드 생성 (기본값) | resources/spriteatlasprebuildgenerator.cs, resources/enablespritepacking.cs, resources/savespriteatlasasset.cs |
| 옵션 B, Addressables 지연 바인딩 | resources/buildaddressablespostprocess.cs, resources/spriteatlaslatebinding.cs, resources/handlelatebinding.cs |
| 이전 API를 사용할 수 있는 모든 것 | resources/deprecatedmethods.cs, resources/dontscriptspriteatlasineditor.cs, resources/dontpackinruntimebuilds.cs |
resources/는 총 38개의 파일을 포함하며, 사용자 정의 패커, 변형, 플랫폼 설정 및 런타임 접근을 다룹니다. 위 표에 없는 작업의 경우 디렉토리를 탐색하여 접근 방식을 직접 발명하지 마세요. 메모리에서 API를 사용하는 대신 이 파일들을 읽는 것이 가장 중요합니다. 그렇지 않으면 아틀라스가 깔끔하게 임포트되지만 런타임에 아무것도 하지 않습니다.
0. 기존 스크립트 확인 (필수 첫 단계)
코드를 생성하기 전에, 이 스킬에 의해 생성된 기존 SpriteAtlas 스크립트를 프로젝트에서 검색하세요.
식별자를 포함하는 파일을 검색하세요: // [UNITY-SKILL:SPRITEATLAS]
기존 스크립트가 발견되면, 항상 다음 형식으로 사용자에게 질문하세요:
"프로젝트에서 기존 SpriteAtlas 스크립트를 찾았습니다:
프리빌드 생성기:
Assets/Editor/SpriteAtlas/SpriteAtlasPrebuildGenerator.csAddressables 빌더:
Assets/Editor/SpriteAtlas/BuildAddressablesPostprocess.cs런타임 로더:
Assets/Scripts/SpriteAtlas/SpriteAtlasLateBinding.cs어떻게 하시겠습니까?"
그런 다음 옵션을 제시하세요:
-
옵션 A: 기존 스크립트 업데이트 (요구 사항이 변경된 경우 권장)
- 기존 경로에 스크립트 재생성
- 파일 위치 유지
- 최신 버전으로 업데이트
- ⚠️ 사용자 정의 수정 사항을 덮어쓸 수 있음
-
옵션 B: 다른 이름으로 새 스크립트 생성
- 기존 스크립트와 함께 생성
- 여러 아틀라스 구성 허용
- 원본 스크립트는 변경되지 않음
- 새 이름/경로를 지정해야 함
-
옵션 C: 중단 (기존 항목 변경하지 않음)
- 코드 생성 없음
- 프로젝트 변경 없음
- 현재 설정을 유지하려는 경우 사용
사용자 선택 처리:
- A 선택 시: 기존 경로에 재생성, 버전을 2.0.1+로 증가
- B 선택 시: 새 스크립트 이름 요청 (예: "SpriteAtlasPrebuild_Custom.cs"), 그런 다음 생성
- C 선택 시: 즉시 중단, 변경사항이 없음을 사용자에게 알림
1. 전달 메커니즘 (필수)
질문: "스프라이트 아틀라스를 어떻게 전달하시겠습니까?"
옵션 A: 빌트인 데이터 (즉시 로딩)
- 아틀라스가 빌드에 포함되어 즉시 로드됨
includeInBuild = true로 설정- 적합한 경우: 핵심 UI, 주요 게임플레이 스프라이트, 항상 필요한 에셋
- 장점: 간단함, 추가 패키지 불필요, 즉시 접근
- 단점: 초기 빌드 크기 증가, 새 빌드 없이 업데이트 불가능
옵션 B: Addressables를 통한 지연 바인딩 (온디맨드 로딩)
- 아틀라스가 빌드에 포함되지 않고 Addressables를 통해 온디맨드 로딩됨
includeInBuild = false로 설정- 각 아틀라스에 대한 Addressables 항목 생성
- 프리빌드 단계로 addressable 설정 추가
- 🚨 필수: 빌드 단계로 Addressables 콘텐츠 빌드
- 🚨 필수: 지연 바인딩 런타임 로더 스크립트 생성
- 적합한 경우: DLC 콘텐츠, 선택적 기능, 대용량 에셋, 다운로드 가능 콘텐츠
- 장점: 더 작은 초기 빌드, 독립적으로 업데이트 가능, 온디맨드 로딩
- 단점: Addressables 패키지 필요, 비동기 로딩, 네트워크 의존성
| 사용 사례 | 권장 사항 |
|---|---|
| 항상 표시되는 핵심 UI 스프라이트 | 옵션 A: 빌트인 |
| 튜토리얼 또는 온보딩 스프라이트 | 옵션 A: 빌트인 |
| 레벨별 스프라이트 (100개 이상 레벨) | 옵션 B: Addressables |
| DLC 또는 시즌 콘텐츠 | 옵션 B: Addressables |
| 지역화된 UI 스프라이트 (여러 언어) | 옵션 B: Addressables |
| 캐릭터 스킨 또는 코스메틱 | 옵션 B: Addressables |
2. SpritePacker 모드 (필수)
아틀라스를 생성하기 전에 Sprite Packer 모드를 활성화한 다음, 설정을 다시 읽고 적용되었는지 확인하세요.
resources/enablespritepacking.cs의 코드를 사용하세요. 이 코드는 EditorSettings.spritePackerMode를 설정하고 임포터의 패킹 설정을 구성합니다.
이 단계는 생성하는 아틀라스가 실제로 작동하는지 결정합니다. Disabled는 SpritePackerMode의 기본값이므로, 아무도 설정하지 않은 프로젝트는 패킹이 비활성화되어 있습니다. 비활성화된 상태에서 생성된 아틀라스는 여전히 임포트되고, 에셋으로 표시되며, 완료된 것처럼 보이지만 결코 패킹되지 않습니다. Unity는 인스펙터에서 "Sprite Atlas packing is disabled" 라고 표시합니다. 워크플로의 다른 부분은 실패하지 않으므로, 이 방식으로 배송된 아틀라스는 성공으로 읽힙니다. 프로젝트가 이미 구성되었다고 가정하지 마세요. 값을 읽으세요.
따라서 "설정했다"는 것으로 처리하지 마세요. 설정한 후 EditorSettings.spritePackerMode를 다시 읽고, Disabled 가 아닌지 확인하고, 실제로 읽은 값을 보고하세요. 다시 읽을 수 없으면 값이 적용되었다고 가정하지 말고 그렇게 말하세요.
메타 파일을 직접 편집하지 마세요.
🚨 중요: 기본 접근 방식은 프리빌드 생성
빌드 파이프라인 중에 SpriteAtlas를 자동으로 생성하거나 업데이트하려면 항상 IPreprocessBuildWithReport를 사용하세요. 이것이 기본이자 필수 접근 방식이며, 사용자가 명시적으로 수동 저작을 요청하지 않는 한 사용합니다.
❌ 수동 메뉴 항목 스크립트를 생성하지 마세요
명시적으로 요청되지 않는 한 아틀라스 생성을 위해 [MenuItem] 속성이 있는 스크립트를 절대 생성하지 마세요. 프리빌드 접근 방식은 수동 클릭의 필요성을 제거합니다. 수동 저작은 다음 경우에만 사용하세요: 수동 최적화 레이아웃, 특정 스프라이트 배열, 또는 에디터 미리보기 요구 사항. 고급: 수동 저작을 참조하세요.
🚨 중요: 스프라이트 소스 위치 제한
프로젝트의 Assets 폴더에서만 스프라이트를 추가하세요. Unity 내장 에셋, 패키지 또는 외부 위치에서 스프라이트를 절대 추가하지 마세요. Unity 내장 에셋은 SpriteAtlas에 패킹할 수 없으며, 패키지 에셋은 임포트/의존성 문제를 일으킬 수 있습니다.
중요 V2 아키텍처
| 컨텍스트 | 구성 요소 | 목적 | 허용된 사용 |
|---|---|---|---|
| 에디터 | SpriteAtlasAsset | 아틀라스 저작 | 에디터 전용. 절대 런타임에 참조하지 마세요 |
| 런타임 | SpriteAtlas | 아틀라스 사용 | 런타임 전용. 절대 에디터에서 생성하지 마세요 |
| 프리빌드 | IPreprocessBuildWithReport | 자동 생성 | 빌드 시 SpriteAtlasAsset을 SpriteAtlas로 변환 |
| Addressables | IEnumerable<object> | 지연 로딩 | 선택 사항, 빌트인이 불가능할 때 사용 |