--- title: "How to Mod Stardew Valley: SMAPI and Content Patcher Guide" description: "Install SMAPI, add mods safely, then build a Stardew Valley mod with Content Patcher: folder layout, manifest.json, content.json, sprite sizes and testing." canonical_url: "https://spritesheetgenerator.online/guides/how-to-mod-stardew-valley" last_updated: 2026-11-05 meta: author: "Dennis Postma" "og:description": "Install SMAPI, add mods safely, then build a Stardew Valley mod with Content Patcher: folder layout, manifest.json, content.json, sprite sizes and testing." "og:image": "https://spritesheetgenerator.online/guides/og-how-to-mod-stardew-valley.png" "og:image:alt": "How to Mod Stardew Valley: SMAPI and Content Patcher Guide" "og:title": "How to Mod Stardew Valley: SMAPI and Content Patcher Guide" "twitter:image": "https://spritesheetgenerator.online/guides/og-how-to-mod-stardew-valley.png" "twitter:image:alt": "How to Mod Stardew Valley: SMAPI and Content Patcher Guide" --- > Index of every page on this site: [llms.txt](https://spritesheetgenerator.online/llms.txt) ## What You Need Three things, all free: - **SMAPI**, the mod loader. Nothing else works without it. - **Content Patcher**, a SMAPI mod that lets you change game assets with a JSON file instead of C#. - **A text editor** that shows JSON errors. VS Code is fine. Notepad is not, because one missing comma breaks the whole file and Notepad will not tell you where. You also want a copy of the original sprites to look at. More on that below. ## Install SMAPI Download the latest release from smapi.io and unzip it somewhere outside the game folder. Inside you will find an installer script for each platform: `install on Windows.bat`, `install on macOS.command` and `install on Linux.sh`. Run the one for your system and pick **Install** when it asks. The installer finds your game folder on its own in most cases. When it finishes, it tells you how to launch the game with SMAPI. On Steam that usually means a launch option it prints for you to paste in. Follow what it says for your setup rather than a tutorial from three versions ago, because the steps have changed over the years. Start the game once. A console window opens next to it. That window is SMAPI, and it is where every error and warning shows up. Keep it visible while you mod. ## Install Other People's Mods Nexus Mods and ModDrop host most Stardew mods. A mod download is a zip with one folder inside. Unzip it into `Stardew Valley/Mods` so you end up with something like: ``` Stardew Valley/ Mods/ ContentPatcher/ SomeNiceMod/ manifest.json ``` Two habits save a lot of grief: 1. **Read the requirements on the mod page.** Many mods are content packs for Content Patcher or another framework. If the framework is missing, the SMAPI console says so in red on startup. 2. **Add mods a few at a time.** When something breaks after you added twenty, you are bisecting. After two, you know. To remove a mod, delete its folder. Mods do not change your game files, so there is nothing else to undo. Your save might still mention items from a removed mod, which is why it is worth backing up `%appdata%/StardewValley/Saves` (or the equivalent on your system) before you try a big one. ## How a Content Patcher Mod Works The game loads every image by an asset name such as `Characters/Abigail` or `Portraits/Abigail`. Content Patcher sits in between. When the game asks for `Characters/Abigail`, Content Patcher applies your patches to it before the game sees it. That gives you two main actions: | Action | What it does | Use it when | | --- | --- | --- | | `Load` | Replaces the whole asset with your file | You add something new, or nobody else should touch it | | `EditImage` | Pastes your image over part or all of the original | You change existing art and want to play well with other mods | Two mods cannot both `Load` the same asset. Many mods can `EditImage` it. For a retexture, `EditImage` is almost always the right pick. ## Build Your First Mod The example below replaces Abigail's overworld sprite. Swap in any NPC; the steps are the same. 1. **Make the folder.** In `Mods`, create `[CP] Abigail Retexture`. The `[CP]` prefix is a convention that tells players this is a Content Patcher pack. 2. **Add `manifest.json`.** This is the mod's ID card. 3. **Add `content.json`.** This is the list of patches. 4. **Add your art** in an `assets` subfolder. 5. **Start the game** and watch the SMAPI console for your mod's name. The manifest: ```json { "Name": "Abigail Retexture", "Author": "YourName", "Version": "1.0.0", "Description": "A new overworld sprite for Abigail.", "UniqueID": "YourName.AbigailRetexture", "UpdateKeys": [], "ContentPackFor": { "UniqueID": "Pathoschild.ContentPatcher" } } ``` `UniqueID` has to be unique across every mod in existence, which is why it starts with your name. `ContentPackFor` tells SMAPI to hand this folder to Content Patcher. The patch file: ```json { "Format": "2.0.0", "Changes": [ { "Action": "EditImage", "Target": "Characters/Abigail", "FromFile": "assets/abigail.png" } ] } ``` `Format` is the Content Patcher version your file is written for. Older values still work because Content Patcher migrates them, but when you start a new mod, use the current version from the Content Patcher author guide so you get the newest features. The finished folder: ``` [CP] Abigail Retexture/ manifest.json content.json assets/ abigail.png ``` ![A file explorer showing the \[CP\] Abigail Retexture folder inside Stardew Valley/Mods, with an assets folder holding abigail.png, plus content.json and manifest.json](https://spritesheetgenerator.online/guides/stardew-mod-folder.svg) *Three files and a folder. Content Patcher sits next to your pack in Mods and reads it on startup.* ## Get the Original Sprites You will want the vanilla sheet next to yours, to match size and layout. The game stores its images as `.xnb` files. StardewXnbHack unpacks them: put it in the game folder, run it, and it writes a `Content (unpacked)` folder full of plain PNGs. Open `Characters/Abigail.png` from there and you will see the layout you need to match. Every regular NPC uses the same one: - Frames are **16x32 pixels**. - The sheet is **4 frames wide**. - The first four rows are walking **down, right, up and left**, in that order. - Rows below that hold NPC-specific poses, like sitting or a special animation. ![An NPC sheet in the editor: four 16x32 frames per row, rows for walking down, right, up and left, with Columns set to 4 and Force Size at 16 x 32](https://spritesheetgenerator.online/guides/stardew-npc-sheet.svg) *The vanilla NPC layout. Columns 4 and Force Size 16 x 32 make the editor grid match it exactly.* Portraits in `Portraits/Abigail.png` are **64x64** per expression, two per row. The order of expressions is fixed by the game's dialogue codes, so copy the order of the vanilla file exactly. **Tip** Draw your sheet at 1x, the same 16x32 cells as the original. The game scales everything up for the screen. If you paint at 4x and export at 4x, the sprite comes out four times too large. ## Only Change Part of a Sheet `EditImage` without coordinates pastes your whole image at the top left. With `FromArea` and `ToArea` you can paste one region. This patch replaces only the walking-down row: ```json { "Action": "EditImage", "Target": "Characters/Abigail", "FromFile": "assets/abigail-down.png", "ToArea": { "X": 0, "Y": 0, "Width": 64, "Height": 32 } } ``` Smaller patches clash less with other mods. If someone else changed Abigail's sitting pose and you only touched her walk, both changes survive. Add `"PatchMode": "Overlay"` when your image has transparent parts that should let the original show through. A hat on top of the existing sprite is the classic case. ## Make It React to the Game Content Patcher patches can carry conditions. This version only applies in winter: ```json { "Action": "EditImage", "Target": "Characters/Abigail", "FromFile": "assets/abigail-winter.png", "When": { "Season": "Winter" } } ``` ![content.json open in a code editor with two EditImage patches for Characters/Abigail, the second one limited to winter by a When condition](https://spritesheetgenerator.online/guides/stardew-content-json.svg) *Patches apply top to bottom, so the winter sheet lands on top of the regular one only while the condition holds.* Season, weather, day of the week, friendship level and whether another mod is installed are all available as conditions. A winter coat that appears on its own is the kind of detail players notice and remember. ## Test Without Restarting Restarting the game for every pixel tweak gets old fast. Content Patcher adds console commands to the SMAPI window: - `patch reload YourName.AbigailRetexture` re-reads your files while the game runs. - `patch summary` lists every patch and whether it applied. When your sprite does not show up, this tells you why. ![A simplified SMAPI console listing Content Patcher and the Abigail Retexture pack, then the patch reload and patch summary commands](https://spritesheetgenerator.online/guides/stardew-smapi-console.svg) *A simplified SMAPI console. Your pack shows up in the startup list, and the two patch commands run while the game is open.* ## Where the Art Comes From If you draw, the built-in [pixel art editor](https://spritesheetgenerator.online/features/pixel-art-editor) works at 16x32 and exports a plain PNG. If you do not, the [gallery](https://spritesheetgenerator.online/gallery) has sheets other people published for anyone to reuse, and the [Stardew Valley mod sprites](https://spritesheetgenerator.online/mods/stardew-valley) page lists the ones that already fit the NPC grid. Art ripped from other games is a different story. It is not yours to ship even when it looks perfect, and the [licensing guide](https://spritesheetgenerator.online/guides/free-sprite-sheets-licenses) explains how to check where a sheet came from. ## Share It Zip the mod folder (the folder itself, not just its contents) and upload it to Nexus Mods or ModDrop. List Content Patcher as a requirement. Once the mod page exists, put its key in `UpdateKeys`, for example `"Nexus:12345"`, and SMAPI will tell players when you release an update. **Draw or rearrange your NPC sheet in the browser.** [Open the editor](https://spritesheetgenerator.online/editor) ## **Try it in the editor** The editor is free and needs no account. Open it in another tab and work through the steps above with your own frames. [Open the editor](https://spritesheetgenerator.online/editor) [See all features](https://spritesheetgenerator.online/features) ## **Keep reading** [**Modding****How to Mod Terraria: tModLoader Setup and Your First Mod** 6 min read](https://spritesheetgenerator.online/guides/how-to-mod-terraria "How to Mod Terraria: tModLoader Setup and Your First Mod") [**Sprite sheets****Character Sprite Sheets: Which Animations Your Game Needs** 7 min read](https://spritesheetgenerator.online/guides/character-sprite-sheet "Character Sprite Sheets: Which Animations Your Game Needs") [**Sprite sheets****Free Sprite Sheets: Where to Find Them, What Licenses Allow** 7 min read](https://spritesheetgenerator.online/guides/free-sprite-sheets-licenses "Free Sprite Sheets: Where to Find Them, What Licenses Allow") --- ```json {"@context":"https://schema.org","@graph":[{"@id":"https://spritesheetgenerator.online/#website","@type":"WebSite","description":"Free online tool to create spritesheets for game development. Upload sprites, arrange them, and export as a spritesheet with animation preview.","name":"Spritesheet Generator","url":"https://spritesheetgenerator.online/","publisher":{"@id":"https://spritesheetgenerator.online/#identity"}},{"@id":"https://spritesheetgenerator.online/guides/how-to-mod-stardew-valley#webpage","@type":"WebPage","dateModified":"2026-11-05","datePublished":"2026-11-05","description":"Install SMAPI, add mods safely, then build a Stardew Valley mod with Content Patcher: folder layout, manifest.json, content.json, sprite sizes and testing.","name":"How to Mod Stardew Valley: SMAPI and Content Patcher Guide","url":"https://spritesheetgenerator.online/guides/how-to-mod-stardew-valley","breadcrumb":{"@id":"https://spritesheetgenerator.online/guides/how-to-mod-stardew-valley#breadcrumb"},"isPartOf":{"@id":"https://spritesheetgenerator.online/#website"},"potentialAction":[{"@type":"ReadAction","target":["https://spritesheetgenerator.online/guides/how-to-mod-stardew-valley"]}],"primaryImageOfPage":{"@id":"https://spritesheetgenerator.online/#logo"}},{"@id":"https://spritesheetgenerator.online/#identity","@type":"Organization","description":"A free, browser based sprite sheet generator for 2D game developers and pixel artists.","name":"Spritesheet Generator","url":"https://spritesheetgenerator.online","logo":{"@id":"https://spritesheetgenerator.online/#logo"},"sameAs":["https://discord.gg/2vvfqwn5k7"]},{"@id":"https://spritesheetgenerator.online/guides/how-to-mod-stardew-valley#breadcrumb","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","name":"Home","item":"https://spritesheetgenerator.online","position":1},{"@type":"ListItem","name":"Guides","item":"https://spritesheetgenerator.online/guides","position":2},{"@type":"ListItem","name":"How to Mod Stardew Valley: SMAPI and Content Patcher Guide","item":"https://spritesheetgenerator.online/guides/how-to-mod-stardew-valley","position":3}]},{"@id":"https://spritesheetgenerator.online/about#dennis-postma","@type":"Person","name":"Dennis Postma","url":"https://spritesheetgenerator.online/about","sameAs":["https://github.com/Dennis4720"]},{"@id":"https://spritesheetgenerator.online/guides/how-to-mod-stardew-valley#article","dateModified":"2026-11-05","datePublished":"2026-11-05","description":"Install SMAPI, add mods safely, then build a Stardew Valley mod with Content Patcher: folder layout, manifest.json, content.json, sprite sizes and testing.","headline":"How to Mod Stardew Valley: SMAPI and Content Patcher Guide","inLanguage":"en","thumbnailUrl":"https://spritesheetgenerator.online/guides/og-how-to-mod-stardew-valley.png","@type":["Article","TechArticle"],"articleSection":["Modding"],"author":{"@id":"https://spritesheetgenerator.online/about#dennis-postma"},"image":{"@id":"https://spritesheetgenerator.online/#/schema/image/1"},"isPartOf":{"@id":"https://spritesheetgenerator.online/guides/how-to-mod-stardew-valley#webpage"},"mainEntityOfPage":{"@id":"https://spritesheetgenerator.online/guides/how-to-mod-stardew-valley#webpage"},"publisher":{"@id":"https://spritesheetgenerator.online/#identity"}},{"@id":"https://spritesheetgenerator.online/#logo","@type":"ImageObject","caption":"Spritesheet Generator","contentUrl":"https://spritesheetgenerator.online/web-app-manifest-512x512.png","inLanguage":"en","url":"https://spritesheetgenerator.online/web-app-manifest-512x512.png"},{"@id":"https://spritesheetgenerator.online/#/schema/image/1","@type":"ImageObject","contentUrl":"https://spritesheetgenerator.online/guides/og-how-to-mod-stardew-valley.png","inLanguage":"en","url":"https://spritesheetgenerator.online/guides/og-how-to-mod-stardew-valley.png"}]} ``` ## Sitemap See the full [sitemap](https://spritesheetgenerator.online/sitemap.md) for all pages.