Terraria

What This Is

Play Terraria with your companion. They stay by your side mining, chopping trees, fishing, and fighting, and they can build you a house or lay out a boss arena. When you need a pile of something, they take the order, go off on their own, and come back with it. While they are away you keep chatting, and they tell you what they run into out there.

Just talk, no commands to memorize: "dig up some iron", "go get 50 wood", "build me a room".

If you haven't finished the four basics (install, activate, API, character), go through Quick Start first and come back.

Before You Start

• Terraria, the Steam version.
• tModLoader: Terraria's mod loader. Search for tModLoader on the Steam store. It is free if you own Terraria, and shows up in your library as a separate game.

Installing the Mod

1. One-click install

   From the KOA home screen, click "Terraria" to open its panel, then click "Auto-install mod required files" in the top bar. The launcher puts the mod into tModLoader's Mods\ folder and enables it for you, so there is nothing to tick in the mod list.

2. Not found automatically? Point to it

   The launcher finds Terraria through Steam. If it is installed somewhere unusual, a folder picker pops up. Point it to your Terraria install folder.

3. "Open folder" can wait

   When the install finishes, the launcher offers to open a folder. That is where their appearance image lives (Documents\My Games\Terraria\tModLoader\KOA\). You only need it when changing their look.

4. Enter a world with tModLoader

   Launch tModLoader from Steam and enter any world. They will be right beside you. New worlds and existing ones both work.

Meeting in the World

1. They follow you

   They open doors, jump up ledges, and drop down through platforms. If you get too far ahead or they get stuck on terrain, they appear next to you in a puff of smoke. When you fly, they fly after you.

2. Typing

   Press Enter to open the game's own chat box. Anything that doesn't start with / reaches them. The first time you enter a world, the chat shows "KOA: server connected".

3. Talking

   Pick the trigger mode on the launcher's API page. With "Auto-detect speech", just speak. With "Push to talk", press V in game to start recording and press it again to stop. See Voice Guide for details.

4. Two things you'll use a lot

   Press K for the in-game panel. Right-click them to open their inventory. Both are covered below.

In-Game Panel

Press K. The panel has five rows, with the current state on the left and a button on the right:

Inventory and Weapons

Right-click them and their inventory opens below yours. Hovering over them shows "Right click: bag".

• Giving: putting something in their bag is giving it to them. There is no separate gift button. They find out what you gave when you close the bag.
• Taking: everything they mine, chop, pick up, or fish ends up here. Take what you want. Or say "give me the iron" and they will walk over and hand it to you.
• Weapon slot: one slot in the bag is marked "Weapon". Put a sword, bow, or gun in it and that is what they fight with. Anything that isn't a weapon gets moved back into the bag.
• Tools: they mine with the best pickaxe in their bag, or with a strength based on world progress if there isn't one. Fishing needs a fishing pole in their bag, torches need torches, arenas need platforms.

Normal and Power Mode

• Normal (default): how strong they are depends on what you give them. With an empty weapon slot they punch, and it doesn't hurt much.
• Power Mode: even bare-handed they hit with a strength that grows with world progress, higher for every boss down. If the weapon in their slot is stronger, they use that.

Both modes only change their attack. They never take damage and never go down. The setting is saved with your character, so it stays the way you left it.

Healing

When your health drops into the red, they throw you a healing potion. If you are near them, a hit that would have killed you gets caught. The potions cost you nothing and don't come out of their bag, and they get better as you beat more bosses. This works the same in Normal and Power Mode.

What They Can Do

As always, just ask:

Orders, Wandering, Expeditions

You don't have to stick together the whole time. You get on with your thing, and they can go off and do theirs.

Orders

"Get me 50 wood", "go dig up 30 iron ore". They take the order, head off on their own, and come back to hand it over once they have enough. The chat shows how much they delivered.

• Give a number. If you just say "get some wood", they'll ask how many first.
• They can take orders for wood, stone, dirt, sand, clay, mud, ice, snow, obsidian, cobweb, gems, and every ore from copper to chlorophyte.
• If they can't find any more, or their pickaxe is too weak, they come back with what they have to talk it over.
• Say "come back for a sec" and they return to you with the order on hold; what they've gathered stays in their bag. "Go on" sends them back to finish. "Forget it" makes them hand over what they have and cancels the order.
• If a boss shows up, they drop the order and hurry back.

Wandering

