Skip to content

tes3mobilePlayer⚓︎

A mobile object for a the player.

This type inherits the following: tes3mobileNPC, tes3mobileActor, tes3mobileObject

Properties⚓︎

acrobatics⚓︎

Read-only. Direct access to the NPC's acrobatics skill statistic.

Returns:


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)

alchemy⚓︎

Read-only. Direct access to the NPC's alchemy skill statistic.

Returns:


alteration⚓︎

Read-only. Direct access to the NPC's alteration skill statistic.

Returns:


alwaysRun⚓︎

Toggle flag for if the player should always run.

Returns:

  • result (boolean)

animationController⚓︎

Read-only. Access to the player's animation controller.

Returns:


armorer⚓︎

Read-only. Direct access to the NPC's armorer skill statistic.

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)

athletics⚓︎

Read-only. Direct access to the NPC's athletics skill statistic.

Returns:


attackBonus⚓︎

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

Returns:

  • result (number)

attackDisabled⚓︎

Toggle flag for if the player can attack.

Returns:

  • result (boolean)

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.

Returns:


autoRun⚓︎

Toggle flag for if the player should constantly run forward.

Returns:

  • result (boolean)

axe⚓︎

Read-only. Direct access to the NPC's axe skill statistic.

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)

birthsign⚓︎

Read-only. The player's birthsign.

Returns:


blind⚓︎

Direct access to the actor's blind effect attribute.

Returns:

  • result (number)

block⚓︎

Read-only. Direct access to the NPC's block skill statistic.

Returns:


bluntWeapon⚓︎

Read-only. Direct access to the NPC's blunt weapon skill statistic.

Returns:


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:


bounty⚓︎

The player's current bounty.

Returns:

  • result (number)

cameraHeight⚓︎

Access to the player camera height, used for both the first person and third person camera (specifically the orbit centre). It is normally placed at head height by the game, on loading, or when a race is selected. The camera height can be reset to its regular value by setting this property to nil.

Returns:

  • result (number)
Example: Adjust the camera to match shrunken player scale
local function shrink()
    -- Shrink player.
    tes3.player.scale = 0.5
    -- Reset camera height to default value.
    tes3.mobilePlayer.cameraHeight = nil
    -- Modify camera height to match scale.
    tes3.mobilePlayer.cameraHeight = tes3.player.scale * tes3.mobilePlayer.cameraHeight
end

local function unshrink()
    tes3.player.scale = 1
    tes3.mobilePlayer.cameraHeight = nil
end

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)

castReady⚓︎

Toggle flag for if the player has casting ready.

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)

clawMultiplier⚓︎

Read-only. Quick access to the ClawMultiplier global variable.

Returns:


collidingReference⚓︎

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

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:


conjuration⚓︎

Read-only. Direct access to the NPC's conjuration skill statistic.

Returns:


controlsDisabled⚓︎

Toggle flag for if the player's controls are disabled.

Returns:

  • result (boolean)

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:


destruction⚓︎

Read-only. Direct access to the NPC's destruction skill statistic.

Returns:


dialogueList⚓︎

Read-only. Access to the collection that holds what dialogue topics the player has access to.

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[])

enchant⚓︎

Read-only. Direct access to the NPC's enchant skill statistic.

Returns:


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. It corresponds to the mobile.reference.orientation.z. Facing of 0 corresponds to the in game North, facing of PI corresponds to the game South. It's in clockwise direction.

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)

firstPerson⚓︎

Read-only. Quick access to the first person NPC.

Returns:


firstPersonReference⚓︎

Read-only. Quick access to the first person NPC's reference.

Returns:


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)

forceJump⚓︎

Toggle flag for if the NPC jumps.

Returns:

  • result (boolean)

forceMoveJump⚓︎

Toggle flag for if the NPC moves and jumps.

Returns:

  • result (boolean)

forceRun⚓︎

Toggle flag for if the NPC runs.

Returns:

  • result (boolean)

forceSneak⚓︎

Toggle flag for if the NPC sneaks.

Returns:

  • result (boolean)

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)

handToHand⚓︎

Read-only. Direct access to the NPC's hand to hand skill statistic.

Returns:


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.

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:


heavyArmor⚓︎

Read-only. Direct access to the NPC's heavy armor skill statistic.

Returns:


height⚓︎

The height of the mobile above the ground.

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)

illusion⚓︎

Read-only. Direct access to the NPC's illusion skill statistic.

Returns:


impulseVelocity⚓︎

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

Returns:


inactivityTime⚓︎

The time that the player has spent inactive.

Returns:

  • result (number)

inCombat⚓︎

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

Returns:

  • result (boolean)

inJail⚓︎

Toggle flag for if the player is currently in jail.

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)

is3rdPerson⚓︎

Read-only. Shows if the player's camera is currently in 3rd person view.

Returns:

  • result (boolean)

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)

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)

jumpingDisabled⚓︎

Toggle flag for if the player can jump.

Returns:

  • result (boolean)

knownWerewolf⚓︎

Read-only. Quick access to the KnownWerewolf global variable.

Returns:


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)

lastUsedAlembic⚓︎

Read-only. The last used alchemy alembic.

Returns:


lastUsedAmmoCount⚓︎

The amount of ammo for the ranged weapon that that was last equipped.

Returns:

  • result (number)

lastUsedCalcinator⚓︎

Read-only. The last used alchemy calcinator.

Returns:


