Architecture

Operator Cheat Sheet

🎯 Operator Cheat Sheet#

Single-Agent View Flow#

  1. Pick an agent in the sidebar (socket agents list)
  2. Center: Prismarine iframe — global feed or that agent’s POV port
  3. Right: AgentDetail — inventory, modes, memory, nearby entities, self-prompter

Viewer / POV Feeds#

Concept Behavior
Global viewer Default world camera (port VITE_GLOBAL_VIEWER_PORT, default 55669)
Per-agent feed Extra Prismarine on agent.viewerPort (direct hostname:port)
Feed buttons Switch iframe src; global port may use proxy path

URL Rules (viewer-url.js)#

  • VITE_GLOBAL_VIEWER_URL — if set, forces that URL
  • Else if VITE_USE_VIEWER_PROXY ≠ false — uses VITE_VIEWER_PROXY_PATH (default /viewer/) → same origin (avoids mixed content on HTTPS)
  • Per-agent ports always use http(s)://<current-host>:<port>

Blank iframe? Dashboard HTTPS + per-agent HTTP = mixed content blocked. Use proxy for global feed.

Right Panel — AgentDetail#

Tab Content
🧰 Inv Inventory items (name, count); “N / 36 slots used”
🎚 Modes !setMode <name> <true|false> toggles
🧠 Memory Summarized memory blob + auto-summary hint
👁 Nearby Players, blocks, entities

Self-prompter bar (always visible): state (STOPPED/ACTIVE/PAUSED), goal text, play → !goal <text>, stop → !goal (clear).

In-Game Commands#

Core Commands#

Command Action
!stop Halt all actions
!come Pathfind to your location
!inventory List carried items
!goal {description} Set high-level natural language goal
!stats Show health/hunger/position
!nearbyBlocks List nearby blocks
!entities List nearby entities
!craftable Show craftable recipes
!time / !weather Show time/weather

Action Commands#

!goToPlayer !followPlayer !goToCoordinates !goToPlace !attack !attackPlayer !collectBlocks !craftRecipe !smeltItem !placeHere !equip !discard !eat !newAction !setMode !task

Agent Personalities#

Name Model Personality Strength
Groqqo Llama 3.3 70B Explorer Mapping, biome discovery
Groqqi Llama 3.1 8B Builder Repetitive tasks, gathering
Gemmiii Gemini 2.0 Pro Diplomat Negotiation, strategy
Gemmiij Gemini 2.0 Flash Warrior Combat, reflex actions

Prompt Engineering Tips#

  1. Be Specific: “Mine iron” ≪ “Find a cave below Y=50 and mine iron ore”
  2. Break it Down: Complex tasks work best when chained
  3. Context: Remind the bot of its tools (“Use your stone pickaxe”)

Skins (Profile JSON)#

In bots/profiles/agents/*.json:

"skin": { "model": "slim", "path": "https://textures.minecraft.net/texture/..." }

On spawn the bot runs /skin set URL … / /skin clear — requires Fabric Tailor on the server.

Move World Spawn#

Stop Paper/Spigot first, then from repo root:

node scripts/offset_world_spawn.mjs --east 200 --apply

Other axes/flags: run with --help. Backs up level.dat before apply.

OpenRouter Quick Config#

  • Key: OPENROUTER_API_KEY in bots/keys.json
  • One base URL for all profiles: env OPENROUTER_BASE_URL
  • Model entries: "model": { "api": "openrouter", "model": "vendor/model-id" }
  • Implementation: bots/src/models/openrouter.js

Automation Reminders#

Goal How
Which bots run settings.js profiles or MOINCRAFT_PROFILES env
Health check ./verify_stack.sh (ports + HTTP)
Relay contract cd bots && npm run relay:contract
PM2 ecosystem.config.cjs at repo root

Emergency Procedures#

Bot stuck in loop?

  1. !stop in chat
  2. If unresponsive: pkill -f "node main.js"

Server crashed?

  1. ./stop_all.sh
  2. ./launch_all.sh

Out of token budget?

  1. Switch profiles to local Ollama models in settings.js

Improvement Matrix#

ID Idea Why
A1 OpenRouter embeddings One key for chat + RAG
A2 SSE streaming Faster perceived replies
B1 Feed health API Disable dead viewer buttons
B2 Viewer proxy Same-origin for all feeds
C1 Hotbar UI True Minecraft-shaped HUD
C2 Cost telemetry Budget guardrails

Code Pointers#

  • bots/dashboard/src/lib/components/Viewer.svelte — iframe, feed switch
  • bots/dashboard/src/lib/components/AgentDetail.svelte — tabs, inventory, self-prompter
  • bots/dashboard/src/lib/viewer-url.js — proxy vs direct URL logic
  • bots/dashboard/src/lib/stores/socket.svelte.js — selectedAgent, agents, metrics