Seth/minecraft-ai-god-paper-fork
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
83b9037a9419011991aacd4910994ac4fad0d3cd
minecraft-ai-god-paper-fork/README.md
T
Seth 83b9037a94 Docs: full README refresh for current runtime behavior 
- Rewrite README to reflect live architecture and feature set
- Document pray/bible/sudo triggers (chat without slash)
- Document two-call model split and context payloads
- Add first-login benevolence behavior and persistence
- Add sudo history context and whitelist details
- Update config table and shrink-world example values
- Refresh deployment and debugging sections
2026-03-15 21:24:52 -04:00

248 lines
7.4 KiB
Markdown
Raw Blame History

# Minecraft AI God
A Python log-watcher + RCON automation script that gives a vanilla Minecraft server an in-game AI "God".
Players type chat triggers (`pray`, `bible`, `sudo`) and the agent:
- reads context from server state + player state + recent logs,
- calls local LLM(s),
- executes validated commands via RCON,
- and speaks in public chat.
No Bukkit/Paper plugin required.
---
## What Is Included
- **God prayer pipeline** (`pray <message>`)
- **Two-call LLM architecture**
- command model decides commands (JSON)
- message model writes divine speech (text)
- **Divine intervention timer** (random unprompted acts)
- **First-login benevolence** (one-time blessing per player)
- **Bundled sudo translator agent** (`sudo <request>`) with whitelist + user lock
- **Persistent prayer memory**
- **Rolling server event memory** (up to 3 hours / 200 events)
- **Debug command preview** toggle
---
## Trigger Commands (Chat, No Slash)
Vanilla 1.21 rejects unknown slash commands client-side. Use plain chat messages:
- `pray <message>` — prayer flow (God judgment + optional commands + speech)
- `bible` — private usage/help text
- `sudo <request>` — command translator mode (authorized user only)
Examples:
- `pray Lord, I need food and shelter`
- `bible`
- `sudo give me 500 wood`
---
## Architecture
```text
chat line -> latest.log tail -> trigger parser
pray path:
ack player -> gather context -> commands call -> message call -> execute commands -> broadcast message
sudo path:
auth check -> translate request to commands -> validate/repair -> execute -> private preview
join path:
login notice -> one-time first-login benevolence event
timer path:
poisson interval -> if players online -> intervention commands+message
```
### Two-call design (prayer/intervention)
1. **Commands call** (`command_model`)
- strict JSON output
- low temp for stable command generation
2. **Message call** (`model`)
- prose only
- no token competition with command JSON
This avoids the common failure mode where long speech truncates commands.
---
## Context Passed to LLM
### Prayer / Intervention context
- Online players
- Player positions + distance from spawn
- Time of day, weather, world border
- Scoreboard-derived state where available (deaths, shrink flags)
- Recent server events (chat/death/join/leave), capped by both:
- last **3 hours**
- last **200 events**
- Prayer memory (last 10 exchanges)
### Praying player state
- Inventory summary (with rarity annotations)
- Health
- Food level
- XP level
- Death count
### Sudo context
- Requesting player
- Online players
- Current natural-language sudo request
- Last 10 sudo actions:
- request text
- translated commands
- executed commands
This helps sudo correct previous bad translations.
---
## Safety and Validation
- Command-family whitelist enforced (`give`, `effect`, `xp`, `tp`, `time`, `weather`, `execute`, `kill`, `summon`, `tellraw`, `worldborder`)
- Auto-repair for common malformed outputs:
- transposed `give` args (`give player 64 item`)
- missing `minecraft:` namespace
- shorthand aliases (`wood` -> `oak_log`, `door` -> `oak_door`, `bed` -> `white_bed`, etc.)
- malformed `effect` form corrected to `effect give ...`
- Max commands per response cap
- Per-player prayer cooldown
- First-login benevolence can include many commands but is benevolent by prompt rules
- If kill commands appear in first-login mode, at most one player kill is allowed
---
## Configuration
Main file: `/etc/mc_aigod.json`
| Key | Type | Description |
|---|---|---|
| `server_name` | string | Friendly server name for prompts |
| `log_path` | string | Absolute path to `latest.log` |
| `rcon_host` | string | RCON host |
| `rcon_port` | int | RCON port |
| `rcon_password` | string | RCON password |
| `ollama_url` | string | Ollama API base URL |
| `model` | string | Message model (creative prose) |
| `command_model` | string | Command model (JSON/command generation) |
| `temperature` | float | Message generation temperature |
| `max_tokens` | int | Message call max tokens |
| `cooldown_seconds` | int | Prayer cooldown per player |
| `max_commands_per_response` | int | Max commands in prayer/intervention response |
| `interventions_per_day` | float | Avg random acts/day (Poisson) |
| `god_chat_prefix` | string | Prefix for God speech |
| `debug_commands` | bool | Show `[~]` command preview in chat |
| `god_lore` | string | Optional lore block injected into message system prompt |
| `memory_path` | string | Prayer memory JSON path |
| `sudo_enabled` | bool | Enable/disable sudo agent |
| `sudo_user` | string | Authorized sudo username |
| `sudo_max_commands` | int | Max commands translated from one sudo request |
| `first_login_benevolence_enabled` | bool | Enable one-time first-login blessing |
| `first_login_benevolence_max_commands` | int | Max commands in first-login blessing |
| `first_login_path` | string | Persistent file storing already-blessed players |
### Current shrink-world example
```json
{
"server_name": "shrink-world",
"log_path": "/opt/mcsmanager/daemon/data/InstanceData/shrinkborder1234567890abcdef12345/logs/latest.log",
"rcon_host": "127.0.0.1",
"rcon_port": 25576,
"rcon_password": "REDACTED_RCON",
"ollama_url": "http://192.168.0.141:11434",
"model": "gemma3:12b",
"command_model": "qwen3-coder:30b",
"temperature": 0.85,
"max_tokens": 600,
"cooldown_seconds": 20,
"max_commands_per_response": 6,
"interventions_per_day": 48,
"god_chat_prefix": "[§6§lGOD§r]",
"debug_commands": true,
"sudo_enabled": true,
"sudo_user": "slingshooter08",
"sudo_max_commands": 3,
"first_login_benevolence_enabled": true,
"first_login_benevolence_max_commands": 10,
"first_login_path": "/opt/mcsmanager/daemon/data/InstanceData/shrinkborder1234567890abcdef12345/aigod_first_login_seen.json",
"god_lore": "This is the shrink-world server...",
"memory_path": "/opt/mcsmanager/daemon/data/InstanceData/shrinkborder1234567890abcdef12345/aigod_memory.json"
}
```
---
## Deployment
```bash
# Dependencies
apt install -y python3-requests
# Install script + config + service
cp mc_aigod.py /usr/local/bin/mc_aigod.py
chmod +x /usr/local/bin/mc_aigod.py
cp mc_aigod_shrink.json /etc/mc_aigod.json
cp mc-aigod.service /etc/systemd/system/mc-aigod.service
# Start service
systemctl daemon-reload
systemctl enable --now mc-aigod.service
# Logs
journalctl -fu mc-aigod.service
tail -f /var/log/mc_aigod.log
tail -f /var/log/mc_aigod_responses.log
```
---
## Debugging Checklist
- No response on trigger?
- Ensure you typed `pray` / `bible` / `sudo` in chat **without slash**
- Sudo does nothing?
- Confirm username matches `sudo_user`
- Check `sudo_enabled`
- Unknown item errors?
- See `/var/log/mc_aigod.log` for translated command + server error
- Alias/repair may still need extension for new slang terms
- Long God speech issues?
- Two-call design is active; commands are decided separately from message text
- Random acts too frequent?
- Lower `interventions_per_day`
---
## File Map
- `mc_aigod.py` — main script
- `mc_aigod_shrink.json` — real config template
- `mc-aigod.service` — systemd unit
- `Minecraft_Ai_God.md` — deeper design/context notes
- `CONTEXT.md` / `COMMANDS.md` — local infrastructure references
---
## Deployed Reference (Sethpc)
- Host: CT 644 (MCSManager)
- Server: `shrink-world` (RCON `25576`)
- Ollama: `http://192.168.0.141:11434`
- Models:
- message: `gemma3:12b`
- commands: `qwen3-coder:30b`
- Service: `mc-aigod.service`
Reference in New Issue View Git Blame Copy Permalink