### Example ItemFilter from Equipment.json

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/ItemFilters-ItemFilters

An example of an ItemFilter from the Equipment.json ItemFilterMap, demonstrating the use of arbitrary priority numbers for filters. This filter prioritizes equipped items and then checks stack amount and proficiency.

```json
"ALL" : 
    {
        "Filters" : 
        {
            "50" : 
            {
                "TargetStat" : "HAS_TYPE_EQUIPPED"
            },
            "51" : 
            {
                "CompareStrategy" : "HIGHER",
                "TargetStat" : "STACK_AMOUNT"
            },
            "52" : 
            {
                "CalculateStackUsing" : 
                {
                    "ARMOR_TYPES" : 
                    [
                        "SELF"
                    ],
                    "EQUIPMENT_TYPES" : 
                    [
                        "SELF"
                    ]
                },
                "CompareStrategy" : "HIGHER",
                "TargetStat" : "STACK_AMOUNT"
            },
            "53" : 
            {
                "TargetStat" : "PROFICIENCY"
            }
        }
    }
```

--------------------------------

### PreFilter Execution Example - STACK_LIMIT

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/Quickstart-Guide-3

This log demonstrates the execution of a per-item PreFilter, specifically 'STACK_LIMIT'. It shows the start and end logs for the filter, indicating the eligible party members after its execution.

```plaintext
77061853 Automatic_Inventory_Manager  [DEBUG] : Processing Per-Item PreFilter STACK_LIMIT
...
77062004 Automatic_Inventory_Manager  [DEBUG] : After processing per-item PreFilter STACK_LIMIT, eligible party members are [
	"Elves_Female_High_Player_6922eea6-c4e2-0600-d4bc-859f69b2273b"
]
```

--------------------------------

### Compare Filters Configuration Example (JSON)

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/ItemFilters-CompareFilters

This JSON snippet demonstrates how to configure Compare Filters for a specific item tag ('LOCKPICKS'). It shows the use of multiple filters with different TargetStats and CompareStrategies to prioritize item allocation based on character skills and item stack amounts.

```json
"LOCKPICKS" :
{
	"Filters" :
	{
		"1" :
		{
			"CompareStrategy" : "HIGHER",
			"TargetStat" : "SKILL_TYPE",
			"TargetSubStat" : "SleightOfHand"
		},
		"2" :
		{
			"CompareStrategy" : "HIGHER",
			"TargetStat" : "STACK_AMOUNT"
		}
	}
},
```

--------------------------------

### AIM Initialization Log Entries

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/Quickstart-Guide-3

These log entries indicate the start of the Automatic Inventory Manager's initialization process. They show the successful registration of item filter maps and the loading of filter presets, which are essential for the mod's functionality.

```plaintext
77022321 Automatic_Inventory_Manager  [INFO] : AIM has begun initialization!
77022329 Automatic_Inventory_Manager  [INFO] : Mod Automatic_Inventory_Manager successfully registered 5 new itemFilterMaps under preset Automatic_Inventory_Manager-All-Defaults
77022337 Automatic_Inventory_Manager  [INFO] : Mod Automatic_Inventory_Manager successfully registered 3 new itemFilterMaps under preset Automatic_Inventory_Manager-Camp-Gold-Books
77022344 Automatic_Inventory_Manager  [INFO] : Loading filter preset Automatic_Inventory_Manager-All-Defaults
77022350 Automatic_Inventory_Manager  [INFO] : Merging Automatic_Inventory_Manager-All-Defaults/Roots.json into active itemFilterMaps
77022356 Automatic_Inventory_Manager  [INFO] : Merging Automatic_Inventory_Manager-All-Defaults/Tags.json into active itemFilterMaps
77022363 Automatic_Inventory_Manager  [INFO] : Merging Automatic_Inventory_Manager-All-Defaults/RootPartial.json into active itemFilterMaps
77022369 Automatic_Inventory_Manager  [INFO] : Merging Automatic_Inventory_Manager-All-Defaults/Equipment.json into active itemFilterMaps
77022376 Automatic_Inventory_Manager  [INFO] : Merging Automatic_Inventory_Manager-All-Defaults/Weapons.json into active itemFilterMaps
77022384 Automatic_Inventory_Manager  [DEBUG] : Finished loading in presets - finalized item maps are:
```

--------------------------------

### Configure TargetFilter JSON Rules

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/ItemFilters-TargetFilters

Examples of JSON configurations for item routing. These snippets demonstrate how to route items to the camp chest, use conditional logic for inventory distribution, and apply stack limits with eligibility checks.

```json
"CAMPSUPPLIES" : 
{
    "Filters" : 
    [
        {
            "Target" : "camp"
        }
    ]
}
```

```json
"SCROLL" : 
{
    "Filters" : 
    [
        {
            "CompareStrategy" : "HIGHER",
            "TargetStat" : "STACK_AMOUNT"
        },
        {
            "Target" : "originalTarget"
        }
    ]
}
```

