;========================================================================================
; Find / Filter =========================================================================
;========================================================================================

; -- Actors --

; Returns an array of actors near the reference. 
; Origin: The object to search around. Note: If the player is not the origin then the player can be included in the results. 
; Count: The number of actors to try to find. 
; Closest: True: Get the closest qualifying actors (actors arranged by closest). False: Random actors.
; MaxDistance: Maximum distance from the player. 0 = No limit.
; FilterFactions: Only return actors that are a member of at least one of these factions.
; ReverseFactFilter: Reverse the faction filter - Return only actors that are not a member of any of the provided factions. 
; FilterRaces: Return only actors whos race is one of these. Empty array = match any. 
; ReverseRaceFilter: False: Return actors matching any FilterRaces race. True: Return actors that don't match any of these races. 
; FilterMods: Only return actors that are defined in these mods. 
; ReverseModFilter: True: Return only actors that are NOT defined in FilterMods. 
; FilterGender: 0: Either, 1: Male only, 2: Female only. Vanilla gender. Creatures are likely male only. 
; FilterCreatures: 0 = Either, 1 = Humanoid only (ActorTypeNpc keyword check), 2 = Creature only
; FilterDead: 0 = Dead or alive, 1: Only alive, 2: Only dead. 
; FilterUnique: 0 = Any, 1 = Unique only, 2 = Non-unique only. 
; FilterChildren: 0 = Any, 1 = No children, 2 = Children only. 
; FilterInScene: 0 = Any, 1 = None in scenes, 2 = Only in scenes. Note: An actor can be in a scene and in active combat at the same time! 
; FilterInCombat: 0 = Any, 1 = None in combat, 2 = Only in combat. 
; FilterHostileToPlayer: 0 = Any, 1 = None with hostile disposition to player, 2 = Only those with hostile disposition. (May or may not be actively hostile)
; FilterCombatWithPlayer: 0 = Any, 1 = Not fighting the player, 2 = Only those fighting the player. (Target = Player)
; FilterSearching: 0 = Any, 1 = Not searching, 2 = Searching only. This is combat/sneaking searching. 
; FilterAlarmed: 0 = Any, 1 = Not alarmed, 2 = Alarmed only. Alarmed = actor confronting the player for crime. (Approach + dialogue)
; ExcludeActors: Exclude any actor in this array from results. 
Actor[] Function FindActorsNearRef(ObjectReference Origin, \
									Int Count, \
									bool Closest = true, \
									Float MaxDistance = 0.0, \
									Faction[] FilterFactions, \
									Bool ReverseFactFilter = false, \
									Race[] FilterRaces, \
									Bool ReverseRaceFilter = false, \
									String[] FilterMods, \
									Bool ReverseModFilter = false, \
									Int FilterGender = 0, \
									Int FilterCreatures = 1, \
									Int FilterDead = 1,\
									Int FilterUnique = 1, \
									Int FilterChildren = 0, \
									Int FilterInScene = 1, \
									Int FilterInCombat = 1, \
									Int FilterHostileToPlayer = 0, \
									Int FilterCombatWithPlayer = 0, \
									Int FilterSearching = 0, \
									Int FilterAlarmed = 0, \
									Actor[] ExcludeActors) Global Native

