Reference

에셋 패키저

PNG 폴더 하나, 또는 라벨이 붙은 시트 한 장을 유효한 toonstrip 에셋 팩으로 변환합니다.

팩을 직접 작성하려면 pack.json과 캐릭터별 매니페스트, 스프라이트 시트 사각형 좌표, 그리고 포즈마다 얼굴/몸통 소켓을 일일이 작성해야 합니다. @toonstrip/asset-packager는 바로 이 부분을 대신합니다. 완성된 그림을 넣으면 검증하고, 시트로 묶고, 접합부를 계산해서 팩을 작성해 줍니다.

오프라인으로, 결정적으로 동작합니다. 모델 호출도 네트워크 접속도 없이 PNG만 소비합니다. 이미지 모델에서 나온 것이든, Procreate나 Aseprite에서 그린 것이든 상관없습니다. toonstrip는 여전히 아트를 생성하지 않으며(FAQ 참고), 이 도구는 그림이 이미 준비된 이후 단계입니다.

npm install -D @toonstrip/asset-packager

전체 흐름

# 1. scaffold a source pack
npx -p @toonstrip/asset-packager toonstrip-pack init ./my-source --name my-pack

# 2. draw or generate the poses into ./my-source/characters/<id>/, then check them
npx -p @toonstrip/asset-packager toonstrip-pack validate ./my-source

# 3. build, and look at the join preview before shipping
npx -p @toonstrip/asset-packager toonstrip-pack build ./my-source --out ./my-pack --preview joins.png

# 4. the output is a normal pack
npx -p @toonstrip/cli toonstrip pack validate ./my-pack
npx -p @toonstrip/cli toonstrip render strip.json --out strip.png --pack ./my-pack

--force는 오류가 있어도 강제로 빌드합니다. 오류 내용을 읽는 대신 깨진 팩을 직접 눈으로 보고 싶을 때 사용하세요.

Tip

toonstrip-pack(패키저, 소스를 입력받음)과 toonstrip(CLI, 팩을 출력함)은 서로 다른 명령입니다. 위 4단계는 첫 번째 명령의 결과물을 두 번째 명령으로 검증하는, 독립적인 확인 절차입니다.

두 가지 입력 방식

포즈당 PNG 한 장

my-source/
  source.json                      # name, version, license, spec overrides
  characters/<id>/
    face-NEUTRAL.png               # required
    torso-NEUTRAL.png              # required
    face-HAPPY.png
    torso-WAVE.png
    face-SAD@0.5-2.png             # optional intensity and variant
  backdrops/<id>.png

파일명은 <kind>-<EMOTION>[@<intensity>][-<variant>].png 형식입니다. kind는 face 또는 torso이고, EMOTION은 아홉 개의 얼굴 이름(NEUTRAL, HAPPY, COY, BORED, SCARED, SAD, ANGRY, SHOUT, LAUGH) 또는 아홉 개의 몸통 이름(NEUTRAL, WAVE, POINTOTHER, POINTSELF, DOUBLEPOINT, SHRUG, 3QRWALK, SIDEWALK, 3QFWALK) 중 하나입니다. 대소문자를 구분하며, 디렉터리 안에서 인식되지 않는 파일은 거부되지 않고 그냥 무시되므로 참고용 스케치를 아트와 함께 둘 수 있습니다.

모든 부품은 정사각형에 배경이 투명한 PNG로, 파일 하나에 포즈 하나여야 하며 최소 256×256, 가급적 1024×1024를 권장합니다. 얼굴은 짧은 목 부분까지 포함한 머리로, 접합부에서 끝납니다. 몸통은 어깨부터 허리까지이며 목선이 위쪽 끝에 있고 아랫부분은 캔버스 밖으로 이어집니다. 상세 규칙은 docs/asset-image-spec.md에 있습니다.

시트 한 장에 여러 에셋

이미지 모델로 아트를 만들 때는 포즈마다 파일을 따로 두는 대신 한 번에 그리드로 생성하세요. 그러면 셀 사이에서 정체성이 흔들리지 않고, 패키저가 캐릭터의 NEUTRAL 셀을 기준으로 나머지 포즈를 등록합니다. 배경도 방식은 같습니다. 이미지 한 장에 여러 장면을 담습니다.

# a reference sheet to prompt with; also prints the source.json fragment and a prompt
npx -p @toonstrip/asset-packager toonstrip-pack template --out ref.png
npx -p @toonstrip/asset-packager toonstrip-pack template --out scenes.png --kind backdrop --ids hall,cellar,attic --columns 2

그리드 형태는 자유롭게 정할 수 있습니다. 셀 이름은 source.json에서 지정합니다.

{
  "characters": [
    {
      "id": "pim",
      "sheet": {
        "file": "characters/pim/sheet.png",
        "layout": [
          ["face-NEUTRAL", "face-HAPPY"],
          ["torso-NEUTRAL", "torso-WAVE"]
        ],
        "labelBand": 0.1
      }
    }
  ],
  "backdropSheets": [
    { "file": "backdrops/interiors.png", "ids": ["hall", "cellar", "attic", "kitchen"], "columns": 2 }
  ]
}

