Skip to content

tes3mobileCreature⚓︎

A mobile object for a creature.

This type inherits the following: tes3mobileActor, tes3mobileObject

Properties⚓︎

actionBeforeCombat⚓︎

Read-only. Action data stored before the actor entered combat.

Returns:

actionData⚓︎

Read-only. Current action data. Pre-combat action data is stored in the actionBeforeCombat property.

Returns:

activeAI⚓︎

Friendly access to the actor's flag that controls if AI is active.

Returns:

  • result (boolean)

activeMagicEffectList⚓︎

Read-only. The active magic effects on the actor, from which all others can be accessed. A table with tes3activeMagicEffect items.

Returns:

actorType⚓︎

Read-only. The type of the mobile actor. Maps to values in tes3.actorType namespace.

Returns:

agility⚓︎

Read-only. Direct access to the actor's agility attribute statistic. If you are setting player stats, instead use tes3.setStatistic to also update the UI immediately.

Returns:

aiPlanner⚓︎

Read-only. Access to the mobile's AI planner and AI package information. Doesn't exist on the player mobile.

Returns:

alarm⚓︎

The actor's alarm AI value.

Returns:

  • result (number)

animationController⚓︎

Read-only. No description yet available.

Returns:

armorRating⚓︎

Read-only. The actor's current armour rating, taking equipment condition into account. Armour mitigation can be automatically applied to damage by using the applyDamage function.

Armour mitigation calculation:

x = damage / (damage + target.armorRating)

damage *= max(fCombatArmorMinMult, x)

if damage < 1 then

    damage = 1

end

Returns:

  • result (number)

attackBonus⚓︎

Direct access to the actor's attack bonus effect attribute.

Returns:

  • result (number)

attacked⚓︎

Read-only. Friendly access to the actor's flag that controls if the actor has been attacked.

Returns:

  • result (boolean)

attributes⚓︎

Read-only. Access to a table of 8 tes3statistic objects for the actor's attributes. If you are setting player stats, instead use tes3.setStatistic to also update the UI immediately.

Note

This array is 1-indexed. The array indices correspond to the tes3.attribute table plus 1 to account for Lua's 1-based array indexing. In other words myMobile.attributes[tes3.attribute.strength + 1] returns the tes3statistic object corresponding to strength.

Returns:

barterGold⚓︎

The current amount of gold that the actor has access to for bartering.

Barter gold is reset on talking to an actor if fBarterGoldResetDelay hours have passed since the last transaction. The base value is held in tes3npc.barterGold, which is the base object and not an instance.

Returns:

  • result (number)

blind⚓︎

Direct access to the actor's blind effect attribute.

Returns:

  • result (number)

boundSize⚓︎

A vector that shows the size of the bounding box in each direction. Note that this is a convenience feature, and delivers the x and y values from boundSize2D with the z value of the mobile's height. Editing the values of the returned vector will not change the values that they came from, though setting the property itself will work.

Returns:

boundSize2D⚓︎

A vector that shows the size of the bounding box in X and Y directions. boundSize is a convenience property that exposes the bounding in 3 dimensions.

Returns:

canAct⚓︎

Read-only. If true, the actor is able to freely execute actions like attacking or casting magic. This is equal to checking if the actor is not dead, knocked down, knocked out, hit stunned, paralyzed, drawing/sheathing their weapon, attacking, casting magic or using a lockpick or probe.

Returns:

  • result (boolean)

canJump⚓︎

Read-only. If true, the actor is currently able to jump. This is equal to checking if the actor is not dead, knocked down, knocked out, paralyzed, jumping, falling, swimming or flying.

Returns:

  • result (boolean)

canJumpMidair⚓︎

Read-only. If true, the actor is currently able to jump midair. This is equal to checking if the actor is not dead, knocked down, knocked out, paralyzed, swimming or flying. For more information on midair jumping see tes3mobileActor:doJump().

Returns:

  • result (boolean)

canMove⚓︎

Read-only. If true, the actor is able to freely move along the ground or in the air. This does not include jumping (see canJump). This is equal to checking if the actor is not dead, knocked down, knocked out, hit stunned, or paralyzed.

Returns:

  • result (boolean)

cell⚓︎

Read-only. Fetches the cell that the actor is in.

Returns:

cellX⚓︎

Read-only. The X grid coordinate of the cell the mobile is in.

Returns:

  • result (number)

cellY⚓︎

Read-only. The Y grid coordinate of the cell the mobile is in.

Returns:

  • result (number)

chameleon⚓︎

Direct access to the actor's chameleon effect attribute.

Returns:

  • result (number)

collidingReference⚓︎

Read-only. The reference that the mobile has collided with this frame. Doesn't include actors and terrain.

Returns:

combat⚓︎

Read-only. Direct access to the creature's combat statistic. This is a creature-specific generalization of skills, where this statistic is used in place of all combat skills. To get an individual skill value by skill ID, see the getSkillValue or getSkillStatistic methods.

Returns:

combatSession⚓︎

Read-only. Combat session data. This exists while the actor is in combat to provide memory for AI combat decisions. Doesn't exist on the player's mobile.

Returns:

corpseHourstamp⚓︎

This is the time measured in hours from the beginning of the game when the actor died. Returns a UNIX-style timestamp based on in-world simulation time since the start of the era. For living actors this field has value a of 0.

Returns:

  • result (number)

currentEnchantedItem⚓︎

Read-only. The currently equipped enchanted item that the actor will use.

Returns:

currentSpell⚓︎

Read-only. The currently equipped spell that the actor will use.

Returns:

effectAttributes⚓︎

Read-only. Access to a table of 24 numbers for the actor's effect attributes. In order those are: attackBonus, sanctuary, resistMagicka, resistFire, resistFrost, resistShock, resistCommonDisease, resistBlightDisease, resistCorprus, resistPoison, resistParalysis, chameleon, resistNormalWeapons, waterBreathing, waterWalking, swiftSwim, jump, levitate, shield, sound, silence, blind, paralyze, and invisibility. Each of those can be accessed individually. For example, tes3mobileActor.chameleon.

Returns:

  • result (number[])

encumbrance⚓︎

Read-only. Access to the actor's encumbrance statistic. When modifying this value, prefer to use tes3.modStatistic or tes3.setStatistic to also update the UI immediately.

Returns:

endurance⚓︎

Read-only. Direct access to the actor's endurance attribute statistic. If you are setting player stats, instead use tes3.setStatistic to also update the UI immediately.

Returns:

facing⚓︎

Read-only. The facing of the actor, in radians. Facing is defined like a compass heading, positive values are clockwise and North (+Y axis) is zero, while facing of PI corresponds to South (-Y axis).

It's the same as mobile.reference.orientation.z.

Returns:

  • result (number)

fatigue⚓︎

Read-only. Access to the actor's fatigue statistic. When modifying this value, prefer to use tes3.modStatistic or tes3.setStatistic to also update the UI immediately.

Returns:

fight⚓︎

The actor's fight AI value.

Returns:

  • result (number)

flags⚓︎

Access to the root mobile object flags, represented as an integer. Should not be accessed directly.

Returns:

  • result (integer)

flee⚓︎

The actor's flee AI value.

Returns:

  • result (number)

flySpeed⚓︎

Read-only. The calculated fly movement speed.

Returns:

  • result (number)

friendlyActors⚓︎

Read-only. A collection of other tes3mobileActors that this actor considers friendly.

Returns:

friendlyFireHitCount⚓︎

The number of times the player has hit this actor with friendly fire. The actor will turn on the player on the fourth hit if it is not already in combat. The game will not increase this past 4, and will reset it to 0 at the end of combat.

Returns:

  • result (number)

greetDuration⚓︎

No description yet available.

Returns:

  • result (number)

greetTimer⚓︎

Read-only. No description yet available.

Returns:

  • result (number)

hasBlightDisease⚓︎

Read-only. True if the actor is has a blight disease effect. This does not include common or corprus diseases, nor does it include vampirism.

Returns:

  • result (boolean)

hasCommonDisease⚓︎

Read-only. True if the actor is has a common disease effect. This does not include blight or corprus diseases, nor does it include vampirism.

Returns:

  • result (boolean)

hasCorprusDisease⚓︎

Read-only. True if the actor is has a corprus disease effect. This does not include common or blight diseases, nor does it include vampirism.

Returns:

  • result (boolean)

hasFreeAction⚓︎

Read-only. If true, the actor isn't knocked down or knocked out.

Returns:

  • result (boolean)

hasVampirism⚓︎

Read-only. True if the actor has a vampirism effect. Checks if the actor has an active vampirism magic effect. This is the same method used in the engine to determine if an NPC has a vampire head model, or can use a vampire dialogue response.

Returns:

  • result (boolean)

health⚓︎

Read-only. Access to the actor's health statistic. When modifying this value, prefer to use tes3.modStatistic or tes3.setStatistic to also update the UI immediately.

Returns:

height⚓︎

The height of the mobile's bounding box.

Returns:

  • result (number)

hello⚓︎

The actor's hello AI value.

Returns:

  • result (number)

holdBreathTime⚓︎

This is the time the actor can stay underwater without taking drowning damage, measured in seconds. It's starting value is fHoldBreathTime(GMST) seconds by default. Once the actor is underwater, this value is decreasing based on the time passed while underwater. The actor will start taking drowning damage once this time is below 0. During drowning this time will have more and more negative values based on the duration of the drowning. Changing this allows manipulating for how long the actor can stay underwater without drowning. Note that player's Breath HUD element won't show values larger than fHoldBreathTime.

Returns:

  • result (number)

hostileActors⚓︎

Read-only. A collection of other tes3mobileActors that this actor considers hostile.

Returns:

idleAnim⚓︎

Read-only. Friendly access to the actor's flag that controls if the actor is using their idle animation.

Returns:

  • result (boolean)

impulseVelocity⚓︎

A vector that represents the 3D acceleration of the object.

Returns:

inCombat⚓︎

Read-only. Friendly access to the actor's flag that controls if the actor is in combat.

Returns:

  • result (boolean)

intelligence⚓︎

Read-only. Direct access to the actor's intelligence attribute statistic. If you are setting player stats, instead use tes3.setStatistic to also update the UI immediately.

Returns:

inventory⚓︎

Read-only. Access to the items the mobile object has in its inventory.

Returns:

invisibility⚓︎

Direct access to the actor's invisibility effect attribute.

Returns:

  • result (number)

isAffectedByGravity⚓︎

If true, the mobile is affected by gravity. Does not have any effect on spell projectiles.

Returns:

  • result (boolean)

isAttackingOrCasting⚓︎

Read-only. If true, the actor is attacking, casting magic or using a lockpick or probe.

Returns:

  • result (boolean)

isCrittable⚓︎

Read-only. Friendly access to the actor's flag that controls if the actor can be critically hit.

Returns:

  • result (boolean)

isDead⚓︎

Read-only. True if the actor is dead.

Returns:

  • result (boolean)

isDiseased⚓︎

Read-only. True if the actor is has a disease effect. This counts normal, blight, and corprus effects.

Returns:

  • result (boolean)

isFalling⚓︎

Direct access to the actor's current movement flags, showing if the actor is falling. This is when the actor is falling without having jumped, e.g. if they walked off a ledge.

Returns:

  • result (boolean)

isFlying⚓︎

Direct access to the actor's current movement flags, showing if the actor is flying.

Returns:

  • result (boolean)

isHitStunned⚓︎

Read-only. If true, the actor is affected by hit stun. This prevents the actor from initiating an attack, but not continuing and finishing an attack. It also prevents movement except for jumping.

Returns:

  • result (boolean)

isJumping⚓︎

Direct access to the actor's current movement flags, showing if the actor is jumping.

Returns:

  • result (boolean)

isKnockedDown⚓︎

Read-only. If true, the actor is knocked down. An actor can be knocked down after being attacked or falling.

Returns:

  • result (boolean)

isKnockedOut⚓︎

Read-only. If true, the actor is knocked out. An actor can be knocked out if their fatigue has been reduced below zero.

Returns:

  • result (boolean)

isMovingBack⚓︎

Direct access to the actor's current movement flags, showing if the actor is moving backwards.

Returns:

  • result (boolean)

isMovingForward⚓︎

Direct access to the actor's current movement flags, showing if the actor is moving forwards.

Returns:

  • result (boolean)
Example: Checking if a mobile actor is moving

There are many movement flags for mobile actors. To check if a mobile actor is moving at all, we need to check if the mobile is moving in each possible direction.

--- Returns true if the mobile is moving.
---@param mobile tes3mobileCreature|tes3mobileNPC|tes3mobilePlayer
---@return boolean
local function isMoving(mobile)
    return mobile.isMovingForward or mobile.isMovingBack or mobile.isMovingLeft or mobile.isMovingRight
end

isMovingLeft⚓︎

Direct access to the actor's current movement flags, showing if the actor is moving left.

Returns:

  • result (boolean)

isMovingRight⚓︎

Direct access to the actor's current movement flags, showing if the actor is moving right.

Returns:

  • result (boolean)

isParalyzed⚓︎

Read-only. If true, the actor is affected by the magic effect paralyze.

Returns:

  • result (boolean)

isPlayerDetected⚓︎

Direct access to the actor's flag showing the player was detected on the last detection check.

Returns:

  • result (boolean)

isPlayerHidden⚓︎

Direct access to the actor's flag showing the player was hidden on the last detection check.

Returns:

  • result (boolean)

isReadyingWeapon⚓︎

Read-only. If true, the actor is drawing or sheathing their weapon.

Returns:

  • result (boolean)

isRunning⚓︎

Direct access to the actor's current movement flags, showing if the actor is running.

Returns:

  • result (boolean)

isSliding⚓︎

Direct access to the actor's current movement flags, showing if the actor is sliding off a steep surface.

Returns:

  • result (boolean)

isSneaking⚓︎

Direct access to the actor's current movement flags, showing if the actor is sneaking.

Returns:

  • result (boolean)

isSpeaking⚓︎

Read-only. This property is true when the actor is speaking a dialogue line. This includes: hit grunts, combat reactions, and the usual dialogue.

Returns:

  • result (boolean)

isSwimming⚓︎

Direct access to the actor's current movement flags, showing if the actor is swimming.

Returns:

  • result (boolean)

isTurningLeft⚓︎

Direct access to the actor's current movement flags, showing if the actor is turning left.

Returns:

  • result (boolean)

isTurningRight⚓︎

Direct access to the actor's current movement flags, showing if the actor is turning right.

Returns:

  • result (boolean)

isWalking⚓︎

Direct access to the actor's current movement flags, showing if the actor is walking.

Returns:

  • result (boolean)

jump⚓︎

Direct access to the actor's jump effect attribute.

Returns:

  • result (number)

lastGroundZ⚓︎

This has a large negative value if the actor is on the ground. When the actor jumps, this will have a positive value. During jump event this value is still negative. A split second after, it will have the value of the .z coordinate when the actor was on the ground. Beware that this value changes after some amount of time while the actors is in the air.

Returns:

  • result (number)

levitate⚓︎

Direct access to the actor's levitate effect attribute.

Returns:

  • result (number)

luck⚓︎

Read-only. Direct access to the actor's luck attribute statistic. If you are setting player stats, instead use tes3.setStatistic to also update the UI immediately.

Returns:

magic⚓︎

Read-only. Direct access to the creature's magic statistic. This is a creature-specific generalization of skills, where this statistic is used in place of all magic skills. To get an individual skill value by skill ID, see the getSkillValue or getSkillStatistic methods.

Returns:

magicka⚓︎

Read-only. Access to the actor's magicka statistic. When modifying this value, prefer to use tes3.modStatistic or tes3.setStatistic to also update the UI immediately.

Returns:

magickaMultiplier⚓︎

Read-only. Access to the actor's magicka multiplier statistic.

Returns:

mobToMobCollision⚓︎

Allows modifying if this mobile will collide with other mobiles (actors and projectiles). When true (default), the actor cannot move through other actors, and projectiles will collide with actors. When false, the actor is allowed to move through other actors, and other actors can move through it. Projectiles will pass through actors and other projectiles.

May be useful when free movement is required in crowded situations, or to temporarily let the player move past an actor.

Returns:

  • result (boolean)

movementCollision⚓︎

Controls if the mobile has movement collision active. When false, the mobile can move through any object, but can still block other mobiles, and can still be hit in combat. Actors will still follow pathgrids, ramps and stairs when navigating.

Returns:

  • result (boolean)

movementFlags⚓︎

Access to the root mobile object movement flags, represented as an integer. Should not be accessed directly.

Returns:

  • result (integer)

moveSpeed⚓︎

Read-only. The calculated base movement speed.

Returns:

  • result (number)

nextActionWeight⚓︎

Read-only. No description yet available.

Returns:

  • result (number)

object⚓︎

Read-only. The actor object that maps to this mobile.

Returns:

objectType⚓︎

Read-only. The type of mobile object. Maps to values in tes3.objectType namespace.

Returns:

paralyze⚓︎

Direct access to the actor's paralyze effect attribute.

Returns:

  • result (number)

personality⚓︎

Read-only. Direct access to the actor's personality attribute statistic. If you are setting player stats, instead use tes3.setStatistic to also update the UI immediately.

Returns:

playerDistance⚓︎

The distance to the player. Updated every frame when the mobile is in an active cell.

Returns:

  • result (number)

position⚓︎

A vector that represents the 3D position of the object.

Returns:

prevMovementFlags⚓︎

Access to the root mobile object movement flags from the previous frame, represented as an integer. Should not be accessed directly.

Returns:

  • result (integer)

readiedAmmo⚓︎

The currently equipped ammo, if any.

Returns:

readiedAmmoCount⚓︎

The number of ammo equipped for the readied ammo.

Returns:

  • result (integer)

readiedShield⚓︎

The currently equipped shield, if any.

Returns:

readiedWeapon⚓︎

The currently equipped weapon, if any.

Returns:

reference⚓︎

Read-only. Access to the reference object for the mobile, if any.

Returns:

resistBlightDisease⚓︎

Direct access to the actor's blight disease resistance effect attribute.

Returns:

  • result (number)

resistCommonDisease⚓︎

Direct access to the actor's common disease resistance effect attribute.

Returns:

  • result (number)

resistCorprus⚓︎

Direct access to the actor's corprus disease resistance effect attribute.

Returns:

  • result (number)

resistFire⚓︎

Direct access to the actor's fire resistance effect attribute.

Returns:

  • result (number)

resistFrost⚓︎

Direct access to the actor's frost resistance effect attribute.

Returns:

  • result (number)

resistMagicka⚓︎

Direct access to the actor's magicka resistance effect attribute.

Returns:

  • result (number)

resistNormalWeapons⚓︎

Direct access to the actor's normal weapon resistance effect attribute.

Returns:

  • result (number)

resistParalysis⚓︎

Direct access to the actor's paralysis resistance effect attribute.

Returns:

  • result (number)

resistPoison⚓︎

Direct access to the actor's poison resistance effect attribute.

Returns:

  • result (number)

resistShock⚓︎

Direct access to the actor's shock resistance effect attribute.

Returns:

  • result (number)

runSpeed⚓︎

Read-only. The calculated run movement speed.

Returns:

  • result (number)

sanctuary⚓︎

Direct access to the actor's sanctuary effect attribute.

Returns:

  • result (number)

scanInterval⚓︎

The time interval in seconds between specific actor AI checks. These checks include checking for hostile actors and engaging combat, as well as checking if the actor should equip a light source if it is too dark. The specified time in seconds will always be increased by one second when checking, therefore a value of 0.0 will actually cause the actor AI checks to occur every second instead of every frame. Setting this to lower values than the default increases the impact on performance. The default value for a newly created actor depends on the total amount of all currently active tes3aiPlanner, meaning the checks will be executed at different intervals for each actor.

Returns:

  • result (number)

scanTimer⚓︎

Read-only. The time in seconds since the last time the checks specified in scanInterval were executed.

Returns:

  • result (number)

shield⚓︎

