Notas de creación de modelos de FreeMinecraftModels

Estas notas describen los archivos de modelo, sus archivos complementarios y los nombres que FreeMinecraftModels lee durante la importación y la ejecución.

Formatos de origen

FreeMinecraftModels actualmente acepta:

• archivos .bbmodel para importaciones de fuente editable
• archivos .fmmodel para datos de modelo listos para runtime

Para un .bbmodel suelto sin archivos complementarios:

1. colócalo directamente en plugins/FreeMinecraftModels/imports, con la extensión .bbmodel en minúsculas
2. ejecutar /fmm reload
3. comprueba que su conversión .fmmodel aparezca en la carpeta de modelos activa y que la recarga termine correctamente

El importador de archivos sueltos deja el original en imports, por lo que las siguientes importaciones lo convierten otra vez. No recoge archivos .json o .yml complementarios sueltos ni acepta un .fmmodel suelto. Para conjuntos de modelos creados por ti, guarda los modelos y sus complementos juntos en la carpeta models activa o usa un paquete de contenido con la estructura correcta. Se omiten las subcarpetas de imports que no tengan pack.meta. Una recarga rechazada puede dejar activo el catálogo anterior; revisa la consola.

La conversión de archivos sueltos conserva únicamente source, id y name de las texturas y descarta los metadatos de dimensiones y tiempos de animación. También requiere un array textures. Si necesitas conservar esos metadatos, usa la carpeta de modelos activa o un paquete que preserve el archivo original; el lector de modelos en ejecución sí acepta la ausencia del array de texturas.

Función de las carpetas

plugins/FreeMinecraftModels/imports
plugins/FreeMinecraftModels/models
plugins/FreeMinecraftModels/models_disabled

• imports es la carpeta de recepción para importaciones manuales de modelos y descargas de paquetes oficiales antes del procesamiento
• models contiene contenido de modelos activos instalados
• models_disabled contiene contenido de paquetes descargados o instalados que está actualmente desactivado

Las instalaciones antiguas pueden tener una carpeta Models con mayúscula inicial. FreeMinecraftModels prefiere models en minúsculas si existe y usa Models en caso contrario. En un sistema de archivos que no distingue mayúsculas, ambos nombres corresponden al mismo directorio. En uno que sí las distingue pueden coexistir, y el importador compartido de paquetes prefiere actualmente un destino Models existente mientras el motor lee models en minúsculas. Haz una copia de seguridad y unifica el contenido en models con el servidor detenido para evitar que las importaciones acaben fuera de la carpeta activa.

ID de modelos

• Los IDs de modelo del runtime provienen del nombre del archivo, sin la extensión .bbmodel o .fmmodel
• Usa nombres de archivo estables y únicos porque el ID es lo que los comandos y las llamadas API resuelven
• Las referencias de animación de Blockbench son basadas en nombre, por lo que la nomenclatura duplicada o poco clara dentro del modelo es más propensa a causar problemas que un esquema de nomenclatura limpio y explícito
• La lectura de extensiones en la carpeta de modelos activa no distingue mayúsculas, por lo que acepta .BBModel y .FMModel. La importación de archivos sueltos desde imports solo reconoce .bbmodel en minúsculas

Normalización de ID y colisiones

El nombre del archivo se normaliza antes de convertirse en el ID de modelo del runtime y en el nombre de archivo del resource pack:

1. se pasa a minúsculas
2. cada carácter fuera de a-z, 0-9, ., _ y - se reemplaza por _

Así que My Table.bbmodel, my table.bbmodel y my_table.bbmodel se normalizan todos al mismo ID, my_table.

Antes de ejecutar cualquier conversión, FreeMinecraftModels barre todo el árbol de modelos y comprueba si hay archivos que se normalicen al mismo ID. Cuando todos los archivos con ese ID son idénticos byte a byte, como ocurre cuando dos paquetes de contenido distribuyen el mismo modelo, FMM carga aquel cuya ruta absoluta va primero en orden y omite las copias sin aviso. Cuando los archivos difieren:

