Assistente Caramelo

Virtual AI Assistant

Meet Caramelo, an AI-powered companion dog that can talk to you, understand natural language requests, follow you, protect you, carry items, and perform useful tasks in your Minecraft world.

The mod combines Google Gemini for free-form requests with local speech recognition and speech synthesis. Caramelo's voice uses positional 3D audio, so it comes from the dog's actual location and fades with distance.

Language note: the interface, built-in phrases, voice model, and primary conversation experience are designed for Brazilian Portuguese.

Main features

• One personal companion dog for each player.
• Natural-language conversation through chat or microphone.
• Local voice shortcuts for immediate commands such as follow, sit, protect, stop, place a torch, collect nearby drops, and return to the last death location.
• AI-assisted mining, building, crafting, furnace management, exploration, navigation, item handling, and world inspection.
• Threat warnings for nearby hostile mobs.
• Automatic rescue behavior when the owner is in danger.
• Memory of the player's last death location.
• A mouth inventory that lets the pet carry and return items.
• Positional 3D speech using a bundled Brazilian Portuguese Piper voice.
• Configurable permissions, usage limits, confirmations, and play styles.

Supported versions

Each Minecraft version has its own JAR. Download the file that exactly matches your game.

Minecraft	Required Java
1.20.1	Java 17 or newer
1.21.1	Java 21 or newer
1.21.11	Java 25 or newer
26.2	Java 25 or newer
26.3-snapshot-7	Java 25 or newer

Requirements

• Fabric Loader 0.19.3 or newer
• Fabric API
• GeckoLib
• A Google Gemini API key for free-form AI requests
• Python with faster-whisper only if microphone input is desired

The microphone is optional. Chat interaction and the pet's spoken responses still work without faster-whisper.

Installation

1. Install Fabric Loader for the correct Minecraft version.
2. Install Fabric API and GeckoLib.
3. Download the matching Virtual AI Assistant JAR and place it in the mods folder.
4. Start Minecraft and enter a world.
5. Run /assistant config.
6. Open IA e Custos, enter your Gemini API key, and save.

The API key can be created in Google AI Studio. Availability, quotas, and billing depend on the Google account and plan being used.

Mod Menu is optional. When installed, the same configuration screen is available through Mods → Virtual AI Assistant → Configure.

Using Caramelo

The player receives the assistant item when first joining a world. Use the item to place Caramelo beside you.

• Right-click with meat or a bone: feed and heal the pet.
• Right-click with an empty hand: make the pet sit or stand.
• Sneak + right-click: return the pet to your inventory.
• Use the pet item: place Caramelo in the world again.

A stored pet is completely inactive. Place it back in the world before trying to talk to it or request a task.

Voice control

Hold V, speak, and release the key to send a request. Toggle mode and wake-word mode are also available in the configuration screen.

To enable microphone recognition, install faster-whisper for the Python environment visible to Minecraft:

pip install faster-whisper

Piper and the voice model are already included in the release JAR. Raw microphone audio, speech recognition, speech synthesis, and fixed shortcuts remain local.

Example requests:

• “Caramelo, vem cá.”
• “Senta.”
• “Me protege.”
• “Coloque uma tocha aqui.”
• “Pegue os itens no chão.”
• “Minere os diamantes próximos.”
• “Construa uma ponte de pedra.”
• “Onde fica a vila mais próxima?”
• “Me leve até onde eu morri.”
• “Verifique se estou pronto para o Nether.”

Commands

Command	Purpose
/assistant <message>	Send a request to Caramelo
/assistant config	Open the configuration screen
/assistant status	Show the current assistant status
/assistant reclaim	Recover the pet or its item
/assistant cancel	Cancel the current AI request
/assistant clear	Clear the player's conversation history
/assistant usage	Show estimated AI usage and cost
/assistant pets	List loaded pets; operator command
/assistant fixpets	Remove orphaned pets and collapse duplicates; operator command

Multiplayer and permissions

Singleplayer, LAN, and dedicated servers start with the familia permission profile. This profile is intended for private worlds with trusted players and permits powerful world-changing actions without requiring operator status.

Public servers should manually select servidor_publico in the configuration and restart. In that profile, actions such as giving items, spawning mobs, changing game mode, teleporting, and building require operator level 2.

On a dedicated server, all players use the Gemini key configured by the server owner. Administrators should configure limits.globalRequestsPerHour and/or costTracking.monthlyBudget to control shared usage.