; Returns an array of actors who's location is designated at akLocation or lower in the location hierarchy.  
; So for example FindActorsInLocation(WhiterunLocation) would find any actor in any Whiterun location or sublocations. 
; And FindActorsInLocation(WhiterunHoldLocation) could find any actor in Whiterun, Riverwood, Rorikstead or any other location that
; is a sublocation of WhiterunHoldLocation. 
; akLocation: Where to pull actors from. Use a broader location to increase the area. SleepingGiantInnLocation < RiverwoodLocation < WhiterunHoldLocation. 
; Count: The number of actors to try to find. 
; FilterFactions: Only return actors that are a member of at least one of these factions.
; ReverseFactFilter: Reverse the faction filter - True: Return only actors that are NOT a member of any of the provided factions. 
; FilterRaces: Return only actors whos race is one of these. Empty array = match any. 
; ReverseRaceFilter: False: Return actors matching any race. True: Return actors that don't match any of these races. 
; FilterMods: Only return actors that are defined in these mods. 
; ReverseModFilter: False: Return only actors defined in FilterMods. True: Return only actors that are NOT defined in FilterMods.
; FilterGender: 0: Either, 1: Male only, 2: Female only. Vanilla gender. Creatures are likely male only. 
; FilterCreatures: 0 = Either, 1 = Humanoid only (ActorTypeNpc keyword check), 2 = Creature only
; FilterDead: 0 = Dead or alive, 1: Only alive, 2: Only dead. 
; FilterUnique: 0 = Any, 1 = Unique only, 2 = Non-unique only. 
; FilterChildren: 0 = Any, 1 = No children, 2 = Children only. 
; FilterInScene: 0 = Any, 1 = None in scenes, 2 = Only in scenes. Note: An actor can be in a scene and in active combat at the same time! 
; FilterInCombat: 0 = Any, 1 = None in combat, 2 = Only in combat. 
; FilterHostileToPlayer: 0 = Any, 1 = None with hostile disposition to player, 2 = Only those with hostile disposition. (May or may not be actively hostile)
; FilterCombatWithPlayer: 0 = Any, 1 = Not fighting the player, 2 = Only those fighting the player. (Target = Player)
; FilterSearching: 0 = Any, 1 = Not searching, 2 = Searching only. This is combat/sneaking searching. 
; FilterAlarmed: 0 = Any, 1 = Not alarmed, 2 = Alarmed only. Alarmed = actor confronting the player for crime. (Approach + dialogue)
; ExcludeActors: Exclude any actor in this array from results. 									
Actor[] Function FindActorsInLocation(Location akLocation, \
										Int Count, \
										Faction[] FilterFactions, \
										Bool ReverseFactFilter = false, \
										Race[] FilterRaces, \
										Bool ReverseRaceFilter = false, \
										String[] FilterMods, \
										Bool ReverseModFilter = false, \
										Int FilterGender = 0, \
										Int FilterCreatures = 1, \
										Int FilterDead = 1, \
										Int FilterUnique = 1, \
										Int FilterChildren = 0, \
										Int FilterInScene = 1, \
										Int FilterInCombat = 1, \
										Int FilterHostileToPlayer = 0, \
										Int FilterCombatWithPlayer = 0, \
										Int FilterSearching = 0, \
										Int FilterAlarmed = 0, \
										Actor[] ExcludeActors) Global Native

; Similar to FindActorsInLocation but returns actors that were placed in the editor at akLocation, whereas
; FindActorsInLocation() works on where the actor currently is. 
Actor[] Function FindActorsByEditorLocation(Location akLocation, \
										Int Count, \
										Faction[] FilterFactions, \
										Bool ReverseFactFilter = false, \
										Race[] FilterRaces, \
										Bool ReverseRaceFilter = false, \
										String[] FilterMods, \
										Bool ReverseModFilter = false, \
										Int FilterGender = 0, \
										Int FilterCreatures = 1, \
										Int FilterDead = 1, \
										Int FilterUnique = 1, \
										Int FilterChildren = 0, \
										Int FilterInScene = 1, \
										Int FilterInCombat = 1, \
										Int FilterHostileToPlayer = 0, \
										Int FilterCombatWithPlayer = 0, \
										Int FilterSearching = 0, \
										Int FilterAlarmed = 0, \
										Actor[] ExcludeActors) Global Native

; Similar to FindActorsByEditorLocation but keys on the Cell the actor was placed in by the editor
; This may only be reliable for interior cells. Exterior cells need testing. 
; GetEditorLocation2 may resolve exterior placements to the parent Worldspace rather than a specific grid Cell, in which case this will not match. 
; akCell: The cell to match against.
; LoadedOnly: 	True - Only scan actors currently in the process lists (cheap). 
;				False - scan every actor ever placed anywhere in the load order (complete, but expensive. Consider caching the result). 
Actor[] Function FindActorsByEditorCell(Cell akCell, \
									Int Count, \
									Bool LoadedOnly = true, \
									Faction[] FilterFactions, \
									Bool ReverseFactFilter = false, \
									Race[] FilterRaces, \
									Bool ReverseRaceFilter = false, \
									String[] FilterMods, \
									Bool ReverseModFilter = false, \
									Int FilterGender = 0, \
									Int FilterCreatures = 1, \
									Int FilterDead = 1, \
									Int FilterUnique = 1, \
									Int FilterChildren = 0, \
									Int FilterInScene = 1, \
									Int FilterInCombat = 1, \
									Int FilterHostileToPlayer = 0, \
									Int FilterCombatWithPlayer = 0, \
									Int FilterSearching = 0, \
									Int FilterAlarmed = 0, \
									Actor[] ExcludeActors) Global Native