```json
"ALCH_Solution_Elixir_Meditation_Greater_8c7656f5-507a-4cee-8e15-320c968539f0" : 
{
    "PreFilters" : 
    {
        "STACK_LIMIT" : 2
    },
    "Filters" : 
    {
        "1": {
            "Target" : "S_Player_ShadowHeart_3ed74f06-3c60-42dc-83f6-f034cb47c679",
            "RespectEligibility": "true"
        },
        "2": {
            "CompareStrategy" : "LOWER",
            "TargetStat" : "STACK_AMOUNT"
        }
    }
}
```

--------------------------------

### Example ItemFilter from Tags.json

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/ItemFilters-ItemFilters

An example of an ItemFilter from the Tags.json ItemFilterMap, showcasing sequential priority arrays for filters. This filter prioritizes healing potions based on health percentage and stack amount, with a prefilter for stack limit.

```json
"HEALING_POTION" : 
    {
        "Filters" : 
        [
            {
                "CompareStrategy" : "LOWER",
                "TargetStat" : "HEALTH_PERCENTAGE"
            },
            {
                "CalculateStackUsing" : 
                {
                    "TAGS" : 
                    [
                        "HEALING_POTION"
                    ]
                },
                "CompareStrategy" : "LOWER",
                "TargetStat" : "STACK_AMOUNT"
            }
        ],
        "PreFilters" : 
        {
            "STACK_LIMIT" : 2
        }
    }
```

--------------------------------

### Recorded Entity Properties Output

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/Quickstart-Guide-4

Example of the JSON output generated by the Entity Property Recorder. This structure identifies the item's unique RootTemplate GUIDSTRING, which is required for blacklisting.

```json
{
	"CONS_Potion_Healing_A_Greater_e3b95c96-dc26-40fe-bfc0-baa05e1abd20" : 
	{
		"Automatic_Inventory_Manager" : 
		{
			"Tags" : 
			{
				"Value" : 
				[
					"POTION",
					"HEALING_POTION"
				]
			},
			"uuid" : 
			{
				"Value" : "CONS_Potion_Healing_A_Greater_e3b95c96-dc26-40fe-bfc0-baa05e1abd20"
			}
		}
	}
}
```

--------------------------------

### AIM Item Processing Start Log

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/Quickstart-Guide-3

This log block signifies the beginning of AIM's processing for a specific item. It includes details such as the item's ID, its root, the current inventory holder, owner, and the computed item filter applied. This information is vital for understanding how AIM evaluates and sorts items.

```plaintext
77061586 Automatic_Inventory_Manager  [DEBUG] : 
----------------------------------------------------------
			STARTED
----------------------------------------------------------
77061598 Automatic_Inventory_Manager  [DEBUG] : 
	|item| = CONS_Potion_Healing_A_7e452640-a465-e14f-5732-aeb925874ff8
	|root| = CONS_Potion_Healing_A_d47006e9-8a51-453d-b200-9e0d42e9bbab
	|inventoryHolder| = Elves_Female_High_Player_6922eea6-c4e2-0600-d4bc-859f69b2273b
	|owner| = 6922eea6-c4e2-0600-d4bc-859f69b2273b
	|originalOwner| = 6922eea6-c4e2-0600-d4bc-859f69b2273b
	|directInventoryOwner| = 6922eea6-c4e2-0600-d4bc-859f69b2273b
	|itemStackSize| = 2
	|templateStackSize| = 2
	|computedItemFilter| = 
{
	"Filters" : 
	[
		{
			"CompareStrategy" : "LOWER",
			"TargetStat" : "HEALTH_PERCENTAGE"
		},
		{
			"CalculateStackUsing" : 
			{
				"TAGS" : 
				[
					"HEALING_POTION"
				]
			},
			"CompareStrategy" : "LOWER",
			"TargetStat" : "STACK_AMOUNT"
		},
		{
			"CompareStrategy" : "HIGHER",
			"TargetStat" : "STACK_AMOUNT"
		}
	],
	"PreFilters" : 
	{
		"STACK_LIMIT" : 2
	}
}
```

--------------------------------

### ItemBlackList.json Configuration

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/Configurations

The ItemBlackList.json file defines items, root templates, and container roots that AIM should ignore. It supports partial or full UUIDs and human-readable tags, with entries processed in a case-insensitive manner.

```json
{
	"ContainerRoots" : 
	[
		"CONT_ISF_Container",
		"TUT_Chest_Potions",
		"DIQ_OBJ_Important_Container",
		"DIQ_OBJ_Clothing_Container",
		"DIQ_OBJ_Dye_Container",
		"DIQ_OBJ_Weapon_Container"
	],
	"Items" : [],
	"RootTemplates" : 
	[
		"FOCUSLODESTONES",
		"TMOG",
		"FallenStar_Cons_Wifi"
	],
	"Tags" : []
}
```

--------------------------------

### Configure AIM behavior via config.json

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

The main configuration file defines global mod settings, including enablement, logging levels, and active preset management. It is located in the Script Extender directory and controls when sorting triggers occur.

