Community이미지github.com

threejs-에셋-생성기

Three.js r170 이상에서 시드 기반 결정론적 빌더로 절차적 로우폴리 3D 에셋을 생성합니다. 파라미터 스키마, 플랫 셰이딩 버텍스 컬러 메시, 올바른 와인딩의 커스텀 지오메트리, 대칭 부품, 리깅된 이족보행 및 크리처 커널, 복합체, 텍스처, 독립 실행형 코드 내보내기, 참조 이미지 일치를 지원합니다. glTF 파일 로딩 용도가 아닙니다.

threejs-에셋-생성기란 무엇인가요?

Three.js r170 이상에서 실행되는 이 오픈소스 CLI 도구는 개발자가 스크립트 가능한 결정론적 파이프라인을 통해 완전히 절차적인 로우폴리 3D 에셋을 생성할 수 있도록 합니다. 이는 수동 모델링이나 glTF 파일 로딩을 대체하는 것이 아니라, 시드 기반의 재현 가능한 함수를 사용하여 에셋을 설계하고, 사용자가 라이브 미리보기와 동일한 함수를 통해 독립 실행형 코드로 내보낼 수 있게 합니다. 주요 기능으로는 파라미터화된 스키마, 플랫 셰이딩 및 버텍스 컬러, 올바른 삼각형 와인딩을 보장하는 커스텀 지오메트리(대칭 부품 포함), 리깅된 이족보행 및 크리처용 커널, 복합체, 텍스처, 참조 이미지 일치, 시드 결정론 적용을 위한 엄격한 가이드라인 등이 있습니다. 이 도구는 Three.js 커뮤니티, 게임 개발자, 인터랙티브 웹 경험을 구축하는 3D 아티스트에게 이상적이며, CLI 명령어(예: `npx tsx scripts/qa-asset.ts`)를 통해 QA를 자동화합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Luciansvon/ThreeJS-modeling-skill/tree/HEAD/threejs-asset-generator

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

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

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

문서

Three.js 절차적 로우폴리 에셋 생성기

이 버전은 워크스페이스와 Node.js를 가정합니다. 번들된 빌더와 CLI 게이트를 사용하여 실제 에셋에서 증거를 수집하세요.

모든 에셋(단일 또는 복합)을 순수하고 시드 기반 함수로 빌드하세요. 라이브 미리보기와 독립 실행형 코드 내보내기가 동일한 함수를 호출하므로, 사용자가 보는 것이 내보내는 것입니다.

표면 세부 사항: 솔리드 재질 또는 버텍스 컬러로 시작하세요. 요청되거나 가시적인 세부 사항에만 이미지 맵을 추가하세요. 원본 아트워크가 적합한 경우 세션의 이미지 생성기를 사용하고, 그 출력을 빌더의 고정 입력으로 유지하세요.

미리보기 선택: 사용자가 모드를 선택하지 않고 미리보기를 요청하면, 빠른 미리보기(궤도, 이동, 텍스처 확인, 임베디드 클립 재생 또는 스크러빙)와 전체 미리보기(편집 가능한 파라미터, 리그 검사, 애니메이션 저작, 또는 표정)를 제공하세요. 이미 사용 가능한 경우 빠른 결과를 공유하고 요청된 모드를 사용하세요. 참조/studio-preview.md를 참조하세요.

대상: 공식 마이그레이션 노트(r187까지, 참조/export.md §12)와 대조 확인된 three ≥ r170을 ES 모듈로 사용.

코드는 src/에 있습니다. 문서에 있지 않습니다. 실행하세요, 다시 읽지 마세요: tsx src/<name>.test.ts (순수 테스트는 three가 필요 없음). 참조 파일은 각 모듈의 API를 나열합니다.

참조 이미지가 주어졌습니까? 코드를 작성하기 전에 참조/reference-matching.md를 읽고 모든 빌드 단계 후에 그 루프를 실행하세요(§15).

다음에 읽을 내용

