Brotor

Rule Hooks

Rules

RuleValue (int)Inputs
XpAward Party XP about to be given amount int
subject object
source int (XP sources)
XpAwardCreature TSL One creature's own award amount int
creature object
source int (XP sources)
StoreBuyPrice Price per unit charged item object
store object
customer object
value int
markup int (%)
stack int
StoreSellPrice Price per unit paid item object
store object
customer object
value int
markdown int (%)
stack int
LevelUpPoints One count a level gives kind int (0 ability, 1 skills, 2 feats, 3 bonus feats, 4 powers, 5 group picks)
class int
classLevel int
totalLevel int
ruleLevel int
intelligence int (base)
path int (0 screens, 1 auto, 2 character creation)
creature object
group string (kind 5)
ItemPropertyAmount An equipped property's amount (penalty negative) property int
subtype int
costValue int
param1Value int
slot int
amount int
item object
creature object
AttackBonus Extra bonus, starts at 0 attacker object
target object
weapon object
offHand int
ranged int
sheet int
feat int (-1 none)
round int
total int
DamageBonus Extra bonus, starts at 0 attacker object
target object
weapon object
offHand int
ranged int
sheet int
feat int (-1 none)
round int
Defense Extra defense, starts at 0 creature object
attacker object
round int
total int
AttackUsesDexterity Melee attack may use Dexterity (1/0) attacker object
target object
weapon object
offHand int
ranged int
sheet int
feat int (-1 none)
round int
dexterity int (modifier)
strength int (modifier)
CriticalThreat Lowest d20 that threatens attacker object
target object
weapon object
offHand int
feat int (-1 none)
threat int (base range)
keen int
CriticalMultiplier Critical multiplier, at least 1 attacker object
target object
weapon object
offHand int
feat int (-1 none)
AttackResult A rolled attack's result (AttackResult values) attacker object
target object
weapon object
offHand int
ranged int
roll int (d20)
attack int (modifier)
defense int
feat int (-1 none)
index int
round int
result int (1 to 4; AttackResult values)
RoundAttacks A round's attack count, per hand creature object
target object
kind int (0 on hand, 1 off hand)
feat int (-1 none)
count int
round int
AttackAnimation A swing's animations.2da row attacker object
target object
weapon object
ranged int
engaged int
feat int (-1 none)
onHand int
offHand int
swing int (0 first)
round int
row int
clip string
UnarmedDamageDice Unarmed dice count or sides creature object
kind int (0 count, 1 sides)
count int
sides int
sheet int
CanDeflect May try to deflect (1/0) shooter object
deflector object
offHand int
round int
canReflect int
DeflectionTotal Deflection roll's total shooter object
deflector object
offHand int
round int
attack int
roll int (d20)
total int
DeflectionResult Deflection roll's result (0 attack goes on, 1 deflected, 2 returned) shooter object
deflector object
offHand int
round int
attack int
roll int (d20)
total int
canReflect int
result int (0 attack goes on, 1 deflected, 2 returned)
DamageReduction Damage reduction takes off target object
attacker object
damage int
power int
level int
limit int
reduction int
HitPointsAfterDamage Hit points after a damage target object
source object
damage int
lost int
hitPoints int (before)
minimum int
SavingThrow Extra save bonus, starts at 0 creature object
versus object
kind int (1 Fortitude, 2 Reflex, 3 Will)
dc int
saveType int
spell int
spellSide int (0 none, 1 light, 2 dark)
source int (-1 screen, 0 script, 1 on-hit property, 2 attack, 3 poison)
sheet int
total int
ReflexAdjustedDamage GetReflexAdjustedDamage's result creature object
versus object
damage int
dc int
saveType int
spell int
saveResult int (0 failed, 1 made, 2 immune)
SkillBonus Extra skill rank, starts at 0 creature object
versus object
skill int
total int
ForceCost Force points a power costs caster object
spell int
partyMember int
cost int
ForceJumpAllowed Force Jump weapon test (1/0) attacker object
target object
weapon object
leftWeapon object
OnHitChance On-hit chance (%) attacker object
target object
item object
subtype int (iprp_onhit row)
costValue int
param1Value int
offHand int
chance int
OnHitSaveDc On-hit save DC attacker object
target object
item object
subtype int (iprp_onhit row)
costValue int
param1Value int
offHand int
dc int
saveKind int
saveType int
OnHitDuration On-hit effect duration in seconds (float) attacker object
target object
item object
subtype int (iprp_onhit row)
costValue int
param1Value int
offHand int
rounds int
seconds float
CanLevelUp May level up (1/0) creature object
totalLevel int
class int
classLevel int
slot int (0 first)
experience int
needed int
LevelUpClassAllowed Level-up may raise this class slot (1/0) creature object
slot int (0 first)
class int
classLevel int
totalLevel int
MovementSpeed Movement rate in m/s (float) creature object
kind int (0 walk, 1 run, 2 stealth walk)
speed float