; Filters the provided array of actors based on the provided parameters. 
; akActors: The array of actors to be filtered. 
; Closest: True arrange returned actors by distance to the player (shortest to longest). False: Return randomly. 
; MaxDistance: Max distance from the player. 0 = Unlimited.
; akFactions; The array of factions to filter with.
; ReverseFactFilter: false = Return actors in at least one of the factions. True: Return actors NOT in any of these factions. 
; FilterRaces: Return only actors whos race is one of these. Empty array = match any. 
; ReverseRaceFilter: False: Return actors matching any race. True: Return actors that don't match any of these races. 
; FilterMods: Only return actors that are defined in these mods. 
; ReverseModFilter: False: Return only actors defined in FilterMods. True: Return only actors that are NOT defined in FilterMods. 
; FilterGender: 0: Either, 1: Male only, 2: Female only. Vanilla gender. Creatures are likely male only. 
; FilterCreatures: 0 = Any, 1 = Humanoid only (ActorTypeNpc keyword check), 2 = Creatures only.
; FilterDead: 0 = Any, 1 = Alive only, 2 = Dead only.
; FilterUnique: 0 = Any, 1 = Unique only, 2 = Non-unique only.
; FilterChildren: 0 = Any, 1 = No children, 2 = Children only. 
; FilterInScene: 0 = Any, 1 = None in scenes, 2 = Only in scenes. Note: An actor can be in a scene and in active combat at the same time! 
; FilterInCombat: 0 = Any, 1 = None in combat, 2 = Only in combat. 
; FilterHostileToPlayer: 0 = Any, 1 = None with hostile disposition to player, 2 = Only those with hostile disposition. (May or may not be actively hostile)
; FilterCombatWithPlayer: 0 = Any, 1 = Not fighting the player, 2 = Only those fighting the player. (Target = Player)
; FilterSearching: 0 = Any, 1 = Not searching, 2 = Searching only. This is combat/sneaking searching. 
; FilterAlarmed: 0 = Any, 1 = Not alarmed, 2 = Alarmed only. Alarmed = actor confronting the player for crime. (Approach + dialogue)
Actor[] Function FilterActors(Actor[] akActors, \
								Bool Closest = true, \
								Float MaxDistance = 0.0, \
								Faction[] akFactions, \
								Bool ReverseFactFilter = false, \
								Race[] FilterRaces, \
								Bool ReverseRaceFilter = false, \
								String[] FilterMods, \
								Bool ReverseModFilter = false, \
								Int FilterGender = 0, \
								Int FilterCreatures = 1,\
								Int FilterDead = 1, \
								Int FilterUnique = 1, \
								Int FilterChildren = 0, \
								Int FilterInScene = 1, \
								Int FilterInCombat = 1, \
								Int filterHostileToPlayer = 0, \
								Int filterCombatWithPlayer = 0, \
								Int FilterSearching = 0, \
								Int FilterAlarmed = 0) Global Native

; If the actor exists, isn't disabled & isn't dead then returns the actor. If not then returns none.
Actor Function ValidateActor(Actor akActor) Global Native

; Removes any actors that are none, disabled or dead from the input array. 
Actor[] Function ValidateActors(Actor[] akActors) Global Native

; -- Object References --

