Cosmetics

Cosméticos 3D, cosméticos de modelos de objetos y skins con menús de armario y almacenamiento por jugador.

Privadasv0.0.2Menús y visuales

RequiereTypeWriter0.9GUIEntityCraftEngineopcionalProfilesopcional

Creada para la red BornToCraft. Esta extensión está documentada como referencia y no se distribuye.

Soporte

Descripción general

Cosmetics permite a los jugadores vestirse y personalizar su equipo. Cubre dos tipos de cosméticos. Los cosméticos de entidad son modelos 3D (un sombrero, una mochila, alas, un halo) que siguen al jugador, con partículas opcionales. Los cosméticos de objeto cambian el modelo de un objeto real que lleva el jugador, como una pieza de armadura o una espada, de modo que el nuevo aspecto también se ve cuando el objeto se sostiene, se lleva puesto o se suelta. Una función aparte de skins aplica un revestimiento al objeto que el jugador tiene en la mano.

Los jugadores eligen cosméticos en un menú de guardarropa con una pestaña por categoría. Un cosmético está disponible cuando no tiene permiso, cuando el jugador posee su permiso, o cuando un administrador u otra entrada lo ha desbloqueado. Los cosméticos equipados y desbloqueados se guardan por jugador en artefactos.

La extensión funciona en la compilación BTC de TypeWriter (BTC Core, Paper/Folia) y se documenta aquí como referencia. La versión 0.0.2 es una versión temprana.

Características

• Cosméticos de entidad — asocia cualquier definición de entidad (un item display, un modelo de BetterModel…) a un jugador, relativa al cuerpo o a la cabeza, o fija.
• Cosméticos de objeto — sustituye el item_model y el aspecto al llevarlo de los objetos coincidentes, y los restaura cuando se quita el cosmético.
• Partículas — asocia efectos de partículas a un cosmético.
• Categorías y pestañas — agrupa cosméticos en categorías, una pestaña por categoría, con un filtro de posesión (todos, poseídos, no poseídos).
• Uno por categoría — un jugador lleva un cosmético por categoría a la vez.
• Desbloqueos — gratuitos, por permiso, por comando o desde otras entradas.
• Skins — revestimientos para el objeto sostenido, elegidos en un menú específico, que se eliminan cuando se suelta el objeto.
• Cosméticos en entidades — asocia un cosmético a un NPC u otra entidad con datos de entidad.
• Placeholders y facts — muestra recuentos en otros plugins y comprueba la posesión en criterios.

Instalación

1. Instala la extensión GUI (GuiAndDialogs en la compilación BTC), usada por ambos menús.
2. Instala la extensión Entity de TypeWriter, u otra extensión que proporcione definiciones de entidad, para los cosméticos de entidad. Los cosméticos de objeto y las skins no la necesitan.
3. Opcional: instala CraftEngine si tus cosméticos de objeto apuntan a objetos de CraftEngine, y la extensión Profiles si los cosméticos deben seguir al perfil activo.
4. Coloca el JAR de Cosmetics en plugins/Typewriter/extensions/ y reinicia el servidor.
5. Proporciona los modelos en tu paquete de recursos: claves item_model para los cosméticos de objeto y las skins (Minecraft 1.21.4 o posterior), y texturas assets/<namespace>/textures/entity/equipment/ para los aspectos de armadura puesta.

Primeros pasos

Crea un sombrero que los jugadores desbloqueen con un permiso:

1. En el panel web de TypeWriter, abre una página de manifest y añade una entrada Cosmetic Category. Llámala Hats y elige un icon.
2. Añade una entrada Cosmetic Definition. Establece category con el ID de la entrada de categoría (o su nombre si no tiene ID), priority, un menuIcon y permission (por ejemplo cosmetics.hat.top_hat).
3. En model, haz referencia a una definición de entidad, por ejemplo un item display que contenga el modelo de tu sombrero. Establece rotationMode en RELATIVE_TO_HEAD y ajusta offset y rotationOffset.
4. Añade un artefacto Player Cosmetics para que se guarden los cosméticos equipados y desbloqueados. Deja artifactId para que lo genere el panel web.
5. Añade una acción BTC Cosmetics Menu. Construye su layout en layoutPool, con los cinco marcadores cosmetics_button: descritos en Menús, y establece baseMenuId si usas un chasis de menú compartido.
6. Publica. Da el permiso a un jugador de pruebas, o ejecuta /tw cosmetics give <player> <cosmetic entry id>, luego ejecuta /tw cosmetics y equipa el sombrero.

Usa el ID de la entrada

La lista de desbloqueos, la lista de equipados, el comando give y el fact Has Cosmetic identifican un cosmético por su ID de entrada, no por el campo cosmeticId. El campo cosmeticId solo se muestra como el token {cosmetic_id} en los menús.

