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.md | src/lowpoly.ts, src/jitter.ts |
| 커스텀 지오메트리, 와인딩, 대칭 부품, 오버레이(§6, §7) | 참조/geometry.md | src/geometry.ts, src/overlay.ts |
| 크리처, 선체, 날개, 순수 삼각형 커널(§6.2, §6.3) | 참조/creatures.md | src/tri.ts, src/organic.ts |
| 애니메이션, 인간형, 돌출, 텍스처(§6.4~§6.7) | 참조/rigging-biped.md | src/rig.ts, src/biped.ts, src/texture.ts |
| 평평하거나 블록 같은 외관, 아틀라스, 모따기, AO, 소켓(§6.8) | 참조/detail.md | src/detail.ts, src/detailThree.ts |
| 하나의 여러 하위 에셋(§8) | 참조/composite.md | |
| 접지, 폐기, 재구축, 조명(§9, §10) | 참조/lifecycle.md | src/lifecycle.ts |
| 코드 내보내기, Three.js 버전(§11, §12) | 참조/export.md | src/fingerprint.ts |
에셋의 .glb 파일(§16) | 참조/glb-export.md | scripts/export-glb.ts |
너무 무거운가, 플랫폼 예산, LOD detail(§17) | 참조/budget.md | scripts/mesh-stats.ts, src/lod.ts |
| 리그, 애니메이션 클립, 드리프트, 표정(§18) | 참조/rig-check.md | scripts/rig-check.ts |
| 빠른 GLB 뷰어 또는 전체 미리보기 스튜디오 | 참조/studio-preview.md | 빠른 미리보기 HTML |
| 완전한 작은 예제 | 참조/examples.md | |
| 에셋이 완료되었다고 말하기 전에: QA 게이트, 리뷰 이미지(§13) | 참조/qa-gates.md | scripts/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반복. 기본detail2는 기존 에셋을 변경하지 않습니다. - 내보내기 대상(모듈, 임포트 맵, 클래식 전역)은 코드가 실행될 위치와 일치합니다.
- 패리티 테스트 통과:
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. 순서대로 규칙:
- 한 번 인테이크. 참조를 한 번 보고,
ref-spec.md를 작성하고(최대 15줄: 방향, 측정된 비율, 부품, 팔레트, 3가지 특징, 범위 밖),scripts/ref-intake.ts를 실행하고, 마스크 PNG를 한 번 봅니다. 그 후에는 이미지를 다시 읽지 마세요: 사양과ref.json에서 작업합니다. - 거친 것에서 미세한 것으로 빌드하고, 각 단계 후 비교. 블록아웃(G1 비율, G2 측면) → B 실루엣(뷰당 G2 IoU ≥ 0.85) → C 색상(G3 팔레트) → D 세부 사항(G4 특징). 각 단계 후
scripts/ref-compare.ts를 실행하세요. 1초 미만이 걸립니다. - 그림보다 숫자 먼저. 라운드당 첫 번째 실패 게이트만 수정하고, 하나의 파라미터 그룹을 변경하고, 다시 비교하세요
…
[번역을 위해 잘림]