TexturePacker를 Godot 4로 · 플러그인 없이
TexturePacker(또는 같은 JSON을 쓰는 패커)로 묶은 시트를 고도 엔진 4 프로젝트에 넣고 싶다면 PNG와 JSON을 함께 끌어다 놓으세요. 프레임마다 트림 정보를 읽고, 이름으로 애니메이션을 묶어, AnimatedSprite2D 씬이 딸린 SpriteFrames .tres로 내보냅니다. 검증에서 Godot 4.7.2가 불러와 프레임마다 그린 번들 형식이며, 편집기 플러그인은 필요 없습니다.
TexturePacker JSON 데이터 파일(해시 또는 배열)에는 스프라이트마다 이름, PNG 위 사각형, 트림(spriteSourceSize, sourceSize), rotated 표시, 선택적으로 피벗이 있지만 애니메이션과 시간 정보는 없습니다. PNG와 JSON을 Nerulio에 함께 넣으면 트림을 반영해 프레임을 읽고, 이름으로 애니메이션을 묶고(walk_01, walk_02 → walk), 편집기 플러그인 없이 Godot 4용 SpriteFrames .tres, AnimatedSprite2D .tscn, .png.import로 내보냅니다. Godot 4 전용이며, 이 번들 형식은 Godot 4.7.2에서 불러와 확인했습니다.
- Godot 4검증됨· Godot 4.7.2
- 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
- .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
TexturePacker 파일에 든 것과 Godot가 필요로 하는 것
TexturePacker의 JSON은 스프라이트 목록입니다. 각각에 frame(PNG 위에 저장된 픽셀 위치), spriteSourceSize(그 픽셀이 원래 이미지에서 있던 위치), sourceSize(원래 크기), rotated(조각이 90도 돌려져 있음), 그리고 피벗을 설정했다면 0–1 범위의 pivot이 있습니다. meta.image가 PNG 이름, meta.size가 그 크기입니다. 프레임 길이도 애니메이션 목록도 없고, 애니메이션은 이름 규칙으로만 존재합니다.
Godot 4는 AnimatedSprite2D가 SpriteFrames 리소스를 재생해 프레임 애니메이션을 보여 줍니다. 여기서 프레임 하나는 AtlasTexture이며, region은 아틀라스 위 사각형이고 margin이 트림된 테두리를 되돌려 주어 트림된 프레임도 원래 크기를 유지합니다. AtlasTexture에는 atlas, region, margin, filter_clip만 있고 회전 속성이 없기 때문에, 회전된 스프라이트는 다시 패킹해야 합니다.
Nerulio는 TexturePacker의 PNG를 그대로 쓰지 않습니다. 모든 프레임을 트림째 잘라 내고, 타임라인에서 태그 이름과 길이를 정하게 한 다음, 회전 없이 Godot용 새 페이지를 패킹합니다. 페이지 배치는 TexturePacker와 다를 수 있지만 프레임 이름은 그대로입니다.
- spriteSourceSize
- 원래 이미지 안에서 저장된 픽셀의 x, y, w, h.
- sourceSize
- 트림 전 원래 이미지의 너비와 높이.
- AtlasTexture margin
- 트림된 프레임을 되살리는
Rect2(왼쪽, 위, 더할 너비, 더할 높이). - 상대 길이
- Godot의 프레임별 배수. 1.0은 1 ÷ 애니메이션 속도만큼 보임.
예시: 트림된 프레임 하나를 JSON에서 SpriteFrames로
TexturePacker JSON Godot 4 SpriteFrames (.tres)
"run_0": { [sub_resource type="AtlasTexture" …]
"frame": {"x":…,"y":…,"w":18,"h":15}, region = Rect2(x, y, 18, 15), 새 페이지 기준
"spriteSourceSize": {"x":10,"y":10,"w":18,"h":15},
"sourceSize": {"w":40,"h":29} } margin = Rect2(10, 10, 22, 14)
22 = 40 − 18, 14 = 29 − 15
filter_clip = true
이름 run_0 … run_5 → 애니메이션 "run", 6프레임, 각 100ms (JSON에 시간 정보 없음)
"speed": 10.0 (1000 / 100ms) 모든 프레임 "duration": 1.0
Studio에서 run_5를 250ms로 → run_5 "duration": 2.5 (250 / 100)margin이 18 × 15 조각을 40 × 29 프레임의 왼쪽과 위에서 10px 안쪽에 되돌려 놓으므로, Godot는 원래 크기로 프레임을 그리고 잽니다.
TexturePacker 퍼블리시 설정과 Godot에 도착하는 것
| TexturePacker 설정 | 그때 JSON에 들어가는 것 | Godot 4 번들의 결과 |
|---|---|---|
| 데이터 형식 JSON (Hash) 또는 JSON (Array) | 이름을 키로 한 객체 또는 filename이 있는 목록의 frames | 둘 다 읽음. 이름은 확장자 없이 유지 |
| Trim mode Trim | trimmed: true, spriteSourceSize, sourceSize | AtlasTexture margin이 원래 크기를 되살림 |
| Trim mode Crop, flush position | 잘린 크기와 같은 sourceSize | 프레임이 잘린 크기로 도착하며 원래 캔버스는 되찾을 수 없음 |
| Allow rotation 켬 | 돌린 스프라이트에 rotated: true | 돌려진 채로 가져오며 내보내기는 미검증. 회전 없이 다시 패킹 |
| Detect identical sprites | 여러 이름이 한 사각형을 가리킴 | 이름마다 프레임이 유지되고 .tres에서 같은 AtlasTexture를 공유 |
| 피벗 포인트 | 0–1 범위의 pivot {x, y} | 프레임 피벗. 노드 오프셋은 첫 프레임의 피벗 |
| 스프라이트 이름 walk_01, walk_02 … | 이름뿐 | 애니메이션 walk, 자연 순서(2가 10보다 먼저) |
이렇게 작동합니다
- 해시·배열 JSON 모두, 트림된 프레임 포함: spriteSourceSize와 sourceSize가 프레임의 원래 캔버스와 오프셋이 됩니다.
- 이름으로 애니메이션 묶기: walk_01, walk_02 …는 "walk"가 되고 자연 정렬(2가 10보다 앞)을 따르며, 이름 자체는 그대로 둡니다.
- JSON에 피벗이 있으면 쓰고, 없으면 아래 가운데에서 시작해 피벗 도구(P)로 옮깁니다.
- TexturePacker JSON에는 시간이 없어 모든 프레임이 100ms로 시작합니다. 내보내기 전에 프레임별이나 태그별로 실제 길이를 넣으세요.
- 번들 내용: SpriteFrames .tres(AtlasTexture 영역+여백), Nearest 필터와 피벗 오프셋이 설정된 AnimatedSprite2D .tscn, fix_alpha_border를 끈 .png.import.
사용 방법
- PNG와 .json을 함께 넣습니다(JSON의 meta.image가 짝이 되는 이미지를 가리킵니다).
- 가져오기 패널에서 프레임 수, 애니메이션 묶음, 이미지 밖에 있는 프레임을 확인합니다.
- 타임라인에서 이름·태그·시간을 고치고 Enter로 미리 봅니다.
- 패킹·내보내기에서 Godot 4를 골라 내보냅니다. 이 대상은 프레임을 회전하지 않습니다.
- 폴더를 res:// 아래 아무 곳에 복사하고 .tscn을 씬에 끌어다 놓거나, .tres를 직접 만든 AnimatedSprite2D에 지정합니다.
받게 되는 파일
| 파일 | 용도 |
|---|---|
run.tres | SpriteFrames: 태그마다 속도·반복·상대 길이가 있는 애니메이션, AtlasTexture의 region·margin·filter_clip, 피벗과 박스가 든 메타데이터 nerulio. |
run.tscn | 이 리소스를 쓰는 AnimatedSprite2D. Nearest 텍스처 필터, 첫 프레임 피벗을 오프셋으로. |
run.png, run.png.import | 새 페이지와 가져오기 설정: 무손실, 밉맵 없음, Fix Alpha Border 끔. |
README-GODOT.md | 이 번들의 단계 설명. |
Godot 4로 가져오기
- 압축을 풀고 폴더째
res://아래에 복사합니다(예:res://characters/run/)..tres가 상대 경로로 새 PNG를 찾습니다. - 파일시스템 독이 가져오게 둡니다. 함께 온
.png.import가 흐린 픽셀을 정확히 지켜 줍니다. Godot 기본 가져오기는 알파 20 미만 픽셀의 색을 바꿉니다. run.tscn을 씬에 끌어 놓거나, 직접 만든 AnimatedSprite2D의 Sprite Frames 속성에run.tres를 지정합니다.- 스크립트에서
$Hero.play("run")으로 재생하고, 반복하지 않는 애니메이션은animation_finished를 연결합니다. - 다른 곳에서 쓰지 않는다면 예전 TexturePacker PNG와 JSON을 프로젝트에서 지워 같은 그림을 두 번 가져오지 않게 합니다.
결과 확인
- SpriteFrames 패널: 이름 그룹마다 애니메이션 하나, 프레임 수는 JSON과 같음(run_0 … run_5면 6).
- 400%로 확대해 트림된 프레임을 원본과 비교합니다. margin이 트림을 되살렸으므로 크기와 위치가 같아야 합니다.
print($Hero.sprite_frames.get_frame_texture("run", 0).margin)이 그 프레임의 margin Rect2를 출력합니다.
TexturePacker JSON 항목이 Godot에서 가는 곳
| TexturePacker JSON | Studio에서 | Godot 4 번들에서 |
|---|---|---|
| frames 키 또는 filename | 확장자를 뺀 프레임 이름 | 접두사로 애니메이션 이름, 메타데이터에 프레임 항목 |
| frame {x, y, w, h} | 원래 시트에서의 프레임 영역 | 새로 패킹한 페이지의 AtlasTexture region |
| spriteSourceSize, sourceSize | 원래 프레임 캔버스와 오프셋 | AtlasTexture margin으로 원래 크기 복원 |
| pivot | 프레임 피벗(기본은 아래 가운데) | AnimatedSprite2D offset, 모든 피벗은 메타데이터에 |
| rotated: true | 돌아간 채로 가져옴 | 미검증, 회전 없이 다시 패킹 권장 |
| meta.image | JSON과 PNG를 짝지음 | PNG 페이지와 .png.import(무손실, 밉맵 없음) |
| 시간 항목 없음 | 바꾸기 전까지 프레임당 100ms | 애니메이션 speed와 상대 길이 |
문제 해결
| 증상 | 유력한 원인 | 확인 방법 | 해결 |
|---|---|---|---|
| 프레임이 엉뚱한 애니메이션으로 묶임 | 이름이 "이름 + 번호" 규칙을 따르지 않거나 두 그룹이 접두어를 공유 | 가져오기 패널에 묶인 방식이 표시됨 | 내보내기 전에 타임라인에서 프레임 이름이나 태그를 고침 |
| 일부 프레임이 옆으로 누움 | 그 스프라이트가 회전된 채 패킹됨 | JSON에서 "rotated": true 검색 | TexturePacker에서 Allow rotation을 끄고 다시 패킹한 뒤 새 파일 쌍을 넣음 |
| 모든 애니메이션이 같은 속도로 재생됨 | JSON에 시간 정보가 없어 모든 프레임이 100ms로 시작 | 내보내기 전 타임라인의 길이 | 프레임이나 태그마다 실제 길이를 정하고 다시 내보냄 |
| 가져오기 패널에 이미지 밖에 있는 프레임이 있다고 나옴 | JSON이 다른 PNG의 것이거나 패킹 후 PNG 크기가 바뀜 | meta.size와 PNG 크기 비교 | meta.image에 적힌 PNG를 그 JSON과 함께 넣음 |
| 흐린 픽셀(빛, 연기)의 색이 바뀜 | 함께 온 .png.import 대신 Godot 기본값(Fix Alpha Border 켬)으로 가져옴 | PNG의 Import 독 | 함께 온 .png.import를 유지하거나 Fix Alpha Border를 끄고 다시 가져옴 |
다른 방법
| 방법 | 이럴 때 더 낫습니다 |
|---|---|
TexturePacker 자체 Godot 가져오기(Godot SpriteSheet .tpsheet + 플러그인) | 계속 TexturePacker에서 퍼블리시하며 자동으로 다시 가져오고 싶을 때. CodeAndWeb 설명에 따르면 .sprites 폴더에 스프라이트마다 AtlasTexture를, 10fps로 반복하는 애니메이션의 AnimationLibrary를 만듭니다. Godot 4.7.2 시험에서 올바르게 그려졌지만, Godot 기본 PNG 가져오기에서는 궁수 10프레임 중 2프레임에서 흐린 픽셀이 바뀌었습니다. |
| Godot의 Add Frames from Sprite Sheet | 균일한 격자 시트에만 맞습니다. 패킹된 아틀라스는 프레임 크기가 제각각입니다. Godot에서 스프라이트 시트 참고. |
| 원본에서 시작 | .aseprite 파일이 남아 있다면 Aseprite를 Godot로가 TexturePacker JSON에는 없던 태그와 길이를 지켜 줍니다. |
엔진별 내보내기와 검증 방법
"검증됨"은 실제 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 프리셋으로 피합니다.
한계
- JSON의 회전된 스프라이트는 돌려진 채로 가져오며, 내보내기는 미검증입니다.
- TexturePacker의
.tpsheet형식은 읽지 않습니다. 시트를 JSON(Hash 또는 Array)으로 퍼블리시하세요. - 폴리곤으로 패킹된 시트는 사각형으로 읽으며 폴리곤 메시는 무시합니다.
- 격자·섬 인식은 신뢰도가 표시된 미리보기일 뿐이며 적용을 누르기 전에는 아무것도 자르지 않습니다. 모든 선택에는 한 번에 바꿀 수 있는 대안이 있습니다.
- 레이어가 정확히 합성되지 않는 .aseprite 파일(그룹 불투명도 등)은 합쳐서 가져오고, 가져오기 패널에 이유를 표시합니다.
- 가져온 아틀라스에서 회전된 프레임은 회전된 채로 남으며 그 내보내기는 미검증입니다.
- 이미지는 한 변 32,768px(2억 6,800만 픽셀)까지이며 브라우저 메모리에 따라 달라집니다.
버전과 출처
Nerulio의 Godot 4 번들(SpriteFrames .tres, .tscn, .png.import)을 Godot 4.7.2에서 불러와 모든 프레임을 1배와 4배로 그려 원본과 비교했습니다. TexturePacker JSON 읽기는 src/studio/sprite/atlas-data.js입니다. TexturePacker 8.3.0과 Godot 플러그인 v4.3.0은 2026-09-25 비교에서 실행했습니다. Godot 동작은 Godot 4.7 문서를, 플러그인 동작은 CodeAndWeb 설명을 따릅니다.
참고한 공식 문서
자주 묻는 질문
TexturePacker가 회전해서 넣은 프레임은요?
시트에 놓인 그대로(돌아간 채로) 가져오며, 그 프레임의 내보내기는 미검증입니다. TexturePacker에서 회전을 끄고 다시 패킹한 파일을 넣으세요. Godot의 AtlasTexture는 영역을 돌릴 수 없어서 Godot 대상은 회전 패킹을 하지 않습니다.
Godot에서도 프레임 시간이 유지되나요?
Godot 방식으로 유지됩니다. 애니메이션의 speed가 fps이고 프레임 duration은 그에 대한 상대값이라, 12fps에서 250ms는 3.0으로 기록됩니다. 역방향·핑퐁은 프레임 순서로 풀어 씁니다. Godot 3.x는 이 리소스를 읽지 못합니다.
히트박스는 어디로 가나요?
Studio에서 그린 박스와 충돌 폴리곤은 노드가 아니라 SpriteFrames 메타데이터 "nerulio"(sprite_frames.get_meta("nerulio"))에 저장됩니다.
무료인가요? 계정이 필요한가요?
이 페이지의 기능은 모두 무료이며 계정 없이 쓸 수 있습니다. 워터마크나 막혀 있는 내보내기가 없습니다.
스프라이트가 업로드되나요?
아니요. Studio는 이 브라우저 탭 안에서 디코딩·패킹·내보내기를 합니다. 프로젝트는 브라우저(IndexedDB)에 자동 저장되며 .nerulio 파일로 저장할 수 있습니다.
Aseprite나 엔진 플러그인을 설치해야 하나요?
아니요. .aseprite 파일은 브라우저에서 읽고 씁니다. 엔진별 번들에는 그 엔진에 필요한 것이 들어 있습니다(Godot는 가져오기 설정과 씬, Unity와 Godot 타일셋은 작은 편집기 스크립트).