Skip to content

AbilityTarget

A data type containing information about what the Player has targeted during a phase of an Ability.

Constructors

Constructor Name Return Type Description Tags
AbilityTarget.New() AbilityTarget Constructs a new Ability Target data object. None

Properties

Property Name Return Type Description Tags
hitObject Object Object under the reticle, or center of the screen if no reticle is displayed. Can be a Player, StaticMesh, etc. Read-Write
hitPlayer Player Convenience property that is the same as hitObject, but only if hitObject is a Player. Read-Write
spreadHalfAngle number Half-angle of cone of possible target space, in degrees. Read-Write
spreadRandomSeed integer Seed that can be used with RandomStream for deterministic RNG. Read-Write

Functions

Function Name Return Type Description Tags
GetOwnerMovementRotation() Rotation Gets the direction the Player is moving. None
SetOwnerMovementRotation(Rotation) None Sets the direction the Player faces, if Ability.facingMode is set to AbilityFacingMode.MOVEMENT. None
GetAimPosition() Vector3 Returns the world space position of the camera. None
SetAimPosition(Vector3) None The world space location of the camera. Setting this currently has no effect on the Player's camera. None
GetAimDirection() Vector3 Returns the direction the camera is facing. None
SetAimDirection(Vector3) None Sets the direction the camera is facing. None
GetHitPosition() Vector3 Returns the world space position of the object under the Player's reticle. If there is no object, a position under the reticle in the distance. If the Player doesn't have a reticle displayed, uses the center of the screen as if there was a reticle there. None
SetHitPosition(Vector3) None Sets the hit position property. This may affect weapon behavior. None
GetHitResult() HitResult Returns physics information about the point being targeted None
SetHitResult(HitResult) None Sets the hit result property. Setting this value has no affect on the Ability. None

Examples

Example using:

New

The ability's targeting data can be generated programmatically, for specific results. In this example, We create a target that is always at the world origin (Vector3.ZERO). If added to a rifle's Shoot ability, all shots will go to (0,0,0). For this to work the script should be placed in a client context under the ability. The ability should also have the option "Is Target Data Update" turned off for the Execute phase, otherwise any data set programmatically will be overwritten when the phase changes.

local abilityTarget = AbilityTarget.New()
abilityTarget:SetHitPosition(Vector3.ZERO)

local ability = script:FindAncestorByType("Ability")

function OnCast(ability)
    ability:SetTargetData(abilityTarget)
end

ability.castEvent:Connect(OnCast)

See also: AbilityTarget.SetHitPosition | CoreObject.FindAncestorByType | World.SpawnAsset | Ability.SetTargetData | Event.Connect


Example using:

GetAimPosition

GetAimDirection

In this example, a non-weapon ability needs to know where the player is aiming in order to spawn the effect correctly. It creates an effect that moves down the center of where the camera is aiming. However, if the effect were to begin at the camera's position that could be weird in a third-person game. Instead, the player's position is projected onto the camera's vector to determine a more suitable starting point.

local ability = script:FindAncestorByType("Ability")

function ProjectPointOnLine(p, linePoint, lineDirection)
    local lineToP = p - linePoint
    return linePoint + (lineToP..lineDirection) / (lineDirection..lineDirection) * lineDirection
end

function OnExecute(ability)
    local targetData = ability:GetTargetData()

    -- Project the player's position onto the camera vector, to get a starting point for the effect
    local playerPos = ability.owner:GetWorldPosition()
    local aimPosition = targetData:GetAimPosition()
    local aimDirection = targetData:GetAimDirection()
    local playerProjection = ProjectPointOnLine(playerPos, aimPosition, aimDirection)

    -- Placeholder for some ability effect. Draw a red line 9 meters long
    local params = {duration = 3, color = Color.RED, thickness = 3}
    CoreDebug.DrawLine(playerProjection, playerProjection + aimDirection * 900, params)
end

ability.executeEvent:Connect(OnExecute)

See also: CoreObject.FindAncestorByType | World.SpawnAsset | Vector3 - Vector3 | Ability.GetTargetData | Player.GetWorldPosition | Color.RED | CoreDebug.DrawLine | Event.Connect


Example using:

GetHitPosition

SetHitPosition

The ability's targeting data gives a lot of information about where and what the player is aiming at. If setup correctly, it can also be modified programmatically. In this example, the Z position of the target is flattened horizontally. Useful, for example, in a top-down shooter. For this to work it should be placed in a client context under the ability. The ability should also have the option "Is Target Data Update" turned off for the Execute phase, otherwise any data set programmatically will be overwritten when the phase changes.

