API 가이드: AbilitySystemComponent의 Ability 관련 기능

개요

언리얼 엔진의 AbilitySystemComponent는 게임플레이 어빌리티 시스템(Gameplay Ability System, GAS)의 핵심 구성 요소입니다. 게임플레이 어빌리티 시스템은 액터에게 특별한 능력, 스킬, 효과 등을 부여하고 관리하기 위한 언리얼 엔진의 프레임워크입니다.

이 가이드에서는 특히 AbilitySystemComponent의 어빌리티(Ability) 관련 기능과 API에 초점을 맞춥니다. 주요 내용은 다음과 같습니다:

  1. 어빌리티 부여 및 활성화 관리
  2. 어빌리티 스펙(Spec) 구성 및 처리
  3. 어빌리티 활성화와 네트워크 복제 연동
  4. 입력 시스템과 어빌리티 연결
  5. 어빌리티 태그 기반 관리 및 필터링

AbilitySystemComponent는 다양한 게임 장르에서 캐릭터 능력, 스킬, 공격, 버프, 디버프 등을 모듈화하고 확장 가능한 방식으로 구현할 수 있게 해주는 강력한 도구입니다.

클래스/함수별 상세 설명

AbilitySystemComponent 클래스

UAbilitySystemComponent는 UGameplayTasksComponent를 상속받고, IGameplayTagAssetInterface와 IAbilitySystemReplicationProxyInterface 인터페이스를 구현하는 컴포넌트입니다. 이 컴포넌트는 액터에게 어빌리티 시스템을 제공하며, 어빌리티 관리, 게임플레이 이펙트, 어트리뷰트 등을 처리합니다.

UCLASS(ClassGroup=AbilitySystem, hidecategories=(Object,LOD,Lighting,Transform,Sockets,TextureStreaming), editinlinenew, meta=(BlueprintSpawnableComponent))
class GAMEPLAYABILITIES_API UAbilitySystemComponent : public UGameplayTasksComponent, public IGameplayTagAssetInterface, public IAbilitySystemReplicationProxyInterface

어빌리티 부여 및 관리 함수

어빌리티 부여 함수

GiveAbility

FGameplayAbilitySpecHandle GiveAbility(const FGameplayAbilitySpec& AbilitySpec);
  • 목적: 어빌리티를 부여합니다.
  • 매개변수:
    • AbilitySpec: 부여할 어빌리티의 스펙 정보
  • 반환값: 어빌리티 스펙 핸들(활성화에 사용)
  • 설명: 이 함수는 새로운 어빌리티를 시스템에 추가합니다. 액터가 권한(Authority)을 가진 경우에만 작동합니다.

K2_GiveAbility (블루프린트 호출 가능)

UFUNCTION(BlueprintCallable, BlueprintAuthorityOnly, Category = "Gameplay Abilities", meta = (DisplayName = "Give Ability", ScriptName = "GiveAbility"))
FGameplayAbilitySpecHandle K2_GiveAbility(TSubclassOf<UGameplayAbility> AbilityClass, int32 Level = 0, int32 InputID = -1);
  • 목적: 블루프린트에서 어빌리티를 부여하기 위한 함수
  • 매개변수:
    • AbilityClass: 부여할 어빌리티 클래스
    • Level: 어빌리티 레벨 (기본값: 0)
    • InputID: 어빌리티 활성화에 사용할 입력 ID (기본값: -1, 입력 바인딩 없음)
  • 반환값: 어빌리티 스펙 핸들
  • 설명: 지정된 클래스의 어빌리티를 지정된 레벨로 생성하고 시스템에 추가합니다. BlueprintAuthorityOnly 태그는 이 함수가 서버에서만 호출될 수 있음을 의미합니다.

GiveAbilityAndActivateOnce

FGameplayAbilitySpecHandle GiveAbilityAndActivateOnce(FGameplayAbilitySpec& Spec, const FGameplayEventData* GameplayEventData = nullptr);
  • 목적: 어빌리티를 부여하고 즉시 한 번만 활성화합니다.
  • 매개변수:
    • Spec: 부여 및 활성화할 어빌리티 스펙
    • GameplayEventData: 활성화에 사용할 이벤트 데이터 (선택 사항)
  • 반환값: 어빌리티 스펙 핸들
  • 설명: 어빌리티를 부여하고 즉시 활성화한 후, 활성화가 끝나면 자동으로 제거합니다. 서버에서만 작동하며, 로컬 또는 로컬 예측 실행 정책을 가진 어빌리티에는 사용할 수 없습니다.

K2_GiveAbilityAndActivateOnce

UFUNCTION(BlueprintCallable, BlueprintAuthorityOnly, Category = "Gameplay Abilities", meta = (DisplayName = "Give Ability And Activate Once", ScriptName = "GiveAbilityAndActivateOnce"))
FGameplayAbilitySpecHandle K2_GiveAbilityAndActivateOnce(TSubclassOf<UGameplayAbility> AbilityClass, int32 Level = 0, int32 InputID = -1);
  • 목적: 블루프린트에서 어빌리티를 부여하고 즉시 한 번만 활성화하기 위한 함수
  • 작동 방식: GiveAbilityAndActivateOnce의 블루프린트 호출 가능 버전입니다.

어빌리티 제거 함수

ClearAbility

