# ui_virtual_class 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_kit, 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

## Description

The functions in this library implement various UI hacks to introduce 'virtual' classes and kits, that show up in character generation and on the character sheet the same way as 'real' classes and kits, and to otherwise override the way in which class information is displayed on the character sheet.

## Public functions

add_kit_menu(name:i, desc:i, title:i, trueclass_desc:i, name_strref:i, desc_strref:i, title_strref:i, trueclass_desc_strref:i, id:s, kits:s, class:s)=() action

This creates a kit-selection menu for a given class. All kits in the space-separated list 'kits' (identified by kitlist.2da rownames) for the class 'class' (identified by a class.ids entry) are grouped into their own menu. 'id' is some unique identifier for this menu (use a modder prefix).

'name', 'desc' and 'title' should be the numbers of entries in the currently-loaded tra file. 'name' is the name of the menu itself (displayed in place of a kit name on the parent class's kit menu). 'title' is the name for the submenu (replacing 'Choose Kit'). 'desc' is the description displayed when you click or mouse over the submenu on the main kit-selection screen.

For instance, if you want to gather several dragon disciple kits together, 'name' might be 'Dragon Disciple', 'desc' might be the general description for Dragon Disciples, and 'title' might be 'Choose Dragon' or similar.

add_virtual_class(multiclass:b, name:i, desc:i, name_strref:i, desc_strref:i, ident:s, parent:s, human:s, dwarf:s, elf:s, gnome:s, halfling:s, half_elf:s, halforc:s, all_races:s="true")=() action

This adds a new virtual class to the class-selection menu (to the single-class bit unless multiclass is set to 1). You need to specify a unique string 'ident' to identify the class, and a real class ('parent', an entry in class.ids) as its parent.

You also need a name and description, specifiable either as a tra ref ('name', 'desc') or directly as a strref ('name_strref', 'desc_strref').

By default, the class will be available to all races. To restrict it, set 'all_races' to 'false' and then set each of 'human', 'dwarf' etc to 'true' if you want it available.

assign_kit_to_virtual_class(kit:s, class:s)=() action

The kit 'kit' (a rowname from kitlist.2da) is added to the virtual class 'class' (the unique ID for the class, specified in add_virtual_class). The kit needs to be a legal kit for the parent class of the virtual class, and will now be displayed in the virtual class's kit menu rather than the real class's menu.

exclude_subrace(kit:s, subrace:s)=() action

This forces 'kit' (a rowname entry from kitlist.2da) to prohibit characters of subrace 'subrace' (an ID from the sfo-lua-generated table 'dw_subrace_ids.2da' in dw_shared).

get_virtual_parent_classes()=(virtual_parent_classes:a) action

Parses m_dw_vcd.lua to extract an array of virtual classes, in the form $virtual_parent_class([virtual class id])=[id of first kit included in the class]

override_chargen_kit_name(override:i, use_tra:b=1, kit:s, class:s, lua:s="m_dw_vcd")=() action

This function overrides the name displayed on the character-generation selection screen (but not on the character sheet) for a specific kit, which is specified both by 'kit' (a rowname entry from kitlist.2da) and 'class' (an entry in class.ids).

The integer 'override' specifies the new name. By default it's an entry drawn from the current tra file. If use_tra is set to 0, it's instead a strref.

'lua' lists where the override instruction is stored. (Don't change this off the default unless you know what you're doing and have a very good reason.)

override_class_kit_menu(virtual:b, title_tra:i="-1", class:s, title:s)=() action

This changes the title of a kit-selection menu in character generation. 'Class' should be an entry from class.ids, or the ID of a virtual class (in the latter case, you need to set virtual=1). You can set the title either directly as a string ('title') or indirectly as the tra number of a line in the current tra file ('title_tra').

override_class_kit_menu_setup()=() action

override_kit_desc_data(old_1_strref:i, new_1_strref:i, old_2_strref:i, new_2_strref:i, old_3_strref:i, new_3_strref:i, kit:s, swap:s, old_1:s, new_1:s, old_2:s, new_2:s, old_3:s, new_3:s)=() action

This function overrides the displayed class names on a character's character sheet. Its main use is for multiclass kits, so that the names of the kit components show up instead of the class components. The 'kit' variable (which should be a kitlist 2da rowname) specifies the kit for which the override should be applied.

You can specify the override in several ways. The simplest (which is usually sufficient) is to set 'swap' to a list of class=>kit swaps, e.g. swap="fighter=>kensai thief=>assasin". Here 'class' should be a class.ids entry, and 'kit' should be a kitlist.2da rowname. You can also directly specify strings to be swapped out and in, either by strref (old_[123]_strref is swapped for new_[123]_strref) or directly by string (old_[123] is swapped for new_[123]).

require_gender(kit:s, gender:[male|female])=() action

This forces 'kit' (a rowname entry from kitlist.2da) to require the character to be male or to be female, according to what 'gender' is set to.

set_kit_display_priority(priority:i, kit:s)=() action

This assigns an integer 'priority' to the kit 'kit' (specified by a kitlist.2da rowname). This determines the order in which the kits are displayed at character selection: kits are displayed in increasing order of order priority, with kits that have no order priority displayed last and kits displayed in alphabetical order within each priority.

virtual_class_setup()=() action

Set up the various lua files and menu edits for virtual classes

## Internal functions

These should not be called from outside the library itself.

build_kit_sec_menu()=() action

build_multiclass_menu()=() action

chardesc_sub()=() patch

chargen_class_sub()=() patch

chargen_kit_sub()=() patch

chargen_kit_title_sub()=() patch

get_virtual_class_strrefs()=(multiclass_name:s, multiclass_desc:s, fighter_name:s, mage_name:s, mage_real_name:s, fighter_real_name:s) action