# lib_kit function library

Dependencies: alter_effect, ds, lib_2da, lib_2daq, lib_anon, lib_array, lib_class, lib_cre, lib_data, lib_eff, lib_fn, lib_ids, lib_ietool, lib_ini, lib_script, lib_sfo, lib_spl, lib_splconv, lib_ssl, lib_struct, lib_sugar, lib_tools, lib_ui, lib_vtable, resolve_spell, ui_add_subraces, ui_bonus_spells, ui_deolvynize, ui_detect_class_kit, ui_dual_class_kits, ui_externalize_hlas, ui_externalize_proficiencies, ui_extra_spells, ui_on_open, ui_shared_code, ui_spell_system, ui_system_call, ui_virtual_class

## Description

Functions to make and edit kits, usually by reading them into a WEIDU data structure (the 'vtable' format), editing that structure, and writing back out.

## Public functions

kit_add_clab_mc(kit_ids_entry:i, parent_class:s, primary_class:s, commands:s)=() action

Adds a list of powers to a multiclass kit. Supply: the entry of the kit in kit.ids ('kit_ids_entry'), the kit's parent class (parent_class), the class to which the powers are to be added ('primary_class'), and the list of powers to add ('commands'). 'commands' is a comma-separated list each of whose elements should be of the form 'GA(arg)' or 'AP(arg)', where 'arg' is the usual form of a lib_kit power command, i.e. 'resref first_level', 'resref first_level interval', or 'resref first_level interval last_level'.

kit_apply_powers(arguments:s, struct:s, class:s)=(struct:a) dimorphic

kit_baseline_lua()=() action

Make sure every kit is using a unique LUA entry. (Idempotent.)

kit_clab_initialize()=() action

Wild Mage squats on the core CLABs mages; give them unique entries. Also make sure every clab actually exists

kit_clab_mc_initialize()=() action

kit_copy(debug:b=1, kit:s, edits:s, struct:s=k)=() action

Given kit="old=>new", copy kit 'old' onto kit 'new'. 'old' can be a class instead of a kit, and can be a rowname entry from kitlist or a row label from clastext. This assumes 'new' is a new kit, and doesn't officially support overwriting, i.e. when kit 'new' already exists. (It might work fine but no guarantees.)

'edits' is executed as an anonymous function, which first reads old kit into struct 'struct' (default 'k') and then writes that struct onto the new kit.

kit_copy_from(struct:s, arguments:s, source:s)=(struct:a) dimorphic

Struct function. 'arguments' is a space-separated list of kit-defining 2das. 'source' is another kit, identified via rowname. The values used by that kit are copied over.

kit_edit(edit_strrefs_in_place:b, debug:b, clab_only:i, kit:s, edits:s, struct:s="k")=() action

Edit the kit (or class) 'kit'. (You can also specify a string of kits, and each will be edited, but be careful using this function for bulk minor editing of kits, as it may be faster to edit the relevant 2da directly.) 'kit' should be a rowname entry from kitlist.2da (or a class from class.ids), but we can cope with it being a row entry from clastext.2da instead (e.g. we can cope with ARCHER or ASSASSIN rather than FERALAN or ASSASIN).

'edits' is executed as an anonymous function, which first reads the kit into struct 'struct' (default value 'k') and then writes that struct back.

If 'edit_strrefs_in_place' is set to 1, any strrefs have their values updated, rather than being replaced with new strrefs (use this with caution).

kit_edit_all(edit_strrefs_in_place:b, skip_trueclass:b, clab_only:b, parent_class:s, edits:s, filter:s, struct:s=k)=() action

Apply 'edits' as an edit to all kits with parent class 'parent_class', using the same syntax as 'kit_edit'. If 'skip_trueclass' is set to 0 (the default) also include the parent class itself. If 'filter' is set, apply 'filter' as an SFO function to each (uppercased) kit label, and apply the edit only if the return value is 1. (You can use the anonymous function construct.)

kit_edit_clab(power_array:s, delete_powers:s, clab:s)=() dimorphic

kit_find_class_clab_prefix(class:s)=(prefix:s, clab:s) dimorphic

Given a class, return the CLAB prefix for that class, and also the full unkitted CLAB file for that class.

kit_find_next_ids(to_start:ix4029)=(idsnum:s) action

Find an unused ids entry in kit.ids, and return it in hex format.

kit_find_next_unused_lua(clone:i=1, try_next:i, root:s)=(lua_short:s) dimorphic

Given 'root', find the first unused lua of the form 'LU[root][0-9]', starting from try_next (by default, 0). If clone=1 (default) copy the default version over to the new one. The returned string, 'lua_short', does not include the 'lu'.

kit_find_unused_clab(try_next:i=1, parent_class:s, file_ext:s)=(clab:s) dimorphic

Find an unused clab for the current kit.

kit_get_id(kit:s)=(kit_id:s, found:s) dimorphic

Find the kit_id of a kit. (The left-hand column of kitlist.2da.) Returns a new entry if not found. Also returns 'found' as 1 if found, 0 if not

kit_grant_apply_mc_powers(arguments:s, struct:s, class:s, prefix:s)=(struct:a) dimorphic

kit_grant_powers(arguments:s, struct:s, class:s)=(struct:a) dimorphic

kit_label_original_classes()=() action

kit_match_usability(struct:s, arguments:s)=(struct:a) dimorphic

Struct function. 'arguments' is a kit; the current kit's 'unusable' flag is set to match it

kit_read(clab_only:i, kit:s)=(struct:a) dimorphic

Read the contents of a kit (or the kit part of a class, if 'kit' is a class) into a struct. (This is basically a wrapper for vtable_read, with a bit of extra functionality to support clab editing.)

kit_remove_powers(arguments:s, struct:s)=(struct:a) dimorphic

kit_resolve_spell_applicator(number:i=1, spell:s="null")=(applicator:s) action

Checks a master table (dw_mc_applicators.txt, in data_loc_shared) to see if we have a spell which grants 'spell' 'number' times. If we do, return its resref. If we don't, build it and then return its resref.

kit_set_alignment(struct:s, arguments:s)=(struct:a) dimorphic

Struct function. 'arguments' is a space-separated list of alignments in format 'cg', 'nn', etc. Those and only those alignments are permitted.

kit_set_race_tables(force:b, struct:s, kit:s)=() dimorphic

Given a kit-defining struct, set the race tables to reflect any changes in availability. If force=1, set them whether or not the struct metavariables are set (use this for new/copied kits).

kit_set_table(present:b=1, kit_id:i, table:s)=() dimorphic

Given a k_x_y table (which might not exist), a kit id, and 'present' (a Boolean), add or subtract the kit to/from the table, creating it if necessary

kit_write(is_dummy:b, clab_only:i, edit_strrefs_in_place:b, kit:s, struct:s)=() dimorphic

Write the contents of a struct into (new or existing) kit 'kit'. This includes setting the clab file and the race tables (which are controlled by the 'any_race' and 'human'/'dwarf' (etc) struct variables). If 'edit_strrefs_in_place' is set to 1, any strrefs have their values updated, rather than being replaced with new strrefs (use this with caution). ('is_dummy' just creates a dummy kit; this is used internally).

## Internal functions

These should not be called from outside the library itself.

kit_grant_apply_powers(arguments:s, struct:s, prefix:s)=(struct:a) action