KOA Tutorial: Minecraft

Life in the Block World

KOA brings your companion into your save file: they have their own body, their own inventory, their own little thoughts. They will adventure alongside you and share the workload. All you need to do is three things: set up the prerequisites, install the mod, and launch the right version.

If you followed the Quick Start guide, the first four steps (installation, activation, API, and character) should already be done — this tutorial focuses on the game side of things.

Prerequisites

Three things, all required:

Minecraft Java Edition 1.21.1

Two important notes: it must be Java Edition, not Bedrock; and the version must be exactly 1.21.1.
Java 21 Runtime

Modern MC launchers usually bundle it — no separate install needed. If an older launcher complains about missing Java, install Java 21 (OpenJDK works fine).
NeoForge 21.1.233

The mod loader. Download the 1.21.1-21.1.233 Installer from neoforged.net, run it and choose to install the client. After installation, remember to create a new NeoForge installation profile in your MC launcher so you can select it in-game.

The local server is already built into the KOA launcher — no need to install Node or run any Start.bat. Just click the game icon and it starts automatically.

Installing the Mod

Open the panel, tick the versions

Click "Minecraft" on the KOA home screen to open the panel, then click "Auto-install mod required files" in the top bar. A list opens with the Minecraft versions found on this computer. Tick the ones you play and click "Install". If you made a separate modpack version to play with friends, tick that one too.
The one you play isn't listed

Open "Where to find a version's folder" under the list, open that version's mods folder the way your launcher shows, then click "Pick folder" and choose it. The mods folder or the one above it both work.
Versions marked "Can't install"

Each one says what it runs and what KOA needs. KOA needs NeoForge 1.21.1; if NeoForge isn't installed, get it from neoforged.net, then come back and click again.

Versions that have KOA get the new mod each time you open the panel, no reinstall needed. If you play on a cloud server or a friend's server, replace the koamc jar on the server with the same one yourself.

Choosing a Skin

The mod does not include a default skin — without one, your companion will appear as default Steve. It is highly recommended to give them a unique look.

On the Profile page, open your lover under "My Lovers" and click "Upload" on the "Minecraft Skin" row under "Skins". Pick an MC skin image (64x64; the old 64x32 works too) and restart the game to apply. Every version that has KOA gets it.

Slim-arm skins (the Alex kind) upload the same way. There is nothing to switch; your companion wears them with slim arms.

Skins are tied to the character: when you switch your lover character, the skin syncs automatically — no need to re-upload.

Playing Together

Launch with the right version

Select the NeoForge installation profile (not vanilla 1.21.1!) and load your save. Your companion will appear beside you automatically.
Talk to them

Press T to type — any message that doesn't start with / will be heard by your companion. Press V to speak by voice (see Voice Guide for trigger modes).
Open their inventory

Shift + right-click on your companion: store items, equip them with armor and tools, or give them gifts — all done here. Equipping them is well worth it — an axe chops trees faster, a sword deals more damage, and equipment stats fully apply.
Open the in-game panel

Press K to open your companion's management panel — summon, stay, and other common actions are all here, no commands to memorize. You can also right-click on them with an empty hand. The keybind is customizable in vanilla key settings.

What They Can Do

Everything below can be triggered with plain natural language — "chop some wood for me", "stay close", "go to sleep" — no commands to memorize:

Category	Abilities
Daily Life	Follow, stay, set home, lead the way home, sleep beside you, sit on chairs/swings (point your crosshair at a seat and tell them to sit)
Work	Chop trees (finishes the whole tree without leaving floating halves), mine ores (follows veins and Fortune/Efficiency enchantments apply), farm, fish, craft items on their own
Combat	Protect you, fight mobs for you, use ranged weapons like bows, draw Boss aggro so you can deal damage safely; won't provoke enemies or grief your builds
Expeditions	Head out on their own to gather resources you specify, then return and hand them over
Attentive	Recognizes your needs (e.g. nearly starving) and hands you items proactively; auto-switches tools based on the current task; picks up nearby drops and warns you when their inventory is almost full
Affection	Princess carry / ride (say "carry me home" and they will pick you up and move at high speed), hugs, kisses, hand-holding; a cute thinking animation appears above their head while they deliberate
Building	Import blueprints and they'll build the structure for you — supports .nbt / .schem / .litematic formats, materials appear from thin air (see Blueprint Building)
Accessories	`Shift` + right-click with an empty hand to open the accessories panel, compatible with accessory mods

Your companion also has a goal system — when you are not giving orders, they come up with their own little plans and decide what to do. Don't be surprised if they suddenly wander off to admire some flowers.

Accidentally gave them the wrong item? Just tell them to spit it out.

Blueprint Building

Tell your companion what you want built, and they'll put it up brick by brick.

Importing Blueprints

Place blueprint files in your game directory under config\koamc\blueprints\. Three common formats are supported:

.nbt — vanilla Structure Block / Create export format
.schem — Sponge / WorldEdit format
.litematic — Litematica format

The mod also includes a few pre-built structures — you can use those right away without importing anything.

Starting a Build

Aim at the target ground

The blueprint's front-door anchor will snap to where your crosshair points, with the door facing your direction — think of it as "you're standing at the future doorstep, looking in."
Tell your companion

Just use natural language — "build me a cabin" or "help me build the cottage." They'll confirm the position and orientation, mark the footprint on the ground, and start construction once you approve.

No need to gather materials — your companion will generate the blocks from thin air, building the structure like a 3D printer.

Built in the wrong spot? Use /koa undo_build to undo the most recent build and restore the terrain.

Useful Commands

Pressing K to open the in-game panel is the most convenient way to manage your companion — summon, stay, and more are all there. The following commands are still available as supplements:

/koa summon — teleport them to your side (useful when they get lost or stuck)
/koa stay — park them in place and have them wait for you
/koa despawn — have them leave temporarily
/koa quiet — pause LLM calls to save tokens (useful when AFK or focused on building)
/koa strong — Power Mode: max out their combat stats, sweep everything
/koa weak — return to normal mode, fight fair side by side
/koa chatty 1-5 — adjust how talkative they are; higher numbers mean more chatter. Enter /koa chatty alone to check the current level
/koa undo_build — undo the most recent build and restore the original terrain

Recommended Mods

KOA has built deep integration for the following mods. Mods marked Integrated are automatically recognized by KOA — no extra setup needed.

MCA (Minecraft Comes Alive) — Integrated: use a wedding ring to marry your companion
Senro Story — Integrated: your companion has unique reactions when given drinks from this mod
CasualSwing — Integrated: your companion can sit and swing with you
Accessories — Integrated: equip your companion with accessories and trinkets — any mod built on the Accessories ecosystem is supported (e.g. SimpleHats). Requires: owo-lib, Curios
Kaleidoscope Tavern — brew drinks and give them to your companion

Troubleshooting

Companion doesn't appear

Most common cause: you launched vanilla 1.21.1 instead of NeoForge. Make sure the version name includes "neoforge".
Confirm KOA MC appears in your launcher's Mods list (if using a third-party launcher, double-check the directory you selected during mod installation).
Try /koa summon to manually summon them.

Companion appears but doesn't talk

Make sure your API Key is entered and has remaining quota (the API Setup Guide has an error reference table).
Check the "Logs" page in the KOA launcher for server output — the error cause is usually immediately visible.

If you can't resolve it, export a diagnostic package and reach out through the channels listed in the Help Center.