CommunityImagengithub.com

Generador de Activos 3D Low-Poly en Three.js

Genera activos 3D low-poly procedimentales en Three.js r170+ utilizando constructores deterministas basados en semillas, esquemas de parámetros, mallas con vértices de color sombreado plano, geometría personalizada, partes reflejadas, kernels de bípedos y criaturas con rig, composites, texturas, exportación de código independiente y coincidencia con una imagen de referencia. No está diseñado para cargar archivos glTF.

¿Qué es Generador de Activos 3D Low-Poly en Three.js?

Este asistente especializado en generación de activos 3D procedimentales para Three.js permite construir desde objetos simples hasta criaturas complejas con rig, todo mediante funciones deterministas basadas en semillas. Utiliza un pipeline claro: los parámetros se resuelven a través de un esquema, luego se construye el activo con `build…Asset()` y se obtiene un `THREE.Group`. La determinismo garantiza que los mismos parámetros siempre produzcan el mismo resultado. Soporta mallas con vértices de color, geometría personalizada con winding correcto, partes reflejadas, rigs de bípedos y criaturas, texturas procedurales o generadas por IA, y exportación de código limpio como módulos ES. También incluye un sistema para hacer coincidir el activo generado con una imagen de referencia. No carga archivos glTF. Es ideal para desarrolladores que necesitan activos 3D predecibles, ligeros y reutilizables en aplicaciones web con Three.js.

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

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Generador de Activos 3D Low-Poly Procedimental para Three.js

Esta edición harness asume un espacio de trabajo y Node.js. Utilice los constructores empaquetados y las puertas CLI para recopilar evidencia del activo real.

Construya cada activo (simple o compuesto) como una función pura basada en semilla. La vista previa en vivo y la exportación de código independiente llaman a esa misma función, por lo que lo que el usuario ve es lo que exporta.

Detalle de superficie: Comience con material sólido o colores de vértice. Agregue un mapa de imagen solo para un detalle solicitado o visible que lo necesite. Utilice el generador de imágenes de la sesión cuando el arte original sea adecuado, luego mantenga su salida como una entrada fija al constructor.

Elección de vista previa: Cuando el usuario solicite una vista previa sin elegir un modo, ofrezca Vista previa rápida (orbitar, panoramizar, verificar texturas, reproducir o desplazar clips incrustados) y Vista previa completa (parámetros editables, inspección de rig, autoría de animaciones o expresiones). Comparta un resultado rápido si ya está disponible y use el modo solicitado. Consulte references/studio-preview.md.

Objetivo: three ≥ r170 como módulos ES, verificado contra las notas de migración oficiales hasta r187 (§12 en references/export.md).

El código está en src/, no en los documentos. Ejecute, no vuelva a leer: tsx src/<nombre>.test.ts (las pruebas puras no necesitan three). Los archivos de referencia enumeran la API de cada módulo.

¿Imagen de referencia dada? Lea references/reference-matching.md ANTES de escribir código y ejecute su ciclo después de cada paso de construcción (§15).

Dónde leer a continuación

Lo que está haciendoLeaCódigo
Materiales, sombreado plano, texturas procedurales o generadas por imagen, jitter de vértices (§4, §5)references/look.mdsrc/lowpoly.ts, src/jitter.ts
Geometría personalizada, winding, partes reflejadas, superposiciones (§6, §7)references/geometry.mdsrc/geometry.ts, src/overlay.ts
Criatura, casco, ala, kernel de triángulo puro (§6.2, §6.3)references/creatures.mdsrc/tri.ts, src/organic.ts
Cualquier cosa que anime, humanoide, extrusión, textura (§6.4 a §6.7)references/rigging-biped.mdsrc/rig.ts, src/biped.ts, src/texture.ts
Aspecto plano o bloqueado, atlas, chaflán, AO, sockets (§6.8)references/detail.mdsrc/detail.ts, src/detailThree.ts
Varios sub-activos en uno (§8)references/composite.md
Conexión a tierra, eliminación, reconstrucciones, luces (§9, §10)references/lifecycle.mdsrc/lifecycle.ts
Exportación de código, versiones de Three.js (§11, §12)references/export.mdsrc/fingerprint.ts
Un archivo .glb del activo (§16)references/glb-export.mdscripts/export-glb.ts
¿Es demasiado pesado, presupuesto de plataforma, LOD detail (§17)references/budget.mdscripts/mesh-stats.ts, src/lod.ts
Rig, clips de animación, deriva, expresiones (§18)references/rig-check.mdscripts/rig-check.ts
Visor GLB rápido o estudio de vista previa completoreferences/studio-preview.mdHTML de vista previa rápida
Ejemplo pequeño completoreferences/examples.md
Antes de decir que un activo está terminado: puertas de QA, imagen de revisión (§13)references/qa-gates.mdscripts/qa-asset.ts

