Rule Hooks
Rules
| Rule | Value (int) | Inputs |
|---|---|---|
XpAward |
Party XP about to be given | amount intsubject objectsource int (XP sources) |
XpAwardCreature TSL |
One creature's own award | amount intcreature objectsource int (XP sources) |
StoreBuyPrice |
Price per unit charged | item objectstore objectcustomer objectvalue intmarkup int (%)stack int |
StoreSellPrice |
Price per unit paid | item objectstore objectcustomer objectvalue intmarkdown 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 intclassLevel inttotalLevel intruleLevel intintelligence int (base)path int (0 screens, 1 auto, 2 character creation)creature objectgroup string (kind 5) |
ItemPropertyAmount |
An equipped property's amount (penalty negative) | property intsubtype intcostValue intparam1Value intslot intamount intitem objectcreature object |
AttackBonus |
Extra bonus, starts at 0 | attacker objecttarget objectweapon objectoffHand intranged intsheet intfeat int (-1 none)round inttotal int |
DamageBonus |
Extra bonus, starts at 0 | attacker objecttarget objectweapon objectoffHand intranged intsheet intfeat int (-1 none)round int |
Defense |
Extra defense, starts at 0 | creature objectattacker objectround inttotal int |
AttackUsesDexterity |
Melee attack may use Dexterity (1/0) | attacker objecttarget objectweapon objectoffHand intranged intsheet intfeat int (-1 none)round intdexterity int (modifier)strength int (modifier) |
CriticalThreat |
Lowest d20 that threatens | attacker objecttarget objectweapon objectoffHand intfeat int (-1 none)threat int (base range)keen int |
CriticalMultiplier |
Critical multiplier, at least 1 | attacker objecttarget objectweapon objectoffHand intfeat int (-1 none) |
AttackResult |
A rolled attack's result (AttackResult values) | attacker objecttarget objectweapon objectoffHand intranged introll int (d20)attack int (modifier)defense intfeat int (-1 none)index intround intresult int (1 to 4; AttackResult values) |
RoundAttacks |
A round's attack count, per hand | creature objecttarget objectkind int (0 on hand, 1 off hand)feat int (-1 none)count intround int |
AttackAnimation |
A swing's animations.2da row | attacker objecttarget objectweapon objectranged intengaged intfeat int (-1 none)onHand intoffHand intswing int (0 first)round introw intclip string |
UnarmedDamageDice |
Unarmed dice count or sides | creature objectkind int (0 count, 1 sides)count intsides intsheet int |
CanDeflect |
May try to deflect (1/0) | shooter objectdeflector objectoffHand intround intcanReflect int |
DeflectionTotal |
Deflection roll's total | shooter objectdeflector objectoffHand intround intattack introll int (d20)total int |
DeflectionResult |
Deflection roll's result (0 attack goes on, 1 deflected, 2 returned) | shooter objectdeflector objectoffHand intround intattack introll int (d20)total intcanReflect intresult int (0 attack goes on, 1 deflected, 2 returned) |
DamageReduction |
Damage reduction takes off | target objectattacker objectdamage intpower intlevel intlimit intreduction int |
HitPointsAfterDamage |
Hit points after a damage | target objectsource objectdamage intlost inthitPoints int (before)minimum int |
SavingThrow |
Extra save bonus, starts at 0 | creature objectversus objectkind int (1 Fortitude, 2 Reflex, 3 Will)dc intsaveType intspell intspellSide int (0 none, 1 light, 2 dark)source int (-1 screen, 0 script, 1 on-hit property, 2 attack, 3 poison)sheet inttotal int |
ReflexAdjustedDamage |
GetReflexAdjustedDamage's result | creature objectversus objectdamage intdc intsaveType intspell intsaveResult int (0 failed, 1 made, 2 immune) |
SkillBonus |
Extra skill rank, starts at 0 | creature objectversus objectskill inttotal int |
ForceCost |
Force points a power costs | caster objectspell intpartyMember intcost int |
ForceJumpAllowed |
Force Jump weapon test (1/0) | attacker objecttarget objectweapon objectleftWeapon object |
OnHitChance |
On-hit chance (%) | attacker objecttarget objectitem objectsubtype int (iprp_onhit row)costValue intparam1Value intoffHand intchance int |
OnHitSaveDc |
On-hit save DC | attacker objecttarget objectitem objectsubtype int (iprp_onhit row)costValue intparam1Value intoffHand intdc intsaveKind intsaveType int |
OnHitDuration |
On-hit effect duration in seconds (float) | attacker objecttarget objectitem objectsubtype int (iprp_onhit row)costValue intparam1Value intoffHand introunds intseconds float |
CanLevelUp |
May level up (1/0) | creature objecttotalLevel intclass intclassLevel intslot int (0 first)experience intneeded int |
LevelUpClassAllowed |
Level-up may raise this class slot (1/0) | creature objectslot int (0 first)class intclassLevel inttotalLevel int |
MovementSpeed |
Movement rate in m/s (float) | creature objectkind int (0 walk, 1 run, 2 stealth walk)speed float |
Events
| Event | When | Inputs |
|---|---|---|
RoundStarted |
A combat round started | creature objecttarget objectfeat int (-1 none)round intonHand intoffHand int |
AttackResolved |
An attack was rolled, before its damage | attacker objecttarget objectresult int (AttackResult values)ranged intoffHand intindex int (0 first)feat int (-1 none)damage int (0 on a miss)round int |
Damaged |
A creature took damage | target objectsource objectdamage intlost inthitPoints int (left)dead int |
ForcePointsSpent |
A cast paid its Force points | creature objectspell intcost inthitPoints int (paid in HP) |
ItemAcquired |
An item reached a creature | item objectowner objectcount intnewEntry int (0 a merge) |
ItemLost |
An item left a creature | item objectowner objectcount int |
JournalUpdated |
A journal entry changed | tag stringstate intxp intsource int (0 script, 1 dialogue node) |
Dispatches
| Dispatch | When | OBJECT_SELF | Inputs |
|---|---|---|---|
FeatUse |
A dispatched feat used, in place of its attack | user | user objecttarget objectfeat intsource 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 objectentry string (its id)box int |
ActionEntryUse |
An action entry used | leader | leader objectentry 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
| K1 | TSL | Declaration |
|---|---|---|
| 772 | 877 | void BrotorSetHeldPose(object oCreature, int nPose); |
| 773 | 878 | string BrotorGetRuleName(); |
| 774 | 879 | int BrotorGetRuleInt(string sName); |
| 775 | 880 | float BrotorGetRuleFloat(string sName); |
| 776 | 881 | object BrotorGetRuleObject(string sName); |
| 777 | 882 | int BrotorGetRuleValue(); |
| 778 | 883 | float BrotorGetRuleValueFloat(); |
| 779 | 884 | void BrotorSetRuleValue(int nValue); |
| 780 | 885 | void BrotorSetRuleValueFloat(float fValue); |
| 781 | 886 | string 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
| 0 | Kill | 7 | AwardStealthXP |
| 1 | GivePlotXP | 8 | TSL skill use |
| 2 | Dialogue plot XP | 9 | TSL joining |
| 3 | AddJournalQuestEntry | 10 | Debug console |
| 4 | Dialogue quest XP | 11 | Catch-up (not hooked) |
| 5 | GiveXPToCreature | 12 | TSL AddMultiClass on a creature |
| 6 | AddMultiClass (party) |
Save sources
| -1 | screen |
| 0 | script |
| 1 | on-hit property |
| 2 | attack |
| 3 | poison |
LevelUpPoints kinds
| 0 | ability |
| 1 | skills |
| 2 | feats |
| 3 | bonus feats |
| 4 | powers |
| 5 | group picks |
LevelUpPoints paths
| 0 | screens |
| 1 | auto |
| 2 | character creation |
DeflectionResult values
| 0 | attack goes on |
| 1 | deflected |
| 2 | returned |
AttackResult values
| 1 | hit | 8 | deflected |
| 2 | critical | 9 | returned |
| 3 | automatic hit | 10 | energy shield |
| 4 | miss |
MovementSpeed kinds
| 0 | walk |
| 1 | run |
| 2 | stealth walk |
shownIf values
| 0 | hidden |
| 1 | shown |
| 2 | dimmed |
Behaviour
| Several mods | Chain in load order, each sees the last value |
|---|---|
| OBJECT_SELF | Rules and events: the module, no event context; dispatches: the user or leader |
| Inputs | Names ignore case; missing reads 0 / OBJECT_INVALID |
| Value not set | Unchanged |
| Events | Run after the engine step; setters do nothing |
| Dispatches | First mod in load order wins a feat |
| shownIf can't run | Entry hidden |
| Deferred work | Runs after the whole calculation |
| Waiting | None: value read when the hook returns |
| Budget | 32,768 instructions per run; overrun stops only that hook |
| Errors | script error: mod ID/FIX (rule NAME) |
| Same rule inside a hook | Engine's plain value, no loop |
| AI weapon choice | Unhooked |
| Outside a hook | Defaults returned, setters do nothing |
| Unknown rule, missing script | Fix 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);
}