히트박스 편집기 · 프레임별 히트·허트 박스
공격 프레임에 히트·허트·상호작용·사용자 박스를 그리고, 태그를 따라 복사하고, 프레임마다 미세 조정하세요. 같은 박스는 모든 프레임에서 같은 id를 가져 엔진이 추적할 수 있습니다.
히트박스(피해를 주는 영역)와 허트박스(맞을 수 있는 영역)는 게임 코드가 검사하는 프레임별 도형이며 그림의 일부가 아닙니다. Nerulio에서는 프레임마다 hit, hurt, interact나 원하는 이름의 사각형·원·폴리곤 박스를 그리고, 박스 하나를 같은 id로 태그 전체에 복사하고, 프레임마다 미세 조정할 수 있습니다. 모든 박스는 Godot 번들의 메타데이터와 일반 JSON으로, 사각형은 Aseprite 슬라이스로도 내보냅니다. 엔진 노드나 콜라이더는 만들어지지 않으므로 Area2D 도형, Unity 콜라이더, Phaser 바디는 이 데이터로 직접 구성합니다.
- 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
박스는 프레임에 속하고, 엔진은 데이터로 만든다
액션 게임은 애니메이션에 따라 박스를 켜고 끕니다. 공격의 히트박스는 유효 프레임에만 있고, 허트박스는 매 프레임 몸을 따라갑니다. 그래서 박스는 스프라이트가 아니라 프레임에 속하고, 같은 논리적 박스는 프레임이 바뀌어도 하나의 정체성을 가져야 합니다. Nerulio의 박스는 id, 유형, 프레임 캔버스 픽셀(원점 왼쪽 위, y는 아래) 단위의 도형을 가지며, 태그 범위로 그리거나 복사하면 id가 유지돼 코드가 칼 박스를 프레임마다 추적할 수 있습니다.
엔진은 이미지에서 박스를 읽지 않습니다. Godot는 CollisionShape2D나 CollisionPolygon2D 자식을 가진 Area2D 노드로 겹침을 감지하고, Unity는 로컬 단위의 크기와 오프셋을 가진 BoxCollider2D 같은 Collider2D 컴포넌트를 쓰며, Phaser Arcade 바디는 setSize, setOffset, setCircle로 크기를 정하고 아니면 프레임 크기를 씁니다. 세 엔진 모두 프레임마다 도형을 코드나 애니메이션 트랙으로 직접 바꿔야 합니다. 내보내기는 숫자를 줄 뿐, 그런 노드나 컴포넌트를 만들지 않습니다.
박스 좌표는 프레임 캔버스 기준입니다. 오브젝트에 놓으려면 피벗을 빼세요. 오프셋이 −피벗인 Godot 씬에서 프레임의 (x, y)에 있는 박스는 노드 공간의 (x − 피벗 x, y − 피벗 y)에 있습니다. Unity는 y가 위로 가고 단위가 유닛이므로 Pixels Per Unit(Unity 내보내기에서는 100)으로 나눕니다.
- 히트박스
- 공격 프레임에서 피해를 주는 영역.
- 허트박스
- 몸에서 맞을 수 있는 영역.
- 박스 id
- 박스를 복사한 모든 프레임에서 같아서, 코드가 박스 하나를 따라갈 수 있음.
- 프레임 캔버스 픽셀
- 프레임 전체 캔버스의 왼쪽 위 모서리부터의 좌표, y는 아래 방향.
예시: 히트박스 하나를 Godot와 Unity에 놓기
프레임 캔버스 48 × 64, 피벗 (24, 64). attack 4~6번 프레임에 x 34, y 30, 16 × 12px 히트 박스.
Nerulio(프레임 캔버스, y 아래) x 34, y 30, w 16, h 12
피벗 기준 왼쪽 34 − 24 = 10, 위 30 − 64 = −34
Godot 노드 공간(y 아래) 사각형 10, −34, 16 × 12, 중심 (18, −28)
Unity(y 위, 유닛당 100px) 중심 ((34 + 8 − 24) ÷ 100, (64 − (30 + 6)) ÷ 100) = (0.18, 0.28)
크기 (0.16, 0.12)
Godot 메타데이터 get_meta("nerulio")["frames"]["attack_004"]["boxes"]
[{"id": …, "type": "hit", "shape": "rect", "x": 34, "y": 30, "w": 16, "h": 12}]원은 cx, cy, r로, 폴리곤은 점 목록으로 같은 픽셀 단위로 저장됩니다. 공격 박스가 아니라 단단한 충돌 윤곽이 필요하면 충돌 폴리곤 생성기를 보세요.
박스가 들어가는 내보내기
| 대상 | 내보내기에 든 박스 | 엔진에서 만들 것 |
|---|---|---|
| Godot 4 | 모든 박스(사각형·원·폴리곤)를 id·유형과 함께 프레임별로 SpriteFrames metadata/nerulio에 | CollisionShape2D나 CollisionPolygon2D 자식을 가진 Area2D, 스크립트로 프레임마다 이동(메타데이터는 Godot 4.7.2에서 다시 읽어 확인) |
| 일반 JSON | 프레임별 모든 박스, 피벗, 충돌 폴리곤 | 어느 엔진이든 frames[key].boxes를 읽기 |
| .aseprite, Aseprite JSON | 사각형만: 박스 유형·순번마다 슬라이스 하나, 박스가 바뀌는 프레임에 키. 원과 폴리곤은 빠짐 | Aseprite에서 슬라이스로 보임(Aseprite 1.3.18에서 확인). JSON을 읽는 쪽은 meta.slices |
| Unity 6 | 없음. 내보내기 안내에 표시됨 | 일반 JSON을 읽는 직접 만든 스크립트로 콜라이더 구성 |
| Phaser, PixiJS, LÖVE, Spine, Starling, Defold, GameMaker, CSS | 없음 | 아틀라스 옆에 일반 JSON을 함께 불러오기 |
이렇게 작동합니다
- 정수 픽셀에 맞춰지는 사각형(B), 원(C), 폴리곤(Q) 박스.
- 히트·허트·상호작용·사용자 이름 유형과 유형별 색.
- 범위: 한 프레임, 선택, 태그 전체, 전체 프레임. Alt+B는 다음 프레임으로 복사합니다.
- 프레임 캔버스를 벗어난 박스도 표시해 유지하며, Aseprite 슬라이스·Godot 번들·일반 JSON으로 내보냅니다.
사용 방법
- 스프라이트를 넣고 가져오기를 적용합니다.
- 박스 유형과 범위를 고르고 프레임 위를 드래그합니다.
- 애니메이션을 넘기며 프레임마다 조정합니다(화살표 1px, Shift 10px).
- 내보내면 박스가 프레임과 함께 전달됩니다.
결과 확인
- , 와 . 로 공격을 넘기며 프레임마다 박스를 봅니다. 프레임 캔버스 밖으로 나간 박스도 유지되고 표시됩니다.
- Godot로 내보낸 뒤
print($Hero.sprite_frames.get_meta("nerulio")["frames"].keys())로 프레임 키를 보고, 각 항목의boxes에 박스가 있는지 확인합니다. - .aseprite로 내보낸 뒤 Aseprite에서 엽니다. 사각형 박스 유형마다 슬라이스가 있고, 박스가 움직이는 프레임에서 키가 바뀝니다.
문제 해결
| 증상 | 유력한 원인 | 확인 방법 | 해결 |
|---|---|---|---|
| Aseprite에 원이나 폴리곤 박스가 없음 | Aseprite 슬라이스는 사각형이라 .aseprite 내보내기가 다른 도형을 건너뛰고 이름을 알려 줌 | 내보내기 메시지에 건너뛴 박스가 나옴 | Aseprite까지 가야 하는 박스는 사각형으로 그리거나, 원·폴리곤은 일반 JSON에서 읽기 |
| 엔진에서 박스 위치가 틀림 | 박스 좌표는 피벗이 아니라 프레임 캔버스의 왼쪽 위 모서리에서 시작함 | 위 예시와 박스 하나를 비교 | 피벗을 빼기. Unity라면 y를 뒤집고 Pixels Per Unit으로도 나누기 |
| 박스가 있으면 안 되는 프레임에 나옴 | 범위를 태그나 전체 프레임으로 두고 그리거나 복사함 | 프레임을 넘겨 보면 같은 id가 모두 있음 | 그 프레임에서 지우거나, 범위를 이 프레임으로 두고 다시 그리기 |
| Unity로 가져온 결과에 박스가 없음 | Unity 내보내기는 스프라이트 사각형, 피벗, 클립만 씀 | 내보내기 안내: 히트박스를 넣을 Unity 스프라이트 필드가 없음 | 일반 JSON도 내보내 그걸로 콜라이더 만들기 |
다른 방법
| 방법 | 이럴 때 더 낫습니다 |
|---|---|
| 엔진에서 도형 그리기(Godot CollisionShape2D, Unity BoxCollider2D, Phaser 바디 setSize·setOffset) | 프레임마다 바뀌지 않는 박스가 한두 개일 때. |
| Aseprite의 슬라이스 | 그림 옆에 사각형 박스를 그릴 때. Nerulio는 이름 있는 슬라이스(hit, hurt …)를 박스로 가져오고 다시 씁니다. |
엔진별 내보내기와 검증 방법
"검증됨"은 실제 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 프리셋으로 피합니다.
한계
- 엔진 노드, 콜라이더, 물리 바디는 만들지 않습니다. 내보내기에는 데이터만 들어갑니다.
- Aseprite 형식에는 사각형 박스만 들어갑니다.
- 박스 좌표는 프레임 캔버스의 정수 픽셀입니다.
- 격자·섬 인식은 신뢰도가 표시된 미리보기일 뿐이며 적용을 누르기 전에는 아무것도 자르지 않습니다. 모든 선택에는 한 번에 바꿀 수 있는 대안이 있습니다.
- 레이어가 정확히 합성되지 않는 .aseprite 파일(그룹 불투명도 등)은 합쳐서 가져오고, 가져오기 패널에 이유를 표시합니다.
- 가져온 아틀라스에서 회전된 프레임은 회전된 채로 남으며 그 내보내기는 미검증입니다.
- 이미지는 한 변 32,768px(2억 6,800만 픽셀)까지이며 브라우저 메모리에 따라 달라집니다.
버전과 출처
Godot 번들의 박스는 Godot 4.7.2가, 사각형 슬라이스는 Aseprite 1.3.18이 다시 읽었습니다(프레임 캔버스 밖으로 나간 박스 포함). 노드와 컴포넌트 이름은 Godot 4.7, Unity 6, Phaser 문서를 따릅니다.
참고한 공식 문서
자주 묻는 질문
공격 전체에 박스 하나를 그릴 수 있나요?
네. 범위를 태그로 두면 한 번의 드래그로 그 태그의 모든 프레임에 같은 박스(같은 id)가 생기고, 옮기면 한 번의 되돌리기 단위로 모두 옮겨집니다.
어떤 형식에 박스가 들어가나요?
모든 박스는 Godot 번들의 메타데이터와 일반 JSON에 들어갑니다. .aseprite와 Aseprite JSON에는 사각형만 슬라이스로 들어가고, Unity에는 박스가 들어가지 않습니다. Godot 번들의 박스는 Godot 4.7.2에서 불러와 확인했습니다.
무료인가요? 계정이 필요한가요?
이 페이지의 기능은 모두 무료이며 계정 없이 쓸 수 있습니다. 워터마크나 막혀 있는 내보내기가 없습니다.
스프라이트가 업로드되나요?
아니요. Studio는 이 브라우저 탭 안에서 디코딩·패킹·내보내기를 합니다. 프로젝트는 브라우저(IndexedDB)에 자동 저장되며 .nerulio 파일로 저장할 수 있습니다.
Aseprite나 엔진 플러그인을 설치해야 하나요?
아니요. .aseprite 파일은 브라우저에서 읽고 씁니다. 엔진별 번들에는 그 엔진에 필요한 것이 들어 있습니다(Godot는 가져오기 설정과 씬, Unity와 Godot 타일셋은 작은 편집기 스크립트).