```json
{
    "ENABLED": 1,
    "LOG_LEVEL": 3,
    "SORT_ITEMS_ON_FIRST_LOAD": 1,
    "SORT_ITEMS_DURING_COMBAT": 0,
    "SORT_CONSUMABLE_ITEMS_ON_USE_DURING_COMBAT": 0,
    "RESPECT_CONTAINER_BLACKLIST_FOR_CUSTOM_STACK_CALCULATIONS": 0,
    "RECORD_APPLICABLE_ENTITY_PROPS": 0,
    "PRESETS": {
        "PRESETS_DIR": "presets",
        "FILTERS_PRESETS": {
            "Automatic_Inventory_Manager-All-Defaults": ["Tags", "Roots", "RootPartial", "Weapons", "Equipment"]
        },
        "ACTIVE_PRESETS": {
            "Automatic_Inventory_Manager-All-Defaults": ["ALL"]
        }
    }
}
```

--------------------------------

### Configure Preset Loading in config.json

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

Configures the directory and active status of inventory presets. Users can define custom preset maps and specify which ones are active for the mod to process.

```json
{
    "PRESETS": {
        "PRESETS_DIR": "presets",
        "FILTERS_PRESETS": {
            "Automatic_Inventory_Manager-All-Defaults": ["Tags", "Roots", "RootPartial", "Weapons", "Equipment"],
            "Automatic_Inventory_Manager-Camp-Gold-Books": ["Tags"],
            "MyMod-CustomPreset": ["Tags", "Weapons"]
        },
        "ACTIVE_PRESETS": {
            "Automatic_Inventory_Manager-All-Defaults": ["Tags", "Weapons", "Equipment"],
            "MyMod-CustomPreset": ["ALL"]
        }
    }
}
```

--------------------------------

### Item Filter Definition Example

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/Quickstart-Guide-5

This JSON structure defines properties for filtering items, including EquipmentType and Tags. It specifies 'Can Be Applied To' which details the FilterFields, ItemFilterFields, and ItemFilterMaps that can be used for categorization.

```json
{
			"ItemFilterMaps" : 
			[
				"Equipment"
			]
		},
		"Value" : "Melee Main Weapon"
	},
	"EquipmentType" : 
	{
		"Can Be Applied To" : 
		{
			"FilterFields" : 
			[
				"Key",
				"CalculateStackUsing"
			],
			"ItemFilterFields" : 
			[
				"Filters"
			],
			"ItemFilterMaps" : 
			[
				"Equipment",
				"Weapons"
			]
		},
		"Value" : "Javelin"
	},
	"Tags" : 
	{
		"Can Be Applied To" : 
		{
			"FilterFields" : 
			[
				"Key",
				"CalculateStackUsing"
			],
			"ItemFilterFields" : 
			[
				"Filters"
			],
			"ItemFilterMaps" : 
			[
				"Tags"
			]
		},
		"Value" : 
		[
			"SHOPTRIGGER_FOR_SALE",
			"WEAPONTAG",
			"WPN_VFX_SPEAR",
			"AI_THROWITEM",
			"WPN_JAVELIN",
			"WEIGHT_TINY"
		]
	},
	"uuid" : 
	{
		"Can Be Applied To" : 
		{
			"FilterFields" : 
			[
				"Key",
				"CalculateStackUsing"
			],
			"ItemFilterFields" : 
			[
				"Filters"
			],
			"ItemFilterMaps" : 
			[
				"Roots",
				"RootPartial",
				"Equipment",
				"Weapons"
			]
		},
		"Value" : "WPN_Kuotoa_Javelin_A_1_8fdd7b33-6740-4d15-935c-9e54f54e16d4"
	}
}
```

--------------------------------

### Adding Blacklist Entries

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

Provides functionality for third-party mods to add items to the blacklist programmatically.

```APIDOC
## Adding Blacklist Entries

### Description
Third-party mods can add items to the blacklist programmatically.

### Method
`AddEntriesToBlackList(modUUID, blacklistedItems, blacklistedRoots, blacklistedTags, blacklistedContainers)`
`IsItemOrTemplateInBlacklist(item, rootTemplate)`
`IsContainerInBlacklist(item)`

### Parameters
#### `AddEntriesToBlackList` Parameters
- **modUUID** (string) - The unique identifier for the mod.
- **blacklistedItems** (table, optional) - A list of specific item UUIDs to blacklist.
- **blacklistedRoots** (table, optional) - A list of root template partial matches to blacklist.
- **blacklistedTags** (table, optional) - A list of tags to blacklist.
- **blacklistedContainers** (table, optional) - A list of container UUIDs to blacklist.

#### `IsItemOrTemplateInBlacklist` Parameters
- **item** (object) - The item object to check.
- **rootTemplate** (string) - The root template of the item.

#### `IsContainerInBlacklist` Parameters
- **item** (object) - The item object whose container is to be checked.

### Request Example (Add Entries)
```lua
AIM_SHORTCUT.ItemBlackList:AddEntriesToBlackList(SAMPLE_MOD_UUID,
    nil,
    {
        "ALCH_Solution_Oil_Combustion-bb750807-895b-468d-81e1-4378797d11ca"
    },
    nil,
    nil
)
```

### Request Example (Check Blacklist)
```lua
local isBlacklisted = AIM_SHORTCUT.ItemBlackList:IsItemOrTemplateInBlacklist(item, rootTemplate)
local containerRoot = AIM_SHORTCUT.ItemBlackList:IsContainerInBlacklist(item)
```
```