수행 작업읽을 내용코드
재질, 플랫 셰이딩, 절차적 또는 이미지 생성 텍스처, 버텍스 지터(§4, §5)참조/look.mdsrc/lowpoly.ts, src/jitter.ts
커스텀 지오메트리, 와인딩, 대칭 부품, 오버레이(§6, §7)참조/geometry.mdsrc/geometry.ts, src/overlay.ts
크리처, 선체, 날개, 순수 삼각형 커널(§6.2, §6.3)참조/creatures.mdsrc/tri.ts, src/organic.ts
애니메이션, 인간형, 돌출, 텍스처(§6.4~§6.7)참조/rigging-biped.mdsrc/rig.ts, src/biped.ts, src/texture.ts
평평하거나 블록 같은 외관, 아틀라스, 모따기, AO, 소켓(§6.8)참조/detail.mdsrc/detail.ts, src/detailThree.ts
하나의 여러 하위 에셋(§8)참조/composite.md
접지, 폐기, 재구축, 조명(§9, §10)참조/lifecycle.mdsrc/lifecycle.ts
코드 내보내기, Three.js 버전(§11, §12)참조/export.mdsrc/fingerprint.ts
에셋의 .glb 파일(§16)참조/glb-export.mdscripts/export-glb.ts
너무 무거운가, 플랫폼 예산, LOD detail(§17)참조/budget.mdscripts/mesh-stats.ts, src/lod.ts
리그, 애니메이션 클립, 드리프트, 표정(§18)참조/rig-check.mdscripts/rig-check.ts
빠른 GLB 뷰어 또는 전체 미리보기 스튜디오참조/studio-preview.md빠른 미리보기 HTML
완전한 작은 예제참조/examples.md
에셋이 완료되었다고 말하기 전에: QA 게이트, 리뷰 이미지(§13)참조/qa-gates.mdscripts/qa-asset.ts

0. 규칙 (한 번 결정하고 모든 곳에 적용)

주제규칙
단위1 단위 = 1 미터
축Y 위, 오른손 좌표계
정면+Z (glTF 및 Object3D.lookAt와 동일)
측면정면 +Z 및 위 Y 기준, 에셋의 오른쪽은 −X이고 왼쪽은 +X (오른쪽 = 정면 × 위)
피벗발자국 중심의 원점, 가장 낮은 지점이 Y = 0 (참조: §9)
면 이름축으로 면 이름 지정 (+X 면, 상단), 좌현/우현/왼쪽/오른쪽으로 지칭 금지 (규칙이 축과 모순되지 않도록)
대칭한쪽을 빌드하고 PartBuilder.add 또는 mirrorTris(§6.1)를 통해 사본을 미러. 음수 스케일의 applyMatrix4는 와인딩을 뒤집어 놓음

이것이 중요한 이유: bow = +Z와 starboard = +X를 짝짓는 것은 미러된 상태이며, 그 짝으로 빌드된 선박은 측면이 바뀝니다. 정면 +Z인 경우 starboard는 −X이고 port는 +X입니다.

1. 하나의 파이프라인, 하나의 진실 공급원

파라미터 스키마 (기본값, 범위) → resolveParams() → build…Asset() → THREE.Group
  • 기본값과 범위는 스키마에만 있습니다. build…Asset(rawParams)는 resolveParams를 자체적으로 호출합니다. 세 가지 경쟁 기본값(params.seed || 12345, 스키마 default: 42, 복합 ?? 101)은 미리보기, 프리셋 및 내보낸 코드가 불일치하게 만듭니다.
  • build…Asset는 순수합니다: 동일한 확인된 파라미터는 동일한 지오메트리를 제공합니다. Math.random, Date.now, DOM 액세스 또는 모듈 수준의 가변 상태가 없습니다.
  • THREE를 정상적으로 가져오세요. THREEInstance를 주입하지 마세요: 헬퍼는 모듈 가져오기를 사용하므로, 주입은 반쯤만 작동하고 버그를 숨깁니다. 내보내기 단계에서 임포트 라인을 제공합니다(§11).
  • 모든 빌더와 파라미터 목록에 고유한 이름을 지정하세요(buildTreeAsset, treeParameters). 일반 buildAsset은 복합체가 두 생성기를 가져오는 즉시 충돌합니다.
  • 커스텀 지오메트리(크리처, 선체, 날개)의 경우, 일반 삼각형 배열에 대한 순수 함수로 형태 로직을 유지하고 THREE가 마지막에 결과를 감싸도록 하세요(§6.2). 프리미티브 전용 속성은 직접 PartBuilder에 유지할 수 있습니다.

