GetNpcData: Difference between revisions
Update Lua API reference |
Release 0.1.9 / BUILD264 / Protocol42: availability and download setup; preserve experimental limits |
||
| (6 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
= getNpcData = | = getNpcData = | ||
<div style="background:#fff5f5; border:1px solid #d13b3b; border-left:5px solid #d13b3b; color:#111111; padding:0.85rem 1rem; margin:0.75rem 0 1rem;"> | |||
<div style="color:#111111; font-weight:bold; letter-spacing:0.04em;">IMPROVED FROM UPDATE 0.1.2</div> | |||
<div style="color:#111111; margin-top:0.25rem;">This function is available in earlier releases and has corrected or expanded behavior in G1R:MP 0.1.2 and later. The contract below describes the updated behavior.</div> | |||
</div> | |||
Returns the complete authoritative state of a scripted NPC. | Returns the complete authoritative state of a scripted NPC. | ||
| Line 16: | Line 20: | ||
== Returns == | == Returns == | ||
Returns a table containing | Returns a table containing <code>id</code>, <code>ownerResource</code>, <code>name</code>, <code>skin</code>, <code>armor</code>, <code>weapon</code>, <code>x</code>, <code>y</code>, <code>z</code>, <code>yaw</code>, <code>speed</code>, <code>routeIndex</code>, <code>routeCount</code>, <code>routeLoop</code>, <code>routeActive</code>, <code>paused</code>, <code>nameplateIdVisible</code>, <code>obstacleBehavior</code>, <code>navigationMode</code>, and <code>navigationCollisionMode</code>; otherwise returns <code>false</code>. | ||
== Examples == | == Examples == | ||
| Line 30: | Line 34: | ||
* Available only in server-side resource scripts. | * Available only in server-side resource scripts. | ||
* Position and speed values use metres and metres per second; yaw uses degrees. | * Position and speed values use metres and metres per second; yaw uses degrees. | ||
* <code>obstacleBehavior</code> is <code>"wait"</code> or <code>"avoid"</code>, <code>navigationMode</code> is <code>"builtin"</code> or <code>"scripted"</code>, and <code>navigationCollisionMode</code> is <code>"combined"</code>, <code>"builtin"</code>, or <code>"custom"</code>. | |||
* Mutating functions accept only NPCs owned by the calling resource. | * Mutating functions accept only NPCs owned by the calling resource. | ||
[[Category:Lua Functions]] | |||
[[Category:Server Functions]] | [[Category:Server Functions]] | ||
[[Category:World Functions]] | [[Category:World Functions]] | ||
[[Category:NPC Functions]] | [[Category:NPC Functions]] | ||
<!-- npc015:start --> | |||
== Additional fields since 0.1.5 == | |||
The existing table additionally returns weaponMode (string), animation (active alias or empty string), health, maxHealth, invulnerable, attackDamage and combatTarget (player ID, or 0). Use [[getNpcCombatMovement]], [[getNpcCombatConfig]] and [[getNpcCombatState]] for pursuit/projectile data. See [[NPC scripting]]. | |||
<!-- npc015:end --> | |||
<!-- npc-appearance015:start --> | |||
== Appearance API since 0.1.5 == | |||
Additional fields from 0.1.5: identity (string, default initially), identityExplicit (boolean, false until setNpcIdentity is called). Use [[getNpcSkinColor]] and [[getNpcTattoo]] for independent override values. Identity default with identityExplicit=false preserves legacy skin behaviour. | |||
<!-- npc-appearance015:end --> | |||
<!-- upcoming019:start --> | |||
== Item-type armor bonuses (from 0.1.9) == | |||
[[Item type stats]] adds explicit armor bonusHealth/bonusMana/bonusStrength/bonusDexterity contributions for equipped scripted NPCs, plus the armor protection profile. Unconfigured native bonuses do not silently change existing NPC balance. Base stats and bonuses are separate; raising maxima does not heal/refill and lowering maxima clamps current values without reviving dead NPCs. | |||
setNpcMaxHealth/setNpcMaxMana set BASE maxima; getNpcMaxHealth/getNpcMaxMana return EFFECTIVE maxima. setNpcCombatConfig/getNpcCombatConfig dexterity is BASE dexterity. getNpcData adds baseMaxHealth, baseMaxMana, baseDexterity, mana, maxMana, dexterity, armorHealthBonus, armorManaBonus, armorStrengthBonus and armorDexterityBonus. | |||
NPC melee includes explicit armor strength and ranged combat uses effective dexterity. Numeric refresh preserves accepted attack/projectile snapshots; it does not reload ammo or restart prepared casts. NPC toughness and NPC jewelry are not implemented by this addition. These are extensions to existing APIs, not new names or a replacement for their earlier contracts. | |||
<!-- upcoming019:end --> | |||
Latest revision as of 13:27, 20 October 2026
getNpcData
Returns the complete authoritative state of a scripted NPC.
Syntax
table|false getNpcData(int npcId)
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
npcId |
int |
yes | The server-assigned NPC identifier returned by spawnNpc or getNpcs.
|
Returns
Returns a table containing id, ownerResource, name, skin, armor, weapon, x, y, z, yaw, speed, routeIndex, routeCount, routeLoop, routeActive, paused, nameplateIdVisible, obstacleBehavior, navigationMode, and navigationCollisionMode; otherwise returns false.
Examples
Read the current route state:
local npc = getNpcData(npcId)
if npc then
outputDebugString(("Route %d/%d"):format(npc.routeIndex, npc.routeCount))
end
Notes
- Available only in server-side resource scripts.
- Position and speed values use metres and metres per second; yaw uses degrees.
obstacleBehavioris"wait"or"avoid",navigationModeis"builtin"or"scripted", andnavigationCollisionModeis"combined","builtin", or"custom".- Mutating functions accept only NPCs owned by the calling resource.
Additional fields since 0.1.5
The existing table additionally returns weaponMode (string), animation (active alias or empty string), health, maxHealth, invulnerable, attackDamage and combatTarget (player ID, or 0). Use getNpcCombatMovement, getNpcCombatConfig and getNpcCombatState for pursuit/projectile data. See NPC scripting.
Appearance API since 0.1.5
Additional fields from 0.1.5: identity (string, default initially), identityExplicit (boolean, false until setNpcIdentity is called). Use getNpcSkinColor and getNpcTattoo for independent override values. Identity default with identityExplicit=false preserves legacy skin behaviour.
Item-type armor bonuses (from 0.1.9)
Item type stats adds explicit armor bonusHealth/bonusMana/bonusStrength/bonusDexterity contributions for equipped scripted NPCs, plus the armor protection profile. Unconfigured native bonuses do not silently change existing NPC balance. Base stats and bonuses are separate; raising maxima does not heal/refill and lowering maxima clamps current values without reviving dead NPCs.
setNpcMaxHealth/setNpcMaxMana set BASE maxima; getNpcMaxHealth/getNpcMaxMana return EFFECTIVE maxima. setNpcCombatConfig/getNpcCombatConfig dexterity is BASE dexterity. getNpcData adds baseMaxHealth, baseMaxMana, baseDexterity, mana, maxMana, dexterity, armorHealthBonus, armorManaBonus, armorStrengthBonus and armorDexterityBonus.
NPC melee includes explicit armor strength and ranged combat uses effective dexterity. Numeric refresh preserves accepted attack/projectile snapshots; it does not reload ammo or restart prepared casts. NPC toughness and NPC jewelry are not implemented by this addition. These are extensions to existing APIs, not new names or a replacement for their earlier contracts.