Privacy

Raw microphone audio never goes to Gemini. The following remain local:

• Microphone audio
• Speech recognition with faster-whisper
• Piper speech synthesis
• Positional OpenAL playback
• Fixed local shortcuts

Free-form requests send the typed or locally transcribed text, recent conversation history, and relevant game context to Gemini. Context may include the player's position, dimension, health, hunger, biome, time, weather, equipment, nearby dangers, saved locations, last death, and the tools the player is allowed to use.

The API key is stored only by the host or dedicated server and is not embedded in the mod JAR or sent to clients.

License

Virtual AI Assistant is proprietary software distributed under All Rights Reserved. Downloading an authorized copy permits personal use of the unmodified mod. Copying, modifying, redistributing, selling, sublicensing, publishing, or distributing its source or files requires prior written permission from the author.

Third-party components remain subject to their respective licenses.

---

Virtual AI Assistant

Mod Fabric para Minecraft 1.20.1, 1.21.1, 1.21.11, 26.2 e 26.3 snapshot. Cada jogador recebe seu próprio cachorro assistente, capaz de conversar em português, ouvir o microfone, falar com voz local, acompanhar o dono e executar tarefas no mundo.

O mod usa Gemini para entender pedidos livres e faster-whisper para reconhecer voz. A fala do pet usa Piper, com áudio espacial: a voz vem da posição do cachorro e diminui com a distância.

Documentação técnica, status e roteiros estão centralizados em docs/README.md. Agentes de IA devem começar por AGENTS.md, que carrega somente as regras obrigatórias e aponta o contexto adicional sob demanda.

Versões suportadas

Minecraft	Java	Código	Artefato
1.20.1	17+	versions/1.20.1	versions/1.20.1/build/libs/virtual-ai-assistant-0.1.0-alpha+mc1.20.1.jar
1.21.1	21+	raiz do projeto	build/libs/virtual-ai-assistant-0.1.0-alpha.jar
1.21.11	25+	versions/1.21.11	versions/1.21.11/build/libs/virtual-ai-assistant-0.1.0-alpha+mc1.21.11.jar
26.2	25+	versions/26.2	versions/26.2/build/libs/virtual-ai-assistant-0.1.0-alpha+mc26.2.jar
26.3 snapshot 7	25+	versions/26.3	versions/26.3/build/libs/virtual-ai-assistant-0.1.0-alpha+mc26.3-snapshot-7.jar

Cada versão possui seu próprio JAR. O conteúdo funcional é compartilhado entre as cinco; os diretórios de versão guardam somente diferenças reais de API. A snapshot é fixada em 26.3-snapshot-7 e deve avançar de forma explícita quando a Mojang publicar outra.

Instalação e configuração inicial

1. Instale o Fabric Loader e o Fabric API adequados à versão do Minecraft.
2. Coloque o JAR correspondente em mods/.
3. Crie uma chave em https://aistudio.google.com/apikey.
4. Entre no jogo e use /assistant config.
5. Em IA e custos, cole a chave e salve.

Com Mod Menu instalado, a mesma tela aparece em Mods → Virtual AI Assistant → Configurar. O Mod Menu é opcional; /assistant config sempre abre a GUI. A tela está em português, explica cada opção, destaca valores modificados e possui Restaurar padrões.

Em singleplayer ou LAN, a chave fica no servidor integrado de quem abriu o mundo. Os convidados usam a mesma chave do anfitrião e não precisam cadastrar outra. Em servidor dedicado, o administrador configura uma chave para o servidor.

O modo padrão é API_KEY. O código também oferece OAuth2 PKCE opcional (PLAYER_OAUTH ou SERVER_OWNER_OAUTH) para instalações avançadas; tokens locais usam AES-GCM e arquivos restritos à conta do sistema. Tokens XOR de versões anteriores são invalidados e exigem novo login. Isso protege o arquivo em repouso, mas não um computador comprometido ou outro mod executando com a mesma conta.

A edição manual continua disponível em:

config/virtualassistant/secrets/api_key

No ambiente de desenvolvimento, o caminho é run/config/virtualassistant/secrets/api_key. Nunca publique ou versione essa chave.

Voz local

O JAR de release inclui Piper e o modelo de voz; -PslimJar os remove apenas para iteração de desenvolvimento. O reconhecimento de voz requer Python e faster-whisper instalados no computador de cada jogador que quiser usar o microfone:

pip install faster-whisper

No Windows, o mod também detecta o lançador py, mesmo quando python não está no PATH do Minecraft. Teste no PowerShell:

py -c "import faster_whisper; print('OK')"

Os helpers são criados na primeira execução em config/virtualassistant/stt/ e config/virtualassistant/tts/.

Frases fixas que o pet repete o tempo todo ("Parei!", "Já vou!", avisos de limite, "Chegamos!") vêm com áudio já gravado dentro do JAR, então tocam na hora em vez de esperar o Piper gerar de novo — desliga em tts.cannedPhrasesEnabled. Isso nunca afeta respostas da IA: só toca áudio pronto quando o texto é idêntico a uma dessas frases fixas, nunca por parecença.

Como usar o pet

Ao entrar pela primeira vez, o jogador recebe o item do assistente. Segure o item e use o botão direito para colocar o cachorro no mundo. O item é consumido enquanto o pet está solto.

Interação	Resultado
Botão direito com carne ou osso	Alimenta o pet, toca um som e mostra corações
Botão direito normalmente	Alterna entre sentado e em pé
Agachar + botão direito	Recolhe o pet para o inventário
Usar o item do pet	Coloca novamente o pet no mundo

O pet pertence a um único jogador. Outro jogador não pode sentá-lo, recolhê-lo ou dar ordens; a tentativa reproduz em voz: “Esse não é seu assistente.” Em LAN, cada jogador conversa apenas com o próprio pet, e uma mensagem não influencia o pet de outra pessoa.

Pet recolhido é totalmente inativo. No inventário ele não ouve, não responde, não alerta sobre monstros, não luta e não executa comandos ou tarefas. Use o item para soltá-lo antes de falar.

Sentado, o cachorro continua observando e avisando sobre perigo, mas não segue o dono. Ordens que exigem movimento — como “vem cá”, “ataca” ou “me protege” — fazem o pet levantar. Por padrão, ele também levanta se o dono se afastar mais de 24 blocos, evitando que seja esquecido.

Como falar

Segure V, fale e solte para enviar. Em stt.toggleMode, é possível trocar para o modo aperta/aperta: uma vez inicia a gravação e outra envia. Também existe o modo contínuo por palavra de ativação; nele, diga o nome configurado do pet, por exemplo: “Caramelo, vem cá.”

Frases curtas e conhecidas são atalhos locais: funcionam sem Gemini, têm resposta imediata e toleram pequenos erros de transcrição. Pedidos livres ou específicos são interpretados pela IA. Assim, “ataca” é local, enquanto “ataque o creeper” vai para o Gemini para preservar o alvo.

As frases abaixo são exemplos, não comandos rígidos. É possível falar naturalmente, trocar quantidades, itens, mobs, destinos e nomes.

Conversa e informações

Recurso	O que faz	Exemplos para o microfone
Conversa em português	Responde perguntas curtas usando o contexto atual do jogador	“Como faço uma cama?” · “Para que serve redstone?”
Descrever os arredores	Informa posição, bioma, horário, clima e entidades próximas	“O que tem por aqui?” · “Descreva onde eu estou”
Identificar o alvo	Identifica o bloco ou entidade para o qual o jogador está olhando	“O que é isso?” · “Olha esse bloco”
Procurar blocos e minérios	Varre blocos próximos, incluindo variantes deepslate	“Tem diamante por perto?” · “Procure ferro aqui”
Verificar se pode dormir	Explica se é dia, se há monstros perto, se falta cama ou se já pode dormir	“Posso dormir?” · “Está na hora de dormir?”
Legendas para responsáveis	Mostra no chat o que o STT entendeu, facilitando acompanhar a criança	Ative ux.parentCaptions na configuração
Histórico de conversa	Mantém contexto recente por jogador	“E como eu faço isso?” depois de uma pergunta anterior
Repetir a última resposta	Fala de novo o que acabou de dizer — atalho local, sem gastar IA	“Repete” · “Pode repetir?” · “Fala de novo” · “Não entendi”
Cancelar uma solicitação	Cancela o pedido de IA que ainda está sendo processado	“Cancela” · “Esquece”

Movimento, postura e localização do pet

