Notas de Creación de Modelos de FreeMinecraftModels

Esta página documenta los detalles actuales de creación que son visibles en la base de código de FreeMinecraftModels. Es intencionalmente conservadora: se enfoca en el contrato de importación/runtime, no en cada preferencia de flujo de trabajo de Blockbench.

Formatos de Origen

FreeMinecraftModels actualmente acepta:

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

El flujo de importación normal es:

1. colocar el modelo en plugins/FreeMinecraftModels/imports
2. ejecutar /fmm reload
3. dejar que FreeMinecraftModels importe el modelo al conjunto de modelos activos y reconstruya el resource pack generado

Roles de 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 en su lugar una carpeta Models en mayúscula. FreeMinecraftModels lo resuelve prefiriendo la canónica models en minúscula cuando existe, y recayendo en la heredada Models solo cuando no existe. En Windows y macOS los dos nombres son de todas formas el mismo directorio; en un sistema de archivos de Linux sensible a mayúsculas una instalación antigua sigue funcionando, pero si de algún modo existen ambos directorios, solo se lee models en minúscula. Consolídalo todo en models si encuentras ambos.

IDs 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 coincidencia de extensión no distingue mayúsculas de minúsculas, así que .BBModel y .FMModel también se aceptan

Normalización de IDs 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 encuentra una colisión:

• 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 al que le falte el array groups se pasa sin fusionar, así que sus huesos pierden sus nombres y los prefijos reservados (tag_, h_, b_, m_, hitbox) dejan de reconocerse
  • 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 Bones Significativas para el Runtime

El convertidor actual y la pipeline de esqueleto reconocen algunas convenciones de nomenclatura:

• hitbox
  • reservado para la generación de hitbox
  • debe definir la hitbox del modelo limpiamente en lugar de usarse como un bone visual
  • debe ser un bone de nivel superior en el outliner. El importador solo lo busca en el nivel raíz; un grupo hitbox anidado dentro de otro bone se trata como un bone normal
  • debe contener exactamente un cubo, que define el ancho (x), la profundidad (z) y la altura (y) del runtime. Los cubos de más registran has more than one value defining a hitbox! Only the first cube will be used; un bone hitbox vacío registra has a hitbox bone but no hitbox cube! y no se genera ninguna hitbox
  • nunca se anima (las pistas de animación que apuntan a hitbox se omiten), nunca se renderiza y queda excluido de la exportación de geometría de Bedrock. En Bedrock, un modelo sin bone hitbox recae en 1.0 x 2.0
• tag_...
  • la única forma de que un modelo obtenga un nametag. Consulta Los nametags requieren un hueso tag_ más abajo
• h_...
  • tratados como bones de cabeza
• b_...
  • bones sin visualización (ocultos en runtime). Úsalos para bones estructurales u organizativos que no deben renderizarse en el juego.
• m_...
  • bones de punto de montaje. Cada bone con este prefijo crea una posición de asiento montable en el modelo. Los jugadores o entidades pueden montarse en estas posiciones en runtime. Múltiples bones m_ crean múltiples asientos. Gestionados internamente por MountPointManager.

Estas no son solo convenciones de estilo; afectan la conversión y el comportamiento del runtime.

Los nametags requieren un hueso tag_

Esta es la causa más habitual de contenido publicado con mobs sin nombre, así que conviene decirlo sin rodeos:

Un modelo solo obtiene un nametag si contiene un hueso cuyo nombre empiece por tag_. No hay ningún respaldo.

Cómo funciona:

• Durante la importación, cualquier hueso llamado tag_... obtiene un hueso "meta" autogenerado en paralelo (fmm_nametag_bone_<name>) que queda marcado como hueso de nametag. Nada más en la canalización establece esa marca
• En runtime el esqueleto recopila esos huesos marcados, y se genera un text display en el origen del hueso tag_. Su posición y su texto siguen a ese hueso
• ModeledEntity.setDisplayName(...) y setDisplayNameVisible(...) iteran sobre esa colección. Sin un hueso tag_, la colección está vacía y ambas llamadas no hacen nada en silencio — sin error, sin advertencia, sin nombre

Por qué el nametag vanilla no te cubre:

• Un modelo dinámico oculta a los clientes su entidad viva subyacente (setVisibleByDefault(false), más la marca de invisibilidad), así que el propio nametag del mob vanilla tampoco se renderiza
• El efecto neto es un mob completamente sin nombre, aunque el plugin que llama haya establecido correctamente un nombre visible

