A Rule is a series of statements that evaluates to true or false. By using one or more rule functions, items are matched and assigned to Categories.

General

Logical operators and/or/not and parenthesis () are available.
🆎 These are case-sensitive!
⚠️ See important note below about the correct use of not.
Parameters are not case-sensitive unless 🆎 otherwise indicated (neither are function names).
Leading and trailing spaces in strings are trimmed.
Multiple parameters func(param1, param2, paramN) implicitly become func(param1) or func(param2) or func(paramN).
^{The former is easier to read and slightly more performant.}
Some functions (marked with ✳️) can leverage Lua string patterns by "/wrapping the parameter in slashes/" (see example below).
Behind the scenes, Rules are Lua code run in a limited environment. In other words, whatever you write must be valid Lua.

⚠️ `not` is not a combining operator

When building a Rule, you cannot write:

Func("Param") not OtherFunc("OtherParam")

It must be:

Func("Param") and not OtherFunc("OtherParam")

A few Rule examples

Name("Bread")

Any item with bread in the name.

Name("Bread") and not Name("Freshly Baked")

Any item with bread in the name, but Freshly Baked Bread would be excluded.

Type("Quest") or Tooltip("Quest Item")

Items with a type of Quest or whose tooltip contains quest item.

(Type("Trade Goods") and Bag(1)) or Quality(1)

Just an example of how to group rule functions.
Would match any trade goods in bag 1 or items with common quality.

Tooltip("/%+%d+ %a+ resist/")

Any item with +[number] [word] resist in the tooltip, like +12 Frost Resistance.
This is actually an example from the ArkInventory wiki, which works in Bagshui once the parameter is surrounded by slashes.
✳️ Lua pattern meaning:
%+ literal plus (must be %escaped because + is a magic character)
%d+ one or more digits
space
%a+ one or more letters
resist remaining space and text

Available rule functions

Refer to the in-game rule function menu [𝗙𝒙] in the Category Editor for more details, including aliases and lists of known parameters.

Legend

^{✳️ Can use Lua string patterns by "/wrapping in slashes/". 🔗 Pattern tester.

🆎 Parameters are case-sensitive.

🧩 Relies on another addon.

🔎 In-game command to help find parameter values.

🐢 Turtle WoW-exclusive.}

Item-based

ℹ️ Finding correct parameter values:

Functions with static values will be listed in the Category Editor's [𝗙𝒙] menu.
The Item Information window can help you find item-specific values.

