Difference between revisions of "Modding:Content Patcher"
Pathoschild (talk | contribs) (expand & update intro) |
Pathoschild (talk | contribs) (expand) |
||
Line 3: | Line 3: | ||
Do you want to create Content Patcher packs for Stardew Valley? This guide is for you! '''For using mods, see [[Modding:Player Guide/Getting Started|Modding:Player Guide]].''' | Do you want to create Content Patcher packs for Stardew Valley? This guide is for you! '''For using mods, see [[Modding:Player Guide/Getting Started|Modding:Player Guide]].''' | ||
− | == | + | ==Quick start== |
+ | This guide is meant as a gentle introduction to creating Content Patcher packs. If you don't need a gentle introduction, see the [https://github.com/Pathoschild/StardewMods/tree/develop/ContentPatcher#readme full Content Patcher readme]. | ||
+ | |||
+ | ==Basic concepts== | ||
===What is Content Patcher?=== | ===What is Content Patcher?=== | ||
− | {{nexus mod|1915|Content Patcher}} is a SMAPI mod which lets you change the game assets (images, dialogue, data, and maps) without replacing game files or writing code. You use it by creating a content pack (basically a folder | + | {{nexus mod|1915|Content Patcher}} is a SMAPI mod which lets you change the game assets (images, dialogue, data, and maps) without replacing game files or writing code. You use it by creating a content pack (basically a folder) with a couple of JSON files (basically text). Just by editing a JSON file, you can... |
* replace one image file; | * replace one image file; | ||
Line 13: | Line 16: | ||
* and much more. | * and much more. | ||
− | ===Content Patcher vs | + | ===Assets=== |
− | Content Patcher | + | An ''asset'' is essentially a file in the <tt>Content</tt> folder with a unique ''asset name''. The asset name never includes the <tt>Content</tt> path, language, or file extension (you can use [[/Tokens|tokens]] to target specific languages). For example: |
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! file | ||
+ | ! asset name | ||
+ | |- | ||
+ | | <tt>Content/Portraits/Abigail.xnb</tt> | ||
+ | | <tt>Portraits/Abigail</tt> | ||
+ | |- | ||
+ | | <tt>Content/Maps/spring_beach.xnb</tt><br /><tt>Content/Maps/spring_beach.es-ES.xnb</tt><br /><tt>Content/Maps/spring_beach.fr-FR.xnb</tt> | ||
+ | | <tt>Maps/spring_beach</tt> | ||
+ | |} | ||
+ | |||
+ | An asset may contain multiple sprites or data entries. For example, here's what <tt>Portraits/Abigail</tt> contains if you unpack it: | ||
+ | |||
+ | [[File:Modding - creating an XNB mod - example portraits.png]] | ||
+ | |||
+ | So if you wanted to change Abigail's portraits, you would use Content Patcher to load or edit <tt>Portraits/Abigail</tt>. | ||
+ | |||
+ | ===Load vs edits=== | ||
+ | There are two conceptual ways you can change an asset: | ||
+ | |||
+ | * ''Load'' the initial version of an asset. Each asset can only be loaded by one mod at the same time. This is mainly useful for total replacement mods (like a mod that completely changes an NPC's portraits), or to provide files that don't exist in the <tt>Content</tt> folder. | ||
+ | * ''Edit'' an asset after it's loaded. Any number of edits can be applied to the same asset. | ||
+ | |||
+ | For example, let's say the game needs Abigail's portraits. This is how changes are applied: | ||
+ | <pre> | ||
+ | ┌────────────┐ | ||
+ | │ edit asset │ | ||
+ | ┌───────────┐ ├────────────┤ | ||
+ | get Portraits/Abigail ──>│ load file │───>│ edit asset │──> portrait asset | ||
+ | └───────────┘ ├────────────┤ | ||
+ | │ edit asset │ | ||
+ | └────────────┘ | ||
+ | </pre> | ||
+ | |||
+ | This is divided into four different action types (<tt>Load</tt>, <tt>EditImage</tt>, <tt>EditData</tt>, <tt>EditMap</tt>), which is explained in more detail on the following pages. | ||
+ | |||
+ | ==Get started== | ||
+ | First let's get our basic content pack up and running: | ||
+ | <ol> | ||
+ | <li>Install [https://smapi.io/ SMAPI] and {{nexus mod|1915|Content Patcher}}.</li> | ||
+ | <li>Unpack the game's <tt>Content</tt> folder so you can see what each asset contains (see [[Modding:Editing XNB files#Unpack game files]]).</li> | ||
+ | <li>[[Modding:Content packs#Create a content pack|Create a SMAPI content pack]].</li> | ||
+ | <li>Create a <tt>content.json</tt> file in the same folder this content: | ||
+ | <source lang="javascript"> | ||
+ | { | ||
+ | "Format": "1.9", | ||
+ | "Changes": [ | ||
+ | ] | ||
+ | } | ||
+ | </source> | ||
+ | </li> | ||
+ | <li>Launch the game.</li> | ||
+ | </ol> | ||
+ | |||
+ | If you did everything correctly so far, you should see the new mod under "Loaded X content packs" in the SMAPI console! (If not, review the above steps or [[/Troubleshooting#Ask for help|come ask for help]].) | ||
− | + | ==Next steps== | |
− | + | You've created a Content Patcher pack! Next we'll make it do something. This tutorial will walk you through creating Blueberries Everywhere, a mod which just turns various things into blueberries. | |
− | |||
− | |||
− | |||
− | + | When you're ready to continue, see the navigation at the bottom of the page to continue. | |
− | == | + | ==See also== |
− | + | * [https://github.com/Pathoschild/StardewMods/tree/develop/ContentPatcher#readme Content Patcher readme] for the full technical reference, known limitations, FAQs, etc | |
{{modding guide footer | {{modding guide footer | ||
|prev = | |prev = | ||
− | |next = [[/ | + | |next = [[/Load|Load assets]] |
}} | }} |
Revision as of 22:50, 24 September 2019
Do you want to create Content Patcher packs for Stardew Valley? This guide is for you! For using mods, see Modding:Player Guide.
Quick start
This guide is meant as a gentle introduction to creating Content Patcher packs. If you don't need a gentle introduction, see the full Content Patcher readme.
Basic concepts
What is Content Patcher?
Content Patcher is a SMAPI mod which lets you change the game assets (images, dialogue, data, and maps) without replacing game files or writing code. You use it by creating a content pack (basically a folder) with a couple of JSON files (basically text). Just by editing a JSON file, you can...
- replace one image file;
- make seasonal changes;
- make dialogue that changes based on the weather, date, your relationships with other NPCs, etc;
- make very specific changes (like coffee is more expensive on winter weekends when it's snowing after you've completed the JojaMart);
- and much more.
Assets
An asset is essentially a file in the Content folder with a unique asset name. The asset name never includes the Content path, language, or file extension (you can use tokens to target specific languages). For example:
file | asset name |
---|---|
Content/Portraits/Abigail.xnb | Portraits/Abigail |
Content/Maps/spring_beach.xnb Content/Maps/spring_beach.es-ES.xnb Content/Maps/spring_beach.fr-FR.xnb |
Maps/spring_beach |
An asset may contain multiple sprites or data entries. For example, here's what Portraits/Abigail contains if you unpack it:
So if you wanted to change Abigail's portraits, you would use Content Patcher to load or edit Portraits/Abigail.
Load vs edits
There are two conceptual ways you can change an asset:
- Load the initial version of an asset. Each asset can only be loaded by one mod at the same time. This is mainly useful for total replacement mods (like a mod that completely changes an NPC's portraits), or to provide files that don't exist in the Content folder.
- Edit an asset after it's loaded. Any number of edits can be applied to the same asset.
For example, let's say the game needs Abigail's portraits. This is how changes are applied:
┌────────────┐ │ edit asset │ ┌───────────┐ ├────────────┤ get Portraits/Abigail ──>│ load file │───>│ edit asset │──> portrait asset └───────────┘ ├────────────┤ │ edit asset │ └────────────┘
This is divided into four different action types (Load, EditImage, EditData, EditMap), which is explained in more detail on the following pages.
Get started
First let's get our basic content pack up and running:
- Install SMAPI and Content Patcher.
- Unpack the game's Content folder so you can see what each asset contains (see Modding:Editing XNB files#Unpack game files).
- Create a SMAPI content pack.
- Create a content.json file in the same folder this content:
{ "Format": "1.9", "Changes": [ ] }
- Launch the game.
If you did everything correctly so far, you should see the new mod under "Loaded X content packs" in the SMAPI console! (If not, review the above steps or come ask for help.)
Next steps
You've created a Content Patcher pack! Next we'll make it do something. This tutorial will walk you through creating Blueberries Everywhere, a mod which just turns various things into blueberries.
When you're ready to continue, see the navigation at the bottom of the page to continue.
See also
- Content Patcher readme for the full technical reference, known limitations, FAQs, etc