When we want to add new NPC as a companion, we have to define it in dispositions file. It's very important to define our NPC when we wants to be supported as companion in mod.
To add new NPC companion via content pack create file companions/<YourNpcName>.json where <YourNpcName> is a name of your NPC you wish add as a companion in the game. This NPC must be a valid villager vanilla or custom NPC. present in SDV's content asset Data/NPCDispositions. If you are add custom NPC as a companion be sure a mod (usually via Content Patcher) which adds your NPC registers it into that SDV content asset.
If you are NPC Adventures contributor and do you want add or edit native companion, look for <modSource>/assets/companions/<npcName>.json. If this file for your desired NPC doesn't exists, create it.
NPC Adventures mod looks for JSON files in <modFolder>/assets/companions/<npcName>.json and in <contentPackFolder>/companions/<YourNpcName>.json and loads companions from each present JSON file.
Each JSON disposition file represents data for single NPC companion.
Companion definition
| Field | Type | Default value | Description |
|---|---|---|---|
| Format | <major>.<minor> | REQUIRED! Disposition file format version. This field can be omitted for mod's native companions. | |
| Name | string | REQUIRED! A name of your companion mathing a key in SDV's Data/NPCDispositions. | |
| Description | string | Translatable Description of your companion. | |
| Skills | CompanionSkill[] | Skills assigned to a companion. | |
| Rules | {[string]: string} | Rules by which companion makes a decission if they accept or reject farmer's adventure offer. NPC adventure suggestions are driven by these rules too. If no rule is defined or matched, adventure request is rejected. | |
| UnlockMail | string | na_invitation | Unlock this companion for a farmer's adventure ask by a mail flag in player's received mails list. If companion is locked, farmer can't ask them for an adventure and your companion acts like non-companion NPC until it's unlocked by specified mail flags. You can specify more mail flags separated by ,. All defined mail flags are required for a farmer to unlock this companion. |
| CanSuggest | boolean | true | Can this companion suggest an adventure to farmer? |
| Bedtime | integer | 2200 | The time when companion always rejects the adventure or auto-dismiss when it's on an adventure with farmer due to it's too late. The number is a time 24-hour digit format hhmm without delimiter in range 600 - 2600 like 2200 for 10 pm or 2600 for 2am. More info |
| BedtimeSpouse | integer | 2400 | Same as Bedtime but it is valid for married spouse companion. |
| Price | integer | 0 | How much costs recruit of this companion. This field is valid for Freelancers. |
| Sales | {[string]: float} | Recruitment price sales rules. This field is valid for Freelancers. | |
| Buffs | BuffsData | Buffs which are granted to farmer while adventure with this companion. | |
| BuffsDescription | string | Translatable Default text description for player of assigned buffs granted by this companion. | |
| ProstheticBuffs | BuffsData[] | Changeable buffs granted by this companion. | |
| Weapons | {[integer]: string} | Weapons defined for each combat level. If no weapons are defined, companion uses their fists to fight. This field is valid for companions with fighter or warrior skill. | |
| IdleBehaviors | IdleBehaviorData[] | Idle behavior definitions. | |
| EnableWithMod | string | Enable this companion only when mod with defined UID here is loaded. Doesn't support more mod UIDs. Always enabled when both fields EnableWithMod and DisableWithMod are null or empty. | |
| DisableWithMod | string | Disable this companion only when mod with defined UID here is loaded. Doesn't support more mod UIDs. Always enabled when both fields EnableWithMod and DisableWithMod are null or empty. |
Native companions added by the NPC Adventures mod itself doesn't require field Format
which is mandatory for companions defined by content packs.
Native companion disposition files are always on latest format version.
Example
{
"Format": "2.0", // Don't forget define format version if you add companion via content pack
"Name": "Abigail",
"Skills": [
{ "Name": "warrior" }
],
"Rules": {
"f Abigail 1250": "accept"
},
"Buffs": {
"Attack": 1,
"Luck": 1,
"Speed": 1
},
"BuffsDescription": "[abigail.buffs]",
"Weapons": {
"0": "Abby's Planchette", // 1-3
"1": "Steel Smallsword", // 4-8
"2": "Pirate's Sword", // 8-14
"3": "Cutlass", // 9-17
"4": "Forest Sword", // 8-18
"5": "Iron Edge", // 12-25
"6": "Holy Blade", // 18-24
"7": "Bone Sword", // 20-30
"8": "Tempered Broadsword", // 29-44
"9": "Obsidian Edge", // 30-45
"10": "Lava Katana" // 55-64
},
"IdleBehaviors": [
{
"Behavior": "Animate",
"Animations": [
"abigail_sit_ground",
"abigail_flute"
],
"Tendency": 5,
"MinDuration": 10,
"MaxDuration": 30
},
{
"Behavior": "Lookaround",
"FaceMinSeconds": 2,
"FaceMaxSeconds": 5,
"Tendency": 2,
"MinDuration": 10,
"MaxDuration": 30
}
]
}
Translatable strings
Some strings are translatable. In docs this kind of strings are marked with Translatable badge which says you can use i18n translation key. The translation key is wrapped with [ and ] without any character outside. Between these parentheses are the i18n translation key which refers a string with translated text. Translations are provided i18n translation system in SMAPI.
For example: [buffs.abigail] refers translation key buffs.abigail in i18n/default.json and its coresponding locale file by current game localization (like i18n/pt.json for Portuguese localization). The localization is fetched from i18n/ folder in mod folder (if the companion is defined by NPC Adventures itself) or the coresponding content pack which adds this companion.
You can reference contextual translations embedded in your content pack which adds your companion only.
It's impossible reference translations from another content packs or from NPC Adventures mod folder. This is valid for native mod companions too, so you can't reference translations in content packs from mod's native companion disposition file.
Bedtime format
The mod uses the same time format hhmm for their bedtimes as is used in event preconditions with allowed range 600 - 2600. If you want to define midnight (12pm) and after, use 2400 (12pm), 2500 (1am) and 2600 (2am).