--------------------------------

### Define Custom Inventory Presets (JSON)

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/Quickstart-Guide-5

This JSON snippet shows how to define a custom inventory preset named 'My_Custom_Preset' within the 'ACTIVE_PRESETS' configuration. It specifies that items categorized as 'Weapons' should be included in this preset. This configuration is part of the Automatic Inventory Manager's setup.

```json
{
		"ACTIVE_PRESETS" : 
		{
			"Automatic_Inventory_Manager-All-Defaults" : 
			[
				"ALL"
			],
			"My_Custom_Preset" : 
			[
				"Weapons"
			]
		},
}
```

--------------------------------

### Add Blacklist Entries (Lua)

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

Provides methods to programmatically add items to the game's blacklist. Entries can be specified by item UUID, root template partial matches, tags, or containers. The API also includes functions to check if an item or its container is blacklisted.

```lua
AIM_SHORTCUT.ItemBlackList:AddEntriesToBlackList(SAMPLE_MOD_UUID,
    nil,  -- blacklistedItems (specific item UUIDs)
    {
        "ALCH_Solution_Oil_Combustion-bb750807-895b-468d-81e1-4378797d11ca"
    }, -- blacklistedRoots (root template partial matches)
    nil,  -- blacklistedTags
    nil   -- blacklistedContainers
)

local isBlacklisted = AIM_SHORTCUT.ItemBlackList:IsItemOrTemplateInBlacklist(item, rootTemplate)
local containerRoot = AIM_SHORTCUT.ItemBlackList:IsContainerInBlacklist(item)
```

--------------------------------

### Registering Custom PreFilter Processors

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

Allows for the addition of per-stack or per-item prefilters to exclude party members before filter processing.

```APIDOC
## Registering Custom PreFilter Processors

### Description
Add per-stack or per-item prefilters to exclude party members before filter processing.

### Method
`RegisterPerStackPreFilterProcessor(modUUID, preFilterName, preFilterFunction)`
`RegisterPerItemPreFilterProcessor(modUUID, preFilterName, preFilterFunction)`

### Parameters
#### Per-Stack PreFilter Function Parameters
- **preFilterContent** (table) - Content defined for the prefilter in the ItemFilterMap.
- **paramMap** (table) - Contains `itemFilter`, `eligiblePartyMembers`, `item`, `currentItemStackSize`, `root`, `inventoryHolder`.

#### Per-Item PreFilter Function Parameters
- **content** (table) - Content defined for the prefilter in the ItemFilterMap.
- **paramMap** (table) - Contains `itemFilter`, `eligiblePartyMembers`, `item`, `currentItemStackSize`, `root`, `inventoryHolder`, `targetsWithAmountWon`.

### Request Example (Per-Stack)
```lua
AIM_SHORTCUT.PreFilterProcessors:RegisterPerStackPreFilterProcessor(SAMPLE_MOD_UUID,
    "CustomPreFilter-PerStack",
    function(preFilterContent, paramMap)
        if preFilterContent.isEnabled then
            Ext.Utils.Print("PerStack Pre-Filter is working!")
            return paramMap.eligiblePartyMembers
        end
        return nil
    end
)
```

### Request Example (Per-Item)
```lua
AIM_SHORTCUT.PreFilterProcessors:RegisterPerItemPreFilterProcessor(SAMPLE_MOD_UUID,
    "CustomPreFilter-PerItem",
    function(content, paramMap)
        if not content.amICool then
            Ext.Utils.Print("PerItem Pre-Filter is working!")
            return paramMap.eligiblePartyMembers
        end
    end
)
```

### Usage in ItemFilterMap
```lua
local newItemFilterMap = {
    ["Tags"] = {
        ["HEALING_POTION"] = {
            PreFilters = {
                ["CustomPreFilter-PerStack"] = { isEnabled = true },
                ["CustomPreFilter-PerItem"] = { amICool = false }
            },
            Filters = {
                [1] = { TargetStat = "HEALTH_PERCENTAGE", CompareStrategy = "LOWER" }
            }
        }
    }
}
```
```

--------------------------------

### Register ItemFilterMap Presets via API

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

Allows third-party mods to register custom item filter maps programmatically. Requires checking if the AIM mod is loaded before registration.

```lua
SAMPLE_MOD_UUID = "83f59e8c-7bf4-4e53-92bc-68dc7e8d5d17"

if Ext.Mod.IsModLoaded("23bdda0c-a671-498f-89f5-a69e8d3a4b52") then
    AIM_SHORTCUT = Mods.Automatic_Inventory_Manager

    local newItemFilterMap = {
        ["Tags"] = {
            ["HEALING_POTION"] = {
                PreFilters = {
                    [AIM_SHORTCUT.ItemFilters.ItemFields.PreFilters.STACK_LIMIT] = 2
                },
                Filters = {
                    [1] = {
                        TargetStat = AIM_SHORTCUT.ItemFilters.FilterFields.TargetStat.HEALTH_PERCENTAGE,
                        CompareStrategy = AIM_SHORTCUT.ItemFilters.FilterFields.CompareStrategy.LOWER
                    },
                    [2] = {
                        TargetStat = AIM_SHORTCUT.ItemFilters.FilterFields.TargetStat.STACK_AMOUNT,
                        CompareStrategy = AIM_SHORTCUT.ItemFilters.FilterFields.CompareStrategy.LOWER
                    }
                }
            }
        }
    }

    AIM_SHORTCUT.ItemFilters:RegisterItemFilterMapPreset(SAMPLE_MOD_UUID, "VanillaFilters", newItemFilterMap)
else
    Ext.Utils.PrintError("Automatic_Inventory_Manager was not loaded!!")
end
```