UFUNCTION(BlueprintCallable, BlueprintAuthorityOnly, Category = "Gameplay Abilities")
void ClearAbility(const FGameplayAbilitySpecHandle& Handle);
  • 목적: 특정 어빌리티를 제거합니다.
  • 매개변수:
    • Handle: 제거할 어빌리티의 핸들
  • 설명: 지정된 핸들을 가진 어빌리티를 시스템에서 제거합니다. 서버에서만 작동합니다.

ClearAllAbilities

UFUNCTION(BlueprintCallable, BlueprintAuthorityOnly, Category="Gameplay Abilities")
void ClearAllAbilities();
  • 목적: 모든 어빌리티를 제거합니다.
  • 설명: 이 함수는 모든 어빌리티를 시스템에서 제거합니다. 서버에서만 작동합니다.

ClearAllAbilitiesWithInputID

UFUNCTION(BlueprintCallable, BlueprintAuthorityOnly, Category = "Gameplay Abilities")
void ClearAllAbilitiesWithInputID(int32 InputID = 0);
  • 목적: 특정 입력 ID에 바인딩된 모든 어빌리티를 제거합니다.
  • 매개변수:
    • InputID: 제거할 어빌리티의 입력 ID (기본값: 0)
  • 설명: 지정된 입력 ID를 가진 모든 어빌리티를 시스템에서 제거합니다. 서버에서만 작동합니다.

SetRemoveAbilityOnEnd

void SetRemoveAbilityOnEnd(FGameplayAbilitySpecHandle AbilitySpecHandle);
  • 목적: 어빌리티가 끝난 후 자동으로 제거되도록 설정합니다.
  • 매개변수:
    • AbilitySpecHandle: 설정할 어빌리티의 핸들
  • 설명: 어빌리티가 활성화된 상태라면 종료 시 제거하도록 표시하고, 그렇지 않다면 즉시 제거합니다.

어빌리티 활성화 함수

TryActivateAbility

UFUNCTION(BlueprintCallable, Category = "Abilities")
bool TryActivateAbility(FGameplayAbilitySpecHandle AbilityToActivate, bool bAllowRemoteActivation = true);
  • 목적: 특정 어빌리티를 활성화하려고 시도합니다.
  • 매개변수:
    • AbilityToActivate: 활성화할 어빌리티의 핸들
    • bAllowRemoteActivation: 원격 활성화 허용 여부 (기본값: true)
  • 반환값: 활성화 시도 성공 여부 (나중에 실패할 수도 있음)
  • 설명: 지정된 어빌리티를 활성화하려고 시도합니다. 비용과 요구사항을 확인합니다. 원격 활성화가 허용되면 클라이언트에서 서버 어빌리티를 활성화할 수 있습니다.

TryActivateAbilityByClass

UFUNCTION(BlueprintCallable, Category = "Abilities")
bool TryActivateAbilityByClass(TSubclassOf<UGameplayAbility> InAbilityToActivate, bool bAllowRemoteActivation = true);
  • 목적: 지정된 클래스의 어빌리티를 활성화하려고 시도합니다.
  • 매개변수:
    • InAbilityToActivate: 활성화할 어빌리티 클래스
    • bAllowRemoteActivation: 원격 활성화 허용 여부 (기본값: true)
  • 반환값: 활성화 시도 성공 여부
  • 설명: 지정된 클래스의 어빌리티를 찾아 활성화하려고 시도합니다.

TryActivateAbilitiesByTag

UFUNCTION(BlueprintCallable, Category = "Abilities")
bool TryActivateAbilitiesByTag(const FGameplayTagContainer& GameplayTagContainer, bool bAllowRemoteActivation = true);
  • 목적: 지정된 태그를 가진 모든 어빌리티를 활성화하려고 시도합니다.
  • 매개변수:
    • GameplayTagContainer: 필요한 태그 컨테이너
    • bAllowRemoteActivation: 원격 활성화 허용 여부 (기본값: true)
  • 반환값: 활성화된 어빌리티가 하나라도 있는지 여부
  • 설명: 태그와 일치하는 모든 어빌리티를 찾아 활성화를 시도합니다.

InternalTryActivateAbility

bool InternalTryActivateAbility(FGameplayAbilitySpecHandle AbilityToActivate, FPredictionKey InPredictionKey = FPredictionKey(), UGameplayAbility ** OutInstancedAbility = nullptr, FOnGameplayAbilityEnded::FDelegate* OnGameplayAbilityEndedDelegate = nullptr, const FGameplayEventData* TriggerEventData = nullptr);
  • 목적: 어빌리티 활성화 과정의 내부 구현입니다.
  • 매개변수:
    • AbilityToActivate: 활성화할 어빌리티의 핸들
    • InPredictionKey: 예측 키 (선택 사항)
    • OutInstancedAbility: 인스턴스화된 어빌리티 출력 포인터 (선택 사항)
    • OnGameplayAbilityEndedDelegate: 어빌리티 종료 시 호출할 대리자 (선택 사항)
    • TriggerEventData: 이벤트 데이터 (선택 사항)
  • 반환값: 활성화 성공 여부
  • 설명: 이 함수는 어빌리티 활성화의 실제 로직을 처리합니다. 비용 확인, 태그 요구사항 확인, 인스턴스화 등을 수행합니다.

어빌리티 검색 및 조회 함수

GetAllAbilities

