Pets

Pets companheiros colecionáveis que seguem ou flutuam sobre os jogadores, ganham XP, sobem de nível e usam skins.

Privadasv0.0.2Entidades e modelos

RequerTypeWriter0.9.0-beta-177 (BTC build)GUI (TypeWriter extension)ModelEngineopcionalUiCore (TypeWriter extension)opcional

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

Suporte

Visão geral

O Pets adiciona companheiros colecionáveis inspirados no EcoPets. Cada pet é definido uma vez no painel web (uma Pet Definition), e cada jogador possui cópias dele. Um pet é entregue como um item token: clicar com o botão direito no token adiciona o pet ao menu de companheiros do jogador. No menu, o jogador ativa um pet por vez, e esse pet flutua acima da cabeça dele, anda ao lado dele ou voa ao redor dele.

Os pets ganham experiência quando o dono mata mobs ou quando a sua história concede XP, e sobem de nível seguindo uma fórmula ou uma tabela que você escreve. Um pet pode revidar contra mobs que atingem o dono e pode ter várias skins que são desbloqueadas por criteria do TypeWriter.

Recursos

• Três modos de exibição — HEAD flutua acima do jogador, GROUND anda ao lado dele, FLY paira a uma altura definida.
• Menu de companheiros — um GUI com uma grade de pets possuídos, ativação, ocultar e mostrar, detalhes e skins.
• Itens token — os pets passam entre jogadores como itens que mantêm nível, XP, modo e skin.
• XP e níveis — uma fórmula como {level} * 100 ou uma tabela explícita, com um nível máximo.
• XP por mortes e XP de história — XP por mob morto, além de uma ação para conceder XP a partir de qualquer sequence.
• Revide — contra-ataque opcional contra mobs que ferem o dono, com dano por nível.
• Skins — várias skins de NPC por pet, cada uma com criteria, prioridade e um ícone de menu.
• Permissões de slots — bloqueie slots do menu atrás de permissões para vender slots extras de companheiros.
• Placeholders — nome, nível, XP, status e posse do pet ativo, de um slot ou de qualquer pet.
• Suporte a modelos — os pets terrestres e voadores usam qualquer definição de entidade, incluindo modelos do ModelEngine.

Instalação

1. Instale a extensão GUI, que desenha os menus.
2. Opcional: instale o ModelEngine e a extensão do TypeWriter que expõe seus modelos como definições de entidade, se os pets devem usar modelos animados.
3. Coloque o JAR do Pets em plugins/Typewriter/extensions/ e reinicie o servidor.
4. Crie um artifact Pet Storage para que os pets possuídos sejam salvos; veja Primeiros passos.

Primeiros passos

Crie um primeiro pet e entregue-o a um jogador:

1. No painel web do TypeWriter, abra uma page static e adicione um artifact Pet Storage. Sem ele, a extensão registra "No pet_storage entry found" e nada persiste.
2. Adicione uma Pet Definition. O name da própria entry é o nome de exibição do pet e seu id é o identificador do pet.
3. Escolha defaultMode. Para HEAD, opcionalmente cole uma texture em base64 para a cabeça flutuante. Para GROUND ou FLY, defina npc como uma entry de definição de entidade que será gerada ao lado do jogador.
4. Em xp, defina maxLevel e uma formula usando {level} (por exemplo {level} * 100) ou uma lista levels. Defina killReward para o XP por morte.
5. Opcional: marque combat.enabled para o revide e personalize token (o item, seu nome e lore e um brilho).
6. Adicione uma ação Pets Open Menu, defina seu storage como o seu artifact Pet Storage e dispare-a a partir de um NPC, um item ou um comando.
7. Publique e depois execute /pets give <pet> 1 como jogador. Clique com o botão direito no token, depois abra o menu e clique no pet para ativá-lo.

Para conceder XP a partir da sua história, adicione uma ação Pets Add XP com amount. Ele vai para o pet ativo do jogador. Para controlar um pet específico, use Pets State com pet e action.

Como os jogadores obtêm um pet

Não existe uma ação que desbloqueie um pet diretamente. Um pet chega a um jogador como um item token, por /pets give ou pelo botão "return to item" do menu. Execute o comando por uma ação de comando de console em uma quest ou em uma loja para torná-lo uma recompensa desbloqueável.

Como funciona

Um jogador possui no máximo um pet por definição. Apenas um pet fica ativo por vez: ativar outro desativa o primeiro. Os pets são salvos no artifact Pet Storage em segundo plano, e o pet ativo é restaurado quando o jogador entra.

Modos de exibição.

• HEAD mostra o pet acima da cabeça do jogador com headOffset aplicado. Se npc estiver definido, essa entidade é usada. Caso contrário, um armor stand invisível usa uma cabeça de jogador com texture.
• GROUND gera o npc (ou o NPC da skin selecionada) alguns blocos atrás do jogador e o faz segui-lo. swimMode decide se ele nada em líquidos: AUTO segue as capacidades da entidade, ALWAYS e NEVER forçam o comportamento.
• FLY é igual a GROUND, mas o pet paira flightHeight blocos acima do jogador.

