AI 튜토리얼

pxl로 코드처럼 픽셀 아트, 스프라이트 시트, GIF 만들기

pxl 설치 방법, 간결한 DSL로 픽셀 아트를 정의하는 방법, PNG 스프라이트와 스프라이트 시트를 생성하는 방법, 실시간 브라우저 뷰어에서 변경 사항을 미리 보는 방법, 그리고 변형, 애니메이션, 장면, 조명, AI 지원 워크플로와 같은 고급 기능을 사용하는 방법을 알아보세요.

2026년 10월 15일약 11분 소요

pxl이란?

pxl은 Node.js용 코드 우선 픽셀 아트 도구입니다. 간결한 .px.js 또는 .px.ts 파일로 아트워크를 설명한 다음, 명령줄 인터페이스를 사용해 PNG 스프라이트, JSON 메타데이터가 포함된 스프라이트 시트, 애니메이션 GIF, 픽셀 그리드가 있는 확대 미리보기를 생성할 수 있습니다.

이 프로젝트에는 Node.js 22.18 이상이 필요합니다. 런타임 의존성이 없으며, 복제한 저장소에서 사용할 때 별도의 빌드 단계도 필요하지 않습니다.

브라우저의 라이브 뷰어는 소스 파일을 저장할 때마다 아트워크를 다시 빌드합니다. 편집한 에셋을 작업 단위별로 재생할 수도 있어, 직접 그리거나 AI 에이전트와 작업할 때 제작 과정을 쉽게 살펴볼 수 있습니다.

주요 기능

간결한 팔레트: 한 문자 키에 색상을 할당하고 Pico-8, Sweetie 16, Endesga 32 같은 기본 제공 팔레트를 사용할 수 있습니다.
스프라이트와 변형: 텍스트 그리드 스프라이트를 만들고, 좌우 반전하거나, 자동 외곽선을 추가하고, 회전 또는 뒤집기를 적용하며, 팔레트를 바꾼 변형을 만들 수 있습니다.
그리기 도구: 직사각형, 선, 원, 다각형, 그라디언트, 디더링, 노이즈, 산포 브러시, 타일맵, 기본 제공 픽셀 글꼴을 사용할 수 있습니다.
스프라이트 시트: TexturePacker 스타일의 JSON 메타데이터가 포함된 패킹 이미지를 내보낼 수 있습니다.
장면: 아트워크를 레이어로 구성하고, 그림자와 광원 레이어를 추가하며, 개별 레이어를 PNG 파일로 내보낼 수 있습니다.
애니메이션: 기본 스프라이트 위에 패치로 프레임을 정의하고 스트립, JSON 태그, GIF 파일을 내보낼 수 있습니다.
선택적 조명: 램프, 광원 효과, 노멀 기반 입체 효과를 추가할 수 있습니다.
유용한 진단 정보: 오류에 파일, 줄, 열, 에셋, 레이어, 작업 정보가 포함되며, 해당하는 경우 “혹시 다음을 의미했나요?” 힌트도 표시됩니다.

pxl 설치 및 실행

옵션 1: 저장소 복제

프로젝트를 복제하고 해당 디렉터리로 이동합니다.

git clone https://github.com/crsolver/claude-pxl.git
cd claude-pxl

복제한 저장소에서는 node bin/pxl.js를 통해 CLI를 실행합니다. 포함된 예제 중 하나를 라이브 뷰어에서 바로 열 수 있습니다.

node bin/pxl.js serve examples/shop.px.js

브라우저에서 http://127.0.0.1:4321/을 엽니다. 아트 파일을 저장할 때마다 뷰어가 프로젝트를 다시 빌드합니다.

옵션 2: npx로 실행

저장소를 복제하지 않고도 GitHub 저장소에서 직접 아트 파일을 빌드할 수 있습니다.

npx github:crsolver/claude-pxl build art.px.js