"Go explore on your own for a bit." They'll take a stroll nearby, drop in on a townsperson, find somewhere to sit, or pick herbs. You can name someone, like "go see the Merchant". You keep chatting while they're out, and they'll tell you if they spot something interesting.

• Surface only. They can't wander underground.
• If you walk away, they stay where they are and keep wandering. Say "come back" and they return.
• If a boss appears or things are going badly for you, they come back on their own.

Expeditions

"Go check out the jungle." They leave your world for a while: four to seven minutes for nearby places, up to around twenty for far ones. They come back with what they gathered there. You can still talk on the way, and they'll tell you what they come across.

• Destinations: forest, underground, caverns, snow, desert, jungle, ocean, the Corruption or Crimson (whichever your world has), glowing mushroom biome, the Underworld, sky islands, the Hallow (Hardmode only), and the Dungeon (after Skeletron).
• To call them back early, just tell them, or press K and click "Call over".
• They won't set out while a boss is alive. If a boss appears mid-expedition, they hurry back.
• When they say they saw a chest, it's a real one in your world. Go where they said and it'll be there.

Changing Their Look

They come with a default look out of the box. To change it:

1. Make one in the sprite editor

   On the launcher home screen, go to "Tools", then "Terraria Sprite Editor". Click "Load Game Assets" first so the editor can read the textures from your Terraria install. Then pick gender, hairstyle, skin and eye color, and colors for the shirt, undershirt, pants, and shoes. Under "Saved look per persona", "Save" keeps a look and "Load" brings it back.

2. Export, then reload in game

   Click "Export Sprite Sheet". The image is written straight into their appearance folder. Type /koareload in game and the new look appears without restarting.

3. Make the look follow the character

   Home, then "Profile", then "My Lovers". Under this character's "Skins", click "Upload" next to "Terraria Sprite". From then on, switching characters switches the in-game look too.

Drawing your own or commissioning an artist

The full image is 44×1350 pixels: 25 frames stacked in one column, each 44×54. Name it companion.png, put it in Documents\My Games\Terraria\tModLoader\KOA\, and run /koareload in game.

For facing direction and where the character sits in each frame, follow a sheet exported from the editor. Export a default one and draw over it.

Hurt Sound

With KOA installed, female characters no longer make the vanilla sound when hit. By default it becomes a dull thud.

To pick something else, open "Mod Configuration" in the game settings and find "Hurt Sound". "Sound when hit" can be silent, a frog, duck, bird, seagull, owl, dolphin, cat, cockatiel, macaw, toucan, or the male character's voice, with a preview when you save. "Volume" only affects this one sound. "Male characters too" is off by default.

These settings only change what you hear.

Commands

The panel and right-click cover everyday use. These are backups:

• /koaspawn: moves them to your side, for when they're lost or stuck
• /koareload: reloads their look after you change the image
• /koabag: opens their inventory. If right-clicking them does nothing, /koabag debug shows which step failed

Troubleshooting

They don't appear

1. Most common: you launched vanilla Terraria, not tModLoader.
2. Check tModLoader's mod list to see whether KOA is enabled. After a failed load, tModLoader sometimes disables all mods.
3. If you're in the world and still can't see them, type /koaspawn.
4. Make sure the Terraria panel is running in the KOA launcher (green status dot on the home card).

The installer says it needs tModLoader first

tModLoader is installed but has never been launched. Launch it once, get to the main menu, close it, then click "Auto-install mod required files" again.

They don't talk or respond

1. If the chat says "KOA: server offline", go back to the launcher, click "Terraria", and wait for the panel to come up.
2. Press K and check whether the first row says "Muted".
3. Make sure your API key is filled in and has credit left (API Setup Guide has an error table).
4. Check the server output on the launcher's "Logs" page.

K does nothing, or the panel buttons don't work

Find "Companion Panel" in the game's keybinding settings and check it's bound to K. If it's bound to a mouse button, clicking a button closes the panel before the click lands.

Right-clicking them doesn't open the inventory

Type /koabag to open it directly. Then type /koabag debug and include what it prints in chat when you report the problem.

Their look didn't change

1. Type /koareload in game. When the chat says "KOA: skin reloaded", it worked.
2. Check that companion.png is in Documents\My Games\Terraria\tModLoader\KOA\. If OneDrive manages your Documents folder, look under OneDrive's Documents instead.
3. Misaligned or garbled frames usually mean the size is wrong. Compare against the frame table above.

Still stuck? Export a diagnostic bundle and report it through the channels listed in the Help Center.