Exclusive Groups

[adya]

Summary

Exclusive Groups allow users to define sets of distributable forms where only one from the set can be distributed at any time. Ordering and other distribution rules are unaffected by Exclusive Group. When one entry is distributed, all other entries from common exclusive groups are banned for that NPC.

Use Case

For example, when people want to distribute only one type of weapon, but still being able to randomize it.
Let's imagine we have a distribution of several new weapons:

Item = CoolSword|...|50
Item = DecentAxe|...|40
Item = OPBow|...|10

In this scenario NPC can get anywhere between 0 and 3 items. If we want to ensure that only one of those items can be distributed we could introduce a set of temp keywords:

Keyword = GetsCoolSword|...|50
Keyword = GetsDecentAxe|-GetsCoolSword,...|40
Keyword = GetsOPBow|-GetsCoolSword,-GetsDecentAxe,...|10

Item = CoolSword|GetsCoolSword
Item = DecentAxe|GetsDecentAxe
Item = OPBow|GetsOPBow

It works, but it's ugly 🙂 and limited.

Other than cluttering keywords and growing exponentially in size and complexity, this approach also can't reliably support add-ons.
So if there are some other mods that would like to extend weapons that NPCs can get there is no way for them to know about
each other and take them into account.

This is where Exclusive Groups come to the rescue 😄 we don't need to foresee all possible weapons that other people might add, we only want to tell them that there is this group of weapons and we really don't want to distribute any other weapons on top. So we do it like this:

Item = CoolSword|...|50
Item = DecentAxe|...|40
Item = OPBow|...|10

ExclusiveGroup = Primary Weapon|CoolSword,DecentAxe,OPBow

and we're done. We no longer need to clutter Keywords or worry about compatibilities.
Now when another mod wants to add a crossbow, it just needs to add this crossbow to the Primary Weapon group:

Item = FineCrossbow|...|80

ExclusiveGroup = Primary Weapon|FineCrossbow

all for weapons will be mutually exclusive now.

---

Syntax

Familiar syntax was preserved.

Defining Exclusive Group

To define a new Exclusive Group we only need to provide a name and at least one form (FormID/EditorID) in the second section.
Name can be any arbitrary text (obviously not containing | character)

ExclusiveGroup = MyGroup|Form1,Form2

Now there will be one Exclusive Group named MyGroup with 2 forms: Form1, Form2

Adding forms to existing Exclusive Group

Similarly, we can later add new forms to the existing Exclusive Group by providing other forms:

ExclusiveGroup = GroupName|Form3

MyGroup now will contain all 3 forms: Form1, Form2 and Form3

Removing forms from existing Exclusive Group

As Exclusive Groups utilize the same filters parsing we can use NOT filter to remove forms from Exclusive Group:

ExclusiveGroup = MyGroup|-Form3

MyGroup now will contain original 2 forms: Form1 and Form2

Mixing everything together

We can also do mutation at the same time in one entry:

ExclusiveGroup = MyGroup|Form4,-Form2

MyGroup now will contain original 2 forms: Form1 and Form4

P.S. This description probably will be converted into an article for SPID page and be the beginning of extensive documentation for SPID 😆

[adya]

Closed as original branch was rebased onto the latest stable version 6.8.2