🐕 Virtual AI Assistant

Companheiro com IA no Minecraft | AI Companion for Minecraft

The Virtual AI Assistant introduces Caramelo — a loyal stray dog companion powered by state-of-the-art artificial intelligence (Google Gemini), featuring local voice commands (STT/TTS) and 3D spatial audio.
He talks to you, understands voice or chat commands, mines, builds, retrieves items, guides you when you die, warns you about threats, and automatically rescues you in dangerous situations!

✨ Mod Features

• 🐶 Your Dog Companion (Caramelo): One assistant per player that follows you, carries items in his mouth, and reacts to petting, food, and commands.
• 🎙️ Locally Processed Voice: Speak by holding the V key! STT with faster-whisper and TTS with Piper run directly on your machine. Audio is never sent to Gemini; only transcribed free-form requests use the API.
• 🔊 3D Spatial Audio: Caramelo's voice comes from his exact location in the Minecraft world, and the sound direction matches where you're looking!
• ⚡ Instant Local Shortcuts: Short commands ("sit", "come here", "protect me", "torch") are executed instantly offline, with no AI latency.
• 🧠 Function Calling via Gemini: Request complex tasks in natural language! The AI controls the pet to mine specific ores, build bridges/houses, locate biomes/structures, fetch items, and organize furnaces.
• 🛡️ Threat Alert System: An intelligent danger filter that warns you via voice about nearby monsters ("Watch out! Creeper to your right!").
• 🩺 Low-Health Auto-Rescue: If your health drops below 3 hearts near enemies, Caramelo will automatically enter combat to save you.
• 🗺️ Death Guide: Upon dying, the dog memorizes the location and offers to guide you back to your lost items.

🎙️ How Voice Control Works

  [ V Key ]  --->  [ Local STT (Whisper) ]  --->  [ Direct Shortcut or Gemini AI ]
                                                               |
  [ 3D Hearing ] <--- [ Positional OpenAL Audio ] <--- [ Local TTS (Piper) ]

1. Hold the V key (or toggle with toggleMode), speak your request, and release it.
2. Direct commands ("Caramelo, sit" or "come here") are executed instantly.
3. Complex requests or questions ("Find a jungle biome" or "Build a wall here") are sent to Google Gemini, which executes the necessary tools in-game.

🔨 AI Tools and Capabilities

Caramelo walks to the target location for short actions like mining, collecting, and placing torches. Large builds are executed in remote steps to prevent pathfinding lag. Here is what you can ask:

⚡ Local Voice Shortcuts (Zero Latency)

These commands work offline and instantly, without consuming AI quota:

• "come here" / "follow me": Calls the dog to your side.
• "sit" / "stand up": Toggles the dog's posture.
• "protect me" / "attack": Enters active defense mode.
• "stop" / "stop attacking": Cancels the current combat.
• "light here" / "torch": Places a torch from the inventory on the nearest block.
• "pick up everything": Collects all dropped items around.
• "food": Delivers food from the inventory to the player if they are hungry.
• "where I died": Guides the player back to the location of their last death.

🐕 Interacting with Caramelo

• Feed: Right-click holding meat (any type) or a bone. He eats it, heals, and spawns heart particles!
• Sit / Stand: Right-click with an empty hand.
• Store in Inventory: Shift + Right-click to store the pet as an item in your inventory.
• Release in the world: Drop the pet item on the ground (Q key) and he will spawn by your side.

📋 Requirements and Dependencies

To run the mod, you will need the following dependencies installed:

• 🧩 Fabric API: Required for network communication and game events.
• 🦎 GeckoLib: Required for the pet's custom 3D animations.
• ☕ Java: 17+ on Minecraft 1.20.1, 21+ on 1.21.1, and 25+ on newer versions.
• ⚡ Fabric Loader: Version 0.19.3 or higher.

⚙️ Quick Setup Guide

1. Gemini API Key

1. Go to the Google AI Studio portal and create an API Key (free).
2. Inside Minecraft, type:

   /assistant config

1. Open the AI & Costs tab, paste your key, and click Save. (If you have Mod Menu installed, you can also access this screen in Mods → Virtual AI Assistant → Configure).

2. Voice Recognition (Microphone)