; Find matching object references in the world around a reference. 
; Origin - Reference to center the search on. 
; Count - The max number of matching objects to try to find. 
; Closest - True: ObjRefs are returned in order of distance from player. False: ObjRefs are randomly picked within MaxDistance. 
; MaxDistance - How far from the player to search. 0.0 = Any distance. 
; FormTypes - Which types of forms to find. See the CK Wiki for 'GetType' for a full list: https://ck.uesp.net/wiki/GetType_-_Form
; 				Empty FormTypes array = match any form type. 
; akKwds - The ObjRef's base object must have at least one of these keywords. Empty array = match anything. 
; ReverseKwds - Reverses the keyword filter. False: normal. True: Return only objects that DON'T have any of these keywords. 
; IncludeForms - ObjRef's base object must be one of these to pass. Empty array = match anything. A form in both IncludeForms & ExcludeForms will be excluded. 
; ExcludeForms - Exclude specific forms from search results. 
; MinGold - Object base must be worth at least this. -1 = No minimum. 
; MaxGold - Object base must be worth at most this. -1 = No maximum. 
; MinWeight - Object must weight at least this. -1.0 = No Minimum. 
; MaxWeight - Object must weigh at most this. -1.0 = No maximum. 
; Ownership - 0: Any, 1: Unowned only, 2: Owned only. 
; ExcludeQuestItems - False: Any items. True: Filter out quest references. 
ObjectReference[] Function FindObjRefsNearRef(ObjectReference Origin, \
												Int Count, \
												Bool Closest = true, \
												Float MaxDistance = 0.0, \
												Int[] FormTypes, \
												Keyword[] akKwds, \
												Bool ReverseKwds = false, \
												Form[] IncludeForms, \
												Form[] ExcludeForms, \
												Bool IncludeDisabled = false, \
												Int MinGold = -1, \
												Int MaxGold = -1, \
												Float MinWeight = -1.0, \
												Float MaxWeight = -1.0, \
												Int Ownership = 0, \
												Bool ExcludeQuestItems = True) Global Native

; Find all object references at this location whose base object matches any form in akForms. 
; akLoc - Where to search. 
; akForms - A list of forms to match. 
; IncludeChildLocs - False: Only objrefs from exactly akLoc only. True: Also check any sublocation. 
; IncludeDisabled - False: Don't include disabled reference. True: References can be enabled or disabled. 
; Note: If checking a location that is unloaded then only persistent reference will be returned. 
ObjectReference[] Function FindAllObjRefsLikeAtLoc(Location akLoc, Form[] akForms, Bool IncludeChildLocs, Bool IncludeDisabled) Global Native

; If the reference exists, isn't disabled or dead (actors only), returns the actor. If not then returns none.
ObjectReference Function ValidateRef(ObjectReference akRef) Global Native

; Removes any refs that are none, disabled or dead (actors only) from the input array. 
ObjectReference[] Function ValidateRefs(ObjectReference[] akRefs) Global Native

; -- Forms (Generic) --

; Returns a list of all forms of type 'FormType' that have keyword akKeyword. 
; FormType - The type of forms to get. See: https://ck.uesp.net/wiki/GetType_-_Form
; akKeyword - The keywords to filter with. Pass an empty array to skip keyword filtering. 
; RequireAllKeywords  - If true, form must have ALL keywords. If false, ANY keyword matches.
; ReverseKeywordFilter - If true, excludes forms that pass the keyword check instead of including them.
; ModFilter           - List of mod/plugin name substrings to filter by (e.g. "Skyrim.esm", "MyMod"). Pass empty array to skip.
; ReverseModFilter    - If true, excludes forms originating from matched mods instead of including them.
; NameFilter          - List of strings to substring match against the form's name. Pass an empty array to skip. 
; ReverseNameFilter   - If true, excludes forms whose name matches instead of including them.
; EditorIDFilter      - List of strings to substring match against the form's editor ID. Pass empty array to skip. 
; ReverseEditorIDFilter - If true, excludes forms whose EditorID matches instead of including them.
; FormListFilter      - Only include (or exclude) forms present in this FormList. Pass None to skip.
; ReverseFormListFilter - If true, excludes forms found in the FormList instead of including them.
; FilterUnplayable    - If true, excludes forms flagged as non-playable (where applicable).
; FilterUnnamed       - If true, excludes inventory type forms (Armor, Weapon, Potion, MiscObject etc) with an empty name.
; FilterEnchanted - Filter by enchantment status. 0 - Any. 1 - Unenchanted only. 2 - Only enchanted. No effect on non-enchantable forms. 
Form[] Function FindForms(int FormType, \
							Keyword[] akKeywords, \
							Bool RequireAllKeywords = False, \
							Bool ReverseKeywordFilter = False, \
							String[] ModFilter, \
							Bool ReverseModFilter = False, \
							String[] NameFilter, \
							Bool ReverseNameFilter = False, \
							String[] EditorIDFilter, \
							Bool ReverseEditorIDFilter = False, \
							FormList FormListFilter = None, \
							Bool ReverseFormListFilter = True, \
							Bool FilterUnplayable = True, \
							Bool FilterUnnamed = True, \
							Int FilterEnchanted = 1) Global Native

