minecraft-ai-god-paper-fork/README.md

# 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:

```json
"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:

```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
```

---

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