Events

EventWhenInputs
RoundStarted A combat round started creature object
target object
feat int (-1 none)
round int
onHand int
offHand int
AttackResolved An attack was rolled, before its damage attacker object
target object
result int (AttackResult values)
ranged int
offHand int
index int (0 first)
feat int (-1 none)
damage int (0 on a miss)
round int
Damaged A creature took damage target object
source object
damage int
lost int
hitPoints int (left)
dead int
ForcePointsSpent A cast paid its Force points creature object
spell int
cost int
hitPoints int (paid in HP)
ItemAcquired An item reached a creature item object
owner object
count int
newEntry int (0 a merge)
ItemLost An item left a creature item object
owner object
count int
JournalUpdated A journal entry changed tag string
state int
xp int
source int (0 script, 1 dialogue node)

Dispatches

DispatchWhenOBJECT_SELFInputs
FeatUse A dispatched feat used, in place of its attack user user object
target object
feat int
source int (0 target box, 1 talent script)
ActionEntryShown An action entry's shownIf, as the bar is built (0 hidden, 1 shown, 2 dimmed) leader leader object
entry string (its id)
box int
ActionEntryUse An action entry used leader leader object
entry string (its id)
box int

Patch edits

{ "rule": "XpAward", "script": "dbl_xp_k1" }
{ "event": "Damaged", "script": "my_dmg" }
// Script runs in place of the feat's attack
{ "featUse": 300, "script": "my_burst" }
// Best first; weapons melee, ranged or any
{ "targetFeat": [302, 301, 300], "weapons": "melee" }
// box 0 to 3; name a StrRef or text
{ "actionEntry": "burst", "box": 2, "name": "Burst Fire", "icon": "i_burst", "script": "my_use", "shownIf": "my_show" }
// Feats join it in feat.2da brotor_group
{ "featGroup": "talents", "caption": 48000, "order": 20, "picks": 1, "exclusive": true }
// HasFeat counts the granting feats
{ "featCredential": 100, "grantedBy": [200, 201] }
// 1 to 50
{ "levelCap": 40 }

Functions

K1TSLDeclaration
772877void BrotorSetHeldPose(object oCreature, int nPose);
773878string BrotorGetRuleName();
774879int BrotorGetRuleInt(string sName);
775880float BrotorGetRuleFloat(string sName);
776881object BrotorGetRuleObject(string sName);
777882int BrotorGetRuleValue();
778883float BrotorGetRuleValueFloat();
779884void BrotorSetRuleValue(int nValue);
780885void BrotorSetRuleValueFloat(float fValue);
781886string BrotorGetRuleString(string sName);

Append to nwscript.nss

int BROTOR_POSE_NONE = 0;
int BROTOR_POSE_DISABLED = 1;

void BrotorSetHeldPose(object oCreature, int nPose);
string BrotorGetRuleName();
int BrotorGetRuleInt(string sName);
float BrotorGetRuleFloat(string sName);
object BrotorGetRuleObject(string sName);
int BrotorGetRuleValue();
float BrotorGetRuleValueFloat();
void BrotorSetRuleValue(int nValue);
void BrotorSetRuleValueFloat(float fValue);
string BrotorGetRuleString(string sName);

