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á haciendo | Lea | Código |
|---|---|---|
| Materiales, sombreado plano, texturas procedurales o generadas por imagen, jitter de vértices (§4, §5) | references/look.md | src/lowpoly.ts, src/jitter.ts |
| Geometría personalizada, winding, partes reflejadas, superposiciones (§6, §7) | references/geometry.md | src/geometry.ts, src/overlay.ts |
| Criatura, casco, ala, kernel de triángulo puro (§6.2, §6.3) | references/creatures.md | src/tri.ts, src/organic.ts |
| Cualquier cosa que anime, humanoide, extrusión, textura (§6.4 a §6.7) | references/rigging-biped.md | src/rig.ts, src/biped.ts, src/texture.ts |
| Aspecto plano o bloqueado, atlas, chaflán, AO, sockets (§6.8) | references/detail.md | src/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.md | src/lifecycle.ts |
| Exportación de código, versiones de Three.js (§11, §12) | references/export.md | src/fingerprint.ts |
Un archivo .glb del activo (§16) | references/glb-export.md | scripts/export-glb.ts |
¿Es demasiado pesado, presupuesto de plataforma, LOD detail (§17) | references/budget.md | scripts/mesh-stats.ts, src/lod.ts |
| Rig, clips de animación, deriva, expresiones (§18) | references/rig-check.md | scripts/rig-check.ts |
| Visor GLB rápido o estudio de vista previa completo | references/studio-preview.md | HTML de vista previa rápida |
| Ejemplo pequeño completo | references/examples.md | |
| Antes de decir que un activo está terminado: puertas de QA, imagen de revisión (§13) | references/qa-gates.md | scripts/qa-asset.ts |
0. Convenciones (decida una vez, aplique en todas partes)
| Tema | Regla |
|---|---|
| Unidades | 1 unidad = 1 metro |
| Ejes | Y hacia arriba, diestro |
| Adelante | +Z (igual que glTF y Object3D.lookAt) |
| Lados | Con adelante +Z y arriba +Y, la derecha del activo es −X y su izquierda es +X (derecha = adelante × arriba) |
| Pivote | Origen en el centro de la huella, punto más bajo en Y = 0 (ver §9) |
| Nombres de caras | Nombre las caras por eje (cara +X, superior), nunca por babor/estribor/izquierda/derecha, para que una regla no pueda contradecir los ejes |
| Simetría | Construya 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 aresolveParamspor sí mismo. Tres valores predeterminados en competencia (params.seed || 12345, esquemadefault: 42, compuesto?? 101) hacen que la vista previa, los ajustes preestablecidos y el código exportado no coincidan. build…Assetes puro: los mismos parámetros resueltos dan geometría idéntica. SinMath.random,Date.now, acceso al DOM o estado mutable a nivel de módulo.- Importe
THREEnormalmente. No inyecte unTHREEInstance: 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). UnbuildAssetgené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 || 12345convierte silenciosamente la semilla0en12345. - Asigne a cada característica su propia secuencia bifurcada. Con un solo
rngcompartido, cambiarsegmentso alternarhasFruitsdesplaza 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
Setde 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
seedmáximo en 99999 o más. Los constructores compuestos derivan sub-semillas comofork(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 cambiaratlasOndeje 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…Assetllama aresolveParams - Las semillas usan
??; la semilla0funciona; sinMath.randomoDate.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.mdescrito una vez,ref.jsoncreado, PNG de máscara verificado;ref-compareejecutado 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
signedVolumepositivo, también después del reflejo;DoubleSidesolo en láminas de grosor cero - Las partes reflejadas pasan por
add()/addTrisomirrorTris, nunca unapplyMatrix4desnudo 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
metalnessreducido - 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 usanAnimationMixeren la raíz del rig - Las cadenas de extremidades pasan por
twoBoneIKo cadenas de puntos fijos; los pies y las manos tienen adelante/arriba explícitos - Las partes extruidas y perfiladas tienen
signedVolumepositivo, 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 ydisposeAssetliberamap
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
NoColorSpaceconroughness: 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
signedVolumepositivo; las cantidades de esculpido mantienen radios > 0 - La oclusión ambiental se aplica una vez (
aoShadepor parte para rigs,applyAOpara fusiones estáticas) y nunca más oscura que el piso de 0.35 - Los detalles pequeños provienen de
raycastTris/scatterOnSurface+placeTrisconsink; el lado reflejado usamirrorHit
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.tsexit 0 en la compilación actual;review.pngvisto, 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;
disposeAssetse 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/addonssolo si se usamergeGeometries) - 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
detailagregado:scripts/mesh-stats.ts(--lodspara LOD) exit 0, perfil y tipo nombrados,no revisadorepetido;detailpredeterminado 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:
- 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), ejecutescripts/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 yref.json. - 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.tsdespués de cada paso; toma menos de un segundo. - 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]