UFUNCTION(BlueprintCallable, BlueprintPure = false, Category = "Gameplay Abilities")
void GetAllAbilities(TArray<FGameplayAbilitySpecHandle>& OutAbilityHandles) const;
  • 목적: 모든 부여된 어빌리티의 핸들을 반환합니다.
  • 매개변수:
    • OutAbilityHandles: 결과 핸들을 저장할 배열
  • 설명: 현재 활성화 가능한 모든 어빌리티의 핸들을 출력 배열에 채웁니다.

FindAllAbilitiesWithTags

UFUNCTION(BlueprintCallable, BlueprintPure = false, Category = "Gameplay Abilities")
void FindAllAbilitiesWithTags(TArray<FGameplayAbilitySpecHandle>& OutAbilityHandles, FGameplayTagContainer Tags, bool bExactMatch = true) const;
  • 목적: 특정 태그를 가진 모든 어빌리티를 찾습니다.
  • 매개변수:
    • OutAbilityHandles: 결과 핸들을 저장할 배열
    • Tags: 찾을 태그
    • bExactMatch: 정확히 일치해야 하는지 여부 (기본값: true)
  • 설명: 지정된 태그와 일치하는 모든 어빌리티를 찾아 출력 배열에 채웁니다.

FindAllAbilitiesMatchingQuery

UFUNCTION(BlueprintCallable, BlueprintPure = false, Category = "Gameplay Abilities")
void FindAllAbilitiesMatchingQuery(TArray<FGameplayAbilitySpecHandle>& OutAbilityHandles, FGameplayTagQuery Query) const;
  • 목적: 특정 태그 쿼리와 일치하는 모든 어빌리티를 찾습니다.
  • 매개변수:
    • OutAbilityHandles: 결과 핸들을 저장할 배열
    • Query: 게임플레이 태그 쿼리
  • 설명: 태그 쿼리와 일치하는 모든 어빌리티를 찾아 출력 배열에 채웁니다.

FindAllAbilitiesWithInputID

UFUNCTION(BlueprintCallable, BlueprintPure = false, Category = "Gameplay Abilities")
void FindAllAbilitiesWithInputID(TArray<FGameplayAbilitySpecHandle>& OutAbilityHandles, int32 InputID = 0) const;
  • 목적: 특정 입력 ID를 가진 모든 어빌리티를 찾습니다.
  • 매개변수:
    • OutAbilityHandles: 결과 핸들을 저장할 배열
    • InputID: 찾을 입력 ID (기본값: 0)
  • 설명: 지정된 입력 ID에 바인딩된 모든 어빌리티를 찾아 출력 배열에 채웁니다.

FindAbilitySpecFromHandle

FGameplayAbilitySpec* FindAbilitySpecFromHandle(FGameplayAbilitySpecHandle Handle, EConsiderPending ConsiderPending = EConsiderPending::PendingRemove) const;
  • 목적: 특정 핸들을 가진 어빌리티 스펙을 찾습니다.
  • 매개변수:
    • Handle: 찾을 어빌리티 핸들
    • ConsiderPending: 대기 중인 어빌리티를 고려할지 여부
  • 반환값: 찾은 어빌리티 스펙 포인터 (찾지 못한 경우 nullptr)
  • 설명: 지정된 핸들과 일치하는 어빌리티 스펙을 찾습니다.

FindAbilitySpecFromClass

FGameplayAbilitySpec* FindAbilitySpecFromClass(TSubclassOf<UGameplayAbility> InAbilityClass) const;
  • 목적: 특정 클래스의 어빌리티 스펙을 찾습니다.
  • 매개변수:
    • InAbilityClass: 찾을 어빌리티 클래스
  • 반환값: 찾은 어빌리티 스펙 포인터 (찾지 못한 경우 nullptr)
  • 설명: 지정된 클래스의 어빌리티 스펙을 찾습니다.

FindAbilitySpecFromInputID

FGameplayAbilitySpec* FindAbilitySpecFromInputID(int32 InputID) const;
  • 목적: 특정 입력 ID를 가진 어빌리티 스펙을 찾습니다.
  • 매개변수:
    • InputID: 찾을 입력 ID
  • 반환값: 찾은 어빌리티 스펙 포인터 (찾지 못한 경우 nullptr)
  • 설명: 지정된 입력 ID에 바인딩된 어빌리티 스펙을 찾습니다.

어빌리티 취소 함수

CancelAbility

void CancelAbility(UGameplayAbility* Ability);
  • 목적: 특정 어빌리티를 취소합니다.
  • 매개변수:
    • Ability: 취소할 어빌리티
  • 설명: 지정된 어빌리티를 취소합니다.

CancelAbilityHandle

void CancelAbilityHandle(const FGameplayAbilitySpecHandle& AbilityHandle);
  • 목적: 특정 핸들을 가진 어빌리티를 취소합니다.
  • 매개변수:
    • AbilityHandle: 취소할 어빌리티의 핸들
  • 설명: 지정된 핸들을 가진 어빌리티를 취소합니다.

CancelAbilities

void CancelAbilities(const FGameplayTagContainer* WithTags=nullptr, const FGameplayTagContainer* WithoutTags=nullptr, UGameplayAbility* Ignore=nullptr);
  • 목적: 특정 태그 조건을 만족하는 어빌리티를 취소합니다.
  • 매개변수:
    • WithTags: 포함해야 하는 태그 (선택 사항)
    • WithoutTags: 포함하지 않아야 하는 태그 (선택 사항)
    • Ignore: 무시할 어빌리티 (선택 사항)
  • 설명: 태그 조건을 만족하는 모든 어빌리티를 취소합니다.

