CommunityImagemgithub.com

Gerador de Assets 3D Low-Poly em Three.js

Gera assets 3D low-poly procedurais em Three.js r170+ com construtores determinísticos baseados em sementes, esquemas de parâmetros, malhas com vértices coloridos e shading flat, geometria personalizada com winding correto, partes espelhadas, kernels de bipedais e criaturas, composições, texturas, exportação de código independente e correspondência a uma imagem de referência. Não é para carregar arquivos glTF.

O que é Gerador de Assets 3D Low-Poly em Three.js?

Este é um skill especializado para gerar assets 3D low-poly puramente procedurais no Three.js, a partir da versão r170. Ele se baseia em funções puras e determinísticas alimentadas por sementes, garantindo que a mesma semente produza exatamente o mesmo asset. O skill cobre desde geometria personalizada (com winding correto e partes espelhadas) até geração de criaturas, bipedais articulados e composições de múltiplos sub-assets. Também inclui um pipeline completo para correspondência a imagens de referência (sketches, screenshots), com verificação em várias etapas de proporções, silhueta, cor e detalhes. O skill é executado em um workspace Node.js e utiliza construtores modulares (como `PartBuilder`, `RigBuilder`) e funções de teste em `src/`. A saída principal é um grupo `THREE.Group` que pode ser visualizado em pré-visualizações rápidas ou completas, e exportado como código ES module autônomo ou como arquivo `.glb`. O gerenciamento de ciclo de vida, incluindo descarte de assets e reconstrução, é integrado, e há um sistema de QA (`scripts/qa-asset.ts`) que verifica determinismo, geometria, iluminação e outras propriedades. Para quem usa ferramentas como Claude Code ou Cursor, este skill permite gerar assets 3D programáticos e reproduzíveis sem depender de modelos pré-existentes, ideal para prototipação rápida, geração de variações, ou criação de conteúdo para jogos e visualizações técnicas que exigem baixo poli e shading flat.

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

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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á fazendoLeiaCódigo
Materiais, shading flat, texturas procedurais ou geradas por imagem, jitter de vértices (§4, §5)references/look.mdsrc/lowpoly.ts, src/jitter.ts
Geometria personalizada, winding, partes espelhadas, overlays (§6, §7)references/geometry.mdsrc/geometry.ts, src/overlay.ts
Criatura, casco, asa, kernel de triângulos puro (§6.2, §6.3)references/creatures.mdsrc/tri.ts, src/organic.ts
Qualquer coisa que anime, humanoide, extrusão, textura (§6.4 a §6.7)references/rigging-biped.mdsrc/rig.ts, src/biped.ts, src/texture.ts
Aparência plana ou blocada, atlas, chanfro, AO, encaixes (§6.8)references/detail.mdsrc/detail.ts, src/detailThree.ts
Vários sub-assets em um (§8)references/composite.md
Aterramento, descarte, reconstruções, luzes (§9, §10)references/lifecycle.mdsrc/lifecycle.ts
Exportação de código, versões do Three.js (§11, §12)references/export.mdsrc/fingerprint.ts
Um arquivo .glb do asset (§16)references/glb-export.mdscripts/export-glb.ts
Está muito pesado, orçamento da plataforma, LOD detail (§17)references/budget.mdscripts/mesh-stats.ts, src/lod.ts
Rig, clipes de animação, drift, expressões (§18)references/rig-check.mdscripts/rig-check.ts
Visualizador GLB rápido ou estúdio de Pré-visualização Completareferences/studio-preview.mdHTML de Pré-visualização Rápida
Exemplo pequeno completoreferences/examples.md
Antes de dizer que um asset está pronto: gates de QA, imagem de revisão (§13)references/qa-gates.mdscripts/qa-asset.ts

0. Convenções (decida uma vez, aplique em todo lugar)

TópicoRegra
Unidades1 unidade = 1 metro
EixosY para cima, sistema destro
Frente+Z (mesmo que glTF e Object3D.lookAt)
LadosCom 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 facesNomeie faces por eixo (face +X, topo), nunca por bombordo/estibordo/esquerda/direita, para que uma regra não possa contradizer os eixos
SimetriaConstrua 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) chama resolveParams por si só. Três padrões concorrentes (params.seed || 12345, default: 42 do esquema, ?? 101 do 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. Sem Math.random, Date.now, acesso ao DOM ou estado mutável em nível de módulo.
  • Importe THREE normalmente. Não injete uma THREEInstance: 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). Um buildAsset gené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 || 12345 transforma silenciosamente a semente 0 em 12345.
  • Dê a cada recurso seu próprio fluxo bifurcado. Com um rng compartilhado, alterar segments ou alternar hasFruits desloca 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 Set de 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 seed em 99999 ou mais alto. Construtores compostos derivam sub-sementes como fork(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 alternar atlasOn deixe 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…Asset chama resolveParams
  • Sementes usam ??; semente 0 funciona; sem Math.random ou Date.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.md escrito uma vez, ref.json feito, PNG de máscara verificado; ref-compare executado 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 signedVolume positivo, também após espelhamento; DoubleSide apenas em folhas de espessura zero
  • Partes espelhadas passam por add()/addTris ou mirrorTris, nunca por um applyMatrix4 de 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 metalness reduzido
  • 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 usam AnimationMixer na raiz do rig
  • Cadeias de membros passam por twoBoneIK ou cadeias de pontos fixos; pés e mãos têm frente/cima explícitos
  • Partes extrudadas e loftadas têm signedVolume positivo, 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 e disposeAsset libera map

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 NoColorSpace com roughness: 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 signedVolume positivo; quantidades de escultura mantêm raios > 0
  • AO é aplicado uma vez (aoShade por parte para rigs, applyAO para mesclagens estáticas) e nunca mais escuro que o piso de 0.35
  • Pequenos detalhes vêm de raycastTris/scatterOnSurface + placeTris com sink; lado espelhado usa mirrorHit

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.ts exit 0 na construção atual; review.png visualizado, 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/addons apenas se mergeGeometries for 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 detail adicionado: scripts/mesh-stats.ts (--lods para LOD) exit 0, perfil e tipo nomeados, not checked repetido; detail padrã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:

  1. 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), execute scripts/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 de ref.json.
  2. 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.ts após cada etapa; leva menos de um segundo.
  3. Números antes de imagens. Corrija apenas o PRIMEIRO gate com falha por rodada, mude um grupo de parâmetros, compare novamente

Habilidades Relacionadas