Add Paper advanced fork implementation
- Introduce dedicated paper AI script (mc_aigod_paper.py) - Add expanded whitelist for structure ops: fill/setblock/clone - Add deterministic sudo build templates (house/tower/wall/church) - Keep prayer/sudo/memory/intervention architecture from base branch - Add paper-specific config and systemd unit files - Document deployment/runtime in rewritten README
This commit is contained in:
@@ -1,247 +1,110 @@
|
||||
# Minecraft AI God
|
||||
# Minecraft AI God — Paper Advanced Fork
|
||||
|
||||
A Python log-watcher + RCON automation script that gives a vanilla Minecraft server an in-game AI "God".
|
||||
This fork targets a dedicated **Paper** server on port `25567` and adds advanced automation not present in the vanilla-first branch.
|
||||
|
||||
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.
|
||||
## What is new in this fork
|
||||
|
||||
No Bukkit/Paper plugin required.
|
||||
- Dedicated Paper server deployment (`mc-paper-ai.service`)
|
||||
- Plugin stack:
|
||||
- **FastAsyncWorldEdit** (large/fast edits)
|
||||
- **LuckPerms** (permissions foundation)
|
||||
- Separate AI service (`mc-aigod-paper.service`) and config (`/etc/mc_aigod_paper.json`)
|
||||
- Expanded whitelist (`fill`, `setblock`, `clone`) for structure operations
|
||||
- **Sudo build templates** (deterministic multi-command structure generation)
|
||||
- First-login benevolence with multi-command blessings
|
||||
- All legacy features retained: pray, bible, sudo, intervention timer, memory, context, command validation
|
||||
|
||||
---
|
||||
|
||||
## What Is Included
|
||||
## Runtime Topology
|
||||
|
||||
- **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
|
||||
- Paper game port: `25567`
|
||||
- Paper RCON port: `25577`
|
||||
- AI service watches: `/opt/paper-ai-25567/logs/latest.log`
|
||||
- Ollama backend: `http://192.168.0.141:11434`
|
||||
- Message model: `gemma3:12b`
|
||||
- Command model: `qwen3-coder:30b`
|
||||
|
||||
---
|
||||
|
||||
## Trigger Commands (Chat, No Slash)
|
||||
## Services
|
||||
|
||||
Vanilla 1.21 rejects unknown slash commands client-side. Use plain chat messages:
|
||||
- `mc-paper-ai.service` — Paper server process
|
||||
- `mc-aigod-paper.service` — AI orchestration process
|
||||
|
||||
- `pray <message>` — prayer flow (God judgment + optional commands + speech)
|
||||
- `bible` — private usage/help text
|
||||
- `sudo <request>` — command translator mode (authorized user only)
|
||||
Useful commands:
|
||||
|
||||
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
|
||||
```bash
|
||||
systemctl status mc-paper-ai.service
|
||||
systemctl status mc-aigod-paper.service
|
||||
journalctl -fu mc-paper-ai.service
|
||||
journalctl -fu mc-aigod-paper.service
|
||||
```
|
||||
|
||||
### 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
|
||||
## Chat Triggers (no slash)
|
||||
|
||||
### Prayer / Intervention context
|
||||
- `pray <message>` — God prayer flow
|
||||
- `bible` — help text
|
||||
- `sudo <request>` — translator mode (authorized user only)
|
||||
|
||||
- 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)
|
||||
### New: deterministic build mode via sudo
|
||||
|
||||
### Praying player state
|
||||
If a sudo request starts with `build`, `make`, or `create`, the fork uses deterministic templates before LLM translation.
|
||||
|
||||
- Inventory summary (with rarity annotations)
|
||||
- Health
|
||||
- Food level
|
||||
- XP level
|
||||
- Death count
|
||||
Examples:
|
||||
|
||||
### Sudo context
|
||||
- `sudo build house`
|
||||
- `sudo build tower`
|
||||
- `sudo create church`
|
||||
- `sudo build wall`
|
||||
|
||||
- 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
|
||||
These trigger multi-command `fill/setblock/give` sequences near the player and are optimized for Paper performance.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Main file: `/etc/mc_aigod.json`
|
||||
Main file: `/etc/mc_aigod_paper.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 |
|
||||
Important keys:
|
||||
|
||||
### 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"
|
||||
}
|
||||
```
|
||||
- `log_path`: `/opt/paper-ai-25567/logs/latest.log`
|
||||
- `rcon_port`: `25577`
|
||||
- `sudo_max_commands`: default `12` (higher for build bursts)
|
||||
- `interventions_per_day`: default `24`
|
||||
- `first_login_benevolence_max_commands`: default `12`
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
## Backwards Compatibility
|
||||
|
||||
```bash
|
||||
# Dependencies
|
||||
apt install -y python3-requests
|
||||
This fork is derived from the original architecture and remains broadly compatible:
|
||||
|
||||
# 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
|
||||
- Same trigger style (`pray`, `bible`, `sudo`)
|
||||
- Same command validation and syntax repair pipeline
|
||||
- Same memory model concepts
|
||||
- Same two-call LLM split
|
||||
|
||||
# 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
|
||||
```
|
||||
You can run the vanilla branch and this Paper fork side-by-side because they use separate files, ports, and services.
|
||||
|
||||
---
|
||||
|
||||
## Debugging Checklist
|
||||
## Deploy (already applied in this environment)
|
||||
|
||||
- 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`
|
||||
1. Install Paper server in `/opt/paper-ai-25567`
|
||||
2. Install plugins in `/opt/paper-ai-25567/plugins`
|
||||
3. Install `mc-paper-ai.service`
|
||||
4. Install `mc_aigod_paper.py` to `/usr/local/bin/mc_aigod_paper.py`
|
||||
5. Install `/etc/mc_aigod_paper.json`
|
||||
6. Install `mc-aigod-paper.service`
|
||||
7. Enable + start both services
|
||||
|
||||
---
|
||||
|
||||
## File Map
|
||||
## Notes
|
||||
|
||||
- `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`
|
||||
- If a model generates malformed `give`/`effect` syntax, auto-repair handlers normalize common forms.
|
||||
- If a slang item appears (`wood`, `doors`, etc.), alias normalization attempts valid item IDs.
|
||||
- Build templates are deterministic first, LLM second, to reduce surprises for complex build tasks.
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
[Unit]
|
||||
Description=Minecraft AI God (Paper Fork)
|
||||
After=network.target mc-paper-ai.service
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
ExecStart=/usr/bin/python3 /usr/local/bin/mc_aigod_paper.py
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@@ -0,0 +1,25 @@
|
||||
{
|
||||
"server_name": "paper-ai-25567",
|
||||
"log_path": "/opt/paper-ai-25567/logs/latest.log",
|
||||
"rcon_host": "127.0.0.1",
|
||||
"rcon_port": 25577,
|
||||
"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": 700,
|
||||
"cooldown_seconds": 10,
|
||||
"max_commands_per_response": 8,
|
||||
"interventions_per_day": 24,
|
||||
"god_chat_prefix": "[§b§lPAPER GOD§r]",
|
||||
"debug_commands": true,
|
||||
"sudo_enabled": true,
|
||||
"sudo_user": "slingshooter08",
|
||||
"sudo_max_commands": 12,
|
||||
"first_login_benevolence_enabled": true,
|
||||
"first_login_benevolence_max_commands": 12,
|
||||
"first_login_path": "/opt/paper-ai-25567/aigod_first_login_seen.json",
|
||||
"god_lore": "This is the Paper AI world. God may grant structures, blessings, and rapid build packages. The world rewards creative construction and experimentation.",
|
||||
"memory_path": "/opt/paper-ai-25567/aigod_memory.json"
|
||||
}
|
||||
+1631
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user