Cómo funciona

Una definición es un cosmético de objeto cuando tiene un itemModel o un equipmentAssetId, y además lista applicableCraftEngineIds o applicableItems. Cualquier otra definición es un cosmético de entidad y usa model. Los cosméticos de objeto se aplican a los objetos coincidentes del inventario del jugador en cada tick de la actualización, y el modelo original se conserva en el objeto para poder restaurarlo.

Menús

El BTC Cosmetics Menu es una entrada de GUI con una vista por categoría, generada a partir de tus entradas Cosmetic Category. Una categoría usada por un cosmético pero nunca declarada aparece igualmente como pestaña. Coloca estos marcadores en tu layout con la etiqueta cosmetics_button:<TYPE>:

Marcador	Dónde	Qué hace
CATEGORY_TAB	Repetible	Una pestaña por categoría. Tokens: {category_id}, {category_name}, {owned}, {total}.
COSMETIC_SLOT	Repetible	Una ranura por cosmético de la pestaña activa, ordenados por priority. El clic lo equipa, o lo desequipa cuando ya está puesto. Los cosméticos no poseídos se muestran pero están inertes. Tokens: {cosmetic_id}, {cosmetic_name}, {category_name}, {state}.
SORT_TOGGLE	Una vez	Alterna entre todos, poseídos y no poseídos. Token: {current_filter}. El filtro se restablece cuando el jugador se va.
CLEAR_CATEGORY	Una vez	Desequipa el cosmético de la pestaña activa.
PAGE_NAV	Una vez	Clic izquierdo para la página siguiente, clic derecho para la anterior. Tokens: {page}, {total_pages}, {page_indicator}. Oculto cuando basta una página.

categoryView es una plantilla clonada para cada categoría (su nombre acepta {category_name} y {category_id}), y categoryViewIdPrefix (por defecto cosmetic_) antepone un prefijo a los ids de vista. No hay un marcador de cerrar ni de indicador de página: el cierre lo gestiona el chasis y el contador lo lleva PAGE_NAV. Los textos por defecto de estos botones están en francés.

El menú de skins es independiente: se abre con la acción Open Skins Menu o /tw skins, muestra las skins que se aplican al objeto de la mano principal del jugador y su disposición la define la entrada Skins Menu Config (skinSlots, plantillas para skins desbloqueadas, activas y bloqueadas, y los botones). El clic izquierdo en una skin desbloqueada la aplica, y los botones quitan la skin o la aplican a todos los objetos compatibles del inventario. Un objeto con skin que se suelta pierde su skin.

Configuración

Los cosméticos y las skins se almacenan mediante dos artefactos, cargados aproximadamente un segundo después del inicio y guardados unos segundos después de cada cambio:

• Player Cosmetics almacena, por jugador, los cosméticos desbloqueados y el equipado de cada categoría.
• Player Skins almacena las skins desbloqueadas y la skin seleccionada de cada tipo de objeto.

Perfiles y datos almacenados

Cuando la extensión Profiles está instalada, los cosméticos equipados se almacenan bajo el perfil activo del jugador en lugar de su UUID. Los cosméticos guardados antes bajo el UUID no se eliminan, pero dejan de encontrarse. En un servidor que ya contiene datos reales de jugadores, migra las claves antes de instalar o actualizar con Profiles presente. Los desbloqueos se almacenan siempre por UUID del jugador.

Comandos

Los comandos de Cosmetics son subcomandos del comando de TypeWriter, por lo que empiezan por /typewriter o /tw.

Comando	Descripción
/tw cosmetics o /tw cosmetics open	Abre el menú de cosméticos. Requiere cosmetics.use.
/tw cosmetics give <player> <cosmetic>	Desbloquea un cosmético, indicado por su ID de entrada. Requiere cosmetics.admin.
/tw cosmetics remove <player> <cosmetic>	Elimina un desbloqueo. Requiere cosmetics.admin.
/tw cosmetics reset <player>	Borra los cosméticos del jugador. Requiere cosmetics.admin.
/tw skins o /tw skins open	Abre el menú de skins para el objeto en mano. Requiere skins.use.
/tw skins give <player> <skin>	Desbloquea una skin por su skinId. Requiere skins.admin.
/tw skins remove <player> <skin>	Elimina el desbloqueo de una skin. Requiere skins.admin.
/tw skins reset <player>	Borra las skins del jugador. Requiere skins.admin.

Los clics del menú usan los comandos internos cosmetics ... y skins ..., gestionados por la extensión. No están pensados para escribirse a mano.

Permisos

