Aseprite 스프라이트 시트 변환 · 태그 그대로 패킹
.aseprite 파일을 넣고 패킹·내보내기를 열면 모든 프레임이 워커에서 바로 아틀라스 페이지로 패킹됩니다. 같은 프레임은 한 번만 저장하고, 빈 테두리는 오프셋을 기억한 채 잘라 내며, 파일의 태그와 프레임별 시간은 엔진이 읽는 데이터 파일에 그대로 들어갑니다.
.aseprite 파일을 넣고 패킹·내보내기를 열면 프레임이 PNG 한 장에 패킹되고(트림, 같은 프레임은 한 번만 저장) 엔진이 읽는 데이터 파일과 함께 나옵니다. Aseprite JSON 대상은 Aseprite 자체 File > Export Sprite Sheet와 같은 구조입니다. duration이 있는 frames, meta.frameTags, meta.slices를 해시나 배열로, 한 페이지에, Phaser의 createFromAseprite가 기대하는 0, 1, … 프레임 키로 씁니다. Godot, Unity, PixiJS 등 다른 대상은 태그와 타이밍을 각자 형식으로 담습니다.
- Phaser 3 / 4검증됨· Phaser 3.90 + 4.2
- Aseprite JSON검증됨· Phaser load.aseprite · PixiJS 8.21
- Godot 4검증됨· Godot 4.7.2
- Unity 6검증됨· Unity 6000.5.3f1
- PixiJS 8검증됨· 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
Aseprite JSON이 딸린 스프라이트 시트의 구성
스프라이트 시트는 모든 프레임을 담은 이미지 한 장과 각 프레임의 위치를 알려 주는 데이터 파일입니다. Aseprite JSON의 프레임 항목에는 frame(시트 위 사각형), rotated, trimmed, spriteSourceSize(원래 캔버스 안에서 잘린 사각형의 위치), sourceSize(캔버스), 밀리초 단위 duration이 있습니다. meta에는 이미지 이름·크기·배율이 있고, 요청하면 frameTags(name, from, to, direction)와 slices가 들어갑니다.
해시와 배열은 frames만 다릅니다. 해시는 프레임 이름을 키로 하는 객체, 배열은 항목마다 filename이 있는 목록입니다. 프레임 이름은 Aseprite의 파일 이름 형식에서 오며, Phaser의 createFromAseprite는 항목 파일 이름이 {frame}뿐이기를 기대하므로 키가 0, 1, 2 …가 됩니다.
태그는 프레임 목록 위의 from–to 구간이라 태그마다 한 줄로 이어져 있어야 합니다. Nerulio는 패킹하면서도 이를 지킵니다. 두 태그가 함께 쓰는 프레임이나 순서가 뒤섞인 태그의 프레임은 같은 영역을 가리키는 항목을 하나 더 만들고, 내보내기 안내에 반복한 항목 수를 적습니다.
- spriteSourceSize
- 원래 프레임 안에서 트림된 픽셀의 위치와 크기.
- sourceSize
- 트림 전 원래 프레임(캔버스) 크기.
- frameTags
- Aseprite의 애니메이션: 이름, 첫·마지막 프레임, 방향, 설정돼 있으면 반복 횟수.
- 별칭(Alias)
- 보이는 픽셀이 다른 프레임과 같은 프레임은 한 번만 저장하고 두 항목이 같은 곳을 가리킵니다.
예시: 트림된 프레임 하나와 태그 두 개의 JSON
"0": { "frame": { "x": 0, "y": 0, "w": 18, "h": 29 }, "rotated": false, "trimmed": true,
"spriteSourceSize": { "x": 7, "y": 3, "w": 18, "h": 29 },
"sourceSize": { "w": 32, "h": 32 }, "duration": 125 }
"frameTags": [
{ "name": "idle", "from": 0, "to": 3, "direction": "forward", "color": "#6acd5bff" },
{ "name": "attack", "from": 10, "to": 15, "direction": "forward", "color": "#fe5b59ff", "repeat": "1" } ]
"slices": [ { "name": "pivot", "color": "#0000ffff", "keys": [
{ "frame": 0, "bounds": { "x": 0, "y": 0, "w": 32, "h": 32 }, "pivot": { "x": 16, "y": 32 } } ] } ]
트림: 32 × 32 = 1024 px² → 18 × 29 = 522 px²만 저장 (−49 %), (7, 3)에 다시 그림무한 반복 태그에는 repeat가 없고, 한 번 재생하는 태그는 "repeat": "1"입니다. 피벗 (16, 32)는 32 × 32 캔버스의 아래 가운데로, 파일에 피벗 슬라이스가 없을 때 씁니다. 키는 원래 파일이 아니라 이 목록에서의 위치입니다.
무엇이 어디로 옮겨지나
| .aseprite에서 | Aseprite JSON에서 | 참고 |
|---|---|---|
| 프레임 픽셀(보이는 레이어 전부) | PNG 위 트림된 영역: frame + spriteSourceSize | 레이어는 합성, 같은 프레임은 한 번만 저장 |
| 프레임 길이 | ms 단위 duration | 정수 밀리초 |
| 태그 | from, to, direction이 있는 meta.frameTags 항목 | 함께 쓰거나 순서가 뒤섞인 프레임은 항목 추가 |
| 반복 | 유한하면 문자열 repeat | 무한 반복 태그에는 없음 |
| 피벗 슬라이스(없으면 아래 가운데) | meta.slices의 pivot 슬라이스, 바뀌는 곳에 키 | 경계 = 프레임 캔버스 |
| 히트·허트 박스 | 종류와 순번마다 슬라이스 하나, 박스가 끝나는 곳에 빈 키 | 사각형만 |
| 레이어 | meta.layers에 항목 하나(Layer 1) | 시트에는 합성된 프레임 |
| 페이지 | PNG 정확히 한 장 | 이 대상은 한 페이지로 다시 패킹 |
이렇게 작동합니다
- 패커: 배치 규칙 5가지의 MaxRects, Skyline, Guillotine. "모두 시도"는 가장 작은 페이지를 고르고, 같은 입력이면 항상 같은 바이트가 나옵니다.
- 트림은 프레임 크기와 오프셋을 유지하고, crop-keep은 프레임을 줄이면서 피벗을 옮겨 그림 위치를 지킵니다. 보이는 픽셀이 같은 프레임은 바이트 비교 후 한 번만 저장합니다.
- 페이지: 최대 64장, 한계 8~16384px, 2의 거듭제곱·정사각·고정 크기, 테두리·도형 여백, 가장자리 확장.
- @0.5x~@4x 배율 변형(최근접 이웃만). 정수 배율 확대는 픽셀을 그대로 복제합니다.
- Aseprite의 파일 › 스프라이트 시트 내보내기와 같은 형태의 Aseprite JSON(해시·배열): 방향·반복이 든 frameTags, 프레임별 duration, 피벗과 박스 슬라이스.
사용 방법
- .aseprite 파일을 넣으면 스프라이트 작업 공간이 레이어·태그·길이를 읽습니다.
- 패킹·내보내기를 엽니다. 설정을 바꿀 때마다 다시 패킹해 보여 주며, 오래 걸리면 취소할 수 있습니다.
- 엔진 프리셋이나 Aseprite JSON을 고릅니다. 한 페이지만 되거나 회전이 안 되는 대상은 다시 패킹하고 바뀐 점을 버튼 옆에 적습니다.
- 패킹된 프레임 목록에서 트림되거나 합쳐진 프레임을 확인합니다.
- 내보내기를 누르고 PNG 페이지와 데이터 파일을 프로젝트에 풉니다.
받게 되는 파일
| 파일 | 용도 |
|---|---|
hero.png | 패킹된 시트. 이 대상은 한 페이지입니다. |
hero.json | frameTags와 slices가 있는 Aseprite JSON(해시 또는 배열). |
README-ASEPRITE-JSON.md | 이 파일들을 Phaser에서 불러오는 코드와, PixiJS가 여기서 무엇을 읽는지. |
Phaser 3·4에서 불러오기
hero.png와hero.json을 게임의 에셋 폴더에 복사합니다.preload()에서:this.load.aseprite('hero', 'hero.png', 'hero.json').create()에서:this.anims.createFromAseprite('hero')가 태그마다 태그 이름의 애니메이션을 만듭니다.- 추가하고 재생:
this.add.sprite(100, 100, 'hero').play('walk'). 픽셀아트라면 게임을pixelArt: true로 만드세요.
Godot, Unity, PixiJS에는 Aseprite JSON 대신 각자의 대상을 고르세요. Aseprite를 Godot로, Aseprite를 Unity로, Aseprite JSON을 PixiJS로 참고.
결과 확인
frames의 항목 수는 프레임 수에 내보내기 안내가 말한 반복 항목 수를 더한 값입니다.- 게임에서 태그를 재생해 한 사이클 시간을 Aseprite와 비교하세요(walk: 6 × 100 ms = 0.6초).
hero.png를 열어 보세요. 트림된 프레임이 빽빽하게 패킹되어 같은 프레임을 격자로 내보낼 때보다 시트가 작습니다.
.aseprite 하나에서 나오는 시트
| 출력 | 데이터 파일 | 태그와 시간 | 확인 방법 |
|---|---|---|---|
| Aseprite JSON(해시·배열) | meta.frameTags와 meta.slices가 든 <이름>.json | 방향·반복이 있는 from..to 범위, 프레임별 ms | Phaser 3.90·4.2 load.aseprite, PixiJS 8.21 프레임 |
| Phaser 3 / 4 | 아틀라스 JSON 해시나 multiatlas + .anims.json | 태그마다 애니메이션, 프레임별 길이 | Phaser 3.90·4.2 |
| PixiJS 8 | animations와 anchor가 든 spritesheet JSON | animations에 재생 순서, ms는 meta.nerulio | PixiJS 8.21 |
| Godot 4 | SpriteFrames .tres + AnimatedSprite2D .tscn | 태그별 speed, 상대 길이, 반복 | Godot 4.7.2 |
| 범용 JSON | TexturePacker식 frames, animationData, 피벗, 박스 | 자체 애니메이션 항목에 보존 | Phaser 3.90·4.2, PixiJS 8.21이 TexturePacker 해시로 읽음 |
| Spine / libGDX 아틀라스 | .atlas 텍스트 | 없음(아틀라스는 영역만 담음) | spine-canvas 4.2가 모든 영역을 그림 |
문제 해결
| 증상 | 유력한 원인 | 확인 방법 | 해결 |
|---|---|---|---|
| “Aseprite JSON describes one sheet image” 오류 | 현재 페이지 크기 한도로는 프레임이 한 페이지에 다 들어가지 않습니다 | 패킹·내보내기의 페이지 크기 설정 | 페이지 한도를 올리거나, Phaser 프리셋(멀티아틀라스)이나 PixiJS 8(연결된 페이지)을 쓰세요 |
| Phaser에서 애니메이션이 안 생김 | JSON에 frameTags가 없거나, 키가 단순한 프레임 번호가 아닙니다 | frames의 첫 키와 meta.frameTags가 있는지 봅니다 | Nerulio의 Aseprite JSON을 쓰거나, Aseprite에서 내보낼 때 Item Filename을 {frame}으로 두고 Meta의 Tags를 켜세요 |
| 직접 만든 로더에서 프레임이 튐 | spriteSourceSize를 무시해서 트림된 프레임이 오프셋을 잃었습니다 | 트림된 프레임의 위치를 spriteSourceSize와 비교합니다 | 각 프레임을 sourceSize 안의 spriteSourceSize.x/y에 그리거나 트림을 끄세요 |
| 읽는 프로그램에서 프레임이 옆으로 누움 | 패킹 때 회전을 허용했습니다. Aseprite 자체는 회전된 프레임을 쓰지 않습니다 | frames에 "rotated": true | 이 내보내기에서는 회전을 끄세요 |
| 게임에서 픽셀아트가 흐릿함 | 엔진이 텍스처를 선형 필터로 그립니다 | 가장자리를 확대해 봅니다 | Phaser는 게임 설정에 pixelArt: true, 다른 엔진은 최근접 필터 |
다른 방법
| 방법 | 이럴 때 더 낫습니다 |
|---|---|
Aseprite의 File > Export Sprite Sheet, 또는 aseprite -b hero.aseprite --sheet hero.png --data hero.json --format json-array --list-tags --list-slices | Aseprite가 있고 그 자체의 배치 옵션을 쓰고 싶을 때. --sheet-type packed는 패킹, --trim은 트림합니다. |
| Aseprite JSON 대신 엔진 대상 | 엔진이 Aseprite JSON으로 애니메이션을 만들지 않을 때(PixiJS, Godot, Unity). 대상별로 무엇이 남는지 참고. |
엔진별 내보내기와 검증 방법
"검증됨"은 실제 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는 원본과 동일합니다. |
검증 근거
내보내기: 실제 CC0 에셋으로 실제 엔진에서 49회 실행해 47회 통과. 실패 2회는 Phaser 3.90의 트림 XML 버그이며 Phaser 3 프리셋으로 피합니다. 실제 프레임 세트 5개로 패커 비교(CodeAndWeb 무료 웹 패커, GAPTools, free-tex-packer): 회전 허용 시 5개 모두 가장 작은 시트, 회전 없이는 5개 중 4개. 모든 프레임이 픽셀 단위로 복원됩니다.
한계
- Aseprite JSON은 한 페이지입니다. 아주 큰 세트는 멀티팩이 되는 엔진 프리셋이 필요합니다.
- 레이어를 따로 시트로 내보내지는 않습니다.
- 폴리곤(메시) 패킹은 제공하지 않습니다. 검증한 엔진 중 내보낸 데이터로 메시 아틀라스를 그리는 엔진이 없기 때문입니다.
- GameMaker 스트립은 GameMaker 자체에서 검증하지 않았습니다.
- 배율 변형(@0.5x~@4x)은 최근접 이웃 방식만 씁니다.
- 트림된 Starling XML은 Phaser 3.90에서 잘못 그려지므로 "Sparrow XML (Phaser 3)" 프리셋을 쓰세요.
버전과 출처
Nerulio의 Aseprite JSON은 Phaser 3.90과 4.2가 load.aseprite와 createFromAseprite로 불러왔고, PixiJS 8.21이 프레임을 읽었습니다. Aseprite가 직접 만든 JSON도 기준으로 같은 검사를 통과했습니다. 바탕이 되는 .aseprite 읽기는 실제 파일 231개로 확인했습니다. 위의 Aseprite·Phaser 내용은 각 공식 문서를 따릅니다.
참고한 공식 문서
자주 묻는 질문
Aseprite JSON은 왜 한 페이지뿐인가요?
Aseprite JSON 파일 하나는 이미지 하나를 설명하고 Phaser의 load.aseprite도 그렇게 읽기 때문에, 이 대상은 한 페이지로 다시 패킹합니다. 여러 페이지가 필요하면 Phaser 프리셋(multiatlas)이나 페이지를 related_multi_packs로 잇는 PixiJS 8을 쓰세요.
프레임 키가 "0", "1", "2"인 이유는?
Phaser의 createFromAseprite가 번호로 프레임을 찾기 때문에 --filename-format "{frame}" 형식으로 씁니다. Phaser 3.90·4.2가 load.aseprite로 불러왔고 PixiJS 8.21도 프레임을 읽었습니다.
두 태그가 같은 프레임을 쓰면 하나가 사라지나요?
아니요. Aseprite JSON에서 태그는 from..to 범위라서, 두 태그가 함께 쓰는 프레임이나 순서가 뒤섞인 태그의 프레임은 같은 영역을 가리키는 항목을 하나 더 만듭니다. 몇 개를 반복했는지 내보내기가 알려 줍니다.
무료인가요? 계정이 필요한가요?
이 페이지의 기능은 모두 무료이며 계정 없이 쓸 수 있습니다. 워터마크나 막혀 있는 내보내기가 없습니다.
스프라이트가 업로드되나요?
아니요. Studio는 이 브라우저 탭 안에서 디코딩·패킹·내보내기를 합니다. 프로젝트는 브라우저(IndexedDB)에 자동 저장되며 .nerulio 파일로 저장할 수 있습니다.
Aseprite나 엔진 플러그인을 설치해야 하나요?
아니요. .aseprite 파일은 브라우저에서 읽고 씁니다. 엔진별 번들에는 그 엔진에 필요한 것이 들어 있습니다(Godot는 가져오기 설정과 씬, Unity와 Godot 타일셋은 작은 편집기 스크립트).