Give Feedback
SPID: The Complete Reference
as of SPID 7.0.0
Everything you need to know to start creating SPID mods.
Changelog
Spoiler:
Show
- 17.04.24
- Removed section about special Outfits ordering. The reverse ordering was removed in SPID 6.5.0
Table of Contents
Spoiler:
Show
- General Distribution Info
- How does SPID load configs?
- When distribution happens?
- In what order forms are distributed?
- Syntax
- Form Type
- Type Inferring
- Distributable Form
- Filtering
- String Filters
- Supported Strings
- String Expression Modifiers
- Form Filters
- Supported Filterable Forms
- Form Expression Modifiers
- Level Filters
- Supported Values
- Ranges Syntax
- Leveled Distribution
- Traits Filters
- Supported Traits
- Trait Expression Modifier
- Note on Templated NPCs
- Count or Package Index
- Item Count
- Package Index
- Package List Type
- Chance
General Distribution Info
SPID distributes all configured forms at runtime, it doesn't have effect on either loaded plugins nor on save. SPID distributes everything from scratch each time you launch the game. You can think of SPID distribution as a "virtual plugin" that applies changes last in your load order. This makes any SPID-based mods safe to install/uninstall at any time, as they don't leave a trace.
- How does SPID load configs? (Order)
- At startup SPID looks into Skyrim's Data/ folder and finds all ini files that have a _DISTR suffix in their name.
- Then it orders them alphabetically from A to Z and loads in that order.
- Each file is read from top to bottom, preserving relative order of each type of forms (this order is used later during distribution. (each type of forms is guaranteed to be distributed in the same order as they appear in the file as well as the global order of files).
- When Distribution happens?
Distribution of forms is split into two steps:
- Persistent static (not scaling with Player's level) NPCs are distributed to on Main Menu load.
- Dynamic leveled NPCs are distributed to as they are loaded in the world (typically, on cell load).
- In what order forms are distributed?
SPID distribution processes forms of each type separately.
The exact order at which form types are processed is:
Spoiler:
Show
- Keywords
- Factions
- Spells
- Perks
- Shouts
- Packages
- Outfits
- Items
- Skins
Within each type forms are distributed in the same order that they were loaded with a few exceptions:
- Keywords are additionally sorted to make sure that keywords that depend on other keywords will be distributed later than their dependencies. This allows you to freely use keywords as requirements for other keywords without manually ordering them.
Syntax
General syntax for a distributable form looks like this:
FormType = FormOrEditorID|StringFilters|FormFilters|LevelFilters|TraitFilters|CountOrPackageIndex|Chance
required required optional optional optional optional optional optional Default: Index=0; Count=1 Default: 100
Optional sections can be either left blank or marked as NONE.
Example:
Spoiler:
Show
So both
Item = MyItem|||||5
and Item = MyItem|NONE|NONE|NONE|NONE|5
are valid.Form Type
Type of a distributable form that you want to configure.
Here is a list of all supported Distributable Forms that you can specify in FormType:
Form type Signature
- Spell [SPEL, LVSP]
- Perk [PERK]
- Item [ALCH, AMMO, ARMO, BOOK, INGR, KEYM, LVLI, MISC, SCRL, SLGM, WEAP]*
- Shout [SHOU]
- Package [PACK, FLST*]
- Keyword* [KYWD]
- Outfit [OTFT]
- SleepOutfit [OTFT]
- Faction [FACT]
- Skin [ARMO]
* When distributing FormList it must contain only Packages, otherwise game most likely will crash.
* SPID can also create Keywords dynamically, so you can distribute custom keywords.
Example:
Spoiler:
Show
This will create a new keyword and distribute it to NPCs
Keyword = MyVerySpecialKeyword
Type Inferring
You can also specify Form as a generic Form Type and let SPID work out proper Form Type based on provided Distributable Form.
IMPORTANT
Keep in mind that SleepOutfit and Skin can't be inferred,
because they use the same forms as Outfit and Item respectively, so the latter will always be detected first.
Example:Spoiler:ShowForm = SteelSwordis the same as
Form = DefaultOutfitItem = SteelSword
Outfit = DefaultOutfit
Distributable Form
A unique identifier of the Form to be distributed.
Form must be one of the supported types listed in Form Type section.
A form can be identified by using one of the following IDs:
- FormID - a hexadecimal number (0x12345) with a plugin name as a suffix (e.g 0x12345~MyPlugin.esp). Read FormIDs and You for more details on how this ID is formed.
- EditorID - a text identifier of the Form as seen in Creation Kit or xEdit. (e.g. ElvenMace or ImperialBow).
Generally, EditorID is considered to be a more stable way of referencing a Form since, unlike FormID, it will remain the same when the mod is merged, converted to esl or compacted.
Filtering
Distributable Form can be restricted to a group of NPCs that match specific criteria. These criteria are configured by a handful of filtering sections, that we'll talk about in a moment.
All Filters sections are multiplicative (combined using logical AND operation), while expressions within the same section are additive (combined using logical OR operation).
Example:
Spoiler:
Show
So the entry
can be read as "give a form 0x12345 when NPC has (A OR B) AND (0x12 OR 0x34)".
Form = 0x12345|A,B|0x12,0x34can be read as "give a form 0x12345 when NPC has (A OR B) AND (0x12 OR 0x34)".
TIP
Use multiple entries for the same distributable forms to target different groups of NPCs.
Example:Spoiler:ShowKeyword = FemaleBandits||BanditFaction||Fwill give the keyword only to NPCs that are both Female AND part of Bandit Faction. ButKeyword = FemaleOrBandits||BanditFactionwill give the keyword to all members of Bandit Faction as well as all Females in the game.
Keyword = FemaleOrBandits||||F
String Filters
A list of comma-separated textual expressions that allows you to filter eligible NPCs by their textual properties, such as a name.
Form = 0x12345|StringExpression1,StringExpression2,...
Supported Strings
String Filters allow you to match NPCs by the following criteria:
- NPC's Name (e.g. Balgruuf).
- NPC's EditorID (e.g. BalgruufTheGreater).
- NPC Templates* EditorID. This allows you to target all descendants of a template.
- NPC's Keywords (e.g. ActorTypeNPC). This also includes Keywords distributed by SPID.
- NPC Race's Keywords (e.g. ActorTypeAnimal).
Example:
Spoiler:
Show
Give a form to all Whiterun Guards
Give a form to NPC with ActorTypeNPC OR ActorTypeDragon
Form = 0x12345|Whiterun GuardGive a form to NPC with ActorTypeNPC OR ActorTypeDragon
Form = 0x12345|ActorTypeNPC,ActorTypeDragonString Expression Modifiers
By default, String Expression looks for the exact match of the specified term, but this behavior can be changed with several modifiers.
- Exclusion modifier (-). Placed in front of a term. This will invert the expression and make it only match NPCs who does NOT have the exact term.
Spoiler:
Show
Give a form to every NPC except specifically "Balgruuf" (so "Balgruuf Junior" would still be allowed)
Form = 0x12345|-Balgruuf- Partial match modifier (*). Placed in front of a term. This will make the expression allow partial matches of the term. (e.g. "Guard" in "Whiterun Guard")
Spoiler:
Show
Give form to every guard, this will match all "Whiterun Guard", "Falkreath Guard", "Markarth Guard", etc. Note that this will also match NPCs like "Guardian" or "Bodyguard".
Form = 0x12345|*Guard
- Combining modifier (+). Placed between multiple terms you want to combine. This will make the expression only match NPCs who have ALL of the exact terms.
Spoiler:
Show
Give a form to NPCs who are simultaneously ActorTypeNPC, Bandit and ActorTypeGhost
Form = 0x12345|ActorTypeNPC+Bandit+ActorTypeGhostIMPORTANT
Only one modifier can be used in a single expression.
Example:Spoiler:ShowNone of these are valid:Form = 0x12345|-*Guard
Form = 0x12345|-Guard+ActorTypeNPC
Form = 0x12345|ActorTypeNPC-Guard
Form = 0x12345|*Guard+ActoryTypeNPC
Form Filters
A list of comma-separated expressions containing FormOrEditorIDs that allows you to filter eligible NPCs by their form properties, such as Race, Class, etc.
Form = 0x12345||FormExpression1,FormExpression2,...Supported Filterable Forms
Form Filters allow you to match NPCs by the following criteria:
Form type Signature NPC's Record in xEdit
- Combat Style[CSTY] ZNAM - Combat Style
- Class [CLAS] CNAM - Class
- Faction [FACT] Factions
- Race [RACE] RNAM - Race
- Outfit [OTFT] DOFT - Default outfit
- Specific NPC [NPC_] FormID, EDID - Editor ID
- NPC's Template* [NPC_] FormID, EDID - Editor ID
- Voice Type [VTYP] VTCK - Voice
- Known Spell [SPEL] Actor Effects
- Skin [ARMO] WNAM - Worn Armor
- Editor Location* [LCTN] XLCN - Persistent Location (of ActorRef)
- FormList* [FLST] Recursively looks for any form from the list.
* This is the location where NPC is placed in the Editor, NOT the location where NPC is right now.
* List can contain any of the forms from this table, including another nested FormList.
Example:
Spoiler:
Show
Give a form to all Nords (NordRace "Nord" [RACE:00013746])
Give a form to NPCs that are located in Whiterun (WhiterunLocation "Whiterun" [LCTN:00018A56]) OR report crimes in Whiterun Hold (CrimeFactionWhiterun "Whiterun" [FACT:000267EA]).
Form = 0x12345||NordRace
Give a form to NPCs that are located in Whiterun (WhiterunLocation "Whiterun" [LCTN:00018A56]) OR report crimes in Whiterun Hold (CrimeFactionWhiterun "Whiterun" [FACT:000267EA]).
Form = 0x12345||WhiterunLocation,CrimeFactionWhiterunAdditionally, here you can specify only name of the plugin where NPC is defined. This will match only NPCs from given plugin.
Example:
Spoiler:
Show
Give a form only to NPCs from CoolNPCs.esp plugin
Form = 0x12345||CoolNPCs.espForm Expression Modifiers
By default, Form Expression checks whether an NPC has the specified form, but this behavior can be changed with several modifiers.
- Exclusion modifier (-). Placed in front of a form. This will invert the expression and make it only match NPCs who does NOT have the form.
Spoiler:
Show
Give a form to every NPC except Nords (NordRace "Nord" [RACE:00013746])
Form = 0x12345||-NordRace
- Combining modifier (+). Placed between multiple forms you want to combine. This will make the expression only match NPCs who have ALL of the forms.
Spoiler:
Show
Give a form to NPCs who are simultaneously Nords (NordRace "Nord" [RACE:00013746]), Report Crime in Whiterun (CrimeFactionWhiterun "Whiterun" [FACT:000267EA]) and know Stoneflesh spell (StonefleshLeftHand "Stoneflesh" [SPEL:00072316])
Form = 0x12345||NordRace+CrimeFactionWhiterun+StonefleshLeftHand
IMPORTANT
Only one modifier can be used in a single expression.
Example:Spoiler:ShowNone of these are valid:Form = 0x12345|-NordRace+WhiterunLocation
Form = 0x12345|CrimeFactionWhiterun-NordRace
Level Filters
A list of comma-separated expressions with numeric ranges that allows you to filter eligible NPCs by their leveled properties, such as level or skill.
Form = 0x12345|||LevelExpression,SkillExpression1,SkillExpression2,...
IMPORTANT
Only one Level Expression can be specified.
Providing multiple Level Expression will cause SPID to only recognize the last one.
Example:Spoiler:ShowIn the entryForm = 0x12345|||5/10,7/12only 7/12 levels will be stored. 5/10 will be discarded.
Supported Values
Level Filters allow you to match NPCs by the following criteria:
Value Expression
- Level min/max
- Skill Level skillIndex*(min/max)
- Skill Weight Same as Skill but prefixed with letter w.
Spoiler:
Show
# Skill
0. One-Handed
1. Two-Handed
2. Archery
3. Block
4. Smithing
5. Heavy Armor
6. Light Armor
7. Pickpocket
8. Lockpicking
9. Sneak
10. Alchemy
11. Speech
12. Alteration
13. Conjuration
14. Destruction
15. Illusion
16. Restoration
17. Enchanting
0. One-Handed
1. Two-Handed
2. Archery
3. Block
4. Smithing
5. Heavy Armor
6. Light Armor
7. Pickpocket
8. Lockpicking
9. Sneak
10. Alchemy
11. Speech
12. Alteration
13. Conjuration
14. Destruction
15. Illusion
16. Restoration
17. Enchanting
Ranges Syntax
- Closed range (min/max). Match values between min and max, including min and max.
- Half-open range (min or min/). Matches values starting from min and to infinity :)
- Exact value (value/value). Matches exact value.
Spoiler:
Show
Give a form to NPCs who are at least level 5
Give a form to NPCs who has 50 in Destruction skill level
Give a form to NPCs who level up their Two-Handed skill slightly more actively than other skills. (controlled by Skill Weight)
Form = 0x12345|||5
Give a form to NPCs who has 50 in Destruction skill level
Form = 0x12345|||14(50/50)
Give a form to NPCs who level up their Two-Handed skill slightly more actively than other skills. (controlled by Skill Weight)
Form = 0x12345|||w2(2/3)
Leveled Distribution
Whenever a Distributable Form defines a Level Filter it becomes a part of the Leveled Distribution. Unlike regular distribution, Leveled Distribution checks levels and/or skills of all loaded auto-leveled NPCs and checks whether they've met requirements of the Level Filter. This happens unless either other filters discard the NPC or a random chance check would fail.
Trait Filters
A single expression that allows you to filter eligible NPCs by traits, such as gender or teammate.
Form = 0x12345||||TraitExpression
Supported Traits
- Female
- Male
- Unique
- Summonable
- Child
- Leveled (Is PC Level Mult)
- Player's Teammate
Example:
Spoiler:
Show
Give a form to females
Form = 0x12345||||FTrait Expression Modifier
By default, Trait Expression checks whether an NPC has given Trait, but this behavior can be changed with several modifiers.
- Exclusion modifier (-). Placed in front of a trait. This will invert the trait and make it only match NPCs who does NOT have that trait.
Spoiler:
Show
Give a form only to not unique NPC
Form = 0x12345||||-U
- Combining modifier (/). Placed between multiple traits you want to combine. This will make the expression only match NPCs who have ALL of the traits.
Spoiler:
Show
Give a form to all non unique male NPCs who are also adults
Form = 0x12345||||-U/M/-C
TIP
Note that, unlike other filters, Traits actually support mixing of expression modifiers.
Example:Spoiler:ShowSo you can do thisForm = 0x12345||||F/-U/L/-S
Note on Templated NPCs
Templated NPCs are those that inherit their attributes from another NPC, that is referred to as a base template. Filters always check the final NPC that is created after merging attributes from NPC and its base template.
Additionally, String Filters and Form Filters allow you to target specific NPCs using EditorID or FormID, including IDs of templates that they derive from. However, when template hierarchy includes multiple templated NPC, SPID can only reach specific templates. In such cases the following templates can be specified:
For not leveled NPCs:
- Final NPC. This is the resolved NPC that will inherit attributes from its template.
- Base template. This is the immediate parent Template of the final NPC.
Spoiler:
Reachable Reachable Unreachable
Show
DLC2SV01DragonPriestBoss [NPC_:0401CAD5] => EncDragonPriestFire [NPC_:0002025A] => EncDragonPriest [NPC_:00023A93]
Final NPC Base template Further template in hierarchyReachable Reachable Unreachable
For leveled NPCs:
- Original NPC. This is the top-level NPC that was used to create the final NPC.
- Base leveled NPC. This is the Leveled NPC that is the closest to Original NPC in the hierarchy of templates that was used to pick a random NPC.
- Base template. This is a random NPC that was picked from Leveled NPC and will be used as a template for Original NPC.
Spoiler:
Unreachable Reachable Reachable
Unreachable Reachable Unreachable
Show
[NPC_:FF000D45] => LvlDraugrAmbushMelee2HMale [NPC_:0004A04E] => LCharDraugrMelee2HMale [LVLN:0001E772] =>
Dynamic Final NPC Original NPC Base leveled NPCUnreachable Reachable Reachable
SubCharDraugr02Melee2HM [LVLN:00023BFF] => EncDraugr02Melee2HHeadM05 [NPC_:0001FF2C] => EncDraugr02Template2H [NPC_:0005B753]
Nested leveled NPC Base template Further template in hierarchyUnreachable Reachable Unreachable
Count or Package Index
A numeric value that is interpreted based on associated Distributable Form.
Item Count
When Distributable Form is an Item, this section is interpreted as a number of items that should be added.
If this section is empty or absent Default count is 1.
You can also specify a numeric range as a Count and let SPID pick a Random Item Count to distribute from this range.
Example:
Spoiler:
Show
Give a single bow (default count 1)
Give 3 swords
Give somewhere between 10 and 20 arrows
Form = ImperialBowGive 3 swords
Form = IronSword|||||3Give somewhere between 10 and 20 arrows
Item = SteelArrow|||||10-20Package Index
When Distributable Form is a Package, this section is interpreted as an index where given Package should be inserted.
If this section is empty or absent Default index is 0.
Note that Package Index is zero-based, so the first Package has index 0.
Example:
Spoiler:
Show
Set Patrol package (Patrol [PACK:00017723]) as the second package
Set Travel package (Travel [PACK:00016FAA]) as the first package (default index 0)
Package = Patrol|||||1
Set Travel package (Travel [PACK:00016FAA]) as the first package (default index 0)
Package = Travel
Package List Type
When Distributable Form is a FormList, this section is interpreted as a type of the Package List that should be overwritten.
If this section is empty or absent Default type is 0.
Type can be one of the following:
# Type NPC's Record in xEdit
0. Default Package List DPLT - Default Package List
1. Spectator Override SPOR - Spectator override package list
2. Observe Corpse Override OCOR - Observe dead body override package list
3. Guard Warn Override GWOR - Guard warn override package list
4. Enter Combat Override ECOR - Combat override package list
Example:
Spoiler:
Show
Set default package list
or, since default type is 0, we can simply write
Package = DefaultPackageListLinkedPatrol|||||0
or, since default type is 0, we can simply write
Package = DefaultPackageListLinkedPatrolChance
A percentage value that sets a chance of given Distributable Form to be distributed.
Chance is a decimal value from 0 to 100. There is no limit on how small you want the chance to be (good luck hitting those 0.0001% chances though :D)
If this section is absent Default chance is 100 (e.g. guaranteed).
Example:
Spoiler:
Show
Give a form with a 60% chance
Give a form with a 0.01% chance
Form = 0x12345||||||60
Give a form with a 0.01% chance
Form = 0x12345||||||0.01
42 comments
like
Keyword = test_keyword1~MYESP.esp|-test_keyword2-test_keyword3||-C||33
Basically I want to distribute keywords so 33% of npcs have only 1 kind of keyword that's mutually exclusive, the other 33% have another kind, and the last 34% have another
-test_keyword2,-test_keyword3
This is a bit counterintuitive, but specifically expressions with exclusion are combined with AND. Looks like I missed that bit of info. Will add it later.I plan to address this inconsistency in the future
Use Traits LC2SV01DragonPriestBoss [NPC_:0401CAD5] => EncDragonPriestFire [NPC_:0002025A]
add flag and add template )
I want to distribute armors from this mod via SPID:
https://www.nexusmods.com/skyrimspecialedition/mods/85913
The problem is, that most of the Armors have not been added to Outfits (at least i can't find them.)
Can somebody give a tutorial on how to add the individual armor pieces to Outfits, so that i can use SPID to distribute them?
keyword = IsMage||*priest
keyword = IsMage||*wizard
keyword = IsMage||*spell
keyword = IsMage||*dremora
keyword = IsMage||*sorcerer
Spell = 0xD62~KS Wigs SMP SPID.esp|ActorTypeNPC,-Sybille Stentor,-Selana Petreia,-Braith,-Lillith Maiden-Loom,-Fralia GrayMane,-Eldawyn,-Silana Petreia,-Madena,-Ardwen,-Aranea,-IsMage,-jobcourtwizardfaction|-WEAdventurerBattlemage,-jobcourtwizardfaction,-WE31Mage,-WE30Alchemist,-WEAdventurerMageShieldStaff,-WEAdventurerMageShieldStaffHighElfF,-WEAdventurerMageShieldStaffHighElfFFireclass,-WEAdventurerMageShieldStaffHighElfFIce,-WEAdventurerMageShieldStaffHighElfFStorm,-WEAdventurerRangedConjurer,-WEAdventurerRangedConjurerWoodElfF,-WEBanditWizardNoFaction,-WEDA02Cultist,-WEForswornMeleeNoFaction,-WEJS25_LvlWarlockFire,-WEJS25_LvlWarlockFrost,-WERJ07Thrall,-WERJ07Vampire,-WEThalmorMageclass,-WIChangeLocation03Wizard,-mage,-priest,-bandit,-farmer,-combatmageelemental,-combatmageconjurer,-combatmagedestruction,-combatmagenecro,-encclassthalmorwizard,-encclassbanditwizard,-combatsorcerer,-encclassalikrwizard,-sorcerer,-spellvendorfaction,-wizard,-thalmormage,-wethalmormage,-dremora,-IsMage|NONE|U/F/-C|NONE|100
and I still run across no-name NPCs that are mages and naked because of a smp wig. I really don't get how the CLASS stuff works. Do I need the word class on classes? Do they go in the second set of | | or the first... or third? Is there a way to simply check if an NPC has a hood, and define that as a keyword = HasHood, and simply negate them getting a wig?
Outfit=Light|ActorTypeNPC|EncClassAlikrMelee,EncClassAlikrMissile,EncClassBanditMelee,EncClassBanditMissile,EncClassForsworn,EncClassForswornMissile,EncClassThalmorMelee,EncClassThalmorMissile,EncClassVampire|NONE|NONE|NONE|2
I have a noob question, plz answer if you would like to do it. Let's say I have a custom armor pack that contains 3 sets: Heavy armor/Light armor/Robe. I want to distribute these to the bandit faction with the following logic :
1.Heavy armor for tanker-alike bandits ( good at 2-handed and/or 1-handed+shield )
2.Light armor for assassin-alike bandits ( good at dual wield and/or archery )
3.Robe for magic-alike bandits (good at anything of magic school)
I have examples of pre-configurations like this :
Outfit = Heavy|ActorTypeNPC|EncClassBanditMelee|NONE|NONE|NONE|NONE
Outfit = Light|ActorTypeNPC|EncClassBanditMissile|NONE|NONE|NONE|NONE
Outfit = Robes|ActorTypeNPC|EncClassBanditWizard|NONE|NONE|NONE|NONE
The problem here is that I don't know how to effectively specify the required skills like 2-handed, 1-handed, block and archer to give the appropriate distribution of heavy and light armor. Could you plz help me with this ???
TIA !
What you're looking for is most likely Level Filters section's Skill Expressions, for example, 1(40) will require people to have at least 40 Skill level in Two-Handed.
Putting it together:
Outfit = Heavy|ActorTypeNPC|EncClassBanditMelee|1(40),0(40)
This will give Heavy outfits to melee bandits who reached at least 40 skill level in either one-handed or two-handed. Unfortunately, there is no support for combining modified in Level Filters (yet) so you can't express 1-handed+shield condition directly, you can use Keywords for that in the meantime:Keyword = SkilledOneHanded|||0(40)
Keyword = SkilledBlock|||3(40)
; One-handed + Shield
Outfit = Heavy|ActorTypeNPC+SkilledOneHanded+SkilledBlock|EncClassBanditMelee
; Two-handed
Outfit = Heavy|ActorTypeNPC|EncClassBanditMelee|1(40)
P.S. don't leave trailing NONEs refer to the syntax pattern - all trailing sections that are marked with green optional footnote can be omitted.