Solbridge Readme

SolBridge is a Forge 1.12.2 prototype mod that adds Sol, a dark floating orb familiar. Sol has local entity behavior, follows or stays near its…

Raw Source

Executive Summary

SolBridge is a Forge 1.12.2 prototype mod that adds Sol, a dark floating orb familiar. Sol has local entity behavior, follows or stays near its owner, accepts /sol commands and right-click interaction, sends structured world context to a local HTTP daemon, and executes only validated JSON actions. The LLM stays outside Minecraft.

SolBridge

SolBridge is a Forge 1.12.2 prototype mod that adds Sol, a dark floating orb familiar. Sol has local entity behavior, follows or stays near its owner, accepts /sol commands and right-click interaction, sends structured world context to a local HTTP daemon, and executes only validated JSON actions.

The LLM stays outside Minecraft. The daemon can talk to a local OpenAI-compatible llama.cpp server, retrieve lore through the Sol knowledge API, keep persistent conversation memory, and return only safe structured action JSON.

Requirements

Build

bash
cd /home/david/minecraft-neoriris-upgrade-lab-1.12.2/solbridge
JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 ./gradlew --no-daemon clean build

The jar is written to:

text
build/libs/solbridge-0.1.6.jar

Run A Dev Server

bash
cd /home/david/minecraft-neoriris-upgrade-lab-1.12.2/solbridge
JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 ./gradlew --no-daemon runServer

On first load, SolBridge creates:

text
config/solbridge/solbridge.cfg
config/solbridge/allowed_blocks.json
config/solbridge/player_permissions.json
config/solbridge/blueprints/

Commands

text
/sol help
/sol summon
/sol dismiss
/sol follow
/sol stay
/sol status
/sol say <message>
/sol build <blueprintName>
/sol tempbuild <blueprintName> [seconds]
/sol undo
/sol reload

Use /sol summon to spawn Sol near you. You can also craft a Sol Entity item and right-click it to spawn or move your orb.

Crafting recipe:

text
G C G
E M E
G N G

G is glowstone dust, C is a clock, E is eye of ender, M is the PortalGun miniature black hole, and N is a nether star.

/sol build lamp_post builds a small approved structure near the player block by block. /sol tempbuild black_marker 10 builds an approved structure, waits 10 seconds, then withdraws only the blocks Sol still owns. /sol say build a marker here sends player/world/orb context to the daemon and executes the returned action plan if it validates.

Daemon Stub

bash
cd /home/david/minecraft-neoriris-upgrade-lab-1.12.2/solbridge
python3 sol-daemon/server.py

The daemon exposes:

text
POST http://127.0.0.1:3737/minecraft/event

By default it calls the local llama.cpp OpenAI-compatible endpoint at http://127.0.0.1:18083/v1/chat/completions, retrieves lore context from http://127.0.0.1:8892/query, requires the knowledge API to serve the openai embedding backend, and stores memory in ~/.local/share/solbridge/daemon_memory.json.

Useful daemon environment variables:

text
SOL_LLM_URL=http://127.0.0.1:18083/v1/chat/completions
SOL_REQUIRED_KNOWLEDGE_BACKEND=openai
SOL_KNOWLEDGE_URL=http://127.0.0.1:8892/query
SOL_MEMORY_PATH=~/.local/share/solbridge/daemon_memory.json

If the LLM or knowledge API fails, the daemon falls back to deterministic safe speech/actions. It never exposes raw command execution to Minecraft.

Conversation And Behavior

Sol is conversational by default through /sol say, right-click, idle observation events, and combat-retaliation events. The context sent to the daemon includes player identity, Sol mode/position, biome, time, held item, looked-at block, nearby entities, and a compact counted sample of nearby blocks.

Sneak-right-click Sol to open its 18-slot inventory. Right-click Sol with a book, written book, writable book, or enchanted book to store it directly. Sol also collects nearby dropped books automatically; written pages are trimmed and sent to the daemon as a book_ingested prompt. The daemon treats readable book text like player speech, responds in chat, and stores the text as persistent book memory for later conversation context. Book prompts are restricted to speech actions rather than builds or commands.

When llmIdleObservations=true, Sol regularly asks the daemon to describe the immediate scene ominously using detected entities and blocks. Idle narration uses safe speech actions only, and the daemon rejects repeated recent lines so Sol varies its phrasing.

When retaliationEnabled=true, Sol detects attacks against its owner, flings the attacker upward with bounded force, marks the fall damage so it cannot reduce the target below retaliationMinHealth, heals the owner by retaliationOwnerHeal, caps the triggering hit so it cannot reduce the owner below retaliationOwnerMinHealth, emits smoke/portal/redstone/ward particles, and asks the daemon for a concise retaliation line.

Blueprints

Blueprints live in:

text
config/solbridge/blueprints/

Bundled examples:

text
lamp_post.json
black_marker.json
small_terminal.json

Blueprints use a small JSON format with declared size, a character palette, and Y layers from bottom to top. Palette blocks must appear in allowed_blocks.json, must be real Forge block registry names, and must fit configured size and block-count limits.

Safety Model

SolBridge does not execute raw Minecraft commands, shell commands, or arbitrary daemon text. The daemon can only request structured actions such as say, set_mode, play_sound, spawn_particle, build_blueprint, and temporary_build_blueprint.

Building is rejected unless the player has permission, the blueprint exists locally, every palette block is allowed, the structure is under configured limits, and the entire target area is safe. By default SolBridge only replaces air or replaceable blocks and refuses tile entities, storage, signs, command blocks, bedrock, TNT, fluids, fire, redstone components, doors, and similar intentional blocks. Temporary builds record the previous and placed state for every block; deconstruction only restores blocks that still match what Sol placed, so player edits are skipped rather than overwritten.

Retaliation is native bounded behavior, not a daemon action. The daemon can supply speech, but cannot request arbitrary damage or commands.

Ambient Temporary Builds

When ambientTemporaryBuilds=true, an owned Sol in follow/stay mode may occasionally materialize one of ambientTemporaryBlueprints, then withdraw it after temporaryBuildLifetimeTicks. This uses the same safe blueprint and area validation as /sol build. Defaults are conservative: 10 minutes plus up to 5 minutes jitter between attempts, 3 minutes lifetime, and no chat notification unless ambientTemporaryBuildNotify=true.

Current Limitations

Planned Next Steps