# 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

---

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

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.