Custom Companions for Stardew Valley

What this mod does

Custom Companions, by PeacefulEnd, is a framework for creating «companions»: simple creatures and characters that appear on maps or follow the player. According to Nexus, more than 130 mods use it, including several large expansions. On its own it adds nothing.

What it allows

• Map companions with behaviors such as walking a route, going back and forth, floating or jumping.
• Followers that trail behind the player, an NPC or another companion.
• Dialogue, overhead text, portraits, shadows, their own lights and a breathing animation.
• Spawn and despawn rules: at the start of the day, on a timer, by tiles, by player proximity or during festivals.

Requirements and compatibility

It only needs SMAPI. Version 5.1.0 (December 19, 2025, 78 KB) loads portraits through the content system. Version 5.0.0 updated it for 1.6.9. It has supported multiplayer since 1.4.4, integrates with Content Patcher and Save Anywhere, and Nexus tags it as compatible with Android.

There’s an example pack for authors under Optional files, but it needs Json Assets and is old; as a player you don’t need it.

Requirements

• Stardew Valley 1.6.9 or later (PC; tagged as compatible with Android)
• SMAPI 4.x
• Content packs that use it (it does nothing on its own)

How to install it

1. Install SMAPI first (see its mod page) and launch the game once with it to make sure it works.
2. Open the Custom Companions page on Nexus Mods, go to the Files tab and click Manual download on the main file (Custom Companions 5.1.0). You need a free Nexus account to download.
3. Extract the .zip outside the game folder and move the resulting folder into the Mods folder, inside the game folder.
4. Launch the game with SMAPI and check in the console that Custom Companions appears in the list of loaded mods with no red errors.

Version history

1. 5.1.019 Dec 2025Current

   Current file: portraits loaded through the content system

2. 3.0.024 Feb 2023

   Last version for 1.5.5 (Old files)

Common problems