Direct access to the actor's shield effect attribute.

Returns:

  • result (number)

silence⚓︎

Direct access to the actor's silence effect attribute.

Returns:

  • result (number)

skills⚓︎

Read-only. An array-style table with access to the three creature skill statistics.

Returns:

sound⚓︎

Direct access to the actor's sound effect attribute.

Returns:

  • result (number)

speed⚓︎

Read-only. Direct access to the actor's speed attribute statistic. If you are setting player stats, instead use tes3.setStatistic to also update the UI immediately.

Returns:

spellReadied⚓︎

Read-only. Friendly access to the actor's flag that controls if the actor has a spell readied.

Returns:

  • result (boolean)

stealth⚓︎

Read-only. Direct access to the creature's stealth statistic. This is a creature-specific generalization of skills, where this statistic is used in place of all stealth skills. To get an individual skill value by skill ID, see the getSkillValue or getSkillStatistic methods.

Returns:

strength⚓︎

Read-only. Direct access to the actor's strength attribute statistic. If you are setting player stats, instead use tes3.setStatistic to also update the UI immediately.

Returns:

swiftSwim⚓︎

Direct access to the actor's swift swim effect attribute.

Returns:

  • result (number)

swimRunSpeed⚓︎

Read-only. The calculated swim movement speed while running.

Returns:

  • result (number)

swimSpeed⚓︎

Read-only. The calculated swim movement speed.

Returns:

  • result (number)

talkedTo⚓︎

Direct access to the actor's flag that shows it was recently talked to.

Returns:

  • result (boolean)

torchSlot⚓︎

The currently equipped light.

Returns:

underwater⚓︎

Read-only. Friendly access to the actor's flag that controls if the actor is under water.

Returns:

  • result (boolean)

velocity⚓︎

A vector that represents the 3D velocity of the object.

Tip

To change the velocity of an actor change this property during the calcMoveSpeed event.

Returns:

walkSpeed⚓︎

Read-only. The calculated walk movement speed.

Returns:

  • result (number)

waterBreathing⚓︎

Direct access to the actor's water breathing effect attribute.

Returns:

  • result (number)

waterWalking⚓︎

Direct access to the actor's water walking effect attribute.

Returns:

  • result (number)

weaponDrawn⚓︎

Read-only. Friendly access to the actor's flag that shows if the weapon model is visible. When readying a weapon, there is a short period of time at the start of the animation, where the weapon is not visible yet. This flag will only be set after this initial stage is done. This flag is still set with hand-to-hand even though it doesn't use a model. Setting this to false while a weapon is drawn will normally cause the actor to play its weapon draw animation again.

Returns:

  • result (boolean)

weaponReady⚓︎

A flag for if the actor has a weapon ready or being readied (visible and held in the hand). Setting it to true will cause the actor to take out their weapon. Setting it to false will cause the actor to put it away.

Returns:

  • result (boolean)

werewolf⚓︎

Read-only. Friendly access to the actor's flag that controls if the actor in werewolf form.

Returns:

  • result (boolean)

width⚓︎

Read-only. No description yet available.

Returns:

  • result (number)

willpower⚓︎

Read-only. Direct access to the actor's willpower attribute statistic. If you are setting player stats, instead use tes3.setStatistic to also update the UI immediately.

Returns:

Methods⚓︎

applyDamage⚓︎

Damages the actor, with options to control mitigation and difficulty scaling. Invokes the damage and damaged events, with tes3.damageSource.script source. Returns the actual damage done after armor mitigation and resistance, but before difficulty scaling.

local result = myObject:applyDamage({ damage = ..., applyArmor = ..., resistAttribute = ..., applyDifficulty = ..., playerAttack = ..., doNotChangeHealth = ... })

Parameters:

  • params (table)
    • damage (number): The amount of damage to apply.
    • applyArmor (boolean): Default: false. If armor should mitigate the incoming damage. If the player is the target, armor experience will be gained.
    • resistAttribute (tes3.effectAttribute): Optional. The resistance attribute that is applied to the damage. It can reduce damage or exploit weakness. Uses values from tes3.effectAttribute namespace.
    • applyDifficulty (boolean): Default: false. If the game difficulty modifier should be applied. Must be used with the playerAttack argument to apply the correct modifier.
    • playerAttack (boolean): Optional. If the attack came from the player. Used for difficulty calculation.
    • doNotChangeHealth (boolean): Default: false. If all armor effects except the health change should be applied. These include hit sounds, armor condition damage, and player experience gain from being hit.

Returns:

  • result (number)

applyFatigueDamage⚓︎

Damages the actor's fatigue, with accompanying reaction from the reciever. Invokes the damageHandToHand and damagedHandToHand events, with tes3.damageSource.script source. Returns the actual fatigue damage done.

local result = myObject:applyFatigueDamage(fatigueDamage, swing, alwaysPlayHitVoice)

Parameters:

  • fatigueDamage (number): The amount of fatigue damage to apply.
  • swing (number): Optional. The attack swing magnitude, range 0-1. Only modifies hit volume.
  • alwaysPlayHitVoice (boolean): Optional. Always play the hit reaction voiceover.