0. Convenciones (decida una vez, aplique en todas partes)

TemaRegla
Unidades1 unidad = 1 metro
EjesY hacia arriba, diestro
Adelante+Z (igual que glTF y Object3D.lookAt)
LadosCon adelante +Z y arriba +Y, la derecha del activo es −X y su izquierda es +X (derecha = adelante × arriba)
PivoteOrigen en el centro de la huella, punto más bajo en Y = 0 (ver §9)
Nombres de carasNombre las caras por eje (cara +X, superior), nunca por babor/estribor/izquierda/derecha, para que una regla no pueda contradecir los ejes
SimetríaConstruya un lado, refleje la copia a través de PartBuilder.add o mirrorTris (§6.1). Un applyMatrix4 desnudo con escala negativa deja el winding al revés

Por qué esto importa: emparejar "proa = +Z" con "estribor = +X" está reflejado, y un barco construido con ese emparejamiento tiene los lados intercambiados. Con adelante +Z, estribor es −X y babor es +X.

1. Un solo pipeline, una sola fuente de verdad

esquema de parámetros (valores predeterminados, rangos) → resolveParams() → build…Asset() → THREE.Group
  • Los valores predeterminados y los rangos viven solo en el esquema. build…Asset(rawParams) llama a resolveParams por sí mismo. Tres valores predeterminados en competencia (params.seed || 12345, esquema default: 42, compuesto ?? 101) hacen que la vista previa, los ajustes preestablecidos y el código exportado no coincidan.
  • build…Asset es puro: los mismos parámetros resueltos dan geometría idéntica. Sin Math.random, Date.now, acceso al DOM o estado mutable a nivel de módulo.
  • Importe THREE normalmente. No inyecte un THREEInstance: los ayudantes usan la importación del módulo, por lo que la inyección solo funciona a medias y oculta errores. El paso de exportación proporciona la línea de importación (§11).
  • Asigne a cada constructor y lista de parámetros un nombre único (buildTreeAsset, treeParameters). Un buildAsset genérico choca tan pronto como un compuesto importa dos generadores.
  • Para geometría personalizada (criaturas, cascos, alas), mantenga la lógica de forma en funciones puras sobre matrices de triángulos simples y deje que THREE envuelva el resultado al final (§6.2). Las propiedades solo de primitivas pueden permanecer directamente en PartBuilder.

Tipos: src/types.ts (ParamDef, AssetGeneratorSchema).

Ejemplo trabajado (árbol): references/examples.md.

2. Determinismo

La salida reproducible es el objetivo principal de una semilla, así que protéjala:

  • Use ??, nunca ||, para semillas y cualquier valor de respaldo numérico. seed || 12345 convierte silenciosamente la semilla 0 en 12345.
  • Asigne a cada característica su propia secuencia bifurcada. Con un solo rng compartido, cambiar segments o alternar hasFruits desplaza cada número aleatorio posterior y reorganiza partes no relacionadas del activo.
  • Itere en un orden fijo (arrays, no claves de objeto de orden desconocido, no Set de inserción mixta).

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 valores predeterminados, coercionar tipos, ajusta a min/max, ajusta a step, y rechaza colores y selecciones incorrectos. Úselo en la interfaz de usuario, en ajustes preestablecidos y en build…Asset, para que ningún consumidor pueda producir NaN o geometría fuera de rango.

Código: src/params.ts. API:

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

  • Después de resolver, aplique restricciones derivadas para que las combinaciones de controles deslizantes no puedan producir formas degeneradas (por ejemplo trunkRadius = Math.min(trunkRadius, crownRadius * 0.6)).

  • Mantenga seed máximo en 99999 o más. Los constructores compuestos derivan sub-semillas como fork(label).seed % 100000; un máximo más pequeño las ajustaría a todas al mismo valor.

  • Las alternancias (hasFruits, hasTurrets) cambian lo que se construye, nunca qué números aleatorios reciben las otras partes (§2).

  • Alternancias de detalle (aoStrength, bevel, atlasOn) son parámetros ordinarios. Cambian lo que agrega el pase de detalle, nunca qué números aleatorios reciben otras partes.

  • La secuencia del atlas está bifurcada. Genere atlas desde rng.fork('atlas'), de modo que cambiar atlasOn deje todas las demás partes sin cambios (references/detail.md).

13. Lista de verificación (marque por activo, no envíe pre-marcado)

Ejecute las puertas, luego mire. npx tsx scripts/qa-asset.ts --module ./kernel.ts --export buildXTris --symmetric para un kernel puro, o --tris tris.json para el activo final conectado a tierra (uso y lista de puertas: references/qa-gates.md). Imprime Q1 a Q10, escribe review.png y termina con una línea @@RESULT. Corrija la primera puerta que falla y vuelva a ejecutar.

Regla de finalización. Nunca informe un activo como terminado hasta que qa-asset haya pasado en la compilación actual (o cada puerta que falla se nombre con su motivo), review.png se haya abierto con la herramienta de visualización y una línea por panel diga lo que se vio, y todo lo que figure como NO VERIFICADO o no revisado se repita en la respuesta. Termine con la tabla de puertas de la última ejecución.

Determinismo y parámetros

  • Los valores predeterminados y los rangos existen solo en el esquema; build…Asset llama a resolveParams
  • Las semillas usan ??; la semilla 0 funciona; sin Math.random o Date.now
  • Cada característica tiene su propia secuencia bifurcada; las alternancias no reorganizan otras partes
  • Las restricciones derivadas evitan formas degeneradas; las sub-semillas se ajustan al rango de semillas

Referencia (solo cuando el usuario proporcionó una imagen)

  • ref-spec.md escrito una vez, ref.json creado, PNG de máscara verificado; ref-compare ejecutado después de cada paso de construcción; tabla de puertas (§15) está en la respuesta

Geometría y apariencia

  • Los ejes siguen §0; las caras se describen por eje; derecha = −X cuando adelante = +Z
  • La geometría personalizada tiene signedVolume positivo, también después del reflejo; DoubleSide solo en láminas de grosor cero
  • Las partes reflejadas pasan por add()/addTris o mirrorTris, nunca un applyMatrix4 desnudo con escala negativa
  • Las formas de geometría personalizada y criatura viven en kernels de triángulo puro con pruebas de Node (determinismo, volumen firmado, aislamiento de secuencia)
  • Las partes pasan por bakeFlat + paint; las funciones de color por triángulo son puras
  • El jitter se aplica antes de add(), soldado en las costuras, con volúmenes delimitadores recalculados
  • Las partes metálicas tienen un mapa de entorno o un metalness reducido
  • Las superposiciones usan una inserción de distancia constante y una pequeña elevación contra el z-fighting

Rigging, humanoides, texturas (solo cuando correspondan)

  • Las partes móviles son huesos de RigBuilder, creados en pose de reposo; las partes estáticas permanecen fusionadas; huesos ≤ aproximadamente 12
  • Los huesos izquierdo/derecho provienen de mirrorBone + una matriz de espejo; los clips usan AnimationMixer en la raíz del rig
  • Las cadenas de extremidades pasan por twoBoneIK o cadenas de puntos fijos; los pies y las manos tienen adelante/arriba explícitos
  • Las partes extruidas y perfiladas tienen signedVolume positivo, también después del reflejo
  • UV está desactivado a menos que se use una textura; con una textura, PartBuilder({ uv }) se establece para cada parte de ese material y disposeAsset libera map

