Aseprite를 Phaser 3·4로 · 아틀라스와 애니메이션 JSON
.aseprite 파일 하나로 두 가지: anims.fromJSON으로 불러오는 아틀라스+애니메이션 파일, 또는 Phaser의 load.aseprite·createFromAseprite가 읽는 Aseprite JSON. 둘 다 Phaser 3.90·4.2에서 그려 확인했습니다.
Phaser 3·4는 .aseprite 파일을 읽지 않고 PNG와 JSON을 읽습니다. Nerulio는 파일을 Phaser가 지원하는 두 가지 JSON 경로 중 하나로 바꿉니다. this.anims.fromJSON()용 .anims.json이 딸린 TexturePacker 아틀라스(반복·핑퐁·프레임별 밀리초가 들어 있음), 또는 this.load.aseprite()와 this.anims.createFromAseprite()용 Aseprite JSON입니다. 둘 다 Phaser 3.90과 4.2가 불러와 그렸습니다. 프레임이 선명하게 보이도록 게임 설정에 pixelArt: true를 넣으세요.
- Phaser 3 / 4검증됨· Phaser 3.90 + 4.2
- Aseprite JSON검증됨· Phaser load.aseprite · PixiJS 8.21
- Starling / Sparrow XML검증됨· Phaser 4.2
- 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
- LÖVE검증됨· LÖVE 11.5
- Defold빌드 확인· Defold bob.jar 1.13.1
- GameMaker미검증
- CSS sprites검증됨· Chromium
- GIF / APNG디코딩 확인· Pillow
Phaser가 JSON으로 애니메이션을 만드는 두 가지 방법
Phaser는 텍스처 아틀라스에서 프레임을 그립니다. PNG와, 프레임마다 사각형·트림·피벗을 적은 JSON입니다. 애니메이션은 따로 만드는 객체로 키, 프레임 목록, 프레임 속도, 반복 횟수(−1은 무한), 처음으로 되돌아가며 재생하는 yoyo를 가집니다. 애니메이션 프레임마다 밀리초 길이를 줄 수 있고, 재생할 때 프레임 속도를 덮어쓰지 않는 한 Phaser는 그 값을 그 프레임의 시간으로 씁니다.
경로 1, 아틀라스 + 애니메이션 파일: load.atlas(페이지가 여럿이면 load.multiatlas)가 TexturePacker 형식 JSON을 읽고, anims.fromJSON이 모든 설정이 이미 들어 있는 JSON에서 애니메이션을 만듭니다. 경로 2, Aseprite JSON: load.aseprite가 Aseprite의 File › Export Sprite Sheet가 쓰는 JSON을 읽고, createFromAseprite가 태그마다 애니메이션을 만들며 프레임별 길이와 방향(역방향, 핑퐁은 yoyo)을 읽습니다. Phaser 3.90과 4.2 소스를 보면 태그의 반복 횟수는 읽지 않으므로, 재생할 때 반복을 지정하지 않으면 한 번만 재생됩니다.
Nerulio는 브라우저에서 .aseprite를 읽고 프레임마다 보이는 레이어를 합성해 패킹합니다. 경로 1에서는 태그마다 ∞면 repeat: -1, 횟수면 n − 1을 쓰고, 역방향은 순서를 뒤집어 쓰고, 핑퐁은 yoyo로, 프레임마다 밀리초를 씁니다. 경로 2에서는 createFromAseprite가 기대하는 "0" … "n" 프레임 키, 방향과 반복이 든 frameTags, 피벗과 박스용 슬라이스를 씁니다. 이 경로는 모든 프레임이 한 페이지에 있어야 합니다. 검증에서 두 Phaser 버전 모두 회전된 TexturePacker 프레임을 거울처럼 뒤집어 그렸기 때문에 회전은 끕니다.
- 아틀라스 JSON
- 사각형·트림·피벗이 든 TexturePacker 형식 프레임 목록(해시, 페이지가 여럿이면 multiatlas).
- anims.fromJSON
- 애니메이션 설정이 든 JSON 파일로 애니메이션을 만드는 함수.
- createFromAseprite
- 불러온 Aseprite JSON의 frameTag마다 애니메이션을 하나씩 만드는 함수.
- repeat
- 첫 재생 뒤 추가로 반복하는 횟수. −1은 무한 반복.
- yoyo
- 프레임을 앞으로 재생한 뒤 처음까지 거꾸로 재생.
예시: 태그 3개, 두 가지 경로
Aseprite 태그 hero.anims.json (경로 1)
idle 4 × 125 ms, ∞ frameRate 10, repeat -1, duration 125 ×4
attack 100, 100, 150, 250 ms, ×1 repeat 0(한 번 재생), duration 100, 100, 150, 250
jump 3 × 80 ms, 핑퐁, ∞ 프레임 0, 1, 2 + yoyo: true, repeat -1
Aseprite JSON (경로 2): frameTags idle 0–3, attack 4–7 (repeat "1"), jump 8–10 pingpong
createFromAseprite → idle, attack, jump 모두 repeat 0
sprite.play({ key: 'idle', repeat: -1 }) ← 반복 태그에 필요두 경로 모두 attack은 100 + 100 + 150 + 250 = 600ms 동안 재생됩니다. Phaser가 프레임마다 duration을 그 프레임의 시간으로 쓰기 때문입니다.
변환 후에도 남는 것
| Aseprite | Nerulio | Phaser 3 / 4 |
|---|---|---|
| 프레임 픽셀(보이는 레이어) | 합성한 프레임을 PNG에 패킹 | 트림 오프셋이 있는 아틀라스 프레임 |
| 프레임 길이(ms) | 프레임마다 유지 | AnimationFrame의 duration(ms), 그 프레임의 시간 |
| 태그 | 같은 이름의 애니메이션 하나 | 애니메이션 키(anims.json) 또는 frameTag(Aseprite JSON) |
| 방향: 역방향 | 프레임 순서를 뒤집어 기록 | 역순으로 놓인 프레임 |
| 방향: 핑퐁 | 프레임은 정방향으로 나열 | yoyo: true |
| 반복 ∞ / 반복 n | 반복 / n번 재생 | 경로 1: repeat: -1 / n − 1. 경로 2: 재생할 때 repeat를 직접 지정 |
| 피벗 슬라이스나 P 피벗 | 프레임 피벗 | 경로 1: 프레임 pivot, Phaser가 사용자 피벗으로 읽음. 경로 2: Phaser가 쓰지 않는 pivot 슬라이스 |
| hit / hurt 슬라이스 | 박스 | 경로 2에서만, 직접 쓸 수 있게 meta의 슬라이스로 |
이렇게 작동합니다
- 아틀라스 JSON 해시(페이지가 여럿이면 multiatlas)와 프레임별 길이가 든 .anims.json.
- frameTags(방향·반복)와 슬라이스가 있는 Aseprite JSON 해시·배열. createFromAseprite에 필요한 "0".."n" 프레임 키.
- Phaser용은 회전을 끕니다. 두 버전 모두 회전된 TexturePacker 프레임을 제대로 되돌려 그리지 못했기 때문입니다.
- PixiJS 8용은 animations와 anchor가 있는 전용 spritesheet JSON을 받습니다.
사용 방법
- .aseprite 파일을 끌어다 놓습니다.
- 타임라인에서 태그를 확인합니다.
- 패킹·내보내기에서 Phaser 3/4 또는 Aseprite JSON을 고릅니다.
- this.load.atlas·multiatlas + anims.fromJSON 또는 this.load.aseprite로 불러옵니다.
받게 되는 파일
경로 1(패킹·내보내기 › Phaser 3 / 4)과 경로 2(Aseprite JSON 해시·배열)의 파일입니다.
| 파일 | 용도 |
|---|---|
hero.png | 패킹된 프레임(트림, 2px 간격, 회전 없음). |
hero.json | 경로 1: 아틀라스 JSON 해시(페이지가 여럿이면 hero.multiatlas.json). 경로 2: "0"…"n" frames, meta.frameTags, meta.slices가 든 Aseprite JSON. |
hero.anims.json | 경로 1 전용: 태그마다 anims.fromJSON용 애니메이션 설정. |
README-PHASER.md / README-ASEPRITE-JSON.md | 이 번들을 불러오는 코드. |
Phaser에서 불러오기
- PNG와 JSON 파일을 게임의 에셋 폴더에 복사합니다.
- 게임 설정에
pixelArt: true를 넣어 만듭니다. 안티에일리어싱을 끄고 위치를 정수로 맞춥니다. - 경로 1,
preload()에서:this.load.atlas('hero', 'hero.png', 'hero.json')과this.load.json('hero-anims', 'hero.anims.json'). - 경로 1,
create()에서:this.anims.fromJSON(this.cache.json.get('hero-anims'))다음this.add.sprite(100, 100, 'hero').play('idle'). - 경로 2:
preload()에서this.load.aseprite('hero', 'hero.png', 'hero.json'), 그다음this.anims.createFromAseprite('hero'), 반복해야 할 태그는sprite.play({ key: 'idle', repeat: -1 }). sprite.play('attack')으로 애니메이션을 바꾸고, 한 번만 나오는 동작 뒤에는animationcomplete를 받아idle로 돌아갑니다.
결과 확인
create()에서this.anims.get('attack').frames.map(f => f.duration)을 출력하면 100, 100, 150, 250이 나와야 합니다.- 경로 1에서
this.anims.get('idle').repeat는 −1이어야 합니다. - jump는 앞으로 재생한 뒤 처음 쪽으로 되돌아가야 합니다.
this.anims.get('jump').yoyo가 true입니다. pixelArt: true면 4배로 확대해도 픽셀 경계가 선명해야 합니다.
문제 해결
| 증상 | 유력한 원인 | 확인 방법 | 해결 |
|---|---|---|---|
| 애니메이션이 한 번 재생되고 멈춤(경로 2) | createFromAseprite가 태그의 반복을 읽지 않아 모든 애니메이션이 repeat 0 | this.anims.get('idle').repeat가 0 | { key, repeat: -1 }로 재생하거나, 반복이 기록되는 경로 1 사용 |
| 애니메이션이 비었거나 프레임이 빠짐 | Aseprite JSON의 프레임 키가 "0"…"n"이 아닌 제목 형식이라 createFromAseprite가 찾지 못한 프레임을 건너뜀 | JSON frames의 키 확인 | Nerulio로 다시 내보내거나("0"…"n"으로 씀) Aseprite CLI를 --filename-format "{frame}"로 실행 |
| 스프라이트가 흐림 | 게임이 안티에일리어싱으로 실행됨 | 게임 설정 | pixelArt: true 설정 |
| 일부 프레임이 뒤집히거나 뒤섞여 보임 | 다른 패커의 회전된 프레임: Phaser는 회전된 TexturePacker 프레임을 거울처럼 그림 | JSON의 "rotated": true | 회전 없이 패킹. Phaser 아틀라스 프레임 오류 참고 |
| 프레임별 길이가 무시됨 | play()에 사용자 frameRate를 넘겨 Phaser가 모든 프레임에 같은 시간을 씀 | 재생 설정 확인 | 프레임 속도를 덮어쓰지 말고 길이를 바꾸기 |
| Nerulio가 Aseprite JSON 내보내기를 거부함 | 프레임이 한 페이지에 다 들어가지 않는데 Aseprite JSON은 시트 한 장만 설명함 | 내보내기 안내에 페이지 수가 나옴 | 페이지 크기를 키우거나 multiatlas를 쓰는 경로 1 사용 |
다른 방법
| 방법 | 이럴 때 더 낫습니다 |
|---|---|
Aseprite 자체 File › Export Sprite Sheet(JSON Data, 태그) + load.aseprite | Aseprite가 있고 그 내보내기를 선호할 때. 필요한 내보내기 설정은 Phaser 문서에 나와 있습니다. |
load.spritesheet와 anims.create로 쓰는 격자 시트 | 프레임 속도가 일정한 애니메이션 하나. 프레임 크기가 필요합니다: 프레임 크기 재기. |
| Phaser 대신 PixiJS | Aseprite JSON을 PixiJS로. |
엔진별 내보내기와 검증 방법
"검증됨"은 실제 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 프리셋으로 피합니다.
한계
- 레이어는 합쳐지고 블렌드 모드는 프레임에 구워집니다.
- 히트박스는 데이터일 뿐이며 Phaser가 물리 바디를 만들지는 않습니다.
- 경로 2는 모든 프레임이 한 페이지에 있어야 합니다.
- 격자·섬 인식은 신뢰도가 표시된 미리보기일 뿐이며 적용을 누르기 전에는 아무것도 자르지 않습니다. 모든 선택에는 한 번에 바꿀 수 있는 대안이 있습니다.
- 레이어가 정확히 합성되지 않는 .aseprite 파일(그룹 불투명도 등)은 합쳐서 가져오고, 가져오기 패널에 이유를 표시합니다.
- 가져온 아틀라스에서 회전된 프레임은 회전된 채로 남으며 그 내보내기는 미검증입니다.
- 이미지는 한 변 32,768px(2억 6,800만 픽셀)까지이며 브라우저 메모리에 따라 달라집니다.
버전과 출처
검증 실행에서 두 경로 모두 Phaser 3.90과 Phaser 4.2가 불러왔습니다. 모든 프레임을 그려 원본과 비교했고, anims.fromJSON과 createFromAseprite가 만든 애니메이션을 다시 읽었습니다. createFromAseprite가 태그의 반복을 무시한다는 점은 Phaser 3.90·4.2 소스에서 확인했고, 나머지는 Phaser API 문서를 따릅니다.
참고한 공식 문서
- Phaser docs: LoaderPlugin (spritesheet, atlas, aseprite)
- Phaser docs: SpriteSheetConfig
- Phaser docs: AnimationManager (create, createFromAseprite, fromJSON)
- Phaser docs: Animation and AnimationFrame config
- Phaser docs: Game config (pixelArt)
- Phaser 3.90 source: AnimationManager.createFromAseprite
- Aseprite 문서: Sprite sheets
자주 묻는 질문
어느 쪽을 써야 하나요?
Aseprite JSON은 Phaser의 Aseprite 흐름을 그대로 씁니다. 아틀라스 방식은 여러 스프라이트를 한 텍스처와 여러 페이지로 묶습니다.
Sparrow·Starling XML(FNF)은요?
내보낼 수 있습니다. Phaser 3.90에서는 XML 파서가 트림된 프레임을 잘못 그리므로 "Sparrow XML (Phaser 3)" 프리셋을 쓰세요.
무료인가요? 계정이 필요한가요?
이 페이지의 기능은 모두 무료이며 계정 없이 쓸 수 있습니다. 워터마크나 막혀 있는 내보내기가 없습니다.
스프라이트가 업로드되나요?
아니요. Studio는 이 브라우저 탭 안에서 디코딩·패킹·내보내기를 합니다. 프로젝트는 브라우저(IndexedDB)에 자동 저장되며 .nerulio 파일로 저장할 수 있습니다.
Aseprite나 엔진 플러그인을 설치해야 하나요?
아니요. .aseprite 파일은 브라우저에서 읽고 씁니다. 엔진별 번들에는 그 엔진에 필요한 것이 들어 있습니다(Godot는 가져오기 설정과 씬, Unity와 Godot 타일셋은 작은 편집기 스크립트).