Minecraft Companion Mod

Problem

A companion should share the player's world and do visible, useful work, with real inventory and consequences, rather than only describing actions in chat.

A project built for fun

This started on October 21 with a simple wish: have a companion beside me in Minecraft who could understand a request and actually help. It needed a player-like body, my supplied skin, its own inventory, and two ways to play: survival with ordinary consequences, or invincible with flight and creative-style supplies.

The important detail was coexistence. I wanted to keep playing my character in my single-player world while a separate companion worked nearby. There is no second account to manage and no external server requirement. Minecraft’s integrated server owns the gameplay.

Turning the idea into a working loop

Working with Codex, the build separated the model’s decisions from the game’s authority. The loop became observe → choose a tool → validate → execute → observe again. The model receives bounded information about nearby blocks, entities, inventory, and the current task. Local game logic decides whether an action can actually happen.

That boundary makes the companion useful even when a model is slow. Following, immediate defense, and hazard warnings run locally. Mining, crafting, placement, and delivery use actual materials and world state. A resource job finishes when its inventory or committed delivery satisfies the goal.

The moment chat stopped being enough

During the first session, I reported that I saw action messages but no visible movement. The session ended with that concern still open, even though earlier checks had passed.

The next session returned to the question at normal gameplay speed. The recorded check showed the companion walking 11.1 blocks, animating its legs and pickaxe swings, and mining with tool wear. That was a better definition of success: an entity I could see doing the work beside me.

The supplied skin was bundled, and the original 0.1.0 package brought the companion into a usable release. Its recorded checks included both provider adapters, gameplay scenarios, and a 30-minute mixed gameplay soak in a disposable world.

Making setup belong inside Minecraft

The next round of feedback came from using the mod itself. API configuration needed to be understandable without editing files, and appearance settings needed a proper home.

Version 0.1.1 added Options → AI Companion from the title screen and in-world Options, plus a pause-menu entry. Connection, Appearance, and Limits tabs bring together the provider, endpoint, model, masked API key, API test, skin import, and standard or slim arms. The same companion remains in the world while the human player keeps control.

From one action to a goal

The next request was more ambitious: let the companion plan several steps, travel when allowed, place blocks to reach something higher, and dig a safe way down.

Version 0.2.0 added ordered plans of up to 16 steps. Each step still goes through the same local action checks. A failed step stops the remaining work and supplies a real result for replanning. Saved checkpoints retain completed deliveries so resuming does not mean blindly repeating effects.

Terrain access uses supported blocks and descending stairs, with checks for reach, supplies, protected areas, and hazards. Survival mode retains gravity and consumes building materials. Ordinary following and defense do not reshape terrain.

Independent trips now default to 1,000,000 blocks, adjustable in Limits; 0 removes the distance cap within the world border. The owner must enable Allow trip. Time, action, and request budgets still apply, and the companion loads a small moving region rather than the entire distant route.

What the release evidence supports

The 0.2.0 validation record reports 19 unit/provider checks, 34 gameplay scenarios, client checks, and a live Gemini run that gathered supplied reachable logs and completed a five-step wooden-pickaxe plan. A separate paced recording shows real construction, ascent, mining, and collection.

Travel testing includes an actual 1,024-block trip into initially unloaded chunks. The much larger range is a configurable permission boundary, not a claim that a million-block expedition was completed. The earlier soak and compatible-provider checks belong to the original release; they were not rerun as new 0.2.0 evidence.

Released, with room to grow

This is a released single-player mod, with more player mechanics and broader terrain recovery still ahead. Model quality, tool support, and latency affect planning. It does not promise full vanilla-player parity or support for public servers.

Open the project on GitHub, or read the general blog about building a companion worth playing alongside.