CancelAllAbilities

void CancelAllAbilities(UGameplayAbility* Ignore=nullptr);
  • 목적: 모든 어빌리티를 취소합니다.
  • 매개변수:
    • Ignore: 무시할 어빌리티 (선택 사항)
  • 설명: 지정된 어빌리티를 제외한 모든 어빌리티를 취소합니다.

어빌리티 차단 함수

BlockAbilitiesWithTags

void BlockAbilitiesWithTags(const FGameplayTagContainer& Tags);
  • 목적: 특정 태그를 가진 어빌리티를 차단합니다.
  • 매개변수:
    • Tags: 차단할 태그
  • 설명: 지정된 태그를 가진 어빌리티의 활성화를 차단합니다.

UnBlockAbilitiesWithTags

void UnBlockAbilitiesWithTags(const FGameplayTagContainer& Tags);
  • 목적: 특정 태그를 가진 어빌리티의 차단을 해제합니다.
  • 매개변수:
    • Tags: 차단 해제할 태그
  • 설명: 지정된 태그를 가진 어빌리티의 차단을 해제합니다.

BlockAbilityByInputID

void BlockAbilityByInputID(int32 InputID);
  • 목적: 특정 입력 ID를 가진 어빌리티를 차단합니다.
  • 매개변수:
    • InputID: 차단할 입력 ID
  • 설명: 지정된 입력 ID에 바인딩된 어빌리티의 활성화를 차단합니다.

UnBlockAbilityByInputID

void UnBlockAbilityByInputID(int32 InputID);
  • 목적: 특정 입력 ID를 가진 어빌리티의 차단을 해제합니다.
  • 매개변수:
    • InputID: 차단 해제할 입력 ID
  • 설명: 지정된 입력 ID에 바인딩된 어빌리티의 차단을 해제합니다.

IsAbilityInputBlocked

bool IsAbilityInputBlocked(int32 InputID) const;
  • 목적: 특정 입력 ID가 차단되었는지 확인합니다.
  • 매개변수:
    • InputID: 확인할 입력 ID
  • 반환값: 차단 여부
  • 설명: 지정된 입력 ID가 차단되었는지 확인합니다.

입력 시스템 연동 함수

BindToInputComponent

virtual void BindToInputComponent(UInputComponent* InputComponent);
  • 목적: 어빌리티 시스템을 입력 컴포넌트에 바인딩합니다.
  • 매개변수:
    • InputComponent: 바인딩할 입력 컴포넌트
  • 설명: 기본 확인 및 취소 액션에 대한 바인딩을 설정합니다.

BindAbilityActivationToInputComponent

virtual void BindAbilityActivationToInputComponent(UInputComponent* InputComponent, FGameplayAbilityInputBinds BindInfo);
  • 목적: 어빌리티 활성화를 입력 컴포넌트에 바인딩합니다.
  • 매개변수:
    • InputComponent: 바인딩할 입력 컴포넌트
    • BindInfo: 바인딩 설정 정보
  • 설명: 지정된 입력 바인딩 정보를 사용하여 어빌리티를 입력에 바인딩합니다.

AbilityLocalInputPressed

virtual void AbilityLocalInputPressed(int32 InputID);
  • 목적: 로컬 입력 누름 이벤트를 처리합니다.
  • 매개변수:
    • InputID: 누른 입력 ID
  • 설명: 지정된 입력 ID에 바인딩된 어빌리티의 입력 누름 이벤트를 처리합니다.

AbilityLocalInputReleased

virtual void AbilityLocalInputReleased(int32 InputID);
  • 목적: 로컬 입력 해제 이벤트를 처리합니다.
  • 매개변수:
    • InputID: 해제한 입력 ID
  • 설명: 지정된 입력 ID에 바인딩된 어빌리티의 입력 해제 이벤트를 처리합니다.

PressInputID

UFUNCTION(BlueprintCallable, Category = "Gameplay Abilities")
void PressInputID(int32 InputID);
  • 목적: 입력 ID를 프로그래밍 방식으로 누릅니다.
  • 매개변수:
    • InputID: 누를 입력 ID
  • 설명: 지정된 입력 ID를 프로그래밍 방식으로 누르는 것과 같은 효과를 냅니다.

ReleaseInputID

UFUNCTION(BlueprintCallable, Category = "Gameplay Abilities")
void ReleaseInputID(int32 InputID);
  • 목적: 입력 ID를 프로그래밍 방식으로 해제합니다.
  • 매개변수:
    • InputID: 해제할 입력 ID
  • 설명: 지정된 입력 ID를 프로그래밍 방식으로 해제하는 것과 같은 효과를 냅니다.

액터 정보 설정 함수

InitAbilityActorInfo

virtual void InitAbilityActorInfo(AActor* InOwnerActor, AActor* InAvatarActor);
  • 목적: 어빌리티 액터 정보를 초기화합니다.
  • 매개변수:
    • InOwnerActor: 소유 액터
    • InAvatarActor: 아바타 액터
  • 설명: 소유 액터와 아바타 액터를 설정하고 어빌리티 액터 정보를 초기화합니다. 아바타 액터는 어빌리티가 실제로 작용하는 물리적 액터입니다.