; Same as FindForms() but instead fills akList with the forms. Better if you expect a large number of forms. 
; The formlist is not cleared first. Function is additive. 
Int Function FindFormsToList(FormList akList, \
							Int FormType, \
							Keyword[] akKeywords, \
							Bool RequireAllKeywords = False, \
							Bool ReverseKeywordFilter = False, \
							String[] ModFilter, \
							Bool ReverseModFilter = False, \
							String[] NameFilter, \
							Bool ReverseNameFilter = False, \
							String[] EditorIDFilter, \
							Bool ReverseEditorIDFilter = False, \
							FormList FormListFilter = None, \
							Bool ReverseFormListFilter = True, \
							Bool FilterUnplayable = True, \
							Bool FilterUnnamed = True, \
							Int FilterEnchanted = 1) Global native

; Filter the input array of forms for any keyword in akKwds. 
; Input - The input array of forms. 
; akKwds - The list of keywords to match. 
; ReverseFilter - Reverse the keyword filter.
;				False: Return any form that has any keyword in akKwds. 
;				True: Return any form that has none of the keywords in akKwd. 
Form[] Function FilterFormsByKeywords(Form[] Input, Keyword[] akKwds, Bool ReverseFilter = False) Global Native

; -- Armor --

; Returns an array of armors matching your search criteria. 
; akKwds - Keywords to match. 
; ExcludeKwds - Armor must have NONE of these keywords. 
; Slots - Armor must occupy at least ONE of these slots (empty = no slot filter). 
; MatchNames - Armor name must contain at least ONE of these strings (empty = no filter). 
; ExcludeNames - Armor name must NOT contain any of these strings (empty = no filter). 
; FilterEnchanted - Filter by enchantment status. 0 - Any. 1 - Unenchanted only. 2 - Only enchanted. 
; MatchAnyKwd - If true, armor needs ANY required keyword. If false, armor needs ALL required keywords. 
; FilterUnnamed - Filter any items that don't have any name (These are typically hidden inventory items)
Armor[] Function FindArmor(Keyword[] akKwds, \
							Keyword[] ExcludeKwds, \
							Int[] Slots, \
							String[] MatchNames, \
							String[] ExcludeNames, \
							Int FilterEnchanted = 1, \
							Bool MatchAnyKwd = true, \
							Bool FilterUnnamed = true) Global Native

; Populates the provided formlist with armors matching your provided criteria. Returns the number of armors added to the formlist. 
; akFormList - The formlist to add matching armors to.
; akKwds - Keywords to match.
; ExcludeKwds - Armor must have NONE of these keywords.
; Slots - Armor must occupy at least ONE of these slots (empty = no slot filter).
; MatchNames - Armor name must contain at least ONE of these strings (empty = no filter).
; ExcludeNames - Armor name must NOT contain any of these strings (empty = no filter).
; FilterEnchanted - Filter by enchantment status. 0 - Any. 1 - Unenchanted only. 2 - Only enchanted. 
; MatchAnyKwd - If true, armor needs ANY required keyword. If false, armor needs ALL required keywords.
; ClearFormList - Whether to clear the formlist before adding. True: Clear formlist. False: Add to formlist. 
; FilterUnnamed - Filter any items that don't have any name (These are typically hidden inventory items)
Int Function FindArmorToList(FormList akFormList, \
								Keyword[] akKwds, \
								Keyword[] ExcludeKwds, \
								Int[] Slots, \
								String[] MatchNames, \
								String[] ExcludeNames, \
								Int FilterEnchanted = 1, \
								Bool MatchAnyKwd = true, \
								Bool ClearFormList = false, \
								Bool FilterUnnamed = true) Global Native

