Disfraces de jugador

FreeMinecraftModels puede disfrazar a cualquier jugador conectado como un modelo cargado. Los disfraces se controlan mediante comandos, una DisguiseAPI pública y una PlayerDisguiseEntity por jugador que gestiona la invisibilidad y el renderizado del modelo para el jugador disfrazado.

Comandos

Comando	Permiso	Notas
/fmm disguise <modelID>	freeminecraftmodels.disguise.self	Disfraza al emisor. Solo para jugadores
/fmm disguise <modelID> <player>	freeminecraftmodels.disguise.self + freeminecraftmodels.disguise.others	Disfraza al jugador indicado. Funciona desde consola
/fmm undisguise	freeminecraftmodels.disguise.self	Elimina el disfraz del emisor. Solo para jugadores
/fmm undisguise <player>	freeminecraftmodels.disguise.self + freeminecraftmodels.disguise.others	Elimina el disfraz del jugador indicado. Funciona desde consola
/fmm disguiselist	freeminecraftmodels.disguise.others	Lista todos los jugadores disfrazados y el modelo bajo el que está disfrazado cada uno

El comodín freeminecraftmodels.* otorga admin, deleteall, disguise.self y disguise.others con valor predeterminado OP. También otorga el permiso freeminecraftmodels.bypassregionprotection, que se registra por separado.

Comportamiento

• Disfrazar a un jugador que ya está disfrazado reemplaza limpiamente el disfraz previo — no es necesario quitarlo antes.
• FMM oculta al jugador a los demás con setVisibleByDefault(false) y añade un efecto de poción de invisibilidad si todavía no tiene uno. Las sustituciones visuales del equipo ocultan la armadura y los objetos en las manos a los demás, sin cambiar el inventario. Estas sustituciones no se envían al propio jugador; la representación de su cuerpo sigue dependiendo del comportamiento de visibilidad del cliente.
• FMM vuelve a aplicar la invisibilidad un tick después de los eventos relevantes de eliminación o cambio de efectos, o tras reaparecer, solo si este disfraz añadió originalmente el efecto. No conserva ni restaura una invisibilidad que ya existiera al ponerse el disfraz. Al quitarlo, establece la visibilidad predeterminada en true, elimina el efecto aplicado por FMM y vuelve a enviar el equipo actual del jugador.
• La ocultación del equipo se reenvía a quienes se conectan y al cambiar de mundo. No sustituye la armadura ni los objetos reales del jugador.
• La caja de colisión del jugador no cambia. El disfraz decorativo no crea una entidad de interacción mediante paquetes y sus manejadores de clic no hacen nada, por lo que no ofrece un objetivo independiente para ataques o monturas. La invisibilidad puede afectar a comportamientos externos a FMM; no se garantiza que la selección de objetivos de las criaturas permanezca igual.
• Los disfraces no sobreviven a un reinicio del servidor, a un /fmm reload ni a que el jugador se desconecte: se rastrean en memoria y el manejador DisguiseListeners.onQuit elimina el disfraz con PlayerQuitEvent. La muerte y los cambios de mundo no quitan el disfraz.
• Un /fmm reload correcto elimina los disfraces activos durante el apagado; los jugadores deben volver a disfrazarse. Si la recarga se rechaza al preparar el contenido candidato, se conserva la ejecución activa.

Animaciones de disfraz

Cada disfraz tiene un controlador que elige animaciones según el estado del jugador antes de que se ejecute el motor de reproducción compartido de entidades modeladas. No evita ese motor. Los nombres reservados deben ir en minúsculas porque las comprobaciones de existencia del controlador distinguen mayúsculas.

Se reconocen cinco nombres de animación reservados, en este orden de prioridad (de mayor a menor):

Prioridad	Animación	Tipo	Se activa con
1	attack	un solo uso	El jugador mueve el brazo
2	jump	un solo uso	El jugador deja el suelo moviéndose hacia arriba
3	sneak	bucle	El jugador está agachado
4	walk	bucle	La posición del jugador cambió más de 0,01 bloques desde el último tick, incluido el movimiento vertical
5	idle	bucle	No se aplica nada más

Comportamientos que conviene conocer:

• Solo se consideran las animaciones que el modelo tiene realmente. Un modelo sin animación sneak simplemente pasa a walk o a idle.

• Una animación de un solo uso solicita reproducción inmediata sin bucle y pausa todas las nuevas selecciones durante 20 ticks (1 segundo a 20 TPS). Es una cuenta atrás, no la duración medida de la animación. Una animación más larga puede ser interrumpida por la siguiente selección; una más corta puede terminar antes de que se reanude la selección. Los movimientos de brazo durante la pausa se agrupan en un único ataque pendiente, mientras que las transiciones de salto no se ponen en cola.

