Jump to content

Mod Loader/Reference/Story fields

From Threadbox

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, or null if 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 an IDisposable. 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.

Back to the Mod Loader guide