<li><strong>Install Fabric Loader & API:</strong> Follow the instructions <ahref="https://fabricmc.net/use/">here</a>.</li>
<li><strong>Install CreatureChat Mod:</strong> Download and copy <code>creaturechat-*.jar</code> and <code>fabric-api-*.jar</code> into your <code>.minecraft/mods</code> folder.</li>
<li><strong>Create an OpenAI API key:</strong> Visit <ahref="https://platform.openai.com/api-keys">https://platform.openai.com/api-keys</a>, and use the <strong>+ Create new secret key</strong> button.
Copy/Paste your key into the <code>/creaturechat key set <YOUR-SECRET-KEY-HERE></code> command.</li>
<li><strong>Launch Minecraft</strong> with the Fabric profile.</li>
</ol>
</details>
<details>
<summary>Forge (with Sinytra Connector)</summary>
<h3>Forge Instructions</h3>
<h4>NOTE: Sintra Connector only supports Minecraft 1.20.1</h4>
<ol>
<li><strong>Install Forge:</strong> Download <ahref="https://files.minecraftforge.net/">Forge Installer</a>, run it, select "Install client".</li>
<li><strong>Install Forgified Fabric API:</strong> Download <ahref="https://curseforge.com/minecraft/mc-mods/forgified-fabric-api">Forgified Fabric API</a> and copy the <code>*.jar</code> into your <code>.minecraft/mods</code> folder.</li>
<li><strong>Install Sinytra Connector:</strong> Download <ahref="https://www.curseforge.com/minecraft/mc-mods/sinytra-connector">Sinytra Connector</a> and copy the <code>*.jar</code> into your <code>.minecraft/mods</code> folder.</li>
<li><strong>Install CreatureChat Mod:</strong> Download and copy <code>creaturechat-*.jar</code> into your <code>.minecraft/mods</code> folder.</li>
<li><strong>Create an OpenAI API key:</strong> Visit <ahref="https://platform.openai.com/api-keys">https://platform.openai.com/api-keys</a>, and use the <strong>+ Create new secret key</strong> button.
Copy/Paste your key into the <code>/creaturechat key set <YOUR-SECRET-KEY-HERE></code> command.</li>
<li><strong>Launch Minecraft</strong> with the Forge profile.</li>
</ol>
</details>
### In-game Commands
<details>
<summary>Configure CreatureChat</summary>
<ul>
<li><strong>REQUIRED:</strong><code>/creaturechat key set <key></code>
<ul>
<li>Sets the <em>OpenAI API key</em>. This is required for making requests to the LLM.</li>
</ul>
</li>
<li><strong>OPTIONAL:</strong><code>/creaturechat url set "<url>"</code>
<ul>
<li>Sets the URL of the API used to make LLM requests. Defaults to <code>"https://api.openai.com/v1/chat/completions"</code></li>
</ul>
</li>
<li><strong>OPTIONAL:</strong><code>/creaturechat model set <model></code>
<ul>
<li>Sets the model used for generating responses in chats. Defaults to <code>gpt-3.5-turbo</code>.</li>
</ul>
</li>
<li><strong>OPTIONAL:</strong><code>/creaturechat timeout set <seconds></code>
<ul>
<li>Sets the timeout (in seconds) for API HTTP requests. Defaults to <code>10</code> seconds.</li>
</ul>
</li>
<li><strong>OPTIONAL:</strong><code>/creaturechat whitelist <entityType | all | clear></code> - Show chat bubbles
<ul>
<li>Shows chat bubbles for the specified entity type or all entities, or clears the whitelist.</li>
<li>Hides chat bubbles for the specified entity type or all entities, or clears the blacklist.</li>
</ul>
</li>
</ul>
<h4>Configuration Scope:</h4>
<ul>
<li><strong>OPTIONAL:</strong> You can specify the configuration scope at the end of each command to determine where settings should be applied:
<ul>
<li><strong>Default</strong> Configuration (<code>--config default</code>): Applies the configuration universally, unless overridden by a server-specific configuration.</li>
<li><strong>Server</strong>-Specific Configuration (<code>--config server</code>): Applies the configuration only to the server where the command is executed.</li>
<li>If the <code>--config</code> option is not specified, the <code>default</code> configuration scope is assumed.</li>
</ul>
</li>
</ul>
</details>
### Does OpenAI offer a **FREE** model?
While ChatGPT is a popular product and does offer a free version to their users on their website,
the OpenAI developer API does not extend any free models or free usage. You will be charged for each token
consumed and generated. We use the `gpt-3.5-turbo` model by default, due to its low cost
and fast performance... however it is not free.
### Free Local LLM
CreatureChat fully supports **free & open-source** LLMs. An HTTP endpoint which supports the OpenAI Chat Completion
JSON syntax is required. We highly recommend using [Ollama](https://ollama.com/) or [LiteLLM](https://litellm.vercel.app/) as your HTTP proxy.
LiteLLM supports **100+ LLMs** (including Anthropic, VertexAI, HuggingFace, Google Gemini, and Ollama), and proxies them through a
local HTTP endpoint in a compatible format with CreatureChat. *NOTE: You must have a very expensive GPU to run a local
LLM on your computer at a speed which is fast enough to be playable in Minecraft.*
### Costs & Security
Using third-party Large Language Model (LLM) APIs, such as OpenAI, will incur usage-based **fees**.
These fees are based on the amount of data processed. Before integrating your API key, please
[review the pricing](https://openai.com/pricing#language-models) details provided by the API provider.
Be aware of the **potential costs** and plan your usage accordingly to avoid unexpected charges.
## Installation Instructions
### Fabric (Recommended)
1.**Install Fabric Loader & API:** Follow the instructions [here](https://fabricmc.net/use/).
2.**Install CreatureChat Mod:** Download and copy `creaturechat-*.jar` and `fabric-api-*.jar` into your `.minecraft/mods` folder.
3.**Launch Minecraft** with the Fabric profile.
4.**Configure AI:** A LLM (large language model) is required for generating text (AI options **listed below**)
### Forge (with Sinytra Connector)
*NOTE: Sintra Connector only supports Minecraft 1.20.1.*
1.**Install Forge:** Download [Forge Installer](https://files.minecraftforge.net/), run it, select "Install client".
2.**Install Forgified Fabric API:** Download [Forgified Fabric API](https://curseforge.com/minecraft/mc-mods/forgified-fabric-api) and copy the `*.jar` into your `.minecraft/mods` folder.
3.**Install Sinytra Connector:** Download [Sinytra Connector](https://www.curseforge.com/minecraft/mc-mods/sinytra-connector) and copy the `*.jar` into your `.minecraft/mods` folder.
4.**Install CreatureChat Mod:** Download and copy `creaturechat-*.jar` into your `.minecraft/mods` folder.
6.**Launch Minecraft** with the Forge profile.
7.**Configure AI:** A LLM (large language model) is required for generating text (AI options **listed below**)
## AI Options
CreatureChat **requires** an AI / LLM (large language model) to generate text (characters and chat). There are many different
options for connecting an LLM.
1.**Free & Local**: Use open-source and free-to-use LLMs without any API fees. [**Difficulty: Hard**]
2.**Bring Your Own Key**: Use your own API key from providers like OpenAI or Groq. [**Difficulty: Medium**]
3.**Token Shop**: Supports CreatureChat by purchasing tokens from the developers on Discord. [**Difficulty: Easy**]
### 1. Free & Local
CreatureChat fully supports **free and open-source** LLMs. To get started:
- An HTTP endpoint compatible with the OpenAI Chat Completion JSON syntax is required. We highly recommend using:
-[Ollama](https://ollama.com/) & [LiteLLM](https://litellm.vercel.app/) as your HTTP proxy.
-**LiteLLM Features:**
- Supports over **100+ LLMs** (e.g., Anthropic, VertexAI, HuggingFace, Google Gemini, and Ollama).
- Proxies them through a local HTTP endpoint compatible with CreatureChat.
-**Note:** Running a local LLM on your computer requires a powerful GPU.
- Set the local HTTP endpoint in-game:
-`/creaturechat url set "http://ENTER-YOUR-HTTP-ENDPOINT-FROM-LITE-LLM"`
-`/creaturechat model set ENTER-MODEL-NAME`
-`/creaturechat timeout set 360`
- Additional help can be found in the **#locall-llm-info** channel on our [Discord](https://discord.gg/m9dvPFmN3e).
### 2. Bring Your Own Key
For those already using a third-party API (e.g., OpenAI, Groq):
- Integrate your own API key for seamless connectivity.
- Costs depend on the provider’s usage-based pricing model.
- By default, CreatureChat uses the OpenAI endpoint and `gpt-3.5-turbo` model, known for its balance of low cost and fast performance.
- Be aware that OpenAI’s developer API does not include free usage. Please review the [OpenAI pricing](https://openai.com/pricing#language-models) for detailed information.
- To create an OpenAI API key, visit [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys), and use the **+ Create new secret key** button.
- Set the API key & model in-game:
-`/creaturechat key set <YOUR-SECRET-KEY-HERE>`
-`/creaturechat model set gpt-3.5-turbo`
### 3. Token Shop
Supports CreatureChat by purchasing tokens from the developers:
- Easy setup with simple token packs, created for CreatureChat users.
- More info is available in the #token-shop channel on our [Discord](https://discord.gg/m9dvPFmN3e).
- Set the token-shop API key in-game:
-`/creaturechat key set <YOUR-SECRET-KEY-HERE>`
### In-game Commands / Configuration
-**REQUIRED:**`/creaturechat key set <key>`
- Sets the *OpenAI API key*. This is required for making requests to the LLM.
-**OPTIONAL:**`/creaturechat url set "<url>"`
- Sets the URL of the API used to make LLM requests. Defaults to `"https://api.openai.com/v1/chat/completions"`.
-**OPTIONAL:**`/creaturechat model set <model>`
- Sets the model used for generating responses in chats. Defaults to `gpt-3.5-turbo`.
-**OPTIONAL:**`/creaturechat timeout set <seconds>`
- Sets the timeout (in seconds) for API HTTP requests. Defaults to `10` seconds.
-**OPTIONAL:**`/creaturechat whitelist <entityType | all | clear>` - Show chat bubbles
- Shows chat bubbles for the specified entity type or all entities, or clears the whitelist.
