Cosmetics

Cosméticos 3D, cosméticos de modelo de item e skins com menus de guarda-roupa e armazenamento por jogador.

Privadasv0.0.2Menus e visuais

RequerTypeWriter0.9GUIEntityCraftEngineopcionalProfilesopcional

Criada para a rede BornToCraft. Esta extensão é documentada como referência e não é distribuída.

Suporte

Visão geral

O Cosmetics permite que os jogadores se vistam e personalizem seus equipamentos. Ele cobre dois tipos de cosméticos. Os cosméticos de entidade são modelos 3D (um chapéu, uma mochila, asas, uma auréola) que seguem o jogador, com partículas opcionais. Os cosméticos de item alteram o modelo de um item real que o jogador carrega, como uma peça de armadura ou uma espada, de modo que a nova aparência também aparece quando o item é segurado, vestido ou solto. Um recurso separado de skins aplica um revestimento ao item na mão do jogador.

Os jogadores escolhem os cosméticos em um menu de guarda-roupa com uma aba por categoria. Um cosmético está disponível quando não tem permissão, quando o jogador possui sua permissão, ou quando um administrador ou outra entry o desbloqueou. Os cosméticos equipados e desbloqueados são salvos por jogador em artifacts.

A extensão roda na build BTC do TypeWriter (BTC Core, Paper/Folia) e é documentada aqui como referência. A versão 0.0.2 é uma versão inicial.

Recursos

• Cosméticos de entidade — anexe qualquer definição de entidade (um item display, um modelo do BetterModel…) a um jogador, relativa ao corpo ou à cabeça, ou fixa.
• Cosméticos de item — substitua o item_model e a aparência vestida de itens correspondentes e restaure-os quando o cosmético for removido.
• Partículas — anexe efeitos de partículas a um cosmético.
• Categorias e abas — agrupe cosméticos em categorias, uma aba por categoria, com um filtro de posse (todos, possuídos, não possuídos).
• Um por categoria — o jogador usa um cosmético por categoria de cada vez.
• Desbloqueios — gratuitos, por permissão, por comando ou a partir de outras entries.
• Skins — revestimentos para o item na mão, escolhidos em um menu dedicado e removidos quando o item é solto.
• Cosméticos em entidades — anexe um cosmético a um NPC ou outra entidade com dados de entidade.
• Placeholders e facts — mostre contagens em outros plugins e teste a posse em criteria.

Instalação

1. Instale a extensão GUI (GuiAndDialogs na build BTC), usada pelos dois menus.
2. Instale a extensão Entity do TypeWriter, ou outra extensão que forneça definições de entidade, para os cosméticos de entidade. Os cosméticos de item e as skins não precisam dela.
3. Opcional: instale o CraftEngine se seus cosméticos de item têm como alvo itens do CraftEngine, e a extensão Profiles se os cosméticos devem acompanhar o perfil ativo.
4. Coloque o JAR do Cosmetics em plugins/Typewriter/extensions/ e reinicie o servidor.
5. Forneça os modelos no seu resource pack: chaves item_model para cosméticos de item e skins (Minecraft 1.21.4 ou posterior) e texturas em assets/<namespace>/textures/entity/equipment/ para as aparências de armaduras vestidas.

Primeiros passos

Crie um chapéu que os jogadores desbloqueiam com uma permissão:

1. No painel web do TypeWriter, abra uma página de manifest e adicione uma entry Cosmetic Category. Dê a ela o nome Hats e escolha um icon.
2. Adicione uma entry Cosmetic Definition. Defina category com o ID da entry da categoria (ou seu nome, se ela não tiver ID), priority, um menuIcon e permission (por exemplo cosmetics.hat.top_hat).
3. Em model, referencie uma definição de entidade, por exemplo um item display que contenha o modelo do seu chapéu. Defina rotationMode como RELATIVE_TO_HEAD e ajuste offset e rotationOffset.
4. Adicione um artifact Player Cosmetics para que os cosméticos equipados e desbloqueados sejam salvos. Deixe artifactId para o painel web gerar.
5. Adicione uma action BTC Cosmetics Menu. Construa seu layout em layoutPool, com os cinco marcadores cosmetics_button: descritos em Menus, e defina baseMenuId se usar uma base de menu compartilhada.
6. Publique. Dê a permissão a um jogador de teste, ou execute /tw cosmetics give <player> <cosmetic entry id>, e depois execute /tw cosmetics e equipe o chapéu.

Use o ID da entry

A lista de desbloqueios, a lista de equipados, o comando give e o fact Has Cosmetic identificam um cosmético pelo seu ID da entry, não pelo campo cosmeticId. O campo cosmeticId só é exibido como o token {cosmetic_id} nos menus.

Como funciona

Uma definição é um cosmético de item quando tem um itemModel ou um equipmentAssetId e também lista applicableCraftEngineIds ou applicableItems. Toda outra definição é um cosmético de entidade e usa model. Os cosméticos de item são aplicados aos itens correspondentes no inventário do jogador a cada tick da atualização, e o modelo original é mantido no item para que possa ser restaurado.

Menus

O BTC Cosmetics Menu é uma entry de GUI com uma view por categoria, gerada a partir das suas entries Cosmetic Category. Uma categoria usada por um cosmético, mas nunca declarada, ainda aparece como uma aba. Coloque estes marcadores no seu layout com a tag cosmetics_button:<TYPE>:

Marcador	Onde	O que faz
CATEGORY_TAB	Repetível	Uma aba por categoria. Tokens: {category_id}, {category_name}, {owned}, {total}.
COSMETIC_SLOT	Repetível	Um slot por cosmético da aba ativa, ordenado por priority. Clicar equipa, ou desequipa quando já está vestido. Os cosméticos não possuídos são exibidos, mas inertes. Tokens: {cosmetic_id}, {cosmetic_name}, {category_name}, {state}.
SORT_TOGGLE	Uma vez	Alterna entre todos, possuídos e não possuídos. Token: {current_filter}. O filtro é redefinido quando o jogador sai.
CLEAR_CATEGORY	Uma vez	Desequipa o cosmético da aba ativa.
PAGE_NAV	Uma vez	Clique esquerdo para a próxima página, clique direito para a anterior. Tokens: {page}, {total_pages}, {page_indicator}. Oculto quando uma página basta.

categoryView é um template clonado para cada categoria (seu nome aceita {category_name} e {category_id}), e categoryViewIdPrefix (padrão cosmetic_) prefixa os ids das views. Não há marcador de fechar nem de indicador de página: o fechamento é tratado pela base e o contador é carregado por PAGE_NAV. Os textos padrão desses botões estão em francês.

O menu de skins é separado: ele abre com a action Open Skins Menu ou /tw skins, mostra as skins que se aplicam ao item na mão principal do jogador e é organizado pela entry Skins Menu Config (skinSlots, templates para skins desbloqueadas, ativas e bloqueadas, e os botões). O clique esquerdo em uma skin desbloqueada a aplica, e os botões removem a skin ou a aplicam a todos os itens compatíveis do inventário. Um item com skin que é solto perde sua skin.

Configuração

Os cosméticos e as skins são armazenados por meio de dois artifacts, carregados cerca de um segundo após a inicialização e salvos alguns segundos após cada alteração:

• Player Cosmetics armazena, por jogador, os cosméticos desbloqueados e o equipado de cada categoria.
• Player Skins armazena as skins desbloqueadas e a skin selecionada de cada tipo de item.

Perfis e dados armazenados

Quando a extensão Profiles está instalada, os cosméticos equipados são armazenados sob o perfil ativo do jogador em vez de seu UUID. Os cosméticos salvos anteriormente sob o UUID não são excluídos, mas deixam de ser encontrados. Em um servidor que já contém dados reais de jogadores, migre as chaves antes de instalar ou atualizar com o Profiles presente. Os desbloqueios são sempre armazenados por UUID do jogador.

Comandos

Os comandos do Cosmetics são subcomandos do comando do TypeWriter, então começam com /typewriter ou /tw.

Comando	Descrição
/tw cosmetics ou /tw cosmetics open	Abre o menu de cosméticos. Exige cosmetics.use.
/tw cosmetics give <player> <cosmetic>	Desbloqueia um cosmético, indicado pelo ID da entry. Exige cosmetics.admin.
/tw cosmetics remove <player> <cosmetic>	Remove um desbloqueio. Exige cosmetics.admin.
/tw cosmetics reset <player>	Limpa os cosméticos do jogador. Exige cosmetics.admin.
/tw skins ou /tw skins open	Abre o menu de skins para o item na mão. Exige skins.use.
/tw skins give <player> <skin>	Desbloqueia uma skin pelo seu skinId. Exige skins.admin.
/tw skins remove <player> <skin>	Remove o desbloqueio de uma skin. Exige skins.admin.
/tw skins reset <player>	Limpa as skins do jogador. Exige skins.admin.