• se rechazan todos los archivos en conflicto — no se carga ninguno, así que no hay un silencioso "gana el último"
• el ID de modelo queda bloqueado durante el resto de esa pasada de carga
• los modelos rechazados también se excluyen de la exportación del paquete de entidades personalizadas de Bedrock
• la consola recibe:

[FMM Models] Rejected normalized model ID collision '<id>'. These files normalize to the same ID: <paths>. Rename the files so every normalized model ID is unique; no colliding model was loaded.

La solución es siempre renombrar los archivos para que los IDs normalizados sean distintos. La costumbre más segura es nombrar los archivos de modelo en minúsculas y con guiones bajos desde el principio (stone_table.bbmodel), lo que hace que el nombre de archivo y el ID del runtime sean idénticos y elimina cualquier posibilidad de una colisión sorpresa.

Compatibilidad con Blockbench

• FreeMinecraftModels lee meta.format_version del .bbmodel y se ramifica según su número mayor
• Un bloque meta ausente, un format_version ausente o un valor que no se puede analizar recaen todos en la versión 4, con una línea de info/advertencia que indica el modelo
• Un array textures ausente se acepta y se trata como una lista de texturas vacía en lugar de hacer fallar al importador. El exportador de entidades personalizadas de Bedrock omite entonces ese modelo, porque la exportación a Bedrock requiere al menos una textura
• Los nombres de archivo de textura extraídos se normalizan a una única extensión .png. Un nombre de origen como body.jpg, body.PNG o body se escribe y se referencia como body.png
• format_version 4.x y anteriores: los huesos se leen directamente del árbol outliner, que lleva los nombres de hueso en línea
• format_version 5.x y posteriores: el esquema del outliner cambió. outliner es ahora un árbol anidado de cadenas UUID sueltas y diccionarios {uuid, isOpen, children} sin ninguna clave de nombre, mientras que un array plano groups aparte contiene los datos reales de los huesos (incluido name). FMM une ambos por UUID — cada nodo del outliner se reemplaza por su entrada correspondiente en groups, y luego los hijos se fusionan recursivamente — de modo que los nombres, orígenes y rotaciones de los huesos se resuelven con normalidad
• Consecuencias que conviene conocer al editar a mano o generar archivos .bbmodel:
  • Un archivo v5 sin el array groups se pasa sin fusionar. Un outliner ya fusionado puede funcionar; los nodos de grupo v5 sin nombre pueden hacer fallar la carga cuando el lector del esqueleto espera un nombre
  • Los UUID deben coincidir exactamente entre outliner y groups; un nodo del outliner sin grupo correspondiente se conserva tal cual en lugar de descartarse
  • No mezcles un format_version v5 con un outliner con forma v4, ni al revés — la rama se elige a partir de la versión declarada, no de la forma real
• Si los registros de importación dicen que el formato del modelo no es compatible con FreeMinecraftModels, trata eso como un problema de formato del modelo primero, no como un problema de wiki o de comandos

Convenciones de huesos que afectan a la ejecución

El conversor actual y el sistema del esqueleto reconocen estas convenciones de nombres:

• hitbox
  • reservado para generar la caja de colisión
  • debe definir claramente la caja de colisión del modelo, sin usarse como hueso visual
  • debe ser un hueso de nivel superior del outliner para definir la colisión durante la ejecución. Un hitbox anidado pasa por el análisis de huesos ordinario, pero permanece oculto y no define la caja de colisión del modelo
  • debe contener exactamente un cubo, que define el ancho (x), la profundidad (z) y la altura (y). Los cubos adicionales registran has more than one value defining a hitbox! Only the first cube will be used. Un grupo vacío registra has a hitbox bone but no hitbox cube! y deja dimensiones cero; no equivale a la ausencia de hitbox. Los desplazamientos y las rotaciones del cubo no se convierten en un desplazamiento de la caja: el lector usa longitudes absolutas de los lados y un desplazamiento de modelo cero
  • nunca se anima (se omiten las pistas dirigidas a hitbox), nunca se renderiza y se excluye de la exportación de geometría de Bedrock. En Bedrock, un modelo sin este hueso usa 1.0 x 2.0
• tag_...
  • anclaje opcional de etiqueta de nombre definido en el modelo. Consulta Posición de la etiqueta de nombre más abajo
• h_...
  • se tratan como huesos de cabeza
• b_...
  • huesos sin visualización en Java. Usa huesos sin cubos para la estructura: la exportación de geometría Bedrock no filtra el prefijo b_, por lo que sus cubos pueden seguir siendo visibles allí
• m_...
  • huesos de punto de montaje. Cada hueso con este prefijo crea un asiento para un jugador, gestionado por MountPointManager. Varios huesos m_ crean varios asientos. El gestor elige el primer asiento libre y usa una entidad Interaction temporal mientras está ocupado; su método público de montaje acepta jugadores, no entidades arbitrarias.

Los prefijos distinguen mayúsculas; el nombre hitbox se compara sin distinguirlas. Estos nombres afectan a la conversión y al comportamiento durante la ejecución.

Posición de la etiqueta de nombre

El hueso tag_ ahora es opcional. FMM usa el primer hueso tag_ en orden alfabético como anclaje de la etiqueta del modelo. Si no existe ninguno, coloca la etiqueta sobre la caja de colisión escalada, por lo que un modelo sin ese hueso puede mostrar su nombre.

Usa un hueso tag_name sin cubos cuando la posición automática no sea adecuada. Tener varios huesos de etiqueta ya no produce varias copias del mismo nombre.

La API admite nombres de varias líneas, escala, separación entre líneas y visibilidad. Las líneas se ordenan de arriba abajo, con la última en el anclaje. Consulta la guía de la API.

Sombreado de cubos y emisión de luz

• El valor light_emission de un cubo en Blockbench se conserva cuando es un número entero de 0 a 15. Cualquier otro valor se descarta con un aviso de consola que termina en with invalid light_emission. Expected an integer from 0 to 15; ignoring this value.
• Un cubo con el sombreado desactivado (shade: false) recibe además shade_direction_override: "up" en la geometría generada, para que los clientes de Minecraft 26.3 lo rendericen sin sombreado igual que los clientes anteriores. FMM aplica la misma regla a los cubos de un .json de modelo de visualización hermano. Si estableces tú mismo el valor, se conserva

Cubos sueltos

Los cubos declarados en la parte superior del outliner sin un grupo contenedor llegan como cadenas UUID sueltas en lugar de como entradas de hueso. FreeMinecraftModels los adjunta al hueso raíz autogenerado (freeminecraftmodels_autogenerated_root) para que se sigan renderizando. No son direccionables desde las animaciones, así que pon dentro de un grupo real cualquier cosa que pienses animar.

IK, Objetos Nulos y Locators

El código actual confirma soporte para:

• objetos nulos de Blockbench como controladores IK
• blueprints de cadenas IK y resolución IK en runtime (FABRIK)
• análisis de locators. Los locators también pueden servir de anclaje para efectos de partículas de Blockbench; consulta Partículas

Un objeto nulo solo se convierte en controlador IK cuando su entrada .bbmodel contiene tanto ik_source (hueso de origen) como ik_target (hueso o locator de destino). El importador busca en la jerarquía, incluidos recorridos entre hermanos y descendentes. Los hermanos de nivel raíz producen una cadena con solo el origen. lock_ik_target_rotation se lee y se guarda, pero el solucionador actual no lo aplica.

Restricciones prácticas importantes:

• El enlace origen/objetivo es por UUID, así que sobrevive a los renombrados — pero si alguno de los dos UUID falta en el modelo, la consola registra IK chain in model <model>: Could not find source bone with UUID ... / Could not find target with UUID ... y esa cadena se omite
• Si el recorrido no encuentra ningún camino del origen al objetivo, obtienes Could not find path from source to target y la cadena se omite
• La búsqueda de animaciones de un controlador es basada en nombre, por lo que la nomenclatura del controlador necesita mantenerse estable entre la estructura del modelo y los datos de animación
• Solo los fotogramas clave de posición controlan la IK. Su desplazamiento se suma a la posición de reposo del hueso o locator de destino, no a la posición de reposo guardada del controlador. Las pistas de rotación y escala no controlan la IK

