Learn Spells Hooks

When a character is created, the player selects spells that the character can 'LEARN' later in the game. This list of spells is called the 'Knowable' list. At various times in the game, the player is allowed to move certain spells from the 'Knowable' list to the character's spellbook. This process is called 'Learning Spells'. The engine calls two hooks: one to control the number of spells that can be Learned at each spell level and the other to determine which spells can be Learned.

Hook – “LearnSpell”

You probably will not need to implement this hook. If the character is allowed to learn any of the spells in the 'Knowable List' then you can take advantage of the fact that the default result is 100 percent. If a certain spell cannot be learned until, for example, the character has obtained a slice of provolone cheese, then this hook might be attached to such a spell and might adjust the probability as a function of the cheese's ripeness.

This hook is called for each spell in the character's 'Knowable List'. The hook provides the probability of the spell being successfully learned.

Search Order

1. The character's class

2. The spell

Context

1. Class of created character

2. The spell

3. The character

Parameters

• Hook Parameter 5 is the character's INT value.

• Hook Parameter 6 is the spell's level.

This hook is called for every 'Knowable' spell. That can be a lot of spells so you probably don't want your scripts to be very long.

First we call the 'Class' scripts. If the result is an empty string then we call any 'Spell' scripts.

The final script result is examined and if it is non-empty then it is used as the percentage chance of success. For example, if the result is “85”, then the spell acquisition will succeed 85 times out of 100.

If the final result is empty, then the chance of success will be 100 percent.

If the final result is zero, then the spell is not displayed to the player.

Hook – “LearnSpellsNum”

When the character is allowed to “Learn” spells (transfer spells from the 'Knowable List' to the spellbook), the engine calls this hook for each possible spell level. The hook provides two pieces of information for each spell level:

1. The total number of spells that can be in the spellbook at each level.

2. The number of spells that can be learned with certainty at each level.

This hook is called when:

• The player is asked to select the initial spell complement for a newly created character. The 'Circumstance Code' will be “I” (for “I”nitial spells).

• When a character gains a new spell-casting level. In this case the 'Circumstance Code' is set to 'L'.

• Other occasions.....not yet defined.

Search Order

1. The character's class

Context

1. Class of created character

2. The character

Parameters

• Hook Parameter 4 is the 'Circumstance Code'. See discussion above.

• Hook Parameter 5 is the character's INT value.

• Hook Parameter 6 is the spell level. Note that spell level zero is special.

• Hook Parameter 7 is the number of spells already in the spellbook at this level

• Hook Parameter 8 = 3 (modifiable....total number of spells that can be in the spellbook at this level)

• Hook Parameter 9 = 0 (modifiable … number of additional spells at this level that can be learned with certainty)

This hook is called to determine the number of spells that the character can learn at each spell level and the number of spells that the character can learn at each spell level with a probability of 100 percent.

The hook should supply a result in hook parameters [8] and [9]. Hook parameter [8] is initially set to 3 and should be modified to the desired maximum. Hook parameter [9] is initially set to 0 and should be modified to the desired number of spell that the character can acquire with 100 percent probability (called the 'certainty'). Spell level zero is used to determine the total number of spells that the characer can learn. For spell level zero, parameter [8] is initially set to “0” (which allows an unlimited total number of spells) and if the hook changes it to any other number then it will be used to determine the maximum total number of spells that can be learned. For example, the character might be able to learn 2 level one spells and 2 level 2 spells but only 2 spells in total. Then he could learn one of each level or two of any one level.

First we call the 'Class' scripts and use the (possibly modified) hook parameters. The final results will be limited to reasonable integers:

parameter[8] = max(parameter[8], 0)

parameter[9] = max (parameter[9], 0)

The spells which can be learned are presented to the player one level at a time. When a spell is successfully 'Learned', it is removed from the 'Knowable' list. If a spell is selected but fails to be learned, it remains in the 'Knowable List' but is not longer displayed for selection.

The list of 'Knowable' spells is kept in the character's ASL named “$KnowableSpells$ in the form of a delimited string containing the spells' unique names. For example:

“?Bless|Dork?Heal|Just Once?Levitate”

Your scripts can examine and modify this list. But any modification by the two hooks described on this page will be overwritten when the Learning process is complete.