https://dev.epicgames.com/documentation/en-us/unreal-engine/using-gameplay-abilities-in-unreal-engine

Gameplay Ability

Overview of the Gameplay Ability class.

A Gameplay Ability, derived from the UGameplayAbility class, defines what an in-game ability does, what (if anything) it costs to use, when or under what conditions it can be used, and so on. Because Gameplay Abilities are capable of existing as instanced objects running asynchronously, you can run specialized, multi-stage tasks involving character animation, particle and sound effects, and even branching based on player input or character interactions that occur during execution. Gameplay Abilities can replicate themselves across the network, run on client or server machines (including client-side prediction support), and even sync variables and make Remote Procedure Calls (RPCs). Gameplay Abilities also provide flexibility in terms of how the Engine implements them during a game session, such as extensible functionality to implement cooldown and usage costs, player input, animation with Anim Montages, and reacting to the Ability itself being granted to an Actor.

Gameplay Ability 是從 UGameplayAbility 類派生出來的，它定義了一個游戲中技能的功能，包括其作用、是否有使用代價、何時或在什么條件下可以使用等內(nèi)容。

由于 Gameplay Abilities 能夠作為異步運行的實例對象存在，因此你可以運行一些特殊的、多階段的任務(wù)，這些任務(wù)可以涉及角色動畫、粒子和音效，甚至可以根據(jù)執(zhí)行過程中玩家的輸入或角色交互來進行分支。

Gameplay Abilities 可以在網(wǎng)絡(luò)中實現(xiàn)自我復(fù)制，可以在客戶端或服務(wù)器上運行（包括客戶端預(yù)測的支持），并且可以同步變量和進行遠程過程調(diào)用（RPC）。

Gameplay Abilities 還在游戲過程中提供了靈活的實現(xiàn)方式，比如可擴展的功能，用于實現(xiàn)冷卻時間和使用代價、玩家輸入、使用動畫蒙太奇（Anim Montages），以及響應(yīng)技能被賦予給某個 Actor 的事件等。

Granting and Revoking Abilities

Before an Actor can use an Ability, its Ability System Component must be granted that Ability. The following Ability System Component functions can grant access to an Ability:

• GiveAbility: Specifies the Ability to add with an FGameplayAbilitySpec, and returns an FGameplayAbilitySpecHandle. Only the server can give or revoke Abilities.

• GiveAbilityAndActivateOnce: Specifies the Ability to add with an FGameplayAbilitySpec, and returns an FGameplayAbilitySpecHandle. Because only the server can give Abilties, the Ability must be instanced and able to run on the server. After attempting to run the Ability, a FGameplayAbilitySpecHandle will be returned. If the Ability did not meet the required criteria, or if it could not execute, the return value will be invalid and the Ability System Component will not be granted the Ability.

Similar to giving abilities, only the server can remove abilities. The following functions can revoke access to an Ability from an Ability System Component, using the FGameplayAbilitySpecHandle that was returned when the Ability was granted:

• ClearAbility: Removes the specified Ability from the Ability System Component.

• SetRemoveAbilityOnEnd: Removes the specified Ability from the Ability System Component when that ability is finished executing. If the Ability is not executing, it will be removed immediately. If the Ability is executing, its input will be cleared immediately so that the player cannot reactivate or interact with it any further.

• ClearAllAbilities: Removes all Abilities from the Ability System Component. This function is the only one that does not require an FGameplayAbilitySpecHandle.

授予與移除技能（Granting and Revoking Abilities）

在一個 Actor 能夠使用某個技能之前，其 Ability System Component 必須被授予該技能。以下的 Ability System Component 函數(shù)可以用來授予技能：

• GiveAbility：使用一個 FGameplayAbilitySpec 指定要添加的技能，并返回一個 FGameplayAbilitySpecHandle。只有服務(wù)器可以授予或移除技能。

