Tutorial: Making a Custom Shop

If you're looking to make a custom shop for your NPC, this is the guide for you! I will cover creating a shop, adding items, and making rotating stock.

Before you start: This tutorial assumes you know how to create a basic content pack with a manifest and make basic changes with CP. If you don't, start reading the official CP author guide and/or the beginner tutorial on this wiki: Tutorial: Your First Content Patcher Pack. Checking the official wiki documentation can also be very helpful. If you're making a custom NPC, Tiakall's guide is really helpful: Tutorial: Making a Custom NPC

Set Up

Manifest

Every content pack needs a manifest. Take a look at this guide for a guide on how to create one: Tutorial: How to create a manifest

content.json

First, you need to set up a content.json, which is where the magic happens.

Here's a basic, blank content.json:

{
    "Format": "2.7.1" // Change this to the latest version of Content Patcher
    "Changes": [
        // Your code goes here!
    ]
}

Create a shops.json file

This isn't necessary, but I like to organize my json into different files and later include them into the content.json. For organization, I usually would put this file into either a Data/ folder or in Assets/Data.

You can skip this, but when you begin creating bigger projects, it might get unmanageable.

So after you've created the file, you can include that file into content.json by writing:

{
    "LogName": "Adding shops.json",
    "Action": "Include",
    "FromFile": "data/shops.json" // Or wherever you placed the file
}

Now, you're all ready to start creating the shop!

Creating a custom shop

Setting up the shops.json file

You also need to set up the shops.json file. If you are directly writing into content.json, adjust as needed.

{
    "Changes": [
        {
            "LogName": "Adding my custom shop",
            "Action": "EditData",
            "Target": "Data/Shops",
            "Entries": {
                // Code for custom shop goes here
            }
        }
    ]
}

What the code is doing

"LogName": "Adding my custom shop" - Just a little comment on what this section of coding is doing. It's helpful for debugging, as you can find where things went wrong!

"Action": "EditData" - This tells CP what to do with the data we put.

"Target": "Data/Shops" - This is where the data for shops is located in the game files!

"Entries": { } - This is where your code will go.

Creating the shop

In the "Entries" section, we will now set up for the custom shop data.

{
    "{{ModId}}_MyCustomShop": {
        // Shop data goes here!
    }
}

This might not look too exciting yet, but we will add the data later. This code adds the UniqueId for the shop. Since the shop name should be unique to avoid conflicts with the game itself and other mods, adding {{ModId}}_ in front of IDs is suggested as CP automatically replaces that with your mod's UniqueID in the manifest.json. Feel free to change MyCustomShop to something else that fits your shop better.

Setting up shop data

These are some basic shop data entries for a typical shop. I suggest looking at the official wiki documentation on shops for a more extensive documentation on shop data!

{
    "{{ModId}}_MyCustomShop": {
        "Owners": [
            {
                "Name": "{{ModId}}_MyCustomNPC",
                "Portrait": "{{ModId}}_MyCustomNPC",
                "Dialogues": [
                    // Add dialogue here!
                ]
            }
        ],
        "Items": [
            // Add items here!
        ],
        "SalableItemTags": [
            // Add salable item tags here!
            "category_flowers"
        ]
    }
}

Now, I will break down what every part of code is doing.

Owners

This is a list of owners that activates the shop when near. Most of the time, there's going to be a designated shopkeeper. But if any NPC can run this shop, you can also do that, with extra information in the wiki I linked above.

Name

This is the internal name, or UniqueID, of the NPC.

Portrait

This is the internal name, or UniqueID, of the NPC whose portrait will be used when the shop menu opens. Most of the time, it's the same as the data entry above.

Dialogues

This is the dialogue that will appear when the menu opens! I will go into more detail later.

Items

This is the list where you will add the items themselves! I will go into detail about adding items later in the tutorial.

SalableItemTags

This is a list where you add the item tags of the category that the player can sell in the shop. An example I added in the code block above is "category_flowers". This allows the player to sell items of the category "category_flowers" at the shop.

Owner Dialogue

