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
• Localized knowledge retrieval for tool mode:
  • local corpus under /var/lib/mc-langgraph-gateway/knowledge
  • indexed search + document snippet retrieval (local.search -> local.read)
  • optional bootstrap download of Minecraft/Paper/WorldEdit docs at startup

---

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.

For normal sudo translation, the gateway now also runs localized retrieval before command generation, so the model can ground command synthesis in local indexed docs rather than relying only on prompt memory.

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
• bug_log_path: default /var/log/mc_aigod_paper_bug.log
• bug_log_service_lines: recent AI action lines attached to each bug entry
• tp_safety_enabled: auto-wrap risky vertical teleports with fall protection
• tp_safety_vertical_delta: relative Y threshold for teleport safety wrapper

---

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.