To talk to the assistant by holding the V key, you need Python and the faster-whisper library installed on your computer. Follow this step-by-step guide (it's very simple!):

On Windows:

1. Open PowerShell (search for it in the Start menu).
2. Install Python by pasting this command and pressing Enter:

winget install Python.Python.3.12 --override "/quiet InstallAllUsers=0 Include_launcher=1"

(Note: The --override flag ensures the "py launcher" utility is installed. The mod needs it to find Python automatically without you having to configure system variables).

1. Close and reopen PowerShell to update your system settings.
2. Install the voice library:

pip install faster-whisper

1. (Optional) Verify if everything worked:

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

If it prints "OK", you are all set! The mod on Windows will automatically detect the py launcher.

On macOS:

1. Open the Terminal.
2. Install Python (using Homebrew):

brew install python

1. Install the voice library:

pip3 install faster-whisper

On Linux (Ubuntu/Debian):

1. Open the Terminal.
2. Install Python and pip:

sudo apt update
sudo apt install python3 python3-pip

1. Install the voice library:

pip3 install faster-whisper

The connection scripts between the game and the AI are created automatically in your Minecraft's config/virtualassistant/ folder on the first launch.

🔒 Security and Multiplayer Servers

The profile does not change automatically based on the world type: singleplayer, LAN, and dedicated servers all start in familia. This default is intentional for private worlds with trusted people; in it, any player can request actions like giving items, building, spawning mobs, changing gamemodes, and teleporting their own character.

"general": {
  "permissionProfile": "familia" // Options: "familia", "servidor_publico", "custom"
}

• familia (default): Recommended for singleplayer, LAN, and private dedicated servers where everyone is trusted. Tools remain subject to configured limits and confirmations but do not require OP status.
• servidor_publico: Should be chosen manually by those hosting public servers. Actions like giving items, building, spawning mobs, changing gamemodes, teleporting, and other mutating actions will now require OP level 2; consultations and guidance remain open to everyone.
• custom: Respects the levels configured individually by the administrator.

On dedicated servers, there is one Gemini key from the host, used for all players' requests. The key is stored only on the server, in config/virtualassistant/secrets/api_key, with restricted access to the account running Minecraft; it does not go into the JAR, config.json, chat, nor is it sent to clients. To limit abuse or costs, configure limits.globalRequestsPerHour and/or costTracking.monthlyBudget, and monitor it with /assistant usage.

Privacy: What leaves your computer

• Remains local: Raw microphone audio, transcription by faster-whisper, Piper synthesis, and OpenAL playback. Fixed shortcuts also do not call the AI.
• Goes to Gemini in free requests: The typed or already transcribed text, recent history, and the necessary context to reply — version/dimension/position, health and hunger, biome/time/weather, item in hand/armor, nearby dangers, saved locations, last death, and the tools the player has permission to use.
• Conversation history is persisted in the player's save file. The detailed usage log tracks consumption; message texts are logged off by default (costTracking.logMessages=false). Use /assistant clear to clear the history.
• Google's official address is the only allowed destination by default. A custom HTTPS proxy must be explicitly enabled and will receive the key and the same context — use only an endpoint under your control.

❓ Frequently Asked Questions (FAQ)

1. Do I need to pay to use Gemini in the mod?

Usage depends on the quota and conditions of your Google AI Studio account. The mod shows estimated consumption in /assistant usage and allows you to configure a global limit and a monthly budget.

2. Does the mod work in Singleplayer and Multiplayer?

Yes. In singleplayer/LAN, STT, TTS, and audio run locally, while free requests use Gemini. On dedicated servers, the server manages the key and permissions; each client processes its own voice and 3D audio.

3. I lost my dog, now what?

Just say "come here" in voice/chat or use the /assistant reclaim command in the game chat.

📜 License

The Virtual AI Assistant is proprietary software, distributed under All Rights Reserved. Downloading authorizes personal use of the mod, but does not authorize copying, modifying, redistributing, selling, sublicensing, or publishing its code or files without prior explicit permission from the author.

Third-party components remain subject to their respective licenses and do not become proprietary by being part of the distribution.

✨ Destaques do Mod

• 🐶 Seu Cão Companheiro (Caramelo): Um assistente por jogador que te segue, guarda itens na boca, reage a carinhos, alimentos e comandos.
• 🎙️ Voz processada localmente: Fale segurando a tecla V! STT com faster-whisper e TTS com Piper rodam na sua máquina. O áudio não é enviado ao Gemini; somente pedidos livres já transcritos usam a API.
• 🔊 Áudio Espacial 3D: A voz do Caramelo vem da posição real onde o cachorro está no mundo de Minecraft. O som acompanha a direção para onde você olha!
• ⚡ Atalhos Locais Instantâneos: Comandos curtos ("senta", "vem cá", "me protege", "luz aqui") são executados instantaneamente offline, sem latência da IA.
• 🧠 Function Calling via Gemini: Peça tarefas complexas em linguagem natural! A IA assume o controle do pet para minerar minérios específicos, construir pontes/casas, localizar biomas/estruturas, buscar itens e organizar fornalhas.
• 🛡️ Sistema de Alerta de Ameaças: Filtro inteligente de perigos que avisa por voz sobre monstros próximos ("Cuidado! Creeper à sua direita!").
• 🩺 Socorro Automático com Vida Baixa: Se sua vida cair abaixo de 3 corações perto de inimigos, o Caramelo entra em combate sozinho para te salvar.
• 🗺️ Guia de Morte: Ao morrer, o cão memoriza o local e fala para você segui-lo de volta até seus itens perdidos.

🎙️ Como Funciona o Controle por Voz

  [ Tecla V ]  --->  [ STT Local (Whisper) ]  --->  [ Atalho Direto ou Gemini AI ]
                                                                 |
  [ Ouvido 3D ] <--- [ Áudio Posicional OpenAL ] <--- [ TTS Local (Piper) ]

1. Segure a tecla V (ou alterne no modo toggleMode), fale seu pedido e solte.
2. Se for um comando direto ("Caramelo, senta" ou "vem cá"), ele executa na hora.
3. Se for uma pergunta ou ordem complexa ("Encontre um bioma de selva" ou "Construa um muro aqui"), a pergunta vai para o Google Gemini, que executa as ferramentas necessárias no jogo.

🔨 Ferramentas e Capacidades da IA

O Caramelo caminha até o local para ações curtas como minerar, coletar e colocar tochas. Construções grandes são executadas em etapas remotas para evitar travamentos de pathfinding. Veja o que você pode pedir:

⚡ Atalhos de Voz Locais (Sem Latência)

Estes comandos funcionam offline e instantaneamente, sem gastar cota da IA:

• "vem cá" / "me segue": Chama o cão para o seu lado.
• "senta" / "levanta": Alterna a postura do cão.
• "me protege" / "ataca": Entra em modo de defesa ativa.
• "para" / "pare de atacar": Cancela o combate atual.
• "luz aqui" / "tocha": Coloca uma tocha do inventário no bloco mais próximo.
• "pega tudo": Coleta todos os itens caídos ao redor.
• "comida": Entrega comida do inventário ao jogador se ele estiver com fome.
• "onde morri": Guia o jogador de volta ao local da última morte.

🐕 Interagindo com o Caramelo

• Alimentar: Clique com o botão direito segurando carne (qualquer tipo) ou osso. Ele come, recupera vida e solta coraçõezinhos!
• Sentar / Levantar: Clique com o botão direito com a mão vazia.
• Guardar no Inventário: Clique com Shift + Botão Direito para recolher o pet como um item no seu inventário.
• Soltar no mundo: Jogue o item do pet no chão (tecla Q) e ele ganha vida ao seu lado.

📋 Requisitos e Dependências

Para rodar o mod, você precisará das seguintes dependências instaladas:

• 🧩 Fabric API: Necessário para a comunicação de rede e eventos do jogo.
• 🦎 GeckoLib: Necessário para as animações customizadas 3D do pet.
• ☕ Java: 17+ no Minecraft 1.20.1, 21+ no 1.21.1 e 25+ nas versões mais novas.
• ⚡ Fabric Loader: Versão 0.19.3 ou superior.

⚙️ Guia Rápido de Configuração

1. Chave do Gemini

1. Acesse o portal Google AI Studio e crie uma API Key (gratuita).
2. Dentro do Minecraft, digite:

   /assistant config

1. Abra a aba IA e Custos, cole sua chave e clique em Salvar. (No Mod Menu, você também pode acessar essa tela em Mods → Virtual AI Assistant → Configurar).

2. Reconhecimento de Voz (Microfone)

Para falar com o assistente segurando a tecla V, é necessário ter o Python e a biblioteca faster-whisper instalados no seu computador. Siga o passo a passo (é bem simples!):

No Windows:

1. Abra o PowerShell (pesquise no menu Iniciar).
2. Instale o Python colando este comando e apertando Enter:

winget install Python.Python.3.12 --override "/quiet InstallAllUsers=0 Include_launcher=1"

(Nota: O comando --override garante que o utilitário "py launcher" seja instalado. Ele é necessário para o mod achar o Python automaticamente, sem você precisar configurar variáveis de sistema).

1. Feche e abra o PowerShell novamente para atualizar as configurações.
2. Instale a biblioteca de voz:

pip install faster-whisper

1. (Opcional) Teste se tudo deu certo:

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

Se aparecer "OK", está perfeito! O mod no Windows também detecta o lançador py automaticamente.

No macOS:

1. Abra o Terminal.
2. Instale o Python (usando o Homebrew):

brew install python

1. Instale a biblioteca de voz:

pip3 install faster-whisper

No Linux (Ubuntu/Debian):

1. Abra o Terminal.
2. Instale o Python e o pip:

sudo apt update
sudo apt install python3 python3-pip

1. Instale a biblioteca de voz:

pip3 install faster-whisper

Os scripts de conexão entre o jogo e a IA são criados automaticamente na pasta config/virtualassistant/ do seu Minecraft na primeira execução.

🔒 Segurança e Servidores Multiplayer

O perfil não muda sozinho conforme o tipo de mundo: singleplayer, LAN e servidor dedicado começam em familia. Esse padrão é intencional para mundos privados de pessoas confiáveis; nele, qualquer jogador pode pedir ações como dar itens, construir, invocar mobs, trocar gamemode e teleportar o próprio personagem.

"general": {
  "permissionProfile": "familia" // Opções: "familia", "servidor_publico", "custom"
}

• familia (padrão): indicado para singleplayer, LAN e servidor dedicado privado onde todos são confiáveis. As ferramentas continuam sujeitas aos limites e às confirmações configuradas, mas não exigem OP.
• servidor_publico: deve ser escolhido manualmente por quem abre o servidor ao público. Dar itens, construir, invocar mobs, trocar gamemode, teleportar e outras ações mutáveis passam a exigir OP nível 2; consultas e orientação permanecem abertas.
• custom: respeita os níveis configurados individualmente pelo administrador.

Em servidor dedicado existe uma chave Gemini do anfitrião, usada pelos pedidos de todos os jogadores. A chave fica somente no servidor, em config/virtualassistant/secrets/api_key, com acesso restrito à conta que executa o Minecraft; ela não entra no JAR, no config.json, no chat nem é enviada aos clientes. Para limitar abuso ou custo, configure limits.globalRequestsPerHour e/ou costTracking.monthlyBudget e acompanhe com /assistant usage.

Privacidade: o que sai do computador

• Permanece local: áudio bruto do microfone, transcrição pelo faster-whisper, síntese Piper e reprodução OpenAL. Atalhos fixos também não chamam a IA.
• Vai ao Gemini em pedidos livres: o texto digitado ou já transcrito, histórico recente e o contexto necessário para responder — versão/dimensão/posição, vida e fome, bioma/horário/clima, item na mão/armadura, perigos próximos, locais salvos, última morte e ferramentas que o jogador tem permissão para usar.
• O histórico da conversa fica persistido no save do jogador. O log detalhado de uso registra consumo; o texto das mensagens fica desligado por padrão (costTracking.logMessages=false). Use /assistant clear para limpar o histórico.
• O endereço oficial do Google é o único destino permitido por padrão. Um proxy HTTPS personalizado precisa ser habilitado explicitamente e receberá a chave e o mesmo contexto — use somente um endpoint sob seu controle.

❓ Perguntas Frequentes (FAQ)

1. Preciso pagar para usar o Gemini no mod?

O uso depende da cota e das condições da sua conta no Google AI Studio. O mod mostra consumo estimado em /assistant usage e permite configurar limite global e orçamento mensal.

2. O mod funciona em Singleplayer e Multiplayer?

Sim. Em singleplayer/LAN, STT, TTS e áudio rodam localmente, enquanto pedidos livres usam o Gemini. Em servidores dedicados, o servidor gerencia a chave e as permissões; cada cliente processa sua voz e o áudio 3D.

3. Perdi meu cachorro, e agora?

Basta falar "vem cá" no chat/voz ou usar o comando /assistant reclaim no chat do jogo.

📜 Licença

O Virtual AI Assistant é software proprietário, distribuído sob Todos os Direitos Reservados (All Rights Reserved). O download autoriza o uso pessoal do mod, mas não autoriza copiar, modificar, redistribuir, vender, sublicenciar nem publicar seu código ou arquivos sem permissão prévia e expressa do autor.

Componentes de terceiros permanecem sujeitos às respectivas licenças e não passam a ser proprietários por fazerem parte da distribuição.