Returns:

  • result (number)

applyJumpFatigueCost⚓︎

Reduces the actor's current fatigue by the amount a regular jump would currently cost.

myObject:applyJumpFatigueCost()

calcEffectiveDamage⚓︎

Calculates the damage that would be inflicted to an actor after armor and/or resistance. Returns the actual damage done after armor mitigation and resistance, but before difficulty scaling.

local result = myObject:calcEffectiveDamage({ damage = ..., applyArmor = ..., resistAttribute = ... })

Parameters:

  • params (table)
    • damage (number): The amount of damage to apply.
    • applyArmor (boolean): Default: false. If armor should mitigate the incoming damage.
    • resistAttribute (tes3.effectAttribute): Optional. The resistance attribute that is applied to the damage. It can reduce damage or exploit weakness. Uses values from tes3.effectAttribute namespace.

Returns:

  • result (number)

calculateJumpVelocity⚓︎

Calculates the starting velocity of a jump.

local result = myObject:calculateJumpVelocity({ direction = ... })

Parameters:

  • params (table): Optional.
    • direction (tes3vector2): Optional. The ground direction vector used to calculate the velocity. If not specified, a zero-length direction vector for a regular jump without movement will be used.

Returns:

doJump⚓︎

Forces the actor to jump. If velocity or other parameters with non-default values are specified it will be treated as a non-default jump during the jump event. Returns false if the actor is currently unable to jump or the jump has been cancelled, otherwise returns true.

local result = myObject:doJump({ velocity = ..., applyFatigueCost = ..., allowMidairJumping = ... })

Parameters:

  • params (table): Optional.
    • velocity (tes3vector3): Optional. The initial velocity of the jump. If not specified, the velocity of a regular jump without movement will be used.
    • applyFatigueCost (boolean): Default: true. If true, reduces the actor's current fatigue by the amount a regular jump would currently cost. Will not reduce fatigue if false.
    • allowMidairJumping (boolean): Default: false. If true, enables the jump to be performed while already jumping or falling. Does not work during levitation or other methods of flying.

Returns:

  • result (boolean)

equip⚓︎

Equips an item, optionally adding the item if needed. If the best match is already equipped, it does not perform an unequip-equip cycle, but does return true. If the item cannot be equipped, it will return false.

Equip may fail for the following reasons: - The item cannot be found in the inventory. - The exact match cannot be found when itemData is provided. - When a weapon is being used to attack, it cannot be replaced.

local itemEquipped = myObject:equip({ item = ..., itemData = ..., addItem = ..., selectBestCondition = ..., selectWorstCondition = ... })

Parameters:

  • params (table)
    • item (tes3item, string): The item to equip.
    • itemData (tes3itemData): Optional. The item data of the specific item to equip, if a specific item is required.
    • addItem (boolean): Default: false. If true, the item will be added to the actor's inventory if needed.
    • selectBestCondition (boolean): Default: false. If true, the item in the inventory with the best condition and best charge will be selected.
    • selectWorstCondition (boolean): Default: false. If true, the item in the inventory with the worst condition and worst charge will be selected. Can be useful for selecting tools.

Returns:

  • itemEquipped (boolean)

equipMagic⚓︎

Equips a spell or enchantment, optionally equipping the enchanted item if needed. Returns false if the item could not be equipped.

local result = myObject:equipMagic({ source = ..., itemData = ..., equipItem = ..., updateGUI = ... })

Parameters:

  • params (table)

    • source (tes3spell, tes3item, string): The source of the magic to equip.

      Spells must be castable. Castable spells have a castType of tes3.spellType.spell or tes3.spellType.power. The actor is not required to know this spell.

      Items must have a castable enchantment. Castable enchantments have a castType of tes3.enchantmentType.onUse or tes3.enchantmentType.castOnce. The actor is not required to have this item in their inventory, unless equipItem is true.

    • itemData (tes3itemData): Optional. Only valid if an item has been assigned to source. The item data of the specific item to equip.

    • equipItem (boolean): Default: false. Only valid if an item has been assigned to source. If true, the item assigned to source will be equipped. Requires the actor to have the item in their inventory. If false, itemData must not be nil.
    • updateGUI (boolean): Default: true. Only valid if this actor is the player. If false, the player GUI will not be updated to reflect the change to equipped magic.

Returns:

  • result (boolean)

forceWeaponAttack⚓︎

Causes the actor to perform a weapon swing immediately towards its current target. For the player, it will swing and release immediately (minimum damage), and also may hit any target in range.

The actor must be in combat, with its weapon or hands readied, to be able to swing its weapon. This function does not interrupt existing attacks, casting, or any other actions. It returns true if it was able to start the weapon swing.

local result = myObject:forceWeaponAttack({ attackType = ..., swing = ... })

Parameters:

  • params (table)
    • attackType (tes3.physicalAttackType): Optional. The physical attack type to use for melee weapons (slash, chop, thrust). Maps to values in tes3.physicalAttackType namespace. When not specified, it uses a weighted random attack type for NPCs and creatures.
    • swing (number): Optional. The strength of the attack swing, in the range [0 to 1]. When not specified, the attack swing is randomized. This value cannot affect the player swing, as player attacks are driven by input.

Returns:

  • result (boolean)

getActiveMagicEffects⚓︎

Fetches a filtered list of the active magic effects on the actor.

local result = myObject:getActiveMagicEffects({ effect = ..., serial = ... })

Parameters:

  • params (table): Optional.
    • effect (tes3.effect, integer): Optional. The magic effect ID to search for, from tes3.effect table.
    • serial (integer): Optional. The magic instance serial to search for.

Returns:

getBootsWeight⚓︎

Read-only. Gets the weight of the boots equipped on the actor, or 0 if no boots are equipped.

local result = myObject:getBootsWeight()

Returns:

  • result (number)

getFatigueTerm⚓︎

Gets the fatigue-based skill scaling term used by many game mechanics, based on the actor's current and maximum fatigue. It is equal to max(0, fFatigueBase - fFatigueMult * max(0, 1 - fatigue.current/fatigue.base))

local result = myObject:getFatigueTerm()

Returns:

  • result (number)

getPowerUseTimestamp⚓︎

Finds the timestamp a recharging power was used. Powers recharge 24 hours after this timestamp. The timestamp units are hours. The current time as a timestamp can be accessed at tes3.getSimulationTimestamp().

local timestamp = myObject:getPowerUseTimestamp(power)

Parameters:

  • power (tes3spell): The spell object for the power.

Returns:

  • timestamp (number)

getSkillStatistic⚓︎

Fetches the statistic object of a skill with a given index. This is the way to access skills for any type of actor, as creatures have a limited version of the skill system. Note that creatures share a statistic between multiple skills (they only have combat, magic, and stealth stats), so many values will be the same.

local result = myObject:getSkillStatistic(skillId)

Parameters:

  • skillId (tes3.skill): The index of the skill statistic to fetch. Maps to values in tes3.skill namespace.

Returns:

getSkillValue⚓︎

Fetches the current value of a skill with a given index. This is the way to access skills for any type of actor, as creatures have a limited version of the skill system. Note that creatures share a statistic between multiple skills (they only have combat, magic, and stealth stats), so many values will be the same.

local result = myObject:getSkillValue(skillId)

Parameters:

  • skillId (tes3.skill): The index of the skill statistic's value to fetch. Maps to values in tes3.skill namespace.

Returns:

  • result (number)

getViewToActor⚓︎

Returns the angle between provided actor and the front side of the actor on whom the method was called. The returned angle is in degress in range [-180, 180], where 0 degrees is directly in front of the actor, the negative values are on the actor's left side, and positive values on the actor's right.

local angle = myObject:getViewToActor(mobile)

Parameters:

  • mobile (tes3mobileActor): The target actor to calculate the facing angle.

Returns:

  • angle (number): In range of [-180, 180] in degrees.

getViewToPoint⚓︎

Returns the angle between provided point in space and the front side of the actor on whom the method was called. The returned angle is in degress in range [-180, 180], where 0 degrees is directly in front of the actor, the negative values are on the actor's left side, and positive values on the actor's right.

local angle = myObject:getViewToPoint(point)

Parameters:

  • point (tes3vector3): The target point to calculate the facing angle.

Returns:

  • angle (number): In range of [-180, 180] in degrees.
Example: View cone testing

Using the getViewToPoint we can check whether a reference is inside a cone in front of the player.

-- These are view cone sizes in degrees
local viewCone = {
    first = 30,
    third = 45,
}

--- This will return true if the target is inside player's view cone.
--- It doesn't perform any checks if there is line connecting the player
--- and reference. In other words this won't check if the reference
--- isn't actually visible if it's covered by a building for example.
---@param ref tes3reference
---@return boolean
local function inPCViewCone(ref)
    local angle = math.abs(tes3.mobilePlayer:getViewToPoint(ref.position))
    local cone = (tes3.is3rdPerson() and viewCone.third) or viewCone.first
    if angle < cone then
        return true
    end
    return false
end

getViewToPointWithFacing⚓︎

Returns the angle between provided point in space and the actor's current position with provided facing (which effectively overrides the actor's facing used in other getViewTo methods). The returned angle is in degress in range [-180, 180], where 0 degrees is directly in front of the provided facing angle with the origin in actor's position.

local angle = myObject:getViewToPointWithFacing(facing, point)

Parameters:

  • facing (number): The facing angle in radians. The values should be in [0, PI] interval.
  • point (tes3vector3): The target point to calculate the facing angle.

Returns:

  • angle (number): In range of [-180, 180] in degrees.

getWeaponSpeed⚓︎

Fetches the weapon speed of the actor's currently equipped weapon, or 1.0 if no weapon is equipped.

local result = myObject:getWeaponSpeed()

Returns:

  • result (number)

hasUsedPower⚓︎

Check if a power has been used and is recharging.

local result = myObject:hasUsedPower(power)

Parameters:

  • power (tes3spell): The spell object for the power.

Returns:

  • result (boolean)

hitStun⚓︎