--------------------------------

### Identify Booal's Arms EPR Entry

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/Quickstart-Guide-5

This JSON snippet shows a partial EPR entry for 'BOOAL's Arms', another type of Javelin. It demonstrates the 'Equipable.Slot' property, similar to the basic Javelin entry. This example is used to reinforce the reliability of using 'EquipmentType' for filtering, as different Javelin variants share this fundamental property.

```json
{
	"WPN_Kuotoa_Javelin_A_1_8fdd7b33-6740-4d15-935c-9e54f54e16d4" : 
	{
		"Automatic_Inventory_Manager" : 
		{
			"Equipable.Slot" : 
			{
				"Can Be Applied To" : 
				{
					"FilterFields" : 
					[
						"Key"
					]
				}
			}
		}
	},
}
```

--------------------------------

### Identify Javelin Properties using EPR

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/Quickstart-Guide-5

This JSON snippet shows an example entry from the Entity Property Recorder (EPR) for a basic Javelin. It highlights key properties like 'Equipable.Slot', 'EquipmentType', 'Tags', and 'uuid', which are crucial for creating custom item filters in the Automatic Inventory Manager. The 'EquipmentType' field with the value 'Javelin' is identified as the most reliable way to filter for all Javelin types.

```json
{
	"WPN_HUM_Javelin_A_0_0a7adc8d-b561-4f81-a8f2-ec07b5d54955" : 
	{
		"Automatic_Inventory_Manager" : 
		{
			"Equipable.Slot" : 
			{
				"Can Be Applied To" : 
				{
					"FilterFields" : 
					[
						"Key"
					],
					"ItemFilterFields" : 
					[
						"Filters"
					],
					"ItemFilterMaps" : 
					[
						"Equipment"
					]
				},
				"Value" : "Melee Main Weapon"
			},
			"EquipmentType" : 
			{
				"Can Be Applied To" : 
				{
					"FilterFields" : 
					[
						"Key",
						"CalculateStackUsing"
					],
					"ItemFilterFields" : 
					[
						"Filters"
					],
					"ItemFilterMaps" : 
					[
						"Equipment",
						"Weapons"
					]
				},
				"Value" : "Javelin"
			},
			"Tags" : 
			{
				"Can Be Applied To" : 
				{
					"FilterFields" : 
					[
						"Key",
						"CalculateStackUsing"
					],
					"ItemFilterFields" : 
					[
						"Filters"
					],
					"ItemFilterMaps" : 
					[
						"Tags"
					]
				},
				"Value" : 
				[
					"SHOPTRIGGER_FOR_SALE",
					"WEAPONTAG",
					"WPN_VFX_SPEAR",
					"AI_THROWITEM",
					"WPN_JAVELIN",
					"METAL",
					"WEIGHT_TINY"
				]
			},
			"uuid" : 
			{
				"Can Be Applied To" : 
				{
					"FilterFields" : 
					[
						"Key",
						"CalculateStackUsing"
					],
					"ItemFilterFields" : 
					[
						"Filters"
					],
					"ItemFilterMaps" : 
					[
						"Roots",
						"RootPartial",
						"Equipment",
						"Weapons"
					]
				},
				"Value" : "WPN_HUM_Javelin_A_0_0a7adc8d-b561-4f81-a8f2-ec07b5d54955"
			}
		}
	},
}
```

--------------------------------

### Register Custom Filter Processors

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

Extends AIM logic by registering custom TargetStat processors and filter predicates. This allows developers to define unique filtering criteria beyond the default implementation.

```lua
-- Register a new TargetStat processor
AIM_SHORTCUT.FilterProcessor:RegisterTargetStatProcessors(SAMPLE_MOD_UUID, {
    ["MyCustomStat"] = function(partyMemberBeingProcessed, paramMap)
        if partyMemberBeingProcessed ~= paramMap.inventoryHolder then
            Ext.Utils.Print("Processing custom stat for: " .. partyMemberBeingProcessed)
        end
    end
})

-- Register a completely new filter processor with predicate
AIM_SHORTCUT.FilterProcessor:RegisterNewFilterProcessor(SAMPLE_MOD_UUID,
    function(filterBeingProcessed)
        return filterBeingProcessed["TargetStat"] == "MyCustomStat"
            or filterBeingProcessed["CustomField"]
    end,
    function(partyMemberFilterIsBeingRunAgainst, paramMap)
        if paramMap.targetsWithAmountWon[partyMemberFilterIsBeingRunAgainst]
            and paramMap.customItemFilterFields["MyCustomItemFilterField"]
            and paramMap.customItemFilterFields["MyCustomItemFilterField"].Cuz then
            table.insert(paramMap.winners, partyMemberFilterIsBeingRunAgainst)
        end
    end
)
```

