OnPlayerGainXP

The player’s game awarded XP on its own - return false to refuse it, or a number to give that much instead.

The game awards XP as the character does things: a kill, a hit, a distance walked, a book read. Every award goes through the XP rate first (SetXPRate); a rate of 0 gives nothing and this callback is never asked. xp is the award times the rate, for the stat or skill name (kind says which). Return false, or a number of 0 or less, to refuse it; a number to give that much instead; nothing (or true) to give xp. What is given arrives the game’s way - the level-up notice, the perk points. A number you return is capped at 100000. Some awards never get here: the server drops one above 10000 XP (before the rate), more than 40 a second from one player, and one for the main level or for a name that is neither a stat nor a skill.

Defining this callback costs a round trip. The players’ games hold every award until the server answers, so the XP shows a moment after the deed, and a fight sends several awards a second. A mode that only wants more or less XP sets the rate and leaves this out; one that has a rule to apply answers from memory here, never from a database query. XP the mode gives itself (AddPlayerSkillXP) does not come here.

Syntax

function OnPlayerGainXP(pid, kind, name, xp)
  -- ...
end

Parameter	Type
pid	number	the player
kind	string	"stat" or "skill"
name	string	the stat’s or skill’s lower-case name ("marksmanship")
xp	number	the XP the game awarded, times the XP rate

Returns

false refuses the award; a number gives that much instead (0 or less refuses); nothing or true gives xp

Example

-- play teaches a skill up to level 10; above that only the trainer's word counts. Thieves learn twice as fast
function OnPlayerGainXP(pid, kind, name, xp)
  if kind == "skill" and GetPlayerSkill(pid, name) >= 10 then return false end
  if name == "thievery" then return xp * 2 end
end

See also

SetXPRate · SetPlayerXPRate · AddPlayerSkillXP · OnPlayerLevelUp · the Stats, skills, XP and perks group of the index