Armas por código

Armas por código

Un pack de armas modeladas enteras por código (three.js): ningún archivo de modelo, ninguna imagen. Cada arma es una función que la arma en el momento, con medidas reales, sus materiales generados (acero pavonado, chapa pintada, madera laminada, polímero), el desgaste en los cantos y el oscurecido de los rincones. Las partes se mueven, y todas cuelgan de la cámara apuntando a donde mira.

Hoy trae trece cosas (nueve armas de fuego, un cuchillo y tres granadas), y se van a ir sumando más:

Son tipos genéricos: un fusil de la familia AK, una carabina de la familia AR, una pistola de servicio, un subfusil compacto, una ametralladora ligera de cinta, una escopeta de dos caños (entera y recortada), un rifle de cerrojo con mira telescópica, un revólver de doble acción, un cuchillo de combate y tres granadas de mano (fragmentación, humo y aturdidora) como tantos. No copian un modelo real, no llevan marcas de fábrica y los rótulos y números que se ven son inventados.

En la demo: la lista de armas a un costado (y «Todas juntas»: la armería, un tablero donde cuelgan todas a la misma escala, de perfil, acomodadas solas en filas según el largo de cada una, las cosas chicas de un mismo tipo juntas; las que se sumen al catálogo encuentran su lugar). Para la elegida: cinco vistas (la última, En la mano, es como la ve el jugador), un botón por cada parte que se mueve, sus acabados, el desgaste, los colores (un panel con cada zona del arma: diez colores rápidos, un selector libre y «Restablecer»), sus medidas y triángulos, la línea de código que la crea y la descarga del .glb tal como está en pantalla. Se gira arrastrando y la rueda (o dos dedos) acerca. Nada pasa por una sala: es solo la página.

Qué trae

Una carpeta, client/weapons (fogon pieces add weapons):

Las armas

Las tres granadas salen de createGrenade({ kind }); en el catálogo son tres entradas (createWeapon("smoke")).

Todas aceptan además wear (0 nueva … 1 muy gastada), occlusion (cuánto se oscurecen los rincones), textureSize (1024 por defecto; 512 arma más rápido y alcanza en un teléfono), seed y materials (para compartir los materiales entre varias). Construir una lleva unos 0,7 s con texturas de 1024 y 0,3 s con 512, y ocupa el hilo mientras tanto: hacelo al cargar, no en medio de la partida.

Colores

Todas aceptan también colors: un color por zona del arma, encima del acabado que tenga. Cada zona recibe "#rrggbb", un número (0x56603a) o un THREE.Color; la que no se nombra queda como viene.

const rifle = createWeapon("m4", { colors: { metal: "#56603a", furniture: "#b39a6b", accent: 0x1b1c1f } });

rifle.setColors({ metal: "#a32a22" });      // cambia esa zona en el momento; las demás quedan como estaban
rifle.setColors({ metal: null });           // esa zona vuelve a su color de fábrica

Es un teñido del color base, no una mano de pintura lisa: el desgaste de los cantos, el oscurecido de los rincones, los rebajes más oscuros, la veta de la madera, la aspereza y el relieve siguen ahí. setColors no reconstruye nada (reescribe los colores de los vértices, cerca de un milisegundo), así que sirve para un selector en vivo. El color es de esa arma: dos que comparten materials se tiñen cada una por su lado. Y toGlb(gun.object) lo lleva al archivo.

El catálogo las trae con su nombre: WEAPONS.pistol.zones → [{ key: "metal", name: "Corredera" }, …]. Lo que no está en ninguna zona (cerrojo, miras, pasadores, tornillos) conserva su color. Para tener en cuenta: el acero y la chapa siguen siendo metal, así que un color muy claro se ve como metal brillante más que como pintura blanca, y la madera teñida sale algo más clara que el color pedido porque la veta se le suma.

Cómo se usa en un juego

