# 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

- Minecraft `1.12.2`
- Forge `1.12.2-14.23.5.2860`
- Java 8 for builds and runtime
- No Bukkit, Sponge, Mohist, Magma, or Custom NPCs required

## 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.8.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.

The `Sol Build Site Marker` is a craftable placement item. Place it where the structure should begin, then use the prompt screen to pick a known schematic preset or edit the build description. Submitting the prompt sends a `build_site_marker` event to the daemon with the marker position; approved structures build from that marker instead of the default nearby-player origin.

Build site marker recipe:

```text
P S P
R G R
P S P
```

`P` is paper, `S` is stone brick, `R` is redstone, and `G` is glowstone dust.

## 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.

The client renderer shows Sol as a dark translucent cube-orb with a red inner core, particles, and a faint animated computer-vision overlay projected onto the outer shell. The overlay is visual-only; it does not grant the daemon new authority or bypass action validation.

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. If a book or chat prompt clearly requests a structure, the daemon may request a permanent approved blueprint build; the native mod still validates permission, blueprint name, size, palette, and target area before placing anything.

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
signal_spire.json
watcher_ring.json
archive_node.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

- Rendering is a simple pulsing dark cube-orb rather than a polished sphere model.
- Blueprint support is JSON-only; legacy `.schematic` files are not supported.
- Build styles currently support `bottom_up` and `instant`; `slow_spiral` is accepted as bottom-up behavior.
- Undo only restores the last completed permanent build and skips blocks that no longer match Sol's placed state.
- The daemon uses a local LLM and persistent JSON memory, but does not yet summarize memory or expose moderation/approval UI.
- Idle observation and combat speech depend on the local daemon and local model being reachable.

## Planned Next Steps

- Better orb model/texture and client-side animation polish
- Preview outlines before building
- Per-player daemon routing and richer memory context
- Optional approved schematic import
- More build styles and approval workflows