Gerador de Assets 3D Low-Poly Procedurais em Three.js
Esta edição harness assume um workspace e Node.js. Use os construtores empacotados e os gates de CLI para coletar evidências do asset real.
Construa cada asset (simples ou composto) como uma função pura e determinística baseada em semente. A pré-visualização ao vivo e a exportação de código autônomo chamam a mesma função, então o que o usuário vê é o que eles exportam.
Detalhamento de superfície: Comece com material sólido ou cores de vértices. Adicione um mapa de imagem apenas para um detalhe solicitado ou visível que precise de um. Use o gerador de imagem da sessão quando uma obra de arte original for a opção adequada; em seguida, mantenha sua saída como uma entrada fixa para o construtor.
Escolha de pré-visualização: Quando o usuário solicitar uma pré-visualização sem escolher um modo, ofereça Pré-visualização Rápida (orbitar, mover, verificar texturas, reproduzir ou percorrer clipes incorporados) e Pré-visualização Completa (parâmetros editáveis, inspeção de rig, animação, ou expressões). Compartilhe um resultado rápido se já estiver disponível e use o modo solicitado. Consulte references/studio-preview.md.
Alvo: three ≥ r170 como módulos ES, verificado nas notas oficiais de migração até r187 (§12 em references/export.md).
O código está em src/, não na documentação. Execute, não releia: tsx src/<nome>.test.ts (testes puros não precisam de three). Arquivos de referência listam a API de cada módulo.
Imagem de referência fornecida? Leia references/reference-matching.md ANTES de escrever código e execute seu loop após cada etapa de construção (§15).
Onde ler a seguir
| Se você está fazendo | Leia | Código |
|---|---|---|
| Materiais, shading flat, texturas procedurais ou geradas por imagem, jitter de vértices (§4, §5) | references/look.md | src/lowpoly.ts, src/jitter.ts |
| Geometria personalizada, winding, partes espelhadas, overlays (§6, §7) | references/geometry.md | src/geometry.ts, src/overlay.ts |
| Criatura, casco, asa, kernel de triângulos puro (§6.2, §6.3) | references/creatures.md | src/tri.ts, src/organic.ts |
| Qualquer coisa que anime, humanoide, extrusão, textura (§6.4 a §6.7) | references/rigging-biped.md | src/rig.ts, src/biped.ts, src/texture.ts |
| Aparência plana ou blocada, atlas, chanfro, AO, encaixes (§6.8) | references/detail.md | src/detail.ts, src/detailThree.ts |
| Vários sub-assets em um (§8) | references/composite.md | |
| Aterramento, descarte, reconstruções, luzes (§9, §10) | references/lifecycle.md | src/lifecycle.ts |
| Exportação de código, versões do Three.js (§11, §12) | references/export.md | src/fingerprint.ts |
Um arquivo .glb do asset (§16) | references/glb-export.md | scripts/export-glb.ts |
Está muito pesado, orçamento da plataforma, LOD detail (§17) | references/budget.md | scripts/mesh-stats.ts, src/lod.ts |
| Rig, clipes de animação, drift, expressões (§18) | references/rig-check.md | scripts/rig-check.ts |
| Visualizador GLB rápido ou estúdio de Pré-visualização Completa | references/studio-preview.md | HTML de Pré-visualização Rápida |
| Exemplo pequeno completo | references/examples.md | |
| Antes de dizer que um asset está pronto: gates de QA, imagem de revisão (§13) | references/qa-gates.md | scripts/qa-asset.ts |
0. Convenções (decida uma vez, aplique em todo lugar)
| Tópico | Regra |
|---|---|
| Unidades | 1 unidade = 1 metro |
| Eixos | Y para cima, sistema destro |
| Frente | +Z (mesmo que glTF e Object3D.lookAt) |
| Lados | Com frente +Z e cima +Y, a direita do asset é −X e sua esquerda é +X (direita = frente × cima) |
| Pivô | Origem no centro da pegada, ponto mais baixo em Y = 0 (veja §9) |
| Nomes de faces | Nomeie faces por eixo (face +X, topo), nunca por bombordo/estibordo/esquerda/direita, para que uma regra não possa contradizer os eixos |
| Simetria | Construa um lado, espelhe a cópia através de PartBuilder.add ou mirrorTris (§6.1). Um applyMatrix4 simples com escala negativa deixa o winding do avesso |
Por que isso importa: emparelhar "proa = +Z" com "estibordo = +X" é espelhado, e um navio construído a partir desse emparelhamento tem seus lados trocados. Com frente +Z, estibordo é −X e bombordo é +X.
1. Um pipeline, uma única fonte de verdade
esquema de parâmetros (padrões, intervalos) → resolveParams() → build…Asset() → THREE.Group
- Padrões e intervalos vivem apenas no esquema.
build…Asset(rawParams)chamaresolveParamspor si só. Três padrões concorrentes (params.seed || 12345,default: 42do esquema,?? 101do composto) fazem com que pré-visualização, predefinições e código exportado discordem. build…Asseté pura: os mesmos parâmetros resolvidos geram geometria idêntica. SemMath.random,Date.now, acesso ao DOM ou estado mutável em nível de módulo.- Importe
THREEnormalmente. Não injete umaTHREEInstance: os helpers usam a importação do módulo, então a injeção só funciona pela metade e esconde bugs. A etapa de exportação fornece a linha de importação (§11). - Dê a cada construtor e lista de parâmetros um nome único (
buildTreeAsset,treeParameters). UmbuildAssetgenérico colide quando um composto importa dois geradores. - Para geometria personalizada (criaturas, cascos, asas), mantenha a lógica de forma em funções puras sobre arrays de triângulos simples e deixe o THREE envolver o resultado no final (§6.2). Props apenas com primitivas podem ficar diretamente no
PartBuilder.
Tipos: src/types.ts (ParamDef, AssetGeneratorSchema).
Exemplo prático (árvore): references/examples.md.
2. Determinismo
A saída reproduzível é o objetivo principal de uma semente, então proteja-a:
- Use
??, nunca||, para sementes e qualquer fallback numérico.seed || 12345transforma silenciosamente a semente0em12345. - Dê a cada recurso seu próprio fluxo bifurcado. Com um
rngcompartilhado, alterarsegmentsou alternarhasFruitsdesloca todos os números aleatórios posteriores e reorganiza partes não relacionadas do asset. - Itere em uma ordem fixa (arrays, não chaves de objeto de ordem desconhecida, não
Setde inserção mista).
Código: src/prng.ts. API:
export function hashString(str: string)export function createPRNG(seed = 1)export type Rng = ReturnType<typeof createPRNG>;
3. Parâmetros
resolveParams aplica padrões, faz coerção de tipos, limita a min/max, ajusta a step, e rejeita cores e seleções ruins. Use-o na interface do usuário, em predefinições e em build…Asset, para que nenhum consumidor possa produzir NaN ou geometria fora do intervalo.
Código: src/params.ts. API:
-
export function resolveParams(schema: { parameters: ParamDef[] }, input: Record<string, unknown> = {}) -
Após resolver, aplique restrições derivadas para que combinações de controles deslizantes não possam produzir formas degeneradas (por exemplo
trunkRadius = Math.min(trunkRadius, crownRadius * 0.6)). -
Mantenha o máximo de
seedem 99999 ou mais alto. Construtores compostos derivam sub-sementes comofork(label).seed % 100000; um máximo menor as limitaria todas ao mesmo valor. -
Alternâncias (
hasFruits,hasTurrets) mudam o que é construído, nunca quais números aleatórios as outras partes recebem (§2). -
Alternâncias de detalhes (
aoStrength,bevel,atlasOn) são parâmetros comuns. Eles mudam o que a passagem de detalhes adiciona, nunca quais números aleatórios outras partes recebem. -
Fluxo do atlas é bifurcado. Gere atlas a partir de
rng.fork('atlas'), para que alternaratlasOndeixe todas as outras partes inalteradas (references/detail.md).
13. Lista de verificação (marque por asset, não envie pré-marcado)
Execute os gates, depois veja. npx tsx scripts/qa-asset.ts --module ./kernel.ts --export buildXTris --symmetric para um kernel puro, ou --tris tris.json para o asset final aterrado (uso e lista de gates: references/qa-gates.md). Ele imprime Q1 a Q10, escreve review.png e termina com uma linha @@RESULT. Corrija o primeiro gate com falha e execute novamente.
Regra de conclusão. Nunca relate um asset como pronto até que qa-asset tenha passado na construção atual (ou cada gate com falha seja nomeado com seu motivo), review.png tenha sido aberto com a ferramenta de visualização e uma linha por painel diga o que foi visto, e tudo listado como UNVERIFIED ou not checked seja repetido na resposta. Termine com a tabela de gates da última execução.
Determinismo e parâmetros
- Padrões e intervalos existem apenas no esquema;
build…AssetchamaresolveParams - Sementes usam
??; semente0funciona; semMath.randomouDate.now - Cada recurso tem seu próprio fluxo bifurcado; alternâncias não reorganizam outras partes
- Restrições derivadas previnem formas degeneradas; sub-sementes se encaixam no intervalo de sementes
Referência (apenas quando o usuário forneceu uma imagem)
-
ref-spec.mdescrito uma vez,ref.jsonfeito, PNG de máscara verificado;ref-compareexecutado após cada etapa de construção; tabela de gates (§15) está na resposta
Geometria e aparência
- Eixos seguem §0; faces descritas por eixo; direita = −X quando frente = +Z
- Geometria personalizada tem
signedVolumepositivo, também após espelhamento;DoubleSideapenas em folhas de espessura zero - Partes espelhadas passam por
add()/addTrisoumirrorTris, nunca por umapplyMatrix4de escala negativa simples - Formas de geometria personalizada e criaturas vivem em kernels de triângulos puros com testes Node (determinismo, signed volume, isolamento de fluxo)
- Partes passam por
bakeFlat+paint; funções de cor por triângulo são puras - Jitter é aplicado antes de
add(), soldado na costura, com volumes delimitadores recalculados - Partes metálicas têm um mapa de ambiente ou um
metalnessreduzido - Overlays usam um recuo de distância constante e uma pequena elevação contra z-fighting
Rigging, humanoides, texturas (apenas quando se aplicam)
- Partes móveis são ossos de
RigBuilder, criados em pose de descanso; partes estáticas permanecem mescladas; ossos ≤ cerca de 12 - Ossos esquerdo/direito vêm de
mirrorBone+ uma matriz de espelhamento; clipes usamAnimationMixerna raiz do rig - Cadeias de membros passam por
twoBoneIKou cadeias de pontos fixos; pés e mãos têm frente/cima explícitos - Partes extrudadas e loftadas têm
signedVolumepositivo, também após espelhamento - UV está desligado a menos que uma textura seja usada; com uma textura,
PartBuilder({ uv })é definido para cada parte desse material edisposeAssetliberamap
Passagem de detalhes (apenas quando se aplica)
- Células do atlas seguem a convenção (célula 0 no canto superior esquerdo); toda parte de um material texturizado tem uv; mapas de rugosidade/ bump são
NoColorSpacecomroughness: 1 - Atlas é gerado a partir de um fluxo bifurcado (
seededAtlas), ou injetado como parâmetro; o construtor nunca carrega arquivos ou toca no DOM - Partes chanfradas e esculpidas têm
signedVolumepositivo; quantidades de escultura mantêm raios > 0 - AO é aplicado uma vez (
aoShadepor parte para rigs,applyAOpara mesclagens estáticas) e nunca mais escuro que o piso de 0.35 - Pequenos detalhes vêm de
raycastTris/scatterOnSurface+placeTriscomsink; lado espelhado usamirrorHit
Composto
- Nomes únicos de construtores exportados; parâmetros com namespace e fatiados com
pickParams - Posicionamento usa pegadas, ordem de prioridade fixa e tentativas limitadas
- Itens pulados são determinísticos; objetos repetidos são clonados ou instanciados
QA (todo asset)
-
scripts/qa-asset.tsexit 0 na construção atual;review.pngvisualizado, um achado por painel; itens UNVERIFIED listados; tabela de gates na resposta
Ciclo de vida e exportação
- Grupo wrapper aterra o asset em Y = 0;
disposeAsseté chamado em cada reconstrução - Meshes são nomeados; contagem de triângulos está dentro do orçamento
- Exportador usa um transpilador TS real, inclui helpers uma vez e tem zero importações exceto
three(three/addonsapenas semergeGeometriesfor usado) - GLB solicitado: escolha o caminho de exportação em §16. Relate o arquivo, verificações realizadas em seus bytes e quaisquer estágios visuais ou de importação não verificados.
- Plataforma fornecida ou
detailadicionado:scripts/mesh-stats.ts(--lodspara LOD) exit 0, perfil e tipo nomeados,not checkedrepetido;detailpadrão 2 deixa o asset existente inalterado - Alvo de exportação (módulo, import map, global clássico) corresponde a onde o código será executado
- Teste de paridade passa:
generate(params)e o módulo exportado dão a mesma fingerprint
14. Asset único mínimo (quando um esquema completo é exagero)
As ~290 linhas de um primeiro asset são principalmente infraestrutura fixa (prng.ts, lowpoly.ts, params.ts), não custo por asset. Escreva-as uma vez como módulos compartilhados e nunca as coloque inline em um arquivo de asset. Para um prop único, pule o esquema e resolveParams, mantenha o PRNG (determinismo ainda importa), e exporte apenas com os helpers realmente usados (helpers: [rawPrng, rawLowpoly]). Um asset completo tem então cerca de 30 linhas:
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')); // cor por face, fluxo próprio
for (const s of [-1, 1]) // sarrafos de canto
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);
}
Promova-o para a forma de esquema completa (§1) assim que ganhar controles deslizantes, predefinições ou for usado dentro de um composto.
15. Correspondência de referência (quando o usuário fornece uma imagem, screenshot ou esboço)
Procedimento completo e scripts: references/reference-matching.md. As regras, em ordem:
- Captura única. Veja a referência uma vez, escreva
ref-spec.md(máximo 15 linhas: orientação, proporções medidas, partes, paleta, 3 características marcantes, fora de escopo), executescripts/ref-intake.ts, olhe para o PNG de máscara uma vez. Depois disso, nunca releia a imagem: trabalhe a partir da especificação e deref.json. - Construa do grosso ao fino, compare após cada etapa. Um blockout (proporções G1, aspecto G2) → silhueta B (IoU G2 ≥ 0.85 por vista) → cor C (paleta G3) → detalhe D (características marcantes G4). Execute
scripts/ref-compare.tsapós cada etapa; leva menos de um segundo. - Números antes de imagens. Corrija apenas o PRIMEIRO gate com falha por rodada, mude um grupo de parâmetros, compare novamente