Permiso	Concede
cosmetics.use	/tw cosmetics y /tw cosmetics open.
cosmetics.admin	give, remove y reset para cosméticos.
skins.use	/tw skins y /tw skins open.
skins.admin	give, remove y reset para skins.
permission del cosmético	Un permiso de tu elección que desbloquea un cosmético.
permission de la skin	Un permiso de tu elección que desbloquea una skin.

Placeholders

Son etiquetas de MiniPlaceholders de la expansión cosmetics. Sustituye cat por un ID o nombre de categoría e id por un ID de entrada de cosmético.

Placeholder	Devuelve
<cosmetics_total_unlocked>	Número de cosméticos que el jugador ha desbloqueado.
<cosmetics_total_available>	Número de definiciones de cosméticos en el servidor.
<cosmetics_category_unlocked:cat>	Cosméticos desbloqueados de la categoría.
<cosmetics_category_total:cat>	Cosméticos de la categoría.
<cosmetics_is_unlocked:id>	true o false.
<cosmetics_is_active:id>	true cuando ese cosmético está equipado.
<cosmetics_active:cat>	El ID del cosmético equipado en la categoría, vacío cuando no hay ninguno.

<cosmetics_category_unlocked:cat> cuenta solo los cosméticos desbloqueados por comando o por otras entradas, no los que están disponibles mediante un permiso.

Entradas

11 entradas, generadas a partir del código fuente de la extensión.

Acciones2

• BTC Cosmetics MenuBTC Cosmetics Menu
• Open Skins Menu ActionOpens the skins menu

Hechos2

• Has Cosmetic FactChecks if a player has a specific cosmetic unlocked.
• Has Skin FactVérifie si un joueur possède un skin spécifique.

Datos de entidad1

• Cosmetic Entity DataAttach cosmetics to an entity definition

Artefactos2

• Player Cosmetics ArtifactStores player unlocked cosmetics
• Player Skins ArtifactStores player selected skins

Manifiestos4

• Cosmetic CategoryDéfinition d'une catégorie de cosmétiques (ex: Chapeaux, Capes)
• Cosmetic DefinitionDefine a 3D Cosmetic
• Skin DefinitionDéfinition d'une catégorie de skins (wraps) pour les items
• Skins Menu ConfigConfiguration du menu des skins

Solución de problemas

El menú dice "Aucun menu de cosmétiques n'est configuré". No hay ninguna entrada BTC Cosmetics Menu publicada. /tw cosmetics abre la primera que encuentra.

Una pestaña de categoría está vacía o falta un cosmético. La category del cosmético debe coincidir con el ID de la entrada de categoría (o su nombre cuando no tiene ID), ignorando mayúsculas y minúsculas. Un nombre que no coincide con ninguna entrada de categoría crea igualmente una pestaña propia.

El modelo nunca aparece. Los cosméticos de entidad necesitan que model haga referencia a una definición de entidad. Una definición que tiene itemModel pero no applicableItems ni applicableCraftEngineIds no es un cosmético de objeto y recurre a la ruta de entidad. Para los cosméticos de objeto, la clave itemModel debe ser una clave con namespace válida (namespace:path); una clave no válida se registra una vez como "Invalid itemModel".

El modelo del objeto cambia en el inventario pero no en el cuerpo. itemModel solo cambia el aspecto del objeto en la mano y en el inventario. Para la armadura, establece también equipmentAssetId con el recurso de equipamiento del material (por ejemplo armors:enderite), sin el nombre de la pieza. Solo se aplica cuando el objeto puesto ya lleva un componente equipable.

Un objeto de CraftEngine no recibe el cosmético. Usa applicableCraftEngineIds con el id de CraftEngine (por ejemplo armors:enderite_helmet). Un objeto de CraftEngine se reconoce por su id, no por su material, así que applicableItems no coincidirá con él.

Se pierden los cosméticos equipados o los desbloqueos. Añade los artefactos a una página publicada. El registro informa de un artefacto ausente o de "has no generated artifact id", y sin ellos no se guarda nada. Si la extensión Profiles se instaló hace poco, consulta la advertencia de arriba.

Otros jugadores no ven mi cosmético. Los cosméticos de entidad son entidades falsas. Si el registro muestra "Viewer method ... unavailable ... owner-only fallback active", la extensión Entity en uso no permite espectadores adicionales y solo el dueño ve el cosmético.

/tw skins dice que no hay skin para este objeto. El objeto sostenido debe coincidir con un objeto de applicableItems de una Skin Definition que liste al menos una skin, y debe haber una entrada de menú de skins publicada. Los textos de los mensajes provienen de la entrada Skins Menu Config.

Extensiones relacionadas

• GUI — layouts y chasis de menús.
• Profiles — los cosméticos pueden seguir al perfil activo.
• BetterModel — modelos 3D utilizables como cosméticos de entidad.