• GiveAbilityAndActivateOnce：使用一個 FGameplayAbilitySpec 指定要添加的技能，并返回一個 FGameplayAbilitySpecHandle。由于只有服務(wù)器可以授予技能，該技能必須是實例化的并能夠在服務(wù)器上運行。在嘗試運行該技能后，會返回一個 FGameplayAbilitySpecHandle。如果該技能不符合要求，或者無法執(zhí)行，返回值將無效，并且 Ability System Component 不會被授予該技能。

與授予技能類似，只有服務(wù)器可以移除技能。以下函數(shù)可以使用在授予技能時返回的 FGameplayAbilitySpecHandle 來撤銷 Ability System Component 對技能的訪問權(quán)限：

• ClearAbility：從 Ability System Component 中移除指定的技能。

• SetRemoveAbilityOnEnd：在指定的技能執(zhí)行完成后，從 Ability System Component 中移除該技能。如果該技能當(dāng)前未在執(zhí)行，則會立即被移除；如果正在執(zhí)行，其輸入會立即被清除，以防玩家再次激活或與之交互。

• ClearAllAbilities：從 Ability System Component 中移除所有技能。這個函數(shù)是唯一一個不需要 FGameplayAbilitySpecHandle 的函數(shù)。

Basic Usage

A Gameplay Ability's basic execution lifecycle, after being granted to an Actor's Ability System Component, looks like this:

1. CanActivateAbility lets the caller know whether or not an Ability is available for execution without attempting to execute it. For example, your user interface may need to gray out and deactivate icons that the player can't use, or play a sound or particle effect on the character to show that a certain Ability is available.