Function	Matches when the item...
`ActiveQuest()`	Is a quest objective in the current character's quest log.
`Bag(number)` `Bag(num1, num2, numN)`	Is in the specified bag number.
`BagType("Type")` `BagType("Type1", "Type2", "TypeN")`	Is in a bag of the specified type.
`BindsOnEquip()`	Binds when equipped.
`CharacterLevelRange()` `CharacterLevelRange(levelsBelowOrAbove)` `CharacterLevelRange(levelsBelow, levelsAbove)`	Is usable based on the character's current level.
`Count(number)` `Count(min, max)`	Is in a stack of the specified size.
`EmptySlot()`	Is an empty slot.
`EquipLocation("Slot")` `EquipLocation("Slot1", "Slot2", "SlotN")`	Can be equipped in the specified slot.
`Equipped()` `Equipped("Slot")` `Equipped("Slot1", "Slot2", "SlotN")`	Has previously been worn (useful to match gear that is not soulbound).
`Id(number)`	ID number matches exactly.
`ItemString("item:number:number")`	ItemString begins with `item:<itemId>:<enchantId>[:<suffixId>]` (the `item:` prefix is optional).
`Location("Location")`	Is stored in the given location (Bags, Bank, etc.).
`MatchCategory(CategoryID)` `MatchCategory(id1, id2, idN)`	Matches one or more other categories. ➡️ See notes
`MinLevel(number)` `MinLevel(min, max)`	Is usable at the specified level or above or within the given range.
`Name("string")` `Name("string1", "string2", "stringN")`	Name contains the specified string. ✳️
`NameExact("string")` `NameExact("string1", "string2", "stringN")`	Name exactly matches the specified string.
`Openable()` `Openable(Locked)` `Openable(Unlocked)`	Can be opened, optionally filtered by lock state.
`Outfit()` `Outfit("Outfit Name")` `Outfit("outfit1", "outfit2", "outfitN")`	Is part of an ItemRack or Outfitter outfit. 🧩 Requires ItemRack or Outfitter
`PeriodicTable("SetName")` `PeriodicTable("set1", "set2", "setN")`	Belongs to a Periodic Table set. 🆎^{If installed, AtlasLoot's database can be also be utilized.}
`ProfessionCraft()` `ProfessionCraft("Profession Name")` `ProfessionCraft("prof1", "prof2", "profN")`	Is crafted by the current character's professions (within limitations).
`ProfessionReagent()` `ProfessionReagent("Profession Name")` `ProfessionReagent("prof1", "prof2", "profN")`	Is a reagent for the current character's professions (within limitations).
`Quality(number)` `Quality(num1, num2, numN)`	Is of the specified quality.
`RecentlyChanged()` `RecentlyChanged(New)` `RecentlyChanged(Up)` `RecentlyChanged(Down)`	Stock state has changed, optionally filtered by change type.
`RequiresClass("ClassName")` `RequiresClass("class1", "class2", "classN")`	Is usable by the specified class.
`Soulbound()`	Is soulbound.
`Stacks()`	Can be stacked.
`Subtype("Type")` `Subtype("type1", "type2", "typeN")`	Is of the specified subtype.
`Tooltip("String")` `Tooltip("string1", "string2", "stringN")`	Tooltip contains the specified string. ✳️
`Transmog()`	🐢 Is in your Turtle WoW transmog collection or is eligible to be transmogged. 🧩 Requires Tmog and Bagshui-Tmog
`Type("Type")` `Type("type1", "type2", "typeN")`	Is of the specified type.
`Usable()`	Is usable by the current character level, skills, and professions.
`Wishlist()`	Is on the AtlasLoot wishlist. 🧩 Requires AtlasLoot

`MatchCategory()` notes

Super-powerful function that allows you to build Categories on top of other Categories.

Parameters are Category IDs (not names) which can be found the bottom of the Category Editor.
IDs for built-in Categories are strings (that may not match their names) and must be "quoted" appropriately.
Custom Categories have numeric IDs.

Examples

MatchCategory("Food")

Simple (and fairly useless); this is the same as just adding the built-in Food category to a group.

MatchCategory("Food") and not Name("Essence Mango")

Now things start getting interesting. You can leverage the built-in Food category, but "edit" it by adding your own exclusions.

MatchCategory(1, "Drink") and Zone("Thunder Bluff")

Match the custom Category with ID 1 or the built-in Drink category, but only when you're in Thunder Bluff.

Game state-based

Function	Matches when the player...
`LootMaster()`	Is the loot master. ^{🔎 /Bagshui Info Group}
`LootMethod("FreeForAll")` `LootMethod("FreeForAll")` `LootMethod("RoundRobin")` `LootMethod("Master")` `LootMethod("NeedBeforeGreed")` `LootMethod("PersonalLoot")` `LootMethod("method1", "method2", "methodN")`	Has the specified loot method active. ^{🔎 /Bagshui Info Group}
`PlayerInGroup()` `PlayerInGroup(Party)` `PlayerInGroup(Raid)`	Is in a group, optionally filtered by type. ^{🔎 /Bagshui Info Group}
`Subzone("Subzone Name")` `Subzone("zone1", "zone2", "zoneN")`	Is in the specified subzone. ^{🔎 /Bagshui Info Location}
`Zone("Zone Name")` `Zone("zone1", "zone2", "zoneN")`	Is in the specified zone. ^{🔎 /Bagshui Info Location}

Writing valid Lua

This is a fairly useful Lua cheatsheet. Keep in mind:

❌ print() is not available to Rules.
🛑 Rules cannot access the global environment (_G).
ℹ️ ~= is the "not equal" operator.
^{In other words, != will not work.}

Advanced Rules

If you need to push Rules to the limit, "raw" item and character data are available. There is not (currently) a friendly interface for this; the best way to find properties and values is to look at <WoW Folder>\WTF\Account\<AccountName>\SavedVariables\Bagshui.lua.

Object	Alias
`item`	`i`
`character`	`c`

`item`

All properties of the item being tested.
A list of all possible keys is in BS_ITEM_SKELETON.
To find values, refer to entries in SavedVariables under characters > <Character - Realm> > <inventoryType> > inventory (searching for the item name is usually easiest).

Basic Example

item.name == "Major Healing Potion"

`character`

Basic information about the current character (no spells or skills).
Available properties and values can be found in SavedVariables under characters > <Character - Realm> > info.
⚠️ Only non-table values are usable in the Rule environment. In other words, class and faction are populated, but skills and spells are not.

Basic Example

character.class ~= "DRUID"

Rules - veechs/Bagshui GitHub Wiki

General

⚠️ `not` is not a combining operator

A few Rule examples

Available rule functions

Legend

Item-based

`MatchCategory()` notes

Examples

Game state-based

Writing valid Lua

Advanced Rules

`item`

Basic Example

`character`

Basic Example

⚠️ GitHub.com Fallback ⚠️

Rules - veechs/Bagshui GitHub Wiki

General

⚠️ not is not a combining operator

A few Rule examples

Available rule functions

Legend

Item-based

MatchCategory() notes

Examples

Game state-based

Writing valid Lua

Advanced Rules

item

Basic Example

character

Basic Example

⚠️ **GitHub.com Fallback** ⚠️

⚠️ `not` is not a combining operator

`MatchCategory()` notes

`item`

`character`

⚠️ GitHub.com Fallback ⚠️