타입: src/types.ts (ParamDef, AssetGeneratorSchema).

작업 예제 (나무): 참조/examples.md.

2. 결정론

재현 가능한 출력이 시드의 핵심이므로, 보호하세요:

  • 시드 및 모든 숫자 폴백에 ||가 아닌 ??를 사용하세요. seed || 12345는 시드 0을 조용히 12345로 바꿉니다.
  • 각 기능에 자체 분기 스트림을 제공하세요. 하나의 공유 rng로 segments를 변경하거나 hasFruits를 토글하면 모든 후속 난수가 이동하고 에셋의 관련 없는 부분이 재구성됩니다.
  • 고정된 순서로 반복하세요(알 수 없는 순서의 객체 키나 혼합 삽입의 Set이 아닌 배열).

코드: src/prng.ts. API:

  • export function hashString(str: string)
  • export function createPRNG(seed = 1)
  • export type Rng = ReturnType<typeof createPRNG>;

3. 파라미터

resolveParams는 기본값을 적용하고, 타입을 강제 변환하고, min/max로 클램핑하고, step으로 스냅하고, 잘못된 색상과 선택을 거부합니다. UI, 프리셋 및 build…Asset에서 사용하므로, 어떤 소비자도 NaN 또는 범위를 벗어난 지오메트리를 생성할 수 없습니다.

코드: src/params.ts. API:

  • export function resolveParams(schema: { parameters: ParamDef[] }, input: Record<string, unknown> = {})

  • 확인 후, 파생 제약 조건을 적용하여 슬라이더 조합이 변형된 형태를 생성하지 못하도록 하세요(예: trunkRadius = Math.min(trunkRadius, crownRadius * 0.6)).

  • seed 최대값을 99999 이상으로 유지하세요. 복합 빌더는 하위 시드를 fork(label).seed % 100000으로 파생합니다. 더 작은 최대값은 모두 동일한 값으로 클램핑합니다.

  • 토글(hasFruits, hasTurrets)은 빌드되는 것을 변경할 뿐, 다른 부분이 수신하는 난수는 변경하지 않습니다(§2).

  • 세부 사항 토글(aoStrength, bevel, atlasOn)은 일반적인 파라미터입니다. 세부 사항 패스가 추가하는 것을 변경할 뿐, 다른 부분이 수신하는 난수는 변경하지 않습니다.

  • 아틀라스 스트림은 분기됩니다. 아틀라스를 rng.fork('atlas')에서 생성하므로, atlasOn을 전환해도 다른 모든 부분은 변경되지 않습니다 (참조/detail.md).

13. 체크리스트 (에셋당 체크, 미리 체크된 상태로 배송 금지)

게이트를 실행한 후 확인하세요. 순수 커널의 경우 npx tsx scripts/qa-asset.ts --module ./kernel.ts --export buildXTris --symmetric, 또는 최종 접지된 에셋의 경우 --tris tris.json (사용법 및 게이트 목록: 참조/qa-gates.md). Q1~Q10을 출력하고, review.png를 작성하고, @@RESULT 줄로 끝납니다. 첫 번째 실패 게이트를 수정하고 다시 실행하세요.

완료 규칙. qa-asset가 현재 빌드에서 통과할 때까지(또는 각 실패 게이트가 이유와 함께 명명될 때까지) 에셋을 완료되었다고 보고하지 마세요. review.png가 뷰 도구로 열렸고 패널당 한 줄씩 본 내용이 기록되었으며, UNVERIFIED 또는 not checked로 나열된 모든 항목이 답변에 반복되었는지 확인하세요. 마지막 실행의 게이트 테이블로 끝내세요.

결정론 및 파라미터

  • 기본값과 범위는 스키마에만 존재합니다. build…Asset는 resolveParams를 호출합니다.
  • 시드는 ??를 사용합니다. 시드 0이 작동합니다. Math.random 또는 Date.now가 없습니다.
  • 각 기능에 자체 분기 스트림이 있습니다. 토글이 다른 부분을 재구성하지 않습니다.
  • 파생 제약 조건이 변형된 형태를 방지합니다. 하위 시드가 시드 범위에 맞습니다.