Os cliques nos menus usam os comandos internos cosmetics ... e skins ..., tratados pela extensão. Eles não foram feitos para serem digitados manualmente.

Permissões

Permissão	Concede
cosmetics.use	/tw cosmetics e /tw cosmetics open.
cosmetics.admin	give, remove e reset para cosméticos.
skins.use	/tw skins e /tw skins open.
skins.admin	give, remove e reset para skins.
permission do cosmético	Uma permissão de sua escolha que desbloqueia um cosmético.
permission da skin	Uma permissão de sua escolha que desbloqueia uma skin.

Placeholders

Estas são tags MiniPlaceholders da expansão cosmetics. Substitua cat por um ID ou nome de categoria e id por um ID de entry de cosmético.

Placeholder	Retorna
<cosmetics_total_unlocked>	Número de cosméticos que o jogador desbloqueou.
<cosmetics_total_available>	Número de definições de cosméticos no servidor.
<cosmetics_category_unlocked:cat>	Cosméticos desbloqueados na categoria.
<cosmetics_category_total:cat>	Cosméticos na categoria.
<cosmetics_is_unlocked:id>	true ou false.
<cosmetics_is_active:id>	true quando esse cosmético está equipado.
<cosmetics_active:cat>	O ID do cosmético equipado na categoria, vazio quando não há nenhum.

<cosmetics_category_unlocked:cat> conta apenas os cosméticos desbloqueados por comando ou por outras entries, não aqueles disponíveis por meio de uma permissão.

Entries

11 entradas, geradas a partir do código-fonte da extensão.

Ações2

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

Fatos2

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

Dados de entidade1

• Cosmetic Entity DataAttach cosmetics to an entity definition

Artefatos2

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

Manifestos4

• 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

Solução de problemas

O menu diz "Aucun menu de cosmétiques n'est configuré". Nenhuma entry BTC Cosmetics Menu está publicada. /tw cosmetics abre a primeira que encontrar.

Uma aba de categoria está vazia ou um cosmético está faltando. category no cosmético deve corresponder ao ID da entry da categoria (ou ao nome, quando ela não tem ID), sem diferenciar maiúsculas de minúsculas. Um nome que não corresponde a nenhuma entry de categoria ainda cria uma aba própria.

O modelo nunca aparece. Os cosméticos de entidade precisam que model referencie uma definição de entidade. Uma definição que tem itemModel, mas nenhum applicableItems ou applicableCraftEngineIds, não é um cosmético de item e recorre ao caminho de entidade. Para cosméticos de item, a chave itemModel deve ser uma chave com namespace válida (namespace:path); uma chave inválida é registrada uma vez como "Invalid itemModel".

O modelo do item muda no inventário, mas não no corpo. itemModel altera apenas a aparência do item na mão e no inventário. Para armaduras, defina também equipmentAssetId com o asset de equipamento do material (por exemplo armors:enderite), sem o nome da peça. Ele só é aplicado quando o item vestido já carrega um componente equipável.

Um item do CraftEngine não recebe o cosmético. Use applicableCraftEngineIds com o id do CraftEngine (por exemplo armors:enderite_helmet). Um item do CraftEngine é reconhecido pelo seu id, não pelo material, então applicableItems não o corresponderá.

Os cosméticos equipados ou os desbloqueios se perdem. Adicione os artifacts a uma página publicada. O log informa um artifact ausente ou "has no generated artifact id", e nada é salvo sem eles. Se a extensão Profiles foi instalada recentemente, veja o aviso acima.

Outros jogadores não veem o meu cosmético. Os cosméticos de entidade são entidades falsas. Se o log mostrar "Viewer method ... unavailable ... owner-only fallback active", a extensão Entity em uso não permite espectadores extras e apenas o dono vê o cosmético.

/tw skins diz que não há skin para este item. O item na mão deve corresponder a um item em applicableItems de uma Skin Definition que liste pelo menos uma skin, e uma entry de menu de skins deve estar publicada. Os textos das mensagens vêm da entry Skins Menu Config.

Extensões relacionadas

• GUI — layouts e base de menu.
• Profiles — os cosméticos podem acompanhar o perfil ativo.
• BetterModel — modelos 3D utilizáveis como cosméticos de entidade.