Community이미지github.com

blender-gamepipe

블렌더 에셋(나무, 잔디, 바위, 소품, 건물)과 절차적 PBR 텍스처를 검증된 게임 레디 GLB/텍스처 세트(LOD, KTX2/meshopt 압축 포함)로 변환하고 three.js에서 렌더링을 확인합니다. 재사용 가능한 three.js 런타임(지형 바이옴, 바람에 흔들리는 잔디, 인스턴싱된 나무 LOD, 하늘)과 월드 핸드오프 도구를 포함합니다. 게임/웹 엔진용 블렌더 에셋 내보내기/최적화, 베이크/LOD/검증, 타일 가능한 지면 또는 건물 텍스처 생성, 블렌더 에셋으로 three.js 월드 구축, bpy 스크립트(베이크, 내보내기, 지오메트리 노드) 작성/디버깅 요청 시 사용합니다.

blender-gamepipe란 무엇인가요?

blender-gamepipe는 블렌더 에셋을 게임 엔진용으로 변환하는 완전 자동화된 파이프라인입니다. spec → lint → build → validate → export → GLB 검사 → 엔진 확인의 결정론적 루프를 제공하며, 모든 단계를 통과해야만 에셋이 완료된 것으로 간주합니다. 이 스킬은 나무, 풀, 바위, 건물, 캐릭터 등 다양한 에셋 타입과 13개의 타일 가능한 PBR 텍스처 세트(7개 바이옴 + 4개 건축 재료)를 지원하며, LOD 생성(KTX2/meshopt 압축 포함)과 three.js 기반의 엔진 검증을 자체 런타임으로 수행합니다. Claude Code, Cursor, Codex 등의 AI 에이전트가 블렌더 작업을 요청받았을 때 사용하며, headless 모드(blender -b)와 MCP를 통한 라이브 블렌더 세션을 지원하고, GOTCHAS 파일에 블렌더 API의 일반적인 함정이 정리되어 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/RNT56/agent-skill-blender-export-three.js/tree/HEAD/skills/blender-gamepipe

Installed? Explore more 이미지 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

blender-gamepipe은(는) 무엇을 하나요?

블렌더 중심의 결정론적 루프: 스펙 -> 린트 -> 빌드 -> 검증 -> 내보내기 -> GLB 검사 -> 엔진 확인. 에이전트는 판단(레시피, 수정, 아트 방향)을 제공하고, 스크립트는 게이트 역할을 합니다. 게이트를 통과하지 않으면 배포되지 않습니다.

하나의 규칙

에셋이 완료되었다고 로그나 렌더만 보고 직접 판단하지 마십시오. 완료는 다음 모두를 의미합니다:

  1. bin/gp build <spec>이 종료 코드 0으로 종료되었고 out/<asset>/manifest.json에 "passed": true가 명시되어 있어야 합니다.
  2. 미리보기/QA 이미지를 열어 직접 확인했습니다 (로깅에서는 보이지 않는 무음 실패: 빈 베이크, 뒤집힌 텍스처, 튀어나온 지오메트리).
  3. 엔진 확인이 성공했습니다 (파일이 three.js에서 로드되고, 텍스처가 압축되어 도착하며, 콘솔 오류가 없고, 실제 조명에서 올바르게 보입니다). 어떤 단계가 실패했거나 건너뛰었다면, 그 사실을 명확히 말하십시오.

빠른 시작