아래 명령에서 pxl은 복제한 저장소의 node bin/pxl.js 또는 npx github:crsolver/claude-pxl을 의미합니다.

첫 번째 코드 스프라이트 만들기

art.px.js라는 파일을 만들고 다음 코드를 추가합니다.

pal({
  k: "#1b1630",
  g: "#8ccf63",
  G: "#4c8a44",
  w: "#fff6e0",
  r: "#e2585e",
  R: "#a63a4c"
})

sprite("slime", { mx: true, outline: "k" }, `
  ....ggg
  ..ggGGg
  .ggGwGg
  gggkwgg
  GGGGGGG`)

sprite("slime_red", {
  base: "slime",
  swap: { g: "r", G: "R" }
})

sheet("chars", ["slime*"], { pad: 1 })

예제 이해하기

pal()은 한 문자 키를 16진수 색상에 매핑합니다. 이렇게 지정한 키는 스프라이트 그리드에서 직접 사용할 수 있습니다.
sprite("slime", ...)은 기본 스프라이트를 선언합니다.
mx: true 옵션은 입력한 스프라이트의 절반을 가로로 반전합니다.
outline: "k"는 k에 할당된 팔레트 색상으로 스프라이트의 외곽선을 자동으로 만듭니다.
두 번째 스프라이트는 base: "slime"을 사용하고 초록색을 빨간색으로 바꿉니다. 따라서 그리드를 복제하지 않고 색상만 변경한 변형을 만들 수 있습니다.
sheet()는 chars라는 이름의 스프라이트 시트를 만듭니다. slime* 패턴은 일치하는 에셋을 포함하며, pad: 1은 1픽셀의 여백을 추가합니다.

에셋 빌드

복제한 저장소에서 다음을 실행합니다.

node bin/pxl.js build art.px.js

예제는 다음과 같은 파일을 생성합니다.

out/sprites/slime.png
out/sprites/slime_red.png
out/chars.png
out/chars.json
out/_preview/*.png

스프라이트 파일에는 원래의 1픽셀 크기로 아트워크가 저장됩니다. chars.png와 chars.json 파일은 스프라이트 시트와 TexturePacker 스타일 메타데이터를 구성합니다. out/_preview/ 디렉터리에는 픽셀 그리드가 표시된 확대 미리보기가 들어 있습니다.

라이브 뷰어 사용

아트 파일용 개발 서버를 시작합니다.

node bin/pxl.js serve art.px.js

기본적으로 뷰어는 4321 포트에서 사용할 수 있습니다. 저장할 때마다 다시 빌드가 실행되고 편집한 에셋이 단계별로 재생됩니다. 출력이 비활성화되지 않은 경우 서버는 빌드 명령과 동일한 out/ 파일도 작성합니다.

다른 포트나 출력 디렉터리를 선택하려면 다음을 사용합니다.

node bin/pxl.js serve art.px.js --port 5000 --out generated

생성된 에셋을 디스크에 저장하지 않고 뷰어를 사용하려면 다음을 실행합니다.

node bin/pxl.js serve art.px.js --no-out

CLI 명령 살펴보기

선택한 에셋 빌드

build 명령은 대상 디렉터리, 선택한 에셋, 출력 배율 및 미리보기에 대한 옵션을 지원합니다:

pxl build <art.px.js> [--out DIR] [--only a,b] [--scale N] [--no-preview]

예를 들어 이름이 지정된 두 에셋만 원본 크기의 네 배로 빌드하려면 다음과 같이 실행합니다:

node bin/pxl.js build art.px.js --only slime,slime_red --scale 4

스프라이트를 텍스트로 검사하기

ascii 명령은 가로 및 세로 눈금자와 함께 에셋을 팔레트 키로 출력합니다. 개별 픽셀의 위치를 찾을 때 유용합니다:

node bin/pxl.js ascii art.px.js slime

프로젝트 정의 나열하기

list를 사용하면 에셋, 그룹, 시트를 소스 위치와 함께 표시할 수 있습니다:

node bin/pxl.js list art.px.js

고급 워크플로 팁

TypeScript 아트 파일 사용하기

아트 프로젝트에서는 .js 또는 .ts를 사용할 수 있습니다. 저장소에는 .px.ts 파일의 편집기 자동 완성을 제공하는 types/pxl.d.ts가 포함되어 있습니다.

아트워크 재사용 및 변형하기

에셋이 공통 구조를 공유한다면 그리드를 반복해서 작성하지 마세요. 기본 스프라이트에서 변형을 만들고, 다른 색 구성표에는 팔레트 교체를 사용하며, 필요에 따라 뒤집기, 회전, 재사용 가능한 _parts 및 stamp를 활용하세요.

결정론적 절차 도구 사용하기

DSL에는 그라디언트, 디더링, 노이즈, 산포 브러시, 타일맵 및 재현 가능한 시드를 사용하는 무작위 그룹이 포함되어 있습니다. 생성된 디테일을 빌드 간에 안정적으로 유지하려는 경우 재현 가능한 무작위성이 특히 유용합니다.

레이어로 장면 구성하기

더 큰 구성을 만들 때는 모든 작업을 하나의 평면 에셋에 배치하기보다 장면과 레이어를 사용하세요. pxl은 그림자와 조명 레이어, 그리고 레이어별 PNG 내보내기를 지원합니다. 전체 API는 reference.md를 참조하세요.

애니메이션과 조명을 선별적으로 추가하기

애니메이션 프레임은 기본 스프라이트 위에 적용되는 패치로 표현할 수 있으므로 유사한 프레임 간 중복을 줄일 수 있습니다. pxl은 이러한 정의를 스트립, JSON 태그 및 애니메이션 GIF로 변환할 수 있습니다. 램프, 발광 및 노멀 기반 입체 효과는 전용 조명 가이드를 따르세요.

AI 에이전트와 pxl 사용하기

이 저장소는 에이전트 스킬로 작동하도록 설계되었습니다. 권장 루프는 아트 파일을 작성하고, 빌드하고, 미리보기를 검사한 다음 소스를 수정하는 것입니다. 라이브 뷰어를 사용하면 이 워크플로를 실시간으로 확인할 수 있습니다.

모든 Claude Code 프로젝트에 스킬을 설치하려면 다음을 실행하세요:

git clone https://github.com/crsolver/claude-pxl.git ~/.claude/skills/pxl-pixel-art

현재 프로젝트에만 설치하려면 다음을 실행하세요:

git clone https://github.com/crsolver/claude-pxl.git .claude/skills/pxl-pixel-art

Codex, Cursor 또는 다른 에이전트에서는 에이전트가 SKILL.md를 참조하도록 하고 CLI 경로를 node <path-to-pxl>/bin/pxl.js로 지정하세요. 브라우저에서 아트가 제작되는 과정을 확인하려면 에이전트에 pxl serve를 시작하도록 요청하세요.

개발 명령

pxl 자체를 수정하려는 경우 개발 종속성을 설치하고 검사를 실행하세요:

npm install
npm run check

개발 종속성에는 TypeScript와 Node.js 타입 정의가 포함되어 있습니다. 저장소 갤러리를 다시 생성하려면 다음을 실행하세요:

node scripts/gallery.ts

결론

pxl은 픽셀 아트를 소스 코드로 다루는 간결한 방법을 제공합니다. 팔레트와 텍스트 그리드 스프라이트로 시작해 PNG 및 스프라이트 시트 에셋으로 빌드하고, 빠른 피드백을 위해 라이브 뷰어를 열어 두세요. 프로젝트가 성장하면 런타임 종속성을 추가하지 않고 재사용 가능한 변형, 그리기 프리미티브, 레이어 장면, 애니메이션, 조명 및 AI 지원 반복 루프를 추가할 수 있습니다.