SetAvatarActor

void SetAvatarActor(AActor* InAvatarActor);
  • 목적: 아바타 액터를 변경합니다.
  • 매개변수:
    • InAvatarActor: 새 아바타 액터
  • 설명: 소유 액터는 그대로 두고 아바타 액터만 변경합니다.

기타 어빌리티 관련 함수

GetAnimatingAbility

UGameplayAbility* GetAnimatingAbility();
  • 목적: 현재 애니메이션을 재생 중인 어빌리티를 반환합니다.
  • 반환값: 애니메이션 중인 어빌리티
  • 설명: 현재 몽타주를 재생 중인 어빌리티를 반환합니다.

IsAnimatingAbility

bool IsAnimatingAbility(UGameplayAbility* Ability) const;
  • 목적: 지정된 어빌리티가 현재 애니메이션을 재생 중인지 확인합니다.
  • 매개변수:
    • Ability: 확인할 어빌리티
  • 반환값: 애니메이션 중인지 여부
  • 설명: 지정된 어빌리티가 현재 몽타주를 재생 중인지 확인합니다.

GetUserAbilityActivationInhibited

UFUNCTION(BlueprintCallable, Category="Abilities")
bool GetUserAbilityActivationInhibited() const;
  • 목적: 사용자 어빌리티 활성화가 억제되었는지 확인합니다.
  • 반환값: 억제 여부
  • 설명: 사용자 어빌리티 활성화가 억제되었는지 확인합니다. 이는 입력 처리나 UI 표시 등에 영향을 줍니다.

SetUserAbilityActivationInhibited

UFUNCTION(BlueprintCallable, Category="Abilities")
virtual void SetUserAbilityActivationInhibited(bool NewInhibit);
  • 목적: 사용자 어빌리티 활성화 억제 상태를 설정합니다.
  • 매개변수:
    • NewInhibit: 새 억제 상태
  • 설명: 사용자 어빌리티 활성화 억제 상태를 설정합니다. 이는 게임 메커니즘(침묵, 무력화 등)이 아닌 입력/UI 관련 억제에만 사용해야 합니다. 이 함수는 로컬 소유 플레이어에서만 호출되어야 합니다.

게임플레이 이벤트 처리 함수

HandleGameplayEvent

virtual int32 HandleGameplayEvent(FGameplayTag EventTag, const FGameplayEventData* Payload);
  • 목적: 게임플레이 이벤트를 처리합니다.
  • 매개변수:
    • EventTag: 이벤트 태그
    • Payload: 이벤트 데이터
  • 반환값: 성공적으로 활성화된 어빌리티 수
  • 설명: 게임플레이 이벤트를 처리하고 이벤트에 대응하는 어빌리티를 활성화합니다.

TriggerAbilityFromGameplayEvent

bool TriggerAbilityFromGameplayEvent(FGameplayAbilitySpecHandle AbilityToTrigger, FGameplayAbilityActorInfo* ActorInfo, FGameplayTag Tag, const FGameplayEventData* Payload, UAbilitySystemComponent& Component);
  • 목적: 게임플레이 이벤트로부터 어빌리티를 트리거합니다.
  • 매개변수:
    • AbilityToTrigger: 트리거할 어빌리티 핸들
    • ActorInfo: 액터 정보
    • Tag: 이벤트 태그
    • Payload: 이벤트 데이터
    • Component: 어빌리티 시스템 컴포넌트
  • 반환값: 트리거 성공 여부
  • 설명: 게임플레이 이벤트를 사용하여 특정 어빌리티를 트리거합니다.

네트워크 관련 함수

InternalServerTryActivateAbility

virtual void InternalServerTryActivateAbility(FGameplayAbilitySpecHandle AbilityToActivate, bool InputPressed, const FPredictionKey& PredictionKey, const FGameplayEventData* TriggerEventData);
  • 목적: 서버에서 어빌리티 활성화를 처리합니다.
  • 매개변수:
    • AbilityToActivate: 활성화할 어빌리티 핸들
    • InputPressed: 입력이 눌렸는지 여부
    • PredictionKey: 예측 키
    • TriggerEventData: 이벤트 데이터 (선택 사항)
  • 설명: 서버에서 클라이언트 요청에 응답하여 어빌리티 활성화를 처리합니다.

ServerTryActivateAbility

UFUNCTION(Server, reliable, WithValidation)
void ServerTryActivateAbility(FGameplayAbilitySpecHandle AbilityToActivate, bool InputPressed, FPredictionKey PredictionKey);
  • 목적: 서버에 어빌리티 활성화를 요청합니다.
  • 매개변수:
    • AbilityToActivate: 활성화할 어빌리티 핸들
    • InputPressed: 입력이 눌렸는지 여부
    • PredictionKey: 예측 키
  • 설명: 클라이언트에서 서버에 어빌리티 활성화를 요청합니다. Server 태그는 이 함수가 클라이언트에서 서버로의 RPC임을 나타냅니다.

ClientTryActivateAbility

UFUNCTION(Client, reliable)
void ClientTryActivateAbility(FGameplayAbilitySpecHandle AbilityToActivate);
  • 목적: 클라이언트에게 어빌리티 활성화를 요청합니다.
  • 매개변수:
    • AbilityToActivate: 활성화할 어빌리티 핸들
  • 설명: 서버에서 클라이언트에게 어빌리티 활성화를 요청합니다. Client 태그는 이 함수가 서버에서 클라이언트로의 RPC임을 나타냅니다.