; Filter a given armor array. 
; akKwds - Keywords to match.
; ExcludeKwds - Armor must have NONE of these keywords.
; Slots - Armor must occupy at least ONE of these slots (empty = no slot filter).
; MatchNames - Armor name must contain at least ONE of these strings (empty = no filter).
; ExcludeNames - Armor name must NOT contain any of these strings (empty = no filter).
; MatchAnyKwd - If true, armor needs ANY required keyword. If false, armor needs ALL required keywords.
; FilterUnnamed - Filter any items that don't have any name (These are typically hidden inventory items)
Armor[] Function FilterArmors(Armor[] InputArmors, \
								Keyword[] akKwds, \
								Keyword[] ExcludeKwds, \
								Int[] Slots, \
								String[] MatchNames, \
								String[] ExcludeNames, \
								Int FilterEnchanted = 1, \
								Bool MatchAnyKwd = true, \
								Bool filterUnnamed = true) Global Native

; -- Locations --

; Returns all Location forms matching the given filters.
; akKeywords - Keywords to filter by. Empty array = no keyword filtering.
; RequireAllKeywords - True: Location must have ALL keywords. False: ANY keyword matches.
; ExcludeKeywords - Location is rejected if it has ANY of these. 
; ModFilter - List of mod/plugin name substrings to filter by. Empty array = skip.
; ReverseModFilter - True: Exclude locations from matched mods instead of including them.
; NameFilter - Substrings to match against the location's full name. Empty array = skip.
; ReverseNameFilter - True: Exclude locations whose name matches instead of including them.
; EditorIDFilter - Substrings to match against the location's EditorID. Empty array = skip.
; ReverseEditorIDFilter - True: exclude locations whose EditorID matches instead of including them.
; FormListFilter - Only include (or exclude) locations present in this FormList. None = skip.
; ReverseFormListFilter - True: Exclude locations found in the FormList instead of including them.
; WorldspaceFilter - Only include (or exclude) locations resolving into this worldspace (via center/horse marker, then parentLoc chain). None = skip.
; ReverseWorldspaceFilter - True: Exclude locations resolving into WorldspaceFilter instead of including them.
Location[] Function GetLocationsOfType(Keyword[] akKeywords, \
                        Bool RequireAllKeywords = False, \
                        Keyword[] ExcludeKeywords, \
                        String[] ModFilter, \
                        Bool ReverseModFilter = False, \
                        String[] NameFilter, \
                        Bool ReverseNameFilter = False, \
                        String[] EditorIDFilter, \
                        Bool ReverseEditorIDFilter = False, \
                        FormList FormListFilter = None, \
                        Bool ReverseFormListFilter = True, \
                        WorldSpace WorldspaceFilter = None, \
                        Bool ReverseWorldspaceFilter = False) Global Native

; -- Food --

; Returns a list of food items that have 'consume sound' set as any of 'ConsumptionSounds'. 
; 'Potion' must have it's 'Food flag' set to first be considered as a food item and not a potion. 
; ConsumptionSounds: A list of sounds the food must use to be returned. 
; FilterMods: Only return forms from the listed mods. 
; ReverseModFilter: False = Return only forms from FilterMods. True = Return only forms from mods that are NOT in FilterMods. 
; IncludeNull: True = Include food items that have no consumption sound set. False = Don't include items without a consumption sound set. 
Form[] Function GetFoodItems(Form[] ConsumptionSounds, Bool IncludeNull, String[] FilterMods, Bool ReverseModFilter = false) Global Native

; Same as GetFoodItems but instead adds all found items to akList. 
; Does not clear the list first (Results are additive). 
Int Function AddFoodItemsToList(Formlist akList, Form[] ConsumptionSounds, Bool IncludeNull, String[] FilterMods, Bool ReverseModFilter = false) Global Native

; -- Actor Skeleton --

; Return any nodes matching any string in NodeNames. 
; MatchSubstring: False - exact matches only. True - partial matches. 
String[] Function FindNodesWithNames(Actor akActor, String[] NodeNames, Bool MatchSubstring = true) Global Native

; Returns a string list of all nodes in akActor's skeleton. 
String[] Function GetAllNodeNames(Actor akActor) Global Native