참조 (사용자가 이미지를 제공한 경우에만)

  • ref-spec.md가 한 번 작성되었고, ref.json이 만들어졌으며, 마스크 PNG가 확인되었습니다. 모든 빌드 단계 후 ref-compare가 실행되었습니다. 게이트 테이블(§15)이 답변에 있습니다.

지오메트리 및 외관

  • 축은 §0을 따릅니다. 면은 축으로 설명됩니다. 정면 = +Z일 때 오른쪽 = −X입니다.
  • 커스텀 지오메트리는 양수 signedVolume를 가지며, 미러링 후에도 마찬가지입니다. DoubleSide는 두께가 0인 시트에만 사용됩니다.
  • 미러된 부품은 add()/addTris 또는 mirrorTris를 통해 처리되며, 절대 음수 스케일의 applyMatrix4를 사용하지 않습니다.
  • 커스텀 지오메트리 및 크리처 형태는 Node 테스트(결정론, 서명된 볼륨, 스트림 격리)가 있는 순수 삼각형 커널에 있습니다.
  • 부품은 bakeFlat + paint를 거칩니다. 삼각형당 색상 함수는 순수합니다.
  • 지터는 add() 전에 적용되고, 이음매가 용접되며, 바운딩 볼륨이 다시 계산됩니다.
  • 금속 부품에는 환경 맵 또는 낮춰진 metalness가 있습니다.
  • 오버레이는 일정한 거리의 인셋과 z-파이팅에 대항하는 작은 리프트를 사용합니다.

리깅, 인간형, 텍스처 (적용되는 경우에만)

  • 움직이는 부품은 RigBuilder의 뼈이며, 휴식 포즈로 작성되었습니다. 정적 부품은 병합된 상태로 유지됩니다. 뼈는 약 12개 이하입니다.
  • 왼쪽/오른쪽 뼈는 mirrorBone + 미러 매트릭스에서 비롯됩니다. 클립은 리그 루트에서 AnimationMixer를 사용합니다.
  • 사지 체인은 twoBoneIK 또는 고정점 체인을 통과합니다. 발과 손에는 명시적인 정면/위가 있습니다.
  • 돌출 및 로프트된 부품은 양수 signedVolume를 가지며, 미러링 후에도 마찬가지입니다.
  • UV는 텍스처가 사용되지 않는 한 꺼져 있습니다. 텍스처를 사용하는 경우 해당 재질의 모든 부품에 대해 PartBuilder({ uv })가 설정되고 disposeAsset이 map을 해제합니다.

세부 사항 패스 (적용되는 경우에만)

  • 아틀라스 셀은 규칙을 따릅니다(셀 0은 왼쪽 위). 텍스처 재질의 모든 부품에는 uv가 있습니다. 거칠기/범프 맵은 roughness: 1과 함께 NoColorSpace입니다.
  • 아틀라스는 분기된 스트림(seededAtlas)에서 생성되거나 파라미터로 주입됩니다. 빌더는 파일을 로드하거나 DOM에 접촉하지 않습니다.
  • 모따기 및 조각된 부품은 양수 signedVolume를 가집니다. 조각 양은 반경 > 0을 유지합니다.
  • AO는 한 번 적용되며(aoShade는 리그의 경우 부품당, applyAO는 정적 병합의 경우) 0.35 바닥보다 어둡지 않습니다.
  • 작은 세부 사항은 raycastTris/scatterOnSurface + sink가 있는 placeTris에서 비롯됩니다. 미러된 쪽은 mirrorHit을 사용합니다.

복합

  • 고유한 내보내기 빌더 이름입니다. 파라미터는 pickParams로 네임스페이스가 지정되고 슬라이스됩니다.
  • 배치는 발자국, 고정된 우선 순위 순서 및 제한된 시도를 사용합니다.
  • 건너뛴 항목은 결정론적입니다. 반복된 객체는 복제되거나 인스턴스화됩니다.

QA (모든 에셋)

  • scripts/qa-asset.ts가 현재 빌드에서 종료 코드 0입니다. review.png가 확인되었으며, 패널당 하나의 결과가 있습니다. UNVERIFIED 항목이 나열되었습니다. 게이트 테이블이 답변에 있습니다.