ServerEndAbility / ClientEndAbility

UFUNCTION(Server, reliable, WithValidation)
void ServerEndAbility(FGameplayAbilitySpecHandle AbilityToEnd, FGameplayAbilityActivationInfo ActivationInfo, FPredictionKey PredictionKey);

UFUNCTION(Client, reliable)
void ClientEndAbility(FGameplayAbilitySpecHandle AbilityToEnd, FGameplayAbilityActivationInfo ActivationInfo);
  • 목적: 어빌리티 종료를 네트워크에 복제합니다.
  • 매개변수:
    • AbilityToEnd: 종료할 어빌리티 핸들
    • ActivationInfo: 활성화 정보
    • PredictionKey: 예측 키 (서버 함수만 해당)
  • 설명: 어빌리티 종료를 네트워크에 복제하여 모든 클라이언트가 동일한 상태를 유지하도록 합니다.

ServerCancelAbility / ClientCancelAbility

UFUNCTION(Server, reliable, WithValidation)
void ServerCancelAbility(FGameplayAbilitySpecHandle AbilityToCancel, FGameplayAbilityActivationInfo ActivationInfo);

UFUNCTION(Client, reliable)
void ClientCancelAbility(FGameplayAbilitySpecHandle AbilityToCancel, FGameplayAbilityActivationInfo ActivationInfo);
  • 목적: 어빌리티 취소를 네트워크에 복제합니다.
  • 매개변수:
    • AbilityToCancel: 취소할 어빌리티 핸들
    • ActivationInfo: 활성화 정보
  • 설명: 어빌리티 취소를 네트워크에 복제하여 모든 클라이언트가 동일한 상태를 유지하도록 합니다.

ClientActivateAbilityFailed

UFUNCTION(Client, Reliable)
void ClientActivateAbilityFailed(FGameplayAbilitySpecHandle AbilityToActivate, int16 PredictionKey);
  • 목적: 어빌리티 활성화 실패를 클라이언트에게 알립니다.
  • 매개변수:
    • AbilityToActivate: 활성화 실패한 어빌리티 핸들
    • PredictionKey: 예측 키
  • 설명: 서버에서 클라이언트의 어빌리티 활성화 요청이 실패했을 때 클라이언트에게 알립니다.

ClientActivateAbilitySucceed

UFUNCTION(Client, Reliable)
void ClientActivateAbilitySucceed(FGameplayAbilitySpecHandle AbilityToActivate, FPredictionKey PredictionKey);
  • 목적: 어빌리티 활성화 성공을 클라이언트에게 알립니다.
  • 매개변수:
    • AbilityToActivate: 활성화 성공한 어빌리티 핸들
    • PredictionKey: 예측 키
  • 설명: 서버에서 클라이언트의 어빌리티 활성화 요청이 성공했을 때 클라이언트에게 알립니다.

CallServerTryActivateAbility / CallServerEndAbility

void CallServerTryActivateAbility(FGameplayAbilitySpecHandle AbilityHandle, bool InputPressed, FPredictionKey PredictionKey);
void CallServerEndAbility(FGameplayAbilitySpecHandle AbilityHandle, FGameplayAbilityActivationInfo ActivationInfo, FPredictionKey PredictionKey);
  • 목적: 내부적으로 서버 RPC를 호출합니다.
  • 매개변수:
    • AbilityHandle: 어빌리티 핸들
    • InputPressed / ActivationInfo: 입력 상태 / 활성화 정보
    • PredictionKey: 예측 키
  • 설명: 이 함수들은 RPC 배치 처리를 지원하는 래퍼 함수입니다. 일반적인 함수 호출 시에는 바로 RPC를 호출하지만, 배치 모드에서는 여러 RPC를 모아서 한 번에 보냅니다.

몽타주 관련 함수

PlayMontage

virtual float PlayMontage(UGameplayAbility* AnimatingAbility, FGameplayAbilityActivationInfo ActivationInfo, UAnimMontage* Montage, float InPlayRate, FName StartSectionName = NAME_None, float StartTimeSeconds = 0.0f);
  • 목적: 어빌리티와 연결된 몽타주를 재생합니다.
  • 매개변수:
    • AnimatingAbility: 애니메이션을 재생하는 어빌리티
    • ActivationInfo: 활성화 정보
    • Montage: 재생할 몽타주
    • InPlayRate: 재생 속도
    • StartSectionName: 시작 섹션 이름 (선택 사항)
    • StartTimeSeconds: 시작 시간 (선택 사항)
  • 반환값: 몽타주 지속 시간 (-1은 실패)
  • 설명: 어빌리티와 연결된 몽타주를 재생하고, 네트워크 복제 및 예측을 처리합니다.

GetCurrentMontage

UAnimMontage* GetCurrentMontage() const;
  • 목적: 현재 재생 중인 몽타주를 반환합니다.
  • 반환값: 현재 몽타주 (없으면 nullptr)
  • 설명: 현재 재생 중인 몽타주를 반환합니다.

CurrentMontageStop

