108 lines
2.9 KiB
Markdown
108 lines
2.9 KiB
Markdown
# cletus
|
||
|
||
Cletus is a Java Edition Minecraft bot built with AI and Mineflayer. The goal is to have Cletus become somewhat autonomous.
|
||
|
||
# Cletus Bot – A Learning Minecraft AI
|
||
|
||
Cletus is a modular Mineflayer-based Minecraft bot designed to observe, learn, adapt, and evolve through tasks, memory, and AI interaction. It reads signs, listens to players, remembers context, and uses a local AI model to improve over time.
|
||
|
||
---
|
||
|
||
## Features
|
||
- **State-driven AI**: Uses a dynamic state machine (`/states`) to handle tasks like `Observe`, `ReadFromSign`, `Idle`, `HandleChat`, etc.
|
||
- **Memory system**: Persists events, chats, locations, and signs in SQLite via `/memory`
|
||
- **Safe zones**: Prevents accidental destruction near homes, beds, bases, and more
|
||
- **AI integration**: Uses [Ollama](https://ollama.ai) with `gemma3` or any LLM to chat and rewrite failed scripts
|
||
- **Self-growing**: Failed task scripts are auto-sent to AI for improvement and saved
|
||
|
||
---
|
||
|
||
## Folder Structure
|
||
```txt
|
||
├── bot.js # Bot entrypoint
|
||
├── config.json # Centralized bot and AI config
|
||
├── core/
|
||
│ ├── state-machine.js # Loads and manages dynamic states
|
||
│ └── context.js # Shared bot context for state/tasks
|
||
├── states/ # Modular AI states (Observe, Idle, etc.)
|
||
├── bot-tasks/ # AI or manually written task modules
|
||
├── memory/ # Memory modules (chat, signs, events, etc.)
|
||
├── lib/
|
||
│ ├── ai-helper.js # AI chat integration
|
||
│ └── utils.js # (Optional helper utils)
|
||
├── db/
|
||
│ └── memory.db # SQLite database (auto-created)
|
||
```
|
||
|
||
---
|
||
|
||
## Config (`config.json`)
|
||
```json
|
||
{
|
||
"bot": {
|
||
"name": "Cletus",
|
||
"host": "192.168.1.90",
|
||
"port": 25565,
|
||
"auth": "offline",
|
||
"version": "1.20.4"
|
||
},
|
||
"ai": {
|
||
"model": "gemma3",
|
||
"ollamaUrl": "http://localhost:11434/api/generate",
|
||
"persona": "a curious minecraft explorer who learns from the world around them",
|
||
"responseLength": 30
|
||
},
|
||
"safeZone": {
|
||
"xBound": 50,
|
||
"yBound": 30,
|
||
"zBound": 50,
|
||
"keywords": ["home", "bed", "base", "village", "farm"]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🛠 Prerequisites
|
||
- [Node.js](https://nodejs.org/) (v16+)
|
||
- [Ollama](https://ollama.ai) running locally with `gemma3` or compatible model
|
||
- Minecraft server (1.20.4) with bot permissions
|
||
|
||
---
|
||
|
||
## Running the Bot
|
||
```bash
|
||
npm install
|
||
node bot.js
|
||
```
|
||
|
||
Then in Minecraft:
|
||
```
|
||
Say: Cletus, go find a flower
|
||
```
|
||
|
||
---
|
||
|
||
## Extending Cletus
|
||
- Add new tasks to `/bot-tasks/`
|
||
- Add new states to `/states/`
|
||
- Memory system will auto-track chat, signs, events
|
||
- AI auto-rewrites broken tasks using `chatWithAI()`
|
||
|
||
---
|
||
|
||
## AI Improvement Loop
|
||
1. You run a task
|
||
2. If it fails → AI rewrites the file
|
||
3. File is overwritten and reused on next run
|
||
|
||
---
|
||
|
||
## Example Tasks
|
||
- `find-flower`
|
||
- `observe`
|
||
- `read-from-sign`
|
||
- `idle`
|
||
|
||
> Want Cletus to do more? Just ask him in chat.
|
||
|