Consulta Animaciones para saber cómo se controla la IK en cada frame.

División de salida 1.21.4+

FreeMinecraftModels declara api-version: 1.21.4, así que 1.21.4 es la versión mínima de servidor y la distribución moderna de definiciones de modelos de ítems es la que siempre obtendrás:

plugins/FreeMinecraftModels/output/FreeMinecraftModels/assets/freeminecraftmodels/items

En el código todavía existen las ramas heredadas (anteriores a 1.21.4) de overrides de armadura de caballo de cuero, pero ningún servidor capaz de cargar el plugin actual llega hasta ellas. Si estás leyendo notas antiguas o una carpeta de salida antigua, esa es la diferencia que estás viendo.

JSON de modelo de visualización (1.21.4+)

Los administradores pueden colocar un archivo .json hermano junto a un archivo .bbmodel o .fmmodel con el mismo nombre base (por ejemplo, table.bbmodel + table.json). Este JSON debe exportarse desde Blockbench como un modelo "Java Block/Item" y define cómo se ve el ítem cuando se sostiene en la mano o se muestra en el inventario.

FMM lee el JSON junto al archivo de modelo activo, lo copia al paquete de recursos y reescribe los valores sin espacio de nombres de su mapa textures. Las claves numéricas de textura corresponden a los índices de las texturas extraídas del modelo; una clave sin coincidencia usa una textura disponible si existe. Los valores con espacio de nombres no cambian. Si no hay JSON junto al modelo, el objeto usa la apariencia de su material base: normalmente papel para colocar un elemento decorativo, o el material configurado para un objeto que se sostiene. Un complemento mal formado registra Failed to process display model JSON for ... y no registra ese modelo de visualización.

Configuración de objetos personalizados en YML

Establece material en el YAML situado junto al modelo para registrar un objeto que se puede sostener:

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
lore:
  - "&7A blade with a fire enchantment"
enchantments:
  - "minecraft:fire_aspect,2"

Usa ID de encantamientos en minúsculas con espacio de nombres. Los materiales de cuero aceptan un sufijo de tinte RGB, como LEATHER_CHESTPLATE:ff8800; consulta Configuración. Los objetos con materiales no compatibles, encantamientos sin espacio de nombres o una lista scripts: no vacía no estarán disponibles; la consola explica el motivo y se conserva el archivo original. scripts: sigue siendo una función exclusiva de elementos decorativos.

Otras definiciones inválidas, como un isEnabled no booleano, entradas de encantamiento mal formadas, encantamientos duplicados o un nombre de archivo de objeto inválido, pueden rechazar el catálogo candidato y la recarga. Usa nombres de archivo de objetos en minúsculas con solo a-z, 0-9, ., _ y -, de hasta 128 caracteres. La búsqueda de objetos creados lee .yml, no .yaml. Obtén un objeto registrado con /fmm giveitem <item> o el navegador de administración; las recetas de elementos decorativos y las compras en la tienda producen objetos de papel para colocarlos.

Los efectos de objetos ahora pertenecen a definiciones de encantamientos. Las varitas y los bastones usan configuración de armas mágicas. Ninguno usa el antiguo sistema Lua de objetos equipados.

Notas sobre Bedrock y las rutas de renderizado

• El soporte de Bedrock depende de sendCustomModelsToBedrockClientsV2 (por defecto true; sustituye a la clave anterior sendCustomModelsToBedrockClients) y la ruta circundante de Floodgate/Geyser/resource pack
• Los clientes Java en versiones soportadas pueden usar renderizado con display entities cuando useDisplayEntitiesWhenPossible está activado
• No asumas que un modelo que se ve correcto en un cliente Java es automáticamente seguro para tu ruta de Bedrock

