Aseprite JSON을 PixiJS로 · 태그가 애니메이션으로
Aseprite JSON을 PixiJS에 불러오면 텍스처는 생기지만 애니메이션은 없습니다. Spritesheet가 프레임만 읽고 meta.frameTags와 프레임별 duration은 쓰지 않기 때문입니다. JSON과 PNG를 여기에 넣고 PixiJS 8용으로 다시 내보내면 태그는 재생 순서의 animations 맵이, 슬라이스 피벗은 anchor가 되고, 밀리초는 AnimatedSprite용으로 남습니다.
PixiJS 8은 Aseprite JSON을 스프라이트시트로 불러오지만 프레임만 읽습니다. meta.frameTags와 프레임별 duration은 무시되어 sheet.animations가 비어 있습니다. JSON과 PNG를 함께 Nerulio에 넣고 PixiJS 8로 내보내면, 파일에 animations 맵(태그마다 항목 하나, 재생 순서의 프레임), 프레임별 anchor, meta.nerulio.animations의 밀리초가 들어갑니다. 이 밀리초를 {texture, time}으로 AnimatedSprite에 넘기면 됩니다. PixiJS 8.21로 확인했습니다.
- PixiJS 8검증됨· PixiJS 8.21
- Godot 4검증됨· Godot 4.7.2
- Unity 6검증됨· Unity 6000.5.3f1
- Phaser 3 / 4검증됨· Phaser 3.90 + 4.2
- 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
PixiJS가 스프라이트시트 JSON에서 읽는 것
PixiJS의 Spritesheet는 TexturePacker 구조를 받습니다. frames(각각 frame, spriteSourceSize, sourceSize, 선택적 anchor), 이름을 프레임 이름 목록에 연결하는 선택적 animations 객체, 이미지와 scale이 있는 meta입니다. PixiJS 문서는 기본 앵커와 애니메이션 묶음이 TexturePacker 형식 데이터에서만 지원된다고 설명하며, Aseprite의 frameTags는 이 형식에 없습니다. 검증에서도 PixiJS는 frameTags로 애니메이션을 만들지 않았습니다.
AnimatedSprite는 텍스처 목록을 한 속도로 재생하거나, time이 밀리초인 {texture, time} 객체 목록을 재생합니다. loop, updateAnchor, onComplete 같은 콜백은 있지만 핑퐁과 반복 횟수는 없으므로, 방향은 프레임 순서에 풀어 써야 합니다.
Nerulio의 PixiJS 8 내보내기는 두 가지를 모두 합니다. animations[tag]에 한 사이클의 재생 순서대로 프레임 키를 적고(역방향·핑퐁을 펼쳐서), meta.nerulio.animations[tag]에 fps, loop, direction, 단계마다 숫자 하나인 durationsMs를 넣어 텍스처와 바로 짝지을 수 있게 합니다.
- Spritesheet
- JSON을
textures와animations로 바꾸는 PixiJS 클래스. - FrameObject
{texture, time}: AnimatedSprite의 한 단계, 시간은 밀리초.- anchor
- 프레임 텍스처의 기본 앵커(크기 대비 0–1). Nerulio는 프레임 피벗을 씁니다.
- related_multi_packs
- 이 페이지와 함께 불러오는 다른 JSON 페이지 목록.
예시: 핑퐁 walk 태그를 Aseprite JSON에서 PixiJS로
Aseprite JSON 프레임 "4" … "9", 각각 "duration": 100
{ "name": "walk", "from": 4, "to": 9, "direction": "pingpong" }
PixiJS 8 JSON "animations": { "walk": ["4","5","6","7","8","9","8","7","6","5"] }
meta.nerulio.animations.walk.durationsMs = [100, 100, … 값 10개]
한 사이클: 6 + 4 = 10단계 × 100 ms = 1.0 s
const { durationsMs, loop } = sheet.data.meta.nerulio.animations.walk;
const walk = new AnimatedSprite(sheet.animations.walk.map((texture, i) => ({ texture, time: durationsMs[i] })));
walk.loop = loop; walk.play();프레임 키는 JSON의 프레임 이름에서 옵니다. hero 4.aseprite 같은 Aseprite 기본 이름이면 hero_4가 됩니다.
무엇이 어디로 옮겨지나
| 내보낸 JSON에서 | PixiJS API | 할 일 |
|---|---|---|
animations[tag] | sheet.animations[tag]: 텍스처 배열 | {texture, time} 객체로 변환 |
meta.nerulio.animations[tag].durationsMs | FrameObject.time | 단계마다 값 하나, 같은 순서 |
meta.nerulio.animations[tag].loop | AnimatedSprite.loop | 설정하세요. 유한 반복 횟수는 PixiJS에 대응 항목이 없습니다 |
frames[key].anchor(피벗) | 텍스처의 기본 앵커 | 프레임마다 피벗이 다르면 updateAnchor = true |
meta.scale | sheet.resolution | @2x 시트가 @1x 크기로 그려집니다 |
meta.related_multi_packs | 첫 페이지와 함께 로드(linkedSheets) | 다른 페이지의 텍스처는 캐시에서 가져옵니다 |
이렇게 작동합니다
- 해시·배열 형식의 Aseprite JSON을 frameTags(방향·반복), 프레임별 길이와 함께 시트 PNG와 짝지어 읽습니다.
- 태그마다 항목 하나인 animations 맵. 프레임 키가 재생 순서라 역방향·핑퐁도 코드 없이 맞게 재생됩니다.
- 프레임마다 피벗에서 온 anchor: P로 찍은 피벗, 없으면 아래 가운데(JSON의 meta.slices는 읽지 않음).
- meta.nerulio.animations에 태그별 fps·loop·방향·durationsMs를 남기고, README에 그 시간으로 AnimatedSprite를 만드는 코드가 있습니다.
- 여러 페이지는 related_multi_packs로 이어 함께 불러오고, 배율 변형은 각자의 meta.scale을 가집니다.
사용 방법
- Aseprite JSON과 PNG를 함께 넣습니다.
- 타임라인에서 태그를 확인하고, anchor가 달라야 할 곳은 P로 피벗을 옮깁니다.
- 패킹·내보내기에서 PixiJS 8을 고릅니다. 이 대상은 회전을 써도 됩니다.
- 내보낸 JSON을 Assets.load로 불러와 meta.nerulio의 시간으로 sheet.animations에서 AnimatedSprite를 만듭니다.
받게 되는 파일
| 파일 | 용도 |
|---|---|
hero.json | PixiJS 8 스프라이트시트: anchor가 있는 frames, animations, meta.nerulio.animations. 페이지가 여럿이면 hero-0.json, hero-1.json …이 related_multi_packs로 연결됩니다. |
hero.png | 패킹된 페이지(이 대상은 회전을 허용합니다). |
README-PIXI.md | 이 묶음을 불러오고 AnimatedSprite를 만드는 코드. |
PixiJS 8에서 재생하기
hero.json과hero.png를 앱이 에셋을 제공하는 곳에 나란히 둡니다.- 픽셀아트라면 불러오기 전에:
TextureSource.defaultOptions.scaleMode = 'nearest'. const sheet = await Assets.load('hero.json')가 페이지를 불러오고sheet.textures와sheet.animations를 만듭니다.- 예시처럼
sheet.animations[tag]와durationsMs로 애니메이션을 만들고loop를 설정한 뒤play()하고 스테이지에 추가합니다. - 프레임마다 피벗이 움직이면 AnimatedSprite에
updateAnchor = true를 설정해 프레임마다 자기 앵커를 쓰게 하세요.
결과 확인
Object.keys(sheet.animations)에 Aseprite 태그 이름이 모두 나옵니다.- 단계당 100 ms인 10단계 핑퐁 walk는 1초에 한 번 돌고,
onLoop가 그 간격으로 호출됩니다. - 캔버스를 확대하세요.
nearest배율이면 픽셀 가장자리가 네모로 남습니다.
Aseprite JSON 항목과 PixiJS 8의 대응
| Aseprite JSON | PixiJS 8 스프라이트시트 JSON | PixiJS의 처리 |
|---|---|---|
| frames[…].frame | 새 페이지의 frames[key].frame | 텍스처 영역 |
| spriteSourceSize, sourceSize | 같은 항목 | 트림 오프셋 반영 |
| frames[…].duration | meta.nerulio.animations[태그].durationsMs | 스스로는 쓰지 않음, AnimatedSprite 시간으로 전달 |
| meta.frameTags from·to·direction | 재생 순서의 animations[태그] | sheet.animations[태그]로 텍스처 목록 |
| frameTags repeat | meta.nerulio.animations[태그].loop | 스프라이트의 loop를 직접 설정 |
| meta.slices 피벗(읽지 않음, P로 놓은 피벗, 기본은 아래 가운데) | frames[key].anchor | 텍스처의 기본 anchor |
| meta.image, 한 페이지 | 페이지마다 meta.image와 related_multi_packs | 나머지 페이지도 함께 불러옴 |
문제 해결
| 증상 | 유력한 원인 | 확인 방법 | 해결 |
|---|---|---|---|
sheet.animations가 비어 있음 | 내보낸 파일이 아니라 원래 Aseprite JSON을 불러왔습니다. PixiJS는 frameTags를 무시합니다 | Assets.load가 어떤 JSON을 받는지 확인합니다 | Nerulio의 PixiJS 8 내보내기를 불러오세요 |
| 모든 프레임이 같은 속도로 재생됨 | 시간 없이 텍스처만 넘겨서 animationSpeed가 적용됩니다 | AnimatedSprite 생성 코드를 봅니다 | durationsMs로 만든 {texture, time} 객체를 넘기세요 |
| 프레임 사이에 스프라이트가 튀거나 미끄러짐 | 프레임마다 피벗이 다른데 스프라이트가 첫 프레임의 앵커를 유지합니다 | frames[key].anchor 값을 비교합니다 | updateAnchor = true로 하거나, Nerulio에서 태그에 피벗을 하나로(P) 정하세요 |
| 앵커가 전부 아래 가운데 | 가져올 때 Aseprite JSON의 meta.slices를 읽지 않아 기본 피벗으로 시작합니다 | 내보낸 파일의 anchor를 봅니다 | Nerulio에서 P로 피벗을 놓거나, 피벗 슬라이스를 읽는 .aseprite 파일 자체를 가져오세요 |
| @2x 시트가 두 배 크기로 그려짐 | meta.scale이 1이라 PixiJS가 해상도 1로 봅니다 | sheet.resolution | Nerulio에서 @2x 변형을 내보내세요. meta.scale을 "2"로 씁니다 |
다른 방법
| 방법 | 이럴 때 더 낫습니다 |
|---|---|
frameTags와 duration을 읽는 로더를 직접 작성 | 파이프라인에서 Aseprite JSON을 그대로 써야 할 때. meta.frameTags와 길이를 읽어 FrameObject를 직접 만드세요. |
| .aseprite 파일에서 내보내기 | .aseprite 원본이 있을 때. Aseprite JSON 가져오기와 달리 슬라이스(피벗, 박스)도 읽습니다. |
| 낱장 프레임으로 PixiJS 스프라이트시트 만들기 | 프레임이 Aseprite 내보내기가 아니라 따로 된 PNG일 때. |
엔진별 내보내기와 검증 방법
"검증됨"은 실제 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의
meta.slices는 읽지 않습니다. 슬라이스 피벗은.aseprite파일이 필요합니다. - PixiJS에는 반복 횟수가 없어 애니메이션은 반복하거나 한 번 재생하거나 둘 중 하나입니다.
- 폴리곤(메시) 패킹은 제공하지 않습니다. 검증한 엔진 중 내보낸 데이터로 메시 아틀라스를 그리는 엔진이 없기 때문입니다.
- GameMaker 스트립은 GameMaker 자체에서 검증하지 않았습니다.
- 배율 변형(@0.5x~@4x)은 최근접 이웃 방식만 씁니다.
- 트림된 Starling XML은 Phaser 3.90에서 잘못 그려지므로 "Sparrow XML (Phaser 3)" 프리셋을 쓰세요.
버전과 출처
PixiJS 8 대상은 PixiJS 8.21이 회전·다중 페이지 아틀라스까지 불러와 그렸고, @2x 변형은 meta.scale에 따라 @1x 크기로 그렸습니다. 여기 적은 PixiJS 동작은 PixiJS 8 API 문서를 따릅니다.
참고한 공식 문서
자주 묻는 질문
PixiJS가 Aseprite의 frameTags를 읽나요?
읽지 않습니다. Spritesheet는 프레임으로 텍스처만 만들어서 Aseprite JSON으로는 PixiJS에서 애니메이션이 생기지 않습니다. 이 내보내기는 PixiJS가 읽는 animations 맵을 씁니다.
프레임마다 다른 길이로 재생하려면?
meta.nerulio.animations[이름]의 durationsMs를 읽어 {texture, time} 쌍으로 new AnimatedSprite에 넘기세요. 내보낸 README에 예제가 있습니다. 도트라면 TextureSource.defaultOptions.scaleMode를 'nearest'로 두세요.
PixiJS에서 확인했나요?
네. 이 대상의 파일을 PixiJS 8.21이 불러와 그렸고, 회전·여러 페이지 아틀라스도 포함했습니다.
무료인가요? 계정이 필요한가요?
이 페이지의 기능은 모두 무료이며 계정 없이 쓸 수 있습니다. 워터마크나 막혀 있는 내보내기가 없습니다.
스프라이트가 업로드되나요?
아니요. Studio는 이 브라우저 탭 안에서 디코딩·패킹·내보내기를 합니다. 프로젝트는 브라우저(IndexedDB)에 자동 저장되며 .nerulio 파일로 저장할 수 있습니다.
Aseprite나 엔진 플러그인을 설치해야 하나요?
아니요. .aseprite 파일은 브라우저에서 읽고 씁니다. 엔진별 번들에는 그 엔진에 필요한 것이 들어 있습니다(Godot는 가져오기 설정과 씬, Unity와 Godot 타일셋은 작은 편집기 스크립트).