Claude Code
166 lines
4.9 KiB
Markdown
166 lines
4.9 KiB
Markdown
# 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.
|