K1 only: fix function 767 in place

K1's nwscript.nss has an issue where it uses internal names instead of NWScript types for function 767. You can use the provided replacement to resolve this.

void SetAvailableNPCId(INT nNPC, OBJECT_ID oidNPC);   // BROKEN
void SetAvailableNPCId(int nNPC, object oidNPC);      // WORKS

Values

XP sources

0Kill7AwardStealthXP
1GivePlotXP8TSL skill use
2Dialogue plot XP9TSL joining
3AddJournalQuestEntry10Debug console
4Dialogue quest XP11Catch-up (not hooked)
5GiveXPToCreature12TSL AddMultiClass on a creature
6AddMultiClass (party)

Save sources

-1screen
0script
1on-hit property
2attack
3poison

LevelUpPoints kinds

0ability
1skills
2feats
3bonus feats
4powers
5group picks

LevelUpPoints paths

0screens
1auto
2character creation

DeflectionResult values

0attack goes on
1deflected
2returned

AttackResult values

1hit8deflected
2critical9returned
3automatic hit10energy shield
4miss

MovementSpeed kinds

0walk
1run
2stealth walk

shownIf values

0hidden
1shown
2dimmed

Behaviour

Several modsChain in load order, each sees the last value
OBJECT_SELFRules and events: the module, no event context; dispatches: the user or leader
InputsNames ignore case; missing reads 0 / OBJECT_INVALID
Value not setUnchanged
EventsRun after the engine step; setters do nothing
DispatchesFirst mod in load order wins a feat
shownIf can't runEntry hidden
Deferred workRuns after the whole calculation
WaitingNone: value read when the hook returns
Budget32,768 instructions per run; overrun stops only that hook
Errorsscript error: mod ID/FIX (rule NAME)
Same rule inside a hookEngine's plain value, no loop
AI weapon choiceUnhooked
Outside a hookDefaults returned, setters do nothing
Unknown rule, missing scriptFix skipped, logged

Examples

Double XP

double-xp/
  mod.jsonc
  patches/double-xp-k1.jsonc
  patches/double-xp-tsl.jsonc
  assets/dbl_xp_k1.ncs
  assets/dbl_xp_tsl.ncs
// mod.jsonc
{ "format": 1, "id": "double-xp", "game": ["K1", "TSL"], "version": "1.0.0",
  "title": "Double XP", "description": "Doubles XP gain across the board" }

// patches/double-xp-k1.jsonc (TSL: "TSL", dbl_xp_tsl)
{ "title": "Double XP", "description": "Doubles XP gain across the board", "game": ["K1"], "saveLevel": "any",
  "edits": [ { "rule": "XpAward", "script": "dbl_xp_k1" } ] }
// dbl_xp.nss
void main()
{
    BrotorSetRuleValue(BrotorGetRuleValue() * 2);
}

Ranged Dexterity Scaling

{ "rule": "DamageBonus", "script": "rds_dmg" }
void main()
{
    if (BrotorGetRuleInt("ranged"))
        BrotorSetRuleValue(BrotorGetRuleValue()
            + GetAbilityModifier(ABILITY_DEXTERITY, BrotorGetRuleObject("attacker")));
}

Haggling

{ "rule": "StoreBuyPrice", "script": "hgl_price" },
{ "rule": "StoreSellPrice", "script": "hgl_price" }
// 1% better prices per rank of the party's best Persuade, up to 20%
void main()
{
    int nBest = 0;
    int nCount = GetPartyMemberCount();
    int i;
    for (i = 0; i < nCount; i++)
    {
        int nRank = GetSkillRank(SKILL_PERSUADE, GetPartyMemberByIndex(i));
        if (nRank > nBest)
            nBest = nRank;
    }
    if (nBest > 20)
        nBest = 20;

    int nPrice = BrotorGetRuleValue();
    if (BrotorGetRuleName() == "StoreBuyPrice")
        BrotorSetRuleValue(nPrice - nPrice * nBest / 100);
    else
        BrotorSetRuleValue(nPrice + nPrice * nBest / 100);
}