improve errors and readme

DBC_FIELDS.md

@@ -0,0 +1,144 @@
+# DBC Field Names
+
+Related structs live in `nampower/game.hpp` (notably `SpellRec` and `ItemStats_C`).
+
+## ItemStats_C Fields (alphabetical)
+- `allowableClass`
+- `allowableRace`
+- `ammoType`
+- `area`
+- `bagFamily`
+- `block`
+- `bonding`
+- `buyPrice`
+- `class`
+- `containerSlots`
+- `delay`
+- `displayInfoID`
+- `duration`
+- `flags`
+- `inventoryType`
+- `itemLevel`
+- `itemSet`
+- `languageID`
+- `lockID`
+- `map`
+- `material`
+- `maxCount`
+- `maxDurability`
+- `pageMaterial`
+- `pageText`
+- `quality`
+- `randomProperty`
+- `rangedModRange`
+- `requiredCityRank`
+- `requiredHonorRank`
+- `requiredLevel`
+- `requiredRep`
+- `requiredRepRank`
+- `requiredSkill`
+- `requiredSkillRank`
+- `requiredSpell`
+- `sellPrice`
+- `sheatheType`
+- `stackable`
+- `startQuestID`
+- `subclass`
+
+### ItemStats_C Array Fields (alphabetical)
+- `bonusAmount`
+- `bonusStat`
+- `damageType`
+- `maxDamage`
+- `minDamage`
+- `resistances`
+- `spellCategory`
+- `spellCategoryCooldown`
+- `spellCharges`
+- `spellCooldown`
+- `spellID`
+- `spellTrigger`
+
+## SpellRec Fields (alphabetical)
+- `activeIconID`
+- `attributes`
+- `attributesEx`
+- `attributesEx2`
+- `attributesEx3`
+- `attributesEx4`
+- `auraInterruptFlags`
+- `baseLevel`
+- `castUI`
+- `category`
+- `categoryRecoveryTime`
+- `casterAuraState`
+- `castingTimeIndex`
+- `channelInterruptFlags`
+- `dispel`
+- `dmgClass`
+- `durationIndex`
+- `equippedItemClass`
+- `equippedItemInventoryTypeMask`
+- `equippedItemSubClassMask`
+- `id`
+- `interruptFlags`
+- `manaCost`
+- `manaCostPercentage`
+- `manaCostPerlevel`
+- `manaPerSecond`
+- `manaPerSecondPerLevel`
+- `maxAffectedTargets`
+- `maxLevel`
+- `maxTargetLevel`
+- `mechanic`
+- `minFactionId`
+- `minReputation`
+- `modalNextSpell`
+- `powerType`
+- `preventionType`
+- `procChance`
+- `procCharges`
+- `procFlags`
+- `rangeIndex`
+- `recoveryTime`
+- `requiredAuraVision`
+- `school`
+- `spellFamilyFlags`
+- `spellFamilyName`
+- `spellIconID`
+- `spellLevel`
+- `spellPriority`
+- `spellVisual`
+- `spellVisual2`
+- `stackAmount`
+- `stances`
+- `stancesNot`
+- `startRecoveryCategory`
+- `startRecoveryTime`
+- `targetAuraState`
+- `targetCreatureType`
+- `targets`
+
+### SpellRec Array Fields (alphabetical)
+- `dmgMultiplier`
+- `effect`
+- `effectAmplitude`
+- `effectApplyAuraName`
+- `effectBaseDice`
+- `effectBasePoints`
+- `effectChainTarget`
+- `effectDicePerLevel`
+- `effectDieSides`
+- `effectImplicitTargetA`
+- `effectImplicitTargetB`
+- `effectItemType`
+- `effectMechanic`
+- `effectMiscValue`
+- `effectMultipleValue`
+- `effectPointsPerComboPoint`
+- `effectRadiusIndex`
+- `effectRealPointsPerLevel`
+- `effectTriggerSpell`
+- `reagent`
+- `reagentCount`
+- `totem`