Pase de detalle (solo cuando corresponda)

  • Las celdas del atlas siguen la convención (celda 0 arriba a la izquierda); cada parte de un material texturizado tiene uv; los mapas de rugosidad/relieve son NoColorSpace con roughness: 1
  • El atlas se genera desde una secuencia bifurcada (seededAtlas), o se inyecta como parámetro; el constructor nunca carga archivos ni toca el DOM
  • Las partes achaflanadas y esculpidas tienen signedVolume positivo; las cantidades de esculpido mantienen radios > 0
  • La oclusión ambiental se aplica una vez (aoShade por parte para rigs, applyAO para fusiones estáticas) y nunca más oscura que el piso de 0.35
  • Los detalles pequeños provienen de raycastTris/scatterOnSurface + placeTris con sink; el lado reflejado usa mirrorHit

Compuesto

  • Nombres de constructores exportados únicos; parámetros con espacio de nombres y divididos con pickParams
  • La colocación usa huellas, orden de prioridad fijo y intentos limitados
  • Los elementos omitidos son deterministas; los objetos repetidos se clonan o instancian

QA (cada activo)

  • scripts/qa-asset.ts exit 0 en la compilación actual; review.png visto, un hallazgo por panel; elementos NO VERIFICADOS listados; tabla de puertas en la respuesta

Ciclo de vida y exportación

  • El grupo envoltorio conecta a tierra el activo en Y = 0; disposeAsset se llama en cada reconstrucción
  • Las mallas tienen nombre; el conteo de triángulos está dentro del presupuesto
  • El exportador usa un transpilador TS real, incluye ayudantes una vez y tiene cero importaciones excepto three (three/addons solo si se usa mergeGeometries)
  • GLB solicitado: elija la ruta de exportación en §16. Informe el archivo, las comprobaciones realizadas en sus bytes y cualquier etapa visual o de importación no verificada.
  • Plataforma dada o detail agregado: scripts/mesh-stats.ts (--lods para LOD) exit 0, perfil y tipo nombrados, no revisado repetido; detail predeterminado 2 deja el activo existente sin cambios
  • El objetivo de exportación (módulo, mapa de importación, global clásico) coincide con dónde se ejecutará el código
  • Prueba de paridad aprobada: generate(params) y el módulo exportado dan la misma huella digital

14. Activo único mínimo (cuando un esquema completo es excesivo)

Las ~290 líneas de un primer activo son principalmente infraestructura fija (prng.ts, lowpoly.ts, params.ts), no un costo por activo. Escríbalas una vez como módulos compartidos y nunca las incruste en un archivo de activo. Para un accesorio único, omita el esquema y resolveParams, mantenga el PRNG (el determinismo sigue siendo importante) y exporte solo con los ayudantes realmente utilizados (helpers: [rawPrng, rawLowpoly]). Un activo completo es entonces de aproximadamente 30 líneas:

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'));   // color por cara, secuencia propia
  for (const s of [-1, 1])                                                                       // listones de esquina
    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);
}

Promocione a la forma de esquema completa (§1) tan pronto como obtenga controles deslizantes, ajustes preestablecidos o se use dentro de un compuesto.

15. Coincidencia de referencia (cuando el usuario proporciona una imagen, captura de pantalla o boceto)

Procedimiento completo y scripts: references/reference-matching.md. Las reglas, en orden:

  1. Ingesta una vez. Vea la referencia una vez, escriba ref-spec.md (máximo 15 líneas: orientación, proporciones medidas, partes, paleta, 3 características distintivas, fuera del alcance), ejecute scripts/ref-intake.ts, mire el PNG de máscara una vez. Después de eso, nunca vuelva a leer la imagen: trabaje a partir de la especificación y ref.json.
  2. Construya de grueso a fino, compare después de cada paso. Un bloqueo (proporciones G1, aspecto G2) → silueta B (IoU G2 ≥ 0.85 por vista) → color C (paleta G3) → detalle D (características distintivas G4). Ejecute scripts/ref-compare.ts después de cada paso; toma menos de un segundo.
  3. Números antes que imágenes. Corrija solo la PRIMERA puerta que falla por ronda, cambie un grupo de parámetros, compare nuevamente.

[truncado para traducción]

Skills relacionados