Todo está en metros. Cada arma apunta a −Z con +Y hacia arriba, el ánima sobre el eje z y el origen sobre el gatillo: colgada de una cámara, apunta a donde la cámara mira. El cuchillo apunta igual (la punta a −Z, el filo hacia abajo) con el origen en el medio del mango; las granadas están de pie (+Y), con el origen en el medio del cuerpo, la palanca del lado +Z y la anilla del lado +X. El hold de esos cuatro es para tenerlos en la mano, no para apuntar.

Una en la mano:

import { createWeapon, WEAPONS } from "./weapons";
import { studio } from "./weapons/studio";

studio(scene, renderer);                    // sin un entorno que reflejar, el acero sale negro

const gun = createWeapon("pistol", { finish: "two-tone", grips: "wood" });
const { at, turn } = WEAPONS.pistol.hold;   // dónde queda bien delante de la cámara
gun.object.position.set(...at);
gun.object.rotation.set(...turn);
camera.add(gun.object);
scene.add(camera);

createWeapon("ak47", …) devuelve lo mismo que createAk47(…), y createWeapon("pistol", …) lo mismo que createPistol(…): { object, parts, materials, info, points, pose(), setColors(), dispose() }.

Mover las partes. pose() recibe las que quieras cambiar; cada una gira o corre sobre su eje real:

gun.pose({ slide: 1 });                     // corredera atrás: asoma el cañón y se monta el martillo
gun.pose({ trigger: 0.6, safety: 1 });

// un disparo: la corredera va y vuelve en una décima de segundo
let kick = 0;
function fire() { kick = 1; }
function frame(dt: number) {
  kick = Math.max(0, kick - dt * 10);
  gun.pose({ slide: Math.sin(kick * Math.PI) });
}

Para animarlas vos, gun.parts.slide, gun.parts.magazine, etc. son nodos aparte; y el catálogo dice qué hay en cada arma: WEAPONS.ak47.parts → [{ key: "bolt", name: "Cerrojo", max: 1, about, speed }, …].

Dónde sale el fogonazo y por dónde salta la vaina. points da posiciones en el espacio del arma:

const muzzle = new THREE.Vector3(...gun.points.muzzle);
gun.object.localToWorld(muzzle);            // la boca del cañón, en el mundo: ahí va el fogonazo y nace la trazadora
const eject = gun.object.localToWorld(new THREE.Vector3(...gun.points.eject));   // la ventana de expulsión

También están rearSight, frontSight (la línea de miras, para apuntar por ellas), grip y, en el fusil, handguard (dónde van las manos). El rifle de cerrojo tiene scopeEye (dónde va el ojo para mirar por la mira); el cuchillo, tip, grip y guard; las granadas, center y top.

Tirar una granada. El pasador sale, la palanca salta y lo que vuela es el mismo objeto:

const grenade = createWeapon("frag");
grenade.pose({ pin: 1 });                   // sacó el seguro: la anilla y el pasador ya no están
grenade.pose({ lever: 0.5 });               // la palanca se abre… y en 1 ya voló (se oculta)

Varias armas, mismos materiales. Las texturas son lo más caro; se pueden hacer una vez y compartir (el wear y el seed quedan en los materiales):

import { createMaterials } from "./weapons";
const materials = createMaterials({ size: 512, wear: 0.6 });
const rifle = createWeapon("ak47", { materials });
const sidearm = createWeapon("pistol", { materials });

Al terminar, gun.dispose() libera su geometría y sus texturas. Los materiales compartidos no los toca: esos se liberan aparte, una vez, con materials.dispose().

Como archivo .glb

Si preferís cargar un archivo en vez de construir el arma (otro motor, un programa de modelado, o para no ocupar el hilo), la demo sirve estos, con CORS:

import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.js";

const loader = new GLTFLoader().setMeshoptDecoder(MeshoptDecoder);   // sin esta línea no abren
const gltf = await loader.loadAsync("https://play.fogon.page/weapons/pistol.glb");
const slide = gltf.scene.getObjectByName("slide")!;   // las partes siguen siendo nodos, con su eje
camera.add(gltf.scene);

