TexturePacker를 유니티로 · 스프라이트와 클립
유니티 스프라이트 에디터는 격자로 자를 수는 있지만, 패킹된 아틀라스는 크기가 제각각인 프레임이 아무 위치에나 있어 영역을 데이터 파일에서 가져와야 합니다. TexturePacker PNG와 JSON을 여기에 넣고 Unity 6용으로 내보내면, 유니티 좌표로 바꾼 영역·피벗과 그것을 적용해 애니메이션마다 AnimationClip을 만드는 편집기 스크립트가 함께 나옵니다.
TexturePacker JSON은 스프라이트마다 PNG 왼쪽 위에서 잰 사각형, 트림, 선택적인 0–1 피벗을 줍니다. Unity는 왼쪽 아래에서 잰 스프라이트 사각형과 사각형마다의 상대 피벗을 원합니다. PNG와 JSON을 Nerulio에 넣고 Unity 6용으로 내보내면, 변환된 사각형과 피벗이 든 .unity.json과, 텍스처를 잘라(Sprite, Multiple, Point, 무압축) 애니메이션마다 AnimationClip을 만드는 편집기 스크립트 NerulioSpriteImporter.cs가 번들에 들어 있습니다. Unity 6000.5.3f1 배치 모드에서 실행해 확인했습니다.
- Unity 6검증됨· Unity 6000.5.3f1
- Godot 4검증됨· Godot 4.7.2
- Phaser 3 / 4검증됨· Phaser 3.90 + 4.2
- PixiJS 8검증됨· PixiJS 8.21
- Aseprite JSON검증됨· Phaser load.aseprite · PixiJS 8.21
- .aseprite검증됨· Aseprite 1.3.18
- Spine / libGDX검증됨· spine-canvas 4.2
- Starling / Sparrow XML검증됨· Phaser 4.2
- LÖVE검증됨· LÖVE 11.5
- Defold빌드 확인· Defold bob.jar 1.13.1
- GameMaker미검증
- CSS sprites검증됨· Chromium
- GIF / APNG디코딩 확인· Pillow
왼쪽 위 기준 사각형, 왼쪽 아래 기준 스프라이트
Unity는 텍스처 하나에 여러 스프라이트를 둘 때 Sprite Mode를 Multiple로 하고 스프라이트 사각형 목록을 둡니다. 사각형은 왼쪽 아래 모서리부터 픽셀로 재고, 스프라이트의 피벗은 자기 사각형 안의 0–1 좌표입니다.
TexturePacker의 y축은 위에서 아래로 내려가므로, y 위치에 높이 h인 프레임은 사각형 y = 페이지 높이 − (y + h)가 됩니다. 트림된 프레임의 사각형에는 저장된 픽셀만 있으므로, 전체 프레임 기준 피벗을 그 사각형 안으로 옮겨야 합니다. 피벗 x = (피벗 px − 트림 x) ÷ w, 피벗 y = (h − (피벗 py − 트림 y)) ÷ h. 0–1을 벗어난 값이 맞는 값이며, 피벗이 잘려 나간 테두리 쪽에 있다는 뜻입니다.
Pixels Per Unit은 스프라이트가 월드 단위로 얼마나 큰지 정합니다. 기본 100이며 스크립트는 JSON에 적힌 값을 적용합니다. Unity의 애니메이션은 정해진 시각마다 SpriteRenderer의 스프라이트를 바꾸는 AnimationClip이고, 스크립트는 프레임마다 자기 시작 시각에 키를 하나씩 씁니다.
- Sprite Mode Multiple
- 이름 붙은 스프라이트 사각형 여러 개를 담은 텍스처 하나.
- 스프라이트 사각형
- 텍스처 위 스프라이트 하나의 사각형·피벗·이름. 왼쪽 아래부터 픽셀 단위.
- Pixels Per Unit
- 월드 단위 하나에 해당하는 텍스처 픽셀 수.
- AnimationClip
- 시간에 따라 SpriteRenderer의 스프라이트를 바꾸는 키프레임.
예시: 트림된 프레임 하나 변환하기
패킹된 38 × 50 페이지 위 run_0: x 0, y 34, w 18, h 15
40 × 29 프레임에서 트림 위치 (10, 10), 피벗은 아래쪽 가운데 = 전체 프레임 기준 (20, 29) px
Unity 사각형 y = 50 − (34 + 15) = 1 사각형 = (0, 1, 18, 15)
피벗 x = (20 − 10) / 18 = 0.5556
피벗 y = (15 − (29 − 10)) / 15 = −0.2667 사각형 아래: 발이 잘려 나간 줄에 있음
클립 "run": 스프라이트 키 0.0, 0.1, 0.2, 0.3, 0.4, 0.5초, 반복 켬, 한 바퀴 0.6초여섯 프레임의 피벗이 모두 원래 40 × 29 프레임의 같은 점을 가리키므로, 사각형마다 트림이 달라도 캐릭터가 흔들리지 않습니다.
TexturePacker 퍼블리시 설정과 Unity 결과
| TexturePacker 설정 | 그때 JSON에 들어가는 것 | 가져오기 스크립트 실행 후 Unity 6 |
|---|---|---|
| 데이터 형식 JSON (Hash) 또는 JSON (Array) | 이름별 frames 또는 filename이 있는 목록 | 스프라이트 이름 = 확장자 없는 프레임 이름 |
| Trim mode Trim | spriteSourceSize, sourceSize | 사각형 = 저장된 픽셀. 그 안에서 피벗을 정규화해 모든 프레임이 기준점 하나를 공유 |
| Allow rotation 켬 | rotated: true | Unity 대상은 회전된 패킹을 거부: 회전 없이 다시 패킹 |
| 피벗 포인트 | 전체 스프라이트 기준 0–1 pivot | 스프라이트마다 사용자 피벗. 트림된 사각형 안으로 변환 |
| 최대 크기, 멀티팩 | meta.size. 페이지마다 JSON + PNG 한 쌍 | 스크립트가 텍스처 Max Size를 페이지가 들어가는 다음 2의 거듭제곱으로 올림 |
| (설정 없음) | 시간 정보 없음 | Studio에서 길이를 정하기 전까지 클립은 프레임당 100ms |
이렇게 작동합니다
- 영역을 유니티의 왼쪽 아래 원점으로 변환(y = 페이지 높이 − y − h), 프레임마다 이름이 같은 SpriteRect 하나.
- 피벗은 원래 프레임 기준 피벗을 트림된 영역 안에서 정규화해, 트림된 프레임도 위치가 맞습니다. 0~1 밖의 값도 의도된 것입니다.
- 도트용 텍스처 설정: Sprite, Multiple, Point 필터, 압축 없음, 밉맵 없음, 페이지가 들어가도록 Max Size 상향.
- Pixels Per Unit은 JSON에 적힌 숫자(기본 100)이고 스크립트가 적용합니다. 게임이 다른 값을 쓰면 가져오기 전에 고치세요.
- 애니메이션마다 AnimationClip 하나: 프레임별 시작 시각에 SpriteRenderer 스프라이트 키, 태그대로 반복.
사용 방법
- 아틀라스 PNG와 JSON을 함께 넣습니다.
- 프레임 이름으로 묶인 애니메이션을 확인하고, 타임라인에서 피벗과 길이를 정합니다.
- 패킹·내보내기에서 Unity 6을 골라 내보냅니다.
- 폴더를 Editor 폴더째 Assets/에 복사하면 유니티가 NerulioSpriteImporter.cs를 컴파일합니다.
- Tools › Nerulio › Import Studio JSON을 실행해 .unity.json을 고르면 텍스처에 스프라이트가, JSON 옆에 .anim 클립이 생깁니다.
받게 되는 파일
| 파일 | 용도 |
|---|---|
run.png | 페이지 텍스처(Nerulio가 새로 패킹, 회전 없음). |
run.unity.json | Pixels Per Unit, 텍스처, 스프라이트(사각형, 피벗, 테두리), 키 시각과 반복이 있는 클립. |
Editor/NerulioSpriteImporter.cs | 편집기 스크립트: Tools › Nerulio › Import Studio JSON이 텍스처 설정과 스프라이트 사각형을 적용하고 .anim 클립을 씀. |
README-UNITY.md | 이 번들의 단계 설명. |
Unity 6로 가져오기
- 폴더를
Assets/에 복사하되Editor/를 안에 그대로 두어 Unity가NerulioSpriteImporter.cs를 편집기 스크립트로 컴파일하게 합니다. - 2D Sprite 패키지(com.unity.2d.sprite)가 설치돼 있는지 확인합니다. 2D 템플릿에는 들어 있습니다.
- Tools › Nerulio › Import Studio JSON을 실행하고
run.unity.json을 고릅니다. 텍스처에 스프라이트가 생기고 JSON 옆에.anim클립이 생깁니다. - 캐릭터의 SpriteRenderer 오브젝트에 있는 Animator Controller에 클립을 추가합니다. 각 클립이 스프라이트를 바꿉니다.
- 게임이 다른 배율을 쓰면 가져오기 전에
.unity.json의pixelsPerUnit을 바꿉니다.
결과 확인
- Sprite Editor에서 텍스처를 엽니다. run_0 … run_5라는 사각형 6개가 있고, 피벗은 모두 발 위치에 있습니다(트림된 프레임은 사각형 아래).
run클립을 재생합니다. 한 바퀴 0.6초이고 프레임 사이에 캐릭터가 위아래로 움직이지 않아야 합니다.- 텍스처 인스펙터: Sprite Mode Multiple, Filter Mode Point, 압축 없음, 밉맵 없음.
TexturePacker JSON에서 유니티 스프라이트 설정으로
| JSON 항목 | 유니티 임포터가 설정하는 값 | 이유 |
|---|---|---|
| frame {x, y, w, h} | y = 페이지 높이 − (y + h)인 SpriteRect | 유니티 텍스처는 왼쪽 아래에서 시작 |
| spriteSourceSize, sourceSize | 트림된 영역 안에서 정규화한 피벗 | 모든 프레임이 같은 기준점 유지 |
| pivot 또는 P로 정한 피벗 | 그 피벗의 Custom 정렬 | 캐릭터가 제자리에 섬 |
| 프레임 이름 | 스프라이트 이름, 접두사로 애니메이션 | 클립이 이름으로 스프라이트를 찾음 |
| meta.size | 들어가는 가장 작은 2의 거듭제곱으로 Max Size 상향 | 큰 페이지가 줄어드는 것을 막음 |
| JSON에 없음 | Point, 압축 없음, 밉맵 없음, PPU 100 | 선명한 도트, PPU는 JSON에서 수정 |
문제 해결
| 증상 | 유력한 원인 | 확인 방법 | 해결 |
|---|---|---|---|
| 스프라이트가 엉뚱한 곳에서 잘리고 위아래로 밀림 | JSON의 사각형을 y를 뒤집지 않고 손으로 옮겨 적음 | 사각형 y를 페이지 높이 − (y + h)와 비교 | y를 변환하는 가져오기 스크립트 사용 |
| 프레임 사이에 캐릭터가 튐 | 트림된 사각형의 피벗이 Center로 남아 있음 | Sprite Editor에서 스프라이트마다 피벗 확인 | 스크립트로 가져오기. 피벗이 트림된 사각형마다 정규화됨 |
| Tools › Nerulio 메뉴가 없음 | 스크립트가 Editor 폴더에 없거나 다른 곳의 컴파일 오류가 막고 있음 | Console의 컴파일 오류 | Editor/NerulioSpriteImporter.cs를 Editor 폴더에 두고 com.unity.2d.sprite 설치 |
| 스프라이트가 흐리거나 압축 얼룩이 보임 | 가져온 뒤 텍스처 설정이 바뀜(Bilinear, 압축) | 텍스처 인스펙터 | Point 필터, 압축 없음. Unity에서 도트 그림이 흐릴 때 참고 |
| 히트박스가 없음 | Unity 스프라이트에 그 필드가 없어 이 가져오기로는 전달되지 않음 | 내보내기 안내에 표시됨 | 박스는 Generic JSON으로 내보내고 콜라이더는 직접 만듦 |
다른 방법
| 방법 | 이럴 때 더 낫습니다 |
|---|---|
| TexturePacker 자체 Unity 가져오기 | TexturePacker에서 Unity용으로 자주 퍼블리시할 때. Unity Asset Store로 배포되며 여기서는 측정하지 않았습니다. |
| Sprite Editor의 격자 자르기 | 시트가 균일한 격자일 때. 패킹된 아틀라스는 사각형을 데이터 파일에서 가져와야 합니다. Unity에서 스프라이트 시트 참고. |
| 원본에서 시작 | .aseprite 파일이 있다면 Aseprite를 Unity로가 TexturePacker JSON에는 없던 태그와 길이를 지켜 줍니다. |
엔진별 내보내기와 검증 방법
"검증됨"은 실제 CC0 에셋으로 내보낸 파일을 해당 엔진·도구가 직접 불러와 원본과 비교했다는 뜻입니다. 불러오지 않은 형식은 그렇게 표시합니다.
| 대상 | 파일 | 검증 |
|---|---|---|
| Godot 4 | .tres SpriteFrames · .tscn AnimatedSprite2D · .png.import | 검증됨 Godot 4.7.2Godot가 불러와 모든 애니메이션 프레임을 그려 원본과 비교했습니다. 씬은 Nearest 필터를 쓰고 회전은 쓰지 않습니다. |
| Unity 6 | .unity.json · Editor/NerulioSpriteImporter.cs · AnimationClip | 검증됨 Unity 6000.5.3f1배치 모드에서 스프라이트 영역·피벗·픽셀·클립 키·길이를 확인했습니다. |
| Phaser 3 / 4 | atlas JSON (multiatlas) · .anims.json | 검증됨 Phaser 3.90 + 4.2두 버전 모두에서 프레임과 애니메이션을 그렸습니다. |
| PixiJS 8 | spritesheet JSON · animations · anchor · meta.scale | 검증됨 PixiJS 8.21회전·여러 페이지 아틀라스도 포함해 확인했습니다. |
| Aseprite JSON | hash / array · frameTags · slices | 검증됨 Phaser load.aseprite · PixiJS 8.21태그의 방향과 반복 횟수가 유지됩니다. |
| .aseprite | layers · tags · durations · slices | 검증됨 Aseprite 1.3.18Aseprite 명령줄로 열어 렌더링했습니다. |
| Spine / libGDX | .atlas | 검증됨 spine-canvas 4.2Spine 런타임이 회전·트림 영역을 모두 그렸습니다. libGDX 자체는 실행하지 않았습니다. |
| Starling / Sparrow XML | XML per page | 검증됨 Phaser 4.2Phaser 3.90은 트림된 XML 프레임을 잘못 그립니다(Phaser 버그). "Sparrow XML (Phaser 3)" 프리셋은 트림을 끄며 3.90·4.2 모두 통과합니다. |
| LÖVE | Lua quads · nerulio_atlas.lua · main.lua | 검증됨 LÖVE 11.5포함된 헬퍼로 모든 프레임을 그리고 모든 애니메이션을 재생했습니다. |
| Defold | .atlas · .tilesource | 빌드 확인 Defold bob.jar 1.13.1Defold 명령줄 빌더로 빌드하고 빌드된 텍스처의 UV를 다시 읽어 확인했습니다. |
| GameMaker | spr_<name>_stripN.png · gamemaker.json | 미검증GameMaker에서 불러오지 않았습니다(헤드리스 실행 불가). 스트립은 GameMaker 스트립 가져오기 방식대로 자릅니다. |
| CSS sprites | .css · preview .html | 검증됨 Chromium포함된 스타일시트로 모든 클래스를 그렸습니다. |
| GIF / APNG | one file per animation | 디코딩 확인 Pillow내보낸 뒤 모든 프레임과 지연 시간을 다시 디코딩했습니다. APNG는 원본과 동일합니다. |
검증 근거
GIF 디코더: 실제 GIF 29개 408/408프레임이 Pillow와 동일, APNG 16개 132/132프레임. .aseprite: 코퍼스 231개 파일을 가져와 다시 쓰고 Aseprite 1.3.18로 열었을 때 태그·길이·픽셀 231/231 일치. 내보내기: 실제 CC0 에셋으로 실제 엔진에서 49회 실행해 47회 통과. 실패 2회는 Phaser 3.90의 트림 XML 버그이며 Phaser 3 프리셋으로 피합니다.
한계
- JSON의 회전된 스프라이트는 돌려진 채로 가져오며, Unity 대상은 회전된 패킹을 거부합니다.
- TexturePacker JSON에는 프레임 시간이 없으니 내보내기 전에 길이를 정하세요.
- 충돌 폴리곤과 히트박스는 Unity 물리 모양으로 쓰지 않습니다.
- 격자·섬 인식은 신뢰도가 표시된 미리보기일 뿐이며 적용을 누르기 전에는 아무것도 자르지 않습니다. 모든 선택에는 한 번에 바꿀 수 있는 대안이 있습니다.
- 레이어가 정확히 합성되지 않는 .aseprite 파일(그룹 불투명도 등)은 합쳐서 가져오고, 가져오기 패널에 이유를 표시합니다.
- 가져온 아틀라스에서 회전된 프레임은 회전된 채로 남으며 그 내보내기는 미검증입니다.
- 이미지는 한 변 32,768px(2억 6,800만 픽셀)까지이며 브라우저 메모리에 따라 달라집니다.
버전과 출처
Unity 6000.5.3f1 배치 모드에서 내보낸 번들에 NerulioSpriteImporter.cs를 실행하고 사각형, 피벗(공통 기준점 하나), 픽셀, 클립 키와 길이를 다시 읽었습니다. TexturePacker 가져오기는 src/studio/sprite/atlas-data.js이며, TexturePacker 자체 Unity 가져오기는 시험하지 않았습니다. Unity 용어는 Unity 6 매뉴얼을 따릅니다.
참고한 공식 문서
자주 묻는 질문
유니티에 TexturePacker 임포터를 깔아야 하나요?
아니요. 번들에 편집기 스크립트가 들어 있고, 2D 템플릿에 포함된 2D Sprite 패키지(com.unity.2d.sprite)만 있으면 됩니다. Unity 6000.5.3f1 배치 모드에서 실행해 영역·피벗·픽셀·클립 키·길이를 다시 읽어 확인했습니다.
히트박스도 유니티로 가나요?
이 임포터로는 가지 않습니다. 유니티 스프라이트에는 그런 항목이 없어서, 박스와 충돌 폴리곤은 범용 JSON 내보내기에 들어가며 Unity 내보내기가 그 점을 알려 줍니다.
JSON에 회전된 프레임이 있어요.
돌아간 채로 가져오며 그 프레임의 내보내기는 미검증입니다. Unity 대상 자체는 회전 패킹을 거부합니다. TexturePacker에서 회전을 끄고 다시 패킹한 두 파일을 넣으세요.
무료인가요? 계정이 필요한가요?
이 페이지의 기능은 모두 무료이며 계정 없이 쓸 수 있습니다. 워터마크나 막혀 있는 내보내기가 없습니다.
스프라이트가 업로드되나요?
아니요. Studio는 이 브라우저 탭 안에서 디코딩·패킹·내보내기를 합니다. 프로젝트는 브라우저(IndexedDB)에 자동 저장되며 .nerulio 파일로 저장할 수 있습니다.
Aseprite나 엔진 플러그인을 설치해야 하나요?
아니요. .aseprite 파일은 브라우저에서 읽고 씁니다. 엔진별 번들에는 그 엔진에 필요한 것이 들어 있습니다(Godot는 가져오기 설정과 씬, Unity와 Godot 타일셋은 작은 편집기 스크립트).