Phaser 텍스처 아틀라스 생성기 · 아틀라스 JSON과 애니메이션

프레임을 넣으면 this.load.atlas(또는 multiatlas)와 anims.fromJSON이 읽는 파일이 나옵니다. 촘촘한 아틀라스, JSON 해시, 프레임별 길이가 든 애니메이션 파일이며 검증에서 Phaser 3.90·4.2가 그렸습니다.

Phaser는 텍스처 아틀라스를 PNG와 TexturePacker 배치의 JSON(해시 또는 배열)으로 불러옵니다. this.load.atlas(key, png, json)로 읽은 뒤에는 this.add.sprite(x, y, key, "run_0")처럼 프레임 이름으로 부릅니다. Nerulio는 프레임을 이 배치로 패킹하고, this.anims.fromJSON용으로 모든 태그와 프레임별 길이를 담은 .anims.json을 덧붙입니다. 검증 실행에서 Phaser 3.90과 4.2가 회전된 프레임을 되돌려 그리지 못했기 때문에 회전은 끄며, 트림된 프레임은 제대로 그려집니다. Phaser 3.90과 4.2에서 확인했습니다.

패킹할 프레임 이미지, GIF 또는 .aseprite 파일을 끌어다 놓으세요

빈 Studio 열기

브라우저에서 처리하며 파일은 업로드되지 않습니다.

내보내기 대상

Phaser 3 / 4검증됨· Phaser 3.90 + 4.2
Starling / Sparrow XML검증됨· Phaser 4.2
Godot 4검증됨· Godot 4.7.2
Unity 6검증됨· Unity 6000.5.3f1
PixiJS 8검증됨· PixiJS 8.21
Aseprite JSON검증됨· Phaser load.aseprite · 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가 아틀라스에서 프레임을 찾는 방법

로더는 frames 아래 항목마다 하나의 텍스처 키에 속한 이름 있는 프레임을 만듭니다. frame은 PNG에서 잘라 낼 사각형입니다. trimmed가 참이면 Phaser가 sourceSize와 spriteSourceSize를 프레임의 트림 정보로 넘기므로, 잘린 조각이 원래 크기의 상자 안에 그려지고 스프라이트는 트림하지 않은 것처럼 동작합니다. 항목에 pivot이 있으면 프레임을 지정할 때 스프라이트의 원점이 됩니다.

애니메이션은 이 이름을 가리킵니다. 코드에서 this.anims.generateFrameNames(key, {prefix, start, end, zeroPad})로 만들거나, 데이터로 this.anims.fromJSON에 넘길 수 있습니다. 애니메이션 프레임마다 밀리초 단위 duration을 둘 수 있습니다. Phaser 3.90의 애니메이션 코드에서는 그 길이가 지나면 다음 프레임으로 넘어가고, 값이 0이면 애니메이션의 프레임당 밀리초를 씁니다.

프레임이 여러 페이지에 걸치면 this.load.multiatlas(key, json, path)가 textures 목록이 있는 JSON 하나를 읽습니다. 페이지 이미지마다 항목이 하나씩 있고 프레임 이름은 페이지를 넘어 고유하므로, 코드에서는 프레임이 어느 페이지에 있는지 신경 쓰지 않아도 됩니다.

텍스처 키: 로더에 준 이름("run"). 모든 프레임이 이 아래에 있습니다.
프레임 이름: frames 항목의 키("run_0"). add.sprite와 애니메이션이 이 이름을 씁니다.
JSON 해시 / 배열: 같은 프레임 데이터를 이름을 키로 한 객체로, 또는 filename 필드가 있는 목록으로 쓴 것. Phaser는 둘 다 읽습니다.
multiatlas: textures 목록이 있는 JSON 하나. 페이지 이미지마다 항목 하나.

예시: Phaser가 받는 달리기 동작

run.png   38 × 50px, 40 × 29 프레임 6장, 트림 켬, 간격 2, 회전 없음

"run_0": { "frame": {"x":0,"y":34,"w":18,"h":15},
           "spriteSourceSize": {"x":10,"y":10,"w":18,"h":15},
           "sourceSize": {"w":40,"h":29}, "rotated": false, "trimmed": true }
"pivot": {"x":0.5,"y":1}   → 스프라이트 원점 (0.5, 1): 두 발 사이의 점

run.anims.json   { "key":"run", "frameRate":10, "repeat":-1, "yoyo":false,
                   "frames":[ {"key":"run","frame":"run_0","duration":100}, … ×6 ] }