lastUsedMortar⚓︎

Read-only. The last used alchemy mortar.

Returns:


lastUsedRetort⚓︎

Read-only. The last used alchemy retort.

Returns:


levelupPerSpecialization⚓︎

Read-only. Array-style table access to how many skill levels there have been for each of the 3 specializations.

Returns:

  • result (number[])

levelUpProgress⚓︎

The progress the player has made towards leveling up. Equal to the total amount of Minor and Major skill increases during the current level. This value can be larger than 10.

Returns:

  • result (integer)

levelupsPerAttribute⚓︎

Read-only. Array-style table access to how many skill levels there have been for each of the 8 attributes.

Returns:

  • result (number[])

levitate⚓︎

Direct access to the actor's levitate effect attribute.

Returns:

  • result (number)

lightArmor⚓︎

Read-only. Direct access to the NPC's light armor skill statistic.

Returns:


longBlade⚓︎

Read-only. Direct access to the NPC's long blade skill statistic.

Returns:


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:


magicDisabled⚓︎

Toggle flag for if the player can use magic.

Returns:

  • result (boolean)

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:


markLocation⚓︎

Read-only. Access to the structure that holds the player's current mark/recall location.

Returns:


marksman⚓︎

Read-only. Direct access to the NPC's marksman skill statistic.

Returns:


mediumArmor⚓︎

Read-only. Direct access to the NPC's medium armor skill statistic.

Returns:


mercantile⚓︎

Read-only. Direct access to the NPC's mercantile skill statistic.

Returns:


mobToMobCollision⚓︎

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

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

Returns:

  • result (boolean)

mouseLookDisabled⚓︎

Toggle flag for if the player's mouse look controls are disabled.

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)

mysticism⚓︎

Read-only. Direct access to the NPC's mysticism skill statistic.

Returns:


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)

restHoursRemaining⚓︎

How many hours are left while resting.

Returns:

  • result (integer)

restoration⚓︎

Read-only. Direct access to the NPC's restoration skill statistic.

Returns:


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)

security⚓︎

Read-only. Direct access to the NPC's security skill statistic.

Returns:


shield⚓︎

Direct access to the actor's shield effect attribute.

Returns:

  • result (number)

shortBlade⚓︎

Read-only. Direct access to the NPC's short blade skill statistic.

Returns:


silence⚓︎

Direct access to the actor's silence effect attribute.

Returns:

  • result (number)

skillProgress⚓︎

Read-only. Array-style table access to skill progress for each of the 27 skills.

Warning

The first index in the array is 1, but skill indices in tes3.skill table start from 0.

Returns:

  • result (number[])

skills⚓︎

Read-only. An array-style table with access to the twenty seven NPC skill statistics (tes3statisticSkill).

Returns:


sleeping⚓︎

Toggle flag for if the player is currently sleeping.

Returns:

  • result (boolean)

sneak⚓︎

Read-only. Direct access to the NPC's sneak skill statistic.

Returns:


sound⚓︎

Direct access to the actor's sound effect attribute.

Returns:

  • result (number)

spear⚓︎

Read-only. Direct access to the NPC's spear skill statistic.

Returns:


speechcraft⚓︎

Read-only. Direct access to the NPC's speechcraft skill statistic.

Returns:


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)

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)

telekinesis⚓︎

Direct access to the player's telekinesis effect attribute.

Returns:

  • result (number)

torchSlot⚓︎

The currently equipped light.

Returns:


traveling⚓︎

Toggle flag for if the player is currently travelling.

Returns:

  • result (boolean)

unarmored⚓︎

Read-only. Direct access to the NPC's unarmored skill statistic.

Returns:


underwater⚓︎

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

Returns:

  • result (boolean)

vanityDisabled⚓︎

Toggle flag for if the player's vanity camera is disabled.

Returns:

  • result (boolean)

velocity⚓︎

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

Returns:


viewSwitchDisabled⚓︎

Toggle flag for if the player can switch between first person and vanity cameras.

Returns:

  • result (boolean)

visionBonus⚓︎

Direct access to the player's vision bonus effect attribute.

Returns:

  • result (number)

waiting⚓︎

Toggle flag for if the player is currently waiting.

Returns:

  • result (boolean)

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 player has a weapon ready or being readied (visible and held in the hand). Setting it to true will cause the player to take out their weapon. Setting it to false will cause the player 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)

exerciseSkill⚓︎

Exercises a skill, providing experience in it. Invokes exerciseSkill event.

myObject:exerciseSkill(skill, progress)

Parameters:

  • skill (tes3.skill): The skill index to give experience to. Maps to values from tes3.skill table.
  • progress (number): The amount of experience to grant.

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)

getSkillProgressRequirement⚓︎

Returns the total progress needed to progress the skill to the next level. The actual amount of progress needed is the floor of the value returned by this function.

local progressNeeded = myObject:getSkillProgressRequirement(skill)

Parameters:

Returns:

  • progressNeeded (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()

progressSkillLevelIfRequirementsMet⚓︎

Checks to see if a skill is ready to be leveled up, and performs any levelup logic.

myObject:progressSkillLevelIfRequirementsMet(skill)

Parameters:


progressSkillToNextLevel⚓︎

Increments the player's skill to the next level, while respecting all level up mechanics.

local newLevel = myObject:progressSkillToNextLevel(skill)

Parameters:

Returns:

  • newLevel (integer)

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()