PixiJS @2x 스프라이트시트가 두 배로 커질 때
PixiJS 8에서 @2x 스프라이트시트가 @1x보다 두 배 크게 그려진다면 JSON의 meta.scale이 "1"로 되어 있을 가능성이 큽니다. PixiJS는 파일 이름의 “@2x”가 아니라 meta.scale에서 해상도를 읽기 때문에, 늘어난 픽셀이 그대로 크기가 됩니다. "2"로 되어 있으면 @2x 시트는 @1x와 같은 크기로, 더 촘촘하게 그려집니다.
PixiJS 8은 텍스처 크기를 픽셀 수 ÷ 해상도로 정하고, 스프라이트시트의 해상도는 JSON의 meta.scale에서 가져옵니다. 그래서 JSON에 아직 "scale": "1"이라고 적힌 @2x 시트는 두 배 크기로 그려지고, "2"면 @1x와 같은 크기에 세밀함만 두 배가 됩니다. 실제로 불러온 파일의 sheet.data.meta.scale과 texture.source.resolution을 확인하고, 값을 파일에 맞춘 뒤 게임 코드는 @1x 단위로 두세요. Nerulio는 배율 변형마다 맞는 JSON을 따로 씁니다. PixiJS 8.21에서 @2x로 확인했습니다.
- 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
meta.scale이 크기를 정하는 이유
PixiJS는 픽셀과 단위를 나눕니다. 해상도 2의 80 × 58픽셀 텍스처는 40 × 29단위로, 해상도 1의 40 × 29픽셀 텍스처와 같습니다. 그래서 스프라이트 크기, 위치, 충돌 판정은 그대로이고 화면만 더 세밀해집니다.
스프라이트시트의 해상도는 JSON의 meta.scale에서 읽습니다. @2x 이미지 옆에 @1x JSON을 복사해 두거나 모든 변형에 "1"을 쓰는 패커를 쓰면, PixiJS는 늘어난 픽셀을 늘어난 크기로 읽습니다. 음성 대조 실험에서 @2x JSON을 "1"로 고치자 PixiJS는 40 × 29 프레임을 80 × 58 텍스처로 보고했습니다.
간격은 변형마다 그 변형의 픽셀로 셉니다. Nerulio는 @2x에서도 간격을 2px로 두므로, 6프레임 시험 세트의 @2x 페이지는 76 × 100이 아니라 74 × 96입니다. 그래도 @2x 프레임 하나하나는 @1x 프레임을 최근접 이웃으로 정확히 2배 한 것입니다.
- 해상도(resolution)
- 텍스처 소스의 PixiJS 단위당 픽셀 수. @1x는 1, @2x는 2.
- meta.scale
- PixiJS가 스프라이트시트 해상도를 읽는 JSON 필드. 문자열로 적힘.
- 배율 변형
- 같은 아틀라스를 다른 배율로 패킹한 것. 자기 PNG와 JSON이 있음(run@2x.png, run@2x.json).
40 × 29 프레임 하나의 숫자
파일 meta.scale 픽셀 ÷ 해상도 스프라이트 너비 × 높이
run.json "1" 40 × 29 ÷ 1 40 × 29
run@2x.json "2" 80 × 58 ÷ 2 40 × 29
run@2x.json "1" (틀림) 80 × 58 ÷ 1 80 × 58 ← 두 배 크기
6프레임 세트의 페이지: @1x 38 × 50, @2x 74 × 96 (간격은 2px 그대로)
@2x의 run_0: 저장 36 × 30, 위치 (0, 64), 트림 (20, 20), 캔버스 80 × 58위 세 줄은 2026-09-24 검사에서 PixiJS 8.21이 보고한 값입니다. meta.scale에서 해상도 1과 2를 읽었고, 두 변형 모두 크기 40 × 29와 앵커 (0.5, 1)이 같았으며, 음성 대조에서는 두 배 크기였습니다.
이렇게 작동합니다
- 한 번의 패킹에서 @0.5x·@1x·@2x·@3x·@4x 배율 버전을 만들고, 각각 hero.png, hero@2x.png, hero@0.5x.png처럼 이름 붙은 별도 아틀라스로 씁니다.
- 버전마다 JSON이 따로 있고 meta.scale이 그 배율과 같습니다(hero@2x.json이면 "2"). 손으로 고칠 필요가 없습니다.
- 최근접 보간만 씁니다. 정수 배율은 픽셀을 정확히 복제하므로 @2x 도트도 선명하고, @0.5x는 섞지 않고 픽셀을 골라냅니다.
- animations 맵과 프레임별 anchor가 모든 버전에 들어가며, 여러 페이지로 나뉜 버전은 related_multi_packs로 이어집니다.
- PixiJS 8.21에서 @1x와 @2x 내보내기를 Assets.load로 그대로 불러 확인했습니다. meta.scale에서 해상도 1과 2를 읽었고, @2x 텍스처는 PixiJS 단위로 @1x와 크기·anchor·경계가 같았으며, 각 프레임은 원본을 최근접 2배 한 것과 정확히 같았습니다.
사용 방법
- 프레임, 시트(적용까지), GIF 또는 .aseprite 파일을 넣습니다.
- 패킹·내보내기에서 PixiJS 8을 고르고 배포할 배율 버전(예: @1x, @2x)을 체크합니다.
- PixiJS 8로 내보내면 버전마다 PNG와 JSON 한 쌍이 나옵니다.
- 도트라면 TextureSource.defaultOptions.scaleMode를 'nearest'로 두고, 화면에 맞는 버전을 Assets.load로 불러 스프라이트 폭이 @1x 프레임 폭과 같은지 봅니다.
결과 확인
- 불러온 파일의
sheet.data.meta.scale과sheet.textures.run_0.source.resolution을 출력합니다. @2x면 "2"와 2. new Sprite(sheet.textures.run_0).width가 @1x와 @2x에서 같아야 합니다(이 프레임은 40).- 두 변형을 같은 확대율로 캡처합니다. 배치는 똑같고 @2x의 가장자리만 더 선명해야 합니다.
배율 버전과 PixiJS에서 나와야 할 값
40×29px 프레임 기준. PixiJS 단위는 sprite.width·sprite.height가 돌려주는 값입니다.
| 버전 | 파일 | meta.scale | PixiJS 8에서 |
|---|---|---|---|
| @0.5x | hero@0.5x.png, hero@0.5x.json | "0.5" | 예상: @1x와 거의 같은 크기, 텍셀 절반(미실행) |
| @1x | hero.png, hero.json | "1" | 40×29, PixiJS 8.21에서 불러와 그림 |
| @2x | hero@2x.png, hero@2x.json | "2" | 40×29에 텍셀 2배, PixiJS 8.21에서 확인 |
| "1"이 잘못 적힌 @2x | "1"이라고 적힌 @2x JSON | "1" | 80×58, 두 배로 그려짐(대조 실험) |
| @3x, @4x | hero@3x.png, hero@4x.png와 각 JSON | "3", "4" | 예상 40×29(미실행) |
| 여러 페이지의 @2x | hero-0@2x.png, hero-1@2x.png와 각 JSON | 페이지마다 "2" | related_multi_packs로 연결 |
PixiJS 기본값은 선형 필터입니다. 최근접은 4단계처럼 불러올 때 직접 정합니다.
문제 해결
| 증상 | 유력한 원인 | 확인 방법 | 해결 |
|---|---|---|---|
| @2x 스프라이트가 두 배 크기로 그려짐 | @2x JSON의 meta.scale이 "1" | sheet.data.meta.scale | "2"로 고치거나, JSON이 PNG와 맞도록 배율 변형으로 내보냄 |
| 크기는 맞는데 흐림 | 선형 배율이거나, 고밀도 화면에서 @1x 시트를 늘려 씀 | texture.source.scaleMode와 texture.source.resolution | 도트 그림은 최근접 배율. 해상도 2가 필요한 화면에는 @2x 변형을 불러옴 |
| @2x 프레임이 @1x보다 한 픽셀 어긋남 | 위치나 앵커를 단위가 아니라 픽셀로 정했거나, 트림이 다르게 따로 패킹한 변형 | 두 변형의 앵커와 sprite.width 비교 | 내보낸 0–1 앵커를 유지하고 모든 변형을 한 번에 내보냄 |
| 게임 코드가 모든 스프라이트를 0.5배로 줄임 | 틀린 meta.scale을 피하려던 임시방편 | 코드에서 0.5 배율 검색 | JSON을 고친 뒤 추가 배율을 없앰 |
| @2x 시트에 애니메이션이 없음 | 그 JSON에 animations 맵이 없음. 한 파일에만 쓰는 도구가 있음 | @2x JSON 열어 보기 | Nerulio는 모든 변형의 첫 페이지에 animations를 씀 |
다른 방법
| 방법 | 이럴 때 더 낫습니다 |
|---|---|
| @1x만 배포 | 정수 배율과 최근접 배율로 보여 주는 도트 그림은 @2x 파일이 필요 없습니다. 늘어난 픽셀이 어차피 똑같은 복사본입니다. |
meta.scale을 손으로 고치기 | 다시 내보낼 수 없는 시트 한 장이라면 @2x JSON의 문자열만 "2"로 바꾸세요. |
| 프레임에서 변형 내보내기 | 시트가 여러 장이거나 자주 바뀔 때: @2x 변형을 켜고 PixiJS 스프라이트시트 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는 원본과 동일합니다. |
검증 근거
내보내기: 실제 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)" 프리셋을 쓰세요.
버전과 출처
tools/engine-verify/pixi_scale.py(2026-09-24)가 6프레임 CC0 세트의 @1x·@2x 내보내기를 PixiJS 8.21.0(WebGL)에서 불러왔습니다. meta.scale에서 해상도 1과 2를 읽었고 크기와 앵커가 같았으며, @2x 프레임은 모두 최근접으로 정확히 2배였습니다. @2x JSON의 meta.scale을 "1"로 고치자 그려진 크기가 두 배가 됐습니다. @0.5x, @3x, @4x는 PixiJS에서 불러오지 않았습니다.
참고한 공식 문서
자주 묻는 질문
예전에 만든 @2x 시트가 두 배로 그려지는 이유는?
JSON의 meta.scale이 "1"이기 때문일 가능성이 큽니다(@1x 값을 그대로 복사한 패커가 많습니다). 대조 실험에서 @2x JSON의 meta.scale을 "1"로 바꾸자 PixiJS가 40×29 프레임을 80×58로 보고하고 두 배로 그렸습니다. "2"로 고치거나 여기서 다시 내보내세요.
스프라이트를 0.5배로 줄이면 안 되나요?
하나는 되지만 모든 스프라이트에 해야 하고, @1x·@2x 선택이 게임 코드로 새어 나옵니다. meta.scale이 맞으면 두 파일이 같은 크기로 그려져 코드는 그대로입니다.
PixiJS에서 실제로 돌려 본 배율은?
@1x와 함께 @2x뿐입니다. CC0 6프레임 팩 하나, WebGL, 회전 프레임 포함. @0.5x·@3x·@4x도 같은 방식으로 쓰지만 PixiJS에서 불러 보지는 않았습니다.
@2x 페이지가 @1x의 정확히 두 배가 아닌 이유는?
여백이 모든 버전에서 2px로 같아서 배치가 조금 달라집니다. 프레임 하나하나는 @1x의 정확한 2배입니다.
무료인가요? 계정이 필요한가요?
이 페이지의 기능은 모두 무료이며 계정 없이 쓸 수 있습니다. 워터마크나 막혀 있는 내보내기가 없습니다.
스프라이트가 업로드되나요?
아니요. Studio는 이 브라우저 탭 안에서 디코딩·패킹·내보내기를 합니다. 프로젝트는 브라우저(IndexedDB)에 자동 저장되며 .nerulio 파일로 저장할 수 있습니다.
Aseprite나 엔진 플러그인을 설치해야 하나요?
아니요. .aseprite 파일은 브라우저에서 읽고 씁니다. 엔진별 번들에는 그 엔진에 필요한 것이 들어 있습니다(Godot는 가져오기 설정과 씬, Unity와 Godot 타일셋은 작은 편집기 스크립트).