Recurso	O que faz	Exemplos para o microfone
Chamar o pet	Levanta e traz o cachorro até o dono	“Vem cá” · “Vem aqui” · “Me segue”
Sentar	Faz o pet esperar no lugar	“Senta” · “Fica aí” · “Espera aí”
Levantar	Retoma o acompanhamento	“Levanta” · “Fica de pé”
Ir até o pet	Teleporta o jogador para seu pet, se permitido	“Onde está meu pet?” · “Me teleporta pro assistente”
Recuperar vínculo	Reemite o item ou recupera uma entidade solta ausente	Use /assistant reclaim

Ao seguir ou trabalhar, o pet usa pathfinding, atravessa água e tenta se recuperar caso fique preso. Tarefas no mundo respeitam a regra vai e faz: ele caminha até o bloco, item, fornalha ou destino antes de agir — exceto construções (casinha, ponte, parede, coluna, qualquer coisa de vários blocos), que montam sozinhas onde foram pedidas, sem o pet precisar ir até lá (veja "Construção" abaixo).

Combate, proteção e segurança

Recurso	O que faz	Exemplos para o microfone
Ataque pontual	Ataca hostis próximos e para quando a área fica limpa	“Ataca” · “Mata os monstros” · “Pega eles”
Ataque a um tipo	Ataca o mob indicado	“Ataque o creeper” · “Mate aquele zombie”
Proteção contínua	Mantém o modo vermelho e combate ameaças que se aproximarem	“Me protege” · “Fica de guarda” · “Me defende”
Encerrar combate ou trabalho	Para ataque, guia, mineração e trabalhos atuais	“Para” · “Pare de atacar” · “Fica quieto”
Socorro automático	Com vida baixa e hostil por perto, levanta e protege o dono automaticamente	Automático; configure em Socorro
Alertas de ameaça	Avisa tipo, quantidade, urgência e direção de monstros visíveis	Automático: “Tem um creeper à sua direita”
Duelo de treinamento	Cria um zombie para um treino cooperativo com o pet	“Vamos treinar” · “Começa o treino”

O modo de proteção não impede outras ordens: o pet pode guiar, buscar, construir ou trabalhar e depois continuar protegendo. Ameaças críticas podem interromper uma fala em andamento. O aviso usa cooldowns por mob e por tipo para não repetir mensagens continuamente.

Itens, kits, crafting e inventário

Recurso	O que faz	Exemplos para o microfone
Dar item	Entrega itens vanilla, com quantidade opcional	“Me dê 32 blocos de pedra” · “Quero uma picareta de ferro”
Dar item encantado	Aplica conjunto padrão forte ou encantamentos pedidos	“Me dê uma picareta de diamante encantada” · “Quero uma espada com afiação cinco”
Kit de tocha e comida	Entrega suprimentos básicos	“Tocha e comida”
Kit do Nether	Entrega preparação para o Nether	“Kit Nether” · “Me prepara pro Nether”
Kit de diamante	Entrega equipamento de diamante	“Kit diamante” · “Full diamante”
Kit de combate	Entrega equipamento para luta	“Me arma” · “Kit combate”
Item rápido	Atalhos locais para itens comuns	“Me dá tocha” · “Tô com fome”
Crafting	Usa receitas vanilla; informa materiais ausentes e, se permitido, pode completá-los	“Faz uma picareta” · “Crafta um escudo” · “Faz uma mesa de trabalho”
Guardar na boca	O pet caminha até o dono e guarda um item do stack segurado; a boca tem um slot	“Guarda isso” · “Segura isso”
Devolver da boca	O pet caminha até o dono e entrega o item guardado	“Devolve” · “Me dá o que você guardou”
Buscar item apontado	Busca o item no chão para o qual o jogador olha	“Pega isso” · “Busca aquele item”
Recolher drops	Caminha e coleta os itens largados próximos	“Pega tudo” · “Recolhe tudo” · “Cata tudo”

Itens dados, crafting automático e kits dependem do perfil de permissões. O pet nunca puxa itens por um ímã invisível: ele vai até cada drop.

Mineração, iluminação e fornalha