bin/gp test                                  # 모든 것 (Blender 필요; ~5분)
bin/gp textures specs/biomes.json            # 11개의 타일 가능 PBR 세트 (7개 바이옴 + 4개 건축 재료) + 이음새 검사 -> out/textures/
bin/gp generate generators/samurai_keep.py   # 절차적 성주 -> fixtures/samurai_keep.blend (텍스처 먼저 필요)
bin/gp build specs/samurai_keep_01.json      # 레시피 -> 게이트 -> GLB -> 검사 -> 매니페스트 -> 미리보기 (-> out/<asset>/)
bin/gp build specs/grass_blades.json         # 바람 대응 블레이드 팩 (소스 씬 불필요)
bin/gp build specs/tree_maple_01.json        # 나무 LOD0-3 (임포스터 포함)
bin/gp lint my_script.py                     # bpy 코드 실행 전 블렌더 함정 탐지
bin/gp glb out/<asset>/*.glb                 # Blender 없이 내보낸 파일 검사
bin/gp view                                  # 단일 에셋 뷰어: http://localhost:8765/viewer/?asset=<name>
python3 tools/export_world.py --dest ../my-game --models ... --biomes ...   # 게임 폴더 조합 (실패한 에셋 거부)

macOS에서는 Blender가 자동 탐지됩니다; 그 외의 경우 export BLENDER=/path/to/Blender.

파이프라인 맵

필요도구출력
타일 가능 지면/바이옴/건축 PBR (13세트: 7개 바이옴, 돌, 회반죽, 2가지 나무, 지붕 타일, 초가)gp textures (gp_texgen.py)<name>_albedo.jpg, _normal.png, _orm.png + 접촉 시트 + 이음새 보고서
히어로 나무 -> LOD + 임포스터레시피 tree<asset>_LOD0..3.glb (자체 텍스처)
절차적 재질의 바위/소품레시피 prop하나의 베이크된 PBR 세트를 공유하는 LOD
잔디레시피 grassgrass_blades.glb (3종 x 2 LOD, 30트라이앵글; uv.y = 블레이드 높이)
다중 재질 건물 (작성된 LOD)generators/{samurai_keep,minka,teahouse}.py (공유 gen_common.py) 후 레시피 buildingLOD0-2를 담은 하나의 GLB, 텍스처 공유
스킨드, 애니메이션 캐릭터generators/samurai_unit.py (generators/samurai/의 키트) 후 레시피 character스킨드 LOD0-2 + 무기 노드가 하나의 GLB에, 클립당 하나의 애니메이션, clips.json; 먼저 docs/character.md 읽기
엔진runtime/*.js (three.js ES 모듈)지형 바이옴, 바람 잔디, 인스턴스 숲, 하늘, 플레이어
핸드오프tools/export_world.py자체 완결 게임 폴더

워크플로우

  1. 스펙 (specs/*.json): 이름, 타입, recipe, source_blend, 예산, recipe_cfg, glb_expect, export. 이웃 파일을 복사하세요.
  2. 작성한 모든 bpy를 린트 (bin/gp lint). 모든 error를 수정하세요.
  3. 헤드리스 빌드. 라이브 블렌더 세션 내에서 절대 베이크/렌더하지 마십시오 (항목: 진입점 참조).
  4. 종료 코드뿐 아니라 보고서를 읽으십시오: out/<asset>/*.report.json에는 안정적인 찾기 code가 있습니다.
  5. 수정하고 다시 빌드하십시오. 사용자의 동의 없이 예산을 늘리지 마십시오.
  6. 직접 확인: *.preview.png를 열고 (그리고 제너레이터의 경우 --render QA 뷰) 실루엣, 재질, 스케일을 판단하십시오.
  7. 엔진 확인 (아래), 그런 다음 LOD별 트라이앵글, 크기, 검증된 것과 검증되지 않은 것을 보고하십시오.

진입점

  • 헤드리스 (기본): bin/gp build ... = blender -b <source.blend> -P gamepipe/gp_cli.py -- <spec>.
  • MCP를 통한 라이브 블렌더: gp_live.run_headless_from_live(spec)은 열린 씬의 복사본을 저장하고 헤드리스로 실행합니다 (라이브 세션에서 베이크/렌더는 시간 초과되고 UI가 멈춥니다). execute_blender_code 스니펫은 result = {...} (딕셔너리)를 할당해야 합니다.

엔진 확인 (three.js) - 필수

단일 에셋: bin/gp view 실행 후 http://localhost:8765/viewer/?asset=<name> 열고 >= 5초 기다린 후 (KTX2가 워커에서 트랜스코딩), JSON.stringify({state: window.__state, report: window.report}). tris가 매니페스트와 일치하고, mapIsCompressed:true, 나무 껍질 normalMap/aoMap/roughnessFromMap:true, 잎 alphaTest:0.5, 콘솔 오류가 없어야 합니다. 전체 월드: runtime/ 사용 (runtime/index.js 참조); 이러한 모듈을 함께 연결하여 월드를 구축합니다 (지형 + 바이옴, 잔디, 숲, 물, 하늘, 포스트); tools/export_world.py가 게임 폴더를 조립합니다. EXT_disjoint_timer_query_webgl2로 실제 GPU 시간을 측정하십시오 (gl.finish()는 Metal에서 no-op입니다); rAF는 백그라운드/포커스 없는 탭에서 제한되므로 임베디드 브라우저의 fps는 하한선일 뿐 측정값이 아닙니다.

레시피 (gamepipe/recipes/*.py) - recipes/__init__.py의 계약

META = {name, version, needs} + build(spec, out_dir) -> [파생 스펙] (각각: name, type, include_objects, budgets.max_tris, export). 레시피는 새로운 객체를 생성합니다. 추가하려면: 모듈 + 스펙 + 테스트 (tests/test_recipes.py를 복사).

레시피입력설명
tree나무 껍질 메시 + 잎 메시 (잎당 하나의 아일랜드, 첫 번째 정점 = 잎 밑동)알베도/노멀/ORM 베이크, 생성된 아틀라스의 잎 카드, LOD1-2 간소화, LOD3 임포스터; leaf_palette: 녹색/가을/벚꽃
prop절차적 재질의 하나의 메시간소화된 LOD, 공유 베이크 세트; 평평한 노멀 맵은 생략
grass없음 (생성됨)블레이드 UV: u가 가로, v = 높이 0..1; Blender Z-up -> glTF Y-up, -Z 방향으로 구부러짐
building<x>_LOD<n>_<Material> 이름의 작성된 LOD 객체 컬렉션게이트로 통과; lod_budgets는 LOD별 트라이앵글을 강제; 하나의 GLB
character아마추어 + 스킨드 LOD 메시 + 액션 (generators/samurai_unit.py에 의해 빌드됨)게이트가 SKIN_* / RIG_BONE_BUDGET / ANIM_* 코드를 추가; 스킨 + 액션당 하나의 애니메이션을 내보냄; 매니페스트에 clips.json을 작성. docs/character.md 참조

제너레이터 (generators/*.py) - 코드로 빌드된 에셋용

samurai_keep.py: 이시가키 기단 위의 텐슈, 높이 ~23m. 방법 = 실루엣을 위한 지오메트리 + 고정 월드 스케일 텍셀 밀도의 타일 가능 PBR (UV는 월드 공간 평면 투영: 돌/회반죽 3m, 나무 1.5m, 타일 1.6m 반복당). 트라이앵글: LOD0 57k, LOD1 16k, LOD2 4.5k. --render out/_keep.png --no-save로 QA 뷰를 렌더링하고 직접 보십시오. 어렵게 얻은 규칙: 열린 지붕 표면은 위를 향해야 함; 벽은 지붕 표면을 따라야 함 (상자가 아님) 그렇지 않으면 튀어나옴; 모퉁이 돌을 벽 기울기에 맞춰 기울임; 월드 공간 UV만 사용.

지금까지 지어진 건물 (모두 절차적, 모두 동일한 게이트 통과)

에셋설명트라이앵글 LOD0/1/2비고
samurai_keep_01이시가키 기단 위의 성주 (텐슈), ~23m57k / 16k / 4.5k금색 장식 포함 5개 재질
minka_01초가 농가, 엉덩이 지붕, 쇼지 베란다12k / 3.4k / 0.9k초가 = 울퉁불퉁한 높이장; 벽이 그 아래 0.22m 가라앉음
teahouse_0128개의 기둥 + 부두 + 등불 위의 물가 찻집20k / 6.5k / 0.8k원점 = 수면, +Y = 해안 방향; origin_tolerance 3.6 필요 (기둥)
각 제너레이터: bin/gp generate generators/<x>.py [--render out/_x.png --no-save] -> QA 렌더 확인 -> 픽스처 저장 -> bin/gp build specs/<x>_01.json.

런타임 (runtime/*.js) - export_world를 통해 게임으로 복사

assets.js (meshopt+KTX2를 사용한 GLB 로더, 바이옴 텍스처 배열) - terrain.js (7-바이옴 스플랫, 안티타일링, 탄젠트 프레임, 먼 가을 캐노피 + 스노우 라인) - grass.js + grass_clump.js (청크 계층, GPU 바람, 짓밟기; clumps: true = 씨앗 이삭이 있는 높은 논 클럼프) - water.js + water_waves.js (공유 GPU / CPU 웨이브 모델, 베이크된 해안선 + 거품, 흡수, 코스틱스, 평면 반사, 잔물결; 부유물을 위한 heightAt/normalAt/depthAt) - post.js (MSAA HDR -> 블룸 -> ACES -> 그레이딩) - foliage.js/trees.js (인스턴스 LOD 버킷, 흔들림, 반투명) - sky.js (3-스톱 그라디언트, 태양 헤일로, 조명 적운 + 권운) - look.js (공유 looks/*.json, 필 라이트 포함) - player.js - scatter.js - quality.js (적응형 해상도) - noise.js - noisetex.js (하나의 타일 가능 4채널 노이즈 텍스처) - 낮/밤, 계절, 날씨: env_clock.js (태양 + 달 천문학), env_atmosphere.js (looks/atmosphere.json의 태양 고도별 키프레임), env_seasons.js (잔디/잎/지면/눈 상태 + 적용기), env_weather.js, env_sky.js, env_lighting.js, env_grade.js - 생명: aquatic.js (갈대, 수련, 부유물, 해안 바위), fauna.js (잉어, 오리, 잠자리). looks/golden_hour.json 룩은 가을 저태양 룩입니다 (태양 서쪽에서 16도, 따뜻한 하늘, 차가운 필 라이트, 블룸 + 그레이딩). 색상 저작: 룩 JSON 색상은 씬-리니어입니다 (sRGB가 아닙니다); 잔디 틴트는 디스플레이 색상으로 저작되고 셰이더에서 제곱됩니다.

검증기 코드 (수정하세요, 무음 처리하지 마세요)

BUDGET_TRIS/BUDGET_LOD_TRIS/BUDGET_FILE_SIZE/BUDGET_MATERIALS (예산 초과) | UV_MISSING | MAT_PROCEDURAL (베이크하세요) | TEX_BLANK (베이크가 조용히 실패함) | TEX_TOO_LARGE | ALPHA_BLENDED/GLB_ALPHA_BLEND (Math Round -> MASK로 알파 경로 우회) | XFORM_NEG_SCALE/NONUNIFORM | ORIGIN_NOT_AT_BASE | MESH_ZERO_AREA/NON_MANIFOLD | MOD_GEONODES | GLB_* (내보낸 파일의 문제). 텍스처 제너레이터: NOT_TILEABLE, TEX_FLAT, ALBEDO_RANGE, NORMAL_TOO_STRONG.

주의사항

bpy 또는 셰이더 코드를 작성하기 전에 GOTCHAS.md를 읽으십시오. 주요 내용: 노드에서 is가 아닌 == 사용; 베이크는 활성화+선택된 이미지 노드 필요; Blender 이미지는 아래에서 위로 저장됨 (IO에서 뒤집지 않으면 모든 노멀 맵이 반전됨); ORM/노멀 맵은 PNG여야 함 (JPEG 크로마 서브샘플링이 데이터 채널을 손상시킴); glTF 알파 모드는 Round 노드에서 옴; KTX2는 제거하지 않으면 두 번 내보내짐; 백그라운드 탭의 fps는 절대 신뢰하지 마십시오.

다루지 않는 것 (정직하게)

모션 캡처 / 수작업 애니메이션 (character 레시피의 클립은 코드로 작성됨, docs/character.md 참조), 강/수중, 지형 스트리밍/원형 충돌체 이상의 충돌, 오디오, 강체 물리 (부유물에 대한 수면 물리학은 다룸), 강수 (날씨 상태는 이를 위한 precip을 가짐). 하위 나무 LOD는 LOD0의 노멀 맵을 재사용합니다. 거칠기는 알베도 휘도에서 파생됩니다. 절차적 모델링은 수작업 조각/스캔 정밀도가 아닙니다. KTX2는 하나의 브라우저/GPU(Apple M4 / Metal)에서 검증되었습니다.

관련 스킬