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

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

Compatibilidad con Blockbench

• FreeMinecraftModels detecta la versión del archivo de Blockbench durante la importación
• El importador actual todavía contiene ramas de compatibilidad para versiones anteriores a Blockbench v5
• 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
• tag_...
  • tratados como bones virtuales relacionados con nametag
• 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_... o mount_...
  • 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 de montaje crean múltiples asientos. Gestionados internamente por MountPointManager.

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

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
• análisis de locators

Restricción práctica importante:

• La búsqueda de controladores IK 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

División de Salida 1.21.4+

Para Minecraft 1.21.4+, FreeMinecraftModels genera archivos de definición de modelos de ítems bajo:

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

Las versiones más antiguas todavía usan la ruta heredada de modelos de ítems. Si estás verificando la salida generada mientras creas, asegúrate de estar mirando la forma de salida correcta para tu versión de servidor.

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      # opcional — si se establece, el modelo también es un ítem personalizado
name: '&b&lMy Custom Sword'  # opcional — nombre de visualización
lore:                         # opcional
  - '&7A custom weapon'
enchantments:                 # opcional — formato: 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 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_, mount_)
• 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                  <-- la configuración usa el nombre base, no _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.