Recurso	O que faz	Exemplos para o microfone
Minerar o bloco apontado	Caminha até o alvo e quebra um bloco seguro	“Mina isso” · “Quebra esse bloco”
Minerar veio	Quebra o minério apontado e até 16 blocos adjacentes do mesmo tipo	“Mina o veio” · “Pega todo o minério”
Achar e quebrar (sem precisar mirar)	Procura o bloco por perto — árvore inteira ou qualquer outro bloco — vai até lá, quebra e avisa quando termina. O item cai no chão, o pet não entrega na mão	“Quebra uma árvore” · “Corta madeira pra mim” · “Quebra umas folhas e o que cair”
Abrir túnel	Escava um túnel curto de 1×2 na direção do olhar	“Abre caminho” · “Faz um túnel”
Escada para baixo	Escava uma escada descendente de 1×2	“Escada pra baixo” · “Cava uma escada”
Parar mineração	Cancela o trabalho atual	“Para de cavar” · “Para de minerar”
Colocar uma tocha	Usa uma tocha do inventário e a coloca onde o jogador olha	“Luz aqui” · “Coloca uma tocha”
Trilha de tochas	Coloca tochas ao longo do caminho	“Ilumina o caminho” · “Vai colocando tocha”
Parar trilha	Interrompe novas tochas	“Para de iluminar”
Remover tochas do pet	Recolhe apenas as tochas que o próprio pet colocou e registrou	“Apaga as tochas” · “Tira as tochas do caminho”
Colocar na fornalha	Leva minérios crus ou comida e combustível a uma fornalha próxima	“Funde os minérios” · “Cozinha a carne”
Coletar da fornalha	Busca a saída pronta e entrega ao jogador	“Pega da fornalha” · “A fornalha está pronta”
Colher cultura madura	Acha trigo, cenoura, batata ou beterraba já crescidos por perto e colhe — não corta plantação verde	“Colhe o trigo” · “Colhe a plantação” · “Pega a batata pronta”
Plantar semente	Planta em terra arada vazia por perto, sem precisar mirar	“Planta trigo aqui” · “Planta uma cenoura” · “Planta batata nessa terra”
Colocar bloco livre	Linha no chão, parede retangular (largura × altura), ou coluna subindo a partir de onde você está olhando — um material só, sem template fixo	“Coloca um bloco de pedra ali” · “Faz uma parede com essas tábuas” · “Faz uma parede de 5 de largura por 20 de altura” · “Sobe uma coluna de 5 blocos” · “Continua essa parede mais 10 pra cima” · “Preenche esse buraco”

A mineração protege baús, spawners, bedrock, portais e blocos muito duros. Uma picareta melhor guardada na boca do pet aumenta o limite de dureza. Ao chegar a minério raro, ele pode comemorar com um som emocional.

Navegação, estruturas e pontos salvos

Recurso	O que faz	Exemplos para o microfone
Salvar ponto	Salva a posição atual com um nome, gravado em disco (sobrevive a reinício do servidor)	“Marca casa” · “Salva esse lugar como mina” · “Me lembre desse lugar, chama de fazenda”
Listar locais salvos	Fala todos os nomes salvos	“Quais locais eu salvei?” · “Que lugares eu tenho salvo?”
Esquecer local salvo	Remove um local salvo pelo nome	“Esquece a mina” · “Apaga o local fazenda”
Guiar a um ponto	O pet caminha na frente até o local salvo	“Vamos pra casa” · “Me leva até a mina”
Teleportar a um ponto salvo	Teleporta direto para um local salvo, se permitido	“Me teleporta pra casa” · “Tp pra mina”
Guiar a coordenadas	Inicia guia para X, Y e Z informados	“Me guia até X 100, Y 64, Z menos 30”
Parar guia	Cancela a navegação atual	“Para de guiar” · “Para de procurar”
Continuar objetivo	Retoma a última guia interrompida	“Continua” · “Retoma o caminho”
Local da morte	Guarda a última morte e guia uma vez após renascer ou quando pedido	“Onde eu morri?” · “Me leva pro meu corpo”
Encontrar bioma	Localiza o bioma mais próximo	“Onde tem deserto?” · “Encontre um bioma de cerejeiras”
Encontrar estrutura	Localiza vila, templo, monumento, fortaleza e outras estruturas vanilla	“Ache a vila de deserto mais próxima” · “Onde tem um monumento oceânico?”
Guiar até estrutura	Localiza e faz o pet conduzir o jogador	“Encontre uma vila e me guie até lá”
Teleportar a coordenadas	Teleporta para coordenadas absolutas, se permitido	“Me teleporta para 100, 70, menos 200”
Teleportar a estrutura	Localiza e teleporta para uma superfície segura sobre a estrutura	“Me teleporta para a vila de taiga mais próxima”

