100% Orange Juice | Modding Documentation

Overview

A documentation on how to use, install, and create mods for 100% Orange Juice.

Welcome!

Welcome to this brand new guide which will guide you through the process of the installation and creation of various mods for 100% Orange Juice.

If at any time you have questions, you can refer in our Discord modding channel[discord.com], in the Workshop forum, or in this guide comment section.

You can get started at the section: First time preparations & Tips.

Check out mods on the Steam Workshop here: [link]

Legal Notice

Game resources described in these instructions may only be extracted and used outside of the game itself for the exclusive purpose of generating custom graphic mods for the game 100% Orange Juice. They cannot be used for any other purpose, or in any way that demeans the game or the characters, or hurts the rights of the copyright holder. It is the responsibility of all mod creators to obey local laws and respect trademarks.

Fruitbat Factory, Ltd. may announce further restrictions to the way these game resources may be used, or revoke the right to use these resources to create mods at will by posting an announcement about it on Twitter, Discord, Steam or other public venue and encrypting the listed graphic archives.

Before making any mod public, it is the responsibility of the creator to refer to the latest version of this document to make sure their mod is compatible with the current mod guidelines and use limitations.

Limitations

Unit and card textures alongside BGM, voices, and sound effect can currently be modified.

Textures are located in units, alphamasks, hats, hairs, and cards game packages. (Note: You can open those with any archiver software (7-Zip, WinRAR, WinZIP …).

Important notice: only files that are provided in unencrypted archives can be modified for the purposes of modding. In particular voice files can be replaced with custom voiceovers, but existing voice files may not be modified or reused in any way.

The result can be seen in the Config screen, in the newly added Mods tab.

System Version

Guide Updates

Here you can see the changes to the guide.

===============================

First time preparations & Tips

Before jumping into making your mods, there is a few things you need to know.

A “mods” folder at the location of 100% Orange Juice’s executable is where you will put all your locally saved mods. You can find it by going in your Steam Library > Right clicking 100% Orange Juice > Properties > Local Files > Browse Local Files, then by moving to the “mods” folder.

To begin, create a new folder in “mods”. Give it any name. This is where you will place your assets.

The modding system is all about replacements. You can extract our game packages that contains textures by navigating to the “data” folder in the game directory. From there you can open the following PAK files with any software capable to open archives:

• alphamasks
• cards
• hats
• hairs
• units

You can extract their content somewhere on your computer to make it easier for you to search and browse through our assets.

As your mod need to point to a path that the game expects it, you must have a proper structure for your mod.

Your mod should be having this structure, if you want to replace the textures for Suguri for example:

Make up your mod definition

The mod definition file is how you will tell the game about what your mod should do and replace.
To begin, go to your mod folder, and create a new file named “mod”. Make sure that the file extension is JSON.

Here’s below an example you can use.

You can also checkout hexundev’s mod generator: [link]

To see the legacy way of making mod definitions, please refer to its dedicated section. But keep in mind it is recommended to stick with the new format!

The following guide sections will cover the explanation of the different modules you can use.

Mod Definition Section

Mod Replacements Section

Note: Each replacements now have their own subsection. You will need a different array of data for textures and sounds for example.

You can combine multiple subsections in a single mod.

The following sections in this guide will bring more details about them.

Textures

The texture replacement array only require strings to the replaced paths.
This currently include:

• alphamasks
• hats
• hairs
• units
• cards
• field

Textures must be using the PNG format and have the same dimensions as the original texture.

To replace a texture in the game, you must place your file in your mod where it originally appear in the game files. For example, the texture for the neutral pose of Nico is located in units/nico_00_00.png. You must place your replacement in your mod at the same path in your mod folder, like this: 100 Orange Juice/mods/my mod for nico/units/nico_00_00.png.

Unit related texture size : 256×256
Card artwork texture sizes: 256×256 & 128×128 (need two versions.)
Homestop texture size: 256×256
Panel texture size: 128×128

The game will now handle simple paths as a complete set. This means you do not need to add paths for all poses in a specific color, accessory, hair, ect. in your mod definition file.

Example:

For the game, all poses of Cuties default color & color 1 has been included in only 2 lines instead of 12.

Panel textures are an exception, since they are not part of a set. You can still use this method for them though.

For cards, it will also include automatically the 128 & 256 texture variant. Only the ID is necessary here. If you wish to add a custom name and flavor text, see advanced textures below. (Note: For cards, you only need to define it once, even if it is an advanced texture. It’s not the case for unit related textures.)

If you need to only include single files, and not enjoy the pleasure of auto-filling, you can rely on advanced textures with a special parameter. See below.

Advanced textures can have special parameters, such as Face Coordinates for units, or Custom Names & Flavor text for cards.
Face coordinates will change how a texture is centered when taking up the face of a unit. The most obvious example would be the in-game HUD.

Face coordinates must be a position X & Y on the center of your unit’s face.

On the example above, my coordinates would be X116, Y129.

In our JSON file, it would look like this:

Costumes have their own coordinates. You can define a costume by their number identifier.
See the section about costumes to know which one is which.

This will add the coordinates X116 Y129 to Suguri Summer’s costume idle pose.

Advanced textures can be used alongside regular textures in one go just fine. So don’t hesitate to mix them as you need.

Only unit textures and card textures can be treated as Advanced textures. Hairs, accessories ect do not need it. You can simply define them for the default color, and set regular path for the unit color options.

Example:

Note about Kiriko Miko costume
As the naming it uses is unique, you can only rely on using advanced textures with the “single_file” parameter.

Music

The music replacement array require a few parameters described below.
Music must use the OGG format.

Example:

Events can be defined to affect a music to a specific place. You cannot have both a event and a unit_id defined in a single entry, however. If a unit_id is specified with an event, the unit_id parameter will be prioritized.

The list of events can be found below.

Example:

The lobby music will be replaced that way.

Voices

Voice replacement mods require either of these 2 parameters, depending on which types of voices you want replaced:

• character: Array of paths that files to replace character voices will be attempted to be loaded from.
• system: Array of paths that files to replace announcer voices will be attempted to be loaded from.

Before loading the sound files from the .pak, the game will try to find files in the paths listed here and attempt to load those instead.

Format example:

If you want to only replace Kai’s system voices, it’d look like this:

The files that are meant to be in this folder also have to match with what the game’s expecting. The “Dice roll 1” voice line file is named “0_0.wav” (required filenames listed below), so the sound you want to replace the voice line with must be named the same and be located in the character folder you want to replace the voice of. The same also applies to system voices. For best results, make sure your sound files have a 44100Hz sampling rate.

Here’s a folder structure example of a mod replacing QP’s Dice roll 1 and 4 voice lines, along with her “100% Orange Juice” and “Warp” announcer voices:

For information on how to name the files, check out the Character voice filenames section.

Character Hair Color

The character hair color replacement array will only accept arrays of data.
You have several techniques of hair coloring to choose from:

• texture : Rely on a external texture to draw the hair.
• singlecolor : Define a base, shadow, and additional color to draw the hair.
• gradient : Define a base, secondary, shadow, and additional color to draw the hair.

The module only read the following parameters:

You can also specify an alpha value for your color:
#ff000000 : ARGB (255, 0, 0, 0)
#000000 : XRGB (0, 0, 0) (the alpha is always 255.)

Textures do not need any specific parameter. You’ll need to include your texture in the dedicated module (see the earlier section Textures) by following our naming:

Example:
hairs/sora_00_00 : It will change the hair color 1 of Sora’s idle pose.
hairs/sora_02_00_00 : It will change the hair color 1 of Sora’s Summer costume idle pose.

Note: Even if the hair color file is not present in the official files, you can still define yours to be read by the game. As long the name of the file is the same as what the game is expecting, you’re all set.

JSON example:

The single color technique depends on the base color you’ll define to draw the hair.

JSON example:

The gradient color technique depends on the white & black hair textures to draw the hair. The base color being the black part, and the secondary color being the white part.

JSON example:

The hair textures used when using gradients or single colors are the following:

For Alicianrone (applies to all units)

• hairs/alicianrone_b00_00 (base color)
• hairs/alicianrone_h00_00 (hair highlight)
• hairs/alicianrone_m00_00 (gradient)
• hairs/alicianrone_s00_00 (shadow)

Sound Effects

To add a custom sound simply create an entry in ModReplacements with the name sound_effects. This is a list of the sound effects your mod is replacing. These sounds must be in a folder named sound in your mod’s root directory. For best results, make sure your sound files have a 44100Hz sampling rate.
Below is an example definition in your mod.json file:

This suggests that your mod folder structure should be something like this:

What will this do? This will replace the “Player selects something”, “Player cancels a selection” and “Card get” sound effects with whatever these files are. A list of all the sound effects used is located at the end of the guide, so you can use that for reference whenever you need it.

Custom Languages

The Custom Language array only take one member called “directories”.

Your mod structure should look like this:

You need to put the directory name with all the define files inside your mod folder, and set the name under directories.
You can include multiple languages, and you can mix this module with other ones (textures, music replacements…)

This will add the “french” custom language along all the included font files.
For existing translations, it will only be a matter of moving your folder to a dedicated mod folder and copy pasting the JSON code above.
For new translations, you can refer to the file located here: 100 Orange JuicelanguageCustomLanguages.txt to get started.

===============================

Customized Preview

You can include a customized preview with your mod.
This is a requirement if you wish to publish your mod to the workshop.

Create it at the root of your mod’s directory, named preview.png.

The preview should preferably be following a 16:9 aspect ratio, and use the PNG format. It will automatically be read if the game detects the file, so there is no need to do anything else!

The preview must be less than 1 MB in size to be uploaded to the Workshop.

Submit your mod to the Workshop

In order to send your mod to the Steam Workshop, you must ensure the following conditions are fulfilled:

• Your mod definition file must use the JSON format.
• Your mod must have a valid preview. Jump to the Customized Preview section of this guide for more information.

Once the conditions are met, you can then jump in-game and click the Publish button.

If any error during the upload occurs, a message will show up giving more details.

Once the mod is done uploading, you’ll be redirected to the page of your workshop item, ready to be used for everyone.
Note that all submitted items have their visibility set on public by default.

Contest Participation

In order to participate in our official contests, you’ll need to declare the flag

in the mod definition, alongside the other required parameters.

Doing so, you will have to ship all the assets required in your mod folder.
Once your folder is ready, hop in-game and publish, like any mod.

Note: When no contest are available, or if time ran out, you won’t be able to send or update any item.

Tip: As it is considered a mod, you can treat your entry as it was one and have users subscribe to it so they can have a direct preview of your entry in their game.
Placeholder cards will be added in the in-game binder when a contest is up and running.

Please make sure to include full resolution artworks in the submission folder, even if the mod won’t read them.

===============================

(Legacy) Mod definition

To make your first mod, you need to create a new folder in “mods”, which will be your mod’s name.

Inside this folder, you will need a mod definition file, called mod.txt. The content should follow this format:

This syntax is the same as a localization define file.
Make sure the encoding of this file is UTF-8.

Here’s a quick recap of what those values means:

*Those values must be added in your mod.txt. If they are missing or having bad data, your mod might not be loaded by the game.

===============================

Avoid JSON errors!

In order to be loaded, you must make sure your JSON file can be fully parsed. If there is any error, the game will not load your mod.

You can use the following website to check your data:

It will as well highlight the potential issues if there is any.

Alphamask Helper

In order to make the modding process more easy for you, here below are a few helpers to figure out for example what file is what, due to our naming using identifiers.

Unit IDs

You can find below our internal names for units.

Card IDs

You can lookout for the great guide written by Zomoroko:
[link]

Character voice filenames

This list is to help with naming sound files for replacing character voices. Use the prefix with an underscore and then the variation of the line (starting the count from 0) to name the file, you can use the in-game Gallery section for help.
For example: Replacing Warp 3 would need a file named 10_2.wav and replacing Drop panels 4 would need a file named 21_3.wav

It’s important to note that entries marked with * only have one variation, and replacing subsequent lines require changing the prefix. For example: The sound replacement for Special Line 3 needs to be named 52_0.wav.

System voice filenames

Below is the list of system/announcer voice sound files that can be replaced. Just name the sound file you want to use accordingly.

Costumes IDs

You can find below the costumes identifiers.

Sound effect filenames

Below are the sound filenames the game attempts to load along with a brief description of where they’re used in-game. Just add one to your mod’s sound folder under any of the filenames of the sound you want to replace.