virtual void CurrentMontageStop(float OverrideBlendOutTime = -1.0f);
  • 목적: 현재 재생 중인 몽타주를 중지합니다.
  • 매개변수:
    • OverrideBlendOutTime: 블렌드 아웃 시간 오버라이드 (선택 사항)
  • 설명: 현재 재생 중인 몽타주를 중지합니다.

사용 예시

1. 기본 어빌리티 시스템 설정

// 액터 클래스 내부
UPROPERTY()
UAbilitySystemComponent* AbilitySystemComponent;

// 생성자나 BeginPlay에서
AbilitySystemComponent = CreateDefaultSubobject<UAbilitySystemComponent>(TEXT("AbilitySystemComponent"));
AbilitySystemComponent->InitAbilityActorInfo(this, this);

2. 어빌리티 부여 및 활성화

// 블루프린트에서 호출할 수 있는 함수
UFUNCTION(BlueprintCallable, Category = "Abilities")
void GiveFireballAbility()
{
    if (AbilitySystemComponent && HasAuthority())
    {
        // 어빌리티 부여
        FGameplayAbilitySpecHandle AbilityHandle = AbilitySystemComponent->K2_GiveAbility(
            FireballAbilityClass,  // TSubclassOf<UGameplayAbility>
            1,                     // 레벨
            0                      // 입력 ID
        );
        
        // 입력 바인딩을 사용하지 않고 직접 활성화할 수도 있음
        AbilitySystemComponent->TryActivateAbility(AbilityHandle);
    }
}

3. 입력과 어빌리티 연결

// 입력 컴포넌트 설정 시
void AMyCharacter::SetupPlayerInputComponent(UInputComponent* PlayerInputComponent)
{
    Super::SetupPlayerInputComponent(PlayerInputComponent);
    
    // 어빌리티 입력 바인딩 설정
    if (AbilitySystemComponent)
    {
        AbilitySystemComponent->BindAbilityActivationToInputComponent(
            PlayerInputComponent,
            FGameplayAbilityInputBinds(
                "Confirm",       // 확인 명령어
                "Cancel",        // 취소 명령어
                "EAbilityInputID", // 바인딩 열거형
                static_cast<int32>(EAbilityInputID::Confirm),  // 확인 입력 ID
                static_cast<int32>(EAbilityInputID::Cancel)    // 취소 입력 ID
            )
        );
    }
}

4. 태그 기반 어빌리티 활성화

// 특정 태그의 모든 어빌리티 활성화
void AMyCharacter::ActivateAllFireAbilities()
{
    if (AbilitySystemComponent)
    {
        FGameplayTagContainer FireTags;
        FireTags.AddTag(FGameplayTag::RequestGameplayTag(FName("Ability.Fire")));
        
        AbilitySystemComponent->TryActivateAbilitiesByTag(FireTags);
    }
}

5. 어빌리티 차단 및 취소

// 특정 태그의 어빌리티 차단
void AMyCharacter::BlockFireAbilities()
{
    if (AbilitySystemComponent)
    {
        FGameplayTagContainer FireTags;
        FireTags.AddTag(FGameplayTag::RequestGameplayTag(FName("Ability.Fire")));
        
        // 화염 태그가 있는 어빌리티 차단
        AbilitySystemComponent->BlockAbilitiesWithTags(FireTags);
        
        // 화염 태그가 있는 활성화된 어빌리티 취소
        AbilitySystemComponent->CancelAbilities(&FireTags);
    }
}

// 차단 해제
void AMyCharacter::UnblockFireAbilities()
{
    if (AbilitySystemComponent)
    {
        FGameplayTagContainer FireTags;
        FireTags.AddTag(FGameplayTag::RequestGameplayTag(FName("Ability.Fire")));
        
        AbilitySystemComponent->UnBlockAbilitiesWithTags(FireTags);
    }
}

6. 게임플레이 이벤트로 어빌리티 트리거

// 게임플레이 이벤트로 어빌리티 트리거
void AMyCharacter::TriggerAbilityFromDamage(float Damage, FGameplayTag DamageTag)
{
    if (AbilitySystemComponent)
    {
        FGameplayEventData EventData;
        EventData.EventTag = DamageTag;
        EventData.EventMagnitude = Damage;
        
        AbilitySystemComponent->HandleGameplayEvent(DamageTag, &EventData);
    }
}

베스트 프랙티스 및 주의사항

1. 라이프사이클 관리

  • 컴포넌트 초기화: InitAbilityActorInfo를 반드시 호출하여 어빌리티 시스템을 초기화해야 합니다. 일반적으로 BeginPlay나 OnPossessed에서 호출합니다.
  • 컴포넌트 정리: DestroyActiveState를 사용하여 모든 활성 어빌리티를 취소하고 정리합니다. 이는 일반적으로 EndPlay나 OnUnpossessed에서 호출합니다.
  • 포제션(Possession) 변경 처리: 컨트롤러 변경 시 SetAvatarActor를 호출하여 새 컨트롤러에 맞게 어빌리티 시스템을 업데이트합니다.

2. 네트워크 관련 주의사항

  • 권한 확인: 어빌리티 부여 및 제거는 서버에서만 수행해야 합니다. IsOwnerActorAuthoritative를 사용하여 권한을 확인합니다.
  • 예측 모드: 로컬 예측 모드로 설정된 어빌리티는 클라이언트에서 실행되고 서버에서 확인됩니다. 이는 빠른 응답성을 제공하지만 복잡성이 증가합니다.
  • 복제 모드: SetReplicationMode를 사용하여 어빌리티 시스템의 복제 모드를 설정합니다. 일반적으로 Full 모드가 가장 안전하지만, 네트워크 대역폭을 더 많이 사용합니다.