Locais salvos guardam também a dimensão em que foram salvos; se você pedir para ir a um local salvo em outra dimensão (do Overworld para um ponto salvo no Nether, por exemplo), o pet avisa em vez de tentar guiar ou teleportar para lá.

Teleporte longo e outras ações de alto risco pedem confirmação quando ux.confirmBigActions está ativo. Responda “sim”, “confirma”, “não” ou “cancela isso”.

Construção

O pet mostra uma prévia, pede confirmação quando configurado e a construção se monta sozinha no local pedido — o pet não precisa caminhar até lá nem ficar indo e voltando bloco por bloco (diferente de minerar, tocha, fornalha e outras tarefas, que continuam sendo "vai e faz"). Uma coluna de 20 blocos pra cima, por exemplo, sobe inteira sem depender do pet achar um jeito de subir fisicamente nela. Os modelos disponíveis são:

Construção	Exemplo para o microfone
Casinha oca de madeira 5×5	“Faz uma casinha” · “Casa cinco por cinco”
Ponte de tábuas com 10 blocos	“Faz uma ponte” · “Ponte de dez”
Muro circular de pedregulho	“Faz um muro em volta”
Base 3×9 para plantação de cana	“Faz uma farm de cana”
Escada de tábuas para cima	“Escada pra cima” · “Faz uma escada subindo”

Para um pedido que não é nenhum desses cinco modelos, o pet desenha a construção sozinho em vez de recusar: "Faz uma casinha com dois andares", "constrói um muro com uma parte de vidro" e pedidos parecidos viram uma construção pequena (até 200 blocos) que o próprio assistente projeta, com a mesma prévia e confirmação de antes. Não é mágica — o servidor valida cada bloco pedido (tamanho, distância do jogador, nunca spawner/portal/bloco de comando) antes de deixar o pet construir qualquer coisa.

Uma flor, muda de árvore ou cogumelo no meio do caminho não trava a construção — o pet quebra e o item cai no chão, do mesmo jeito que você faria construindo por cima do seu próprio jardim. Folhagem de árvore não conta: o pet nunca corta galhos sem você pedir — já na prévia (antes de dizer "sim") ele avisa se viu galhos no caminho, e depois de construir continua sem eles. Se quiser que os galhos sejam cortados também, é só dizer "corta os galhos" logo em seguida. Terreno que já tinha bloco sólido no caminho (um morro, uma pedra) também é avisado, tanto na prévia quanto no final — nunca é quebrado sem pedido, mas se quiser que o pet limpe esses lugares também, é só dizer "quebra o que atrapalhou" logo depois. Na sobrevivência, "coloca X blocos" confere se você tem material suficiente antes de começar — se faltar, o pet avisa em vez de parar pela metade sem explicação.

Missões, preparação e brincadeiras

Recurso	O que faz	Exemplos para o microfone
Criar missão	Cria uma tarefa curta e mensurável de coleta ou uma aventura até estrutura	“Me dá uma missão” · “Quero uma aventura” · “Cria uma missão para achar um naufrágio”
Status da missão	Verifica o progresso	“Como vai a missão?” · “Status da missão”
Concluir missão	Confere e encerra a missão	“Terminei a missão” · “Missão cumprida”
Preparação para Nether	Verifica resistência ao fogo, picareta, comida, pederneira e blocos	“Tô pronto pro Nether?” · “Checklist Nether”
Preparação para caverna	Verifica picareta, tochas, comida e armadura	“Tô pronto pra caverna?” · “Checklist caverna”
Preparação para o End	Verifica arma, pérola, armadura e comida	“Estou pronto para ir ao End?”
Preparação para luta	Verifica espada, comida e escudo	“Estou pronto para lutar?”
Girar	Animação de giro com corações	“Roda” · “Gira”
Mortal	Animação de cambalhota	“Faz o mortal”
Pose de brincadeira	Abaixa a frente do corpo para brincar	“Vamos brincar” · “Faz pose de brincar”
Latido para assustar	Rosna e afasta levemente animais passivos próximos	“Late pra assustar” · “Assusta eles”

Animais e vilas