--------------------------------

### Compare Filter TargetStats Configuration Reference

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

A JSON schema reference for defining item filters. It demonstrates various TargetStat types including STACK_AMOUNT, SKILL_TYPE, and ABILITY_STAT, which dictate how the inventory manager evaluates items.

```json
{
    "HEALTH_PERCENTAGE_example": {
        "Filters": [{
            "CompareStrategy": "LOWER",
            "TargetStat": "HEALTH_PERCENTAGE"
        }]
    },
    "STACK_AMOUNT_with_custom_calculation": {
        "Filters": [{
            "CompareStrategy": "HIGHER",
            "TargetStat": "STACK_AMOUNT",
            "CalculateStackUsing": {
                "TAGS": ["HEALING_POTION"],
                "ROOTS": ["UNI_CONS_Goodberry"],
                "ARMOR_TYPES": ["SELF", "ScaleMail"],
                "EQUIPMENT_TYPES": ["SELF"]
            }
        }]
    },
    "IS_ONE_OF_CLASS_OR_SUBCLASS_example": {
        "Filters": [{
            "TargetStat": "IS_ONE_OF_CLASS_OR_SUBCLASS",
            "TargetSubStat": ["Wizard", "Sorcerer", "Warlock"]
        }]
    }
}
```

--------------------------------

### Registering Custom ItemFilter Lookup Functions

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

Enables the creation of lookup functions for entirely new ItemFilterMap types.

```APIDOC
## Registering Custom ItemFilter Lookup Functions

### Description
Create lookup functions for entirely new ItemFilterMap types.

### Method
`RegisterItemFilterMapPreset(modUUID, presetName, itemFilterMap)`
`RegisterItemFilterLookupFunction(modUUID, lookupFunction)`

### Parameters
#### `RegisterItemFilterMapPreset` Parameters
- **modUUID** (string) - The unique identifier for the mod.
- **presetName** (string) - The name of the item filter map preset.
- **itemFilterMap** (table) - The structure defining the item filters.

#### `RegisterItemFilterLookupFunction` Parameters
- **modUUID** (string) - The unique identifier for the mod.
- **lookupFunction** (function) - A function that takes `itemFilterMaps`, `root`, `item`, `inventoryHolder` and returns a list of applicable filters.
  - **itemFilterMaps** (table) - Available item filter maps.
  - **root** (string) - The root template of the item.
  - **item** (object) - The item object.
  - **inventoryHolder** (object) - The holder of the item.

### Request Example
```lua
local newItemFilterMap = {
    ["ARMOR"] = {
        [AIM_SHORTCUT.ItemFilters.ItemKeys.WILDCARD] = {
            Filters = {
                [1] = { Target = "originalTarget" }
            }
        }
    }
}

if AIM_SHORTCUT.ItemFilters:RegisterItemFilterMapPreset(SAMPLE_MOD_UUID, "CustomItemFilterMap", newItemFilterMap) then
    AIM_SHORTCUT.ItemFilters:RegisterItemFilterLookupFunction(SAMPLE_MOD_UUID,
        function(itemFilterMaps, root, item, inventoryHolder)
            local filters = {}
            if itemFilterMaps.ARMOR and Osi.IsEquipable(item) then
                local armorItemFilterMap = itemFilterMaps.ARMOR
                if armorItemFilterMap[item] then
                    table.insert(filters, armorItemFilterMap[item])
                end
                if armorItemFilterMap[AIM_SHORTCUT.ItemFilters.ItemKeys.WILDCARD] then
                    table.insert(filters, armorItemFilterMap[AIM_SHORTCUT.ItemFilters.ItemKeys.WILDCARD])
                end
            end
            return filters
        end
    )
end
```
```

--------------------------------

### Configure Stack Calculation using Equipment Types

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/ItemFilters-CompareFilters

Shows how to use the SELF keyword within equipment filters to aggregate stack amounts across similar armor types. This allows the system to treat different armor categories as a single group for comparison logic.

```json
{
	"ChainShirt" : 
	{
		"Filters" : 
		{
			"1" : 
			{
				"CalculateStackUsing" : 
				{
					"ARMOR_TYPES" : 
					[
						"SELF", "ScaleMail", "HalfPlate"
					]
				},
				"CompareStrategy" : "HIGHER",
				"TargetStat" : "STACK_AMOUNT"
			}
		}
	}
}
```

--------------------------------

### Configure PreFilters for Inventory Management

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

Defines JSON configurations for item prefilters, including stack limits, party member exclusions, and class-based exclusions. These settings determine which items are processed by the inventory manager before applying standard filters.