{
    "{{ModId}}_MyCustomShop": {
        "Owners": [
            {
                "Name": "{{ModId}}_MyCustomNPC",
                "Portrait": "{{ModId}}_MyCustomNPC",
                "Dialogues": [
                    {
                        "Id": "{{ModId}}_Default",
                        "Dialogue": "Hello! This is the default dialogue."
                    },
                    {
                        "Id": "{{ModId}}_Spring",
                        "Condition": "SEASON spring",
                        "RandomDialogue": [
                            "This is random spring dialogue number 1!",
                            "This is random spring dialogue number 2!",
                            "This is random spring dialogue number 3!"
                        ]
                    }
                ]
            }
        ],
        "Items": [
            // Add items here!
        ],
        "SalableItemTags": [
            // Add salable item tags here!
            "category_flowers"
        ]
    }
}

In the examples, I added two types of dialogue for the shop! Here's a breakdown of what they do:

Id

This is the UniqueID within the dialogue list. I added {{ModId}}_ just for good practice, but it's not totally needed as it simply needs to be unique within the dialogue list. However, it is highly recommended for when you edit other mod's shops' or the vanilla shops' dialogue.

Condition

This is the game state query. If the game state query is met, the dialogue line will be available. Here's the official wiki documentation on game state queries: Game State Queries

If omitted, like in the default dialogue above, it will be always available.

Dialogue

This is the dialogue line itself that will trigger when the conditions are met.

RandomDialogue

This is a list of dialogue lines that will be randomly selected. You can add as many as you'd like!

Item Data

{
    "{{ModId}}_MyCustomShop": {
        "Owners": [
            {
                "Name": "{{ModId}}_MyCustomNPC",
                "Portrait": "{{ModId}}_MyCustomNPC",
                "Dialogues": [
                    // Add dialogue here!
                ]
            }
        ],
        "Items": [
            {
                "Id": "{{ModId}}_SweetPea",
                "Condition": "SEASON summer",
                "ItemId": "(O)402",
                "AvailableStock": 5,
                "Price": 1000
            },
            {
                "Id": "{{ModId}}_TulipSeeds",
                "ItemId": "(O)427"
            }
        ],
        "SalableItemTags": [
            // Add salable item tags here!
            "category_flowers"
        ]
    }
}

In the example, I added two items: Sweet Pea, and Tulip seeds. For more documentation on item data, check the official wiki page.

Id

This is the UniqueID of the item within the items list. Again, like the dialogue ID, I added {{ModId}}_ just for good practice, but it's not totally needed as it simply needs to be unique within the dialogue list.

Condition

Like the condition in the dialogues above, this is the game state query. If the game state query is met, the item will be available. This is used when making rotating stock. Here's the official wiki documentation on game state queries: Game State Queries

If omitted, like in the default tulip seeds above, it will be always available.

ItemId

This is the qualified ID of the item. Here is the website with the full list of the vanilla item IDs.

AvailableStock

This is the amount of the item available in the stock. If omitted, the player can buy as many as they want. This is reset every day.

Price

This one's pretty obvious, but it's the price of the item specifically at this shop. In the example, sweet pea is sold at (the ridiculous price of) 1000.

If omitted, it sets to the item's default price.

Advanced Item Data

Thank you Chu for suggesting adding these! These are slightly advanced but super helpful parts of item data.

Item Queries:

Item queries a dynamic way to add one or more items instead of specifying an item id. Here is the official wiki page for it!

Adding a random item from your custom items or all of your custom items

"PerItemCondition": "ITEM_ID_PREFIX Target YourName_YourModName_" - With this line, you can target all your items from the current mod you're working on! You can use this to add every custom item you added through your mod, or select a random item from your mod - or something else! There are tons of other PerItemConditions you can play with listed here, specifically the Items Only section: Game State Queries for Items

Conclusion

Well, that's it for this tutorial! You've now successfully made the shop! Give yourself a pat on the back.

But wait - it will not show up in the game yet. You have to add a tile property that opens the shop's menu in the map data itself... which is a whole another beast. I will hopefully be able to create a tutorial on that soon! In the meantime, you can dig through the documentation of modding maps: Modding:Maps (Psst - ctrl+f/cmd+f "Action OpenShop" to jump right there)

I hope you learned something from this tutorial, and I hope this was helpful! Please feel free to let me know if there are any errors. Happy modding! <3