수명 주기 및 내보내기

  • 래퍼 그룹이 Y = 0에서 에셋을 접지합니다. 모든 재구축 시 disposeAsset이 호출됩니다.
  • 메시 이름이 지정되었습니다. 삼각형 수가 예산 내에 있습니다.
  • 내보내기는 실제 TS 트랜스파일러를 사용하고, 헬퍼를 한 번 포함하며, three(mergeGeometries가 사용되는 경우에만 three/addons)를 제외한 가져오기가 0입니다.
  • GLB가 요청됨: §16에서 내보내기 경로를 선택하세요. 파일, 바이트에 대해 수행된 검사 및 확인되지 않은 시각적 또는 가져오기 단계를 보고하세요.
  • 플랫폼이 주어졌거나 detail이 추가됨: scripts/mesh-stats.ts (--lods는 LOD의 경우) 종료 코드 0, 프로필 및 종류 명명, not checked 반복. 기본 detail 2는 기존 에셋을 변경하지 않습니다.
  • 내보내기 대상(모듈, 임포트 맵, 클래식 전역)은 코드가 실행될 위치와 일치합니다.
  • 패리티 테스트 통과: generate(params)와 내보낸 모듈이 동일한 지문을 제공합니다.

14. 최소 단일 에셋 (전체 스키마가 과도한 경우)

첫 번째 에셋의 약 290줄은 주로 고정된 인프라(prng.ts, lowpoly.ts, params.ts)이며, 에셋당 비용이 아닙니다. 공유 모듈로 한 번 작성하고 에셋 파일에 인라인하지 마세요. 일회용 소품의 경우 스키마와 resolveParams를 건너뛰고, PRNG를 유지하며(결정론은 여전히 중요함), 실제로 사용된 헬퍼만 내보내세요(helpers: [rawPrng, rawLowpoly]). 완전한 에셋은 약 30줄입니다:

import * as THREE from 'three';
import { createPRNG } from './prng';
import { PartBuilder, lowPolyMaterial } from './lowpoly';
import { groundAsset } from './lifecycle';

export function buildCrateAsset(raw: { seed?: number; size?: number } = {}) {
  const seed = raw.seed ?? 42, size = Math.min(Math.max(Number(raw.size ?? 1) || 1, 0.3), 3);
  const rng = createPRNG(seed).fork('planks');
  const wood = new PartBuilder();
  wood.add(new THREE.BoxGeometry(size, size, size), () => (rng() < 0.5 ? '#8a6a45' : '#7a5c3b'));   // 면당 색상, 자체 스트림
  for (const s of [-1, 1])                                                                       // 모서리 배튼
    wood.add(new THREE.BoxGeometry(size * 0.08, size * 1.02, size * 1.02), '#5b4329', new THREE.Matrix4().makeTranslation(s * size * 0.46, 0, 0));
  const content = new THREE.Group();
  content.add(wood.build(lowPolyMaterial({ roughness: 0.9 }), { name: 'crate' }));
  return groundAsset(content);
}

슬라이더, 프리셋이 추가되거나 복합체 내부에서 사용되면 즉시 전체 스키마 형식(§1)으로 승격하세요.

15. 참조 일치 (사용자가 이미지, 스크린샷 또는 스케치를 제공한 경우)

전체 절차 및 스크립트: 참조/reference-matching.md. 순서대로 규칙:

  1. 한 번 인테이크. 참조를 한 번 보고, ref-spec.md를 작성하고(최대 15줄: 방향, 측정된 비율, 부품, 팔레트, 3가지 특징, 범위 밖), scripts/ref-intake.ts를 실행하고, 마스크 PNG를 한 번 봅니다. 그 후에는 이미지를 다시 읽지 마세요: 사양과 ref.json에서 작업합니다.
  2. 거친 것에서 미세한 것으로 빌드하고, 각 단계 후 비교. 블록아웃(G1 비율, G2 측면) → B 실루엣(뷰당 G2 IoU ≥ 0.85) → C 색상(G3 팔레트) → D 세부 사항(G4 특징). 각 단계 후 scripts/ref-compare.ts를 실행하세요. 1초 미만이 걸립니다.
  3. 그림보다 숫자 먼저. 라운드당 첫 번째 실패 게이트만 수정하고, 하나의 파라미터 그룹을 변경하고, 다시 비교하세요

…

[번역을 위해 잘림]

관련 스킬