Recurso	O que faz	Exemplos para o microfone
Contar animais	Conta animais passivos próximos, opcionalmente por tipo	“Quantos animais tem aqui?” · “Quantas ovelhas?”
Pastorear até o jogador	Conduz ovelhas, vacas, porcos, galinhas ou todos os animais	“Traga as ovelhas” · “Junta os bichos” · “Traga as vacas”
Pastorear ao cercado	Leva os animais ao ponto salvo com nome cercado	Primeiro “Marca aqui como cercado”; depois “Leva os animais pro cercado”
Tosquiar ovelha	Caminha até a ovelha mais próxima e traz lã da cor dela	“Tosquia essa ovelha” · “Corta a lã dela”
Ordenhar vaca	Caminha até a vaca mais próxima e traz um balde de leite	“Ordenha a vaca” · “Pega leite daquela vaca”
Contar villagers	Resume profissões dos villagers próximos	“Quantos villagers tem aqui?”
Procurar profissão	Procura librarian, farmer e outras profissões	“Tem librarian aqui?” · “Ache um bibliotecário”
Consultar trocas	Resume até duas das melhores ofertas do villager compatível mais próximo	“Que trade o librarian tem?”

Controle do mundo e recursos administrativos

Estas ações dependem das permissões do servidor e podem exigir confirmação:

Recurso	O que faz	Exemplos para o microfone
Alterar horário	Define dia, noite, meio-dia, meia-noite ou horário numérico	“Faz ficar de dia” · “Coloca meia-noite”
Alterar gamemode	Troca entre survival, creative, adventure e spectator	“Coloca no criativo” · “Volta para sobrevivência”
Criar mobs	Invoca de 1 a 16 mobs vanilla, incluindo filhotes compatíveis	“Cria três galinhas” · “Spawna uma vaca bebê”
Dar itens	Entrega qualquer item vanilla permitido	“Me dê uma bússola”
Teleportar	Move o próprio jogador; nenhuma ferramenta aceita outro jogador como alvo	“Me teleporta até uma vila”

Sons, aparência e estados

• Modelo e textura próprios de cachorro caramelo, com animações procedurais.
• Indicador visual de estado: acompanhamento, combate/proteção, guia e trabalho.
• Pose sentada sincronizada e persistente.
• Voz Piper em português do Brasil, reproduzida a partir da posição do pet.
• Rosnado graduado conforme a urgência do perigo.
• Comemoração ao alcançar diamante, esmeralda ou detrito ancestral.
• Mensagens de erro e avisos importantes também podem ser falados — inclusive falta do reconhecedor de voz e tentativa de mexer no pet de outro jogador.

Chat e comandos

Com ux.interceptAllChat=true, mensagens normais são enviadas ao assistente e não aparecem no chat público. Em LAN, cada mensagem continua vinculada ao jogador e ao pet dele. Também é possível usar comandos explicitamente:

