Aseprite를 Godot 4로 · 플러그인 없이 SpriteFrames 만들기
PATH에 Aseprite 실행 파일도, 편집기 플러그인도 필요 없습니다. .aseprite 파일을 넣고 태그를 확인한 뒤 내보내면, 검증에서 Godot 4.7.2가 불러와 프레임마다 그린 번들이 나옵니다.
.aseprite 파일에는 프레임마다 밀리초 단위 길이, 태그(방향과 반복 횟수가 있는 이름 붙은 프레임 구간), 레이어, 슬라이스가 들어 있습니다. Godot 4는 이 파일을 직접 열지 못하고 AnimatedSprite2D에서 SpriteFrames 리소스를 재생합니다. Nerulio는 브라우저에서 파일을 읽어 태그마다 같은 타이밍의 SpriteFrames 애니메이션을 만들고, 프레임을 PNG 한 장에 패킹하고, 바로 쓸 수 있는 씬을 붙여 줍니다. 폴더를 res:// 아래에 복사하고 .tscn을 씬에 넣으면 첫 태그가 Nearest 필터로 재생됩니다. Godot 4 전용이며 4.7.2에서 확인했습니다.
- Godot 4검증됨· Godot 4.7.2
- .aseprite검증됨· Aseprite 1.3.18
- Unity 6검증됨· Unity 6000.5.3f1
- Phaser 3 / 4검증됨· Phaser 3.90 + 4.2
- PixiJS 8검증됨· PixiJS 8.21
- Aseprite JSON검증됨· Phaser load.aseprite · PixiJS 8.21
- 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 파일에 든 것과 Godot가 필요로 하는 것
Aseprite는 애니메이션 문서 전체를 저장합니다. 프레임마다 길이(ms)가 따로 있고, 태그는 프레임 구간에 이름을 붙여 하나의 애니메이션으로 묶으며(walk = 4~9번 프레임) 재생 방식도 정합니다. 정방향·역방향·핑퐁, 무한 반복 또는 정해진 횟수입니다. 레이어는 그림의 부분을 나눠 두고, 슬라이스는 피벗 위치나 히트박스 같은 사각형을 표시합니다.
Godot 4에서 프레임 애니메이션은 AnimatedSprite2D 노드가 SpriteFrames 리소스를 읽어 재생합니다. 애니메이션마다 이름, 초당 프레임 수(FPS), 반복 여부, 프레임 목록이 있고 프레임은 텍스처와 상대 길이로 이뤄집니다. Godot는 한 프레임을 상대 길이 ÷ (FPS × 속도 배율)초 동안 보여 주므로, 밀리초 값을 그대로 옮기면 안 되고 변환해야 합니다.
Nerulio는 모든 태그를 10 FPS로 씁니다. 한 틱이 100ms(Aseprite의 기본 프레임 길이)이고, 각 프레임의 상대 길이는 밀리초 ÷ 100입니다. 그래서 한 태그 안에서 길이가 제각각이어도 프레임 하나하나의 재생 시간이 Aseprite와 같습니다.
- 태그
- Aseprite에서 방향(정방향·역방향·핑퐁)과 반복 횟수가 있는, 이름 붙은 프레임 구간.
- SpriteFrames
- 애니메이션의 이름·속도(FPS)·반복·프레임을 저장하는 Godot 리소스.
- AtlasTexture
- 큰 텍스처의 사각 영역. 내보낸 프레임 하나하나가 패킹된 PNG의 한 영역을 가리킵니다.
- 상대 길이
- Godot의 프레임별 배수. 1.0은 애니메이션 FPS의 한 틱, 2.0은 두 틱 동안 표시됩니다.
예시: 태그 3개가 있는 32 × 32 캐릭터
프레임 16개와 태그 3개가 있는 .aseprite 파일을 내보내면 SpriteFrames에 다음 값이 들어갑니다.
Aseprite Godot 4 SpriteFrames
idle 프레임 0–3 각 125 ms ∞ idle 10 FPS 1.25 × 4 loop on
walk 프레임 4–9 각 100 ms ∞ walk 10 FPS 1.0 × 6 loop on
attack 프레임 10–15 100,100,100,100, attack 10 FPS 1.0, 1.0, 1.0, 1.0, loop off
150, 250 ms ×1 1.5, 2.5
상대 길이 = ms / (1000 / 10 FPS) = ms / 100 125 ms → 1.25 250 ms → 2.5
검산 1.25 / 10 = 0.125초 2.5 / 10 = 0.250초 (Aseprite와 동일)attack은 Aseprite에서 한 번만 재생하도록 되어 있어 반복이 꺼집니다. 한 번 재생된 뒤 마지막 프레임에 멈추므로, 스크립트에서 노드의 animation_finished 시그널을 받아 idle을 다시 재생하세요.
변환 후에도 남는 것
| Aseprite | Nerulio | Godot 4 |
|---|---|---|
| 프레임 픽셀(보이는 레이어) | 합성한 프레임을 PNG 한 페이지에 패킹 | 그 PNG의 AtlasTexture 영역 |
| 프레임 길이(ms) | 프레임마다 유지 | 상대 길이 = ms ÷ 100. 애니메이션 속도는 10 FPS |
| 태그 | 같은 이름의 애니메이션 하나 | 같은 이름의 SpriteFrames 애니메이션 |
| 방향: 역방향·핑퐁 | 재생 순서를 풀어서 기록(핑퐁: 0-1-2-3-2-1) | 그 순서대로 나열된 프레임 |
| 반복 ∞ | 반복 재생 | loop = true |
| 반복 1, 2, 3… | 미리보기에서 그 횟수만큼 재생 | loop = false: Godot에서는 한 번 재생(반복 횟수는 저장되지 않음) |
| 태그가 하나도 없음 | 모든 프레임으로 된 애니메이션 default 하나 | 애니메이션 default |
| 피벗이 있는 슬라이스 | 프레임 피벗(없으면 기본값: 하단 중앙) | 노드 offset = −첫 프레임 피벗, centered = false |
| hit / hurt 등의 이름을 가진 슬라이스 | 프레임별 박스 | 리소스 메타데이터 nerulio에 저장(노드로 만들지 않음) |
| 레이어·블렌드 모드·불투명도 | Studio에서는 유지 | 합쳐짐: Godot에는 합성된 프레임이 들어감 |
Godot 4.7에는 자체 핑퐁 반복 모드도 있지만, 내보내기는 순서를 프레임 단위로 직접 기록하므로 그 기능에 의존하지 않습니다.
이렇게 작동합니다
- 브라우저에서 .aseprite를 읽습니다: 레이어, 태그(방향·반복), 프레임별 길이, 슬라이스 → 피벗·박스·9-슬라이스.
- AtlasTexture 영역, 트림 여백, 상대 길이, 반복이 들어간 SpriteFrames .tres.
- texture_filter = Nearest와 피벗 오프셋이 설정된 AnimatedSprite2D .tscn.
- 무손실 압축, 밉맵 없음, fix_alpha_border 끔으로 설정된 .png.import(흐린 픽셀의 색이 유지됨).
사용 방법
- .aseprite 파일을 끌어다 놓습니다.
- 타임라인에서 태그와 길이를 확인합니다(정확히 합성되는 레이어는 레이어로 유지).
- 패킹·내보내기에서 Godot 4를 고릅니다.
- 번들을 Godot 프로젝트에 풀고 씬을 엽니다.
받게 되는 파일
| 파일 | 용도 |
|---|---|
hero.tres | SpriteFrames 리소스: 애니메이션, FPS, 반복 여부, 상대 길이, AtlasTexture 영역과 트림 여백, 피벗·박스·충돌 폴리곤이 든 메타데이터 nerulio. |
hero.tscn | 이 리소스를 쓰는 AnimatedSprite2D 하나가 든 씬: Nearest 필터, 첫 태그 자동 재생, 피벗을 오프셋으로 설정. |
hero.png | 패킹된 프레임(한 장에 다 들어가지 않으면 페이지가 늘어남). |
hero.png.import | Godot가 읽는 가져오기 설정: 무손실, 밉맵 없음, Fix Alpha Border 끔. 흐린 픽셀의 색이 바뀌지 않습니다. |
README-GODOT.md | 이 번들에 맞춘 아래 단계 설명. |
Godot 4로 가져오기
- 번들 압축을 풀고 폴더째
res://아래 아무 곳에나 복사합니다(예:res://characters/hero/)..tres가 상대 경로로 PNG를 찾으므로 파일을 한곳에 두세요. - 파일시스템 독이 가져오기를 끝낼 때까지 기다립니다. 함께 들어 있는
hero.png.import설정대로 아틀라스가 무손실·밉맵 없이 들어옵니다. hero.tscn을 씬으로 끌어 놓거나, 직접 만든AnimatedSprite2D를 선택해 Sprite Frames 속성에hero.tres를 지정합니다.- 노드의 Animation 속성이나 SpriteFrames 패널에서 애니메이션을 고릅니다. 함께 온 씬은 첫 태그를 자동 재생합니다.
- 스크립트에서는
$Hero.play("walk")로 바꿉니다. 반복하지 않는 태그라면animation_finished를 연결해idle을 다시 재생하세요. - 직접 만든 노드에는 프로젝트 설정 › Rendering › Textures › Canvas Textures › Default Texture Filter를 Nearest로 한 번 바꾸거나, 노드의 Texture › Filter를 Nearest로 설정합니다.
결과 확인
- 씬을 실행합니다. 100ms 프레임 6개로 된
walk는 Aseprite 미리보기처럼 0.6초마다 반복돼야 합니다. - SpriteFrames 패널을 엽니다. 애니메이션마다 태그의 프레임 수와 같아야 합니다(핑퐁 태그는 풀어 쓴 순서로 보임).
- 2D 뷰포트를 400%로 확대합니다. 픽셀 경계가 네모나게 유지돼야 하며, 흐리면 노드가 Linear 필터를 쓰는 것입니다.
print($Hero.sprite_frames.get_meta("nerulio"))로 프레임마다 피벗과 박스가 나오는지 봅니다.
문제 해결
| 증상 | 유력한 원인 | 확인 방법 | 해결 |
|---|---|---|---|
| 스프라이트가 흐리게 보임 | 노드가 프로젝트 기본 Linear 필터를 물려받음 | 확대해 보고 노드의 Texture › Filter 확인 | 노드의 Filter를 Nearest로, 또는 프로젝트의 Default Texture Filter를 Nearest로 |
| 흐린 픽셀(빛, 연기)의 색이 바뀜 | 함께 온 .png.import 대신 Godot 기본값(Fix Alpha Border 켬)으로 가져옴 | PNG의 Import 독에서 Fix Alpha Border가 켜져 있음 | hero.png.import를 PNG 옆에 두거나, Fix Alpha Border를 끄고 Reimport |
| 태그 하나가 없음 | 파일에 태그가 없어 전부 default가 됐거나, 내보내기 전에 태그 이름이 바뀌거나 지워짐 | 내보내기 전에 Nerulio 타임라인의 태그 줄 확인 | Aseprite나 타임라인에서 태그를 고친 뒤 다시 내보내기 |
| 한 번만 나와야 할 태그가 반복되거나, 반복돼야 할 태그가 멈춤 | 반복 ∞는 반복 켬, 횟수를 정한 반복은 반복 끔이 됨 | SpriteFrames 패널에서 해당 애니메이션의 반복 토글 | 태그의 반복 값을 바꾸거나 Godot에서 Loop를 전환. 한 번 재생 태그는 animation_finished 사용 |
| 애니메이션이 바뀔 때 캐릭터가 튐 | 프레임마다 피벗이 다른데 노드의 오프셋은 하나(첫 프레임 피벗) | 내보내기 안내에 피벗 불일치 경고가 뜸. 모든 피벗은 metadata/nerulio에 있음 | 모든 프레임에 같은 피벗 슬라이스를 쓰거나, 내보내기 전에 Nerulio에서 피벗을 맞추기(피벗 편집기) |
| Aseprite보다 빠르거나 느림 | 노드의 Speed Scale이나 play()의 사용자 속도가 1이 아님 | 인스펙터의 Speed Scale | Speed Scale을 1로 두고 play()를 사용자 속도 없이 호출 |
| Godot 3에서 .tres가 안 열림 | 프레임별 길이가 있는 Godot 4 형식 리소스 | — | Godot 4를 쓰거나, PNG 스프라이트 시트로 내보내 Godot 3에서 프레임을 직접 구성 |
다른 방법
| 방법 | 이럴 때 더 낫습니다 |
|---|---|
| Aseprite에서 PNG 시트로 내보내고(File › Export Sprite Sheet) Godot SpriteFrames 패널의 Add Frames from Sprite Sheet 사용 | 애니메이션이 한두 개이고 프레임 길이가 일정할 때. 파일은 적지만 애니메이션마다 FPS를 직접 정해야 하고 프레임별 길이는 사라집니다. Godot에서 스프라이트 시트 쓰기 참고. |
| Godot Asset Library의 .aseprite 가져오기 플러그인 | 그림을 자주 고치고 저장할 때마다 Godot가 다시 가져오게 하고 싶을 때. 이런 플러그인은 Aseprite 프로그램을 호출하므로 가져오는 모든 컴퓨터에 Aseprite가 설치돼 있어야 합니다. |
| 같은 파일을 다른 엔진으로 | Aseprite를 Unity로, Aseprite를 Phaser로. |
엔진별 내보내기와 검증 방법
"검증됨"은 실제 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 프리셋으로 피합니다.
한계
- 반복 횟수가 2 이상이어도 저장되지 않으며 Godot에서는 한 번 재생됩니다.
- 레이어는 합쳐져서 들어갑니다. Godot에서 부분별로 움직이려면 부분마다 파일을 따로 내보내세요.
- 히트·허트 박스는 리소스 메타데이터로만 들어갑니다.
Area2D와CollisionShape2D노드는 직접 만드세요. - 격자·섬 인식은 신뢰도가 표시된 미리보기일 뿐이며 적용을 누르기 전에는 아무것도 자르지 않습니다. 모든 선택에는 한 번에 바꿀 수 있는 대안이 있습니다.
- 레이어가 정확히 합성되지 않는 .aseprite 파일(그룹 불투명도 등)은 합쳐서 가져오고, 가져오기 패널에 이유를 표시합니다.
- 가져온 아틀라스에서 회전된 프레임은 회전된 채로 남으며 그 내보내기는 미검증입니다.
- 이미지는 한 변 32,768px(2억 6,800만 픽셀)까지이며 브라우저 메모리에 따라 달라집니다.
버전과 출처
검증 실행에서 Godot 4.7.2가 Nerulio 번들을 불러와 애니메이션마다 프레임 수·속도·반복·상대 길이를 다시 읽었고, 모든 프레임을 1배와 4배로 그려 원본과 비교했습니다. .aseprite 읽기는 실제 파일 231개로 확인했으며 Aseprite 1.3.18에서 같은 태그·길이·픽셀로 다시 열렸습니다. 위 단계의 Godot 동작은 Godot 4.7 공식 문서를 따릅니다.
참고한 공식 문서
자주 묻는 질문
Aseprite를 설치해야 하나요?
아니요. 파일을 브라우저에서 해석합니다. .aseprite 231개 코퍼스에서 222개는 레이어째, 9개는 이유를 표시하고 합쳐서 가져왔습니다.
.png.import를 같이 주는 이유는?
Godot 기본 가져오기는 알파 20 미만 픽셀의 색을 바꿉니다(fix_alpha_border). 번들의 설정이 이를 끄며, 그 설정으로 테스트의 이펙트 시트가 Godot에서 통과했습니다.
무료인가요? 계정이 필요한가요?
이 페이지의 기능은 모두 무료이며 계정 없이 쓸 수 있습니다. 워터마크나 막혀 있는 내보내기가 없습니다.
스프라이트가 업로드되나요?
아니요. Studio는 이 브라우저 탭 안에서 디코딩·패킹·내보내기를 합니다. 프로젝트는 브라우저(IndexedDB)에 자동 저장되며 .nerulio 파일로 저장할 수 있습니다.
Aseprite나 엔진 플러그인을 설치해야 하나요?
아니요. .aseprite 파일은 브라우저에서 읽고 씁니다. 엔진별 번들에는 그 엔진에 필요한 것이 들어 있습니다(Godot는 가져오기 설정과 씬, Unity와 Godot 타일셋은 작은 편집기 스크립트).