WeiDU functions: ADD_KIT_EX and GET_KIT_EX

This project aims at unifying WeiDU's built-in functions ADD_KIT and COPY_KIT as well as the complementary functions fl#add_kit_ee and qd_multiclass.

ADD_KIT_EX

Overview

ADD_KIT_EX allows you to add new kits to the game or create copies of existing kits. In both cases it is possible to alter selected attributes of the kit and let the function derive the remaining information either from a specified source kit or the kit's parent class. The function provides full support for both classic and EE games.

The following games are currently supported: BG2 (with or without ToB), Tutu, BGT, BG:EE (with or without SoD), BG2:EE, EET, IWD:EE and PST:EE*. TobEx and GemRB are considered when detected.

(*) PST:EE does theoretically support kits, but lacks the necessary files.

Notes:
Adding the kit name to any of the specified 2DA strings is optional. It will be included automatically if needed.

Unless stated otherwise, if no value is provided for one or more of the optional parameters, the corresponding value of a given source kit or the parent class (in that order) will be copied and used for this kit if needed.

Missing entries in specified 2da strings will be filled with sane default values if needed.

Important:
ADD_KIT_EX requires WeiDU version 247 or later to work correctly.

Diagnostic parameters for general use:

Experimental parameters for testing purposes only:

Multiclass Kits

Enhanced Edition games since version 2.0 allow you to create true multiclass kits. However, the way how multiclass kits are handled by the game engine requires additional effort to properly deal with kit-specific abilities.

ADD_KIT_EX provides two ways to control which class aspect of a multiclass kit is used to apply kit-specific abilities:

1) Specify parameters base_class and clab_path:
base_class controls the class aspect used to apply the kit abilities defined in the table specified by clab_path. For this reason it is necessary to specify a class aspect that is covered by the kit's parent multiclass.
The following single-letter class tokens are supported by base_class: F (for Fighter class), P (for Priest class), D (for Druid class), R (for Ranger class), M (for Mage class) and T (for Thief class). Alternatively, specify one of the symbolic class names: FIGHTER, CLERIC, DRUID, RANGER, MAGE or THIEF. Numeric class values are supported as well.

2) Specify any of the clab_base_X parameters:
The clab_base_X parameters can be used to set a class ability table for a specific base class. That way it is possible to assign different ability tables to individual class aspects of a multiclass kit. "X" indicates the base class token for [f]ighter, [p]riest, [d]ruid, [r]anger, [m]age and [t]hief.
For example, for a kit based on the Fighter/Mage/Thief class you can use clab_base_f, clab_base_m and clab_base_t to assign individual ability tables to the fighter, mage and thief class aspect respectively.

Alternatively, it is also possible to override the base class by preceding CLAB table entries with a class token. This token allows you to fine-tune which ability will be applied by which class at level up. For example, to specifically assign the CLAB entry GA_SPCL423 to the thief class aspect (e.g. of a multiclass Fighter/Thief kit), precede it with T to create TGA_SPCL423.

This feature is very versatile, and can be used in a variety of scenarios. Some of the things it can do include:

• giving a kit to a multiclass character at character creation (e.g. Swashbuckler/Mage).
• allowing a multiclass character to have one kit for each of their classes (e.g. a Berserker/Priest of Talos).
• allowing modders to implement their own multiclass kits that have abilities tied to each of the base classes (e.g. the Bladesinger Fighter/Mage kit).
• allowing a single- or multiclass character to gain the benefits of multiple kits of the same class.

Limitations:

Only benefits granted by the class ability table are considered. Item restrictions, inherent abilities of specialist mages or other effects tied to the kit's usability flags are not covered.

Due to the length restrictions on internal names, ADD_KIT_EX can only include abilities that have internal names of 7 characters or less. Abilities with internal names of 8 characters (or more) will be skipped with warnings.

Usage

Launch ADD_KIT_EX via LAUNCH_ACTION_FUNCTION and specify the parameters you want to have set or changed.

Example of a minimalistic kit definition:

LAUNCH_ACTION_FUNCTION ADD_KIT_EX
  INT_VAR
    kit_class = 4   // Parent class: Thief
    mixed     = RESOLVE_STR_REF(~Adventurer~)
    lower     = RESOLVE_STR_REF(~adventurer~)   // Not strictly necessary: will be auto-generated if omitted
    help      = RESOLVE_STR_REF(~ADVENTURER: A jack-of-all-trades...~)  // Not strictly necessary: Parent class
                                                                        // description will be used if omitted
  STR_VAR
    kit_name  = "ADVENTURER"
  RET
    kit_id
END

This function call will install a new Thief kit called "Adventurer". Omitted attributes will be derived from the kit's base class if needed. At successful execution the kit will be installed and can be identified by the numeric value returned by the "kit_id" parameter.

GET_KIT_EX

See function description here: readme-get_kit_ex.txt