Estos archivos están comprimidos para que pesen un tercio (los 18 juntos, 23 MB en vez de 69): las imágenes van en WebP y la geometría empaquetada con meshopt. Usan tres extensiones de glTF: EXT_texture_webp y KHR_mesh_quantization, que three.js carga solo, y EXT_meshopt_compression, que necesita el decodificador de arriba (viene con three.js). Otros programas pueden no abrirlos: para Blender, otro motor o un visor cualquiera, usá el archivo sin comprimir, que se explica abajo. La forma, los triángulos, los nodos de las partes y los colores por vértice son los mismos que los del arma construida; de muy cerca el grano fino del acero y del polímero se ve un poco más suave.

El archivo sin comprimir (glTF 2.0 común, sin ninguna extensión: imágenes JPEG y PNG, de 1,6 a 5 MB por arma) es el que entrega el botón Descargar .glb de la demo, y el que da toGlb(gun.object); por ahí sale también cualquier otra combinación (acero, otro desgaste, tus colores). En el archivo las partes se mueven a mano (no viene pose()).

tools/export.ts escribe los dos: el común en .raw/ y el comprimido en public/ (tools/squeeze.ts), y tools/compare.ts carga cada archivo al lado del arma construida y compara triángulos y partes.

Agregar un arma

1. Un archivo client/weapons/<arma>.ts que exporte create<Arma>(options) y sus tipos <Arma>Options y <Arma>Pose, armado solo con kit.ts y textures.ts (si al kit le falta una herramienta, va en kit.ts, sin nada propio de esa arma). pistol.ts es el ejemplo más corto: unas 470 líneas.
2. La convención: metros y medidas reales; apunta a −Z, +Y arriba, ánima sobre el eje z, origen sobre el gatillo; devuelve { object, parts, materials, info, points, pose(), dispose() } con points.muzzle, eject, rearSight, frontSight y grip; cada parte que se mueve es un nodo con nombre y su pivote real; wear, occlusion, textureSize, seed, materials y colors como opciones comunes. Para colors: un ZONES que diga qué acabados (Finish) forman cada zona (metal, furniture, accent como mínimo), pasado a m.build({ zones }), y setColors() en lo que devuelve (ver pistol.ts).
3. **Una entrada en WEAPONS** (index.ts): nombre, tipo, opciones con sus valores, partes, zonas (zones, con su nombre), hold (dónde cuelga de la cámara), files y, si lo que mide info.barrel no es un cañón, measure ("hoja", o null si no hay nada que medir). Con eso aparece sola en la demo; bun tools/export.ts <id> escribe sus .glb.

La vara de calidad, que se exige desde el primer intento:

• Ninguna chapa lisa: líneas de panel, rebajes y escalones de verdad, con profundidad.
• Secciones redondeadas donde agarra la mano (loft), no tablas.
• El relieve es geometría (estrías, cuadrillado, nervaduras), no un dibujo.
• Tornillos, pasadores y remaches con cabeza.
• Rótulos legibles e inventados: sin marcas ni números de serie reales.
• Rincones oscurecidos y desgaste que siga los cantos y las zonas de roce, sin manchas repetidas.
• Madera laminada por posición y sobria; polímero que se vea negro, no gris.
• Se diseña mirando la vista En la mano: es la que ve el jugador.
• Presupuesto: 12–20 mil triángulos un arma corta, 25–40 mil una larga (hasta 45 mil una con cinta de cartuchos, como la ametralladora), 4–12 mil un cuchillo o una granada.
• Se revisa en capturas (perfil, tres cuartos, primer plano, en la mano) al lado de las que ya están, misma luz.

Licencia

MIT: el código y lo que el código dibuja. Todo es nuestro; no hay modelos, imágenes ni marcas de terceros.