Se um pet GROUND ou FLY não tem NPC (ou nenhuma de suas skins corresponde), ele não é exibido e um aviso é registrado no log. Um rótulo de nome com o nível é exibido acima de todo pet ativo. O modo vem de defaultMode quando o token é criado pela primeira vez e permanece com essa instância do pet.

XP e níveis. Um pet começa no nível 1. Cada entrada de levels fornece o XP total que um pet deve ter atingido para um nível, por exemplo nível 2 com 100 XP, nível 3 com 250 XP. As entradas explícitas prevalecem sobre a fórmula. A fórmula é avaliada com {level} substituído pelo nível a alcançar e aceita + - * /, parênteses e decimais. Um pet sem nenhum requisito para o próximo nível não sobe de nível.

Revide. Com combat.enabled, um pet ativo e visível contra-ataca qualquer mob que não seja jogador e que cause dano ao dono, após um curto atraso e com um cooldown de 1,5 segundo por atacante. O dano é o damage da maior entrada de levels igual ou abaixo do nível do pet. Sem uma, é 1,5 mais 0,5 por nível acima de 1.

Skins. Cada entrada de skins aponta para uma definição de NPC, uma priority e criteria. O pet usa a skin que o jogador escolheu se os criteria dela ainda corresponderem; caso contrário, usa a skin de maior prioridade cujos criteria correspondam. O campo npc da definição é a skin de reserva. Uma entrada de skin precisa de um npc, caso contrário é ignorada.

Menus

A ação Pets Open Menu abre o menu de companheiros embutido, intitulado "Compagnons". Cada pet possuído é um ícone de cabeça de jogador que mostra nível, progresso de XP e estado. O clique esquerdo ativa ou desativa o pet, o clique direito abre a tela de detalhes. A tela de detalhes mostra as estatísticas e permite ao jogador ativar, escolher uma skin (quando o pet tem mais de uma), devolver o pet a um item ou voltar. Um botão no canto inferior esquerdo mostra ou oculta o pet ativo.

As configurações do menu são campos do objeto menu da ação:

• slots — números de slots do inventário onde os pets são exibidos. O padrão são 21 slots em três linhas.
• lockedSlots — pares de slot e permission. Um slot cuja permissão o jogador não tem mostra um marcador de bloqueio, e nenhum pet pode ser colocado nele.
• maxSlots — número máximo de slots usados (padrão 21, mínimo 1): apenas as primeiras maxSlots entradas de slots são dispostas e podem receber um novo pet. Ele limita a disposição e quantos pets um jogador pode obter, não os que ele já possui.
• rows — altura do menu, de 1 a 6.
• storage — o artifact Pet Storage a usar.

A disposição de slots do último menu aberto é salva com os dados do jogador e decide quais slots um token pode ocupar. Um pet que o jogador já possui em um slot além de maxSlots (ou fora da altura do menu) não fica oculto: ele aparece em uma célula livre do menu, nunca no botão de mostrar/ocultar, e seus cliques continuam agindo no próprio slot. Se houver mais pets assim do que células livres, os excedentes continuam pertencendo ao jogador e aparecem na página Pets do menu Social compartilhado, que lista todos os pets possuídos; um aviso é registrado uma vez por jogador.

Uso no seu próprio menu. A extensão registra o prefixo de botão pets_button: para qualquer menu GUI. Defina o buttonPrefix de um item como pets_button: e seu buttonType como um destes:

buttonType	Mostra
PET_ENTRY	O pet naquela posição na lista do jogador. O clique esquerdo o alterna, o clique direito o seleciona para os itens de detalhes.
PET_DETAIL_INFO	Nível, XP e modo do pet selecionado.
PET_LEVEL_ENTRY	Um nível do pet selecionado com seu requisito de XP e estado.
PET_DETAIL_REMOVE	Um botão que devolve o pet selecionado a um item.
PET_LIST_NAV, PET_DETAIL_NAV	Setas de página para a lista de pets e a lista de níveis.

Os slots também podem executar os comandos pet_menu: pet_menu activate <slot>, pet_menu deactivate <slot>, pet_menu toggle_visibility, pet_menu details <slot>, pet_menu skins <slot>, pet_menu select_skin <pet> <skin> e pet_menu remove <slot>.

Se o UiCore estiver instalado, ele pode ler os companheiros do jogador para desenhar um HUD ou uma página de menu.

Idioma

Os textos do menu, a lore do token e o rótulo acima de um pet estão em francês por padrão (por exemplo "Niveau", "Compagnons"). Edite name, lore e noSlotMessage do token por pet. Os outros textos do menu são fixos no código.

Comandos

