pixel-mascot

픽셀 마스코트 만들기

마스코트는 CSS 단계 애니메이션이 적용된 픽셀 아트의 하나의 SVG 파일입니다. 여러 상태(idle, happy, sleep, walk, attack…)를 가질 수 있으며, 각 상태는 루트 요소의 클래스로 표현됩니다. <svg class="happy">는 happy 상태를 재생합니다. 수백 개의 <rect>를 직접 편집하지 않고 코드로 마스코트를 제작하세요: 이 스킬의 scripts/ 폴더(<kit>)에는 작은 키트와 작업 예제가 들어 있습니다. 모든 것은 Python 표준 라이브러리로 이루어져 있으며, 설치할 것이 없습니다.

무엇이든 그리기 전에 이 파일 옆에 있는 LESSONS.md를 읽으십시오. 여기에는 첫 번째 마스코트를 만들면서 발생한 문제점, 그 증상, 원인 및 해결 방법이 나열되어 있으며, 이를 건너뛰면 대부분의 문제가 다시 발생할 것입니다.

파일 위치

사용자에게 마스코트를 어디에 보관할지 물어보십시오. 선호하는 경로가 없으면 ~/pixel-mascots/<name>/(Windows의 경우 %USERPROFILE%\pixel-mascots\<name>\)를 사용하십시오.

파일	설명
make_<name>.py	빌더: 모든 변경 사항은 여기서 편집하고 다시 실행합니다.
<name>.svg	빌드 출력물, 마스코트 자체입니다.
<name>_overrides.json	스튜디오에서 사용자가 직접 편집한 내용으로, 빌더가 마지막에 적용합니다.
sheet.png	미리보기, 각 상태의 정지 프레임 하나씩.

<name>은 소문자, 숫자, 하이픈으로 구성됩니다. 사용자의 파일을 절대 <kit>에 넣지 마십시오: <kit>은 설치된 플러그인에 속하며 업데이트 시 교체됩니다.

스크립트 실행

머신에 있는 Python을 사용하십시오: python3(macOS, Linux), python(Windows), 또는 shim이 일반 python을 차단하는 경우 uv run python. 빌더는 키트를 임포트하므로 실행 시 <kit>을 PYTHONPATH에 설정해야 합니다.

PYTHONPATH="<kit>" python3 make_<name>.py <name>.svg

$env:PYTHONPATH = "<kit>"; python make_<name>.py <name>.svg

preview.py와 스튜디오는 PYTHONPATH가 필요하지 않습니다. 스튜디오는 자체적으로 실행하는 빌더에 대해 PYTHONPATH를 설정합니다.

SVG가 충족해야 하는 조건

