Cametendo/minecraft-ai-companion-mod-EMVs12-Project
1
1
Fork 0
mirror of https://github.com/ritonioz/minecraft-ai-companion-mod-EMVs12-Project.git synced 2026-06-20 20:25:01 +02:00
Code Issues Packages Projects Releases Wiki Activity

Added customization

Browse Source
This commit is contained in:
Cametendo
2026-03-26 20:13:18 +01:00
parent 90ba17c108
commit 14d8b0c431
10 changed files with 973 additions and 251 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
README.md
View File

@@ -4,52 +4,118 @@
---
## About
This Minecraft mod allows players, especially new ones, to get real-time assistance. If you are confused about a mechanic or a location, simply ask your "Companion" for advice.
- Example: If a player is in the Deep Dark, they can ask: "What can I do here?" and the AI will provide useful tips and warnings about the Warden.
Minecraft AI Companion adds an AI-powered helper to Minecraft. You can ask questions directly in chat, or spawn a companion entity that follows you and opens its own chat window when you right-click it.
The mod is especially useful for newer players, but it also works as a general in-game assistant depending on the mode you choose.
Examples:
- "What can I do in the Deep Dark?"
- "How do I find Netherite?"
- "What does this structure do?"
## Requirements & Version
* **Game Version:** 1.21.1
* **Minecraft Version:** 1.20.1
* **Java Version:** 17+
* **Loader:** [Fabric Loader](https://fabricmc.net/)
* **Dependencies:** [Fabric API](https://www.curseforge.com/minecraft/mc-mods/fabric-api)
* **Information**: This mod uses a self-hosted-AI. Active Internet connection and API key required (no subscription).
* **API Key**: This Mod requires an API key from [ai.cametendo.org](https://ai.cametendo.org). Steps on how to acquire an API will be listed further down in the README.
* **Dependency:** [Fabric API](https://www.curseforge.com/minecraft/mc-mods/fabric-api)
* **Internet:** Required when using a remote AI provider
* **AI Backend:** Supports local or self-hosted providers such as Ollama, Open-WebUI, or a custom OpenAI-compatible endpoint
## Usage
There are three commands included in this mod:
- `/ai question`: This will let you communicate with the AI directly from the In-Game Chat
- `/ai spawn`: This will spawn an actual entity, your 'Companion' (multiple companions can be spawned). It will follow you around and can be interacted with by right-clicking.
- `/ai kill`: This will kill / remove all companions you spawned
- `/ai delete-key`: This lets you delete your API-Key, incase you deleted your account on the WebUI or experience other problems, you can use this command to enter a new key.
- Note: Depending on the question the AI will take 1 - 3 minutes to respond. Please be patient while your companion "thinks"!
## Features
- Ask questions directly from in-game chat with `/ai question <message>`
- Spawn one or more AI companion entities with `/ai spawn`
- Right-click a companion to open a persistent chat window for the current world session
- Choose between different AI providers:
Ollama, Open-WebUI, or a custom endpoint
- Fetch available models directly from the configured provider
- Switch between two AI behavior modes:
`Casual` for a general assistant, or `Minecraft` to restrict answers to Minecraft-related topics
- Change the selected model later without redoing the full setup
- Delete only the stored API key, or reset the full AI configuration
- Stored API keys are saved locally in config files and are encrypted when possible
## AI Companion Entity
The AI Companion doesn't just stand around, he too has his own features:
## Commands
The mod currently includes these commands:
- `Chat-Window`: Right-clicking the Companion will open a chat window. In this, you will have a chat-interface that keeps your chat until you leave the world.
- `Follows you`: Instead of just standing around, the companion will ffollow you around wherever you go and walk around the world.
- `API-Key-Verification`: The first time you play this mod, you may need to use the companion to enter your API key.
- `/ai question <question>`
Sends a question to the configured AI provider and returns the answer in chat.
- `/ai spawn`
Spawns an AI companion entity at your position.
- `/ai kill`
Removes all spawned AI companions.
- `/ai delete-key`
Deletes the stored API key but keeps the rest of the provider configuration.
- `/ai delete-config`
Deletes the full saved AI configuration so setup starts from scratch next time.
- `/ai model`
Opens the model selection screen.
- `/ai change-mode`
Opens the mode selection screen.
Note: Response time depends on your provider, model, and hardware. Local models or busy servers may take longer to answer.
## AI Companion Entity
The AI Companion is more than just a decoration:
- `Follow Owner`: The companion follows the player who spawned it.
- `Right-Click Chat`: Interacting with the entity opens the companion chat screen.
- `Persistent Session per World Join`: Companion chat history stays available until you leave the world/server.
- `Invulnerable`: The entity cannot be damaged through normal gameplay.
- `Custom Appearance`: The companion uses a custom player-style model and can temporarily switch appearance through a built-in easter egg.
## First-Time Setup
The first time you use an AI feature, the setup screen opens automatically.
You can configure:
- `Provider Preset`
Choose `Ollama`, `Open-WebUI`, or `Custom`
- `Base URL`
Example: `http://localhost:11434` for Ollama
- `API Key`
Optional for local providers, required for protected remote providers
- `Model`
Fetch available models from the provider, or enter one manually
- `Advanced API Path`
Optional custom chat-completions path for OpenAI-compatible endpoints
- `Mode`
`Casual` or `Minecraft`
After saving, the mod stores the configuration in the `config/` folder and reuses it automatically.
## Provider Notes
- `Ollama`
Best for fully local use. Usually works with `http://localhost:11434` and supports model fetching from the setup screen.
- `Open-WebUI`
Works with Open-WebUI-compatible chat completion endpoints and model lists.
- `Custom`
Use this for any self-hosted or compatible provider with a custom base URL and optional custom API path.
If no custom API path is set, the client automatically tries standard chat-completions endpoints.
## Installation
1. If not already done, install [Fabric 1.21.1](https://maven.fabricmc.net/net/fabricmc/fabric-installer/1.1.1/fabric-installer-1.1.1.jar). (Click to download the Fabric Installer instantly)
2. Download the mod from the [Releases](https://github.com/Cametendo/minecraft-ai-companion-EMVs12-Project/releases) Tab.
3. Place the `.jar` file in your `%appdata%/.minecraft/mods` folder.
4. Launch the game in your preferred launcher with the Fabric 1.21.1 Profile ([List of Minecraft Launchers](https://github.com/TayouVR/MinecraftLauncherComparison)) <br>
1. Install [Fabric Loader](https://fabricmc.net/use/installer/) for Minecraft 1.20.1 if you have not already done so.
2. Download the mod `.jar` from the [Releases](https://github.com/Cametendo/minecraft-ai-companion-EMVs12-Project/releases) page.
3. Place the `.jar` file into your Minecraft `mods` folder.
4. Make sure [Fabric API](https://www.curseforge.com/minecraft/mc-mods/fabric-api) is installed as well.
5. Start Minecraft with your Fabric 1.20.1 profile.
**IMPORTANT**: This Installation Process is strictly for the offical version of Minecraft (including the official Launcher). We are not not responsible for any issues, data loss, or crashes that may occur when using third-party launchers or unofficial versions of the game. Support is only guaranteed for the official Fabric environment.
**Important:** Support is only guaranteed for the official Java Edition + Fabric environment. Third-party launchers or unofficial game versions may work, but are not officially supported.
## API-Key
This mod requires an API key. To acquire an API key, follow these steps:
1. Create an account on [ai.cametendo.org](https://ai.cametendo.org)
2. Press your user profile (bottom-left corner) and switch to the tab "Account".
3. Find the option "API Keys" and press show. A very long line of dots should appear. This is your API key (hidden by default).
4. Copy it and start your game (or go back to it if it's already open)
5. Use /ai question and enter a question. A new window with "Enter your Open-WebUI API-Key" should appear. In the text box, enter your API Key and confirm it by pressing enter.
6. Alternatively, if that didn't work, use /ai spawn to spawn your AI Companion. THen right-click it and you should see the "Enter your Open-WebUI API-Key" window. Enter it into the text box and confirm it by pressing enter.
7. If everything worked, you can now send messages to your AI Companion. Have fun!
## API Key
You only need an API key if your chosen AI provider requires one.
If you are using a hosted Open-WebUI instance such as ai.example.org, the general flow is:
1. Create an account on the provider website.
2. Open your account settings and generate or reveal an API key.
3. Copy the key.
4. In Minecraft, use any AI feature such as `/ai question <question>` or `/ai spawn`.
5. When the setup screen opens, paste the API key into the `API Key` field.
6. Choose the correct provider URL and model, then save the configuration.
If your provider does not require a key, you can leave that field empty.
## License & Credits
* **Authors:** [Cametendo](https://www.github.com/Cametendo), [ritonioz](https://www.github.com/ritonioz), [Adam237A](https://www.github.com/Adam237A)
* **License:** CC0 1.0 (Public Domain). Feel free to include this in any modpack! (Credits are appreciated but not required).
* **License:** CC0 1.0 (Public Domain). Feel free to include this mod in any modpack. Credits are appreciated, but not required.
NOT AN OFFICIAL MINECRAFT SERVICE. NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT
NOT AN OFFICIAL MINECRAFT SERVICE. NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT.