Seth/minecraft-ai-god
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
0556d0ca16ad02900100f8830ae6d3b8eaab3de0
minecraft-ai-god/README.md
T
Claude Code 4771d6c03e Refine vanilla AI prompts and sudo reliability
2026-03-17 19:53:25 -04:00

8.2 KiB
Raw Blame History

Minecraft AI God

A Python log-watcher + RCON automation script that gives a vanilla Minecraft server an in-game AI "God".

Players type chat triggers (pray, bible, sudo) and the agent:

  • reads context from server state + player state + recent logs,
  • calls local LLM(s),
  • executes validated commands via RCON,
  • and speaks in public chat.

No Bukkit/Paper plugin required.

What Is Included

  • God prayer pipeline (pray <message>)
  • Two-call LLM architecture
    • command model decides commands (JSON)
    • message model writes divine speech (text)
  • Divine intervention timer (random unprompted acts)
  • First-login benevolence (one-time blessing per player)
  • Bundled sudo translator agent (sudo <request>) with whitelist + user lock
  • Bug logging trigger (bug_log <optional description>) with recent context capture
  • Persistent prayer memory
  • Rolling server event memory (up to 3 hours / 200 events)
  • Debug command preview toggle

Trigger Commands (Chat, No Slash)

Vanilla 1.21 rejects unknown slash commands client-side. Use plain chat messages:

  • pray <message> — prayer flow (God judgment + optional commands + speech)
  • bible — private usage/help text
  • sudo <request> — command translator mode (authorized user only)
  • bug_log <optional description> — append bug report with recent server logs/events

Examples:

  • pray Lord, I need food and shelter
  • bible
  • sudo give me 500 wood
  • bug_log creeper exploded through wall near spawn

Architecture

chat line -> latest.log tail -> trigger parser

pray path:
  ack player -> gather context -> commands call -> message call -> execute commands -> broadcast message

sudo path:
  auth check -> translate request to commands -> validate/repair -> execute -> private preview

join path:
  login notice -> one-time first-login benevolence event

timer path:
  poisson interval -> if players online -> intervention commands+message

Two-call design (prayer/intervention)

  1. Commands call (command_model)
    • strict JSON output
    • low temp for stable command generation
  2. Message call (model)
    • prose only
    • no token competition with command JSON

This avoids the common failure mode where long speech truncates commands.

Context Passed to LLM

Prayer / Intervention context

  • Online players
  • Player positions + distance from spawn
  • Time of day, weather, world border
  • Scoreboard-derived state where available (deaths, shrink flags)
  • Recent server events (chat/death/join/leave), capped by both:
    • last 3 hours
    • last 200 events
  • Prayer memory (last 10 exchanges)

Praying player state

  • Inventory summary (with rarity annotations)
  • Health
  • Food level
  • XP level
  • Death count

Sudo context

  • Requesting player
  • Online players
  • Current natural-language sudo request
  • Last 10 sudo actions:
    • request text
    • translated commands
    • executed commands

This helps sudo correct previous bad translations.

Safety and Validation

  • Command-family whitelist enforced (give, effect, xp, tp, time, weather, execute, kill, summon, tellraw, worldborder)
  • Auto-repair for common malformed outputs:
    • transposed give args (give player 64 item)
    • missing minecraft: namespace
    • shorthand aliases (wood -> oak_log, door -> oak_door, bed -> white_bed, etc.)
    • malformed effect form corrected to effect give ...
  • Max commands per response cap
  • Per-player prayer cooldown
  • First-login benevolence can include many commands but is benevolent by prompt rules
  • If kill commands appear in first-login mode, at most one player kill is allowed

Configuration

Main file: /etc/mc_aigod.json