Induces hit stun on the actor. Without any parameters, it produces a brief stun that lasts about 1 second and prevents starting a new attack. It can produce other types of stun, see parameters. There are states where actors can't be stunned (such as already being in hit stun and paralysis). The function will return if the stun was successfuly applied.

local result = myObject:hitStun({ knockDown = ..., cancel = ... })

Parameters:

  • params (table): Optional.
    • knockDown (boolean): Optional. Changes the stun type to knockdown. This is when the character falls to their knees and takes several seconds to recover. It will interrupt spell casting.
    • cancel (boolean): Optional. Cancels hit stun and knockdown when used on the same frame as the hit. For regular combat, it should be used in the events damaged or damagedHandToHand.

Returns:

  • result (boolean)

isAffectedByObject⚓︎

Determines if the actor is currently being affected by a given alchemy, enchantment, or spell.

local result = myObject:isAffectedByObject(object)

Parameters:

Returns:

  • result (boolean)

kill⚓︎

Kills the actor by setting its health to 0.

myObject:kill()

overrideHeadTrackingThisFrame⚓︎

Warning

This part of the API isn't fully understood yet and thus is considered experimental. That means that there can be breaking changes requiring the code using this part of the API to be rewritten. The MWSE team will not make any effort to keep backward compatibility with the mods using experimental APIs.

Causes the actor to look towards this reference, while obey the usual head turning constraints. This must be called every frame in the simulate event to work. It will override regular head look behaviour and the target may be at any distance in the same worldspace.

myObject:overrideHeadTrackingThisFrame(target)

Parameters:

rechargePower⚓︎

Makes a power immediately available for casting again.

local result = myObject:rechargePower(power)

Parameters:

  • power (tes3spell): The spell object for the power.

Returns:

  • result (boolean)

resurrect⚓︎

Resurrects the actor, with more control over the resurrect logic compared to mwscript.

myObject:resurrect({ resetState = ..., moveToStartingLocation = ... })

Parameters:

  • params (table)
    • resetState (boolean): Default: true. Controls if the stats are reset, the inventory contents are respawned, and the reference recreated. This is the logic that mwscript resurrect uses. It can be useful to reset armor, ammunition, and consumables, if the player has already looted the body. When false, the base stats and inventory are unchanged.
    • moveToStartingLocation (boolean): Default: false. Controls if the actor should be moved to its spawn point on resurrection. Requires resetState to be true.

setPowerUseTimestamp⚓︎

Sets the timestamp a recharging power was used. Powers recharge 24 hours after this timestamp.

myObject:setPowerUseTimestamp(power, timestamp)

Parameters:

  • power (tes3spell): The spell object for the power.
  • timestamp (number): The timestamp of the moment the power was casted, or 24 hours before the recharge point. The timestamp units are hours. The current time as a timestamp can be accessed at tes3.getSimulationTimestamp().

startCombat⚓︎

Forces the actor into combat with another actor.

myObject:startCombat(target)

Parameters:

startDialogue⚓︎

Starts dialogue with this actor for the player.

myObject:startDialogue()

stopCombat⚓︎

Ends combat for the actor.

myObject:stopCombat(force)

Parameters:

  • force (boolean): Default: false. If false, the function won't stop combat if the actor has other valid hostile targets.

unequip⚓︎

Unequips one or more items from the actor.

local itemUnequipped = myObject:unequip({ item = ..., itemData = ..., type = ..., armorSlot = ..., clothingSlot = ... })

Parameters:

  • params (table)
    • item (tes3item, string): Optional. The item to unequip.
    • itemData (tes3itemData): Optional. The item data of the specific item to unequip, if a specific item is required.
    • type (tes3.objectType): Optional. The item type to unequip. Only used if no other parameter is provided. Only values pertaining to equipment from tes3.objectType can be passed here.
    • armorSlot (tes3.armorSlot): Optional. The armor slot to unequip. Maps to values in tes3.armorSlot namespace.
    • clothingSlot (tes3.clothingSlot): Optional. The clothing slot to unequip. Maps to values in tes3.clothingSlot namespace

Returns:

  • itemUnequipped (boolean)

unequipMagic⚓︎

Unequips the currently equipped magic, optionally unequipping the enchanted item if needed.

myObject:unequipMagic({ unequipItem = ..., updateGUI = ... })

Parameters:

  • params (table): Optional.
    • unequipItem (boolean): Default: false. Only valid if the currently equipped magic is from an equippable item enchantment. If true, the item containing the enchantment will be unequipped.
    • updateGUI (boolean): Default: true. Only valid if this actor is the player. If false, the player GUI will not be updated to reflect the change to equipped magic.

updateDerivedStatistics⚓︎

Updates statistics derived from attributes, which are magicka, fatigue, and encumbrance. Will also update the UI if used on the player. Normally handled automatically when you use tes3.modStatistic().

myObject:updateDerivedStatistics(attribute)

Parameters:

  • attribute (tes3statistic): Optional. Limits the update to statistics derived from this attribute. e.g. mobile:updateDerivedStatistics(mobile.strength). If not present, all derived statistics will be updated.

updateOpacity⚓︎

Updates the actor's visual opacity. Used after modifying applied chameleon or invisiblity effects.

myObject:updateOpacity()