So, first the broad strokes of how the sphere system is implemented. In the IE, divine casters automatically get their spellbooks filled as they level. So, for example, when a normal cleric hits level three:
- The engine checks MXSPLPRS.2da and realizes the cleric can now cast level two spells
- The engine goes looking for files named SPPRxyy, with x being the level and yy being 1-50 (defined in spells.2da)
- The engine checks every one of those spells for restriction flags (e.g. cleric-allowed, good-allowed, etc.).
- If not restricted, the spell is added to the spellbook.
DR instead adds spells to spellbooks directly through a class or kit's CLAB table. The original plan, to apply a single spell to take care of one sphere, failed since we tried to use the learn spell opcode (147)--this granted XP for gaining a spell like a mage using a scroll. Instead we settled on building elaborate tables and then appending long series of stuff like GA_SPPR101, which was messy but functional. We later discovered that using give innate ability (171) would have worked--and v8 has moved back to the original idea using it. Access to the a sphere is now accomplished by applying AP_CDDRxxy at the appropriate level, with xx being a two-letter code for the sphere and y the level. Spell restrictions are preserved by using alignment-targeted EFF files as appropriate.
Previous versions also worked under the assumption that the divine spell tables were unchanged. As of v8, the tables are read dynamically and spells handed out at the appropriate levels based on the current tables. This neatly solves the problem that paladins get up to level six spells in IWDEE and only level three everywhere else, for example, and also means DR doesn't need to worry about the 817 variations of spell progressions in the various tweak mods. This also has the side benefit of fixing the cleric-ranger exploit, where ranger-only spells would be added to the cleric's spellbook as the cleric leveled. Ranger-only spells now only turn up when the ranger levels have earned their addition to the spellbook.
The upshot is a very flexible and extensible system, both for new kits and spells.
HLAs are a little trickier and, at present, not quite as well-implemented, which will be a problem to solve going forward. For now, quest-level spell HLAs are also put into spheres, and then individual HLA tables are built for each kit based on which HLAs are currently present. The tables are no longer overwritten outright; they are instead patched and re-indexed by removing inappropriate HLAs, adding new ones as appropriate, and in most cases non-cleric HLAs are added to offset the reduced selection.
Adding kits to the DR system
If you want your kits to get into the sphere system, there are two macros for you. For kits, code is simple:
ACTION_IF ((MOD_IS_INSTALLED ~DIVINE_REMIX/SETUP-DIVINE_REMIX.TP2~ ~1000~) AND // dr spheres installed (FILE_EXISTS ~divine_remix/lib/macros.tph~)) THEN BEGIN // sanity check for library INCLUDE ~divine_remix/lib/macros.tph~ LAUNCH_ACTION_FUNCTION cd_kit_sphere STR_VAR table = clabpr01 // file name of your kit's clab table class = cleric // allowed values: cleric, paladin, ranger, druid all = none // use major, minor, or none for each sphere (none can be deleted) animal = none astral = none chaos = none charm = none combat = none creation = none divination = none elemental = none elemental_air = none elemental_earth = none elemental_fire = none elemental_water = none guardian = none healing = none law = none necromantic = none necromantic_restorative = none numbers = none plant = none protection = none summoning = none sun = none thoughts = none time = none travelers = none war = none wards = none weather = none END ENDFor example, this is what the mod itself uses to add spheres to Watchers of Helm:
LAUNCH_ACTION_FUNCTION cd_kit_sphere // helm STR_VAR table = clabpr03 class = cleric all = major astral = major combat = major creation = minor divination = major elemental = minor elemental_air = minor elemental_earth = minor elemental_fire = minor elemental_water = minor guardian = major healing = minor protection = major sun = major war = minor wards = major ENDSpheres are set to none by default, so you don't need to list spheres without access. Necromantic is also split between restorative forms only vs. all necromantic to allow for Morninglord's partial access. For full necromantic access, be sure to grant minor/major to both. If you want to radically alter your kit when spherized, like DR's cleric kits, make your changes before the macro.
This macro will do a couple of things. First, it will extend your kit's CLAB table out to level 50, if it isn't already, and then append the spells necessary to populate your kit's spellbook. It will also look up your kit's description from kitlist.2da and extend the kit description with sphere access information. It will also create the necessary lookup tables so that you can apply your kit to creatures in the game and give them the proper spellbook.
Spellbook adjustments for kitted creatures
Once cd_kit_sphere is run, appropriate tables are built to determine allowed spellbooks. Once again, it's simply a matter if invoking a macro:
ACTION_IF ((MOD_IS_INSTALLED ~DIVINE_REMIX/SETUP-DIVINE_REMIX.TP2~ ~1000~) AND // dr spheres installed (FILE_EXISTS ~divine_remix/lib/macros.tph~)) THEN BEGIN // sanity check for library INCLUDE ~divine_remix/lib/macros.tph~ ACTION_FOR_EACH creature IN kpchap01 everard accalia BEGIN ACTION_IF FILE_EXISTS_IN_GAME ~%creature%.cre~ THEN BEGIN COPY_EXISTING ~%creature%.cre~ ~override~ LPF cd_spellbook STR_VAR clab = "foo" END BUT_ONLY END END END"foo" should be replaced with the file name of your kit's CLAB table, e.g. DR's Feywarden kit uses ~A#FEYW~. Known spells that are disallowed simply get deleted--the spellbooks of non-joinables don't matter, and joinables get a spellbook refresh on joining the party. Memorized spells, on the other hand, will get replaced by a random selection from the pool of allowed spells.
Adding spells to the sphere system
Macros are provided once again. Here's an example for some of the IWDification spells:
ACTION_IF ((MOD_IS_INSTALLED ~DIVINE_REMIX/SETUP-DIVINE_REMIX.TP2~ ~1000~) AND // dr spheres installed (FILE_EXISTS ~divine_remix/lib/macros.tph~)) THEN BEGIN // sanity check for library INCLUDE ~divine_remix/lib/macros.tph~ ACTION_CLEAR_ARRAY cd_spheres ACTION_DEFINE_ASSOCIATIVE_ARRAY cd_spheres BEGIN CLERIC_ALICORN_LANCE => an CLERIC_ANIMAL_RAGE => co CLERIC_BEAST_CLAW => co CLERIC_BLOOD_RAGE => co CLERIC_CAUSE_DISEASE => he END OUTER_SET sphere_descript = 1 OUTER_SET hla = 0 LAUNCH_ACTION_MACRO CD_BUILD_SPHERE // now do it again for secondary spheres ACTION_CLEAR_ARRAY cd_spheres ACTION_DEFINE_ASSOCIATIVE_ARRAY cd_spheres BEGIN CLERIC_BEAST_CLAW => ne END OUTER_SET sphere_descript = 2 LAUNCH_ACTION_MACRO CD_BUILD_SPHERE ENDFirst, you need a table that maps a spell's IDS reference to a two-letter code for its sphere (list below). Two variables control how the spell is handled, HLA is set to zero for normal spells, otherwise it's treated as an HLA. At present, spells flagged as HLAs will not really do a lot until an extensible HLA system is developed. The variable sphere_descript takes values of 0-2. A value of 1 will overwrite the existing sphere information on a spell (or add if not present). A setting of 2 will find the existing sphere line and append the selected sphere. So, from the example above, CLERIC_BEAST_CLAW is both a combat and necromantic spell. So it's first run through with sphere_descript = 1, which clears out any existing sphere references and changes the line to Sphere: Combat. Running it through the macro again with sphere_descript = 2 will then append Necromantic to the line, making it read Sphere: Combat, Necromantic. Since I assume most mod-added spells will already have spheres in their descriptions, it's likely that outside of DR itself that non-zero values will be needed for the sphere_descript variable.
The spell will also be added automatically to the appropriate CDDRxxy spell. Alignment restrictions will be looked up and accounted for as appropriate. In the example above, Beast Claw, being a second level spell, would be added to CDDRco2.spl in the first run and CDDRne2.spl on the second. This will automatically add it to the spellbooks of any priest with minor access to combat or necromantic.
Spells from IWDification and Galctygon's beta 6 spell pack are already on the lists.
The complete list of two letter codes:
- al - all
- an - animal
- as - astral
- cs - chaos
- cm - charm
- co - combat
- cr - creation
- di - divination
- ex - elemental (all)
- ea - elemental (air)
- ee - elemental (earth)
- ef - elemental (fire)
- ew - elemental (water)
- gu - guardian
- he - healing
- lw - law
- ne - necromantic
- nr - necromantic (restorative only)
- nu - numbers
- pl - plant
- pr - protection
- su - summong
- sn - sun
- th - thought
- ti - time
- tr - travelers
- wa - war
- wd - wards
- we - weather