로블록스 박스 동물

로블록스 박스 동물은(는) 무엇을 하나요?

각 동물에 대해 하나의 작은 데이터 파일(팔레트, 뼈대, 상자, 클립)을 작성합니다. scripts/boxrig.py가 이 파일을 바탕으로 메시, 스터드, 리깅, 애니메이션, 돌연변이, 렌더링 및 내보내기를 수행합니다.

예제(미리보기는 examples/previews/ 폴더 참조):

• examples/penguin.py: 이족보행 동물.
• examples/dragon.py: 본격적인 크기의 드래곤: 부드러운 복셀 몸체/S자 목/꼬리 + 상자로 만든 머리, 뿔, 판, 박쥐 날개, 턱과 불 호흡 대기 애니메이션 포함.
• examples/lion.py: 덩어리진 외형을 가진 해부학적으로 정확한 사자: 부드러운 복셀 몸체, 큰 스터드, 복셀 그리드 위에 그려진 픽셀 아트 얼굴. examples/lion_chibi.py는 구식 치비 사자로, 박스 API 예제로 유지됩니다.

요구 사항

• 블렌더 4.2 이상, 헤드리스 모드로 실행. Windows의 경우 C:\Program Files\Blender Foundation\Blender */blender.exe에서, Mac의 경우 /Applications/Blender.app/Contents/MacOS/Blender에서 찾을 수 있습니다. 5.1에서 테스트됨.
• Python 3 및 Pillow, numpy: py -m pip install --user pillow numpy. py -I로 스크립트를 실행하지 마세요.
• 아래 플레이스홀더: <B> = 블렌더 실행 파일, <S> = 이 스킬의 폴더.

워크플로우

1. 명세, 해부학 우선(사용자 규칙). 모든 동물은 실제 동물의 구조: 실제 신체 구조, 비율, 실루엣을 블록으로 쌓아 만듭니다. 절대 기능이 붙어 있는 큐브 캐릭터가 아닙니다.
   • reference/anatomy.md를 읽으세요. 실제 동물을 조사하거나 사용자의 참고 자료를 사용하세요.
   • 데이터 파일에 주석으로 어깨 높이 비율을 작성하세요: 몸 길이, 머리, 목, 다리, 꼬리.
   • 큰 모양으로 옆 실루엣을 잡고, 세부 사항을 추가하기 전에 일치시켜야 합니다.
   • 치비 또는 "귀여운 펫" 비율(큰 머리, 짧은 다리)은 사용자가 요청할 때만 사용합니다.
   • 2~4개의 특징적인 특성과 클립(기본 걷기, 달리기, 대기)을 기록합니다. 사용자의 참조 이미지나 모델이 명세입니다.
   • 크기를 결정합니다: 로블록스 캐릭터는 약 5스터드 높이; 펫은 4~8스터드; 실제 크기 생물은 실물 크기(드래곤은 약 40스터드 길이). 큰 동물을 축소하지 마세요.
2. 가장 가까운 예제를 사용자 폴더에 복사하거나, py <S>/scripts/new_animal.py <이름> quad|biped <폴더>를 실행합니다. 스킬 폴더 내부를 절대 편집하지 마세요.
3. 데이터를 편집합니다. 먼저 reference/design_guide.md를 읽으세요.
4. 빌드 및 렌더링:

   <B> -b --factory-startup --python <S>/scripts/boxrig.py -- <animal.py> all
   py <S>/scripts/make_sheet.py <out_dir> _v1
   

   • <out_dir>은 파일 옆에 out_<이름>입니다.
   • 모드는 views(빠름, 형태 잡기용), gif, export, mutations(뷰, 내보내기 및 돌연변이), all입니다.
5. 검토: <이름>_sheet_vN.png, review_<클립>_vN.png, <이름>_mutations_vN.png를 확인합니다. 데이터를 수정하고 새로운 태그로 다시 빌드하세요. Read 도구가 경로별로 이미지를 캐싱하기 때문입니다. 보통 3~5회 반복합니다.
6. 검증: <B> -b --factory-startup --python <S>/scripts/verify_fbx.py -- <out_dir> 명령이 VERIFY_OK를 출력해야 합니다.
7. 전달: 시트, 돌연변이 시트, GIF를 전달합니다.
8. 스튜디오: Roblox Studio MCP가 연결되어 있는 경우. reference/roblox_studio.md를 따르세요: 임포트, 수정, BoxRigAnim + <이름>Clips(포즈 및 KeyframeSequence용), MutationFX, 그 다음 측정된 플레이테스트.

