spright

간단한 시트 패킹

spright.conf 같은 입력 정의 파일에 최대 너비/높이, power-of-two 같은 시트 제약과 출력 파일명, 템플릿을 지정하고 glob으로 이미지 위치를 잡으면, 시트 이미지(예: spright0.png)와 출력 설명 파일(spright.json)이 생성됩니다. Phaser 등 게임 엔진용 템플릿이 기본 제공되며, 별도 템플릿도 쉽게 작성할 수 있습니다.

고급 정의 및 자동 완성

그리드 기반 다중 스프라이트 입력, atlas 기반 비정렬 입력, 파일 시퀀스 입력(예: OrcAttack/Frame{01-04}.png) 등을 정의할 수 있습니다. -c(또는 –mode complete)로 실행하면 그리드의 행/열, atlas의 sprite rect 등 명시되지 않은 정보가 입력 정의에 자동으로 채워지며, 이후 사용자가 ID, 피벗 포인트 등을 직접 추가할 수 있습니다.

주석·태그·데이터

스프라이트에 ID, 태그(예: anim 그룹), 사용자 정의 데이터(data key/value)를 부여할 수 있어 애니메이션 단위 묶음이나 게임 특화 속성을 표현할 수 있습니다. trim, trim-channel, trim-threshold, trim-margin, crop, crop-pivot, extrude, min-size, divisible-size, common-size, align, align-pivot 등을 통해 트리밍과 패딩, 정렬을 세밀하게 제어합니다.

시트 배치와 패킹 옵션

sheet, pack(binpack/compact/rows/columns/single/origin/layers/keep), width/height/max-width/max-height, power-of-two, square, divisible-width, allow-rotate, padding, duplicates(keep/share/drop) 등 시트 단위 옵션으로 패킹 방식과 제약을 설정합니다. output, debug, maps, alpha(keep/opaque/clear/bleed/premultiply/colorkey) 같은 출력 옵션으로 결과 텍스처의 형태와 채널 처리를 지정할 수 있습니다.

출력 설명과 템플릿 엔진

기본적으로 스프라이트 정보를 담은 spright.json이 생성되며, 이는 중간 결과물로 사용됩니다. -t/–template과 -o/–output으로 inja 템플릿 엔진을 사용해 C++, CSS, Cocos2d-x, Phaser 3/2, PixiJS 등 게임 엔진이 소비하는 형태로 변환할 수 있습니다. inja 기본 함수 외에 ceil, floor, makeId, removeExtension, removeDirectories, joinPaths, base64 함수가 추가로 제공됩니다.

설치 및 기본 사용

Windows에서는 다음 패키지 매니저로 설치할 수 있습니다.

• winget install spright
• choco install spright

Linux/macOS에서는 릴리스 페이지의 사전 빌드 패키지, macOS의 경우 Homebrew(houmain/tap, brew install –HEAD spright), Arch Linux에서는 AUR의 spright-git 패키지를 사용할 수 있습니다.

기본 사용 흐름은 다음과 같습니다.

1. spright.conf에 시트/출력 옵션과 glob 또는 input 항목으로 입력 이미지를 정의합니다.
2. 터미널에서 spright를 실행하면 정의대로 시트 이미지와 spright.json이 생성됩니다.
3. 정의를 자동 채우려면 spright -c로 complete 모드를 실행해 누락된 sprite, rect 등을 보완합니다.
4. 게임 엔진용 결과를 만들려면 spright -t phaser.inja -o output.json처럼 템플릿을 지정해 출력 설명을 변환합니다.

–input/–output에 stdin 또는 stdout을 전달해 콘솔 리다이렉션을 사용할 수도 있습니다.

활용 예시

• 그리드 규칙이 있는 시트(예: 32×32 데코레이션, 16×16 적 스프라이트)를 정의해 각 셀을 별도 스프라이트로 시트에 패킹할 때.
• 애니메이션 프레임 시퀀스(예: OrcAttack/Frame01~04)를 하나의 입력 시퀀스로 묶어 한 시트에 배치할 때.
• atlas 모드로 비정렬 다중 스프라이트가 포함된 misc_scenery.png에서 각 스프라이트의 rect를 자동 추정해 정리할 때.
• 애니메이션 그룹이나 게임별 속성을 tag로 부여해, 템플릿 엔진을 통해 Phaser, PixiJS, C++ 등 엔진이 바로 사용하는 파일로 변환할 때.

제한 및 라이선스

spright 본체는 GNU GPLv3으로 배포되며 어떠한 보증도 제공되지 않습니다. README에 포함된 샘플 이미지 파일은 OpenGameArt에서 CC0으로 배포된 자료를 가공한 것입니다. 또한 max-sprites 정의(기본 1000)를 통해 잘못된 입력에서 편집기가 응답하지 않는 상황을 방지합니다.