Comando	Função
/assistant <mensagem>	Envia um pedido ao assistente
/assistant config	Abre a GUI de configuração
/assistant status	Mostra modelo, chave, gamemode, combate, postura e alertas
/assistant reclaim	Recupera o pet ou o item quando permitido
/assistant cancel	Cancela a solicitação de IA em andamento
/assistant clear	Limpa o histórico de conversa do jogador
/assistant do <ação>	Executa uma ação direta; é o mecanismo dos atalhos locais
/assistant usage	Relatório de gasto com IA: conversas, tokens, custo estimado
/assistant usage players	Gasto por jogador (operador)
/assistant usage reset	Zera os contadores; o histórico em usage/*.jsonl é preservado (operador)
/assistant pets	Lista pets, donos, órfãos, rastreamento e coordenadas vistos pelo servidor (operador)
/assistant fixpets	Remove pets órfãos e colapsa duplicatas (operador)

O servidor colapsa automaticamente pets duplicados carregados a cada dois segundos, preservando o UUID rastreado no jogador. Se /assistant pets listar apenas um pet, mas o cliente mostrar dois, a entidade extra é um fantasma visual: sair e entrar novamente limpa a visão. /assistant fixpets continua disponível para uma varredura completa sob demanda.

Permissões, estilos e confirmações

Opção	Comportamento
general.permissionProfile=familia	Perfil aberto para singleplayer, família e amigos
general.permissionProfile=servidor_publico	Exige nível de operador para ações que alteram o mundo
general.permissionProfile=custom	Respeita cada permissão configurada manualmente
general.playStyle=co_pilot	Permite o conjunto completo de ferramentas autorizadas
general.playStyle=buddy	Experiência equilibrada padrão
general.playStyle=safety_net	Prioriza segurança, inspeção, guia e coleta; bloqueia give, spawn, teleporte e construção
ux.confirmBigActions=true	Confirma bosses, teleportes longos, modos criativo/espectador e outras ações grandes
ux.confirmAiActions=true	Também confirma pedidos comuns antes de gastar uma chamada de IA

Nenhuma ferramenta pode escolher outro jogador como alvo. Limites por minuto, ferramentas pesadas, concorrência e teto global por hora ajudam a controlar desempenho e custo.

Configurações mais usadas

O arquivo config/virtualassistant/config.json é criado na primeira execução. A configuração é carregada ao iniciar o jogo; reinicie para aplicar mudanças. config.example.json é gerado pelo código e não deve ser editado manualmente.

Chave	Padrão	Função
general.petName	Caramelo	Nome, vocativo de voz e prefixo das respostas
general.petStandUpDistance	24	Distância para levantar sozinho; 0 desativa
general.permissionProfile	familia	Perfil de permissões
general.playStyle	buddy	Quanto o assistente pode fazer pelo jogador
gemini.model	gemini-3.5-flash-lite	Modelo usado para pedidos livres
gemini.allowCustomApiBase	false	Autoriza explicitamente um proxy HTTPS que receberá chave e contexto
limits.requestsPerMinute	20	Limite por jogador
limits.heavyToolsPerMinute	4	Limite de scans e localizações pesadas
limits.globalRequestsPerHour	0	Teto de todo o servidor; 0 desativa
tts.engine	piper	piper ou espeak
tts.speed	1.0	Valor maior deixa a fala mais lenta
tts.speakErrors	true	Fala mensagens de erro
tts.speakSystemMessages	true	Fala avisos do mod
stt.engine	resident	resident, command ou disabled
stt.model	small	base, small ou medium
stt.toggleMode	false	Alterna entre segurar e apertar V
stt.localShortcuts	true	Atalhos instantâneos sem Gemini
ux.parentCaptions	true	Mostra o texto reconhecido pelo microfone
spatialAudio.maxDistance	32	Distância máxima da voz do pet

Alertas de monstros e socorro possuem páginas próprias na GUI, com raio, vida mínima, cooldowns, linha de visão, latidos e anúncios. Todas as ferramentas também podem ser ligadas, desligadas ou limitadas por permissão.

Build e validação

export JAVA_HOME=/usr/lib/jvm/java-25-openjdk
./scripts/bundle_voice_into_mod.sh   # baixa o runtime de voz (uma vez; idempotente)
./gradlew build                      # JAR completo da 1.21.1 (~79 MB)
./gradlew build -PslimJar            # JAR sem voz, para iterar rápido
./gradlew test
./gradlew generateConfigExample
./gradlew verifyVersionParity

• build: gera o JAR da 1.21.1.
• verifyVersionParity: compila/testa as cinco versões e verifica a paridade das classes.
• bundle_voice_into_mod.sh: baixa Piper para as cinco plataformas + o modelo PT-BR na árvore de recursos compartilhada. As cinco versões consomem a mesma árvore.

O JAR é universal

Cada JAR já contém o Piper de todos os sistemas (Linux x86_64/aarch64, Windows x86_64, macOS Intel/Apple Silicon) e o modelo de voz PT-BR. Não existe versão por sistema operacional e o jogador não baixa nada para o cachorro falar — o mod extrai só a plataforma em uso na primeira execução.

Fora do JAR ficam duas coisas, por motivos diferentes:

• STT (faster-whisper) é Python + pip + modelo, não um binário empacotável. Sem ele o jogador ainda digita no chat e ouve a resposta falada; só o microfone não funciona.
• A chave da API nunca é embutida: fica no servidor, em secrets/api_key, com acesso restrito à conta que executa o jogo.
• Destino da chave: somente a API oficial do Google é aceita por padrão. Um endpoint personalizado exige gemini.allowCustomApiBase=true e deve estar sob controle do administrador.
• Dados enviados em pedidos livres: texto/transcrição, histórico recente e contexto de jogo necessário (posição/dimensão, estado do jogador, ambiente, perigos, locais e ferramentas permitidas). Áudio bruto, STT e TTS permanecem locais.

O código e os ativos originais do mod são proprietários e estão sob Todos os Direitos Reservados. Componentes de terceiros permanecem sujeitos às licenças listadas em THIRD-PARTY.md. Índice técnico: docs/README.md.