셀은 균등 분할이 아니라 실제로 존재하는 거터를 기준으로 잘리므로, 모델이 만든 약간의 오차는 자연스럽게 흡수됩니다. 라벨 밴드가 먼저 잘려나가고, 캐릭터 셀은 가장자리에서부터 플러드 필로 식별됩니다. 대부분의 모델이 투명도를 출력하지 못하므로 여기서는 배경이 순백색인 것을 전제로 합니다. 흰색 셔츠는 가장자리와 연결되지 않으므로 그대로 흰색으로 남습니다.

Warning

배경이 단색이 아니면(그러데이션, 그려진 방, 투명도 대신 쓰인 체크무늬 등) 키잉이 불가능해 background is not transparent 오류가 발생합니다. 단일 색상의 평평한 배경을 요청하세요.

시트는 해상도를 대가로 치릅니다. 1536px에서 상한이 걸리는 모델이라면 3×3 그리드에서 셀당 약 512px, 5×4 그리드에서는 약 300px가 나옵니다. 팩의 기본 cell 크기인 256px 기준으로 보면 3×3은 여유롭고 5×4는 아슬아슬합니다. 그리드가 팩의 셀 크기를 감당하지 못하면 패키저가 오류를 냅니다. 옵션과 진단 항목 전체는 docs/asset-sheets.md에 있습니다.

두 방식 혼합하기

포즈별 파일은 같은 이름의 시트 셀을 덮어씁니다. 약한 셀 하나를 고칠 때 유용한 방법으로, 그 포즈만 시트를 참고 삼아 다시 생성해서 characters/<id>/face-LAUGH.png로 넣고 다시 빌드하면 됩니다. source.json은 수정할 필요가 없습니다.

접합부

얼굴과 몸통은 렌더링 시점에 합성되는 별도의 그림이므로, 패키저는 머리가 목과 만나는 지점을 알아야 합니다. 우선순위 순서로 세 가지 경로가 있습니다.

source.json의 anchors: 입력 캔버스의 픽셀 좌표를 직접 지정합니다.
아트 안의 불투명 마젠타(#ff00ff) 마커 픽셀 하나. 패키징 전에 지워집니다.
관례: 얼굴은 그림의 하단 중앙에서, 몸통은 그림의 상단 중앙에서 접합됩니다.

접합부는 캐릭터의 NEUTRAL 포즈로부터 한 번만 계산되어 나머지 모든 포즈에 재사용됩니다. 포즈마다 머리와 몸의 위치는 그대로 유지하고 표정이나 팔의 자세만 바꾸세요.

접합부가 틀려도 팩 자체는 유효한 상태로 만들어지는데, 이때 필요한 것이 --preview입니다. 각 캐릭터의 NEUTRAL 얼굴과 몸통을 합성해 접합부를 겹쳐 보여 주므로, 머리가 떠 있거나 파묻힌 상태를 한눈에 확인할 수 있습니다. 배포 전에 반드시 확인하세요.

오류와 경고

validate와 build는 동일한 2단계 진단 체계를 사용하며, 첫 번째 문제에서 멈추지 않고 모든 문제를 나열합니다.

오류는 빌드를 막습니다. 정사각형이 아닌 캔버스, 포즈별 파일 방식에서의 불투명한 배경, NEUTRAL 얼굴이나 몸통 누락, 알 수 없는 감정 이름, 비어 있거나 이름이 잘못된 시트 셀, 팩의 셀 크기를 감당하지 못할 만큼 밀집된 그리드가 여기에 해당합니다.

경고는 빌드를 막지는 않지만 확인해 볼 가치가 있습니다. 부드럽거나 흐릿한 윤곽선, 거터 안으로 넘어간 그림, NEUTRAL 셀 대비 스케일이 12% 이상 벗어난 포즈, 캔버스 하단 위로 떠 있는 몸통, 포즈가 하나뿐인 캐릭터, 거의 동일한 배경 셀 두 개 등이 있습니다.

시트 관련 진단은 sheet.png[column,row] -> name 형식으로 어떤 셀을 가리키는지 표시합니다.

라이브러리로 사용하기

CLI는 얇은 래퍼일 뿐이며, 두 단계 모두 임포트해서 사용할 수 있습니다.

import { analyze, buildPack } from "@toonstrip/asset-packager";

const { report } = await analyze("./my-source");   // errors + warnings
const result = await buildPack({ source: "./my-source", out: "./my-pack" });

만든 것의 라이선스 처리

아트의 출처를 명시하세요. 일부라도 본인이 직접 만든 것이 아니라면(본인 소유가 아닌 참고자료로부터 모델이 생성한 것 포함) 출처와 라이선스를 명시한 NOTICE 파일을 함께 배포하세요. 기본 팩의 NOTICE(Microsoft Comic Chat 아트, MIT, 상표권 면책 조항 포함)가 실제 예시입니다. source.json의 license 필드 값은 빌드된 pack.json에 그대로 반영됩니다.