# ds function library

Dependencies: alter_effect, lib_anon, lib_fn, lib_sugar, lib_tools

## Description

Detectable Spells (a shared library with many contributors, developed over many years; see in the file for detailed changelog). Edits spells to set various stats/spellstates, so that AI can detect it.

## Public functions

detectable_spells(fix_khelben:i=1, skip_legacy:i)=() action

Set up detectable spells (allows AI to detect spells; this is a shared set of conventions developed by the modding community). By default, fixes legacy issues in Khelben's Warding Whip caused by (ancient) mods; skip by setting fix_khelben=0. By default, addresses some legacy issues; set skip_legacy=1 to skip.

ds_make_detectable(match_opcode:i="142", match_parameter2:i="-1", stat_value:i=1, complain:i=1, duration:i="-1", id:s, resource:s, match_resource:s="SAME")=(ds_ids_map_stats:a, ds_ids_map_splstate:a) action

The core function in the 'detectable_spells' library. The resource called out is marked so that a given opcode (by default, the icon opcode) is accompanied by a spellstate specified in 'id'.

ds_process_table(complain:i, default_opcode:i=142, table:s, default_stat:s)=(ds_ids_map_stats:a, ds_ids_map_splstate:a) action

Process a table of DS instructions. Possible columns are:

- resource (the thing being patched; compulsory; can be a spell.ids ref, a full resource name, or the resref of a spell or item. If the latter, and if both resref.spl and resref.itm exist, spl is default)
- stat (the stat being assigned; defaults to the default_stat variable)
- stat_value (the value assigned to the stat; defaults to 1)
- match_opcode (the opcode to clone; defaults to 142)
- match_parameter2 (a restriction on which opcode is cloned; defaults to -1, clone all)
- match_resource (a restriction on which opcode is cloned; defaults to SAME, clone all)

Columns can be in any order, but first row must be column headers. Other columns are ignored/

ds_resolve_stat(id:s)=(stat_ind:s, stat_param:s, stat_opcode:s, stat_type:s, ds_ids_map_stats:a, ds_ids_map_splstate:a) patch
ds_resolve_stat(id:s)=(stat_ind:s, stat_param:s, stat_opcode:s, stat_type:s, ds_ids_map_stats:a, ds_ids_map_splstate:a) action

Take the stat 'id' and see if it's already present. If not, add it. Either way, return its value as stat_ind.

By default, we work out where to find/put it heuristically:

- If it's already in stats.ids, we assume it's there and return that value.
- If not, and we're on EE, we return it in splstate.ids.
- If not, and we're on ToBEx, we return it in stats. ids.
- If not, and we're not on EE or ToBex, we give up.

The function gives a little more data: stat_opcode is the opcode used to apply the stat; stat_param is the parameter value used to apply the stat; stat_type is 'stat', 'splstate' or 'null' depending where we put it. (The array returns are for internal use.)

If you enter id as 'splstate:blah' then 'blah' will always be resolved as a splstate (use this when the same id is in stats.ids and splstate.ids)

## Internal functions

These should not be called from outside the library itself.

ds_add_entry(min:i, id:s, file:s)=(stat_ind:s) action
ds_add_entry(min:i, id:s, file:s)=(stat_ind:s) patch

ds_detectable_weapon_enchantment()=() action

ds_fix_khelben()=() action

ds_load_ids(ids:s)=(ids_map:a) action

ds_return_first_entry(list:s)=(entry:s, list:s) patch

ds_set_vars()=(is_tobex:s, enhanced_edition:s) action

ds_sort_ids(ids:s)=() action

ds_stat_entries()=() action

FJ_SPL_ITM_REINDEX()=() patch