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, one-click install

Click "Minecraft" on the KOA home screen to open the panel, then click "Auto-install mod files" in the top bar. The launcher will automatically locate the default %APPDATA%\.minecraft directory and install the mod into mods\ (any older version is removed first to prevent duplicate-mod crashes).
Third-party launchers: pick the right directory

When using third-party launchers like PCL2 / HMCL / Prism, automatic detection may not work and a directory picker will appear:
- Without version isolation: select the .minecraft folder.
- With version isolation (common in PCL2 / HMCL): select the .minecraft\versions\<version-name>\ folder, e.g. .minecraft\versions\1.21.1-neoforge\.
Do not select inside the mods\ folder — the installer will create the mods\ and koamc\ subdirectories automatically. Picking the wrong location means the mod ends up in the wrong place and your companion won't appear in-game.
Missing NeoForge will block installation

If the launcher cannot detect NeoForge, it will prompt you to download it from neoforged.net — install it, then come back and click again.

When KOA updates in the future, the mod is automatically detected and updated at launch — no reinstallation needed.

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.

Recommended method: Upload a standard 64x64 MC skin image directly through the launcher. The launcher handles renaming and placement automatically; restart the game to apply.

Manual method: Place the skin image in the .minecraft\koamc\ directory — if the file shows a .png extension, rename it to companion.png; if your system hides extensions, rename it to companion.

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.