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:
|
## What is new in this fork
|
||||||
- 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.
|
- 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>`)
|
- Paper game port: `25567`
|
||||||
- **Two-call LLM architecture**
|
- Paper RCON port: `25577`
|
||||||
- command model decides commands (JSON)
|
- AI service watches: `/opt/paper-ai-25567/logs/latest.log`
|
||||||
- message model writes divine speech (text)
|
- Ollama backend: `http://192.168.0.141:11434`
|
||||||
- **Divine intervention timer** (random unprompted acts)
|
- Message model: `gemma3:12b`
|
||||||
- **First-login benevolence** (one-time blessing per player)
|
- Command model: `qwen3-coder:30b`
|
||||||
- **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)
|
## 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)
|
Useful commands:
|
||||||
- `bible` — private usage/help text
|
|
||||||
- `sudo <request>` — command translator mode (authorized user only)
|
|
||||||
|
|
||||||
Examples:
|
```bash
|
||||||
- `pray Lord, I need food and shelter`
|
systemctl status mc-paper-ai.service
|
||||||
- `bible`
|
systemctl status mc-aigod-paper.service
|
||||||
- `sudo give me 500 wood`
|
journalctl -fu mc-paper-ai.service
|
||||||
|
journalctl -fu mc-aigod-paper.service
|
||||||
---
|
|
||||||
|
|
||||||
## 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
|
## Chat Triggers (no slash)
|
||||||
|
|
||||||
### Prayer / Intervention context
|
- `pray <message>` — God prayer flow
|
||||||
|
- `bible` — help text
|
||||||
|
- `sudo <request>` — translator mode (authorized user only)
|
||||||
|
|
||||||
- Online players
|
### New: deterministic build mode via sudo
|
||||||
- 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
|
If a sudo request starts with `build`, `make`, or `create`, the fork uses deterministic templates before LLM translation.
|
||||||
|
|
||||||
- Inventory summary (with rarity annotations)
|
Examples:
|
||||||
- Health
|
|
||||||
- Food level
|
|
||||||
- XP level
|
|
||||||
- Death count
|
|
||||||
|
|
||||||
### Sudo context
|
- `sudo build house`
|
||||||
|
- `sudo build tower`
|
||||||
|
- `sudo create church`
|
||||||
|
- `sudo build wall`
|
||||||
|
|
||||||
- Requesting player
|
These trigger multi-command `fill/setblock/give` sequences near the player and are optimized for Paper performance.
|
||||||
- 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
|
## Configuration
|
||||||
|
|
||||||
Main file: `/etc/mc_aigod.json`
|
Main file: `/etc/mc_aigod_paper.json`
|
||||||
|
|
||||||
| Key | Type | Description |
|
Important keys:
|
||||||
|---|---|---|
|
|
||||||
| `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
|
- `log_path`: `/opt/paper-ai-25567/logs/latest.log`
|
||||||
|
- `rcon_port`: `25577`
|
||||||
```json
|
- `sudo_max_commands`: default `12` (higher for build bursts)
|
||||||
{
|
- `interventions_per_day`: default `24`
|
||||||
"server_name": "shrink-world",
|
- `first_login_benevolence_max_commands`: default `12`
|
||||||
"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
|
## Backwards Compatibility
|
||||||
|
|
||||||
```bash
|
This fork is derived from the original architecture and remains broadly compatible:
|
||||||
# Dependencies
|
|
||||||
apt install -y python3-requests
|
|
||||||
|
|
||||||
# Install script + config + service
|
- Same trigger style (`pray`, `bible`, `sudo`)
|
||||||
cp mc_aigod.py /usr/local/bin/mc_aigod.py
|
- Same command validation and syntax repair pipeline
|
||||||
chmod +x /usr/local/bin/mc_aigod.py
|
- Same memory model concepts
|
||||||
cp mc_aigod_shrink.json /etc/mc_aigod.json
|
- Same two-call LLM split
|
||||||
cp mc-aigod.service /etc/systemd/system/mc-aigod.service
|
|
||||||
|
|
||||||
# Start service
|
You can run the vanilla branch and this Paper fork side-by-side because they use separate files, ports, and services.
|
||||||
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
|
## Deploy (already applied in this environment)
|
||||||
|
|
||||||
- No response on trigger?
|
1. Install Paper server in `/opt/paper-ai-25567`
|
||||||
- Ensure you typed `pray` / `bible` / `sudo` in chat **without slash**
|
2. Install plugins in `/opt/paper-ai-25567/plugins`
|
||||||
- Sudo does nothing?
|
3. Install `mc-paper-ai.service`
|
||||||
- Confirm username matches `sudo_user`
|
4. Install `mc_aigod_paper.py` to `/usr/local/bin/mc_aigod_paper.py`
|
||||||
- Check `sudo_enabled`
|
5. Install `/etc/mc_aigod_paper.json`
|
||||||
- Unknown item errors?
|
6. Install `mc-aigod-paper.service`
|
||||||
- See `/var/log/mc_aigod.log` for translated command + server error
|
7. Enable + start both services
|
||||||
- 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
|
## Notes
|
||||||
|
|
||||||
- `mc_aigod.py` — main script
|
- If a model generates malformed `give`/`effect` syntax, auto-repair handlers normalize common forms.
|
||||||
- `mc_aigod_shrink.json` — real config template
|
- If a slang item appears (`wood`, `doors`, etc.), alias normalization attempts valid item IDs.
|
||||||
- `mc-aigod.service` — systemd unit
|
- Build templates are deterministic first, LLM second, to reduce surprises for complex build tasks.
|
||||||
- `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`
|
|
||||||
|
|||||||
@@ -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