• Los bucles solo se vuelven a emitir cuando la animación elegida cambia de verdad, así que un caminar continuo no se reinicia en cada tick.

• jump sí está realmente conectado para los disfraces, a diferencia del estado de salto (actualmente inerte) de las entidades modeladas normales. Consulta Animaciones.

• Un modelo de disfraz sin animación idle registra un aviso cada vez que se aplica el disfraz:

  Disguise model '<model>' has no 'idle' animation — disguised players using this model will freeze on the last animation frame whenever no other action is active.

  Incluye una animación idle en cualquier modelo que pienses usar como disfraz.

Clientes Bedrock

Los disfraces dependen de que FMM renderice el modelo personalizado. El valor predeterminado sendCustomModelsToBedrockClientsV2: true en config.yml habilita el envío de modelos a Bedrock. Si lo estableces en false, los jugadores Bedrock no verán el modelo, mientras que el jugador seguirá siendo invisible. La antigua clave sendCustomModelsToBedrockClients ya no se lee y no controla este comportamiento. Incluso con la opción V2 activada, los clientes siguen necesitando un paquete de recursos convertido compatible y una integración funcional con Geyser/Floodgate para renderizar el modelo.

DisguiseAPI

Los plugins de terceros pueden controlar disfraces programáticamente a través de com.magmaguy.freeminecraftmodels.api.DisguiseAPI.

import com.magmaguy.freeminecraftmodels.api.DisguiseAPI;

// Disguise (returns false if the model ID is not loaded)
boolean ok = DisguiseAPI.disguise(player, "dragon");

// Undisguise (returns true if a disguise was removed)
DisguiseAPI.undisguise(player);

// Queries
boolean isDisguised = DisguiseAPI.isDisguised(player);
String modelID = DisguiseAPI.getDisguiseModelID(player); // null if not disguised

// Unmodifiable snapshot of all disguised players
Collection<Player> all = DisguiseAPI.getDisguisedPlayers();

La API es el punto de entrada público y seguro frente a refactorizaciones. Los plugins deben llamar a DisguiseAPI en lugar del DisguiseManager interno.

La API no comprueba los permisos de los comandos ni normaliza los ID de modelo. Pasa un jugador conectado y un ID cargado exacto. disguise elimina el disfraz actual antes de intentar crear el reemplazo, por lo que un ID desconocido devuelve false después de quitar el anterior. El comando comprueba primero el modelo y conserva el disfraz anterior si el ID es inválido. Un resultado correcto de la API confirma la creación, no el renderizado en el cliente ni la aceptación del paquete de recursos.

Casos de uso comunes

• Servidores de rol y RPG: disfrazar jugadores como modelos de jefes para cinemáticas o scripts de misiones.
• Organización de eventos: disfrazar a un presentador como un modelo personalizado gigante.
• Monturas y vehículos: combinar /fmm mount con /fmm disguise para configuraciones creativas de transporte.
• Integración con EliteMobs: los scripts de jefe pueden disfrazar al jugador que desencadenó un evento para un efecto temporal de transformación.

Solución de problemas

No pasa nada cuando ejecuto /fmm disguise dragon. El ID del modelo debe coincidir exactamente con un modelo cargado. Consulta /fmm admin o el autocompletado del comando para verificar el nombre del modelo. La variante con jugador objetivo comprueba freeminecraftmodels.disguise.others antes de resolver el modelo o el jugador, e informa directamente de ese permiso faltante.

Mi disfraz desapareció después de /fmm reload. Es lo esperado tras una recarga completa correcta. Escucha FmmReloadedEvent, programado en el hilo principal 40 ticks después de la inicialización, si necesitas volver a aplicar los disfraces automáticamente. Una preparación rechazada no elimina la ejecución activa.

Los jugadores Bedrock no pueden ver el disfraz. Consulta Clientes Bedrock más arriba.

El jugador disfrazado sigue siendo visible para los demás. Comprueba si el jugador ya tenía invisibilidad al ponerse el disfraz: FMM no se hace responsable de ese efecto y no lo restaura si desaparece. Revisa también los plugins que cambien la visibilidad, los efectos o los paquetes de equipo del jugador. FMM usa tanto la visibilidad del jugador como un efecto de poción real, además de sustituciones visuales del equipo; confirma el comportamiento en conflicto antes de cambiar la configuración de otro plugin.