this.add.sprite(100, 100, "run", "run_0")
  → 발이 (100, 100)에 서는 40 × 29 스프라이트. 18 × 15 조각은 그 안의 (10, 10)에 그려짐
6프레임 × 100ms = 0.6초마다 한 바퀴. repeat -1 = 무한 반복

Phaser의 repeat는 추가 재생 횟수를 셉니다. Aseprite나 Studio에서 3번 재생으로 설정한 태그는 repeat: 2로 쓰이고, 핑퐁 태그는 yoyo: true가 됩니다.

이렇게 작동합니다

아틀라스 JSON 해시, 프레임이 여러 페이지에 걸치면 multiatlas.
태그마다 애니메이션 하나와 프레임별 길이가 든 .anims.json(this.anims.fromJSON용).
Phaser용은 회전을 끕니다. 3.90·4.2 모두 회전된 TexturePacker 프레임을 제대로 되돌려 그리지 못했기 때문입니다.
프레임 오프셋을 유지하는 트림, 같은 프레임 합치기, 여백과 가장자리 확장.

사용 방법

번호 붙은 프레임, GIF 또는 .aseprite 파일을 끌어다 놓습니다.
타임라인에서 애니메이션을 확인합니다.
패킹·내보내기에서 Phaser 3 / 4 프리셋을 고릅니다.
this.load.atlas(또는 multiatlas)로 아틀라스를, this.anims.fromJSON으로 애니메이션을 불러옵니다.

받게 되는 파일

파일	용도
`run.json`	한 페이지용 아틀라스 JSON 해시: `frame`, `trimmed`, `spriteSourceSize`, `sourceSize`, `rotated`, 정규화된 `pivot`이 있는 `frames`와 `meta.image`, `meta.size`.
`run.multiatlas.json`	프레임이 여러 페이지에 걸칠 때 run.json 대신 생성: `run-0.png`, `run-1.png` …와 각 프레임이 든 `textures` 목록.
`run.anims.json`	태그마다 애니메이션 하나: ms 단위 `duration`이 있는 프레임, `frameRate`, `repeat`(−1 = 반복), 핑퐁용 `yoyo`. 태그가 없으면 만들지 않음.
`run.png`	패킹된 페이지. 색이 256개 이하면 인덱스 PNG.
`README-PHASER.md`	이 번들용 preload·create 코드.

Phaser 3·4에서 쓰기

PNG와 JSON 파일을 함께 게임의 assets 폴더에 복사합니다. multiatlas는 JSON 안의 이미지 이름으로 페이지를 찾습니다.
preload()에서 this.load.atlas("run", "assets/run.png", "assets/run.json")(또는 this.load.multiatlas("run", "assets/run.multiatlas.json", "assets/"))와 this.load.json("run-anims", "assets/run.anims.json")을 호출합니다.
create()에서 this.anims.fromJSON(this.cache.json.get("run-anims"))로 애니메이션을 등록하고, const hero = this.add.sprite(160, 120, "run", "run_0") 뒤 hero.play("run")을 호출합니다.
도트 그림이면 게임을 pixelArt: true로 만듭니다. antialias를 끄고 roundPixels를 켜는 설정입니다.
애니메이션을 직접 만들려면 this.anims.create({ key: "run", frames: this.anims.generateFrameNames("run", { prefix: "run_", start: 0, end: 5 }), frameRate: 10, repeat: -1 })를 씁니다.

결과 확인

this.textures.get("run").getFrameNames()에 run_0 … run_5가 확장자 없이 나와야 합니다.
this.add.image(100, 100, "run", "run_0")와 "run_4"를 같은 점에 놓습니다. 저장된 조각의 오프셋이 달라도 발이 한 선에 있어야 합니다.
this.anims.exists("run")이 참이고, hero.play("run")의 한 바퀴가 0.6초여야 합니다.

문제 해결