local ability = script:FindAncestorByType("Ability")

function OnCast(ability)
    local abilityTarget = ability:GetTargetData()
    local pos = abilityTarget:GetHitPosition()

    pos.z = ability.owner:GetWorldPosition().z + 50

    abilityTarget:SetHitPosition(pos)
    ability:SetTargetData(abilityTarget)
end

ability.castEvent:Connect(OnCast)

See also: CoreObject.FindAncestorByType | World.SpawnAsset | Ability.GetTargetData | Vector3.z | Player.GetWorldPosition | Event.Connect


Example using:

GetHitResult

At any phase of an ability's activation, you can get data about what is under the cursor and would be hit.

This code snippet prints out the name of whatever was under the cursor when the player executes this ability.

local ability = script:FindAncestorByType("Ability")

function OnExecute(ability)
    local hr = ability:GetTargetData():GetHitResult()
    if hr.other then
        print("You shot " .. hr.other.name)
    else
        print("You didn't hit anything...")
    end
end

ability.executeEvent:Connect(OnExecute)

See also: CoreObject.FindAncestorByType | World.SpawnAsset | Ability.owner | HitResult.other | Player.name | Event.Connect | CoreLua.print


Example using:

hitObject

hitPlayer

In this example, an ability casts a magical area of effect (AOE) in front of the player. In case the player was aiming at another player or object that position is used instead.

local ability = script:FindAncestorByType("Ability")
local AOE_ASSET = script:GetCustomProperty("AOEAsset")

function OnExecute(ability)
    -- The default position to spawn at
    local ownerForwardVect = ability.owner:GetWorldTransform():GetForwardVector()
    local spawnPos = ability.owner:GetWorldPosition() + ownerForwardVect * 600 - Vector3.UP * 50

    -- Consider alternate positions based on the ability's targeting information
    local targetData = ability:GetTargetData()
    if targetData.hitPlayer then
        spawnPos = targetData.hitPlayer:GetWorldPosition()

    elseif targetData.hitObject then
        spawnPos = targetData:GetHitPosition()
    end

    -- Spawn the AOE object
    local instance = World.SpawnAsset(AOE_ASSET, {position = spawnPos})
    -- Give the AOE object a reference back to this ability. For example if the AOE kills an enemy,
    -- then it has enough information to correctly attribute a score increase.
    instance.serverUserData.sourceAbility = ability
end

ability.executeEvent:Connect(OnExecute)

See also: CoreObject.FindAncestorByType | World.SpawnAsset | Ability.owner | Player.GetWorldTransform | Transform.GetForwardVector | Vector3.UP | AbilityTarget.GetHitPosition | Object.serverUserData | Event.Connect


Example using:

spreadHalfAngle

spreadRandomSeed

In this example, a shotgun is configured to have a deterministic sequence of spread patterns. Both the angle and the randomness of the shots can be controlled in a way where they follow a predictable pattern of shots that repeats for every 5 shots. Some properties of the ability targeting can only be changed at runtime if the ability's execute phase has the property 'Is Target Data Updated' disabled. Otherwise, any changes to the target data are overridden at the start of the execute phase. The script expects to be placed under the shotgun's client context.

local WEAPON = script:FindAncestorByType("Weapon")
local SHOOT_ABILITY = WEAPON:GetAbilities()[1]

if SHOOT_ABILITY.executePhaseSettings.isTargetDataUpdated then
    warn("For dynamic spread angle to work, select the Shoot ability and disable its 'Is Target Data Updated' in the execute phase.")
end

local sequenceAngle = {
    10, 8, 6, 4, 2
}
local sequenceRngSeed = {
    1, 2, 3, 4, 5
}
local sequenceIndex = 1

function OnCast(ability)
    local targetData = ability:GetTargetData()

    targetData.spreadHalfAngle = sequenceAngle[sequenceIndex]
    targetData.spreadRandomSeed = sequenceRngSeed[sequenceIndex]

    ability:SetTargetData(targetData)

    sequenceIndex = sequenceIndex + 1
    if sequenceIndex > #sequenceAngle then
        sequenceIndex = 1
    end
end

SHOOT_ABILITY.castEvent:Connect(OnCast)

See also: AbilityPhaseSettings.isTargetDataUpdated | Ability.GetTargetData | CoreObject.FindAncestorByType | Weapon.GetAbilities



Last update: February 2, 2022