Mod Loader/Reference/Story fields
Story packs add clients, conversations, and commissions through mod.json. For a working pack, see Make a story pack and Rose and Aster starter ZIP.
Manifest
| Top-level field | Contents |
|---|---|
id
|
Stable pack ID. The loader prefixes client, conversation, and commission IDs with it. |
clients
|
Client definitions. Each needs a unique local ID, display name, and native base character. |
storyDialogues
|
One-time conversations attached to a client. |
commissions
|
Commission definitions attached to a client. |
yarnFiles
|
Optional list of .yarn dialogue files inside the pack. Each file must be under 1 MB.
|
Keep the pack ID and definition IDs unchanged when updating a released pack. Saves use the resulting full IDs to remember clients, conversations, and quests.
Clients
| Field | Required | Meaning |
|---|---|---|
id
|
Yes | Local ID, such as aster.
|
name
|
Yes | Name shown in the game. |
baseCharacter
|
Yes | Native character ID to copy. Find IDs in story-reference.json.
|
shape
|
No | Optional body sliders: bust, waist, and hips, each from 0 to 1. These are slider values, not centimetres. If omitted, the base character's measurements are copied.
|
portrait, happyPortrait, sadPortrait, postcard
|
No | Pack-relative PNG or JPG images. Missing images fall back to the base character's portrait; missing happy, sad, or postcard images fall back to the client's regular portrait. |
expressions
|
No | Object mapping up to 32 expression names to pack-relative PNG or JPG images. Names start with a letter and then use letters, numbers, or underscores (up to 32 characters). Use <<set_mod_portrait name>> in Yarn to show one for the current client. Each named image must exist.
|
Story dialogues
| Field | Required | Meaning |
|---|---|---|
id
|
Yes | Local scene ID. |
client
|
Yes | Native character ID or a client ID from this or another pack. |
availability
|
No | Conditions that must be met before the conversation can play. |
lines
|
No | List of one-line Yarn dialogue entries. A scene is remembered after it plays. If omitted or empty, the loader supplies a short default line. |
Commissions
| Field | Required | Meaning |
|---|---|---|
id
|
Yes | Local commission ID. |
name
|
Yes | Job name shown in the game. |
client
|
Yes | Native character ID or custom client ID. |
summary
|
No | Job description. If omitted, the commission name is used. |
budget
|
No | Integer reward from 0 to 1,000,000. Defaults to 100. |
delivery
|
No | visit for a front-desk visit or pigeon for the pigeon list. Defaults to visit. Pigeon jobs require that feature to be unlocked in the game.
|
requirements
|
No | List of dress rules the finished commission must meet. See Requirement types. |
availability
|
No | Conditions for offering the commission. |
measurementsCm
|
No | With Mod Loader 0.6.64 or newer, sets target bust, waist, and hips measurements in centimetres. The loader matches the client's body to these values for the measuring scene. The mannequin still begins at its usual size for the player to adjust. |
dialogue
|
No | Optional prompt and outcome lines. |
repeatGroup
|
No | Groups this as a repeatable visit commission. Repeat groups currently require at least one tag requirement using AtLeast, and only visit delivery is supported.
|
For a job-specific body size, include all three measurement values:
"measurementsCm": {
"bust": 106.68,
"waist": 84.02,
"hips": 101.44
}
Each value must be within the game's mannequin measurement range. If this field is absent, the client uses their regular body measurements; a custom client's shape sets those defaults.
Availability
| Field | Meaning |
|---|---|
afterStory
|
Wait until the main story is complete. |
minimumLevel
|
Minimum player level, from 0 to 50. |
minimumRelationship
|
Minimum relationship value, from 0 to 5. |
afterQuests
|
Quest IDs that must have succeeded. |
afterDialogues
|
Conversation IDs that must have played. |
Every condition in an availability object must be true. Use local IDs for your own definitions; use a full pack ID and item ID to refer to another pack. Native quest IDs are also accepted. An unavailable or misspelled dependency is logged and prevents the dependent content from loading.
Requirement types
Each rule has a type. Values that need a tag, color, fabric, accessory, or garment also need the matching field shown below. Names and IDs are listed in fabric-reference.json, accessory-reference.json, garment-reference.json, and story-reference.json.
type
|
Fields | What it checks |
|---|---|---|
tag
|
tag, value
|
Tag score. comparison can be AtLeast, Exactly, or AtMost; default is AtLeast.
|
quality
|
value
|
Dress quality, using the selected comparison. |
fabric
|
fabricType
|
A type name or an array of allowed type names. Every cut panel must use one of these types; any mixture is allowed. |
fabricPercentage
|
fabricType, value
|
At least the given percentage of the dress must use one fabric type. Value is 0 to 100; multiple types are not supported here. |
color
|
color or colors
|
Restricts the dress to one color or an allowed list. With colors, every cut panel must use a listed color.
|
colorPercentage
|
color, value
|
At least the given percentage must use this color. Value is 0 to 100. |
accessoryCount
|
accessoryType, value
|
Minimum number of accessories of this type. Value must be a whole number. |
trimLength
|
accessoryType, value
|
Minimum trim length in centimetres. Value must be a whole number. |
accessoryVariety
|
value
|
Minimum number of distinct accessories. Value must be a whole number. |
colorVariety
|
value
|
Minimum number of distinct colors. Value must be a whole number. |
fabricVariety
|
value
|
Minimum number of distinct fabrics. Value must be a whole number. |
garment
|
garment
|
Requires an exact garment component ID. |
Allow more than one fabric type
A fabric rule accepts either a single name or an array in fabricType. For example, this commission allows only lace and silk:
"requirements": [
{ "type": "fabric", "fabricType": ["Lace", "Silk"] }
]
Every cut panel must use a listed type. Lace alone, silk alone, or any mixture of the two passes this rule. It does not require both types, and it does not restrict colours. Use a color rule with colors to limit colours separately.
To require both types, add a minimum percentage for each. This example allows only lace and silk and requires at least 20% of each:
"requirements": [
{ "type": "fabric", "fabricType": ["Lace", "Silk"] },
{ "type": "fabricPercentage", "fabricType": "Lace", "value": 20 },
{ "type": "fabricPercentage", "fabricType": "Silk", "value": 20 }
]
Each fabricPercentage rule takes one type, not an array of multiple types. Keep the combined minimum percentages at or below 100 so the dress can meet them.
A single name, such as "fabricType": "Lace", still works. Use the full registered ID for custom types, such as stylesexpanded.Leather. Empty lists and unknown types are rejected. Keep the field name fabricType even when using an array.
Combine colour and tag requirements
Percentages must be from 0 to 100. Count values must be whole numbers. For example, require Daywear and Simple tag scores while limiting panels to red or black and requiring some of each:
"requirements": [
{ "type": "tag", "tag": "Daywear", "value": 50 },
{ "type": "tag", "tag": "Simple", "value": 25 },
{ "type": "color", "colors": ["Red", "Black"] },
{ "type": "colorPercentage", "color": "Red", "value": 10 },
{ "type": "colorPercentage", "color": "Black", "value": 10 }
]
When using a two-color palette, the color rule blocks other colors; the percentage rules make both listed colors mandatory.
Dialogue fields
Short scenes use lines. A commission's dialogue can contain these line lists:
| Field | Used when |
|---|---|
prompt
|
The player receives the commission. |
complete
|
The commission is completed. |
failed
|
The result does not meet the requirements. |
excelled
|
The result exceeds the commission requirements. If omitted, complete lines are used.
|
Each entry must be one line. Yarn commands and indented choices work in these lines. Missing commission dialogue gets a short default reply.
For longer scenes and choices, put a .yarn file in the pack and list it in yarnFiles. No separate compile step is needed. The loader uses the game's Yarn compiler. A matching node in the Yarn file replaces the simple dialogue node.
Node titles start with Mod_; dots and hyphens in the pack ID become underscores. Commission node names use the full commission ID plus _Prompt, _Complete, _Failed, or _Excelled. A story dialogue uses its full ID. Example:
title: Mod_example_story_starter_rose_daywear_Prompt
---
Could you make me something simple for the daytime? #line:example_story_rose_1
-> Something comfortable? #line:example_story_rose_choice_1
Exactly. A quiet day at home. #line:example_story_rose_reply_1
===
Give custom #line: IDs unique names. Yarn variables work during a conversation, but do not rely on arbitrary Yarn variables being saved between sessions. Use afterQuests and afterDialogues to gate story progress.
Named client expressions use <<set_mod_portrait surprised>>. This looks up surprised on the character currently speaking and calls the game's portrait presenter. An unknown name leaves the current portrait in place and logs a warning. Dressmaker's existing <<set_portrait_neutral>>, <<set_portrait_happy>>, and <<set_portrait_sad>> commands still work.
Removing a story pack
The loader keeps a local story cache so client and quest references in existing saves can still be read. Removed packs stop offering new work; an accepted job can still use retained dialogue. Restore a save backup to undo story progress.
When content does not load
Read BepInEx/LogOutput.log. The loader logs a skipped client, conversation, or commission and the field or ID that caused the error. story-reference.json lists native clients, quests, colors, and outcomes.
Friendship reward fields
Put friendshipRewards inside a client definition. It is an optional array with at most five entries, one per level. See the story pack example.
| Field | Value |
|---|---|
level
|
Required integer from 1 to 5. |
garments
|
Required array of 1 to 64 garment IDs. Local IDs are checked in the same pack first, then full mod or native IDs. Unknown IDs are reported as loading problems; none of that client's reward entries are registered. |
Register a reward in C#
Use FriendshipRewardApi from DressmakerMods. This works with native and modded clients. Your plugin needs a BepInEx dependency on yuu.dressmaker.mods; see writing a C# mod for project setup. The example also uses System.Collections.Generic.
Wait until content is ready before looking up a client. This example adds a reward to the Aster pack in the story guide; normally you would use either its JSON reward or this registration.
private ModContext mod;
private void Awake()
{
mod = ModLoaderApi.Register(this);
FriendshipRewardApi.WhenReady(mod, () =>
{
var client = FriendshipRewardApi.FindClient("aster-patterns.aster");
FriendshipRewardApi.Register(mod, "aster-gift", client,
new ModFriendshipReward
{
Level = 2,
Garments = new List<string> { "aster-patterns.gift-bodice" }
});
});
}
private void OnDestroy()
{
mod?.Dispose();
}
FindClient(string id)returns the character, ornullif it isn't loaded. Modded clients use their full ID.WhenReady(ModContext owner, Action callback)runs after startup content loads. If it has already loaded, the callback runs immediately. The returned subscription can be disposed.Register(ModContext owner, string localId, CharacterDefinition client, ModFriendshipReward reward)returns anIDisposable. Give each reward a unique ID within your plugin. Disposing it stops future rewards without removing earned patterns. Disposing the context removes all its registrations.
Call these methods on Unity's main thread. Registration checks the client, level and garment IDs, and grants the reward immediately if the loaded save already has enough friendship.
Register new garments with ModGarmentDefinition.UnlockByDefault = false. For a garment you created through the runtime API, call GarmentModApi.SetAutoUnlock(component, false) immediately after creation. Reward registration doesn't change the garment's default availability. SetAutoUnlock only accepts modded garments and doesn't revoke patterns already earned.