`NPCModule`

NPC initialization, orc clan appearances, and common orc equipment presets.

Lua script module · Reviewed October 6, 2026.

NPCModule is a reusable Lua spawn-script module for initializing NPC combat statistics, regeneration, spell lists and selected spawn animations. Its imports also make racial appearance and equipment presets available to the calling spawn script.

Load it before calling its functions:

require "SpawnScripts/Generic/NPCModule"

These are Lua functions defined by scripts. Their availability comes from require; they are not individual lua_register engine bindings. Function names are case-sensitive. Calling the module initializer does not automatically apply a clan appearance or an armor preset.

NPCModule(NPC)

function spawn(NPC)
    NPCModule(NPC)
end

Argument	Type	Requirement	Meaning
`NPC`	NPC spawn handle	Required	The NPC to initialize; its existing level, difficulty, class and model drive the result.

The spawn event supplies only NPC. Call the initializer with that one handle. Some local script definitions retain an unused second parameter; it is omitted from the documented calls. The current server looks up the case-sensitive callback name spawn in lowercase.

Return value: none. The function changes the supplied NPC.

The initializer reads level and difficulty, then runs the following helpers in order. The calls below show the single NPC argument each helper needs:

Step	Helper	Current behavior
1	`SpawnAnimations(NPC)`	Sets spawn animation `13016` for the model IDs handled by this function.
2	`Attributes(NPC)`	Sets strength, agility, stamina, intelligence and wisdom from level/difficulty and `GlobalStatMod`, including base attributes; calls `AttributeModifiers`.
3	`AutoAttack(NPC)`	Calculates low/high damage using difficulty, level, the strength modifier and `GlobalDmgMod`; `damage` enables the primary-weapon override and sets delay `3000`.
4	`Regen(NPC)`	Sets HP/power regeneration override flags to `1` and both regeneration values to `0`. The combat-only condition is commented out.
5	`HealthPower(NPC)`	Uses a level table, difficulty multipliers and global HP/power modifiers to update health and power. Levels above 50 use the fixed final table branch.
6	`NPCSpells(NPC)`	Assigns classic spell lists by class and selected creature model IDs. The configured lists must exist in the world data.
7	`AddTimer` → `Heroic`	Schedules checks after `25` and `1000` milliseconds. `Heroic` sets heroic to `1` for groups larger than one, or difficulty `8`/`9`; it does not clear an existing heroic flag.

The module defines GlobalDmgMod, GlobalStatMod, GlobalHPMod, GlobalPowerMod and GlobalSpellMod as 1.0. The first four are used in its calculations. GlobalSpellMod is declared but is not read by the current module's spell-list implementation.

Lower-level helpers use module globals populated during initialization. Use the initializer rather than invoking its calculation steps out of order. Named(NPC) is a separate named-NPC initialization path: it applies a 1.5 HP/power multiplier and finally sets both regeneration values to (level * 2) + (difficulty * 2). It does not schedule the two Heroic timers itself.

Source details to retain when comparing behavior: HealthPower passes the calculated HP value to ModifyPower, although maximum power uses the calculated power value. Named similarly passes HP times its modifier to ModifyPower. The engine's ModifyHP/ModifyPower functions add to current values and clamp to their maxima; the maximum functions assign their totals. These are the current implementation details, not corrected formulas.

Evidence: server/SpawnScripts/Generic/NPCModule.lua:22, :41, :112, :125, :164, :360, :377, :401, :433; WorldServer/Zone/zoneserver.cpp:6031–6034; WorldServer/Lua/LuaInterface.cpp:2803–2826; WorldServer/Lua/LuaFunctions.cpp:2400–2451.

Imported modules

Imported file	What it makes available	How to use it
`SpawnScripts/Generic/NPCRaces.lua`	Racial and clan appearance helpers, including `Bloodskull`, `Brokentusk`, `Lonetusk`, `Ree` and `Deathfist`.	Call the chosen appearance helper explicitly on the NPC.
`SpawnScripts/Generic/EquipmentModule.lua`	Equipment presets, including `OrcArmorCommon`, `GhostOrcArmorCommon`, and class-based random weapon helpers.	Call the chosen equipment preset explicitly.
`SpawnScripts/Generic/IdleAnimations.lua`	Idle animation packages such as `IdleAggressive` and `IdleAlert`.	Choose and call a compatible idle helper explicitly; loading the file does not start every package.

The module publishes global functions, rather than a returned object with methods. The normal use is require "SpawnScripts/Generic/NPCModule" followed by NPCModule(...), Bloodskull(...) or another named helper.

Evidence: server/SpawnScripts/Generic/NPCModule.lua:11–13.

Bloodskull(NPC)

Bloodskull enforces the Bloodskull orc appearance preset. Call it with the NPC handle.

Bloodskull(NPC)

Argument	Type	Requirement	Meaning
`NPC`	NPC spawn handle	Required	The orc whose model and colors are changed.

Return value: none.

The NPCRaces.lua implementation performs exactly these appearance calls:

SpawnSet(NPC, "model_type", 137)
SpawnSet(NPC, "skin_color", "50 60 50")
SpawnSet(NPC, "eye_color", "98 63 28")

This helper changes model and colors. It does not set the NPC's faction, name, level, combat statistics, or equipment. Use Bloodskull(NPC) with a valid NPC handle; a bare Bloodskull() supplies no NPC. The three-argument SpawnSet calls use the engine's default temporary flag, so they apply to the runtime spawn without saving a database spawn definition.

Evidence: server/SpawnScripts/Generic/NPCRaces.lua:194–198; WorldServer/Lua/LuaFunctions.cpp:478–503.

Orc clan appearance helpers

Freeport-area spawn scripts use four clan helpers: Bloodskull, Brokentusk, Lonetusk and Ree. Select the helper matching the NPC's clan. The presets support clan-specific looks, but the current source does not give every clan a unique palette:

Helper call	Model type	Skin RGB	Eye RGB	Source line in `NPCRaces.lua`
`Bloodskull(NPC)`	`137`	`50 60 50`	`98 63 28`	194
`Brokentusk(NPC)`	`137`	`110 75 75`	`98 63 28`	200
`Lonetusk(NPC)`	`137`	`92 52 52`	`98 63 28`	206
`Ree(NPC)`	`137`	`50 60 50`	`98 63 28`	212
`Deathfist(NPC)`	`137`	`50 60 50`	`98 63 28`	188

Bloodskull and Ree currently share the same model and colors; Deathfist uses those values too. Equipment, other script calls and database settings can provide additional differences. The helper names themselves do not assign faction IDs.

Examples in the reviewed checkout: Bloodskull in Commonlands/OgofRunner.lua:12, Brokentusk in TheRuins_Classic/aBrokentuskpawn.lua:15, Lonetusk in TheRuins_Classic/aLonetuskpawn.lua:15, and Ree in WailingCaves/aReerecruit.lua:12.

SpawnScripts/Generic/OrcModule.lua is a separate module with overlapping global helper names. Its Bloodskull body is empty. The appearance values on this page refer to NPCRaces.lua, imported by NPCModule. Loading both files into the same Lua environment can redefine the shared names; check the load order when investigating different results.

OrcArmorCommon(NPC)

OrcArmorCommon applies a randomized common-orc equipment appearance. It complements a clan appearance helper and does not choose the clan itself.

OrcArmorCommon(NPC)

Argument	Type	Requirement	Meaning
`NPC`	NPC entity handle	Required	The NPC whose weapon and armor appearance slots are changed.

Return value: none. Appearance IDs below are equipment appearance types, not inventory item IDs.

First it calls RandomWeapons(NPC), which selects a weapon family from GetClass(NPC):

Class IDs	Weapon helper
`1–4`, `8–10`	`RandomFighterWeapons`
`5–7`	`RandomBrawlerWeapons`
`11–20`	`RandomPriestWeapons`
`21–30`	`RandomMageWeapons`
`31–40`	`RandomScoutWeapons`
Other values	`RandomFighterWeapons` fallback

It then chooses MakeRandomInt(1, 5) and sets these armor appearance slots. Each set uses base and highlight RGB values 255 255 255:

Random choice	Slot → appearance ID
`1`	`7 → 1084`, `5 → 1081`, `8 → 1080`
`2`	`7 → 1084`, `5 → 1081`, `8 → 1080`, `3 → 1079`
`3`	`7 → 1084`
`4`	`7 → 1084`, `5 → 1081`, `8 → 1080`, `2 → 1083`, `3 → 1079`
`5`	`7 → 1084`, `8 → 1080`, `3 → 1079`

The preset only writes the slots selected by that branch. It does not clear unselected armor slots or an unused secondary-weapon slot. Repeated calls reroll equipment and can leave earlier slot appearances in place. It does not create inventory items, assign loot, change combat statistics, or persist equipment to the database. The engine marks the runtime entity's appearance changed; an invalid/non-entity handle causes SetEquipment to log an error.

Evidence: server/SpawnScripts/Generic/EquipmentModule.lua:9–27, :131–161; WorldServer/Lua/LuaFunctions.cpp:7756–7786.

Combined spawn example

Use the initialization and appearance order from Commonlands/OgofRunner.lua, with the one-argument spawn callback:

require "SpawnScripts/Generic/NPCModule"

function spawn(NPC)
    NPCModule(NPC)
    Bloodskull(NPC)
    OrcArmorCommon(NPC)
end

This example preserves the script's initialization/appearance order and omits its unused second callback parameter, movement timers and other callbacks. NPCModule initializes combat behavior, Bloodskull applies the clan model/colors, and OrcArmorCommon adds randomized equipment appearance. These are separate, explicit calls.

For another clan, choose its corresponding appearance helper, for example Brokentusk(NPC), Lonetusk(NPC) or Ree(NPC). Calling RandomWeapons separately immediately before OrcArmorCommon is redundant for weapon selection because OrcArmorCommon calls it again.

Evidence: server/SpawnScripts/Commonlands/OgofRunner.lua:8–14; the Brokentusk and Lonetusk scripts demonstrate the additional standalone weapon call. Examples were checked against local source, not executed in a live world.

Definitions come from the reviewed Lua scripts and engine handlers. Server scripts and bindings are unchanged by this documentation update.

NPCModule