Skip to content

tes3actionData⚓︎

A substructure of mobile actors that provides information about the current or previous action.

Example: Active blocking system

A simple implementation that allows pressing the G key to rise shield and block the next enemy attack.

event.register(tes3.event.keyDown, function(e)
    if e.keyCode ~= tes3.scanCode.g then return end

    -- Start block anim.
    local animRefr = tes3.mobilePlayer.is3rdPerson and tes3.player1stPerson or tes3.player
    tes3.playAnimation({
        reference = animRefr,
        shield = tes3.animationGroup.shield,
        loopCount = 0
    })

    -- Pretend blocking state was triggered.
    -- When set, the controller will clean up the anim after it completes. Resets to 0 after clean up.
    tes3.mobilePlayer.actionData.blockingState = 2
end)

---@param e attackHitEventData
event.register(tes3.event.attackHit, function(e)
    local target = e.targetMobile
    if not target then return end

    local isBlocking = target.actionData.blockingState > 0

    if target.readiedShield and isBlocking then
        -- This blocks hits and redirects damage to the shield.
        -- If there is no shield, it still blocks damage, so check for a shield first.
        e.mobile.actionData.attackWasBlocked = true
    end
end)

Properties⚓︎

aiBehaviorState⚓︎

The behavior state. This maps to values in tes3.aiBehaviorState namespace.

Returns:

animationAttackState⚓︎

The actor's animation state. Maps to values in tes3.animationState namespace.

Returns:

attackSwing⚓︎

When attacking, this value represents how much the weapon has been pulled back. The value ranges from [0.0 - 1.0].

Returns:

  • result (number)

attackWasBlocked⚓︎

A flag that indicates if an attack failed its block check on the initial attack swing, and should be blocked if it connects. May be modified before the strike hits to cause the attack to be blocked. This flag negates damage even if no shield is equipped, so you should check if a shield is present before setting it.

Returns:

  • result (boolean)

blockingState⚓︎

A state index that indicates an actor's blocking state. It is zero when not blocking and non-zero when blocking. A value of 1 indicates a state transition from non-blocking to blocking, while a value of 2 means blocking is active (where the block animation is currently playing and should not be interrupted). The action simulation will reset the value to 0 at the end of a block animation.

Returns:

  • result (number)

currentAnimationGroup⚓︎

Actor's current animation group. Maps to values in tes3.animationGroup namespace.

Returns:

hitTarget⚓︎

The actor's attack target. The target will be saved in hitTarget field until a new attack is made. Missing an attack will clear hitTarget field.

Returns:

lastBarterHoursPassed⚓︎

A 16-bit hourstamp of the last time a merchant's barter gold was at its base level. It is used as a timer for resetting barter gold, which happens on interacting with a merchant at hourstamp lastBarterHoursPassed + GMST fBarterGoldResetDelay or later. Barter gold can also reset when a mobile expires.

Returns:

  • result (number)

lastPositionBeforeCombat⚓︎

When an actor enters combat, the last position is stored here so that they can navigate back after combat.

Returns:

nockedProjectile⚓︎

The currently nocked projectile the associated actor is using. It is available while charging a projectile attack, before releasing the projectile. This can be modified, but can only be set to nil, which will remove the projectile without consuming ammo.

Returns:

physicalAttackType⚓︎

A number from the tes3.physicalAttackType enumeration identifying the physical attack type. Can be tes3.physicalAttackType.slash, .chop, .thrust, .projectile, .creature1, .creature2, or .creature3.

Proper time to change the attack direction is the attackStart event. See the example below to see how.

Returns:

Example: Changing axe attack direction 
-- In this example, we force the attack
-- direction for axes to always be chop

---@param e attackStartEventData
local function onAttackStart(e)
    local mobile = e.reference.mobile
    if not mobile then return end

    local weapon = mobile.readiedWeapon.object --[[@as tes3weapon]]

    if weapon.type == tes3.weaponType.axeOneHand
    or weapon.type == tes3.weaponType.axeTwoHand then
        -- Now actually change the attack direction
        e.attackType = tes3.physicalAttackType.chop
    end
end

event.register(tes3.event.attackStart, onAttackStart)

physicalDamage⚓︎

When attacking, this is the value of the weapon damage that was rolled. This value takes into account the actor's strength, attack swing and weapon condition, but it doesn't include difficulty nor target's armor. This value is updated on an attack. After the attack this value will still contain the damage rolled. It will be refreshed on a new attack.

Returns:

  • result (number)

stolenFrom⚓︎

No description yet available.

Returns:

target⚓︎

The actor's attack target, stored until the actor attacks successfully again. In contrast to hitTarget, target property isn't cleared on missed attack.

Returns:

walkDestination⚓︎

If moving to a location, this is the position to be walked to.

Returns: