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

---

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

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.