README.md

@@ -229,18 +229,24 @@ Examples:
 ```
 
 #### GetItemStats(itemId)
-Returns a Lua table containing all fields for the item’s `ItemStats_C` record (including localized `displayName` and `description`). Returns 0 if the item cannot be found or loaded.
+Returns a Lua table containing all fields for the item’s `ItemStats` record (including localized `displayName` and `description`). Returns nil if the item cannot be found or loaded.
+
+Full field name lists are in [`DBC_FIELDS.md`](DBC_FIELDS.md).
 
 #### GetItemStatsField(itemId, fieldName)
-Fast lookup for a single field on an item. Returns the requested field value or raises a Lua error if the item or field is not found.
+Fast lookup for a single field on an item. Returns the requested field value; returns nil if the item is not found; raises a Lua error if the field name is invalid.
+
+Full field name lists are in [`DBC_FIELDS.md`](DBC_FIELDS.md).
 
 #### GetSpellRec(spellId)
-Returns a Lua table containing all fields for the spell’s `SpellRec` record (including localized `name` and `rank`). Returns 0 if the spell cannot be found.
+Returns a Lua table containing all fields for the spell’s `SpellRec` record (including localized `name` and `rank`). Returns nil if the spell cannot be found.
+
+Full field name lists are in [`DBC_FIELDS.md`](DBC_FIELDS.md).
 
 #### GetSpellRecField(spellId, fieldName)
-Fast lookup for a single field on a spell. Returns the requested field value or raises a Lua error if the spell or field is not found.
+Fast lookup for a single field on a spell. Returns the requested field value; returns nil if the spell is not found; raises a Lua error if the field name is invalid.
 
-Struct references (see `nampower/dbc_fields.cpp` for full details):
+Full field name lists are in [`DBC_FIELDS.md`](DBC_FIELDS.md).
 
 #### GetNampowerVersion()
 Returns the current version of Nampower split into major, minor and patch numbers.

nampower/scripts.cpp

@@ -21,6 +21,7 @@ namespace Nampower {
     // Export Lua functions for dbc_fields.hpp templates
     lua_pushnumberT lua_pushnumber = reinterpret_cast<lua_pushnumberT>(Offsets::lua_pushnumber);
     lua_pushstringT lua_pushstring = reinterpret_cast<lua_pushstringT>(Offsets::lua_pushstring);
+    lua_pushnilT lua_pushnil = reinterpret_cast<lua_pushnilT>(Offsets::lua_pushnil);
     lua_newtableT lua_newtable = reinterpret_cast<lua_newtableT>(Offsets::lua_newtable);
     lua_settableT lua_settable = reinterpret_cast<lua_settableT>(Offsets::lua_settable);
 
@@ -438,8 +439,8 @@ namespace Nampower {
         // Get from cache
         game::ItemStats_C *item = GetItemStats(itemId);
         if (!item) {
-            lua_error(luaState, "Item not found");
-            return 0;
+            lua_pushnil(luaState);
+            return 1;
         }
 
         // Create new table
@@ -476,8 +477,8 @@ namespace Nampower {
         // Get spell info
         auto spell = game::GetSpellInfo(spellId);
         if (!spell) {
-            lua_error(luaState, "Spell not found");
-            return 0;
+            lua_pushnil(luaState);
+            return 1;
         }
 
         // Create new table
@@ -522,7 +523,7 @@ namespace Nampower {
         // Get from cache
         game::ItemStats_C *item = GetItemStats(itemId);
         if (!item) {
-            lua_pushnumber(luaState, 0); // Return nil/false to indicate not found
+            lua_pushnil(luaState);
             return 1;
         }
 
@@ -614,7 +615,7 @@ namespace Nampower {
         // Get spell info
         auto spell = game::GetSpellInfo(spellId);
         if (!spell) {
-            lua_pushnumber(luaState, 0); // Return nil/false to indicate not found
+            lua_pushnil(luaState);
             return 1;
         }