3. 성능 고려사항

  • 어빌리티 수: 활성화 가능한 어빌리티 수를 관리하세요. 너무 많은 어빌리티는 메모리 및 복제 비용을 증가시킵니다.
  • 태그 쿼리 최적화: 빈번한 태그 쿼리는 성능에 영향을 줄 수 있습니다. 가능한 경우 결과를 캐시하거나 쿼리 빈도를 제한하세요.
  • 예측 키 관리: 예측 키를 올바르게 관리하지 않으면 네트워크 성능과 게임플레이 경험에 영향을 줄 수 있습니다. 예측 키를 생성하고 전파하는 방법에 주의하세요.

4. 어빌리티 관리

  • 인스턴스 정책: 어빌리티 인스턴스 정책(NonInstanced, InstancedPerActor, InstancedPerExecution)을 신중하게 선택하세요. 각 정책은 메모리 사용량과 동작 방식에 영향을 줍니다.
  • 실행 정책: 어빌리티 실행 정책(LocalOnly, LocalPredicted, ServerOnly, ServerInitiated)에 따라 네트워크 동작이 달라집니다. 각 어빌리티의 요구사항에 맞는 정책을 선택하세요.
  • 태그 요구사항: 어빌리티의 태그 요구사항(Required, Blocked)을 사용하여 어빌리티 간 상호작용을 관리하세요.

5. 디버깅

  • PrintDebug: AbilitySystemComponent::PrintDebug()를 사용하여 어빌리티 시스템의 상태를 디버깅합니다.
  • 로깅: ABILITY_LOG 매크로를 사용하여 어빌리티 시스템 관련 로그를 출력합니다.
  • 시각적 디버깅: 게임플레이 디버거를 사용하여 실행 중인 어빌리티 및 이펙트를 시각적으로 디버깅합니다.

추가 참고 사항

1. 확장 및 커스터마이징

  • 커스텀 어빌리티 시스템 컴포넌트: 필요에 따라 UAbilitySystemComponent를 상속받아 커스텀 기능을 추가할 수 있습니다.
  • 가상 함수 오버라이드: InternalTryActivateAbility, NotifyAbilityEnded 등의 가상 함수를 오버라이드하여 어빌리티 활성화 및 종료 시 커스텀 로직을 추가할 수 있습니다.
  • 콜백 활용: AbilityActivatedCallbacks, AbilityEndedCallbacks 등의 델리게이트를 활용하여 어빌리티 이벤트에 반응할 수 있습니다.

2. 다른 시스템과의 통합

  • 애니메이션 시스템: PlayMontage, GetCurrentMontage 등의 함수를 사용하여 어빌리티와 애니메이션을 연동할 수 있습니다.
  • 입력 시스템: BindAbilityActivationToInputComponent를 사용하여 어빌리티와 입력을 연동할 수 있습니다.
  • 게임플레이 태그: 태그 시스템을 활용하여 어빌리티 간 상호작용을 관리할 수 있습니다.
  • 어트리뷰트 시스템: 어빌리티 시스템 컴포넌트는 어트리뷰트 세트를 관리하여 캐릭터 스탯과 어빌리티를 연동할 수 있습니다.

3. 고급 기능

  • RPC 배치 처리: BeginServerAbilityRPCBatch와 EndServerAbilityRPCBatch를 사용하여 여러 RPC를 배치로 처리할 수 있습니다. 이는 네트워크 성능을 향상시킬 수 있습니다.
  • 예측 시스템: FScopedPredictionWindow를 사용하여 클라이언트 예측 및 서버 확인을 관리할 수 있습니다.
  • 어빌리티 태스크: 어빌리티 내에서 UAbilityTask를 사용하여 비동기 작업을 처리할 수 있습니다.

4. 알려진 제한사항

  • 복잡한 복제 로직: 어빌리티 시스템의 복제 로직은 복잡하며, 특히 비표준 네트워크 설정에서 문제가 발생할 수 있습니다.
  • 디버깅 어려움: 예측 및 네트워크 관련 문제는 디버깅이 어려울 수 있습니다. 디버깅 도구와 로깅을 적극적으로 활용하세요.
  • 실행 순서 의존성: 어빌리티 시스템의 많은 부분은 실행 순서에 의존합니다. 초기화 및 종료 순서를 신중하게 관리하세요.

이 API 가이드는 AbilitySystemComponent의 어빌리티 관련 기능에 대한 개요를 제공합니다. 게임의 요구사항에 맞게 어빌리티 시스템을 효과적으로 활용하려면 이 가이드와 함께 공식 문서와 예제를 참조하는 것이 좋습니다.

'개발일지(Unreal5) > GAS[Gameplay Ability System]' 카테고리의 다른 글

UGameplayEffectExecutionCalculation  (0) 2025.03.22
AGameplayAbilityWorldReticle  (0) 2025.03.01
Unreal Engine GAS - Gameplay Cue  (0) 2025.02.14
FGameplayAbilityTargetData  (0) 2025.02.14
4.5 게임플레이 이펙트  (0) 2024.02.21

+ Recent posts

티스토리툴바