Architecture

Unutilized Power

🚀 Unutilized Potential — Power Table#

From the moincraft stack deep-dive. Features available but not yet wired up.

Missing OpenRouter Features#

# Feature What It Is Current State
🔴 OpenRouter Embeddings Native embedding API (Nov 2025) throw Error('not supported') — fixable in 5 lines
🔴 Streaming (SSE) Token streaming → faster UX Not implemented; all responses blocking
🔴 Structured Outputs JSON schema enforcement → stop hallucinated commands Not used
🟡 Provider Routing Nitro/Floor shortcuts, fallback chains Hardcoded no routing config
🟡 Response Healing Plugin Auto-fix malformed JSON Not enabled
🟡 Web Search Plugin Real-time search in model context Not enabled
🟡 Vision (allow_vision) Bot screenshot → multimodal analysis false by default; viewer already has the render
🟡 MemoryBank Vector DB for long-term episodic memory Stub only (333 bytes)
🟡 Auto Router openrouter/auto picks optimal model Not tried
🟡 Skill Learning Write new skills to skills.js from successful !newAction Not implemented
🟢 Assistant Prefill Steer model output format Not used in prompts
🟢 god_mode base profile Unlimited power prompts Exists but not in default rotation
🟢 speak TTS Text-to-speech output Exists, disabled
🟢 Task system Structured task execution + evaluation Exists but not used in swarm
🟢 CoopLevel 4/5 Emergent + Collective agents Framework exists, untested at scale

Genius Improvements Table#

UID Improvement What Changes Why It’s Genius
A1 Fix OpenRouter Embeddings Replace throw with embeddings.create() Semantic RAG via single API key — no separate embedding provider
A2 Streaming Responses stream: true + SSE to dashboard Real-time token display; dramatically better UX
A3 Structured JSON Commands response_format: {type:'json_schema'} Zero hallucinated command syntax; eliminates retry loops
B1 Provider Routing Config provider field in profile JSON Per-agent cost/speed tuning: groq for speed, nitro for quality
B2 Persistent Vector Memory Replace MemoryBank stub with SQLite + cosine search Bots remember facts across restarts; experience accumulation
B3 Vision from Viewer Capture Three.js canvas → base64 → promptVision() Reuse existing viewer render; enable allow_vision cheaply
B4 Web Search Plugin plugins: [{id:'web'}] in OpenRouter requests Bots can check Minecraft wiki, item recipes, mods
C1 Per-Bot Cost Tracking Read usage from OpenRouter responses Real-time cost visibility; budget alerts
C2 Skill Auto-Learning On successful !newAction, persist ESLint-passed code to skill library Bots grow smarter over time
C3 Auto Router Fallback openrouter/auto when named model fails Zero-config model fallback
C4 Blueprint Import Parse .nbt / schematic into NPC construction JSON Build any structure from schematic
D1 ZDR Privacy Mode data_collection: 'deny' in all profiles All LLM calls marked no-train, no-log
D2 Dynamic Personality Profiles Swap base_profile at runtime via MindServer Change bot personality without restart
D3 Viewer Canvas Snapshot API REST endpoint for PNG screenshots Headless 3D world screenshots for monitoring, vision, logging

Best Practices (from moincraft-stack-cheatsheet)#

LLM Prompting#

  • Keep max_messages low (15) to avoid context explosion costs
  • Memory summarization in Chinese → better compression ratio
  • Use cooldown in profile to rate-limit rapid self-prompt loops
  • Separate code_model from chat_model: cheap fast model for chat, smarter for code
  • bot_responder prompt prevents cascading bot-to-bot infinite chat loops

Multi-Agent Swarm#

  • AGENT_STARTUP_DELAY_MS=1500 — prevents simultaneous MC login flood
  • Profile names must be unique (they become bot usernames)
  • only_chat_with: [] → empty = respond to everyone; restrict to reduce LLM calls
  • Cooperation level 3+ enables proper task negotiation

OpenRouter Cost Control# 

// Cap tokens for cheap chat models
max_tokens: 512,
// Cheapest provider
model: 'google/gemini-2.5-flash:floor'
// Monitor usage: GET https://openrouter.ai/api/v1/auth/key

Viewer Stability#

  • Never run viewer + mindcraft bots as same username
  • VIEWER_VIEW_DISTANCE=4 on low-resource machines
  • If EADDRINUSE on 55669 → only ONE viewer process should be running

Paper Server#

  • Pre-generate spawn chunks: use WorldBorder to limit exploration
  • view-distance=6 in server.properties (matches bot view distance)
  • paper.yml: anti-xray: false for bots (reduces CPU)