Add limitation: do NOT change unit level directly in ASM

Preload/Reloc.event

@@ -138,4 +138,6 @@ gpJobGrowthList: POIN gJobGrowthList
 gpPrepItemEffectFunc: POIN gPrepItemEffectFunc
 gpPrepItemUsabilityFuncs: POIN gPrepItemUsabilityFuncs
 
+prWriteUnitLevelSafe: POIN WriteUnitLevelSafe
+
 KERNEL_RELOC_END:

Wizardry/Common/BwlRework/source/BwlHiddenLevel.c

@@ -49,3 +49,13 @@ void UnitHiddenLevelPreLoad(struct Unit *unit)
 
 	bwl->levelGain = GetUnitStaticHiddenLevel(unit);
 }
+
+void WriteUnitLevelSafe(struct Unit *unit, int new_level)
+{
+	struct NewBwl *bwl = GetNewBwl(UNIT_CHAR_ID(unit));
+
+	if (bwl)
+		bwl->levelGain += new_level - unit->level;
+
+	unit->level = new_level;
+}

docs/Limitations.md

@@ -88,4 +88,15 @@
     - staff
     - ring
     - skills
-    - save data
+    - save data
+
+5. Do **NOT** directly change the unit level in ASM.
+
+    As unit lvup history is stored in BWL table, and directly change the unit level may not affect the unit recorded level, thus the lvup skill-learning process may not act in exception. For more info, see section: **Learn skills** in [SkillSys](./SkillSys.md).
+
+    As an alternative, kernel offered an API if you want to change unit level in ASM:
+
+    ```c
+    // bwl.h
+    void WriteUnitLevelSafe(struct Unit *unit, int new_level);
+    ```

include/bwl.h

@@ -27,3 +27,7 @@ extern s8 const *const gpClassPreLoadHiddenLevel;
 void NewBwlRecordHiddenLevel(struct Unit *unit);
 int GetUnitHiddenLevel(struct Unit *unit);
 void UnitHiddenLevelPreLoad(struct Unit *unit);
+
+// see limition rule 5
+void WriteUnitLevelSafe(struct Unit *unit, int new_level);
+extern const void (*prWriteUnitLevelSafe)(struct Unit *unit, int new_level);