```json
{
    "STACK_LIMIT_example": {
        "PreFilters": {
            "STACK_LIMIT": 2
        },
        "Filters": [{"Target": "originalTarget"}]
    },
    "EXCLUDE_PARTY_MEMBERS_example": {
        "PreFilters": {
            "EXCLUDE_PARTY_MEMBERS": [
                "S_Player_Laezel_58a69333-40bf-8358-1d17-fff240d7fb12",
                "S_Player_ShadowHeart_3ed74f06-3c60-42dc-83f6-f034cb47c679"
            ]
        },
        "Filters": [{"Target": "originalTarget"}]
    },
    "EXCLUDE_CLASSES_AND_SUBCLASSES_example": {
        "PreFilters": {
            "EXCLUDE_CLASSES_AND_SUBCLASSES": ["Fighter", "Barbarian"]
        },
        "Filters": [{"Target": "originalTarget"}]
    }
}
```

--------------------------------

### Define ItemFilterMaps via JSON

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

Configures item behavior using RootTemplate UUIDs. It supports defining pre-filters for stack limits and complex filtering strategies based on target statistics.

```json
{
    "LOOT_Gold_A_1c3c9c74-34a1-4685-989e-410dc080be6f": {
        "Filters": {
            "1": {
                "CompareStrategy": "HIGHER",
                "TargetStat": "STACK_AMOUNT"
            }
        }
    },
    "ALCH_Solution_Elixir_Meditation_Greater_8c7656f5-507a-4cee-8e15-320c968539f0": {
        "PreFilters": {
            "STACK_LIMIT": 2
        },
        "Filters": {
            "1": {
                "Target": "S_Player_ShadowHeart_3ed74f06-3c60-42dc-83f6-f034cb47c679",
                "RespectEligibility": "true"
            },
            "2": {
                "CompareStrategy": "LOWER",
                "TargetStat": "STACK_AMOUNT"
            }
        }
    }
}
```

--------------------------------

### Register Entity Property Recorders in Lua

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

Registers a callback to document custom fields for entities. This allows mods to inject metadata into the inventory manager's tracking system based on entity state, such as player status or party membership.

```lua
AIM_SHORTCUT.EntityPropertyRecorder:RegisterPropertyRecorders(SAMPLE_MOD_UUID,
    function(entity)
        if Osi.IsPlayer(entity) == 1 then
            local recordEntry = AIM_SHORTCUT.EntityPropertyRecorder:BuildInitialRecordEntry(
                nil,
                { AIM_SHORTCUT.EntityPropertyRecorder.Filters },
                { "CustomField" },
                nil,
                "N/A"
            )

            if Osi.IsPartyMember(entity, 1) == 1 then
                table.insert(
                    recordEntry[AIM_SHORTCUT.EntityPropertyRecorder.CanBeAppliedTo]
                    [AIM_SHORTCUT.EntityPropertyRecorder.ItemFilterMaps],
                    "Tags"
                )
                recordEntry[AIM_SHORTCUT.EntityPropertyRecorder.Value] = "Rando"
            end

            return { ["MyCustomField"] = recordEntry }
        end
    end
)
```

--------------------------------

### Configure PreFilters for Item Distribution

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/ItemFilters-PreFilters

This JSON configuration demonstrates how to apply PreFilters to an item definition. It includes a STACK_LIMIT to prevent overstocking and an EXCLUDE_PARTY_MEMBERS list to skip specific characters.

```json
"HEALING_POTION" : 
{
  "Filters" : [...],
  "PreFilters" : 
  {
    "STACK_LIMIT" : 2,
    "EXCLUDE_PARTY_MEMBERS": ["S_Player_Laezel_58a69333-40bf-8358-1d17-fff240d7fb12", "S_Player_ShadowHeart_3ed74f06-3c60-42dc-83f6-f034cb47c679"]
  }
}
```

--------------------------------

### Configure Custom Stack Calculation via Tags and Roots

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/ItemFilters-CompareFilters

Demonstrates how to define a custom stack calculation for items tagged as HEALING_POTION, including specific root templates like Goodberries. This configuration allows for flexible grouping of items for inventory management purposes.

```json
"HEALING_POTION" : 
{
	"Filters" : 
	{
		"1" : 
		{
			"CalculateStackUsing" : 
			{
				"TAGS" : 
				[
					"HEALING_POTION"
				],
				"ROOTS" : 
				[
					"UNI_CONS_Goodberry"
				]
			},
			"CompareStrategy" : "LOWER",
			"TargetStat" : "STACK_AMOUNT"
		}
	}
}
```

--------------------------------

### Define ItemFilterMaps for Tags and Equipment

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

ItemFilterMaps allow granular control over how items are distributed based on game tags or equipment attributes. These files define comparison strategies and target statistics to determine the optimal party member for a given item.

```json
{
    "HEALING_POTION": {
        "Filters": [
            {
                "CompareStrategy": "LOWER",
                "TargetStat": "HEALTH_PERCENTAGE"
            },
            {
                "CalculateStackUsing": {
                    "TAGS": ["HEALING_POTION"]
                },
                "CompareStrategy": "LOWER",
                "TargetStat": "STACK_AMOUNT"
            }
        ],
        "PreFilters": {
            "STACK_LIMIT": 2
        }
    },
    "LOCKPICKS": {
        "Filters": {
            "1": {
                "CompareStrategy": "HIGHER",
                "TargetStat": "SKILL_TYPE",
                "TargetSubStat": "SleightOfHand"
            },
            "2": {
                "CompareStrategy": "HIGHER",
                "TargetStat": "STACK_AMOUNT"
            }
        }
    }
}
```