데이터 파일 치트 시트

• 단위 및 축: 스터드, Z up, 앞 = -Y, 동물의 왼쪽 = +X.
• 상자: box(x0,x1, y0,y1, z0,z1, colour, bone). sym(...)는 상자를 오른쪽으로 대칭하며, %가 뼈 이름에서 L 또는 R이 됩니다. 뼈에 %가 포함된 box도 동일합니다. 나중에 정의된 상자가 겹치는 부분에서 우선합니다.
• 복셀 조각(크리처 몸체 기본값): VOXEL을 부드러운 곡선을 위해 충분히 작게(몸 길이의 약 1/90: 큰 드래곤 0.5, 사자 0.2) 설정하고, STUD_SIZE는 더 크게(2~4셀, 예: 1.0/0.8) 설정하여 스터드가 덩어리지고 읽기 쉽도록 유지합니다. 그 다음:
  • vell(cx,cy,cz, rx,ry,rz, col, bone): 타원체.
  • vcap(p0, p1, r0, r1, col, bone): 원뿔형 캡슐, 목, 다리, 꼬리, 뿔, 주둥이용.
  • vbox(...): 상자.
  • vsheet(origin, u, v, pts, thick, col, bone): 평평한 다각형, 날개, 지느러미, 프릴용; bone이 ('a', split, low, high)이면 두 뼈 사이에서 분할.
  • 옵션: paint=True는 기존 복셀만 다시 색칠(배 줄무늬, 눈, 표시); paint='belly'는 해당 색상의 셀만 다시 색칠(줄무늬를 가로지르는 띠); 뼈의 '%'는 L과 R로 대칭; mirror=True는 같은 뼈에서 대칭(뿔, 이빨).
  • 모든 것은 하나의 그리드에서 복셀화되고 욕심 많은 방식으로 메시화됩니다. 반지름을 최소 한 복셀 이상으로 유지하세요. 그렇지 않으면 얇은 부분이 끊어집니다. reference/design_guide.md의 "기본 스타일 = 부드러운 SHAPE + 덩어리진 LOOK"을 읽으세요.
• 유기적 형태, 상자 기반(구식 덩어리 스타일):
  • ell(cx,cy,cz, rx,ry,rz, colour, bone)는 3개의 상자로 만든 둥근 계단식 블롭입니다. 몸통, 가슴, 엉덩이, 목 마디, 허벅지, 꼬리 마디에 사용하세요.
  • poly([(x,y),...], z0, z1, colour, bone, step=1.0)는 위에서 본 윤곽을 채웁니다. 날개 막, 지느러미, 프릴, 꼬리 삽에 사용하세요. bone은 x의 함수가 되어 막을 Wing과 WingTip으로 분할할 수 있습니다.
  • beam(p0, p1, width, z0, z1, colour, bone)은 직선 막대입니다. 팔뼈, 날개 손가락, 뿔에 사용하세요.
• 날개 달린 동물: 날개를 펼친 평평한 상태로 모델링한 후, 클립에서 wing_rest=(raise, tip_droop, sweep)로 접습니다. 드래곤은 (58, 24, 22)를 사용합니다. VIEW_POSE = ('Idle', 0)으로 설정하여 시트에 날개를 접고 서 있는 동물을 표시합니다.
• 뼈대: BONES[name] = (parent, head, tail). 정확히 하나의 루트가 (0,0,0)에 있으며, 이 루트에는 상자가 없습니다. head 지점이 피벗입니다.
  • 사족 클립은 Body, Head, FrontUpper/Lower_L/R, BackUpper/Lower_L/R이 필요합니다. 선택 사항: 꼬리 체인, neck 체인, wings=('Wing','WingTip'), jaw.
  • 이족 클립은 Body, Head, Leg_L/R이 필요합니다. 선택 사항: Foot_L/R, Wing_L/R, 꼬리.