Key Type Description
server_name string Friendly server name for prompts
log_path string Absolute path to latest.log
rcon_host string RCON host
rcon_port int RCON port
rcon_password string RCON password
ollama_url string Ollama API base URL
model string Message model (creative prose)
command_model string Command model (JSON/command generation)
temperature float Message generation temperature
max_tokens int Message call max tokens
cooldown_seconds int Prayer cooldown per player
max_commands_per_response int Max commands in prayer/intervention response
interventions_per_day float Avg random acts/day (Poisson)
god_chat_prefix string Prefix for God speech
debug_commands bool Show [~] command preview in chat
god_lore string Optional lore block injected into message system prompt
memory_path string Prayer memory JSON path
sudo_enabled bool Enable/disable sudo agent
sudo_user string Authorized sudo username
sudo_max_commands int Max commands translated from one sudo request
first_login_benevolence_enabled bool Enable one-time first-login blessing
first_login_benevolence_max_commands int Max commands in first-login blessing
first_login_path string Persistent file storing already-blessed players
bug_log_path string File path used for bug_log entries
bug_log_event_lines int Number of in-memory interesting events to attach
bug_log_raw_lines int Number of raw tail log lines to attach
bug_log_service_lines int Number of recent AI action lines from service log
tp_safety_enabled bool Auto-protect risky vertical teleports with safety effects
tp_safety_vertical_delta number Relative ~ ~N ~ threshold that triggers safety wrapper
tp_safety_absolute_y number Absolute Y threshold that triggers safety wrapper

Current shrink-world example

{
  "server_name": "shrink-world",
  "log_path": "/opt/mcsmanager/daemon/data/InstanceData/shrinkborder1234567890abcdef12345/logs/latest.log",
  "rcon_host": "127.0.0.1",
  "rcon_port": 25576,
  "rcon_password": "REDACTED_RCON",
  "ollama_url": "http://192.168.0.141:11434",
  "model": "gemma3:12b",
  "command_model": "qwen3-coder:30b",
  "temperature": 0.85,
  "max_tokens": 600,
  "cooldown_seconds": 20,
  "max_commands_per_response": 6,
  "interventions_per_day": 48,
  "god_chat_prefix": "[§6§lGOD§r]",
  "debug_commands": true,
  "sudo_enabled": true,
  "sudo_user": "slingshooter08",
  "sudo_max_commands": 3,
  "first_login_benevolence_enabled": true,
  "first_login_benevolence_max_commands": 10,
  "first_login_path": "/opt/mcsmanager/daemon/data/InstanceData/shrinkborder1234567890abcdef12345/aigod_first_login_seen.json",
  "god_lore": "This is the shrink-world server...",
  "memory_path": "/opt/mcsmanager/daemon/data/InstanceData/shrinkborder1234567890abcdef12345/aigod_memory.json"
}

Deployment

# Dependencies
apt install -y python3-requests

# Install script + config + service
cp mc_aigod.py /usr/local/bin/mc_aigod.py
chmod +x /usr/local/bin/mc_aigod.py
cp mc_aigod_shrink.json /etc/mc_aigod.json
cp mc-aigod.service /etc/systemd/system/mc-aigod.service

# Start service
systemctl daemon-reload
systemctl enable --now mc-aigod.service

# Logs
journalctl -fu mc-aigod.service
tail -f /var/log/mc_aigod.log
tail -f /var/log/mc_aigod_responses.log

Debugging Checklist

  • No response on trigger?
    • Ensure you typed pray / bible / sudo in chat without slash
  • Sudo does nothing?
    • Confirm username matches sudo_user
    • Check sudo_enabled
  • Unknown item errors?
    • See /var/log/mc_aigod.log for translated command + server error
    • Alias/repair may still need extension for new slang terms
  • Long God speech issues?
    • Two-call design is active; commands are decided separately from message text
  • Random acts too frequent?
    • Lower interventions_per_day

File Map

  • mc_aigod.py — main script
  • mc_aigod_shrink.json — real config template
  • mc-aigod.service — systemd unit
  • Minecraft_Ai_God.md — deeper design/context notes
  • CONTEXT.md / COMMANDS.md — local infrastructure references

Deployed Reference (Sethpc)

  • Host: CT 644 (MCSManager)
  • Server: shrink-world (RCON 25576)
  • Ollama: http://192.168.0.141:11434
  • Models:
    • message: gemma3:12b
    • commands: qwen3-coder:30b
  • Service: mc-aigod.service
Reference in New Issue View Git Blame Copy Permalink