A permissão typewriter.pets é exigida para todo subcomando, junto com a permissão indicada. A maioria dos subcomandos aceita um seletor de jogador opcional [target] depois dos argumentos para agir sobre outra pessoa; sem ele, agem sobre quem enviou o comando.

Comando	Permissão	Descrição
/pets open [target]	typewriter.pets.open	Abre o menu de companheiros.
/pets activate <pet> [target]	typewriter.pets.activate	Ativa um pet possuído.
/pets deactivate [target]	typewriter.pets.deactivate	Dispensa o pet ativo.
/pets show [target]	typewriter.pets.show	Mostra o pet ativo novamente.
/pets hide [target]	typewriter.pets.hide	Oculta o pet ativo.
/pets remove <pet> [target]	typewriter.pets.remove	Exclui um pet do menu do jogador. Nenhum item é devolvido.
/pets give <pet> <amount> [target]	typewriter.pets.give	Entrega de 1 a 64 itens token.

<pet> é o id ou o nome de uma entry Pet Definition. O comando /pets sem argumentos não faz nada nesta versão: use /pets open.

Permissões

Nenhuma é registrada com um padrão, então apenas operadores as têm, a menos que você as conceda com um plugin de permissões.

Permissão	Concede
typewriter.pets	A árvore de comandos /pets.
typewriter.pets.open	/pets open.
typewriter.pets.activate	/pets activate.
typewriter.pets.deactivate	/pets deactivate.
typewriter.pets.show	/pets show.
typewriter.pets.hide	/pets hide.
typewriter.pets.remove	/pets remove.
typewriter.pets.give	/pets give.
Permissões de lockedSlots	Desbloqueiam o slot correspondente do menu. Você escolhe os nomes.

Placeholders

O Pets expõe uma entry de placeholder do TypeWriter, Pets Placeholder. Crie-a uma única vez. A tag é <typewriter_ENTRY:...>, em que ENTRY é o nome ou id da entry em minúsculas, por exemplo <typewriter_pets_placeholder:active:name> quando a entry se chama pets_placeholder.

Caminho do argumento	Retorna
active	Nome do pet ativo, vazio quando não há nenhum.
active:name, active:id	Nome e id do pet ativo.
active:level, active:xp, active:max_level	Nível, XP e nível máximo.
active:next_xp	XP necessário para o próximo nível, Max no topo.
active:damage	Dano de revide no nível atual.
active:status	active ou inactive.
active:visibility	hidden ou visible.
active:mode	head, ground ou fly.
slot:<index>:name, id, level, xp, next_xp, max_level, damage, visibility, mode	Os mesmos campos para o pet naquele slot do menu.
slot:<index>:status	active, inactive ou empty.
pet:<id>:name, description, max_level, xp_per_kill, default_mode, combat, texture	Campos de uma Pet Definition.
pet:<id>:owned	true ou false para o jogador.
pet:<id>:level, xp, next_xp, visibility, mode, damage	A cópia do jogador desse pet, vazio quando não possuído.
pet:<id>:status	active, inactive ou unowned.

Entries

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

Ações3

• Pets Add XPGrant experience to a pet
• Pets Open MenuOpen the pet selection menu
• Pets StateChange the state of a pet

Placeholders1

• Pets PlaceholderExpose companion placeholders

Artefatos1

• Pet StoragePersist companion data

Manifestos1

• Pet DefinitionConfigure a companion pet

Solução de problemas

Os pets se perdem após um reinício. Não existe um artifact Pet Storage, ou a ação de menu não tem storage. O log mostra "No pet_storage entry found. Companion data will not persist until one is created."

O token diz que o menu está cheio. Todo slot do menu está ocupado ou bloqueado para esse jogador. Adicione slots em slots ou conceda a permissão de um slot bloqueado. A mensagem é a noSlotMessage do token.

"Ce familier est déjà présent dans ton menu." Um jogador pode possuir uma cópia de cada pet. Ele não pode usar um segundo token da mesma definição.

Um pet GROUND ou FLY nunca aparece. O log diz "Unable to summon ground pet". Defina npc na definição, ou dê a pelo menos uma skin um npc cujos criteria correspondam ao jogador. Verifique se a entry de definição de entidade existe.

O pet não sobe de nível. O pet precisa de um requisito para o próximo nível, seja uma entrada de levels ou uma formula. Uma fórmula que não pode ser avaliada é tratada como ausência de requisito. Verifique se ela usa apenas números, {level}, + - * / e parênteses.

/pets não imprime nada. Use /pets open. Todos os subcomandos exigem typewriter.pets mais a própria permissão, e essas permissões não são concedidas por padrão.

Uma skin aparece como bloqueada ("???"). Seus criteria ainda não correspondem. Teste os facts ou quests dos quais ela depende.

Extensões relacionadas

• GUI — motor de menus por trás do menu de companheiros e dos itens pets_button:.
• UiCore — pode ler os companheiros do jogador para HUD e páginas de menu.