Minecraft AI God — Paper Advanced Fork

This fork targets a dedicated Paper server on port 25567 and adds advanced automation not present in the vanilla-first branch.

What is new in this fork

• 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

---

Runtime Topology

• 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

LangGraph-style Gateway Sidecar (implemented)

• Service: mc-langgraph-gateway.service
• API: http://127.0.0.1:8091
• Script: /usr/local/bin/langgraph_gateway.py
• Config: /etc/mc_langgraph_gateway.json

mc_aigod_paper.py can route modes through session APIs:

• god (prayer)
• sudo (translator)
• god_system (intervention / first-login)

Enable via config:

"use_langgraph_gateway": true,
"langgraph_gateway_url": "http://127.0.0.1:8091"

The runtime still enforces whitelist/repair/caps/auth after gateway output.

Gateway hardening currently included:

• Session reuse by player+mode when still active (less duplicate session churn)
• SQLite-backed session persistence across gateway restarts
• Command sanitization at gateway return time (strips leading /, rejects prose/non-command lines)
• Mode-specific command family filtering and command dedupe/cap

---

Services

• mc-paper-ai.service — Paper server process
• mc-aigod-paper.service — AI orchestration process

Useful commands:

systemctl status mc-paper-ai.service
systemctl status mc-aigod-paper.service
journalctl -fu mc-paper-ai.service
journalctl -fu mc-aigod-paper.service

---

Chat Triggers (no slash)

• pray <message> — God prayer flow
• bible — help text
• sudo <request> — translator mode (authorized user only)

New: deterministic build mode via sudo

If a sudo request starts with build, make, or create, the fork uses deterministic templates before LLM translation.

Examples:

• sudo build house
• sudo build tower
• sudo create church
• sudo build wall

Template manager commands:

• sudo template search <query>
• sudo template download <https-url|#n|n> [name]
• sudo template install <https-url> [name]
• sudo template pick <n> [name] (download from last search result index)
• sudo template sync (pull from configured sync sources/manifest)
• sudo template build <filename|name> (or no arg = last downloaded template)
• sudo template list
• sudo template delete <filename>
• sudo template hosts

Notes:

• Template download now requires direct file URLs only (.schem/.schematic/.nbt/.zip)
• Template search is direct-link only (no page scraping)
• Recommended workflow is template sync + template build

Info lookup mode via sudo:

• sudo lookup <question>
• sudo wiki <question>
• sudo search <question>

Lookup mode is information-only (wiki/web retrieval + optional justification), and does not execute game commands.

These trigger multi-command fill/setblock/give sequences near the player and are optimized for Paper performance.

---

Configuration

Main file: /etc/mc_aigod_paper.json

Important keys:

• 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

---

Backwards Compatibility

This fork is derived from the original architecture and remains broadly compatible:

• Same trigger style (pray, bible, sudo)
• Same command validation and syntax repair pipeline
• Same memory model concepts
• Same two-call LLM split

You can run the vanilla branch and this Paper fork side-by-side because they use separate files, ports, and services.

---

Deploy (already applied in this environment)

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

---

Notes

• 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.