2. CallActivateAbility executes the game code associated with the Ability, but does not check to see if the Ability should be available. This function is usually called in cases where some logic is needed between the CanActivateAbility check and the execution of the Ability.

   • The main code that users need to override with their Ability's custom functionality is either the C++ function called ActivateAbility, or the Blueprint Event called Activate Ability.

   • Gameplay Abilities do not carry out their primary work in a "tick" function like Actors and Components do. Instead, they launch Ability Tasks during activation which do most of the work asynchronously, and then handle the output of those Tasks by hooking into Delegates (in C++) or connecting nodes to output execution pins (in Blueprints).

   • The CommitAbility function, if called from within Activate, will apply the cost of executing the Ability, such as by subtracting resources from Gameplay Attributes (such as "magic points", "stamina", or whatever fits your game's systems) and applying cooldowns.

   • CancelAbility provides a mechanism to cancel the Ability, although the Ability's CanBeCanceled function can reject the request. Unlike CommitAbility, this function is available for callers outside of the Ability itself. A successful cancelation will broadcast to On Gameplay Ability Cancelled before going through the standard code path for ending the Ability, giving the Ability a chance to run special cleanup code or otherwise behave differently when canceled than it would if it had ended on its own terms.

3. TryActivateAbility is the typical way to execute Abilities. This function calls CanActivateAbility to determine whether or not the Ability can run immediately, followed by CallActivateAbility if it can.

4. EndAbility (in C++) or the End Ability node (in Blueprints) shuts the Ability down when it is finished executing. If the Ability was canceled, the UGameplayAbility class will handle this automatically as part of the cancelation process, but in all other cases, the developer must call the C++ function or add the node into the Ability's Blueprint graph. Failing to end the ability properly will result in the Gameplay Ability System believing that the Ability is still running, and can have effects such as preventing future use of the Ability or any Ability that it blocks. For example, if your game has a "Drink Health Potion" Gameplay Ability that doesn't end properly, the character using that Ability will be unable to take any action that drinking a health potion would prevent, such as drinking another potion, sprinting, climbing ladders, and so on. This Ability blockage will continue indefinitely, since the Gameplay Ability System will think that the character is stil busy drinking the potion.

基本用法（Basic Usage）

一個 Gameplay Ability 被授予給 Actor 的 Ability System Component 后，其基本的執(zhí)行生命周期如下：

• CanActivateAbility 讓調(diào)用者知道該技能當(dāng)前是否可以執(zhí)行，但不會嘗試實際執(zhí)行它。例如，你的用戶界面可能需要將玩家當(dāng)前不能使用的技能圖標(biāo)變灰并禁用，或者在角色身上播放音效或粒子效果來表示某個技能已可用。

• CallActivateAbility 執(zhí)行與該技能關(guān)聯(lián)的游戲代碼，但不會檢查該技能是否應(yīng)該可以使用。這個函數(shù)通常用于在 CanActivateAbility 檢查與實際執(zhí)行之間需要額外邏輯處理的情況。

• 用戶需要重寫的主要代碼是：C++ 中的 ActivateAbility 函數(shù)，或者藍圖中的 Activate Ability 事件。

Gameplay Abilities 并不像 Actor 和 Component 那樣通過 “tick” 函數(shù)來執(zhí)行其主要工作。它們在激活時會啟動 Ability Tasks 來執(zhí)行大部分異步工作，并通過 C++ 中的 Delegates 或藍圖中的輸出執(zhí)行引腳來處理這些任務(wù)的輸出。

• CommitAbility 函數(shù)，如果在 Activate 函數(shù)中調(diào)用，將會應(yīng)用技能的使用代價，例如從 Gameplay Attributes（如“魔法值”、“體力”等）中扣除資源并觸發(fā)冷卻時間。

• CancelAbility 提供了一種機制來取消技能的執(zhí)行，盡管技能的 CanBeCanceled 函數(shù)可以拒絕取消請求。與 CommitAbility 不同，這個函數(shù)可以被技能外部的調(diào)用者使用。成功取消技能后，會廣播 On Gameplay Ability Cancelled，然后進入技能結(jié)束的標(biāo)準(zhǔn)流程，允許技能在取消時運行特殊的清理代碼，或在被取消的情況下以不同于正常結(jié)束的方式表現(xiàn)。

• TryActivateAbility 是執(zhí)行技能的典型方式。這個函數(shù)先調(diào)用 CanActivateAbility 檢查技能是否可以立即執(zhí)行，如果可以，則繼續(xù)調(diào)用 CallActivateAbility。

• EndAbility（在 C++ 中） 或藍圖中的 End Ability 節(jié)點用于在技能執(zhí)行完畢后關(guān)閉該技能。如果技能是被取消的，UGameplayAbility 類會在取消流程中自動處理，但在其他情況下，開發(fā)者必須手動調(diào)用 C++ 函數(shù)或在藍圖圖表中添加節(jié)點來結(jié)束技能。如果未正確結(jié)束技能，Gameplay Ability System 會認為該技能仍在運行，這可能導(dǎo)致無法再次使用該技能，或無法使用被其阻止的其他技能。

例如，如果你的游戲中有一個“喝治療藥水”的技能，但它沒有正確結(jié)束，那么角色將無法進行任何該技能會阻止的動作，例如再喝一瓶藥水、沖刺或爬梯子等。這種技能阻塞會無限持續(xù)，因為 Gameplay Ability System 會認為角色仍在喝藥水。

Tags

Gameplay Tags can help to determine how Gameplay Abilities interact with each other. Each Ability possesses a set of Tags that identify and categorize it in ways that can affect its behavior, as well as Gameplay Tag Containers and Gameplay Tag Queries to support these interactions with other Abilities.

Gameplay Tags 可以幫助判斷 Gameplay Abilities 之間如何相互作用。每個技能擁有一組標(biāo)簽，這些標(biāo)簽用于識別和分類該技能，并可能影響其行為。此外，還可以使用 Gameplay Tag Containers 和 Gameplay Tag Queries 來支持與其他技能之間的交互。

Replication

Gameplay Abilities support replication of internal state and Gameplay Events, or to turn replication off and save network bandwidth and CPU cycles. The Ability's Gameplay Ability Replication Policy can be set to "Yes" or "No", and this will control whether the Ability replicates instances of itself, makes state updates, or sends Gameplay Events across the network. This is not the same as replicating the activation or ending of the ability, which can occur regardless of that setting.

For multiplayer games with Abilities that do replicate, there are a few options for how replication is handled, known as the Gameplay Net Execution Policy:

1. Local Predicted: This option provides a good balance of responsiveness and accuracy. The Ability will run on the local client immediately upon the client issuing the command, but the server will have the final word, and can override the client in terms of what the Ability's actual impact was. The client is effectively asking permission from the server to execute the Ability, but also proceeding locally as if the server is expected to agree with the client's view of the outcome. Because the client is locally predicting the behavior of the Ability, it will feel perfectly smooth and lag-free as long as the server does not contradict the client's prediction.

2. Local Only: The client simply runs the Ability locally. There is no replication to the server, although the Ability will run on the server if the client using it is the host (playing on the physical server machine), or if this is a single-player game. This does not apply to dedicated-server games, as there is never a client playing on the server machine. Anything the client affects with this Ability will still follow normal replication protocol, including potentially receiving corrections from the server.

3. Server Initiated: Abilities that initiate on the server will propagate to clients. These are often more accurate, from the client's perspective, to what is actually happening on the server, but the client using the Ability will observe a delay due to the lack of local prediction. While this delay should be very short, some types of Abilities, especially rapidly-performed actions in pressured situations, will not feel as smooth as they would in Local Predicted mode.

4. Server Only: "Server Only" Abilities will run on the server, and will not replicate to clients. Any data outside of the Gameplay Ability will replicate as normal. In this way, the Ability can still have effects that clients observe, even though the Ability itself will only run on the server.

Replication
Gameplay Abilities 支持其內(nèi)部狀態(tài)和 Gameplay Events 的 Replication，也可以關(guān)閉 Replication，以節(jié)省網(wǎng)絡(luò)帶寬和 CPU 資源。Ability 的 Gameplay Ability Replication Policy 可設(shè)為 “Yes” 或 “No”，用來控制該 Ability 是否會復(fù)制其實例、更新狀態(tài)，或在網(wǎng)絡(luò)中發(fā)送 Gameplay Events。這個設(shè)置與 Ability 的激活或結(jié)束是否被復(fù)制無關(guān)——這些行為無論設(shè)置如何都可能發(fā)生。

對于在多人游戲中需要進行 Replication 的 Ability，有幾種 Replication 策略，稱為 Gameplay Net Execution Policy：

本地預(yù)測（Local Predicted）
這種方式在響應(yīng)速度與準(zhǔn)確性之間提供良好的平衡。客戶端在發(fā)出指令后會立刻在本地執(zhí)行 Ability，但最終的判定權(quán)在服務(wù)器，服務(wù)器可以對客戶端所認為的執(zhí)行結(jié)果進行覆蓋。客戶端等于是在向服務(wù)器請求許可的同時，預(yù)設(shè)服務(wù)器會同意，從而繼續(xù)本地執(zhí)行。由于客戶端進行了本地預(yù)測，只要服務(wù)器的反饋與其一致，使用體驗將非常順暢且無感延遲。

僅本地（Local Only）
客戶端僅在本地運行 Ability，不會將其 Replicate 到服務(wù)器。不過如果客戶端是主機（在服務(wù)器機器上運行）或是在單人模式中，則 Ability 同樣會在服務(wù)器上運行。在專用服務(wù)器（Dedicated Server）環(huán)境下，此方式不適用，因為不會有客戶端直接運行在服務(wù)器上。Ability 所產(chǎn)生的影響依然遵循正常的 Replication 流程，包括可能會從服務(wù)器收到的狀態(tài)修正。

服務(wù)器發(fā)起（Server Initiated）
Ability 由服務(wù)器發(fā)起，并同步到客戶端。從客戶端角度來看，這種方式能夠更準(zhǔn)確地反映服務(wù)器的實際狀態(tài)。但由于缺少本地預(yù)測，客戶端在觀察到 Ability 效果前會有一定延遲。雖然這個延遲通常較短，但對于需要快速操作的能力，尤其在高壓場景中，體驗上會比 Local Predicted 稍顯卡頓。

僅服務(wù)器（Server Only）
這類 Ability 只在服務(wù)器上運行，不會 Replicate 到客戶端。不過 Ability 之外的相關(guān)數(shù)據(jù)仍然會正常 Replicate。因此，盡管 Ability 本體僅在服務(wù)器上執(zhí)行，它產(chǎn)生的效果客戶端仍然可以觀察到。

Instancing Policy

When a Gameplay Ability executes, a new Object (of the Ability's type) will usually spawn to track the Ability in progress. Since Abilities can execute very frequently in some cases, such as battles between a hundred or more players and AI characters in Battle Royale, MOBA, MMO, or RTS games, there may be cases where rapid creation of Ability Objects can negatively impact performance. To address this, Abilities have a choice of three different instantiantion policies, offering tradeoffs between efficiency and functionality. The three supported instancing types supported are:

• Instanced per Execution: A copy of the Ability's Object will spawn each time the Ability runs. The advantage to this is that you can use Blueprint graphs and member variables freely, and everything will be initialized to default values at the beginning of the execution. While this is the simplest instancing policy to implement, it is ideal for Abilities that run infrequently due to the larger overhead involved. For example, an "Ultimate" in a MOBA would be a reasonable use case, as there tends to be a long cooldown (usually 60-90 seconds) between executions, and there are only a few characters (usually about ten) who can use these Abilities at all. A basic attack Ability used by the computer-controlled "minions" would be a poor candidate, as there may be hundreds of them at a time, and each can issue basic attacks fairly frequently, causing rapid creation (and possibly replication) of new Objects.

• Instanced per Actor: Each Actor will spawn one instance of this Ability when the Ability is first executed, and future executions will reuse it. This creates the requirement to clean up member variables between executions of the Ability, but also makes it possible to save information across multiple executions. Per-Actor is ideal for replication, as the Ability has a replicated Object that can handle variable changes and RPCs, but does not waste network bandwidth and CPU time spawning a new Object every time it runs. In larger-scale situations, this policy performs well, since large numbers of Actors using the Ability (for example, in a big battle) will only spawn Objects on their first Ability use.

• Non-Instanced: This is the most efficient instancing policy in all categories. The Ability will not spawn any Object when it runs, and will instead use the Class Default Object. However, this efficiency introduces several restrictions. First, this policy uniquely requires that the Ability is written entirely in C++, as Blueprint Graphs require an Object instance. You can create Blueprint classes of a non-instanced Ability, but only to change the default values of exposed Properties. Further, the Ability must not change member variables or bind Delegates during its execution of the Ability. The Ability also cannot replicate variables or handle RPCs. This should be used only for Abilities that require no internal variable storage (although setting Attributes on the user of the Ability is possible) and don't need to replicate any data. It is especially well-suited to Abilities that run frequently and are used by many characters, such as the basic attack used by units in a large-scale RTS or MOBA title.

Instancing Policy（實例化策略）
當(dāng)一個 Gameplay Ability 執(zhí)行時，通常會生成一個新的該類型的 Object（對象）來追蹤其執(zhí)行過程。由于在某些情況下（例如在 Battle Royale、MOBA、MMO 或 RTS 游戲中上百名玩家與 AI 的戰(zhàn)斗場景）Abilities 的執(zhí)行頻率可能非常高，頻繁創(chuàng)建 Ability Object 可能會對性能產(chǎn)生負面影響。為了解決這個問題，Ability 提供了三種不同的實例化策略，在效率與功能之間做出權(quán)衡。支持的三種實例化類型如下：

Instanced per Execution（每次執(zhí)行實例化）
每次執(zhí)行 Ability 時，都會生成該 Ability 的一個新對象副本。其優(yōu)點在于可以自由使用 Blueprint 圖表和成員變量，并且每次執(zhí)行時所有內(nèi)容都會重置為默認值。這是最易于實現(xiàn)的實例化策略，適用于不頻繁執(zhí)行的 Ability，因為它開銷較大。例如 MOBA 游戲中的“大招”就是一個典型例子，由于通常有較長的冷卻時間（60-90 秒），而且能使用大招的角色數(shù)量也很有限（大約十個）。相反，用于電腦控制“小兵”的普通攻擊能力就不適合，因為“小兵”數(shù)量可能成百上千，而且它們會頻繁使用普通攻擊，從而導(dǎo)致大量對象的快速創(chuàng)建（甚至可能涉及 Replication）。

Instanced per Actor（每個角色實例化一次）
每個 Actor（角色）在第一次執(zhí)行該 Ability 時會生成一個實例，之后的執(zhí)行都會復(fù)用這個實例。這就要求在每次執(zhí)行之間清理成員變量，但也可以在多次執(zhí)行之間保存信息。這種策略非常適合用于 Replication，因為 Ability 擁有一個可復(fù)制的對象，能夠處理變量同步與 RPC 調(diào)用，但不會在每次執(zhí)行時都浪費帶寬和 CPU 去創(chuàng)建新對象。在大規(guī)模場景中表現(xiàn)良好，例如一場大型戰(zhàn)斗中有大量角色使用某個 Ability，每個角色只在首次使用時實例化一次對象。

Non-Instanced（無實例化）
這是在所有方面性能最優(yōu)的實例化策略。執(zhí)行 Ability 時不會生成任何對象，而是直接使用該類的 Class Default Object（類默認對象）。但高效的代價是限制較多：
首先，該策略要求 Ability 必須完全使用 C++ 編寫，因為 Blueprint 圖表需要實例對象。雖然可以創(chuàng)建 Blueprint 類的非實例化 Ability，但只能用于修改暴露屬性的默認值。
此外，該 Ability 在執(zhí)行期間不得修改成員變量或綁定委托（Delegate），也無法進行變量復(fù)制或處理 RPC。
這種策略僅適用于不需要內(nèi)部變量存儲的能力（盡管仍可以設(shè)置 Ability 使用者的 Attributes），也不需要任何數(shù)據(jù)復(fù)制。它特別適合那些頻繁執(zhí)行、被大量角色使用的 Ability，例如 RTS 或 MOBA 游戲中單位的普通攻擊。

改變 Instancing Policy 會影響 Gameplay Ability 的行為方式。例如，OnAvatarSet、OnGiveAbility、ShouldAbilityRespondToEvent、OnRemoveAbility 和 CanActivateAbility 這些函數(shù)調(diào)用可以在不激活 Ability 的情況下發(fā)生。
如果使用 InstancedPerActor，這些調(diào)用會發(fā)生在 Ability 的實例上（因為賦予 Ability 時立即實例化）。
但如果使用 Non-Instanced 或 InstancedPerExecution，這些調(diào)用會發(fā)生在 Class Default Object 上，因為在調(diào)用發(fā)生時并沒有實例存在。

Triggering with Gameplay Events

Gameplay Events are data structures that can be passed around to trigger Gameplay Abilities directly, sending a data payload for context, without going through the normal channels. The usual way to do this is by calling Send Gameplay Event To Actor and providing an Actor that implements the IAbilitySystemInterface interface and the contextual information that Gameplay Events require, but it is also possible to call Handle Gameplay Event directly on an Ability System Component. Because this isn't the normal path to calling Gameplay Abilities, context information that the Ability may need will be passed in through the FGameplayEventData data structure. This structure is generic and will not be extended for any specific Gameplay Event or Ability, but should be sufficient for any use case. The polymorphic ContextHandle field will provide support for additional information as needed.