1. 각 상태마다 하나의 루트 클래스. 각 상태를 .<state> .part{...} 선택자로 스타일링하십시오; 클래스 이름은 사용자의 상태 이름(소문자, 하이픈)입니다. 빌더는 루트에 기본 상태를 작성하므로(s.svg(..., state="idle")), 파일은 브라우저나 <img>에서 자체적으로 애니메이션됩니다; 앱은 루트의 클래스를 변경하여 다른 상태를 표시합니다. 명명된 상태가 없으면 하나를 만드십시오: idle.
2. 모든 색상을 자체 <style> 내의 CSS 클래스에 넣으십시오. CSS 변수(var(--accent,#hex))는 그 안에서만 작동하며, fill= 속성으로는 절대 사용하지 마십시오.
3. 전체 셀을 이동시키는 steps(1) 키프레임(셀 단위 viewBox에서 translateY(-1px)) 또는 불투명도 깜빡임으로 애니메이션하십시오.
4. <title>(대체 텍스트)을 포함하고 <script>, on…=, 외부 이미지, 폰트 또는 링크가 없어야 어디서나 안전하게 표시할 수 있습니다.
5. 루트에 width/height로 그려진 크기를 설정하십시오. 그리드의 정수 배수: 32셀에 128px(셀당 4px), 20셀에 80px.
6. 사용자가 달리 명시하지 않는 한 축소된 움직임을 존중하십시오: @media (prefers-reduced-motion:reduce){*{animation:none!important}}.

작업 흐름

1. 마스코트가 무엇인지, 그 상태, 그리고 3~5가지 정체성 특징을 확정하십시오. 128px에서 인식 가능하게 만드는 요소가 무엇인지 묻고, 그것들을 정확히 과장하고 나머지는 모두 버리십시오. 어떤 상태가 필요한지 묻고; 답변이 없으면 유휴 루프 하나를 만드십시오. 사용자의 아이디어가 결정하며, 여기의 예제가 아닙니다. 사용자가 다른 아티스트의 그림을 공유하면 방향 참고(비율, 윤곽선 스타일, 특징 그리는 방식)로만 사용하십시오: 절대 픽셀을 복사하지 말고, 공유되거나 게시되는 빌드에 저작권이 있는 캐릭터를 절대 넣지 마십시오.

2. 다음 표에서 유형을 찾으십시오. 이 표는 어떤 부분으로 나눌지(각 부분은 자체적으로 애니메이션됨)와 2차 모션을 가질 수 있는 것이 무엇인지 알려줍니다. 2차 모션은 마스코트가 단순히 튀는 스티커처럼 느껴지지 않고 살아있는 것처럼 만듭니다.

   유형	일반적인 정체성 특징	부분(뒤에서 앞으로)	2차 모션
   인간형 캐릭터	머리 모양과 색상, 눈, 하나의 액세서리, 의상, 손에 든 물건	hair-back, body, head (얼굴, 앞머리, 앞머리 가닥), prop	머리 끄덕임/고개짓, 머리카락 후행, 소품 흔들림
   동물	귀, 무늬, 꼬리, 주둥이, 눈 색상	tail, body, ears (머리에 중첩), head	귀 휘날림, 꼬리 흔들림, 머리 기울임
   사물 (램프, 머그잔, 식물, 로봇 청소기)	실루엣, 하나의 시그니처 디테일	back (케이블, 받침대), body, face (그 위에 그려진 얼굴), moving bits	증기 또는 나뭇잎 흔들림, 불빛 깜빡임, 바퀴 회전
   생명체 / 블롭 / 로봇	실루엣, 하나의 독특한 특징(뿔, 안테나, 바이저, 발광)	back, body, head, appendage	압축 및 신축, 안테나 흔들림, 발광 깜빡임

   얼굴이 없는 마스코트도 읽을 수 있는 상태가 필요합니다: 표정 대신 자세, 효과, 속도를 변경하십시오.

3. 캔버스를 선택하십시오. 특징이 적고 단순한 형태는 20×20; 여러 특징이나 표정을 지어야 하는 얼굴이 있는 것은 32×32. 캐릭터의 경우 가슴이나 앉는 부분에서 자르십시오: 얼굴과 정체성 특징이 다리보다 더 공간을 필요로 합니다. 셀당 4px로 그리십시오.

4. 템플릿을 복사하십시오. <kit>/example_mascot.py(세 가지 상태를 가진 고양이 Miso)를 마스코트 폴더의 make_<name>.py로 복사하고, NAME을 설정한 후 도형과 상태를 교체하십시오. 빌더를 유지하십시오: SVG는 빌드 출력물입니다. 템플릿의 마지막 단계인 apply_overrides(...)를 유지하십시오: 이것은 스튜디오(10단계)에서 사용자의 손편집을 적용하므로, 재빌드 시 편집 내용이 손실되지 않습니다.

5. 뒤에서 앞으로 그리십시오. 각 부분은 독립적으로 움직이는 사물 하나당 하나씩입니다. 부속물은 그것이 부착된 것 안에 중첩시키십시오(머리 안에 귀), 그래야 그 부분의 움직임을 따르면서도 자체적으로 움직일 수 있습니다. 키트 도구: rect, ellipse, polygon (귀, 지느러미, 뿔), path (꼬리, 케이블, 줄기), line, zigzag_bottom (머리카락 또는 프린지 가장자리), paint(..., only=...) (기존 도형 위에 세부 그리기), shade_edges (그림자 및 가장자리). 마지막에 s.outline()을 한 번 호출하여 모든 부분이 자체 윤곽선을 가지도록 하십시오. 머리카락이 있는 캐릭터의 경우 LESSONS.md의 "Characters with hair"를 따르십시오.

6. 상태별로 하나의 얼굴(또는 자세), 불투명도 규칙으로 전환되는 그룹으로: 기본값은 f-open, 각 상태에 맞는 추가 그룹. 반응은 색상뿐만 아니라 모양이 다를 때 가장 잘 읽힙니다: 감은 ^ ^ 눈, 반쯤 감은 눈, 열린 입, 그림자 띠. 앞머리가 있는 캐릭터에 그려진 얼굴은 머리카락 셀을 건너뜁니다.

   • 각 상태를 캐릭터에 맞추십시오. 상태가 어울리지 않으면 물어보고, 캐릭터 자신의 이야기에서 순간을 제안하십시오: 시그니처 제스처나 장면. 큰 실루엣 변화는 128px에서 읽히고, 작은 세부 사항(2픽셀 보석, 열리고 닫히는 입)은 읽히지 않습니다.
   • 상태는 얼굴뿐만 아니라 전체 부분을 교체할 수 있습니다: 액세서리 착용/미착용, 수면을 위해 모자를 내림. 교체 가능한 각 조각을 자체 부분으로 만들고 .<state> .part{opacity:…}로 숨기거나 표시하십시오. 모든 규칙을 상태로 범위를 지정하여 다른 상태가 자신의 부분을 유지하도록 하십시오.
   • 사용자가 확신이 없으면 하나를 주장하지 말고 대안을 만드십시오: 빌더가 변형 이름을 인수로 받아 각각 자체 파일로 빌드하고 나란히 보여주도록 하십시오. 사용자가 마음에 들어한 변형을 유지하십시오: 되돌리기는 하나의 인수여야 합니다.

7. 효과는 s.fx(name, cls, frames) 사용: 반짝임, 스피드 라인, Z, 흔들림 표시, 땀방울. 프레임은 s1, s2…가 되어 동기화되지 않고 애니메이션됩니다.

8. 모션: steps(1) 키프레임과 전체 셀 이동(픽셀 아트는 미끄러지듯이 아닌 단계적으로 움직여야 함). 전체 도형은 .rig 그룹 안에 있어 튀거나 흔들리고, 그 위에:

   • 머리는 자체적으로 끄덕이거나, 기울이거나, 고개짓합니다(최대 2셀);
   • 부속물(머리카락, 귀, 꼬리, 안테나)은 최대 1/4 주기 늦게 따라가고, 1/2 주기는 반대편에 위치해 잔상으로 읽힙니다;
   • 소품과 움직이는 부분은 약간 비트를 벗어나 실행됩니다. 유휴 루프는 느리고 작습니다: 호흡, 깜빡임, 꼬리.

9. 빌드하고 살펴보기 전에 아무에게도 보여주지 마십시오("스크립트 실행"의 명령어 참조):

   PYTHONPATH="<kit>" python3 make_<name>.py <name>.svg
   python3 <kit>/preview.py <name>.svg sheet.png
   

   그런 다음 sheet.png를 읽으십시오: 왼쪽에서 오른쪽으로 각 상태당 하나의 정지 프레임. 미리보기는 정지 자세만 표시합니다. 모션을 보려면 스튜디오를 백그라운드에서 시작하고 브라우저(내장 브라우저 창이 있다면 거기)에서 http://127.0.0.1:8765/를 여십시오:

   python3 <kit>/studio/server.py --svg <name>.svg --build make_<name>.py
   

   각 상태가 자체 프레임에서 애니메이션되는 것을 보여줍니다. --states a,b는 상태를 선택하고 순서를 지정합니다(기본값: CSS가 사용하는 모든 상태, 처음 나타나는 순서); --port는 포트를 변경합니다. 사용자는 스크린샷으로 검토하고 종종 빨간색으로 문제를 표시합니다: 표시를 자신이 아는 특징(눈 라인, 입)의 셀과 정렬한 다음 그에 따라 다시 그리십시오. 가시적인 변화가 없어야 하는 리팩터링 후에는 이전 버전과 새 버전을 빌드하고 파일을 바이트 단위로 비교하십시오(cmp 또는 fc /b).

10. 수동 편집. 사용자가 직접 픽셀을 수정하려면 스튜디오의 /editor.html로 보내십시오: 상태별로 페인트, 지우기, 색상 선택, 실행 취소, 저장( <name>_overrides.json에 기록하고 재빌드) 가능. 각 픽셀은 특정 부분에 속하며 그 부분과 함께 움직이고, 편집기는 어떤 부분과 어떤 상태가 그 픽셀을 표시하는지 알려줍니다. 빌더가 없는 마스코트도 작동합니다(--build 생략): 스튜디오는 SVG 옆에 <name>_studio/에 수정되지 않은 복사본과 편집 내용을 보관하고 결과를 SVG에 씁니다. 사용자가 편집한 후, 다른 것을 변경하기 전에 오버라이드 파일과 재빌드된 미리보기를 읽고, 편집이 우발적으로 보이는 경우(나머지에서 멀리 떨어진 외로운 픽셀) 말하십시오.

11. 인계: SVG의 위치, 기본적으로 재생되는 상태, 다른 상태를 표시하는 방법(루트의 클래스 설정; <img>는 불가능하므로 상태를 전환하는 앱은 SVG를 인라인으로 포함하거나 <object> 또는 <iframe>에 로드)을 알려주십시오.

profile.json (마스코트를 표시하는 앱용)

앱은 루트 클래스 이상이 필요할 수 있습니다: 루트의 CSS 변수, 추가 클래스, 고정 상태 레이블. <kit>의 preview.py 옆에 배치된 profile.json은 미리보기와 스튜디오에 정보를 제공합니다. 모든 키는 선택 사항입니다:

{
  "states": [{ "class": "happy", "name": "happy", "label": "happy · on success", "style": "--speed:.5s" }],
  "rootClass": "always-animate",
  "swatches": { "var": "--accent", "label": "accent", "colors": ["#8FA8E8", "#ED93B1"] },
  "workdir": "~/my-app/studio"
}

states는 순서, 버튼 이름, 캡션 및 상태별 루트 스타일을 고정합니다; rootClass는 모든 프레임의 루트에 추가됩니다; swatches는 CSS 변수를 설정하는 색상 버튼을 추가합니다; workdir은 빌더가 없는 마스코트의 경우 <name>_studio/를 대체합니다. 이 플러그인은 어떤 것도 제공하지 않습니다.

이 스킬의 파일

파일	설명
LESSONS.md	효과가 있었던 것과 없었던 것, 원인 및 해결 방법. 먼저 읽으십시오.
scripts/pixelkit.py	도형(rect, ellipse, polygon, path, line), 부분, 음영, 부분별 윤곽선, SVG 출력.
scripts/example_mascot.py	Miso: idle, happy, sleep 상태를 가진 32×32 고양이; 복사할 템플릿.
scripts/preview.py	PNG 시트, 상태당 하나의 정지 프레임, 표준 라이브러리만 사용.
scripts/pixel_overrides.py	완성된 SVG에 손편집을 적용; 빌더가 마지막에 호출.
scripts/studio/	server.py + site/: 모든 상태 애니메이션 및 픽셀 편집기, 모든 마스코트 지원. 로컬 전용(127.0.0.1).