```json
{
    "ALL": {
        "Filters": {
            "50": {
                "TargetStat": "HAS_TYPE_EQUIPPED"
            },
            "51": {
                "CompareStrategy": "HIGHER",
                "TargetStat": "STACK_AMOUNT"
            },
            "52": {
                "CalculateStackUsing": {
                    "ARMOR_TYPES": ["SELF"],
                    "EQUIPMENT_TYPES": ["SELF"]
                },
                "CompareStrategy": "HIGHER",
                "TargetStat": "STACK_AMOUNT"
            },
            "53": {
                "TargetStat": "PROFICIENCY"
            }
        }
    }
}
```

--------------------------------

### Register Custom PreFilter Processors (Lua)

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

Allows adding per-stack or per-item prefilters to exclude party members before filter processing. These functions take a content object and a parameter map, returning a filtered list of eligible party members or nil to use the previous list. Usage is demonstrated within an ItemFilterMap.

```lua
AIM_SHORTCUT.PreFilterProcessors:RegisterPerStackPreFilterProcessor(SAMPLE_MOD_UUID,
    "CustomPreFilter-PerStack",
    function(preFilterContent, paramMap) -- paramMap contains: itemFilter, eligiblePartyMembers, item, currentItemStackSize, root, inventoryHolder
        if preFilterContent.isEnabled then
            Ext.Utils.Print("PerStack Pre-Filter is working!")
            return paramMap.eligiblePartyMembers
        end
        return nil
    end
)

AIM_SHORTCUT.PreFilterProcessors:RegisterPerItemPreFilterProcessor(SAMPLE_MOD_UUID,
    "CustomPreFilter-PerItem",
    function(content, paramMap) -- paramMap additionally contains: targetsWithAmountWon
        if not content.amICool then
            Ext.Utils.Print("PerItem Pre-Filter is working!")
            return paramMap.eligiblePartyMembers
        end
    end
)

local newItemFilterMap = {
    ["Tags"] = {
        ["HEALING_POTION"] = {
            PreFilters = {
                ["CustomPreFilter-PerStack"] = { isEnabled = true },
                ["CustomPreFilter-PerItem"] = { amICool = false }
            },
            Filters = {
                [1] = { TargetStat = "HEALTH_PERCENTAGE", CompareStrategy = "LOWER" }
            }
        }
    }
}
```

--------------------------------

### Register Custom Stack Calculators in Lua

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

Extends the STACK_AMOUNT filter logic by registering a custom calculation function. The function receives the item and comparison values, returning a boolean to determine if the item should be included in the stack count.

```lua
AIM_SHORTCUT.ProcessorUtils:RegisterCustomStackCalculator(SAMPLE_MOD_UUID, {
    ["CUSTOM_KEY"] = function(itemInInventory, valuesToCompareAgainst, originalItem)
        for _, valueToCompare in pairs(valuesToCompareAgainst) do
            Ext.Utils.Print("CustomStackCalculator: Value: " .. valueToCompare
                .. " | Item: " .. itemInInventory
                .. " | Original: " .. originalItem)
        end
        return false
    end
})
```

--------------------------------

### AIM Configuration File Structure

Source: https://github.com/osirisofgit/bg3_automatic_inventory_manager/wiki/Quickstart-Guide-5

This JSON snippet illustrates the structure of the `config.json` file for the Automatic Inventory Manager. It shows how active presets, filter presets, and the preset directory are defined.

```json
{
	"PRESETS" : 
	{
		"ACTIVE_PRESETS" : 
		{
			"Automatic_Inventory_Manager-All-Defaults" : 
			[
				"ALL"
			]
		},
		"FILTERS_PRESETS" : 
		{
			"Automatic_Inventory_Manager-All-Defaults" : 
			[
				"RootPartial",
				"Tags",
				"Equipment",
				"Roots",
				"Weapons"
			],
			"Automatic_Inventory_Manager-Camp-Gold-Books" : 
			[
				"RootPartial",
				"Roots",
				"Tags"
			]
		},
		"PRESETS_DIR" : "presets" 
	},
}
```

--------------------------------

### Configure Item Blacklist

Source: https://context7.com/osirisofgit/bg3_automatic_inventory_manager/llms.txt

Defines items, templates, tags, and containers that the Automatic Inventory Manager should ignore. This prevents specific objects from being processed by the automated systems.

```json
{
    "Items": [],
    "RootTemplates": [
        "FOCUSLODESTONES",
        "TMOG",
        "FallenStar_Cons_Wifi",
        "U_AUTOLOOTTOGGLE"
    ],
    "Tags": [],
    "ContainerRoots": [
        "CONT_ISF_Container",
        "TUT_Chest_Potions",
        "TCP_OBJ_TUTORIALCHEST",
        "SYR_OBJ_",
        "DIQ_OBJ_Important_Container",
        "DIQ_OBJ_Clothing_Container",
        "DIQ_OBJ_Dye_Container",
        "DIQ_OBJ_Weapon_Container"
    ]
}
```