Reglas prácticas:

• Si un modelo representa una entidad con nombre (un jefe de EliteMobs, un NPC de misión, cualquier cosa a la que un plugin llame setDisplayName), añade un hueso tag_
• Colócalo donde deba flotar el nametag — normalmente justo encima de la cabeza
• El hueso no necesita cubos; es un anclaje posicional. tag_name en particular se omite cuando se generan las definiciones de item model, así que nunca se renderiza como geometría
• Se permiten varios huesos tag_; cada uno de ellos obtiene su propio text display mostrando el mismo nombre
• Si ves nametag bone did not spawn name tag en la consola, el hueso fue reconocido pero su text display no se pudo generar — ese es un problema distinto de no tener ningún hueso tag_

Cubos Flotantes 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

Un objeto nulo se convierte en controlador IK solo cuando su entrada en el .bbmodel lleva tanto ik_source (el hueso donde empieza la cadena) como ik_target (el hueso o locator hacia el que la cadena se estira). También se lee lock_ik_target_rotation. La cadena se descubre recorriendo la jerarquía de huesos hacia arriba desde el objetivo hasta el origen, así que ambos deben estar realmente conectados.

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 importan los keyframes de posición de un objeto nulo: se convierten en el desplazamiento del objetivo de IK. Las pistas de rotación y escala de un objeto nulo se ignoran

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.

Display Model JSON (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.

Durante la importación, FMM copia el JSON en la salida del resource pack y reescribe automáticamente cualquier referencia de textura simple dentro de él para que apunte a las texturas extraídas del modelo. Si no existe un JSON hermano, el ítem se muestra como papel simple en el juego.

Configuración Personalizada de Ítem en YML

El archivo de configuración .yml hermano (mismo nombre base que el modelo) ahora admite campos opcionales de ítem. Si se establece material:, el modelo también está disponible como un ítem personalizado que se puede sostener. El formato YML completo es:

isEnabled: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD      # optional — if set, model is also a custom item
name: '&b&lMy Custom Sword'  # optional — display name
lore:                         # optional
  - '&7A custom weapon'
enchantments:                 # optional — format: ENCHANTMENT_NAME,LEVEL
  - SHARPNESS,5
  - FIRE_ASPECT,2

Cuando material: está presente, el modelo aparece en el explorador de contenido de administración junto a los props y puede entregarse a los jugadores como un ítem funcional.

Notas de Bedrock y Ruta 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 los nombres reservados de bones virtuales intencionalmente (hitbox, tag_, h_, b_, m_) — y recuerda que cualquier modelo que deba mostrar un nombre necesita un hueso tag_ o quedará sin nombre en silencio
• nombra las animaciones de estado spawn, idle, walk, attack y death si quieres que se disparen automáticamente; todo lo demás es una animación personalizada que activas tú mismo (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 soporta estados de animación de tensado automáticos para ítems personalizados de arco y ballesta. No se necesita configuración -- simplemente nombra tus archivos de modelo con los sufijos correctos y FMM detecta el conjunto de estados automáticamente durante la generación del resource pack.

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/imports/
  cool_bow_idle.bbmodel
  cool_bow_draw_start.bbmodel
  cool_bow_draw_half.bbmodel
  cool_bow_draw_full.bbmodel
  cool_bow.yml                  <-- config uses the base name, not _idle

Para una ballesta agregarías un quinto archivo, cool_bow_charged.bbmodel.

Cómo Funciona la Detección

• La detección ocurre automáticamente cuando se genera el resource pack (al iniciar o con /fmm reload).
• Solo el modelo _idle obtiene un JSON de definición de ítem en el paquete de salida. Los estados de tensado y cargado se referencian como entradas condicionales dentro de esa definición.
• Solo el nombre base obtiene un archivo de configuración YML. Para el ejemplo anterior, la configuración es cool_bow.yml, no cool_bow_idle.yml.

Display Model JSON

Cada modelo de estado puede tener su propio archivo .json de display model hermano (ej. cool_bow_idle.json, cool_bow_draw_full.json). FMM los conecta automáticamente en la definición de ítem generada. Consulta Salida del Resource Pack para la estructura JSON exacta que se genera.

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.

Los nombres de textura se normalizan a minúsculas y deben terminar en .png: por ejemplo, body.PNG y body.jpg se resuelven como textures/body.png. Evita nombres que solo se diferencien por mayúsculas.