• 클립: CLIPS = {'Walk': (fn, frames), ...} 30fps, 끊김 없음, 제자리.
  • 기성 팩토리(키워드 인수만):
    • quad_walk, quad_run, quad_idle(jaw=, yawn=), quad_fly
    • biped_walk, biped_run, biped_idle, biped_fly
  • 나는 동물(드래곤, 새, 그리핀, 박쥐 등 작동하는 날개가 있는 모든 것)의 사용자 규칙:
    • Walk는 지상 걷기입니다: 다리는 움직이고 날개는 그대로 있습니다. quad_walk(..., wings=..., wing_flap=0) 또는 biped_walk(..., wing_flap=0)을 사용하세요.
    • Run은 비행입니다: 날개를 치고 다리는 뛰지 않습니다. 다리는 접혀서 가만히 있습니다. quad_fly(...) 또는 biped_fly(...)를 사용하고, 절대 quad_run이나 biped_run을 사용하지 마세요.
    • 다리가 달리는 동안 날개를 절대 펄럭이지 마세요.
  • 불 호흡(드래곤 및 기타 불을 뿜는 생물): quad_idle(jaw='Jaw', yawn=26, fire=(0.55, 0.75)) 및 데이터 파일의 MOUTH = (x, y, z)와 MOUTH_BONE = 'Head'.
    • 클립은 뒤로 젖히고 숨을 들이마신 후, t0에서 t1까지 턱을 벌리며 앞으로 내밉니다.
    • GIF에는 대체 불꽃이 표시됩니다. 스튜디오에서는 assets/FireBreath.lua가 클립의 FireStart 및 FireStop 마커에서 실제 불꽃을 구동하며, 각 돌연변이에 따라 색이 지정됩니다.
    • 애니메이션 편집기에는 불이 절대 표시되지 않습니다. 애니메이션 편집기는 뼈만 재생합니다. 편집 모드에서 표시하려면 assets/BoxRigPreview.lua를 사용하세요.
    • 앞을 향한 턱은 rx +로 아래로 열립니다. rx -는 턱을 위로 두개골 안으로 젖혀 사라진 것처럼 보이게 합니다.
  • 일반적인 길이: 걷기 3240프레임, 달리기 1824, 대기 90~150.
  • 큰 동물은 더 느리고 무겁게 움직입니다: 더 많은 프레임, 더 큰 bob과 bounce(스터드 단위), 더 낮은 pitch.
  • 커스텀 클립은 fn(t) -> {bone: ((rx,ry,rz) 관절에서 월드 축 기준 각도, (tx,ty,tz) 스터드 단위 변위)}입니다. 부호: rx +는 발을 뒤로 젖히고, 머리를 숙이며, 꼬리를 들어 올립니다.
• 돌연변이(기본값 Gold, Diamond, Shadow)는 boxrig.py의 MUTATIONS에서 정의합니다.
  • 각 돌연변이는 팔레트의 밝기를 부드러운 색상 램프에 매핑합니다.
  • ROLES는 눈 부분(iris, eye, shine, blush)의 이름을 지정하여 돌연변이의 보색 눈 색상을 받도록 합니다. keep은 이빨과 같은 키를 변경하지 않고 유지합니다.
  • MUTATIONS = {...}로 재정의하고 MUTATIONS_USE로 하위 집합을 선택할 수 있습니다.

로블록스 친화적 구조(이 규칙을 깨지 마세요)

• 하나의 드로우 콜: 하나의 메시, 하나의 재질, 하나의 공유 512px 타일링 스터드 텍스처. 색상은 정점 색상(vertex colour)이며, 로블록스가 TextureID와 곱합니다.
• 단단한 스키닝(1.0 가중치) 및 같은 뼈의 다른 상자에 의해 가려진 면 제거.
• 크기: 펫 약 800 삼각형, 드래곤 약 1,600. 모브는 약 3k 이하 유지; 하드 제한은 20k.
• 돌연변이는 같은 리깅에 있는 별도의 메시입니다: 모든 애니메이션이 모든 변종에서 작동합니다. 효과는 모델당 하나의 이미터와 최대 하나의 라이트에서 발생합니다.
• 내보내기: 잎 뼈 없음, FBX 단위 스케일, -Z forward, Y up, 루트는 원점, FBX당 하나의 클립.

자세한 내용: reference/design_guide.md, reference/roblox_rules.md, reference/roblox_studio.md, reference/pitfalls.md.