증상	유력한 원인	확인 방법	해결
프레임 이름에 엉뚱한 그림이 나오거나 아무것도 안 나옴	이 키 아래에 그 이름이 없음: 오타, 확장자가 남아 있음, 다른 텍스처 키	`this.textures.get(key).getFrameNames()`	JSON에 있는 이름 그대로 사용. Nerulio는 확장자를 뺌(run_0, run_0.png 아님)
일부 프레임만 뒤집히거나 돌아감	회전을 켠 아틀라스(예: 회전을 켠 TexturePacker). Phaser 3.90과 4.2는 이런 프레임을 되돌리지 못했음	해당 항목에 `"rotated": true`	회전을 끄고 다시 패킹. Phaser 아틀라스 프레임 오류 참고
도트 그림이 흐리거나 움직일 때 반짝임	선형 필터와 픽셀 사이 위치	게임 설정에 `pixelArt: true`가 없음	`pixelArt: true`, 또는 `antialias: false`와 `roundPixels: true`
`play("run")`이 아무 일도 안 함	애니메이션이 등록되지 않음: JSON을 불러오기 전에 `fromJSON`을 실행했거나 다른 캐시 키를 읽음	`this.anims.exists("run")`	preload가 끝난 뒤 `create()`에서 `this.anims.fromJSON(this.cache.json.get("run-anims"))` 호출
재생 속도가 편집기와 다름	`play()`에 준 `frameRate`가 애니메이션 값과 달라서 Phaser가 프레임별 `duration` 대신 프레임당 밀리초를 씀	재생 설정 확인	`frameRate`를 덮어쓰지 말고 태그에서 길이를 바꿈

다른 방법

방법	이럴 때 더 낫습니다
Phaser의 Aseprite 로더: `this.load.aseprite`와 `this.anims.createFromAseprite`	그림이 Aseprite에 있고 JSON의 태그를 바로 쓰고 싶을 때. 한 페이지만, 회전 없음. Aseprite를 Phaser로 참고.
`this.load.atlasXML`로 읽는 Starling / Sparrow XML	이미 XML을 쓰는 파이프라인(FNF 방식 에셋). Phaser 3.90에서는 트림을 끄세요. Sparrow XML 참고.
TexturePacker의 Phaser 내보내기	이미 TexturePacker가 있을 때. Phaser 형식은 기본으로 회전하지 않으며, 시험한 네 세트 모두 Phaser 3.90과 4.2에서 통과했습니다.

엔진별 내보내기와 검증 방법

"검증됨"은 실제 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개. 모든 프레임이 픽셀 단위로 복원됩니다.

한계

폴리곤(메시) 패킹은 제공하지 않습니다. 검증한 엔진 중 내보낸 데이터로 메시 아틀라스를 그리는 엔진이 없기 때문입니다.
GameMaker 스트립은 GameMaker 자체에서 검증하지 않았습니다.
배율 변형(@0.5x~@4x)은 최근접 이웃 방식만 씁니다.
트림된 Starling XML은 Phaser 3.90에서 잘못 그려지므로 "Sparrow XML (Phaser 3)" 프리셋을 쓰세요.

버전과 출처

Nerulio의 아틀라스와 애니메이션 파일을 실제 CC0 프레임 세트로 Phaser 3.90.0과 4.2.1(Chromium에서 실제 phaser.min.js)에 불러와, 모든 프레임을 원본과 비교했습니다. 로더와 애니메이션 호출은 Phaser 공식 문서를 따르며, 피벗이 원점이 되는 동작과 프레임 길이 처리는 Phaser 3.90 소스에서 확인했습니다.

참고한 공식 문서

자주 묻는 질문

회전이 꺼져 있는 이유는?

시험에서 Phaser 3.90·4.2 모두 회전된 TexturePacker 프레임을 제대로 되돌려 그리지 못했기 때문에 Phaser 프리셋은 회전하지 않습니다.

Phaser 자체 Aseprite 로더를 써도 되나요?

네. load.aseprite와 createFromAseprite용 Aseprite JSON을 내보내면 되며, 같은 Phaser 버전에서 검증했습니다.

무료인가요? 계정이 필요한가요?

이 페이지의 기능은 모두 무료이며 계정 없이 쓸 수 있습니다. 워터마크나 막혀 있는 내보내기가 없습니다.

스프라이트가 업로드되나요?

아니요. Studio는 이 브라우저 탭 안에서 디코딩·패킹·내보내기를 합니다. 프로젝트는 브라우저(IndexedDB)에 자동 저장되며 .nerulio 파일로 저장할 수 있습니다.

Aseprite나 엔진 플러그인을 설치해야 하나요?

아니요. .aseprite 파일은 브라우저에서 읽고 씁니다. 엔진별 번들에는 그 엔진에 필요한 것이 들어 있습니다(Godot는 가져오기 설정과 씬, Unity와 Godot 타일셋은 작은 편집기 스크립트).