Whether you are looking to upgrade some game assets, play as your OC, or inject your favorite memes into the game, there's a lot a mod can accomplish in 100% Orange Juice. Unfortunately, when things go wrong, it isn't always easy to see why or fix it. In this guide, we will go over some tips and tricks to fixing broken mods.

https://notepad-plus-plus.org

Notepad++ is a free text editor designed for writing code. Unlike default Notepad, Notepad++ uses colors to highlight parts of your JSON file, making it easier to spot formatting problems. JSON is one of the included code environments, so all you have to do is create your "mod.json" file and start writing!




https://www.audacityteam.org/

Audacity is a free audio editing software. It can export in both WAV format for sound effects and voice lines as well as OGG format for background music. The batch export capabilities are particularly helpful when you need to change the sample rate or file type of a large number of voice line files.




https://www.getpaint.net/

Paint.NET is a beginner friendly image editing program. Layers and extra tools and effects make it a huge step up from the default Paint. It lacks a lot of features that Photoshop or Clip Studio would have, but it does a good enough job for basic sprite editing. Heck, it's what I use to make those funny sprite edits.




https://www.gimp.org/

Gimp is another free image editing program with a different set of features than Paint.NET. I'll use it sometimes when there's an effect I want to use that the former program doesn't do well, like transforms or motion blur.

Enabling file extensions will show the hidden part of the filename that tells your operating system what kind of file it is. In Windows 10, this can be done by clicking the "View" tab in File Explorer and checking "File Name Extensions" in the "Show/hide" section.

So instead of the file will show up as
Revealing this makes it easier to find problems with incorrect file types as well as change some, such as a TXT file to a JSON.


Mod files should be in "Steam/steamapps/common/100 Orange Juice/mods". If you were making a mod called "My Amazing Mod", your file structure should look like the diagram below. You don't have to include folders that wouldn't have any files in them.


For voice_cha_unitcode and voice_sys_unitcode, replace "unitcode" with the asset code of the unit who's lines you are replacing. Each character will need their own folders. If any of these folders don't have any files in your mod, you don't have to include them.


One common mistake is to create this file as a TXT, then forget to change it to a JSON.
We'll go more into fixing JSON code in the next section.

If the name of your mod in your JSON file is not unique among your installed mods, this will cause only one of them to be loaded.




The preview image for your mod file needs to be:

• In a 16:9 aspect ratio
  
• In PNG format
  
• Under 1MB in size

If any of these conditions aren't met, your mod may not load.


Just about anything in this game that you can replace has a special ID tied to it. While many assets have the same ID as the name of the thing they represent, many have abbreviated or different internal names. These two guides have lists of all the asset ID.
https://steamproxy.net/sharedfiles/filedetails/?id=2189405817
https://steamproxy.net/sharedfiles/filedetails/?id=2234774298

As mentioned in Sora's modding guide, you can use a JSON formatter like the one linked below to check your JSON file for errors. A JSON formatter is a great tool for finding missing commas or brackets. It's still up to you to fix the errors and misspelled words though.

https://jsonformatter.curiousconcept.com/

Double check to make sure that you have named all the parts of your file correctly. These mistakes will not show up in a JSON formatter unless they cause an error, so they can be a pain to find. One thing that can help is to compare your JSON file to one from a working mod can help you find spelling mistakes and incorrect syntax.


Double quotes ( " ) are used to indicate that a set of characters should be packaged together as a string. There are a number of characters that will cause problems when used incorrectly in a string due to having other uses. For example, while you meant this to be read as a quote on a card the JSON formatter will see this instead and throw an error. The reason for this is that while you wanted a quote, the JSON formatter reads your quotation marks as the end and beginning of a new string. in order to use a double quote in a string, you will have to use a string break.

By typing a backslash ( \ ), you are telling the formatter to use a character in a way that it couldn't normally. In order to display this quote correctly, we should use this line of code.
Here are a few relevant examples of characters that need a string break:

For the most part, sprites need to have the following properties:

• Be in PNG format.
  
• Be 256 x 256 pixels.
  
• While not required, a transparent background looks a lot nicer.

To replace a card's art, you actually need two versions of the image. In addition to the 256 x 256 version of your image, you will need a 128 x 128 version of the image. This can be easily done by resizing your 256 sized image in an image editing program and saving it as a new file. Remember, this includes unit cards!

For example, if you were going to replace the art for Dangerous Pudding, you would need the following in your cards folder:

• A 256 x 256 png file named danger256.png
  
• A 128 x 128 png file named danger128.png

If you notice bits of your character being cut out when equipping a modded costume, it is likely because you didn't edit the alphamask file. The alphamask files tell the game what parts of the original sprite to cut out so they don't poke out from behind costumes. Don't forget to edit these files if you change a costume or it may not cull properly!



An alphamask file consists of black and white sections that indicate what parts of the sprite should be removed when wearing a cosmetic item. Black sections will be cut out when the sprite is rendered in game while white sections will not be changed. For example, the image above is the alphamask file of the pumpkin head for QP's neutral pose. Notice how her head is blacked out? It would look weird if her hair and ears were sticking out from behind the pumpkin, so that part of the sprite is culled by the alphamask.

Most sound files used for 100% Orange Juice mods need to be in WAV format with a 44100 Hz sample rate. If your files do not meet these specifications, you can convert them using Audacity. Simply drag the sound files into the program, change the sample rate if needed, then export the file as a WAV. The sample rate can be changed in the bottom left corner of the window.




Music files are handled a little differently from the rest of the sound files. They use the OGG format and can be made to loop using instructions in your JSON file. The sample rate remains the same at 44100 Hz though.

If your music is playing but not looping correctly, make sure you have the correct loop point by opening the song in Audacity. Set the cursor to your loop point, then click Select > Region > Cursor to track end. Hold Shift and press Play to play the song in loop mode. Listen to check if the song loops correctly. You may need to trim a bit off the end of the song or move your loop point in order to make it loop seamlessly.

https://steamproxy.net/sharedfiles/filedetails/?id=2189405817 The official modding guide made by Fruitbat Factory.

https://steamproxy.net/sharedfiles/filedetails/?id=2234774298 This guide has a list of all the IDs for cards, units, etc.




Sometimes all you need is a fresh set of eyes to find what is causing your mod to break. Fellow modders may be able to help you with your problems if you ask nicely.

The Modding discussions on the Steam Forums
https://steamproxy.net/app/282800/discussions/3/

Fruitbat Factory Discord (specifically the #100-oj-modding channel)
https://discord.gg/fruitbatfactory

Thanks for reading!

What issues have you run into with your mods? How did you figure them out and fix them?

Let me know if you have any suggestions or if you felt this guide was missing something.

Sprites: 100% Orange Juice Wiki[100orangejuice.gamepedia.com]

Pudding: Wikipedia[en.wikipedia.org]

Click here for more OJ guides!