Consejos prácticos de creación

• mantén los nombres de archivo estables porque se convierten en IDs del runtime
• mantén la nomenclatura de controladores y animaciones explícita porque la búsqueda de animaciones de Blockbench es dirigida por nombre
• usa intencionalmente los nombres reservados de huesos virtuales (hitbox, tag_, h_, b_, m_). Añade un anclaje tag_ solo cuando la posición automática de la etiqueta sobre la caja de colisión no sea adecuada
• usa spawn, idle, walk, attack y death en minúsculas para los estados compartidos; ataque y muerte siguen necesitando que se activen durante la ejecución, y otros nombres requieren reproducción explícita (consulta Animaciones)
• un modelo pensado para /fmm disguise debería incluir al menos idle, y puede añadir sneak y jump, que solo reconoce el controlador de disfraces (consulta Disfraces de Jugador)
• valida la salida importada después de /fmm reload, no solo dentro de Blockbench
• verifica el contenido del paquete generado para tu línea objetivo de Minecraft, especialmente en 1.21.4+

Modelos de estado de arco y ballesta

FMM detecta automáticamente los estados visuales de arcos y ballestas durante la generación del paquete. Cada estado obligatorio necesita tanto un archivo de modelo cargado como un .json de visualización complementario procesado correctamente; los nombres de archivo por sí solos no bastan. Configura el objeto con su nombre base y el material BOW o CROSSBOW correspondiente.

Convención de nombres

Sufijo	Propósito	Arco	Ballesta
_idle	Ítem en mano, sin tensar ni cargado	requerido	requerido
_draw_start	Recién comenzó a tensar	requerido	requerido
_draw_half	Tensado a la mitad	requerido	requerido
_draw_full	Completamente tensado	requerido	requerido
_charged	Ballesta cargada (flecha o cohete)	--	requerido

Un arco necesita cuatro modelos (todos excepto _charged). Una ballesta necesita los cinco.

Ejemplo de distribución de archivos

plugins/FreeMinecraftModels/models/my_weapons/
  cool_bow_idle.bbmodel
  cool_bow_idle.json
  cool_bow_draw_start.bbmodel
  cool_bow_draw_start.json
  cool_bow_draw_half.bbmodel
  cool_bow_draw_half.json
  cool_bow_draw_full.bbmodel
  cool_bow_draw_full.json
  cool_bow.yml

Para una ballesta, añade también cool_bow_charged.bbmodel y cool_bow_charged.json. La configuración del objeto es cool_bow.yml, con el nombre base sin _idle.

Cómo funciona la detección

• La detección ocurre automáticamente cuando se genera el resource pack (al iniciar o con /fmm reload).
• Un conjunto completo de estados visuales obtiene una definición de objeto pública con el nombre base, como cool_bow.json. Las definiciones de objeto individuales de _idle, tensado y cargado se eliminan; su geometría sigue referenciada dentro de la definición base
• El registro de visualización expone el ID base y elimina los ID de estado. Un conjunto completo con _charged se trata como ballesta; sin él, como arco. Si faltan estados visuales, no se agrupan
• Usa el nombre base para la configuración YML, por ejemplo cool_bow.yml. El catálogo de objetos omite los archivos YML con sufijos de estado; la búsqueda de configuración de elementos decorativos también elimina el sufijo

JSON del modelo de visualización

Cada estado obligatorio debe tener su propio .json de visualización complementario, como cool_bow_idle.json y cool_bow_draw_full.json. FMM los conecta mediante la definición de objeto base generada. Consulta Salida del paquete de recursos para conocer sus condiciones y ruta de salida.

Fuera de alcance

Esta página no intenta garantizar:

• pasos exactos de la interfaz de Blockbench
• preferencias artísticas de flujo de trabajo
• cada peculiaridad heredada de .bbmodel descrita en material README local más antiguo

Esos detalles cambian más rápido que el contrato de runtime verificado anterior.