Editing GetActorValuePercentage - Actor

[[Category:Scripting]]
[[Category:Papyrus]]
'''Member of:''' [[Actor Script]]

Gets the specified actor value from the actor as a percentage of its maximum value (from 0 to 1).

== Syntax ==
<source lang="papyrus">
float Function GetActorValuePercentage(string asValueName) native
float Function GetAVPercentage(string asValueName)
  return GetActorValuePercentage(asValueName)
EndFunction
</source>

== Parameters ==
*asValueName: The name of the actor value to get the value of. [[Actor Value List]]

== Return Value ==
The value of the requested actor value as a percentage of its maximum value. If 0, then the actor value is at its minimum. If 1, then the actor value is at its maximum.

== Examples ==
If all you need is to get the maximum value after buffs is calculated, that is, the value that is '''not''' represented by the base value, you only need the result from the CurrentMaxValue variable.
<source lang="papyrus">
Float Function GetMaximumActorValue(Actor akActor, String asValueName)
    ; returns the maximum value for this actor value, buffs are accounted for.
    Float BaseValue = akActor.GetBaseActorValue(asValueName)
    Float CurrentMaxValue = Math.Ceiling(akActor.GetActorValue(asValueName) / akActor.GetActorValuePercentage(asValueName))
		
    if BaseValue < CurrentMaxValue
        return BaseValue
    else
        return CurrentMaxValue
    endif
EndFunction
; If your current health value is 10 and the base max value is 1200 but your buffed max is 1250, this will return 1200.
</source>
<br/>
<source lang="papyrus">
; Obtain the AV percentage of either health, stamina or magicka. This version does not take in account for buffed stats.
Float Function GetActorValuePercentageEX(Actor akActor, String asValueName)
  Float CurrentHealth = akActor.GetActorValue(asValueName)
  Float BaseHealth = akActor.GetBaseActorValue(asValueName)

  Float HealthPercent = (CurrentHealth / BaseHealth) * 100

  return HealthPercent
EndFunction 

GetActorValuePercentageEX(Game.GetPlayer(), "health")
; A health value of 930/930 will come out as 100.0 %
; A health value of 53/930 will come out to be about 5.6 %
</source>
<br/>
Get a percent of the total (max) value of a stat AFTER buffs are calculated:
<source lang="papyrus">
; returns requested percent of Actor's total possible stat value after buffs.
; stat 1 = health, stat 2 = magicka, stat 3 = stamina
; percent must be in decimal form, ie 25%: percent = 0.25, 100%: percent = 1, etc.
float Function TStatPV(Actor starget, float percent, int stat)
  if stat == 1
    return ((starget.GetActorValue("Health") / starget.GetActorValuePercentage("Health")) * percent)
  elseif stat == 2
    return ((starget.GetActorValue("Magicka") / starget.GetActorValuePercentage("Magicka")) * percent)
  elseif stat == 3
    return ((starget.GetActorValue("Stamina") / starget.GetActorValuePercentage("Stamina")) * percent)
  endif
EndFunction

; add the above function to your script then call it on an actor,
; for example to get 20% of the player's max health value after buffs:

float phbuffed = TStatPV(Game.GetPlayer(),0.20,1)
Debug.Notification("20% of players max buffed health = "+phbuffed)
</source>
<br/>
<source lang="papyrus">
; Obtain the player's current health percentage value
float playersHealth = Game.GetPlayer().GetActorValuePercentage("health")
if (playersHealth > 0.5)
  Debug.Trace("The player has over half their health left")
endIf
</source>
<br/>
<source lang="papyrus">
; Obtain Bob's current health actor value
float bobsHealth = Bob.GetAVPercentage("Health")
if (bobsHealth < 0.1)
  Debug.Trace("Bob has less then 10% health remaining")
endIf
</source>

== Notes ==
* The examples concerning calculations after buffs maybe off.
* Upon further testing, this function doesn't return the correct value under certain conditions. It is therefor not reliable.
* This function will always return 1.0 for CarryWeight.

== See Also ==
*[[GetActorValue - Actor]]
*[[GetBaseActorValue - Actor]]
*[[DamageActorValue - Actor]]
*[[ModActorValue - Actor]]
*[[ForceActorValue - Actor]]
*[[RestoreActorValue - Actor]]
*[[SetActorValue - Actor]]
*[[Actor Value List]]
*[[Actor Script]]