BearChild · Blog

[UE]GameplayRequestSystem框架

2025-06-24T16:00:00.000Z

GameplayRequestSystem框架

在联网游戏中经常需要有多个玩家之间请求交互的操作，提供一套 GameplayRequestSystem 用于快速自定义出一类新的 Request，自定义可发起请求交互对象、操作回调；

基本框架

从一次 Request 基本的流程出发：

对于某一类 Request，首先 A 需要筛选出关心的 B （其它玩家），判断这些玩家是否可以发起该类请求，如果不可以的话，还可能需要知道无法发起请求的原因；

然后由 A 发起请求，并等待一系列请求交互操作：

SendRequest ：由 A 向 B 发起某个请求，等待请求回复；
AcceptRequest：B / Manager 接受某个请求；
RejectRequest：B / Manager 拒绝某个请求；
CancelRequest：A / B / Manager 取消某个请求；

每个操作需要通知给请求交互的双方 A、B；

对于一个新的 Request，两个玩家的 Client 需要同步到该 Request 信息，获取请求当前状态与一些同步属性等；

由 Player 的 RequestComponent 执行对应 Request 交互、持有 RequestFilter、同步 Request ；
由 Player 的 RequestFilter 进行可以发起请求的目标的注册与更新等；
由RequestMananger 持有实际的 Request，管理其生命周期；

对于 Request 的数据与操作，需要一些自定义参数，通过 CommonParams 实现；

classDiagramdirection TDUGameplayRequestUtils ..> UGameplayRequestManagerUGameplayRequestUtils ..> UGameplayRequestComponent    class UGameplayRequestManager {        CreateRequest()        CancelRequest()        ResponseRequest()        ActiveRequests : TMap~uint64|UGameplayRequestBase*~    }        class UGameplayRequestComponent {        SendRequest()        CancelRequest()        AcceptRequest()        RejectRequest()        GetFilter()        Requests : TArray~UGameplayRequestBase*~        Filters : FGameplaySubSystemCollection~UGameplayRequestFilterBase~    }        UGameplayRequestManager --> UGameplayRequestBase    UGameplayRequestComponent --> UGameplayRequestBase    class UGameplayRequestBase {        GetType()        GetFilterType()        State : EGameplayRequestState        Result : EGameplayRequestResult    }        UGameplayRequestComponent --> UGameplayRequestFilterBase    UGameplayRequestFilterBase --> FGameplayRequestFilterTargetData    class UGameplayRequestFilterBase {    GetType()        IsTargetValid()        RegisterPossibleTarget()        UnregisterPossibleTarget()        FilterTargets()        FilterTargetDatas : TArray~FGameplayRequestFilterTargetData~    }        class FGameplayRequestFilterTargetData {        PlayerUID : uint64        bValid : bool        Params : FCommonVariantParams    }

Request Manager

作为全局的 Manager 管理所有 Request 的生命周期，持有 Request 实例；

在这里控制 Request 增加/移除，将其同步增加/移除到 Sender 与 Target 的 RequestComponent 上，通过 RequestComponent 同步 Request 给对应的 Client ；

根据 UGameplayRequestBase 注册所有的 RequestCDO 用于生成 Request 实例；

特别的，为了 Request 状态能正确同步与通知，当其 Finish 时，并不会直接将其 Remove，而是 KeepAlive，到 KeepAliveDuration 时间结束才将其实例移除；

// RequestManager.h
UCLASS(meta = (BlueprintSpawnableComponent))
class UGameplayRequestManager : public UGameStateComponentBase
{
    GENERATED_BODY()

#pragma region Base
    
protected:
UGameplayRequestManager();
    virtual void OnInitSelf(AGameStateBase* Owner) override;
    virtual void OnUninit() override;

#pragma endregion Base


#pragma region Interact
    
public:
    uint64 CreateRequest(uint32 Type, uint64 SenderUID, uint64 TargetUID, const FCommonVariantParams& Params = {});
    bool CancelRequest(uint64 RequestID, uint64 CancelUID = 0, FCommonVariantParams Params = {});
    bool ResponseRequest(uint64 RequestID, bool bAccept, uint64 ResponseUID = 0, FCommonVariantParams Params = {});
    
#pragma endregion Interact

    
#pragma region Request

public:
    UGameplayRequestBase* GetRequest(uint64 RequestID) const;
    TArray  GetAllRequests() const;

private:
    void InitRequests();
    void UninitRequests();

private:
    void AddRequest(UGameplayRequestBase* Request);
    void RemoveRequest(uint64 RequestID);
    void ClearRequests();

private:
    UPROPERTY()
    TMap  RequestCDOs;

private:
    UPROPERTY()
    TMap ActiveRequests;
    UPROPERTY()
    TMap RequestKeepAliveTimers;

#pragma endregion Request


#pragma region Helper

private:
    void ExecuteFunctionForRequestPlayers(UGameplayRequestBase* Request, TFunction<void(UGameplayRequestComponent*)> Callback);

#pragma endregion Helper

};

// RequestManager.cpp


#pragma region Base

UGameplayRequestManager::UGameplayRequestManager()
{
    SetIsReplicatedByDefault(true);
    PrimaryComponentTick.bCanEverTick = false;
}

void UGameplayRequestManager::OnInitSelf(AGameStateBase* Owner)
{
    Super::OnInitSelf(Owner);

    InitRequests();
}

void UGameplayRequestManager::OnUninit()
{
    Super::OnUninit();

    UninitRequests();
}

#pragma endregion Base


#pragma region Interact

uint64 UGameplayRequestManager::CreateRequest(uint32 Type, uint64 SenderUID, uint64 TargetUID, const FCommonVariantParams& Params)
{
    auto RequestCDO = RequestCDOs.FindRef(Type);
    if (!IsValid(RequestCDO))
    {
        return 0;
    }

    if (SenderUID == TargetUID)
    {
        return 0;
    }
    
    UGameplayRequestBase* NewRequest = NewObject(this, RequestCDO->GetClass());
    if (!IsValid(NewRequest)) return 0;

    uint64 RequestID = NewRequest->Init(SenderUID, TargetUID, Params);
    if (RequestID <= 0) return 0;

    AddRequest( NewRequest );
    
    // RegisterKeepAliveTimer
    float KeepAliveDuration = FMath::Max( 10.0f, NewRequest->GetKeepAliveTime());
    
    FTimerHandle& TimerHandle = RequestKeepAliveTimers.FindOrAdd(RequestID);
    UWorldTimerManager::SetTimer(GetWorld(), TimerHandle,
    [WeakSelfPtr = TWeakObjectPtr(this), RequestID = RequestID]()
    {
        if (!WeakSelfPtr.IsValid()) return;
        WeakSelfPtr->RemoveRequest( RequestID );
    }, KeepAliveDuration, false);

    NewRequest->NotifyCreated();
    
    return RequestID;
}

bool UGameplayRequestManager::CancelRequest(uint64 RequestID, uint64 CancelUID, FCommonVariantParams Params)
{
    auto Request = GetRequest(RequestID);
    if (!IsValid(Request)) return false;

    // 由 Manager / Sender / Target 发起
    if ( !TSet{ 0LL, Request->GetSenderUID(), Request->GetTargetUID() }.Contains( CancelUID ))
    {
        return false;
    }

    if (Request->IsFinished())
    {
        return false;
    }
    
    Params.SetValue( "CancelUID", CancelUID );
    Request->Cancel( Params );

    return true;
}


bool UGameplayRequestManager::ResponseRequest(uint64 RequestID, bool bAccept, uint64 ResponseUID, FCommonVariantParams Params)
{
    auto Request = GetRequest(RequestID);
    if (!IsValid(Request)) return false;

    // 由 Manager / TargetUID 发起
    if ( !TSet{ 0LL, Request->GetTargetUID() }.Contains( ResponseUID ))
    {
        return false;
    }

    if (Request->IsFinished())
    {
        return false;
    }
    
    Params.SetValue( "ResponseUID", ResponseUID );
    
    if (bAccept)
    {
        Request->Accept( Params );
    }
    else
    {
        Request->Reject( Params );
    }

    return true;
}


#pragma endregion Interact



#pragma region Request

UGameplayRequestBase* UGameplayRequestManager::GetRequest(uint64 RequestID) const
{
    return ActiveRequests.FindRef( RequestID );
}

TArray UGameplayRequestManager::GetAllRequests() const
{
    TArray  OutArray;
    for (const auto& [RequestID, Request] : ActiveRequests)
    {
        if (!IsValid(Request)) continue;;
        OutArray.Add( Request );
    }
    return OutArray;
}

// -----

void UGameplayRequestManager::InitRequests()
{
    if (!IsStandaloneOrDS(this)) return;

    TArray RequestClasses;
    GetDerivedClasses(UGameplayRequestBase::StaticClass(), RequestClasses, true);

    for (auto Class : RequestClasses)
    {
        if (!IsValid(Class)) continue;
    if (Class->HasAnyClassFlags(CLASS_Abstract)) continue;
        auto CDO = Class->GetDefaultObject();
        if (!IsValid(CDO)) continue;

        RequestCDOs.Add( CDO->GetType(), CDO );
    }
}

void UGameplayRequestManager::UninitRequests()
{
    if (!IsStandaloneOrDS(this)) return;
    
    ClearRequests();
}

// ----

void UGameplayRequestManager::AddRequest(UGameplayRequestBase* Request)
{
    if (!IsValid(Request)) return;
    ActiveRequests.Add( Request->GetRequestID(), Request );
    
    ExecuteFunctionForRequestPlayers(Request, [Request](UGameplayRequestComponent* Component)
    {
        if (IsValid(Component))
        {
            Component->AddRequest( Request );
        }
    });
}

void UGameplayRequestManager::RemoveRequest(uint64 RequestID)
{
    auto Request = GetRequest(RequestID);

    if (IsValid(Request))
    {
        ExecuteFunctionForRequestPlayers(Request, [RequestID](UGameplayRequestComponent* Component)
        {
            if (IsValid(Component))
            {
                Component->RemoveRequest( RequestID );
            }
        });

        Request->Uninit();
    }
    
    if (auto* TimerHandle = RequestKeepAliveTimers.Find(RequestID))
    {
        UWorldTimerManager::ClearTimer(GetWorld(), *TimerHandle);
        RequestKeepAliveTimers.Remove(RequestID);
    }

    ActiveRequests.Remove(RequestID);
}

void UGameplayRequestManager::ClearRequests()
{
    TArray  RequestIDs;
    ActiveRequests.GetKeys(RequestIDs);

    for (auto RequestID : RequestIDs)
    {
        RemoveRequest( RequestID );
    }
}

#pragma endregion Request


#pragma region Helper

void UGameplayRequestManager::ExecuteFunctionForRequestPlayers(UGameplayRequestBase* Request, TFunction<void(UGameplayRequestComponent*)> Callback)
{
    if (!IsValid(Request)) return;

    if (auto Sender = UGameplayRequestUtils::GetComponentByUID(GetWorld(), Request->GetSenderUID()); IsValid(Sender))
    {
        Callback(Sender);
    }

    if (auto Target = UGameplayRequestUtils::GetComponentByUID(GetWorld(), Request->GetTargetUID()); IsValid(Target))
    {
        Callback(Target);
    }
}

#pragma endregion Helper

RequestComponent

作为 Player 组件进行 Request 操作（请求、同意、拒绝、取消）；

将与 Player 相关的 Request 同步（当 Player 为 Sender / Target 时认为其相关）；

通过 GameplaySubSystem 持有每一种 RequestType 对应的 RequestFilter ，进行 FilterTargetData （可能发起请求的人的相关信息）的更新与同步；

后续每次对 Request 进行 Verify 时，需要通过 Player 上对应 RequestFilter 进行校验是否 IsTargetValid；

同时客户端可以根据 RequestFilter 上的 FilterTargetDatas 信息，提前进行部分操作（比如 Client 知道该类请求无可以请求对象时、自己 / 对方处于不可请求状态时，进行提示）

这里 ReplicateRequest 时，在 Client 创建对应 UObject，需要通过 ReplicateSubobjects_OwnerOnly 来进行同步：

当 Request 作为 Subobject 同步下去时，会在 Client 找到其对应的 Outer（也就是 UGameplayRequestManager，所以 UGameplayRequestManager 需要开启同步）创建在其 ActorChannel 的 CreateSubObjects 中；

在 RequestComponent 中，由一个同步字段 Requests 持有对应指针；

bool UPlayerStateComponentBase::ReplicateSubobjects(UActorChannel* Channel, FOutBunch* Bunch, FReplicationFlags* RepFlags)
{
    bool WroteSomething = Super::ReplicateSubobjects(Channel, Bunch, RepFlags);

if (APlayerStateBase* PS = GetPlayerState(); IsValid(PS) && IsValid(Channel) && IsValid(Channel->Connection))
{
if (Channel->Connection->PlayerController == PS->GetPlayerController())
{
WroteSomething |= ReplicateSubobjects_OwnerOnly(Channel, Bunch, RepFlags);
}
}

return WroteSomething;
}

以下为具体实现：

// RequestComponent.h

UCLASS(meta=(BlueprintSpawnableComponent))
class UGameplayRequestComponent : public UPlayerStateComponentBase, public IGameplaySubSystemCollectionOwnerInterface
{
    GENERATED_BODY()


#pragma region Base

public:
    UGameplayRequestComponent();
    virtual void GetLifetimeReplicatedProps(TArray& OutLifetimeProps) const override;

protected:
    virtual void OnInitSelf() override;
    virtual void OnUninit() override;

#pragma endregion Base

    
    
#pragma region Interact
    
    
public:
    bool SendRequest(uint32 Type, uint64 TargetUID, const FCommonVariantParams& Params = {});
    bool CancelRequest(uint64 RequestID, const FCommonVariantParams& Params = {});
    bool AcceptRequest(uint64 RequestID, const FCommonVariantParams& Params = {});
    bool RejectRequest(uint64 RequestID, const FCommonVariantParams& Params = {});


#pragma region C2S
public:
    UFUNCTION(Reliable, Server)
    void C2S_SendRequest(uint32 Type, uint64 TargetUID, const FCommonVariantParams& Params = {});
    UFUNCTION(Reliable, Server)
    void C2S_AcceptRequest(uint64 RequestID, const FCommonVariantParams& Params = {});
    UFUNCTION(Reliable, Server)
    void C2S_RejectRequest(uint64 RequestID, const FCommonVariantParams& Params = {});
    UFUNCTION(Reliable, Server)
    void C2S_CancelRequest(uint64 RequestID, const FCommonVariantParams& Params = {});
#pragma endregion C2S


#pragma endregion Interact


#pragma region Request

public:
    UFUNCTION()
    UGameplayRequestBase* GetRequest(uint64 RequestID);
    UFUNCTION()
    TArray  GetRequestsByType(uint32 Type);


public:
    void AddRequest(UGameplayRequestBase* Request);
    void RemoveRequest(uint64 RequestID);
    void ClearRequests();
    
private:
    UFUNCTION()
    void OnRep_Requests();
    
private:
UPROPERTY(ReplicatedUsing=OnRep_Requests)
    TArray  Requests;
    
#pragma endregion Request


#pragma region Filter

protected:
    virtual TArray GetFilterClasses() const { return {}; }

public:
    UFUNCTION()
    UGameplayRequestFilterBase* GetFilter(UClass* InClass);

protected:
    virtual bool ReplicateSubobjects_OwnerOnly(UActorChannel* Channel, FOutBunch* Bunch, FReplicationFlags* RepFlags) override;

public:
    DECLARE_GAMEPLAYSUBSYSTEM_ACCESSORS_BY_NAME(Filter, UGameplayRequestFilterBase, Filters);
    virtual TArray GetSubSystemCollectionPtrs() override { return { &Filters }; }
    
private:
    FGameplaySubSystemCollection  Filters;
    
#pragma endregion Filter


#pragma region Debug

public:
    UFUNCTION(Reliable, Server)
    void C2S_DebugSendRequest(uint32 Type, uint64 SenderUID, uint64 TargetUID);
    UFUNCTION(Reliable, Server)
    void C2S_DebugAcceptRequests(uint64 PlayerUID);
    UFUNCTION(Reliable, Server)
    void C2S_DebugRejectRequests(uint64 PlayerUID);
    UFUNCTION(Reliable, Server)
    void C2S_DebugCancelRequests(uint64 PlayerUID);

#pragma endregion Debug

};

// RequestComponent.cpp


#pragma region Base

UGameplayRequestComponent::UGameplayRequestComponent()
{
    SetIsReplicatedByDefault(true);
    PrimaryComponentTick.bCanEverTick = false;
}

void UGameplayRequestComponent::GetLifetimeReplicatedProps(TArray& OutLifetimeProps) const
{
    Super::GetLifetimeReplicatedProps(OutLifetimeProps);

    // --------------------------------------------------------------------------------------------------------------------
    // --- OwnerOnly

    FDoRepLifetimeParams OwnerOnlyRepParams;
    OwnerOnlyRepParams.bIsPushBased = true;
    OwnerOnlyRepParams.Condition = COND_OwnerOnly;

    DOREPLIFETIME_WITH_PARAMS_FAST(UGameplayRequestComponent, Requests, OwnerOnlyRepParams);
}

// -----

void UGameplayRequestComponent::OnInitSelf()
{
    Super::OnInitSelf();

    if (IsStandaloneOrDS(this))
    {
        Filters.Init(this, GetFilterClasses());
    }
}

void UGameplayRequestComponent::OnUninit()
{
    Super::OnUninit();
    
    Filters.Uninit();
    ClearRequests();
}

#pragma endregion Base


#pragma region Interact


bool UGameplayRequestComponent::SendRequest(uint32 Type, uint64 TargetUID, const FCommonVariantParams& Params)
{
    if (!IsStandaloneOrDS(this)) return false;

    auto Manager = UGameplayRequestUtils::GetManager(GetWorld());
    if (!IsValid(Manager)) return false;

    bool bSucceed = Manager->CreateRequest(Type, GetUID(), TargetUID, Params);
    return bSucceed;
}


bool UGameplayRequestComponent::AcceptRequest(uint64 RequestID, const FCommonVariantParams& Params)
{
    if (!IsStandaloneOrDS(this)) return false;
    
    auto Manager = UGameplayRequestUtils::GetManager(GetWorld());
    if (!IsValid(Manager)) return false;
    bool bSucceed = Manager->ResponseRequest(RequestID, true, GetUID(), Params);
    
    return bSucceed;
}

bool UGameplayRequestComponent::RejectRequest(uint64 RequestID, const FCommonVariantParams& Params)
{
    if (!IsStandaloneOrDS(this)) return false;
    
    auto Manager = UGameplayRequestUtils::GetManager(GetWorld());
    if (!IsValid(Manager)) return false;
    bool bSucceed = Manager->ResponseRequest(RequestID, false, GetUID(), Params);
    
    return bSucceed;
}

bool UGameplayRequestComponent::CancelRequest(uint64 RequestID, const FCommonVariantParams& Params)
{
    if (!IsStandaloneOrDS(this)) return false;
    
    auto Manager = UGameplayRequestUtils::GetManager(GetWorld());
    if (!IsValid(Manager)) return false;
    bool bSucceed = Manager->CancelRequest(RequestID, GetUID(), Params);

    return bSucceed;
}


#pragma region C2S

void UGameplayRequestComponent::C2S_SendRequest_Implementation(uint32 Type, uint64 TargetUID, const FCommonVariantParams& Params)
{
    SendRequest(Type, TargetUID, Params);
}


void UGameplayRequestComponent::C2S_AcceptRequest_Implementation(uint64 RequestID, const FCommonVariantParams& Params)
{
    AcceptRequest(RequestID, Params);
}

void UGameplayRequestComponent::C2S_RejectRequest_Implementation(uint64 RequestID, const FCommonVariantParams& Params)
{
    RejectRequest(RequestID, Params);
}

void UGameplayRequestComponent::C2S_CancelRequest_Implementation(uint64 RequestID, const FCommonVariantParams& Params)
{
    CancelRequest(RequestID, Params);
}

#pragma endregion C2S
    

#pragma endregion Interact


#pragma region Request

UGameplayRequestBase* UGameplayRequestComponent::GetRequest(uint64 RequestID)
{
    for (auto Request : Requests)
    {
        if (!IsValid(Request)) continue;
        if (Request->GetRequestID() == RequestID)
        {
            return Request;
        }
    }
    return nullptr;
}

TArray UGameplayRequestComponent::GetRequestsByType(uint32 Type)
{
    TArray  OutArray;
    for (auto Request : Requests)
    {
        if (!IsValid(Request)) continue;
        if (Request->GetType() == Type)
        {
            OutArray.Add( Request );
        }
    }
    return OutArray;
}

void UGameplayRequestComponent::AddRequest(UGameplayRequestBase* Request)
{
    if (!IsValid(Request)) return;
    
    GetRequests_Mutable().AddUnique( Request );
}

void UGameplayRequestComponent::RemoveRequest(uint64 RequestID)
{
    auto Request = GetRequest( RequestID );
    if (!IsValid(Request)) return;
    
    GetRequests_Mutable().Remove( Request );
}

void UGameplayRequestComponent::ClearRequests()
{
    GetRequests_Mutable().Empty();
}

// ----

void UGameplayRequestComponent::OnRep_Requests()
{
    for (auto Request : Requests)
    {
        if (!IsValid(Request)) continue;
        Request->NotifyCreated();
    }
}


#pragma endregion Request


#pragma region Filter

bool UGameplayRequestComponent::ReplicateSubobjects_OwnerOnly(UActorChannel* Channel, FOutBunch* Bunch, FReplicationFlags* RepFlags)
{
    bool WroteSomething = false;

    WroteSomething |= Super::ReplicateSubobjects_OwnerOnly(Channel, Bunch, RepFlags);
    WroteSomething |= Filters.ReplicateSubSystems( Channel, Bunch, RepFlags );
    
    if (IsValid(Channel) && RepFlags->bNetInitial == false)
    {
        for (auto Request : Requests)
        {
            if (!IsValid(Request)) continue;
            WroteSomething |= Channel->ReplicateSubobject(Request, *Bunch, *RepFlags);
        }
    }

    return WroteSomething;
}

UGameplayRequestFilterBase* UGameplayRequestComponent::GetFilter(UClass* InClass)
{
    for (auto Filter : GetFilters())
    {
        if (IsValid(Filter) && Filter->GetClass() == InClass)
        {
            return Filter;
        }
    }
    return nullptr;
}

#pragma endregion Filter


#pragma region Debug

void UGameplayRequestComponent::C2S_DebugSendRequest_Implementation(uint32 Type, uint64 SenderUID, uint64 TargetUID)
{
#if UE_BUILD_SHIPPING
    return;
#endif

    SenderUID = SenderUID > 0 ? SenderUID : GetUID();
    TargetUID = TargetUID > 0 ? TargetUID : GetUID();
    
    auto Component = UGameplayRequestUtils::GetComponentByUID(GetWorld(), SenderUID);
    if (!IsValid(Component)) return;
    
    Component->SendRequest( Type, TargetUID );
}


void UGameplayRequestComponent::C2S_DebugAcceptRequests_Implementation(uint64 PlayerUID)
{
#if UE_BUILD_SHIPPING
    return;
#endif
    PlayerUID = PlayerUID > 0 ? PlayerUID : GetUID();
    auto Component = UGameplayRequestUtils::GetComponentByUID(GetWorld(), PlayerUID);
    if (!IsValid(Component)) return;

    TArray  PlayerRequests = Component->GetRequests();
    
    for (auto Request : PlayerRequests)
    {
        if (!IsValid(Request)) continue;
        Component->AcceptRequest(Request->GetRequestID());
    }
}


void UGameplayRequestComponent::C2S_DebugRejectRequests_Implementation(uint64 PlayerUID)
{
#if UE_BUILD_SHIPPING
    return;
#endif
    
    PlayerUID = PlayerUID > 0 ? PlayerUID : GetUID();
    auto Component = UGameplayRequestUtils::GetComponentByUID(GetWorld(), PlayerUID);
    if (!IsValid(Component)) return;

    TArray  PlayerRequests = Component->GetRequests();
    
    for (auto Request : PlayerRequests)
    {
        if (!IsValid(Request)) continue;
        Component->RejectRequest(Request->GetRequestID());
    }
}

void UGameplayRequestComponent::C2S_DebugCancelRequests_Implementation(uint64 PlayerUID)
{
#if UE_BUILD_SHIPPING
    return;
#endif

    PlayerUID = PlayerUID > 0 ? PlayerUID : GetUID();
    auto Component = UGameplayRequestUtils::GetComponentByUID(GetWorld(), PlayerUID);
    if (!IsValid(Component)) return;

    TArray  PlayerRequests = Component->GetRequests();
    
    for (auto Request : PlayerRequests)
    {
        if (!IsValid(Request)) continue;
        Component->CancelRequest(Request->GetRequestID());
    }
}


#pragma endregion Debug

RequestFilter

对于每一类 Request，每个玩家身上会有一个对应的 RequestFilter，用来更新可能可以发起请求的目标；

通过 Register / Unregister PossibleTarget，然后更新对应的 FilterTargetData 并同步给 Client；

// FilterTargetData 

USTRUCT()
struct FGameplayRequestFilterTargetData
{
GENERATED_BODY()

FGameplayRequestFilterTargetData() = default;
FGameplayRequestFilterTargetData(uint64 PlayerUID) : PlayerUID(PlayerUID) {}

public:
bool operator==(const FGameplayRequestFilterTargetData& Other) const
{
if (PlayerUID != Other.PlayerUID) return false;
return true;
}
bool operator !=(const FGameplayRequestFilterTargetData& Other) const { return !(*this == Other); }

public:
FString ToString() const;


public:
UPROPERTY()
uint64 PlayerUID;

UPROPERTY()
bool bValid = false;

UPROPERTY()
FCommonVariantParams Params = {};
};

// RequestFilterBase.h

UCLASS(Abstract)
class UGameplayRequestFilterBase : public UGameplaySubSystemBase
{
GENERATED_BODY()

#pragma region Config

public:
virtual uint32 GetType() const PURE_VIRTUAL(UGameplayRequestFilterBase::GetType, return 0;);

#pragma endregion Config


#pragma region Base

protected:
virtual void OnInit() override;
virtual void OnUninit() override;
virtual FString ToString() const;

private:
TWeakObjectPtr <class UGameplayRequestComponent> Owner;

#pragma endregion Base


#pragma region Replicate

protected:
virtual void GetLifetimeReplicatedProps(TArray & OutLifetimeProps) const override;
protected:
virtual bool IsSupportedForNetworking() const override { return true; }

#pragma endregion Replicate


#pragma region FilterTarget

public:
UFUNCTION()
virtual bool IsTargetValid(uint64 TargetUID) const;
UFUNCTION()
FGameplayRequestFilterTargetData GetFilterTargetData(uint64 PlayerUID) const;

protected:
void FilterTargets(); // 主动调用

protected:
void ClearPossibleTargets();
void RegisterPossibleTarget(uint64 TargetUID);
void UnregisterPossibleTarget(uint64 TargetUID);

protected:
virtual bool CheckSelfConditionValid() { return true; } 
virtual bool CheckTargetConditionValid(uint64 TargetUID) { return true; }

private:
UFUNCTION()
void OnRep_FilterTargetDatas();

private:
UPROPERTY(Replicated, ReplicatedUsing = OnRep_FilterTargetDatas)
TArray  FilterTargetDatas;

#pragma endregion FilterTarget


#pragma region Helper

protected:
uint64 GetUID() const;
APlayerStateBase* GetPlayerState() const;
float GetTimeNow() const;

#pragma endregion Helper

};

// RequestFilterBase.cpp

#pragma region Base

void UGameplayRequestFilterBase::OnInit()
{
Super::OnInit();
Owner = Cast(GetOuter());
}

void UGameplayRequestFilterBase::OnUninit()
{
Super::OnUninit();
}

FString UGameplayRequestFilterBase::ToString() const
{
return FString::Printf(TEXT("[%llu|%s]"), GetUID(), *GetName());
}


#pragma endregion Base


#pragma region Replicate

void UGameplayRequestFilterBase::GetLifetimeReplicatedProps(TArray& OutLifetimeProps) const
{
Super::GetLifetimeReplicatedProps(OutLifetimeProps);
// --------------------------------------------------------------------------------------------------------------------
// --- OwnerOnly

FDoRepLifetimeParams OwnerOnlyRepParams;
OwnerOnlyRepParams.bIsPushBased = true;
OwnerOnlyRepParams.Condition = COND_OwnerOnly;

DOREPLIFETIME_WITH_PARAMS_FAST(UGameplayRequestFilterBase, FilterTargetDatas, OwnerOnlyRepParams);
}

#pragma endregion Replicate


#pragma region FilterTarget

bool UGameplayRequestFilterBase::IsTargetValid(uint64 TargetUID) const
{
const auto& Data = GetFilterTargetData(TargetUID);
return Data.bValid;
}

FGameplayRequestFilterTargetData UGameplayRequestFilterBase::GetFilterTargetData(uint64 PlayerUID) const
{
for (const auto& Data : FilterTargetDatas)
{
if (Data.PlayerUID == PlayerUID)
{
return Data;
}
}
return {};
}

void UGameplayRequestFilterBase::ClearPossibleTargets()
{
if (!IsStandaloneOrDS(this)) return;

GetFilterTargetDatas_Mutable().Empty();
}

void UGameplayRequestFilterBase::RegisterPossibleTarget(uint64 TargetUID)
{
if (!IsStandaloneOrDS(this)) return;
if (FilterTargetDatas.Contains( TargetUID )) return;
FilterTargetDatas.Add( { TargetUID } );

}

void UGameplayRequestFilterBase::UnregisterPossibleTarget(uint64 TargetUID)
{
if (!IsStandaloneOrDS(this)) return;
if (!FilterTargetDatas.Contains( TargetUID )) return;
FilterTargetDatas.Remove( TargetUID );

}

void UGameplayRequestFilterBase::FilterTargets()
{
bool bSelfConditionValid = CheckSelfConditionValid();
for (auto& Data : FilterTargetDatas)
{
bool bTargetConditionValid = CheckTargetConditionValid(Data.PlayerUID);
Data.bValid = (bSelfConditionValid && bTargetConditionValid);
// TODO : More Params
Data.Params.Clear();
Data.Params.SetValue( "bSelfConditionValid", bSelfConditionValid );
Data.Params.SetValue( "bTargetConditionValid", bTargetConditionValid );
}

MARK_PROPERTY_DIRTY_FROM_NAME(UGameplayRequestFilterBase, FilterTargetDatas, this);
OnRep_FilterTargetDatas();
}


void UGameplayRequestFilterBase::OnRep_FilterTargetDatas()
{
}


#pragma endregion FilterTarget



#pragma region Helper

uint64 UGameplayRequestFilterBase::GetUID() const
{
if (!Owner.IsValid()) return 0;
return Owner->GetUID();
}

APlayerStateBase* UGameplayRequestFilterBase::GetPlayerState() const
{
if (!Owner.IsValid()) return nullptr;
return Owner->GetPlayerState();
}

float UGameplayRequestFilterBase::GetTimeNow() const
{
return UFunctionLibrary::GetGameServerTimeWithSecond(GetWorld());
}

#pragma endregion Helper

Request

一个 Request 由 RequestManager 持有实际的 Request；

通过 Sender 、Target 的 RequestComponent 将其同步到对应 Client；

对于 Request，定义基本属性、状态以及提供生命周期相关回调；

// RequestBase.h

UCLASS(Abstract)
class UGameplayRequestBase : public UObject
{
    GENERATED_BODY()

#pragma region Config

public:
UFUNCTION()
virtual uint32 GetType() const PURE_VIRTUAL(UGameplayRequestBase::GetType, return 0;);
    virtual UClass* GetFilterType() const PURE_VIRTUAL(UGameplayRequestBase::GetFilterType, return UGameplayRequestFilterBase::StaticClass(););

#pragma endregion Config

    
#pragma region Base

public:
virtual FString ToString() const;
    uint64 Init(uint64 SenderUID, uint64 TargetUID, const FCommonVariantParams& InParams);
void Uninit();

private:
    inline static uint64 REQUEST_ID_COUNTER = 0;
    
#pragma endregion Base


#pragma region Replicate

protected:
virtual void GetLifetimeReplicatedProps(TArray& OutLifetimeProps) const override;

private:
virtual bool IsSupportedForNetworking() const override { return true; }

#pragma endregion Replicate


#pragma region Validate

public:
    bool ValidateRequest();

#pragma endregion Validata


#pragma region Timeout

private:
void RegisterTimeoutTimer();

private:
FTimerHandle TimeoutTimer;

#pragma endregion Timeout


#pragma region Interact

private:
friend class UGameplayRequestManager;

private:
void Accept(const FCommonVariantParams& Params = {});
void Reject(const FCommonVariantParams& Params = {});
void Cancel(const FCommonVariantParams& Params = {});

void Timeout();
void Interrupt();

protected:
virtual void OnAccepted() {};
virtual void OnRejected() {};
virtual void OnCanceled() {};

#pragma endregion Interact


#pragma region Create

public:
void NotifyCreated();

private:
bool bHasNotifyCreated = false;

#pragma endregion Create


#pragma region Complete

private:
void NotifyCompleted(EGameplayRequestResult InResult);

protected:
virtual void OnCompleted(EGameplayRequestResult InResult) {}

private:
UFUNCTION()
void OnRep_Result();

private:
UPROPERTY(Replicated, ReplicatedUsing=OnRep_Result)
EGameplayRequestResult Result = EGameplayRequestResult::None;

#pragma endregion Complete


#pragma region State

private:
void UpdateState(EGameplayRequestState InState);

protected:
virtual void OnStateChanged(EGameplayRequestState) {}

private:
UFUNCTION()
virtual void OnRep_State();

private:
UPROPERTY(Replicated, ReplicatedUsing=OnRep_State)
EGameplayRequestState State = EGameplayRequestState::Invalid;

#pragma endregion State



#pragma region KeepAlive

public:
float GetKeepAliveTime() const { return KeepAliveTime; }

private:
// 最大保留时间 (完成后也可能保留)
float KeepAliveTime = 60.0f;

#pragma endregion KeepAlive


#pragma region Params

public:
void CombineParams(const FCommonVariantParams& Params);

private:
UPROPERTY(Replicated)
FCommonVariantParams RequestParams;

#pragma endregion Params


#pragma region Data
private:
UFUNCTION()
void OnRep_RequestID();

private:
UPROPERTY(Replicated)
    uint64 SenderUID = 0;
UPROPERTY(Replicated)
    uint64 TargetUID = 0;

UPROPERTY(Replicated)
    float CreateTime = 0.0f;
UPROPERTY(Replicated)
    float TimeoutDuration = 30.0f;

UPROPERTY(Replicated, ReplicatedUsing=OnRep_RequestID)
uint64 RequestID = 0;

#pragma endregion Data

    

#pragma region Helper

public:
bool IsFinished() const;

protected:
float GetTimeNow() const;
float GetRunningTime() const;
    
#pragma endregion Helper
    
};

// RequestBase.cpp


#pragma region Base

FString UGameplayRequestBase::ToString() const
{
return FString::Printf(TEXT("{[ID=%llu][Type=%d][UID=%llu->%llu][Params=%s][%s][Time=%.f+%.f(s)][%.f(s), %.f(s)]}"),
RequestID,
GetType(), SenderUID, TargetUID, *RequestParams.ToString(),
*UStringUtils::ToString(State),
CreateTime, GetRunningTime(),
TimeoutDuration, KeepAliveTime
);
}

uint64 UGameplayRequestBase::Init(uint64 InSenderUID, uint64 InTargetUID, const FCommonVariantParams& InParams)
{
if (!IsStandaloneOrDS(this)) return 0;

SetRequestID( ++REQUEST_ID_COUNTER );

SetSenderUID( InSenderUID );
SetTargetUID( InTargetUID );
SetRequestParams( InParams );
SetState( EGameplayRequestState::Waiting );

SetCreateTime( GetTimeNow() );
SetTimeoutDuration( 30.0f );

KeepAliveTime = FMath::Max(KeepAliveTime, TimeoutDuration);

bool bValid = ValidateRequest();


if (bValid == false)
{
return 0;
}

RegisterTimeoutTimer();

return RequestID;
}

void UGameplayRequestBase::Uninit()
{

UWorldTimerManager::ClearTimer(GetWorld(), TimeoutTimer);
}

#pragma endregion Base


#pragma region Replicate


void UGameplayRequestBase::GetLifetimeReplicatedProps(TArray& OutLifetimeProps) const
{
Super::GetLifetimeReplicatedProps(OutLifetimeProps);

FDoRepLifetimeParams SharedParams;
SharedParams.bIsPushBased = true;

DOREPLIFETIME_WITH_PARAMS_FAST(UGameplayRequestBase, RequestID, SharedParams);

DOREPLIFETIME_WITH_PARAMS_FAST(UGameplayRequestBase, SenderUID, SharedParams);
DOREPLIFETIME_WITH_PARAMS_FAST(UGameplayRequestBase, TargetUID, SharedParams);
DOREPLIFETIME_WITH_PARAMS_FAST(UGameplayRequestBase, RequestParams, SharedParams);
DOREPLIFETIME_WITH_PARAMS_FAST(UGameplayRequestBase, CreateTime, SharedParams);
DOREPLIFETIME_WITH_PARAMS_FAST(UGameplayRequestBase, TimeoutDuration, SharedParams);
DOREPLIFETIME_WITH_PARAMS_FAST(UGameplayRequestBase, RequestID, SharedParams);

DOREPLIFETIME_WITH_PARAMS_FAST(UGameplayRequestBase, State, SharedParams);
DOREPLIFETIME_WITH_PARAMS_FAST(UGameplayRequestBase, Result, SharedParams);
}

#pragma endregion Replicate


#pragma region Validate

bool UGameplayRequestBase::ValidateRequest()
{
if (GetType() <= 0) return false;

// 如果没有需要的 Filter 则默认为 true
if (auto Filter = UGameplayRequestUtils::GetPlayerFilterByUID(GetWorld(), SenderUID, GetFilterType()); IsValid(Filter))
{
if (!Filter->IsTargetValid(TargetUID))
return false;
}
    
// TODO : 重复 Request

return true;
}

#pragma endregion Validate


#pragma region Timeout

void UGameplayRequestBase::RegisterTimeoutTimer()
{
if (TimeoutDuration <= 0.0f) return;

UWorldTimerManager::SetTimer(GetWorld(), TimeoutTimer,
[WeakSelfPtr = TWeakObjectPtr(this)]()
{
if (!WeakSelfPtr.IsValid()) return;
WeakSelfPtr->Timeout();
}, TimeoutDuration, false);
}

#pragma endregion Timeout


#pragma region Interact

void UGameplayRequestBase::Accept(const FCommonVariantParams& Params)
{
if (IsFinished()) return;


CombineParams(Params);
UpdateState(EGameplayRequestState::Accepted);
OnAccepted();
NotifyCompleted(EGameplayRequestResult::Success);
}

void UGameplayRequestBase::Reject(const FCommonVariantParams& Params)
{
if (IsFinished()) return;

CombineParams(Params);
UpdateState(EGameplayRequestState::Rejected);
OnRejected();
NotifyCompleted(EGameplayRequestResult::Failed);
}

void UGameplayRequestBase::Cancel(const FCommonVariantParams& Params)
{
if (IsFinished()) return;

CombineParams(Params);
UpdateState(EGameplayRequestState::Canceled);
OnCanceled();
NotifyCompleted(EGameplayRequestResult::Canceled);
}

void UGameplayRequestBase::Timeout()
{
if (IsFinished()) return;
Cancel( { "CancelReason", EGameplayRequestCancelReason::Timeout } );
}

void UGameplayRequestBase::Interrupt()
{
if (IsFinished()) return;
Cancel( {"CancelReason", EGameplayRequestCancelReason::Interrupt} );
}


#pragma endregion Interact



#pragma region Create

void UGameplayRequestBase::NotifyCreated()
{
if (bHasNotifyCreated) return;
bHasNotifyCreated = true;
}


#pragma endregion Create


#pragma region Complete

void UGameplayRequestBase::NotifyCompleted(EGameplayRequestResult InResult)
{

SetResult(InResult);
OnCompleted(InResult);
OnRep_Result();
}

void UGameplayRequestBase::OnRep_Result()
{
}


#pragma endregion Complete


#pragma region State

void UGameplayRequestBase::UpdateState(EGameplayRequestState InState)
{
if (InState == State) return;

SetState(InState);
OnStateChanged(InState);
OnRep_State();
}

void UGameplayRequestBase::OnRep_State()
{
}


#pragma endregion State


#pragma region Params

void UGameplayRequestBase::CombineParams(const FCommonVariantParams& Params)
{
if (Params.IsEmpty()) return;
SetRequestParams( RequestParams + Params );

}

#pragma endregion Params


#pragma region Data

void UGameplayRequestBase::OnRep_RequestID()
{

}

#pragma endregion Data


#pragma region Helper

bool UGameplayRequestBase::IsFinished() const
{
return State != EGameplayRequestState::Waiting && State != EGameplayRequestState::Invalid;
}

float UGameplayRequestBase::GetTimeNow() const
{
return UFunctionLibrary::GetGameServerTimeWithSecond(GetWorld());
}

float UGameplayRequestBase::GetRunningTime() const
{
float TimeNow = GetTimeNow();
return TimeNow - CreateTime;
}


#pragma endregion Helper

GameplayRequestUtils

通过该 Utils 提供一些方法给外部使用；

// GameplayRequestUtils.h

UCLASS()
class UGameplayRequestUtils : public UBlueprintFunctionLibrary
{
GENERATED_BODY()

#pragma region Base

public:

UFUNCTION()
static UGameplayRequestManager* GetManager(UWorld* InWorld);
UFUNCTION()
static UGameplayRequestComponent* GetComponent(APlayerStateBase* PS);
UFUNCTION()
static UGameplayRequestComponent* GetComponentByUID(UWorld* InWorld, uint64 UID);


#pragma endregion Base


#pragma region Filter

public:
UFUNCTION()
static UGameplayRequestFilterBase* GetPlayerFilter(APlayerStateBase* PS, UClass* FilterType);

UFUNCTION()
static UGameplayRequestFilterBase* GetPlayerFilterByUID(UWorld* InWorld, uint64 UID, UClass* FilterType);

#pragma endregion Filter


#pragma region Request

public:
UFUNCTION()
static UGameplayRequestBase* GetRequest(UWorld* InWorld, uint64 RequestID);

UFUNCTION()
static UGameplayRequestBase* GetPlayerRequest(APlayerStateBase* PS, uint64 RequestID);

UFUNCTION()
static TArray GetPlayerRequests(APlayerStateBase* PS);

UFUNCTION()
static TArray GetPlayerRequestsByType(APlayerStateBase* PS, uint32 Type);

#pragma endregion Request

};

// GameplayRequestUtils.cpp


#pragma region Base

UGameplayRequestManager* UGameplayRequestUtils::GetManager(UWorld* InWorld)
{
if (InWorld == nullptr) return nullptr;
return UFunctionLibrary::GetGameStateComponentFromWorld(InWorld);
}

UGameplayRequestComponent* UGameplayRequestUtils::GetComponent(APlayerStateBase* PS)
{
if (!IsValid(PS)) return nullptr;
return UFunctionLibrary::GetPlayerStateComponent(PS);
}

UGameplayRequestComponent* UGameplayRequestUtils::GetComponentByUID(UWorld* InWorld, uint64 UID)
{
if (!IsValid(InWorld)) return nullptr;
auto PS = UFunctionLibrary::GetPlayerStateByUID(InWorld, UID);
if (!IsValid(PS)) return nullptr;
return GetComponent(PS);
}


#pragma endregion Base


#pragma region Filter

UGameplayRequestFilterBase* UGameplayRequestUtils::GetPlayerFilter(APlayerStateBase* PS, UClass* FilterType)
{
auto Component = GetComponent(PS);
if (!IsValid(Component)) return nullptr;
return Component->GetFilter(FilterType);
}

UGameplayRequestFilterBase* UGameplayRequestUtils::GetPlayerFilterByUID(UWorld* InWorld, uint64 UID, UClass* FilterType)
{
auto Component = GetComponentByUID(InWorld, UID);
if (!IsValid(Component)) return nullptr;
return Component->GetFilter(FilterType);
}

#pragma endregion Filter


#pragma region Request

UGameplayRequestBase* UGameplayRequestUtils::GetRequest(UWorld* InWorld, uint64 RequestID)
{
if (!IsValid(InWorld)) return nullptr;

if (IsStandaloneOrDS(InWorld))
{
auto Manager = GetManager(InWorld);
if (IsValid(Manager))
{
return Manager->GetRequest( RequestID );
}
}
else if (IsClient(InWorld))
{
APlayerStateBase* HostPS = UFunctionLibrary::GetPlayerStateByUID(InWorld, UFunctionLibrary::GetMainPlayerUID(InWorld));
if (IsValid(HostPS))
{
return GetPlayerRequest( HostPS, RequestID );
}
}

return nullptr;
}


UGameplayRequestBase* UGameplayRequestUtils::GetPlayerRequest(APlayerStateBase* PS, uint64 RequestID)
{
auto Component = GetComponent(PS);
if (!IsValid(Component)) return nullptr;
return Component->GetRequest( RequestID );
}

TArray UGameplayRequestUtils::GetPlayerRequests(APlayerStateBase* PS)
{
auto Component = GetComponent(PS);
if (!IsValid(Component)) return {};
return Component->GetRequests();
}

TArray UGameplayRequestUtils::GetPlayerRequestsByType(APlayerStateBase* PS, uint32 Type)
{
auto Requests = GetPlayerRequests(PS);
TArray  OutRequests;
for (auto Request : Requests)
{
if (!IsValid(Request)) continue;
if (Request->GetType() == Type)
{
OutRequests.Add( Request );
}
}
return OutRequests;
}


#pragma endregion Request

Sample

创建一个请求时，只需要创建该类型对应的 RequestFilter、Request 即可；

// Request_Test.h

UCLASS()
class UGameplayRequest_Test : public UGameplayRequestBase
{
    GENERATED_BODY()

#pragma region Config

public:
virtual uint32 GetType() const override { return 1001; }
    virtual UClass* GetFilterType() const override { return UGameplayRequestFilter_Test::StaticClass(); }

#pragma endregion Config


private:
virtual void OnAccepted() override {};
virtual void OnRejected() override {};
virtual void OnCanceled() override {};
};

// RequestFilter_Test.h

UCLASS()
class UGameplayRequestFilter_Test : public UGameplayRequestFilterBase
{
GENERATED_BODY()

#pragma region Config

public:
virtual uint32 GetType() const override { return 1001; }

#pragma endregion Config

public:
virtual bool IsTargetValid(uint64 TargetUID) const override { return true; };
};

[UE]GameplaySubSystem实现

2025-03-14T16:00:00.000Z

GameplaySubSystem实现

维护 SubSystem 的解决方案；

在维护各个业务时，经常需要将 Manager，下面再拆出若干个子系统，需要一种快捷的方法快速扩展出一套 SubSystem 系统；

基本结构：由 Manager 持有 SubSystemCollection ，Collection 中持有若干个继承于 SubSystemBase 的自定义 SubSystem；
同步方案：当 Manager IsReplicated 且 Collection 中的 SubSystem 需要同步数据时，提供 SubSystem 的同步策略，保证双端统一；

基本结构

classDiagramdirection LRIGameplaySubSystemCollectionOwnerInterface<|--Managerclass IGameplaySubSystemCollectionOwnerInterface {GetSubSystemCollectionPtrs()GetSubSystemCollectionPtr(UClass* InClass)}Manager..*FGameplaySubSystemCollectionclass Manager {SubSystemCollections : FGameplaySubSystemCollection~UGameplaySubSystem~}class FGameplaySubSystemCollectionBase {        Outer : TWeakObjectPtr~UObject~        SubSystemMap : TMap~UClass*,TStrongObjectPtr[UGameplaySubSystemBase]~        BaseType : UClass*                Init()        SetOuter()        Uninit()        Tick()                        AddSubSystem()        RemoveSubSystem()        GetSubSystem()        ReplicateSubSystems()    }    FGameplaySubSystemCollectionBase<|--FGameplaySubSystemCollection    FGameplaySubSystemCollectionBase..>UGameplaySubSystemBaseclass FGameplaySubSystemCollection {FGameplaySubSystemCollection()}       IInterface_ActorSubobject<|--UGameplaySubSystemBase    class IInterface_ActorSubobject {    + OnCreatedFromReplication()    + OnDestroyedFromReplication()    }        class UGameplaySubSystemBase {    LastTickTime : float        + Init()    + Uninit()        # OnInit()    # OnUnInit()        + Tick()    # OnTick(float DeltaTime)    # GetTickInternal()    # GetTimeNow()        + IsSupportedForNetworking()    + OnCreatedFromReplication()    + OnDestroyedFromReplication()    }        UGameplaySubSystemBase<|--UGameplaySubSystem    class UGameplaySubSystem {    # OnInit()    # OnUnInit()    # OnTick(float DeltaTime)        # GetTickInternal()    }

Manager

由 Manager 持有对应类型的 SubSystemCollection，主动调用 Init、Uninit、Tick 。

同时，为了后续的同步， Manager 需要重载 IGameplaySubSystemCollectionOwnerInterface 的 GetSubSystemCollectionPtrs，用于找到对应的 Collection（如果不需要同步，也可以不实现）；

一个 Manager 可能同时持有多个 SubSystemCollection，所以这里需要提供 GetCollections；

提供一个宏，方便地进行注册：

#define DECLARE_GAMEPLAYSUBSYSTEM_ACCESSORS(BaseClass, SubSystemCollections) \
template \
typename TEnableIf::Value, T*>::Type \
GetSubSystem() \
{ \
return SubSystemCollections.GetSubSystem(); \
} \
template \
typename TEnableIf::Value, TArray>::Type \
GetSubSystems() \
{ \
return SubSystemCollections.GetSubSystems(); \
}

// IGameplaySubSystemCollectionOwnerInterface.h

UINTERFACE(BlueprintType, Blueprintable)
class UGameplaySubSystemCollectionOwnerInterface : public UInterface
{
GENERATED_BODY()
};

class IGameplaySubSystemCollectionOwnerInterface
{
GENERATED_BODY()

public:
virtual TArray GetSubSystemCollectionPtrs() = 0;

public:
FGameplaySubSystemCollectionBase* GetSubSystemCollectionPtr(UClass* InClass);
};

// IGameplaySubSystemCollectionOwnerInterface.cpp

FGameplaySubSystemCollectionBase* IGameplaySubSystemCollectionOwnerInterface::GetSubSystemCollectionPtr(UClass* InClass)
{
auto CollectionPtrs = GetSubSystemCollectionPtrs();

for (auto CollectionPtr : CollectionPtrs)
{
if (CollectionPtr != nullptr && InClass->IsChildOf(CollectionPtr->GetBaseType()))
{
return CollectionPtr;
}
}

return nullptr;
}

// Manager.h

public:
DECLARE_GAMEPLAYSUBSYSTEM_ACCESSORS(USubSystemBase_A, SubSystemCollection_A);
DECLARE_GAMEPLAYSUBSYSTEM_ACCESSORS(USubSystemBase_B, SubSystemCollection_B);
virtual TArray GetSubSystemCollectionPtrs() override { return { &SubSystemCollection_A, &SubSystemCollection_B }; }

private:
FGameplaySubSystemCollection  SubSystemCollection_A;
FGameplaySubSystemCollection  SubSystemCollection_B;

// Manager.cpp
// 在合适的时机：
SubSystemCollections.Init()
SubSystemCollections.Uninit()
SubSystemCollections.Tick()

SubSystemCollection

SubSystemCollection 负责收集与管理所有的 SubSystem。

在 SubSystemCollectionBase 中，提供一个 BaseClass，这个 BaseClass 由对应的 SubSystemCollection 在初始化的时候传入：

template<typename TBaseType>
struct FGameplaySubSystemCollection : FGameplaySubSystemCollectionBase
{
static_assert(TIsDerivedFrom::Value, "TBaseType must inherit from UGameplaySubSystemBase");

    FGameplaySubSystemCollection() : FGameplaySubSystemCollectionBase(TBaseType::StaticClass())
{
}
}


FGameplaySubSystemCollectionBase::FGameplaySubSystemCollectionBase(UClass* InBaseType) : BaseType(InBaseType)
{
check(BaseType);
}

提供两种 Init 方法：

根据 BaseClass，找到所有继承于该类的 Class 创建 SubSystem 。
指定 SubSystemClasses 进行创建 SubSystem；

void FGameplaySubSystemCollectionBase::Init(UObject* InOuter, bool bCreatedDerivedClasses)
{
if (!SetOuter(InOuter)) return;

if (bCreatedDerivedClasses)
{
TArray SubSystemClasses;
GetDerivedClasses(BaseType, SubSystemClasses, true);
AddSubSystemByClasses( SubSystemClasses );
}
}

void FGameplaySubSystemCollectionBase::Init(UObject* InOuter, const TArray& InSubSystemClasses)
{
if (!SetOuter(InOuter)) return;
AddSubSystemByClasses(InSubSystemClasses);
}

bool FGameplaySubSystemCollectionBase::SetOuter(UObject* InOuter)
{
if (Outer.IsValid()) return false; // already initialized
if (!IsValid(InOuter)) return false; // invalid Outer

Outer = InOuter;
return true;
}

用 TMap < UClass*, TStrongObjectPtr > SubSystemMap 将所有的 SubSystem 实例保存下来；

void FGameplaySubSystemCollectionBase::AddSubSystem(UGameplaySubSystemBase* SubSystem)
{
if (!IsValid(SubSystem)) return;
SubSystemMap.Add( SubSystem->GetClass(), TStrongObjectPtr(SubSystem)  );
SubSystem->Init();
}

由于期望 FGameplaySubSystemCollection 可以在编译期决定类型，使用了 template ，这也导致无法走 UHT 的反射挂上UPROPERTY 标记来保证其生命周期。

所以这里需要用其它方式保证 Collection 内部的 SubSystem 的生命周期，让其不会被 GC ：

用 TStrongObjectPtr ，缺点是 TStrongObjectPtr 的 Reset 校验其必须 InGameThread，需要注意在访问 SubSystem 时使用引用，不触发指针的拷贝；

explicit FInternalReferenceCollector(const volatile UObject* InObject) : Object(InObject)
{
    check(IsInGameThread());
}

virtual ~FInternalReferenceCollector()
{
    check(IsInGameThread() || IsInGarbageCollectorThread());
}

使用 AddToRoot / RemoveFromRoot ，并用 TWeakObjectPtr 记录；

完整实现：

// FGameplaySubSystemCollectionBase.h

struct FGameplaySubSystemCollectionBase
{
public:
FGameplaySubSystemCollectionBase(UClass* InBaseType);
    UClass* GetBaseType() const;
    
public:
void Init(UObject* InOuter, bool bCreatedDerivedClasses = true);
void Init(UObject* InOuter, const TArray& InSubSystemClasses);
bool SetOuter(UObject* InOuter);

void Uninit();
void Tick();


public:
TArray AddSubSystemByClasses(const TArray& SubSystemClasses);
UGameplaySubSystemBase* AddSubSystemByClass(UClass* SubSystemClass);
void AddSubSystem(UGameplaySubSystemBase* SubSystem);

void RemoveSubSystemByClass(UClass* SubSystemClass);
void RemoveSubSystem(UGameplaySubSystemBase* SubSystem);

protected:
UGameplaySubSystemBase* GetSubSystemInternal(UClass* SubSystemClass) const;
TArray GetSubSystemsInternal() const;

private:
TWeakObjectPtr  Outer = nullptr;
TMap < UClass*, TWeakObjectPtr > SubSystemMap;
UClass* BaseType = nullptr;
};

// FGameplaySubSystemCollectionBase.cpp

FGameplaySubSystemCollectionBase::FGameplaySubSystemCollectionBase(UClass* InBaseType)
: BaseType(InBaseType)
{
check(BaseType);
}

FGameplaySubSystemCollectionBase::GetBaseType() const
{
    return BaseType;
}

void FGameplaySubSystemCollectionBase::Init(UObject* InOuter, bool bCreatedDerivedClasses)
{
if (!SetOuter(InOuter)) return;

if (bCreatedDerivedClasses)
{
TArray SubSystemClasses;
GetDerivedClasses(BaseType, SubSystemClasses, true);
AddSubSystemByClasses( SubSystemClasses );
}
}

void FGameplaySubSystemCollectionBase::Init(UObject* InOuter, const TArray& InSubSystemClasses)
{
if (!SetOuter(InOuter)) return;
AddSubSystemByClasses(InSubSystemClasses);
}

bool FGameplaySubSystemCollectionBase::SetOuter(UObject* InOuter)
{
if (Outer.IsValid()) return false; // already initialized
if (!IsValid(InOuter)) return false; // invalid Outer

Outer = InOuter;
return true;
}


void FGameplaySubSystemCollectionBase::Tick()
{
for (auto& Pair : SubSystemMap)
{
auto& SubSystem = Pair.Value;
if (SubSystem.IsValid())
{
SubSystem->Tick();
}
}
}

void FGameplaySubSystemCollectionBase::Uninit()
{
TArray  SubSystemClasses;
SubSystemMap.GetKeys(SubSystemClasses);
for (auto SubSystemClass : SubSystemClasses)
{
RemoveSubSystemByClass(SubSystemClass);
}
}

// -----

TArray FGameplaySubSystemCollectionBase::AddSubSystemByClasses(const TArray& SubSystemClasses)
{
TArray SubSystems;

for (auto SubSystemClass : SubSystemClasses)
{
auto SubSystem = AddSubSystemByClass( SubSystemClass );
if (IsValid(SubSystem))
{
SubSystems.Add( SubSystem );
}
}

return SubSystems;
}


UGameplaySubSystemBase* FGameplaySubSystemCollectionBase::AddSubSystemByClass(UClass* SubSystemClass)
{
if (SubSystemClass == nullptr || !Outer.IsValid()) return nullptr;
if (SubSystemClass->HasAnyClassFlags(CLASS_Abstract)) return nullptr;
if (!SubSystemClass->IsChildOf(BaseType)) return nullptr;

if (SubSystemMap.Contains( SubSystemClass ))
{
return SubSystemMap.FindRef(SubSystemClass).Get();
}

UGameplaySubSystemBase* SubSystem = NewObject(Outer.Get(), SubSystemClass);
AddSubSystem(SubSystem);
return SubSystem;
}

void FGameplaySubSystemCollectionBase::AddSubSystem(UGameplaySubSystemBase* SubSystem)
{
if (!IsValid(SubSystem)) return;

if (auto CurrentSubSystem = GetSubSystemInternal( SubSystem->GetClass() ); IsValid(CurrentSubSystem))
{
RemoveSubSystem( CurrentSubSystem );
}

SubSystemMap.Add( SubSystem->GetClass(), TStrongObjectPtr(SubSystem)  );
SubSystem->Init();
}

void FGameplaySubSystemCollectionBase::RemoveSubSystemByClass(UClass* SubSystemClass)
{
if (SubSystemClass == nullptr || !Outer.IsValid()) return;
if (!SubSystemMap.Contains( SubSystemClass )) return;

auto SubSystem = GetSubSystemInternal(SubSystemClass);
if (!IsValid(SubSystem)) return;

SubSystem->Uninit();
SubSystemMap.Remove( SubSystemClass );
}

void FGameplaySubSystemCollectionBase::RemoveSubSystem(UGameplaySubSystemBase* SubSystem)
{
if (!IsValid(SubSystem)) return;

auto SubSystemClass = SubSystem->GetClass();
if (!SubSystemMap.Contains( SubSystemClass ) ||SubSystemMap.FindRef(SubSystemClass).Get() != SubSystem) return;

RemoveSubSystemByClass( SubSystemClass );
}

// -----

UGameplaySubSystemBase* FGameplaySubSystemCollectionBase::GetSubSystemInternal(UClass* SubSystemClass) const
{
if (SubSystemClass == nullptr) return nullptr;

if (!SubSystemMap.Contains( SubSystemClass )) return nullptr;

if (auto& SubSystem = SubSystemMap.FindChecked( SubSystemClass ); SubSystem.IsValid())
{
return SubSystem.Get();
}

return nullptr;
}

TArray FGameplaySubSystemCollectionBase::GetSubSystemsInternal() const
{
TArray  OutArray;

for (auto& [Class, SubSystem] : SubSystemMap)
{
if (!SubSystem.IsValid()) continue;
OutArray.Add( SubSystem.Get() );
}
return OutArray;
}

对于 FGameplaySubSystemCollection，提供几个特化的方法，主要是 GetSubSystem：

// FGameplaySubSystemCollection.h

template<typename TBaseType>
struct FGameplaySubSystemCollection : FGameplaySubSystemCollectionBase
{
static_assert(TIsDerivedFrom::Value, "TBaseType must inherit from UGameplaySubSystemBase");

FGameplaySubSystemCollection() : FGameplaySubSystemCollectionBase(TBaseType::StaticClass())
{
}

public:
template<class TSubSystemClass = TBaseType>
typename TEnableIf::Value, TSubSystemClass*>::Type
GetSubSystem() const
{
return static_cast(GetSubSystemInternal(TSubSystemClass::StaticClass()));
}

template<class TSubSystemClass = TBaseType>
typename TEnableIf::Value, TArray>::Type
GetSubSystems() const
{
const TArray& Array = GetSubSystemsInternal();
const TArray* SpecificArray = reinterpret_cast<const TArray*>(&Array);
return *SpecificArray;
}
};

特别地，这里的 FGameplaySubSystemCollection::GetSubSystems，由于 FGameplaySubSystemCollection::GetSubSystemsInternal 返回的也是 UGameplaySubSystemBase 指针，内存大小和 TSubSystemClass 指针一样，所以可以使用 reinterpret_cast 直接将整个数组的类型转化，节省遍历 cast 开销。

SubSystemBase

需要一个 SubSystemBase。

提供一些基础的方法，Init、Uninit、Tick 在 SubSystemCollection 中调用。

同时子类只需要关心：OnInit、OnUninit、OnTick。

对于各自的业务，各自继承自定义的 SubSystemBase ，然后再自定义各自的 SubSytem 继承于这个业务扩展出来的 SubSystemBase 即可。

SubSystemBase->GetOuter() 就可以拿到对应的 Manager。

对于 Tick ，维护一个 LastTickTime，用于计算 DeltaTime 。

// GameplaySubSystemBase.h

UCLASS(Abstract)
class UGameplaySubSystemBase : public UObject
{
GENERATED_BODY()

#pragma region Init

public:
void Init();
void Uninit();

protected:
virtual void OnInit();
virtual void OnUninit();

#pragma endregion Init

#pragma region Tick

public:
void Tick();

protected:
virtual void OnTick(float DeltaTime);

protected:
virtual float GetTickInternal() { return -1.0f; }
virtual float GetWorldTimeNow();

private:
float LastTickTime;


#pragma endregion Tick

};

// GameplaySubSystemBase.cpp

#pragma region Init

void UGameplaySubSystemBase::Init()
{
LastTickTime = GetWorldTimeNow();
OnInit();
}

void UGameplaySubSystemBase::OnInit()
{
}


// ------------------------------

void UGameplaySubSystemBase::Uninit()
{
OnUninit();
}

void UGameplaySubSystemBase::OnUninit()
{
}


#pragma endregion Init



#pragma region Tick


void UGameplaySubSystemBase::Tick()
{
float TickInternal = GetTickInternal();
if (TickInternal < 0) return;

float CurrentTickTime = GetWorldTimeNow();
if (CurrentTickTime - LastTickTime > TickInternal)
{
OnTick(CurrentTickTime - LastTickTime);
LastTickTime = CurrentTickTime;
}
}

void UGameplaySubSystemBase::OnTick(float DeltaTime)
{

}

#pragma endregion Tick

同步方案

由于各业务拆分到 SubSystem 中，其中

SubSystem 需要在 Client 有对应实例；
SubSystem 需要支持属性同步的数据；
SubSystem 需要支持 RPC；

一种简单的方案是将这种需要同步的数据，存储在 Manager 中，SubSystem 也跟着 Manager 创建，但显然这样不够优雅；

于是可以实现一套 SubSystem 的同步方案，核心思路是：

将 SubSystem 作为 Manager 的 SubObj ，通过同步在 Client 创建出来，创建后注册进 Manager 对应的 Collection 中；

同步基建

显然，这里的 Manager 可能是 Actor，也可能是 ActorComponent；

将 SubSystem 作为 Manager 的 SubObj 进行同步创建，通过 ReplicateSubObjects 来同步；

SubSystem 实现 IInterface_ActorSubobject，在其中 OnOnCreatedFromReplication 的回调中，通过 GetOuter 获取 Manager；

Manager 实现 IGameplaySubSystemCollectionOwnerInterface，获取 Collection；

这样就可以在 Client 将 SubSystem 注册进对应 Manager 的 Collection；

Create SubObject

flowchart LRUActorChannel::ProcessBunch-->UActorChannel::ReadContentBlockPayload-->UActorChannel::ReadContentBlockHeaderUActorChannel::ProcessBunch-->UActorChannel::FindOrCreateReplicatorUActorChannel::ProcessBunch-->FObjectReplicator::ReceivedBunch

在 Client 收到同步包时，首先进行 UActorChannel::ReadContentBlockHeader，

在这里会从 Bunch 中反序列出对应的数据，对应着 UActorChannel::WriteContentBlockHeader 中序列化的数据；

可以观察到，对于 SubObj，会在这里进行 NewObject 并且由 ActorChannel->CreateSubObjects 持有；

并且最后返回 SubObj 作为 RepObj，在 UActorChannel::ProcessBunch 中 FindOrCreateReplicator 并记录在 ReplicationMap 中，后续进行 FObjectReplicator::ReceivedBunch；

在 FObjectReplicator::PostReceivedBunch 中 CallRepNotifies 执行一系列 OnRep；

特别地，如果在一个 Object 中同步了一个 SubObjectArray，该 Array 标记有 ReplicatedUsing 方法，当 SubObject 在 Client 创建出时，会立马调用到该 OnRep 方法；（每次 ProcessBunch 都会对所有的 ReplicationMap 调用 PostReceivedBunch）；

一致的 Outer

Client 创建出 SubSystem 时，通过 GetOuter 找到 Manager，从而找到 Collection 注册进该 SubSystem；

所以需要保证这里 NewObject 时，和 DS 保持一致的 Outer，这样才能找到正确的 Manager；

实际上，在 UE4 中这里 NewObject 时，直接将 Actor 作为 Outer；

（但实际上 SubObj 可能由 ActorComponent 等 SubObj 持有；错误的 Actor 会丢失索引路由）

参考 UE5，在 UActorChannel::ReadContentBlockHeader 时：

新写入一个 Bit(0/1) 表示 bActorIsOuter，仅当 (ObjOuter == Actor) || (!Obj->IsSupportedForNetworking()) 时，该值为 true；

为了节省流量，仅当 bActorIsOuter = false 时候向 Bunch 中写入 ObjOuter；

UObject* ObjOuter = Obj->GetOuter();
const bool bActorIsOuter = (ObjOuter == Actor) || (!Obj->IsSupportedForNetworking());
Bunch.WriteBit(bActorIsOuter ? 1 : 0);
if (!bActorIsOuter)
{
    Bunch << ObjOuter;
}

在创建完 SubObj 后，会调用 Actor->OnSubobjectCreatedFromReplication( SubObj )，找到对应的 Interface 执行回调；

if ( UActorComponent * Component = Cast(NewSubobject) )
{
    Component->OnCreatedFromReplication();
}
else if (IInterface_ActorSubobject* SubojectInterface = Cast(NewSubobject))
{
    SubojectInterface->OnCreatedFromReplication();
}

在这里可以进行 SubSystem 的注册；

具体实现

Manager

对于 Manager，重载 Manager 的 ReplicateSubobjects，调用 Collection 提供的 ReplicateSubSystems 方法；

// Manager.cpp

bool UManager::ReplicateSubobjects(UActorChannel* Channel, FOutBunch* Bunch, FReplicationFlags* RepFlags)
{
bool WroteSomething = false;

WroteSomething |= Super::ReplicateSubobjects(Channel, Bunch, RepFlags);
WroteSomething |= SubSystemCollections.ReplicateSubSystems( Channel, Bunch, RepFlags );

return WroteSomething;
}

同时，Manager 需要实现 IGameplaySubSystemCollectionOwnerInterface 接口，用于后续 SubSystem 的注册；

1
2
3

// Manager.h

virtual FGameCollectionBase& GetSubSystemCollectionBase() override { return SubSystemCollections; }

SubSystemCollection

对于 SubSystemCollection 实现 ReplicateSubSystems，将需要同步的（IsSupportedForNetworking == true ）SubSystem 写入到 Bunch 中；

bool FGameCollectionBase::ReplicateSubSystems(UActorChannel* Channel, FOutBunch* Bunch, FReplicationFlags* RepFlags)
{
if (!Outer.IsValid()) return false;
if (!IsValid(Channel)) return false;

if (RepFlags->bNetInitial) return false;

bool WroteSomething = false;
const auto& SubSystems = GetSubSystemsInternal();
for (auto SubSystem : SubSystems)
{
if (!IsValid(SubSystem)) continue;

if (SubSystem->IsSupportedForNetworking())
{
WroteSomething |= Channel->ReplicateSubobject( SubSystem, *Bunch, *RepFlags );
}
}

return WroteSomething;
}

特别地，当 RepFlags 初始化时，先不进行 SubSystem 的同步；

这是因为在 AActor::ReplicateSubobjects 时，递归进行的 ReplicateSubobjects：

for (UActorComponent* ActorComp : ReplicatedComponents)
{
    if (ActorComp && ActorComp->GetIsReplicated())
    {
        WroteSomething |= ActorComp->ReplicateSubobjects(Channel, Bunch, RepFlags);
        WroteSomething |= Channel->ReplicateSubobject(ActorComp, *Bunch, *RepFlags);
    }
}

同步一般会先进行 Actor 的同步，之后进行 ActorComponent 的同步，也就是从上到下的设置同步参数，然后 StartReplicating；

flowchart LRUActorChannel::ReplicateSubobject--> UActorChannel::CreateReplicator--> FObjectReplicator::StartReplicating--> UNetDriver::GetReplicationChangeListMgr--> FRepLayout::CreateReplicationChangelistMgr

但是如果 SubSystem 作为一个 Manager(ActorComponent) 的 SubSystem 时，由于递归的顺序，会先调用 ActorComponent 的 SubSystem 的 StartReplicating，然后再调用 ActorComponent 的 StartReplicating；

可能会导致时序的问题，所以延迟一帧开始同步 SubSystem（判断 RepFlags->bNetInitial）；

SubSystemBase

首先对于需要同步的 SubSystem，重载 IsSupportedForNetworking 标记为 true；

为了在 Client 创建时有回调，需要实现 IInterface_ActorSubobject 接口；

创建后在 Client 正常 GetOuter，就可以获取到 Manager ，通过 Manager 的 IGameplaySubSystemCollectionOwnerInterface 实现的 GetSubSystemCollectionPtr 找到对应 Collection，将 SubSystem 注册进去；

同时，为了支持发送 RPC，需要实现 GetOwnerActor 以找到该 SubSystem 所属的 Actor，以作为 ProcessRemoteFunction 的参数；

并且需要重载 CallRemoteFunction、GetFunctionCallspace，以进行正常的 RPC；

// GameplaySubSystemBase.h

public:
virtual bool IsSupportedForNetworking() const override { return false; }

public:
AActor* GetOwnerActor() const;
virtual bool CallRemoteFunction(UFunction* Function, void* Parameters, FOutParmRec* OutParms, FFrame* Stack) override;
virtual int32 GetFunctionCallspace( UFunction* Function, FFrame* Stack ) override;

public:
virtual void OnCreatedFromReplication() override;
virtual void OnDestroyedFromReplication() override;

在 CreatedFromReplication 时，通过 GetOuter 获取 Manager，再找到 Collection 将自己注册进去；

// GameplaySubSystemBase.cpp

AActor* UGameplaySubSystemBase::GetOwnerActor() const
{
UObject* Outer = GetOuter();
if (!IsValid(Outer)) return nullptr;

if (auto OwnerActor = Cast(Outer); IsValid(OwnerActor))
{
return OwnerActor;
}

if (auto OwnerActorComponent = Cast(Outer); IsValid(OwnerActorComponent))
{
return OwnerActorComponent->GetOwner();
}

return nullptr;
}

bool UGameplaySubSystemBase::CallRemoteFunction(UFunction* Function, void* Parameters, FOutParmRec* OutParms, FFrame* Stack)
{
bool bProcessed = false;

if (AActor* OwnerActor = GetOwnerActor())
{
FWorldContext* const Context = GEngine->GetWorldContextFromWorld(GetWorld());
if (Context != nullptr)
{
for (FNamedNetDriver& Driver : Context->ActiveNetDrivers)
{
if (Driver.NetDriver != nullptr && Driver.NetDriver->ShouldReplicateFunction(OwnerActor, Function))
{
Driver.NetDriver->ProcessRemoteFunction(OwnerActor, Function, Parameters, OutParms, Stack, this);
bProcessed = true;
}
}
}
}

return bProcessed;
}

int32 UGameplaySubSystemBase::GetFunctionCallspace(UFunction* Function, FFrame* Stack)
{
UObject* Outer = GetOuter();
if (!IsValid(Outer)) return false;
return Outer->GetFunctionCallspace(Function, Stack);
}

void UGameplaySubSystemBase::OnCreatedFromReplication()
{
auto CollectionOwner = Cast(GetOuter());
if (CollectionOwner == nullptr) return;

auto CollectionPtr = CollectionOwner->GetSubSystemCollectionPtr( GetClass() );
if (CollectionPtr == nullptr) return;

CollectionPtr->SetOuter(GetOuter());
CollectionPtr->AddSubSystem(this);
}

void UGameplaySubSystemBase::OnDestroyedFromReplication()
{
auto CollectionOwner = Cast(GetOuter());
if (CollectionOwner == nullptr) return;

auto CollectionPtr = CollectionOwner->GetSubSystemCollectionPtr( GetClass() );
if (CollectionPtr == nullptr) return;

CollectionPtr->RemoveSubSystem(this);
}

这样，对于一个 SubSytem 就可以正常的进行数据同步与 RPC；

Note

Remove

在 UE4 中，没有提供直接 RemoveSubObject 机制，对于一个同步的 SubObj，会一直在 ActorChannel->CreateSubObjects 中被持有；

当 UActorChannel::DestroyActorAndComponents 时，会进行 Destroy；或者主动构造 Bunch，让其 Connection->PackageMap->SerializeObject( Bunch, UObject::StaticClass(), SubObjClassObj, &ClassNetGUID ) 获取的 ClassNetGUID invalid，从而在 CreateSubObjects 中 Remove 掉对应的 SubObj；

在 UE5 中相关 SubObj 的同步进行了重构，正常支持动态的 AddSubObject/RemoveSubObject；

Destroy

在 UObject::ConditionalBeginDestroy 执行到 UActorChannel::CleanUp 时，会清除 Channel 中所有的 SubObj。

此时需要注意 GC 的时序，有可能此时 Actor->GetWorld() 中 Actor->GetOuter() 已经提前被清除，导致无法进行 DestroyActorAndComponents，无法正确清除 CreateSubObjects；

if (!Actor->bNetTemporary && Actor->GetWorld() != NULL && !IsEngineExitRequested() && Connection->Driver->ShouldClientDestroyActor(Actor))
{
    UE_LOG(LogNetDormancy, Verbose, TEXT("UActorChannel::CleanUp: Destroying Actor. %s"), *Describe() );

    DestroyActorAndComponents();
}

RPC

在 UE4 中，如果在 ThisClass->UObject 这一条继承链中，没有任何一个 UPROPERTY 属性，则相关 UFUNCTION 的同步数据无法写入 NetFiled，无法发送 RPC

这是因为在 UNetDriver::InternalProcessRemoteFunctionPrivate 时调用的 const FClassNetCache* ClassCache = NetCache->GetClassNetCache( TargetObj->GetClass() );；其中 UClass::SetUpRuntimeReplicationData 判定了：

1	if (!HasAnyClassFlags(CLASS_ReplicationDataIsSetUp) && PropertyLink != NULL)

这里判断了 PropertyLink != nullptr，不过显然是没有必要的，可以将其直接去掉；

这样就支持了没有 UPROPERTY 的 Object 可以正常 SetUpRuntimeReplicationData；

该问题在 UE5.3 中正式修复：Allow replication of UObjects with UFunctions but no UProperties。

2024 年度总结

2024-12-31T15:59:59.000Z

2024 年度总结

一月~二月

在反思中开始了新的一年，今年不断思考，经历无数的迷茫，缓慢前行。

开年经历了各种各样的事件后，在多少个深夜不断思考，剖析自我。

恰逢《我的青春恋爱物语果然有问题》完结。看着八幡从孤僻冷漠的人，经历各种困难，解决各种事件，不断反思与追问，成长为成熟又温柔的大老师。完结的不是春物，结束的只是那个所谓不需要归宿的 “彷徨的孤高灵魂”，他终将找到自己的真物。我的真物又在哪里？

月底《幻兽帕鲁》正式上线，一家小公司不断成长，最终做出了名动世界的作品，这样的故事实在是令人感慨，或许小厂才能有这样的创造力，看了他们制作人的话，很受感动：

到达这一点的道路是漫长的。
回想起来，我觉得自己确实走了一条弯路。
这是一系列不必要的失败。
我一遍又一遍地在我不应该绊倒的地方绊倒，如果我知道的话。
我不知道行业专家应该知道的事情。
因为我们是一群业余爱好者。
“我该怎么做?”——
开始我什么都不知道。
然而，这段弯路让我与人们建立了联系，并组建了今天的团队。
正是因为我们是一群业余爱好者，所以我们才能创造出一种不受行业惯例约束的方法。
如果我们一家叫 Pocket Pair 的公司是一群游戏行业的专业人士，筹集了资金并且现金充裕的话。
《Pal World》这款游戏就不会诞生在这个世界上。
仅仅因为你有钱并不意味着你可以制作有趣的游戏。

或许这群 “业余爱好者” 才是真正的游戏人。“越有才华的人越早离开公司”，太多日子人，用生命玩着上班过家家，扮演着自己的角色，沉浸和迷失在这种 Cosplay 里。

人看似在走，心却停留在原地，在人生的道路上踟蹰不前，我又何尝不是如此？

很喜欢 doctor 说的一段话：

“所谓觉悟，就是在漆黑的荒野上开辟出一条理当前进的光明大道。”

在成长的道路上前行，我又是否有这样的决心与觉悟呢？

三月

满载着迷茫与纠结，被项目推着向前走。在思考的同时，也要先处理好眼下该做的事情，项目七月份就将要上线。

开始负责新的模式夺旗赛，从头开始实现一个玩法单局，设计了核心框架、重构了新的组队系统……除了应付基本的业务需求，也借此机会更加深入底层，不局限于单纯的实现，做了很多如今看来也很有价值的设计与实现。

从技术来看成长了许多，架构清晰了许多。虽然现在回头来看又有很多不足，但这或许说明还有继续成长与进化的空间。

迷茫中缓慢向前走，在技术沉淀的同时也常看一些游戏设计。在加班的同时寻求一些成长，虽然深知将这些积累实际应用起来才有价值，不过也得先做好积累，才有实践的那一天。

看完了《体操武士》，很喜欢评论里的一句话：

“不怕痛的毅力，是追梦人的护身符”。

时时感慨自己心怀梦想却被困在工位，一边觉得世人皆醉我独醒，一边自卑痛恨太过弱小没有力量，踌躇满志却又经常瘫痪在床看动漫。

希望自己可以更加坚强，更加勇敢，更加勤奋一些。

四月

得知了乐华收购 A-SOUL，晚晚决定不继续签合同，选择了退出。这才发现自己也很久没有看 A-SOUL 的直播了，在那个晚上疯狂刷着过去的动态。

自己一路匆匆忙忙寻觅远方，在某个不经意的驻足，才发现错过了多少沿途的美丽风景。

平常总是期待着发生一些奇迹，向往着一些缘分，可以把所有的偶然都实现。回过头看，才发现原来那样一个个相伴着的稀松平常的夜晚，正是奇迹发生的时刻。可惜，再也不会迎来这样的时刻了。

天下没有不散的宴席，再美丽的花朵也会枯萎，再闪耀的太阳也将落下。

或许人生就是这样，体验一次又一次的离去，从痛哭到沉默，从痛苦到漠然，从撕心裂肺再到云淡风轻。不知该庆幸还是可笑，人生的韧性与厚度却随着这些分别在不断增加。

“所以生命啊，它苦涩如歌”，惟愿分别的人们未来各自安好，一路顺风。

有离别的悲伤，也有重逢的喜悦，网易宣布了重新和暴雪展开合作。

当初高中时和朋友们在机房一起打《炉石传说》研究卡牌构筑的日子涌上心头，也回想起了那个暑假，和狗哥他们在《守望先锋》里一起开黑的时光。

在回归留言里写下了《守望先锋》里大锤的话：

从当初的游戏玩家，到现在的游戏开发者，或许我也始终还在做梦，自己能成为守护大家的英雄，能做出那样好玩的作品，见证每一位玩家的青春与时光，创造各种各样的记忆。

五月~六月

五月初和朋友们在广州相聚了一下，一起泡了泡温泉，恰了恰饭，回到科韵路圣地巡礼。

一切好像和往年一样，又有不一样的地方，这次同好会的人没有过去整齐。不过也深知在所难免，随着年纪逐渐增长，有太多的现实需要面对，越来越多的问题需要去解决。好像 时间催着每个人向前，去处理人生或者世俗的要事。

在小学时期就在游戏里结识的朋友，也在此期间摆脱了母胎 solo。翻阅起那些旧日的聊天记录，回忆起曾经分享动漫和日常琐事的时光，真是怀念那段纯真的岁月。可惜尽管曾约定见面，却总是因为忙碌而未能成行，还未见过就已经错过。

也许因为自己内心的自卑，或是不自觉的骄傲，又或许是曾经暗生的情愫，随着她迈入恋爱的新篇章，我也选择了默默减少联系。尽管如此，仍满怀真诚地希望她拥有一个充满幸福和美好的未来。

间歇中看完了《蓝色监狱》，其中绘心对于梦想的描述让人动容：

梦想的意义在于实现，不知不觉间，追逐变成了意义所在。这种不断自我麻痹，沦为逐梦亡灵的垃圾，我一丁点兴趣都没有。
**梦想必须为实现而存在才有意义。**所以，落败是梦想的岔路口，他们必须足够坚强，能在这一刻深感自己能力不够，这是绝望的天赋。
有些可行的道路，只有放弃自己描绘的梦想之路才能看见，这将化为自己全新的可能性。
身陷绝望依然坚持战斗的人，怀有实现梦想的力量。

自己的梦想，需要自己负责。不能总是用一些借口逃避，用虚假的努力安慰自己自我麻痹，假装自己在追求梦想的路上。

又看完了《钻石王牌》，以荣纯的视角，一个普通人逐渐努力成长为王牌，以队伍的视角，青道经历了各种失败，终于在秋季大赛打进了甲子园。

队伍里的每个人都有自己的梦想要追寻，这就是棒球，这就是体育，大家都有自己的奋斗故事。

比起已经搞砸的过去，还有大概率会搞砸的未来，更重要的是现在，这个不知道会不会搞砸的瞬间。

所有人努力毅力与坚持，共同谱写了这段美好的故事。

“为夏日之梦而生的人啊，为青涩灵魂点上熊熊烈火吧！”，敬佩每一个为了梦想，明知不可为而为之的人。

在某个思考着沉默着的夜晚，独自一人长跑去深圳湾边看海。

坐在岸边看着灰暗的天空，想起了三年前初来到深圳，也是在某个深夜坐在深圳湾边看着大海发呆。时间过去了这么久，我也和当初那个自己截然不同。川流不会停止，总在见证着些什么，又遗忘着什么。

流水无情，除了记忆，什么也没有留下。

七月

经历了种种磨难，终于迎来了第一个参加的项目 *《极品飞车：集结》*上线的日子。

上线前花了点时间整理自己做的模块，导出了一张图表，感慨自己在这个项目里留下了这么多的内容。

还记得上线那天六点多起来，天还没亮就出发到公司，早早来等开服。

可惜，故事的结局不总是那么美好。

**努力就会得到回报，是一句狡猾的箴言。**回报的设定也许是在明天，也有可能会被拉长到永远。

上线当天的数据并不让人满意，也因为实际福利与宣传大相径庭导致口碑崩坏。记得晚上一两点的时候，doctor 直接去和老板讨论福利相关的问题，不过并没有什么用，大家都有各自的坚持与需要考虑的问题。

晚上和他在公司楼下聊人生到凌晨四点，听着他的故事，也思考自己的道路。

天美是个大染缸，潜移默化地影响着每一位其中的从业者。日复一日的工作、加班和执行，最终将个性抹平，神经活性开始降低，停止了进化。

为了自我安慰，找升职、买房、结婚这些锚点，继续重复地生活，停止了思考。被这些锚点一辈子钉在原地。世界开始变小，小到只有家、工位和通勤的路。时间开始变短，明天还未开始，就又和昨天类似。

尽管完全有能力和活力做更多的事情，却最终活成了一个程序化的人。

野狗会去追逐星星，明知不可为，也不愿停下。**追逐的路上有风雪艳阳，目尽远方是星河滚烫。**或许还真能抵达世界尽头，去传达几声犬吠。可自己又有多久没有看过天上的星星了，是否还记得自己的初心？

没有人天生就是程序员或游戏开发者，多少人被困在内心的栅栏之中无法迈出一步。

醒得太早不是件好事，或许一辈子没醒更是快乐。

毕业后的第一个夏天，伴随着项目上线画上了句点。

这个夏天，结束得太快。

八月 ~ 九月

上线之后保持着基本的运营，也轻松了许多，更深知做游戏不易。

偶然又看到了当初写的第一个 3D 贪吃蛇 Demo，还有想做出让大家都快乐的游戏的宣言，感慨过去的活力。

项目的数据虽然不好，但还是让很多玩家体验到了自己参与的游戏，不幸却又很幸运。

一路风雪，虽有遗憾却从未后悔。

趁着闲暇的时间充实了一波技术栈，逐渐把过去落下的东西给补上。了解了网络同步底层，也研究透了 GAS，输出了很多技术文章，在 Gameplay 和网络同步相关的技术上都更上一层楼。沉淀技术的同时，也时常找策划探讨各种游戏设计。

恰好黑神话上线，请假了几天通关了隐藏结局，感叹 3A 时代正在拉开帷幕，并由衷地希望自己真的有机会能参与到其中。

羡慕悟空相信 命不由天 ，以肉身之死，换意念永续，最后命不由天、战胜天命。更羡慕最后的制作人员的名单里的游戏开发者们，有生之年可以留下这样一款游戏，青史留名。

相比之下，大多数从业者看似在开发游戏，实际上只是在制造产品，加入了一个以产品为导向的公司。

真正的游戏人太少了，可能每个人入行时怀揣着开发游戏的梦想，但随着时间的推移，逐渐开始变形。日常生活下意识的努力都在向完善一张所谓的简历靠，大部分都在梦游。经历了几年的职场生活后，没有 根源的创作欲 ，不是真的要创作游戏，而是要打好工。

很喜欢肛少说的一段话：

做游戏终归是一条 逆行者之路，是真正的小众。纯粹的人太少了，或碍于现实，或囿于能力，或困于欲望。

常说 “如果……，一切会不会不一样”。人生就是这样，痛苦和魅力都在于这些无法回头的选择。徘徊于某个十字路口，选择了一条路，或左或右，就此开始了完全不一样的人生。

看《王室教师海涅》，很喜欢一句话：

比如说，你在临死前的弥留之际，“啊啊，如果当时那样做就好了”，就算你这么想，时光也不会倒流。
属于你的珍贵人生只有一次，想要随心所欲的生活，根本不需要理由。关键是要看你的觉悟。
一旦是自己决定的事，无论一路上遇到多少挫折和绝望，我都要努力去克服。

自己也还差得太远，仍需不断的努力。

十月~十二月

国庆节家人来深圳旅游，做了周密的计划，一起逛了逛世界之窗，去看了看水族馆，爬了爬山也看了看海。

生活方面，一番折腾过后终于搬到了新家，常坐到天亮看着城市被曙光唤醒；娱乐方面，补上了很多过去没看过的老番，推理、运动、恋爱、异世界广泛涉猎；技术方面，基于学到的知识实现了一些新的工具，用新设计重构了过去的系统，也开始接触新方向的内容；游戏方面，体验了一些新作，沉迷酒馆战棋；炒股方面，经历了种种失败决定戒赌，等以后再出发；运动方面，第一次去健身房，希望可以继续坚持。就这样度过了今年的最后几个月。

在写年度总结的时候，也看到了别人的总结，看到也有人在一样挣扎痛苦着为工作所困，感慨万千。

不过希望这些失败与琐碎不会磨灭真正的热爱，希望当初写下 “将此生献给游戏行业” 的少年们都可以找回 初心与道路。再次找到做游戏最开始的快乐，让自己快乐，让大家快乐，让每一个玩家都快乐。

“正确的道路，不会因为中途的坎坷而有所改变。”

期间看到了《洛奇》的混剪，印象颇深，借鉴一下其中的话：

这个世界并不全是阳光和彩虹，它充满温情而又冷酷无情。
挫折如疾风骤雨，击打我们的灵魂，磨损我们的意志。
真正的勇士并非从未失败，而是失败后选择依旧站起。
失败不是终点，放弃和绝望才是。
如果我们不尽力挣扎，它就会永久性地把我们揍得跪在地上。
强者迎风反抗，懦夫跪地投降。
重要的并不是出拳有多重，而是能挨多重的拳仍坚持向前，这样才叫胜利！

总结

毕业的第一年，在游戏、工作、人生等方面有了更多的思考。

在感情方面基本没有进展，自我总在孤独的静默中苏醒，一个人也过得很开心快乐。

参与的第一个大型项目*《极品飞车：集结》* 终于上线了，即便数据一般，但也让那么多的玩家体验到了自己做的游戏。

清醒地挣扎，缓慢地前行。

成长没有那么快，但坚持在路上，总能走到远方。即便过程中产生了很多负面情绪，也可以算是对热爱的事业为之动容的表现吧。

贪心地希望自己有朝一日可以做出更加满意的游戏，俘获更多的玩家的心，也收获更多的宝贵记忆。

毕竟，在这漫长又短暂的人生之旅中，总得留下几笔 浓墨重彩 吧？

“夜幕低垂，星辰方显璀璨。冬雪皑皑，暖阳更觉温柔。”

哪怕失败会是一路的主旋律，但 风霜岁月的淬炼之下，灵魂才更为坚韧。

整理好行装，准备再次出发踏上新的征途吧！

[UE]FModel资源解包流程

2024-08-29T16:00:00.000Z

FModel资源解包流程

基于 FModel 的资源解包方案

USMAP 生成

通过 DLL 注入工具 DLL Injector 将 UnrealMappingsDumper 注入到对应的游戏进程中：

Inject 后，会弹框并生成对应的 .usmap 文件

AES Key

下载 AES_finder，将 AES_finder.exe 放在对应游戏目录下并运行，得到 key.txt，其中的内容就是 AES Key，即 Advanced Encryption Standard 密钥；

FModel

下载 FModel，将目录选定到需要解包的游戏目录，设置对应的 UE Versions：

打开后，可能会弹出如下报错：

检查如下目录：./FModel/Output/.data ，发现存在未解压的压缩包，将其解压后 Restart：

正常打开后设置对应的 Mapping File 为之前生成的 .usmap：

然后会发现左侧已经识别到对应的 .pak，但是 [WRN] Could not load virtual paths, plugin manifest may not exist，此时设置之前对应的 AES Key 即可：

然后可以看到获得了对应的 .pak：

参考

AES获取与UModel解包

FModel解包教程与资产检索

《黑神话：悟空》MOD制作：模型替换教程

[UE]网络时钟对齐解决方案

2024-08-14T16:00:00.000Z

网络时钟对齐解决方案

由于网络延迟等问题，Client 时间与 DS 时间可能不同。

对于 Client 需要有一个接近正确的 GetServerWorldTime 来获取当前 DS 的时间戳，尽可能保证在 DS 与各个不同的 Client 中，同一时刻该值唯一。

GameInstance

通过 GameInstance 来存储一些时间数据记录，最后保证所有读取数据从这里访问：

1
2
3

int64 StartTicks = 0;
float WorldSeconds = 0;
float ServerWorldSeconds = 0;

首先在 UGameInstance::Init() 时，记录 StartTicks = FDateTime::Now().GetTicks()；

后续在 GeServerWorldTimeSeconds 时，对 ServerWorldSeconds、WorldSeconds 进行更新；

ServerTimeSynchronizer

Register

在 Client 的 PlayerController 成功 Received 时，进行对时校验的注册，每隔 SyncServerTime_TimeInterval = 5.0f 进行一次对时；

void APlayerController::ReceivedPlayer()
{
// ...
if (IsLocalController())
{
ClientStartSyncTime();
}
}

void APlayerController::ClientStartSyncTime()
{
if (GetNetMode() != NM_Client) return;

GetWorld()->GetTimerManager().SetTimer(SyncServerTime_TimeHandle, [WeakSelfPtr = TWeakObjectPtr(this)]()
{
if (!WeakSelfPtr.IsValid() || WeakSelfPtr->GetNetMode() != NM_Client) return;

if (!WeakSelfPtr->ServerTimeSynchronizer.IsTimeSynced())
{
WeakSelfPtr->C2S_ReqReportTime_Reliable(FDateTime::Now().GetTicks());
}
else
{
WeakSelfPtr->C2S_ReqReportTime_Unreliable(FDateTime::Now().GetTicks());
}
}, SyncServerTime_TimeInterval, true);
}

Req & Res

通过 Client 定时发起对时请求 C2S_ReqReportTime，DS 接收到请求后进行回复 S2C_ResReportTime（如果从未进行过对时，则需要 Reliable）；

在 Client 收到 Res 之后，可以根据发包、收包的时间差，不断校准 ServerTime；

UFUNCTION(Reliable, Server)
void C2S_ReqReportTime_Reliable(int64 ClientTime);
UFUNCTION(Unreliable, Server)
void C2S_ReqReportTime_Unreliable(int64 ClientTime);

void OnReceivedServerTime(int64 ClientTime, int64 ServerTime);
UFUNCTION(Reliable, Client)
void S2C_ResReportTime_Reliable(int64 ClientTime, int64 ServerTime);
UFUNCTION(Unreliable, Client)
void S2C_ResReportTime_Unreliable(int64 ClientTime, int64 ServerTime);

void APlayerController::C2S_ReqReportTime_Reliable_Implementation(int64 ClientTime)
{
UGameInstance* GameInstance = GetGameInstance();
if (GameInstance == nullptr) return;

if (GameInstance->IsDedicatedServerInstance() && GameInstance->StartTicks > 0)
{
S2C_ResReportTime_Reliable(ClientTime, FDateTime::Now().GetTicks() - GameInstance->StartTicks);
}
}

void APlayerController::C2S_ReqReportTime_Unreliable_Implementation(int64 ClientTime)
{
UGameInstance* GameInstance = GetGameInstance();
if (GameInstance == nullptr) return;

if (GameInstance->IsDedicatedServerInstance() && GameInstance->StartTicks > 0)
{
S2C_ResReportTime_Unreliable(ClientTime, FDateTime::Now().GetTicks() - GameInstance->StartTicks);
}
}

// --------------------

void APlayerController::OnReceivedServerTime(int64 ClientTime, int64 ServerTime)
{
int64 ClientNow = FDateTime::Now().GetTicks();
int64 RTT = ClientNow - ClientTime;

bool bUpdated = ServerTimeSynchronizer.UpdateServerTime(ServerTime, ClientNow, RTT);
int64 EstimatedServerTime = ServerTimeSynchronizer.CurrentServerTime(ClientNow);

if (!ServerTimeSynchronizer.IsTimeSynced())
{
C2S_ReqReportTime_Reliable(FDateTime::Now().GetTicks());
}
}

void APlayerController::S2C_ResReportTime_Reliable_Implementation(int64 ClientTime, int64 ServerTime)
{
OnReceivedServerTime(ClientTime, ServerTime);
}

void APlayerController::S2C_ResReportTime_Unreliable_Implementation(int64 ClientTime, int64 ServerTime)
{
OnReceivedServerTime(ClientTime, ServerTime);
}

Calculate

通过 FServerTimeSynchronizer 记录时间并辅助对时；

class ENGINE_API FServerTimeSynchronizer
{
public:
FServerTimeSynchronizer() = default;

public:
int64 CurrentServerTime(int64 TimeNow = 0) const;
bool UpdateServerTime(int64 ServerTime, int64 CurrentTime, int64 LatestRTT);
bool IsTimeSynced() const { return bTimeSynced; } // 进行过时钟对齐

private:
int32 CalculateApproximatingDeltaTime(int64 TimeDelta) const;

private:
static constexpr int MAX_VALID_RTT = 500; // 最大能容忍的RTT时间, 超过该时间不作为有效校准数值 (单位 MS)
static constexpr float APPROXIMATING_RATE = 0.33; // 逼近率 (每个单位时间客户端需要逼近服务器的值)

private:
int64 ClientTime = 0;
int64 EstimatedServerTime = 0;
int LatestRTT = INT_MAX;
float DeltaTimeClientToServer = 0.0;
bool bTimeSynced = false;
};

flowchart LRClient_Req--->|RTT|DSDS--->|RTT|Client_Res

每次收到包进行 UpdateServerTime，根据时间差计算出 RTT (收包发包时间差 / 2) 加上当时准确的 ServerTime（RPC 带下来的），可以计算出此时客户端对应的 EstimatedServerTime（此时预估的 ServerTime）；同时记录下这次的 ClientTime；

bool FServerTimeSynchronizer::UpdateServerTime(int64 ServerTime, int64 CurrentTime, int64 RTT)
{
// 丢弃过大的 RTT 时间
if (RTT > MAX_VALID_RTT * ETimespan::TicksPerMillisecond) 
return false; 

// 仅用更小的 RTT 进行当前 EstimatedServerTime 的更新
if (RTT > LatestRTT) 
return false; 

int64 LastEstimatedServerTime = CurrentServerTime(CurrentTime);
ClientTime = CurrentTime;
EstimatedServerTime = ServerTime + RTT / 2;
LatestRTT = RTT;

// 首次更新 ServerTime 或 APPROXIMATING_RATE <= 0, 无需时钟逼近
if ( !bTimeSynced || APPROXIMATING_RATE <= 0)
{
DeltaTimeClientToServer = 0.0;
}
else
{
// 之后的计算逼近到以 EstimatedServerTime 为基准的时间轴
DeltaTimeClientToServer = (float)(LastEstimatedServerTime - EstimatedServerTime);
}

return bTimeSynced = true;
}

这样就可以在后续任何一次查询时，根据查询时的 ClientTime ，与本次对时的预估 ServerTime、 ClientTime 计算出期望的 ServerTime；

int64 FServerTimeSynchronizer::CurrentServerTime(int64 TimeNow) const
{
if (!bTimeSynced) return 0;
int64 TimeDelta = FMath::Max( TimeNow - ClientTime, 0ll );
return EstimatedServerTime + TimeDelta + CalculateApproximatingDeltaTime(TimeDelta);
}

同时，这里引入一个 APPROXIMATING_RATE，进行一定的时间预测逼近，在 DeltaTime 足够小的时候，根据 DeltaTimeClientToServer（客户端与服务器的预测时间差值）进行一定的时间外推 / 内收，让结果尽可能准确。这里 DeltaTimeClientToServer < 0 说明客户端时间比服务器慢，则需要一定的加快。

int32 FServerTimeSynchronizer::CalculateApproximatingDeltaTime(int64 TimeDelta) const
{
if (APPROXIMATING_RATE <= 0)
return 0;

float fEls = float(TimeDelta) * APPROXIMATING_RATE;
if (fEls >= FMath::Abs(DeltaTimeClientToServer))
return 0;

return DeltaTimeClientToServer < 0 ? ceil(DeltaTimeClientToServer + fEls) : ceil(DeltaTimeClientToServer - fEls);
}

GetServerTimeTicks

最后在 PlayerController 暴露 GetServerTimeTicks 给外部访问：

int64 APlayerController::GetServerTimeTicks()
{
return ServerTimeSynchronizer.CurrentServerTime(FDateTime::Now().GetTicks());
}

GetServerWorldTimeSeconds

对 AGameStateBase::GetServerWorldTimeSeconds 进行重载，最后统一通过 WorldGameState 进行时间访问；

double AGameStateBase::GetServerWorldTimeSeconds() const
{
    UWorld* World = GetWorld();
    if (World == nullptr) return 0.;
    
if (UGameInstance* GameInstance = GetGameInstance())
{
float NowSeconds = GetWorld()->TimeSeconds;

// Update ServerWorldSeconds
if (NowSeconds != GameInstance->WorldSeconds)
{
GameInstance->WorldSeconds = NowSeconds;

int64 NowServerTicks = 0;
if (GameInstance->IsDedicatedServerInstance() || HasAuthority())
{
NowServerTicks = FDateTime::Now().GetTicks() - GameInstance->StartTicks;
}
else if (APlayerController* PC = GetGameInstance()->GetFirstLocalPlayerController(GetWorld()))
{
NowServerTicks = PC->GetServerTimeTicks();
}

GameInstance->ServerWorldSeconds = NowServerTicks / ETimespan::TicksPerMillisecond / 1000.f;
}

return GameInstance->ServerWorldSeconds;
}

return World->GetTimeSeconds() + ServerWorldTimeSecondsDelta;
}

[UE]ReplicationGraph应用

2024-08-06T16:00:00.000Z

ReplicationGraph应用

简介

UnrealEngine 基本的网络同步在进行同步时需要对每个连接判断每个 Actor 是否需要同步，开销较大；

可以通过实现 Replication ，实现一个不同的 ReplicationDriver 来优化性能；

Replication 将 World 分为多个区域 Grid，把 Actor 根据所在 Grid 进行分类编组，可以快速找出需要同步的 Actor，同时确定哪些区域需要进行同步复制。

基本原理

对于需要按照空间划分（Spatialize）的 Actor 来说：

首先将 World 按照 CellSize 抽象成一个个 Cell，一个 Cell 对应一个 GridNode，这里的 GridNode 只会在具体用到的时候再创建；

那么对于一个 Actor，根据 Location、CellSize、SpatialBias，就可以计算出其所在的具体 Cell，即 GetCellInfoForActor；

构建

构建 ReplicationGraph 时，在 GridNode 中记录 Actor；

对于 Actor，就可以根据 CellInfo、以及 CullDistance 找到需要同步该 Actor 的 Cell，这里 Cell 对应的 Grid 中会把该 Actor 记录下来；

也就是上述的粉色区域部分，每个 Grid 都会记录下该 Actor；

对于 Spatialize_Static，即静态物体，显然只需要 Add 时计算一次即可；

对于 Spatialize_Dynamic，即动态物体，会在每次开始 PrepareForReplication 时，根据 DynamicActor 的 PreviousCellInfo、NewCellInfo，更新对应的 Grid 存储信息；

查询

在对于一个 Connection 查询哪些 Actor 需要同步时：

UpdateGatherLocationsForConnection 更新 Connection 对应的 Location

根据该 Location 计算出该 Connection 对应的 Cell，把 Cell 对应的 GridNode 中的 Actors 同步下去即可；

源码浅析

数据结构

classDiagram    class UReplicationGraph

FGlobalActorReplicationInfo：同步的 Actor 信息，包括

Settings：FClassReplicationInfo，每个 Actor Class 对应的同步配置，包括 CullDistance、ReplicationPeriodFrame、PriorityScale 等；
Events：FGlobalActorReplicationEvents Events，记录休眠状态的改变时，从休眠列表中添加或者移除；
FConnectionReplicationActorInfo：对于 Connection 同步的 Actor 信息；

ReplicationGraphNode：GraphNode 基类；
ReplicationGraphNode_ActorList：记录同步的 Actors；在 StreamingLevelCollection （以 SubLevelName 为 Key 的 List）中记录 SubLevel 的 Actor，否则在 ReplicationActorList 中记录；
GlobalGraphNodes：维护 GridSpatialization2D；

GraphNode

classDiagram    class UReplicationGraphNode {        TArray~UReplicationGraphNode*~ AllChildNodes        GatherActorListsForConnection()        RouteAddNetworkActorToNodes()        RouteRemoveNetworkActorToNodes()    }    UReplicationGraphNode <|-- UReplicationGraphNode_ActorList     class UReplicationGraphNode_ActorList {    FActorRepListRefView ReplicationActorList    }            UReplicationGraphNode <|-- UReplicationGraphNode_GridSpatialization2D    class UReplicationGraphNode_GridSpatialization2D {        TArray~TArray[UReplicationGraphNode_GridCell*]~ Grid;    }        UReplicationGraphNode <|-- UReplicationGraphNode_AlwaysRelevant    class UReplicationGraphNode_AlwaysRelevant{        TArray~UClass*~AlwaysRelevantClasses;    }        UReplicationGraphNode <|-- UReplicationGraphNode_ActorListFrequencyBuckets         UReplicationGraphNode_ActorList <|-- UReplicationGraphNode_GridCell        UReplicationGraphNode_ActorList <|-- UReplicationGraphNode_AlwaysRelevant_ForConnection

GridSpatalization2D：将世界划分为 2D 网格，按位置把 Actor 分到不同的 GridCell 中，按空间管理Actor 是否进行同步，每帧更新 GridCell 内的 Actor；
GridCell：ReplicationActorList 缓存着在该 GridCell 中的所有静态 Actor，DynamicNodes 里记录动态的 Actor，DormancyNode 里记录休眠的Actor；
AlwaysRelevant ：处理总是发送 Net Updates 给所有 Connections 的 Actors；
AlwaysRelevant_ForConnection：处理总是发送 Net Updates 给特定 Connection 的 Actors ，一般是同步给 PlayerController 和 ViewTarget；
ActorListFrequencyBuckets ：记录地图格子上的动态 Actor ;

生命周期

Init

graph TDStart(UNetDriver::InitBase) --> A("UNetDriver::SetReplicationDriver")A --> B("UReplicationGraph::InitializeActorsInWorld")B --> | 将World中的同步对象添加到对应GraphNode | C("UReplicationGraph::InitializeForWorld")C --> D("UReplicationGraph::AddNetworkActor(AActor* Actor)") A --> E(InitForNetDriver)E --> F(InitGlobalActorClassSettings)E --> G(InitGlobalGraphNodes)

InitGlobalActorClassSettings：设置 CulltDistance、ReplicationPeriodFrame；等信息注册 Actor 对应的 ClassReplicationInfo 到 GlobalActorReplicationInfoMap；

InitGlobalGraphNodes：创建 GridSpatialization2D、AlwaysRelevant 的 GraphNode；

InitConnectionGraphNodes：创建 AlwaysRelevantForConnection 的 GraphNode；

RouteAddNetworkActorToNodes ：生成 Actor 时，添加 NetworkActor，分发 Actor 到 GraphNode；

RouteRemoveNetworkActorToNodes ：销毁 Actor 时，删除 NetworkActor，通知GraphNode 移除 Actor；

Repliate

graph TBStart(ServerReplicateActors) --> A(PrepareForReplication)A --> B(GatherActorListsForConnection)B --> C(ReplicateActorListsForConnections_Default)C --> D[ReplicateSingleActor]

PrepareForReplication ：调用 GraphNode 的 PrepareForReplication：
对于 GridSpatialization2D，会遍历 DynamicActor，更新其所在的 Grid；
对于 AlwaysRelevant，记录需要同步给所有连接的 Actor；
GatherActorListsForConnection ：遍历 Connections 收集 ReplicationActorList
针对每个 Connection 遍历 GlobalGraphNodes 和 Connection 的ConnectionGraphNodes，调用其 GatherActorListsForConnection，收集需要同步给这个Connection 的 Actor；
对于 GridSpatialization2D，通过其 GridCellNode 根据 Actor 的ViewLocation 收集；
收集的 Actor 默认加到 GatheredReplicationListsForConnection 里的 EActorRepListTypeFlags.Default List；
ReplicateActorListsForConnections_Default：进行 Replicate 的同步检测与排序，对 GatheredReplicationListsForConnection 里的 Actor，进行检测；
首先排除 Dormancy、不满足ReplicateFrame 的 Actor，然后根据优先级排序（Distance、Starvation、逻辑判定、Owner & ViewTarget)，将结果缓存在 PrioritizedReplicationList 中；
ReplicateSingleActor：对排好序的 PrioritizedReplicationList 调用 ReplicateSingleActor 进行同步，将对象属性序列化到流中；

具体应用

业务划分

可以按照这些逻辑区分各个 Actor：

Node_AlwaysRelevant_ForConnection：一直同步的 Actor，比如 GameState、全局同步对象；
Node_GridSpatialization2D：用 2D Grid 划分，按照区域同步，比如 Pawn、Character 、SceneItem 等；
Node_PlayerStateFrequencyLimiter：用于 PlayerState，控制同步频率；

初始化

在一个尽早的合适的地方注册UReplicationDriver::CreateReplicationDriverDelegate()；

Lyra 在 ULyraReplicationGraph 的构造函数中（创建 CDO 时）进行；

后续 UNetDriver::InitBase -> SetReplicationDriver 时，会使用该方法进行自定义 ReplicationGraph 的注册：

UReplicationDriver* UReplicationDriver::CreateReplicationDriver(UNetDriver* NetDriver, const FURL& URL, UWorld* World)
{
if (CreateReplicationDriverDelegate().IsBound())
{
return CreateReplicationDriverDelegate().Execute(NetDriver, URL, World);
}
    
    // ...
}

配置化

可以参考 Lyra 注册 ULyraReplicationGraphSettings : UDeveloperSettingsBackedByCVars 在 Project Settings 中，也可以自定义一个 Blueprint 用于记录所有相关配置（在初始化时，重载为初始化该 BP）；

InitGlobalActorClassSettings

进行 Class 相关设置：

SetPolicy

记录 TClassMap ClassRepNodePolicies 用于表示 Class 对应的 Node Policy；

在 RouteAddNetworkActorToNodes、RouteRemoveNetworkActorToNodes 时，通过 GetMappingPolicy(UClass* Class) 找到对应 Policy 的 Node 对应方法；

1
2
3

EClassRepNodeMapping* PolicyPtr = ClassRepNodePolicies.Get(Class);
EClassRepNodeMapping Policy = PolicyPtr ? *PolicyPtr : EClassRepNodeMapping::NotRouted;
return Policy;

可以提供自定义 Policy 的配置，同时需要通过 Class 的一些基础配置设置好 Policy，比如 bAlwaysRelevant && !bOnlyRelevantToOwner 显然是 RelevantAllConnections；

SetClassInfo

FGlobalActorReplicationInfoMap GlobalActorReplicationInfoMap 记录着所有 Class 对应的同步数据，

通过将自定义数据 GlobalActorReplicationInfoMap.SetClassInfo(Class, Info)，并记录 ExplicitlySetClasses 表示该 Class 为自定义类型，防止后续被重载；

可以提供配置化的 Class->FClassReplicationInfo Map；

InitGlobalGraphNodes

进行 ReplicationNode 相关设置，CreateNode 并进行参数设置：

设置 GridNode 的 CellSize（每个 Grid 的大小）、SpatialBias（边界值，ActorLocation 超出时会调用 HandleActorOutOfSpatialBounds 设置 bNeedReubild 并重构 Grid），是否 EnableSpatialRebuilds（决定 AddToClassRebuildDenyList）；
设置 PlayerStateNode 的 TargetActorsPerFrame；

同时可以进行一些额外的参数设置，比如自定义了上层同步频率等；

同步频率控制

控制同步频率和总量；

ClassLimit

进行 ReplicateActorListsForConnections_Default，在 ReplicateActorsForConnection 时，可以针对 RepItem.Actor 的类型进行限制，直接限制该次同步该 ActorClass 可同步的总数量；

bool IsClassLimitExceeded(AActor* Actor)
{
    if (!IsValid(Actor)) return false;
    auto CountPtr = ClassLimitMap.Find( Actor->GetClass() );
    if (CountPtr == nullptr) return true;
    return (*CountPtr)-- > 0;
}

void ReplicateActorsForConnection(UNetConnection* NetConnection, FPerConnectionActorInfoMap& ConnectionActorInfoMap, UNetReplicationGraphConnection* ConnectionManager, const uint32 FrameNum)
{
    // ...
    
    ResetClassLimit(); // 重置可同步总量
    for (int32 ActorIdx = 0; ActorIdx < PrioritizedReplicationList.Items.Num(); ++ActorIdx)
    {
        const FPrioritizedRepList::FItem& RepItem = PrioritizedReplicationList.Items[ActorIdx];
        AActor* Actor = RepItem.Actor;
        // ...
        if (ActorInfo.Channel && IsClassLimitExceeded(Actor) /* 限制同步数量 */)
        {
            continue;
        }
    }
}

Node_PlayerStateFrequencyLimiter

引入 Node_PlayerStateFrequencyLimiter 用于控制 PlayerState 的同步频率，本质是对某一类 Class（可能是不被 AOI 管理，需要一直同步的），进行同步降频；

维护 TArray ReplicationActorLists，每个 FActorRepListRefView 中记录最多 TargetActorsPerFrame 个 Actor，在同步时，对 ReplicationActorLists[ Params.ReplicationFrameNum % ReplicationActorLists.Num() ] 进行同步（帧号 % ListNum）；

需要特别注意：当 NotifyAddNetworkActor 时，进行 ReplicationActorLists 的扩张，当 NotifyRemoveNetworkActor 时，也需要补充上空位（可以将最后的 Actor，补充到被删去的 Actor 的位置）；

同时，新增的 Actor 应该在 ForceNetUpdateReplicationActorList 中；

void UReplicationGraphNode_PlayerStateFrequencyLimiter::NotifyAddNetworkActor(const FNewReplicatedActorInfo& ActorInfo)
{
if (ReplicationActorLists.IsEmpty())
        ReplicationActorLists.AddDefaulted();

FActorRepListRefView* CurrentList = &ReplicationActorLists.Last(); 
if (CurrentList->Num() >= TargetActorsPerFrame)
{
ReplicationActorLists.AddDefaulted();
CurrentList = &ReplicationActorLists.Last(); 
}

CurrentList->Add(ActorInfo.Actor);
ForceNetUpdateReplicationActorList.Add(ActorInfo.Actor);
}

bool UReplicationGraphNode_PlayerStateFrequencyLimiter::NotifyRemoveNetworkActor(const FNewReplicatedActorInfo& ActorInfo, bool bWarnIfNotFound)
{
bool bRemovedSomething = false;
int RemoveListIndex = 0;

for (int Index = 0; Index < ReplicationActorLists.Num(); Index++)
{
if (List[Index].Remove(ActorInfo.Actor))
{
bRemovedSomething = true;
RemoveListIndex = Index;

if (ForceNetUpdateReplicationActorList.Num())
{
ForceNetUpdateReplicationActorList.RemoveFast(ActorInfo.Actor);
}
            
break;
}
}
    
    if (!bRemovedSomthing) return false;

    // 将 LastList 的第一个 Actor 移到 RemoveListIndex 对应的 List
if (ReplicationActorLists.Num() > 1 && RemoveListIndex < ReplicationActorLists.Num())
{
FActorRepListRefView* CurrentList = &ReplicationActorLists.Last();
        
if (!CurrentList->IsEmpty())
{
            auto Actor = (*CurrentList)[0];
ReplicationActorLists[RemoveListIndex].Add(Actor);
CurrentList->RemoveAtSwap(0);
}
        
if (CurrentList->IsEmpty())
{
ReplicationActorLists.RemoveAt(ReplicationActorLists.Num() - 1);
}
}

return true;
}

void UReplicationGraphNode_PlayerStateFrequencyLimiter::NotifyResetAllNetworkActors()
{
Super::NotifyResetAllNetworkActors();

for (auto& List : ReplicationActorLists)
{
List.Reset();
}
    
ReplicationActorLists.Reset();
ForceNetUpdateReplicationActorList.Reset();
}

void UReplicationGraphNode_PlayerStateFrequencyLimiter::GatherActorListsForConnection(const FConnectionGatherActorListParameters& Params)
{
    if (ReplicationActorLists.Num() > 0)
    {
        int ListIdx = Params.ReplicationFrameNum % ReplicationActorLists.Num();
        Params.OutGatheredReplicationLists.AddReplicationActorList(ReplicationActorLists[ListIdx]);
    }

if (ForceNetUpdateReplicationActorList.Num() > 0)
{
        Params.OutGatheredReplicationLists.AddReplicationActorList(ForceNetUpdateReplicationActorList);
}
}

网络相关性

一般的 ReplicationGraph 在启用时，会改变 NetRelevancy，AActor::IsNetRelevantFor 不再被使用；

但是在业务需求中很有可能需要用到这种机制，可以在合适的地方将这个机制添加回去；

首先在 ClassReplicationInfo 添加 bEnableNetRelevancyCheck 字段用于判断是否启用该机制：

static FORCEINLINE_DEBUGGABLE bool IsActorRelevantToConnection( const AActor* Actor, const TArray& ConnectionViewers )
{
for ( int32 viewerIdx = 0; viewerIdx < ConnectionViewers.Num(); viewerIdx++ )
{
if ( Actor->IsNetRelevantFor( ConnectionViewers[viewerIdx].InViewer, ConnectionViewers[viewerIdx].ViewTarget, ConnectionViewers[viewerIdx].ViewLocation ) )
{
return true;
}
}

return false;
}

static FORCEINLINE_DEBUGGABLE bool IsActorEnableNetRelevancyCheck(const FGlobalActorReplicationInfo& GlobalData)
{
   return GlobalData.Settings.bEnableNetRelevancyCheck;
}

在同步 Actor 时进行判定：UReplicationGraph::ReplicateActorListsForConnections_Default：

void UReplicationGraph::ReplicateActorListsForConnections_Default(UNetReplicationGraphConnection* ConnectionManager, FGatheredReplicationActorLists& GatheredReplicationListsForConnection, FNetViewerArray& Viewers)
{
    // ...
    for (const FActorRepListConstView& List : GatheredLists)
    {

        FGlobalActorReplicationInfo& GlobalData = GlobalActorReplicationInfoMap.Get(Actor);
        for (AActor* Actor : List)
        {
            // ...
            if (!ReadyForNextReplication(ConnectionData, GlobalData, FrameNum))
            {
                DO_REPGRAPH_DETAILS(PrioritizedReplicationList.GetNextSkippedDebugDetails(Actor)->FramesTillNextReplication = (FrameNum - ConnectionData.LastRepFrameNum));
                continue;
            }
            
        // [ NetRelevant Check ]
            if (IsActorEnableNetRelevancyCheck(GlobalData) && !IsActorRelevantToConnection(Actor, Viewers))
            {
                continue;
            }
            
            // ...
        }
    }
}

在发送 Multicast RPC 时进行判定：UReplicationGraph::ProcessRemoteFunction：

bool UReplicationGraph::ProcessRemoteFunction(class AActor* Actor, UFunction* Function, void* Parameters, FOutParmRec* OutParms, FFrame* Stack, class UObject* SubObject )
{
    // ...
    
// ----------------------------------
// Multicast
// ----------------------------------

if ((Function->FunctionFlags & FUNC_NetMulticast))
{
        // ...
        FGlobalActorReplicationInfo& GlobalInfo = GlobalActorReplicationInfoMap.Get(Actor);
        
        // ...
        FNetViewerArray ViewsToConsider;
        ViewsToConsider.Emplace(NetConnection, 0.f);

        for (int32 ChildIdx = 0; ChildIdx < NetConnection->Children.Num(); ++ChildIdx)
        {
            if (NetConnection->Children[ChildIdx]->ViewTarget != nullptr)
            {
                ViewsToConsider.Emplace(NetConnection->Children[ChildIdx], 0.f);
            }
        }

        // [ NetRelevant Check ]
        if (IsActorEnableNetRelevancyCheck(GlobalInfo) && !IsActorRelevantToConnection(Actor, Viewers))
        {
            continue;
        }
        
        // ...
    }
    
}

其它应用

快速范围查询

显然，ReplicationGraphNode_GridSpatialization2D 将 Actor 在 World 中按照 Cell 进行了划分；这样的结构可以直接借用来做一些基本的通用需求：比如快速查询某个 Location 一定范围内的所有 Pawn（正常需要对空间额外维护一棵四叉树来处理）；

// 获取 Player 视野范围内的 Actor

TArray UReplicationGraphNode_GridSpatialization2D::GetActorsByPlayer(const APawn* Player)
{
    if (!IsValid(Player)) return {};
    
TArray Result;
    
FVector ClampedViewLoc = Player->GetActorLocation();
if (GridBounds.IsValid)
{
ClampedViewLoc = GridBounds.GetClosestPointTo(ClampedViewLoc);
}
else
{
ClampedViewLoc = ClampedViewLoc.BoundToCube(HALF_WORLD_MAX);
}

    
int32 CellX = UE::LWC::FloatToIntCastChecked((ClampedViewLoc.X - SpatialBias.X) / CellSize);
if (CellX < 0)
{
CellX = 0;
}

int32 CellY = UE::LWC::FloatToIntCastChecked((ClampedViewLoc.Y - SpatialBias.Y) / CellSize);
if (CellY < 0)
{
CellY = 0;
}

if (UReplicationGraphNode_GridCell* CellNode = GetCell(GetGridX(CellX), CellY))
    {
CellNode->GetAllActorsInNode_Debugging(Result);
    }
    
return Result;
}

// 获取坐标范围内的 Cell 中的 Actor

void UReplicationGraphNode_GridSpatialization2D::GetGridActorsByLocationAndRange(FActorRepListType Actor, const FVector& Location3D, float Radius, TArray& OutGatheredNodes)
{
const FActorCellInfo& CellInfo =  GetCellInfoForActor(Actor, Location3D, Radius);
GetGridNodesForActor(Actor, CellInfo, OutGatheredNodes);
}

// 获取 Position 范围 Radius(cm) 内的 Pawn；如果 bAccurate，则需要严格判定，否则模糊判定在 Cell 内即可；

TArray AOIUtils::GetAllPawnsInPosGrid(UWorld* World, const FVector& Position, float Radius, bool bAccurate)
{
    if (!IsValid(World) || !IsValid(World->GetNetDriver())) return {};

    auto RepGraph = World->GetNetDriver()->GetReplicationDriver();
    if (!IsValid(RepGraph)) return {};
    
    auto GridNode = RepGraph->GridNode;
    if (!IsValid(GridNode)) return {};
    
float RadiusSquared = Radius * Radius;
    
    TArray OutGatheredNodes;
    GridNode->GetGridActorsByLocationAndRange(nullptr, Position, Radius, OutGatheredNodes);

    TArray Result;
    for (const auto Cell : OutGatheredNodes)
    {
        TArray>& LocatedActors = Cell->GetLocationNode();
        if (LocatedActors.Num() <= 0) continue; 

        for (auto WeakActorPtr : LocatedActors)
        {
            auto Pawn = Cast(WeakActorPtr);
            if (!IsValid(Pawn)) continue;
            if (!bAccurate || FVector::DistSquared2D(Pawn->GetActorLocation(), Position) <= RadiusSquared)
            {
                Result.Add(Pawn);
            }
        }
    }
    
    return Result;
}

参考

UE ReplicationGraph Document

Lyra (UE5.0-5.3) ReplicationGraph 部分源码

[UE]Subobject同步优化

2024-08-06T16:00:00.000Z

Subobject同步优化

基于 PushModel 的 Subobject 同步优化；

基本机制

UE 提供了 PushModel 机制：

对于 Property 这一层，通过 UEPushModelPrivate::MarkPropertyDirty 主动将其标记为 Dirty；

在 FObjectReplicator::ReplicateProperties_r 进行属性同步时，通过 PushModelState->IsPropertyDirty 判断属性是否 Dirty ；

既然可以判断一个同步对象上的同步 Property 是否有变更，就可以筛选出没有属性变化的对象；可以在 UActorChannel::ReplicateActor、UActorChannel::WriteSubObjectInBunch 时，判断 FObjectReplicator::CanSkipUpdate 跳过这些对象，加快同步速度；

bCanSkip = true;

// Have the RepFlags changed ?
bCanSkip = bCanSkip && SendingRepState.RepFlags.Value == RepFlags.Value; 

// Any Naks to handle ?
bCanSkip = bCanSkip && SendingRepState.NumNaks == 0;

// Have we compared the properties twice ?
bCanSkip = bCanSkip && SendingRepState.LastCompareIndex > 1;

// Do we have open Ack's ?
bCanSkip = bCanSkip && !(SendingRepState.bOpenAckedCalled && SendingRepState.PreOpenAckHistory.Num() > 0);

// Any changelists to send ?
bCanSkip = bCanSkip && SendingRepState.LastChangelistIndex == RepChangelistState.HistoryEnd;

// Is the changelist history fully acknowledged ?
bCanSkip = bCanSkip && SendingRepState.HistoryStart == SendingRepState.HistoryEnd;

// Are we resending data for replay ?
bCanSkip = bCanSkip && Connection->ResendAllDataState == EResendAllDataState::None;

// Are we forcing a compare property ?
bCanSkip = bCanSkip && !OwningChannel->bForceCompareProperties;

// Are any CustomDelta properties dirty ?
bCanSkip = bCanSkip && (RepChangelistState.CustomDeltaChangeIndex == SendingRepState.CustomDeltaChangeIndex && !SendingRepState.HasAnyPendingRetirements());

// Are any replicated properties dirty ?
bCanSkip = bCanSkip && RepChangelistState.HasAnyDirtyProperties() == false;

针对 Subobject 进一步优化

可以观察到 PushModel 在 AActor::ReplicateSubobjects 时，内部针对每个 SubObject 时，进行了一系列优化（CanSkip 的判定）；

但是还是每帧在遍历 ReplicatedComponents 进行判定，并且判定的逻辑本身比较复杂，常数较大，也会造成很大的开销；

这意味着即使没有任何 Component 的 Property 被 MarkDirty，本身 ReplicatedComponents 越多，开销也会随之越大；

基本思路

需要一个机制更加精确地进行 ReplicateSubobject，做到对于非 Dirty 的 Component 直接不遍历；

显然，对于一个 Actor，对于所有需要同步这个 Actor 的 Connection，可以直接记录下 DirtyComponents，即发生了属性变化但还未同步更新的 Subobject；在每次 Dirty 时加入，在同步后移除；

NotifyDirty

首先需要可以知道一个 Component 被 MarkDirty；

在 PushModel 中新增 Delegate：

class NETCORE_API FNetPushModelDelegate
{
public:
    
DECLARE_MULTICAST_DELEGATE_OneParam(FMarkPropertyDirtyDelegate, const UEPushModelPrivate::FNetPushObjectId&);
static FMarkPropertyDirtyDelegate OnMarkPropertyDirty;
};

修改 PushModel::MarkPropertyDirty：

void MarkPropertyDirty(const FNetLegacyPushObjectId ObjectId, const int32 RepIndex)
{
    const int32 ObjectIndex = ObjectId;
    if (LIKELY(PerObjectStates.IsValidIndex(ObjectIndex)))
    {
        PerObjectStates[ObjectIndex].MarkPropertyDirty(static_cast(RepIndex));
        FNetPushModelDelegate::OnMarkPropertyDirty.Broadcast(ObjectIndex);
    }
}

void MarkPropertyDirty(const FNetLegacyPushObjectId ObjectId, const int32 StartRepIndex, const int32 EndRepIndex)
{
    const int32 ObjectIndex = ObjectId;
    if (LIKELY(PerObjectStates.IsValidIndex(ObjectIndex)))
    {
        FPushModelPerObjectState& ObjectState = PerObjectStates[ObjectIndex];
        for (int32 RepIndex = StartRepIndex; RepIndex <= EndRepIndex; ++RepIndex)
        {
            ObjectState.MarkPropertyDirty(static_cast(RepIndex));
            FNetPushModelDelegate::OnMarkPropertyDirty.Broadcast(ObjectIndex);
        }
    }
}

Connection

对于每个 Actor，维护一份 Data，其中维护对其可见的 Connection；

显然可以在 AActor::ReplicateSubobjects 时，将 Connection 加入存储列表；

在 RemoveClientConnection 时，将 Connection 从所有的 Actor 的 Data 中移除；

DirtyComponents

在每次收到 FNetPushModelDelegate::OnMarkPropertyDirty 时，记录该 Subobject 到其 Parent 维护的 DirtyComponents 数据中；

同时，当 ActorComponent 进行 Register、Unregister 时，也需要将其加入 DirtyComponents；

特别地，为了考虑丢包的情况，判断取出 FSendingRepState* SendingRepState = Channel->ActorReplicator->RepState->GetSendingRepState()，然后判定 SendingRepState->NumNaks > 0 时（即存在丢包时），将所有数据重新传一遍（即所有的 ReplicatedComponents 都加入 DirtyComponents）；

每次 ReplicateSubobjects 后，清空 DirtyComponents；

这样就可以保证 DirtyComponents 的个数限制，未 MarkDirty 的不参与 Replicate；

[UE]《极品飞车：集结》

2024-07-10T16:00:00.000Z

《极品飞车：集结》

Intro

“SPEED IT UP, RACE TO THE TOP.”

Gameplay & AI.
MostWanted & CaptureTheFlag

22.03.17 - 24.07.11

Download

MostWanted

热力追踪

CaptureTheFlag

夺旗

Dev Part

负责的模块

[UE]Command解决方案

2024-06-24T16:00:00.000Z

Command解决方案

基本的命令框架，由 Command、CommandHistory、CommandManager 组成；

Command

classDiagramdirection LRclass TCommand {CommandType : TCommandTypeCommandParams : FCommonVariantParamsCommandTargets : TArray~TStrongObjectPtr[UObject]~}TCommand<|--FCommandclass FCommandFCommand*--ECommandTypeclass ECommandTypeFCommandWrapper*--FCommandclass FCommandWrapper {Command : const FCommand *}

TCommand ：维护 Command，其中 CommandType 表示该 Command 的类型，该类型与具体业务相关；CommandParams、CommandTargets 用于记录 Command 的参数，Params 记录基础类型、Targets 记录相关 UObject 指针；

FCommand：针对特殊的 CommandType : ECommandType 的 Command 特化；

FCommandWrapper：对 FCommand 的一个封装，可用于打包数据到 lua；

// Command

template<typename TCommandType>
struct TCommand
{
static_assert(TIsEnumClass::Value, "TCommandType must be a enum type");

TCommand() = default;
TCommand(TCommandType Type, const FCommonVariantParams& Params = {}) : CommandCategory(Category), CommandType(Type), CommandParams(Params) {}
TCommand(TCommandType Type, TStrongObjectPtr Target, const FCommonVariantParams& Params = {}) : CommandCategory(Category), CommandType(Type), CommandParams(Params), CommandTargets({ Target }) {}
TCommand(TCommandType Type, const TArray>& Targets, const FCommonVariantParams& Params = {}) : CommandCategory(Category), CommandType(Type), CommandParams(Params), CommandTargets(Targets) {}

void Clear();

TCommandType GetType() const { return CommandType; }
const FCommonVariantParams& GetParams() const { return CommandParams; }
const TArray>& GetTargets() const { return CommandTargets; }
bool IsValid() const { return CommandType != TCommandType::None; }

void MarkInvalid() const { CommandType = TCommandType::None; }

FString ToString() const;

private:
mutable TCommandType CommandType = TCommandType::None;
FCommonVariantParams CommandParams {};
TArray> CommandTargets{};
};

template<typename TCommandType>
void TCommand::Clear()
{
CommandType = TCommandType::None;
CommandParams = {};
CommandTargets.Empty();
}

// FCommand

UENUM()
enum class ECommandType
{
    None = 0,

    Test_1,
    Test_2,
}

struct FCommand : TCommand 
{
    using Super = TCommand;
    using Super::Super;
};

// FCommandWrapper

USTRUCT(BlueprintType)
struct FCommandWrapper
{
    GENERATED_BODY()

    void BindCommand(const FCommand* InCommand) { Command = InCommand; }

    uint32 GetType() { return (uint32)Command->GetType(); }
    const FCommonVariantParams& GetParams() { return Command->GetParams(); }
    TArray GetTargets();
    bool IsValid() { return Command->IsValid(); }
void MarkInvalid() { Command->MarkInvalid(); }
    FString ToString() { return Command->ToString(); }

private:
    const FCommand* Command = nullptr;
};


TArray FCommandWrapper::GetTargets()
{
TArray Res{};

Algo::Transform(Command->GetTargets(), Res, [](const auto& Value) { return Value.Get(); });

return Res;
}


BEGIN_EXPORT_REFLECTED_CLASS(FCommandWrapper)
    ADD_FUNCTION(GetType)
    ADD_FUNCTION(GetParams)
    ADD_FUNCTION(GetTargets)
    ADD_FUNCTION(IsValid)
    ADD_FUNCTION(MarkInvalid)
    ADD_FUNCTION(ToString)
END_EXPORT_CLASS()
IMPLEMENT_EXPORTED_CLASS(FCommandWrapper)

CommandHistory

classDiagramdirection LRclass TCommandHistory {MaxHistoryCount : int32CurrIndex : int32TailIndex : int32CurrHistoryCount : int32UndoCommandCount : int32CommandHistory : TArray~TUniquePtr[TCommand]~OnProcessCommand : TOnProcessCommandDelegateExecuteCommand(Command, Type)Record(Command)Undo()Redo()}TCommandHistory<--ECommandOperationTypeTCommandHistory<|--FCommandHistoryFCommandHistory*--FOnProcessCommandInternalFCommandHistory*--FCommand

TCommandHistory：用于记录 Command 序列集合，ExecuteCommand 的 Record、Undo、Redo 等；

FCommandHistory：TCommandHistory 针对 TCommand、TOnProcessCommandDelegate 的特化；

通过 OnProcessCommandDelegate 来通知与分发 Command 的执行，其中 OperationType 与业务无关，主要有：

Record：记录新的 Command；
Undo：回退 Command；
Redo：重做 Command；
Discard：在 Truncate 截断 CommandList（回退后有新 Command ）时，丢弃之前回退的 Command；

// Operation

UENUM()
enum class ECommandOperationType : uint8
{
BeforeRecord, // 在命令记录到历史队列前，用于标记命令是否需要进入历史队列
Record,       // 记录命令

BeforeUndo,   // 回退前
Undo,         // 回退
AfterUndo,    // 回退后

BeforeRedo,   // 重做前
Redo,         // 重做
AfterRedo,    // 重做后

Discard,      // 回退之后有新的命令，丢弃已回退的命令
Overwrite,    // 历史队列已满，覆盖最旧的命令
Clear,        // 历史队列清空
};

// TCommandHistory

template<typename TCommand, typename TOnProcessCommandDelegate>
struct TCommandHistory
{
static_assert(TIsSamevoid(const TCommand&, ECommandOperationType)>>::Value, "TOnProcessCommandDelegate must be a TDelegate");

void Init(int32 InMaxHistoryCount);
void Clear();
void Destroy();

void Record(TUniquePtr Command);
void Undo(int32 StepCount);
void Redo(int32 StepCount);
void Truncate();

TOnProcessCommandDelegate OnProcessCommand;

int32 GetCurrHistoryCount() const { return CurrHistoryCount; }
int32 GetTotalHistoryCount() const { return CurrHistoryCount + UndoCommandCount; }

FString ToString() const;

private:
int32 CalcIndex(int32 Val) const;
void ExecuteCommand(int32 Index, ECommandOperationType OperationType);
void ExecuteCommand(const TCommand* Command, ECommandOperationType OperationType);

private:
int32 MaxHistoryCount = -1;

TArray> CommandHistory{};

int32 CurrIndex = -1;
int32 TailIndex = -1;

int32 CurrHistoryCount = 0;
int32 UndoCommandCount = 0;
};

// -----

// TCommandHistory Implementation

template<typename TCommand, typename TOnProcessCommandDelegate>
void TCommandHistory::Init(int32 InMaxHistoryCount)
{
MaxHistoryCount = InMaxHistoryCount;
}

template<typename TCommand, typename TOnProcessCommandDelegate>
void TCommandHistory::Clear()
{
Truncate();

for (auto i = 0; i < CurrHistoryCount; i++)
{
auto Index = CalcIndex(i);
if (CommandHistory.IsValidIndex(Index) && CommandHistory[Index])
{
ExecuteCommand(Index, ECommandOperationType::Clear);
CommandHistory[Index]->Clear();
}
}

CommandHistory.Empty();

CurrIndex = -1;
TailIndex = -1;
CurrHistoryCount = 0;
UndoCommandCount = 0;
}

template<typename TCommand, typename TOnProcessCommandDelegate>
void TCommandHistory::Destroy()
{
Clear();
OnProcessCommand.Unbind();
}

template<typename TCommand, typename TOnProcessCommandDelegate>
void TCommandHistory::Record(TUniquePtr Command)
{
if (MaxHistoryCount == 0)
return;

if (!Command) return;

ExecuteCommand(Command.Get(), ECommandOperationType::BeforeRecord);

// 无效命令不进入队列
if (!Command->IsValid())
{
return;
}

Truncate();

auto Index = CalcIndex(CurrIndex + 1);
if (!CommandHistory.IsValidIndex(Index))
{
CommandHistory.Add(MoveTemp(Command));
}
else
{
if (CommandHistory[Index] && CommandHistory[Index]->IsValid())
{
ExecuteCommand(Index, ECommandOperationType::Overwrite);
}
CommandHistory[Index] = MoveTemp(Command);
}

CurrIndex = TailIndex = Index;
if (MaxHistoryCount > 0)
{
CurrHistoryCount = FMath::Min(CurrHistoryCount + 1, MaxHistoryCount);
}
else
{
CurrHistoryCount++;
}

ExecuteCommand(Index, ECommandOperationType::Record);
}

template<typename TCommand, typename TOnProcessCommandDelegate>
void TCommandHistory::Undo(int32 StepCount)
{
StepCount = FMath::Clamp(StepCount, 0, CurrHistoryCount);
if (StepCount == 0) return;

auto LastCurrIndex = CurrIndex;
CurrIndex = CalcIndex(LastCurrIndex - StepCount);
UndoCommandCount += StepCount;
CurrHistoryCount -= StepCount;

for (auto i = 0; i < StepCount; i++)
{
auto Index = CalcIndex(LastCurrIndex - i);
if (CommandHistory.IsValidIndex(Index) && CommandHistory[Index])
{
ExecuteCommand(Index, ECommandOperationType::BeforeUndo);
ExecuteCommand(Index, ECommandOperationType::Undo);
ExecuteCommand(Index, ECommandOperationType::AfterUndo);
}
}
}

template<typename TCommand, typename TOnProcessCommandDelegate>
void TCommandHistory::Redo(int32 StepCount)
{
StepCount = FMath::Clamp(StepCount, 0, UndoCommandCount);
if (StepCount == 0) return;

auto LastCurrIndex = CurrIndex;
CurrIndex = CalcIndex(LastCurrIndex + StepCount);
UndoCommandCount -= StepCount;
CurrHistoryCount += StepCount;

for (auto i = 1; i <= StepCount; i++)
{
auto Index = CalcIndex(LastCurrIndex + i);
if (CommandHistory.IsValidIndex(Index) && CommandHistory[Index])
{
ExecuteCommand(Index, ECommandOperationType::BeforeRedo);
ExecuteCommand(Index, ECommandOperationType::Redo);
ExecuteCommand(Index, ECommandOperationType::AfterRedo);
}
}
}

template<typename TCommand, typename TOnProcessCommandDelegate>
void TCommandHistory::Truncate()
{
auto Count = UndoCommandCount;
if (Count == 0) return;

TailIndex = CurrIndex;
UndoCommandCount = 0;

for (auto i = 1; i <= Count; i++)
{
auto Index = CalcIndex(CurrIndex + i);
if (CommandHistory.IsValidIndex(Index) && CommandHistory[Index])
{
ExecuteCommand(Index, ECommandOperationType::Discard);
CommandHistory[Index]->Clear();
}
}
}

template<typename TCommand, typename TOnProcessCommandDelegate>
int32 TCommandHistory::CalcIndex(int32 Val) const
{
if (MaxHistoryCount <= 0)
return Val;

auto Res = Val % MaxHistoryCount;
if (Res < 0)
{
Res += MaxHistoryCount;
}
    
return Res;
}

template<typename TCommand, typename TOnProcessCommandDelegate>
void TCommandHistory::ExecuteCommand(int32 Index, ECommandOperationType OperationType)
{
    if (0 <= Index && Index < CommandHistory.Num())
    {
OnProcessCommand.ExecuteIfBound(*CommandHistory[Index].Get(), OperationType);
    }
}


template<typename TCommand, typename TOnProcessCommandDelegate>
void TCommandHistory::ExecuteCommand(const TCommand* Command, ECommandOperationType OperationType)
{
OnProcessCommand.ExecuteIfBound(*Command, OperationType);
}

// TestCommandHistory

DECLARE_DELEGATE_TwoParams(FOnProcessCommandInternal, const FCommand& /*Command*/, ECommandOperationType /*OperationType*/);

struct FCommandHistory : TCommandHistory {};

CommandManager

classDiagramdirection LRCommandUtils-->CommandManagerclass CommandManager {ProcessCommandEvents : TMap~ECommandType, FOnProcessCommand~ChangeCurrCommandHistoryType(CommandHistoryType)RegisterProcessCommandEventListener(CommandType, Object, Callback)UnregisterProcessCommandEventListener(CommandType, Object)DispatchProcessCommandEvent(Command, OperationType)DispatchProcessCommandEventToLua(CommandWrapper, OperationType)}CommandManager*--ECommandHistoryType

CommandManager：

主要是为了维护多个 CommandHistory（可能有多个业务各自相关的 CommandHistory），进行相关的初始化；

通过 ChangeCurrCommandHistoryType 来切换当前执行的 Command 所属的 CommandHistoryType；有些 Command 在多个 CommandHistoryType 的情景下都会有（比如当前切到一个新的 Editor，但是 PropertyCommand 通用模块在任意一个 Editor 都会使用到），所以不选择执行 Command 时指定 CommandHistoryType 的方案，选择主动切换；业务可以根据自己的情况选择维护数据结构来管理 CommandHistoryType 的切换；

提供对应 Event 的注册与分发、提供 Record、Undo 等接口给 CommandUtils 调用（期望外部仅调用 CommandUtils 相关方法），同时进行一些 CommonCommandType 的注册以及与 lua 的通信；

// CommandManager

void UCommandManager::InitCommandHistoryMap()
{
for (auto Type : TEnumRange())
{
auto CommandHistory = MakeShared();
CommandHistory->Init(MAX_HISTORY_COUNT);
CommandHistory->OnProcessCommand.BindUObject(this, &UCommandManager::DispatchProcessCommandEvent);

CommandHistoryMap.Add(Type, CommandHistory);
}
CurrCommandHistoryType = ECommandHistoryType::None;
}

void UCommandManager::ChangeCurrCommandHistoryType(ECommandHistoryType Type)
{
CurrCommandHistoryType = Type;
}

TSharedPtr UCommandManager::GetCurrCommandHistory() const
{
if (auto CommandHistoryPtr = CommandHistoryMap.Find(CurrCommandHistoryType))
{
return *CommandHistoryPtr;
}
return nullptr;
}

// ------------

void UCommandManager::DispatchProcessCommandEvent(const FCommand& Command, ECommandOperationType OperationType)
{
auto Type = Command.GetType();

if (auto EventPtr = ProcessCommandEvents.Find(Type))
{
EventPtr->Broadcast(Command, OperationType);
}

FCommandWrapper CommandWrapper{};
CommandWrapper.BindCommand(&Command);
DispatchProcessCommandEventToLua(CommandWrapper, OperationType);
}

// ------------

template <typename UserClass>
bool UCommandManager::RegisterProcessCommandEventListener(ECommandType Type, UserClass* InUserObject, typename TMemFunPtrType::Value, UserClass, FOnProcessCommandCallbackType>::Type InFunc)
{
    if (!ProcessCommandEvents.Contains(Type))
    {
        ProcessCommandEvents.Add(Type, {});
    }

    auto& Event = ProcessCommandEvents[Type];

    if (Event.IsBoundToObject(InUserObject))
    {
        return false;
    }

    Event.AddUObject(InUserObject, InFunc);
    return true;
}

template <typename UserClass>
bool UCommandManager::UnregisterProcessCommandEventListener(ECommandType Type, UserClass* InUserObject)
{
    if (!ProcessCommandEvents.Contains(Type))
    {
        return false;
    }

    auto& Event = ProcessCommandEvents[Type];
    Event.RemoveAll(InUserObject);
    return true;
}

[UE]InputSystem基础框架

2024-06-17T16:00:00.000Z

InputSystem基础框架

Key

flowchart LRInput(PlayerController::UpdateInput)Input-->InputProcesssor::TickInput-->InputHandle::TickInput-->InputCollector::Tick

InputProcessor

对于 InputProcessor，进行按键的原始输入处理，调用 InputKey 将将数据传递到 InputCollector，继续后续的操作；

通过监听引擎原始的按键数据 APlayerController::IsInputKeyDown(const FKey Key)；
允许外部调用输入，执行 InputKey （比如某个 UI 点击触发输入）；

特别地，在 Tick 中进行原始数据处理；

由于一般按键输入支持 Ctrl / Shit / Alt / Cmd + Key，需要对这种情况适配，同时防止按键冲突：对于KeySetting(KeyType - 具体按键配置映射) 额外维护 bCtrl (需要与 ctrl 组合)、MustNoCtrl (需要不按下 Ctrl)；

// InputProcessor

void UInputProcessor::ProcessInputKey() // Tick
{
    bool bShift = PC->IsInputKeyDown(EKeys::LeftShift) || PC->IsInputKeyDown(EKeys::RightShift);
    bool bCtrl = PC->IsInputKeyDown(EKeys::LeftControl) || PC->IsInputKeyDown(EKeys::RightControl);
    bool bAlt = PC->IsInputKeyDown(EKeys::LeftAlt) || PC->IsInputKeyDown(EKeys::RightAlt);
    bool bCmd = PC->IsInputKeyDown(EKeys::LeftCommand) || PC->IsInputKeyDown(EKeys::RightCommand);
    
    auto IsKeyDown = [&](EInputKeyType KeyType) -> bool
    {
         for (auto KeySetting : KeySettings[KeyType]) // 一个 KeyType 可能有多种触发方式
        {
            bool bKeyDown = PC->IsInputKeyDown(FKey(FName(KeySetting.KeyName())));

            if ((KeySetting.Shift() && !bShift) || (KeySetting.MustNoShift() && bShift))
                bKeyDown = false;
            else if ((KeySetting.Ctrl() && !bCtrl) || (KeySetting.MustNoCtrl() && bCtrl))
                bKeyDown = false;
            else if ((KeySetting.Alt() && !bAlt) || (KeySetting.MustNoAlt() && bAlt))
                bKeyDown = false;
            else if ((KeySetting.Cmd() && !bCmd) || (KeySetting.MustNoCmd() && bCmd))
                bKeyDown = false;

            if (bKeyDown)
                return true;
        }
        
        return false;
    };

    for (auto KeyType : KeyTypes)
    {
        if (IsKeyDown(KeyType))
        {
            InputKey(KeyType);
        }
    }
}

// ----------

void UInputProcessor::InputKey(EInputKeyType KeyType)
{
    if (!IsValid(InputCollector)) return;
    InputCollector->SetKey(KeyType, true);
}

InputCollector

classDiagramdirection LRInputCollector --> FInputKeyInfoclass InputCollector {KeyInfoMap: TMap~KeyType, FInputKeyInfo~}FInputKeyInfo *-- EKeyStateclass FInputKeyInfo {bEnable : boolbPressed : boolKeyState : EKeyState}class EKeyState {IKS_Idle : 未按下IKS_Press : 当帧按下IKS_Release : 当帧释放IKS_Holding : 持续按下}

对于 InputCollector，维护 Key - Press 相关的原始输入数据，将数据从 Press 加工到 KeyState，并每帧检测是否未按下，这样外部只需要进行 Press，而不需要 Release；有几个主要的功能：

提供 SetKey 进行按键设置，提供 GetKey 查询按键状态；
维护每个 Key 的 KeyInfo，数据用于后续处理；
提供 EnableKey，设置按键是否可以输入（Disable 时需要取消输入）；

// InputKeyInfo

USTRUCT(BlueprintType)
struct FInputKeyInfo
{
    GENERATED_BODY()

    UPROPERTY()
    bool bPressed = false;

    UPROPERTY()
    EInputKeyState KeyState = IKS_Idle;
    
    UPROPERTY()
    bool bEnable = true;

    // 用于记录该帧内是否已经处理过按键
    bool bProcessedThisFrame = false;
};

// InputCollector

void UInputCollector::SetKey(EInputKeyType KeyType, bool bPressed, bool bForce)
{
    if (bForce || IsEnableKey(KeyType))
    {
        SetKey_Internal(KeyType, bPressed);
    }
}

FInputKeyInfo UInputCollector::GetKeyInfo(EInputKeyType KeyType)
{
    return KeyInfoMap.Contains(KeyType) ? KeyInfoMap[KeyType] : {};
}

// ----- Internal -----
void UInputCollector::Tick()
{
    // 每次 Tick 进行按键信息重置
    for (auto KeyType : KeyTypes)
    {
        FInputKeyInfo& KeyInfo = KeyInfoMap[KeyType];
        if (!KeyInfo.bProcessedThisFrame)
        {
            SetKey_Internal(KeyType, false);
           KeyInfo.bProcessedThisFrame = false;
        }
    }
}   

void UInputCollector::SetKey_Internal(EInputKeyType KeyType, bool bPressed)
{
    FInputKeyInfo& KeyInfo = KeyInfoMap[KeyType];

    if (bPressed == KeyInfo.bPressed)
    {
        KeyInfo.KeyState = bPressed ? IKS_Holding : IKS_Idle;
    }
    else
    {
        KeyInfo.KeyState = bPressed ? IKS_Press : IKS_Release;
    }

    KeyInfo.bPressed = bPressed;
    KeyInfo.bProcessedThisFrame = true;
}

InputHandle

classDiagramclass InputHandleBase {KeyInfo : TArray~EInputKeyType~SetInput(KeyType, bPressed)CollectInput()ProcessInput()NotifyInput()}InputHandleBase <|-- InputHandld_DefaultInputHandleBase <|-- InputHandle_CharacterInputHandleBase <|-- InputHandle_Vehicle

业务自定义逻辑的位置，一般仅对业务开放这部分的代码修改；

根据不同的输入模式，创建不同的 InputHandle，在这里对输入进行业务级别的加工，同时处理基本的输入操作回调（内部基本的业务逻辑，以及允许其它模块向内部注册的事件），并将输入操作通知给其它模块；

业务自定义其输入逻辑，比如：

该输入模式下，当输入某个操作时，系统自动取消其它操作的输入等；
处理按键是否需要自动抬起；

// InputHandle

void UInputHandleBase::Tick()
{
    RecordInput();   // 记录上次输入结果
    CollectInput();  // 收集本帧输入结果（先默认清空，后根据具体情况收集）
    ProcessInput();  // 根据输入结果修改 KeyState
    DispatchInput(); // 分发输入结果并处理
}


// ----- Process -----

void UInputHandleBase::ProcessInput()
{
    for (auto Key : ActiveKeyTypes)
    {
        bool bLastKeyDown = RecordKeyInfoMap[Key].bPressed;
        bool bCurrentKeyDown = KeyInfoMap[Key].bPressed;
        
        if (bCurrentKeyDown != bLastKeyDown)
        {
            bCurrentKeyDown ? OnGameKeyPress(Key) : OnGameKeyRelease(Key);
        }
        else
        {
            bCurrentKeyDown ? OnGameKeyHolding(Key) : OnGameKeyIdle(Key);
        }
    }
}


// ----- Register -----

DECLARE_MULTICAST_DELEGATE_TwoParams(FInputEvent, KeyType, KeyState);
using FInputEventCallbackParamTypes = FInputEventCallbackType::FDelegate::TFuncType;

TMap  ProcessInputEvents;

template <
typename UserClass,
typename FuncType = TMemFunPtrType::Value, UserClass, FInputEventCallbackParamTypes>::Type
>
bool UInputHandleBase::RegisterInputEvent(EInputKeyType KeyType, UserClass* InUserObject, FuncType InFunc)
{
    if (!ProcessInputEvents.Contains(KeyType))
        ProcessInputEvents.Add(KeyType, {});

    auto& Event = Processvents[KeyType];
    if (Event.IsBoundToObject(InUserObject))
    {
        return false;
    }

    Event.AddUObject(InObject, InFunc);
    return true;
}

template <typename UserClass>
bool UnregisterInputEvent(EInputKeyType Type, UserClass* InUserObject)
{
    if (!ProcessInputEvents.Contains(Type))
        return false;

    auto& Event = ProcessInputEvents[Type];
    Event.RemoveAll(InUserObject);
    return true;
}
                                
void UInputHandleBase::DispatchInput()
{
    // 内部处理基础操作
    // ...
        
    // 执行外部注册的操作
    for (auto KeyType : ActiveKeyTypes)
    {
        if (auto EventPtr = ProcessInputEvents.Find(KeyType))
        {
            EventPtr->Broadcast(KeyType, GetKeyState(KeyType));
        }
    }
}

// ----- Helper -----

void UInputHandleBase::SetInput(EKeyType KeyType)
{
    KeyInfo[KeyType].bPressed = true;
}

void UInputHandleBase::UpdateKeyFromCollector(EInputKeyType KeyType) // 在 CollectInput 中调用
{
    SetInput(KeyType, InputCollector->GetKeyInfo(KeyType).bPressed);
}

Mouse

InputProcessor

Interface : IInputProcessor 由 FSlateApplication 驱动，也有 Key、Mouse 相关操作的回调：

flowchart LRFSlateApplication::ProcessMouseButtonDownEvent-->FSlateApplication::InputPreProcessorsHelper::HandleMouseButtonDownEvent

// IInputProcessor

class SLATE_API IInputProcessor
{
public:
IInputProcessor(){};
virtual ~IInputProcessor(){}

virtual void Tick(const float DeltaTime, FSlateApplication& SlateApp, TSharedRef Cursor) = 0;

    // Key...
virtual bool HandleKeyDownEvent(FSlateApplication& SlateApp, const FKeyEvent& InKeyEvent) { return false; }
virtual bool HandleKeyUpEvent(FSlateApplication& SlateApp, const FKeyEvent& InKeyEvent) { return false; }
virtual bool HandleAnalogInputEvent(FSlateApplication& SlateApp, const FAnalogInputEvent& InAnalogInputEvent) { return false; }

    // Mouse...
virtual bool HandleMouseMoveEvent(FSlateApplication& SlateApp, const FPointerEvent& MouseEvent) { return false; }
virtual bool HandleMouseButtonDownEvent( FSlateApplication& SlateApp, const FPointerEvent& MouseEvent) { return false; }
virtual bool HandleMouseButtonUpEvent( FSlateApplication& SlateApp, const FPointerEvent& MouseEvent) { return false; }
virtual bool HandleMouseButtonDoubleClickEvent(FSlateApplication& SlateApp, const FPointerEvent& MouseEvent) { return false; }
virtual bool HandleMouseWheelOrGestureEvent(FSlateApplication& SlateApp, const FPointerEvent& InWheelEvent, const FPointerEvent* InGestureEvent) { return false; }
virtual bool HandleMotionDetectedEvent(FSlateApplication& SlateApp, const FMotionEvent& MotionEvent) { return false; };

/** Debug name for logging purposes */
virtual const TCHAR* GetDebugName() const { return TEXT(""); }
};

可以在合适的地方（比如 InputSubSystem / InputManager ）进行创建：

1 2	InputProcessor = MakeShareable(new FInputProcessor()); FSlateApplication::Get().RegisterInputPreProcessor(InputProcessor);

其次是与 UI 的交互， UserWidget 中也提供了 Mouse 的回调：

virtual FReply NativeOnTouchStarted(const FGeometry& InGeometry, const FPointerEvent& InGestureEvent) override;
virtual FReply NativeOnTouchMoved(const FGeometry& InGeometry, const FPointerEvent& InGestureEvent) override;
virtual FReply NativeOnTouchEnded(const FGeometry& InGeometry, const FPointerEvent& InGestureEvent) override;
virtual FReply NativeOnMouseWheel(const FGeometry& InGeometry, const FPointerEvent& InMouseEvent) override;

可以将接口收束在一个 InputManager 中，向外暴露相关事件；

DragDrop

DragArea 用于维护可拖动的范围，以及封装引擎基本接口、提供注册方法：

-- DragArea

--region ----- Events -----

function DragAreaView:OnMouseButtonDown(Geometry, MouseEvent)
return UE.UWidgetBlueprintLibrary.DetectDragIfPressed(MouseEvent, self, "LeftMouseButton")
end

-- 开始拖动
function DragAreaView:OnDragDetected(Geometry, PointerEvent)
local OperationClass = self.DragDropOperationClass
local Operation = NewObject(OperationClass)

if self.DragDetectedDelegate ~= nil then
for Object, Callback in pairs(self.DragDetectedDelegate) do
xpcall(Callback, error_handler, Object, Geometry, PointerEvent, Operation)
end
end

return Operation
end

-- 取消拖动
function DragAreaView:OnDragCancelled(Geometry, PointerEvent, Operation)
if self.DragCancelledDelegate ~= nil then
for Object, Callback in pairs(self.DragCancelledDelegate) do
xpcall(Event, error_handler, Object, Geometry, PointerEvent, Operation)
end
end
end

-- Other...

--endregion Events

--reigon ----- Bind -----
function DragAreaView:BindEvent(EventName, Object, Callback)
    if self[EventName] == nil then self[EventName] = {} end

    if self[EventName][Object] == nil then
        self[EventName][Object] = Callback
    end
end

function DragAreaView:UnbindEvent(EventName, Object)
    if self[EventName] == nil then self[EventName] = {} end

    if self[EventName][Object] ~= nil then
        self[EventName][Object] = nil
    end
end

function DragAreaView:BindDragDetected(Object,Func) self:BindEvent("DragDetectedDelegate", Object, Func) end
function DragAreaView:UnbindDragDetected(Object) self:UnbindEvent("DragDetectedDelegate", Object) end

function DragAreaView:BindDragCancelled(Object,Func) self:BindEvent("DragCancelledDelegate", Object, Func) end
function DragAreaView:UnbindDragCancelled(Object) self:UnbindEvent("DragCancelledDelegate", Object) end

--endregion Bind

DragItem 用于维护拖动的实际 Item；

PreviewItem 用于维护拖动时的 Preview（也就是拖动时显示的 Item 预览）；

-- DragItem

function DragItemView:Construct()
self.DragArea:BindDragDetected(self, self.OnDragDetectedCallback)
self.DragArea:BindDragCancelled(self, self.OnDragCancelledCallback)
end

function DragItemView:Destruct()
self.DragArea:UnbindDragDetected(self)
self.DragArea:UnbindDragCancelled(self)
end

--
function DragItemView:OnDragDetectedCallback(Geometry,PointerEvent,Operation)

local BPClass = UE.UGameplayStatics.GetObjectClass(self)
Operation.PreviewItem = UE.UCommonWidgetUtils.CreateWidget(BPClass)

Operation.DefaultDragVisual = Operation.PreviewItem
if Operation.PreviewItem and Operation.PreviewItem.OnDragDetected then
Operation.PreviewItem:OnDragDetected()
end

Operation.Pivot = UE.EDragPivot.TopLeft

local LocalPosition = UE.USlateBlueprintLibrary.AbsoluteToLocal(self:GetCachedGeometry(), UE.UKismetInputLibrary.PointerEvent_GetScreenSpacePosition(PointerEvent))

local Offset = UE.FVector2D()
local Size = UE.USlateBlueprintLibrary.GetLocalSize(self:GetCachedGeometry())
Offset.X = LocalPosition.X / Size.X * -1
Offset.Y = LocalPosition.Y / Size.Y * -1
Operation.Offset = Offset

Operation.UseInAnimation = false
end

function DragItemView:OnDragCancelledCallback(Geometry, PointerEvent, Operation)

if Operation.PreviewItem and Operation.PreviewItem.OnDragCancelled then
Operation.PreviewItem:OnDragCancelled()
end

UE.UCommonWidgetUtils.DestroyWidget(Operation.PreviewItem)
end

// CommonWidgetUtils

UUserWidget* UCommonWidgetUtils::CreateWidget(UWorld* InWorld, TSubclassOf WidgetType)
{
UUserWidget* Widget = UWidgetBlueprintLibrary::Create(InWorld, WidgetType, nullptr);
AddObjectRef(Widget);
return Widget;
}

void UCommonWidgetUtils::DestroyWidget(UUserWidget* Widget)
{
RemoveObjectRef(Widget);
}

// --------------

void UCommonWidgetUtils::AddObjectRef(UObject* Object)
{
if (Object && IsUObjectValid(Object))
{
const auto L = UnLua::GetState();
auto& Env = UnLua::FLuaEnv::FindEnvChecked(L);
Env.AddManualObjectReference(Object);
}
}

void UCommonWidgetUtils::RemoveObjectRef(UObject* Object)
{
if (Object && IsUObjectValid(Object))
{
const auto L = UnLua::GetState();
auto& Env = UnLua::FLuaEnv::FindEnvChecked(L);
Env.RemoveManualObjectReference(Object);
}
}

特别地：

通过 Operation 的 DefaultDragVisual 来设置拖动时的预览 Widget，在 FUMGDragDropOp::New 时，将其设置到 Operation->DecoratorWidget，并在 FUMGDragDropOp::OnDragged 时更新 Position；
CreateWidget / DestroyWidget 针对 PreviewItem，这里可以额外维护一个 Pool 进行 Widget 复用；
在合适的地方增加额外 Callback；

Touch

引擎对于 Touch 的相关实现主要在：UPlayerInput::InputTouch(uint32 Handle, ETouchType::Type Type, const FVector2D& TouchLocation, float Force, FDateTime DeviceTimestamp, uint32 TouchpadIndex) 中；

实际上，可以根据 IInputProcessor 提供的接口，在 InputManager 中维护 TArray InputTouchDatas 以及相关信息，统一管理并分发给各个业务模块，同时方便自定义与扩展。

// InputTouchData
struct FInputTouchData
{
ETouchIndex::Type TouchIndex;
FVector2D StartLocation;
FVector2D Location;
FVector2D DeltaMove;
float BeginTime;
float UpdateTime;
float DeltaTime;
float ForceValue;
bool bPendingKill;
    
    // ....
}

需要和引擎一样维护所有的 TouchData，这样才可以通过 TouchIndex 与其它的接口关联，对应到其它回调的 PointerEvent 中的 (ETouchIndex::Type)PointerEvent.GetPointerIndex()；

// InputProcessor

class FInputProcessor
{
    // ...
    TArray  InputTouchDatas;
}
    
FInputTouchData FInputProcessor::GetInputTouchData(ETouchIndex::Type TouchIndex)
{
    FInputTouchData* DataPtr = InputTouchDatas.FindByKey(TouchIndex);
    return DataPtr != nullptr ? *DataPtr : {};
}

// ----- Process -----

void FInputProcessor::ProcessMouseEvent(ETouchType TouchType, const FPointerEvent& MouseEvent)
{
    FVector2D OutPixelPosition = FVector2D::ZeroVector;
    FVector2D OutViewportPosition = FVector2D::ZeroVector;
    USlateBlueprintLibrary::AbsoluteToViewport(GetWorld(), MouseEvent.GetScreenSpacePosition(), OutPixelPosition, OutViewportPosition);

    InputTouch(MouseEvent.GetPointerIndex(), TouchType, OutPixelPosition, MouseEvent.GetTouchForce());
}

bool FInputProcessor::HandleMouseButtonDownEvent(FSlateApplication& SlateApp, const FPointerEvent& MouseEvent)
{
    ProcessMouseEvent(ETouchType::Began, MouseEvent);
    // BrodcastEvents..
    return true;
}

bool FInputProcessor::HandleMouseMoveEvent(FSlateApplication& SlateApp, const FPointerEvent& MouseEvent)
{
    ProcessMouseEvent(ETouchType::Moved, MouseEvent);
    // BrodcastEvents..
    return true;
}

bool FInputProcessor::HandleMouseButtonUpEvent(FSlateApplication& SlateApp, const FPointerEvent& MouseEvent)
{
    ProcessMouseEvent(ETouchType::Ended, MouseEvent);
    // BrodcastEvents..
    
    // Clear PendingKill Datas
    for (int Index = InputTouchDatas.Num() - 1; Index >= 0; Index--)
    {
        if (InputTouchDatas[Index].bPendingKill == true)
        {
            InputTouchDatas.RemoveAt(Index);
        }
    }
    return true;
}

// InputProcessor

void FInputProcessor::InputTouch(uint32 Handle, ETouchType::Type Type, const FVector2D& TouchLocation, float Force)
{
    FVector Location(TouchLocation, Force);

    switch (Type)
    {
    case ETouchType::Began:
        BeginTouch((ETouchIndex::Type)Handle, Location);
        break;
    case ETouchType::Ended:
        EndTouch((ETouchIndex::Type)Handle, Location);
        break;
    default:
        MoveTouch((ETouchIndex::Type)Handle, Location);
        break;
    }
}

// -----
void FInputProcessor::BeginTouch(const ETouchIndex::Type TouchIndex, const FVector Location)
{
    FInputTouchData* DataPtr = InputTouchDatas.FindByKey(TouchIndex);
    if (DataPtr == nullptr)
    {
        InputTouchDatas.AddDefaulted(1);
        DataPtr = &InputTouchDatas.Last();
    }
    
    FInputTouchData& InputTouchData = *DataPtr;
    InputTouchData.TouchIndex = TouchIndex;
    InputTouchData.StartLocation = InputTouchData.Location = FVector2D(Location.X, Location.Y);
    InputTouchData.ForceValue = Location.Z;
    InputTouchData.BeginTime = InputTouchData.UpdateTime = GetWorld()->GetTimeSeconds();
}

void FInputProcessor::MoveTouch(const ETouchIndex::Type TouchIndex, const FVector Location)
{
    FInputTouchData* DataPtr = InputTouchDatas.FindByKey(TouchIndex);
    if (DataPtr == nullptr) return;

    FInputTouchData& InputTouchData = *DataPtr;
    FVector2D ScreenLocation = FVector2D(Location.X, Location.Y);
    InputTouchData.DeltaMove = ScreenLocation - InputTouchData.Location;
    InputTouchData.Location = ScreenLocation;
    InputTouchData.ForceValue = Location.Z;
    InputTouchData.DeltaTime = GetWorld()->GetDeltaSeconds();
    InputTouchData.UpdateTime = GetWorld()->GetTimeSeconds();
}

void FInputProcessor::EndTouch(const ETouchIndex::Type TouchIndex, const FVector Location)
{
    for (auto& InputTouchData : InputTouchDatas)
    {
        if (InputTouchData.TouchIndex == TouchIndex)
        {
            InputTouchData.bPendingKill = true;
        }
    }
}

这样就在 InputProcessor 中维护了所有的 TouchDatas，可以分发事件给外部监听，以及提供数据查询。

Gesture

根据 Touch 的信息，通过 FGestureRecognizer 维护 Gesture_Pinch、Gesture_Flick、Gesture_Rotate 等；

在 UPlayerInput::Tick 中会进行 GestureRecognizer.DetectGestures(Touches, this, DeltaTime) ：

对于 Pinch：如果 float* CurrentAlpha = CurrentGestureValues.Find(EKeys::Gesture_Pinch) 即 Pinch 还未开启，并且本次 TouchCount > 2，则认为 Pinch 刚刚开始，此时根据 CurrentPinchPoint_Start、CurrentPinchPoint_End 计算出 AnchorDistanceSq 并存储，将 1.0f 作为基础缩放值存储在 GestureValue；在下一次根据新的 NewDistanceSq / AnchorDistanceSq 作为缩放值记录在 CurrentGestureValues[EKeys::Gesture_Pinch]； TouchCount 减少到 < 2 时， Pinch 结束；
对于 Flick：要求 FlickTime < 0.25f && (FlickCurrent - AnchorPoints[0]).SizeSquared() > 10000.f，经过的时间在 0.25s 内，并且滑动一定的距离；计算和存储 Angle 于 CurrentGestureValues[EKeys::Gesture_Flick]；
对于 Rotate：如果 float* CurrentAngle = CurrentGestureValues.Find(EKeys::Gesture_Rotate) 即 Rotate 还未开启，当 TouchCount > 2 时，则认为 Rotate 刚刚开始，此时计算出 StartAngle 记录，将 0.0f 作为基础旋转值存储在 GestureValue；在后续更新 GestureValue 为 NewAngle - StartAngle，表示相对角度； TouchCount 减少到 < 2 时， Rotate 结束；

最后：

Gesture	CurrentGestureValue : Type
Pinch	Scale （相对开始的比例缩放）
Flick	Angle（本次滑动的角度）
Rotate	Angle （相对开始的角度）

bool UPlayerInput::InputGesture(const FKey Gesture, const EInputEvent Event, const float Value)
{
FKeyState& KeyState = KeyStateMap.FindOrAdd(Gesture);

KeyState.Value.X = KeyState.RawValue.X = KeyState.RawValueAccumulator.X = Value;
KeyState.EventAccumulator[Event].Add(++EventCount);

return true;
}

这些信息会存储在 KeyState 里，通过 UPlayerInput::GetKeyState(FKey InKey) 获取；

当然，在 Mouse 的回调中：

1
2
3

virtual FReply NativeOnTouchStarted(const FGeometry& InGeometry, const FPointerEvent& InGestureEvent) override;
virtual FReply NativeOnTouchMoved(const FGeometry& InGeometry, const FPointerEvent& InGestureEvent) override;
virtual FReply NativeOnTouchEnded(const FGeometry& InGeometry, const FPointerEvent& InGestureEvent) override;

可以看到这里有 GestureEvent，也可以获取对应主要信息：

FVector2D ScreenSpacePosition;
FVector2D LastScreenSpacePosition;
FVector2D CursorDelta;
const TSet* PressedButtons;
FKey EffectingButton;
uint32 PointerIndex;
uint32 TouchpadIndex;
float Force;
bool bIsTouchEvent;
EGestureEvent GestureType;
FVector2D WheelOrGestureDelta;
bool bIsDirectionInvertedFromDevice;
bool bIsTouchForceChanged;
bool bIsTouchFirstMove;

实际上，可以将这里的 GestureRecognizer 移到统一维护的 InputManager 中，将相关信息提供给各个业务查询，方便自定义与扩展：比如增加 Tag 限定提供给外部设置，当且仅当 Tag 一致时，进行对应 Gesture 更新等。

参考

UE 5.4 源码

[UE]CharacterMovement源码浅析

2024-06-09T16:00:00.000Z

CharacterMovement源码浅析

Base

classDiagramdirection LRclass UMovementComponent {UpdatedComponent : TObjectPtr~USceneComponent~ (处理空间位置)UpdatedPrimitive : TObjectPtr~UPrimitiveComponent~ (处理渲染物理)}%% -------------UMovementComponent<|--UProjectileMovementComponentclass UProjectileMovementComponent {支持发射体（子弹等）}%% -------------UMovementComponent<|--UNavMovementComponentclass UNavMovementComponent {支持 Agent 寻路NavAgentProps : FNavAgentProperties}UNavMovementComponent<|--UPawnMovementComponentclass UPawnMovementComponent {支持输入控制AddInputVector()}UPawnMovementComponent<|--UCharacterMovementComponent

Move 一般是先进行基础运动（PerformMovent），然后处理基于物理的模拟（Collision、Simulation）；

flowchart LRUCharacterMovementComponentTickComponent-->ConsumeInputVectorTickComponent-->ControlledCharacterMoveTickComponent-->Other...

ComsumeInputVector：

从 PawnOwner 取出累积的 ControlInputVector，该值监听输入并调用 Pawn::AddMovementInput 得来；

ControlledCharacterMove：

进行 Character 移动的输入处理、物理模拟、同步；

Other...

ControlledCharacterMove

void UCharacterMovementComponent::ControlledCharacterMove(const FVector& InputVector, float DeltaSeconds)
{
{
SCOPE_CYCLE_COUNTER(STAT_CharUpdateAcceleration);

// We need to check the jump state before adjusting input acceleration, to minimize latency
// and to make sure acceleration respects our potentially new falling state.
CharacterOwner->CheckJumpInput(DeltaSeconds);

// apply input to acceleration
Acceleration = ScaleInputAcceleration(ConstrainInputAcceleration(InputVector));
AnalogInputModifier = ComputeAnalogInputModifier();
}

if (CharacterOwner->GetLocalRole() == ROLE_Authority)
{
PerformMovement(DeltaSeconds);
}
else if (CharacterOwner->GetLocalRole() == ROLE_AutonomousProxy && IsNetMode(NM_Client))
{
ReplicateMoveToServer(DeltaSeconds, Acceleration);
}
}

flowchart LRControlledCharacterMove-->CheckJumpInput-.->ScaleInputAcceleration-.->ComputeAnalogInputModifierControlledCharacterMove-->|ROLE_Authority|PerformMovement-->Start(StartNewPhysics)ControlledCharacterMove-->|ROLE_AutonomousProxy & IsClient|ReplicateMoveToServerStart-->MOVE_NoneStart-->MOVE_WalkingStart-->MOVE_FallingStart-->MOVE_FlyingStart-->MOVE_SwimmingStart-->MOVE_Custom

Input

解析输入相关的数据；

CheckJumpInput：根据 bPressedJump，计算 JumpCurrentCount、JumpForceTimeRemaining；
ScaleInputAcceleration：根据玩家的输入 InputVector，计算出当前的初始加速度值；
ComputeAnalogInputModifier：模拟输入修正值，将 Acceleration /= MaxAcceleration，限制在 0-1 内；

PerfomeMovement

进行基础运动模拟，设置位移。

Kinetic : Walking

flowchart LRUCharacterMovementComponent%%-------------------------------------PerformMovement-->StartNewPhysics-->PhysWalking%%-------------------------------------PhysWalking-->GetSimulationTimeStepPhysWalking-->CalcVelocityPhysWalking-->MoveAlongFloorPhysWalking-->FindFloorPhysWalking-->CheckLedgesPhysWalking-->MaintainHorizontalGroundVelocity%%-------------------------------------MoveAlongFloor-->ComputeGroundMovementDeltaMoveAlongFloor-->SafeMoveUpdatedComponent%%-------------------------------------CheckLedges-->|true|GetLedgeMoveGetLedgeMove-->|true|RevertMove-->TryLedgeMoveGetLedgeMove-->|false|bMustJump-->|true|RevertMove-->FallCheckLedges-->|false|FloorCheck%%-------------------------------------FloorCheck-->IsWalkableFloorIsWalkableFloor-->|true|AdjustFloorHeight-->SetBaseIsWalkableFloor-->|false|GetPenetrationAdjustment-->ResolvePenetration%%-------------------------------------

GetSimulationTimeStep：将 TickDeltaTime 按照 MaxSimulationTimeStep 分割为若干段（为了保证平滑），处理每一段的信息；

CalcVelocity：根据 Friction、bFluid、BrakingDeceleration 修改 Acceleration，并计算出 Velocity 水平速度；

MoveAlongFloor：根据 MoveVelocity 信息，先调用 ComputeGroundMovementDelta，根据 Velocity 计算出 RampVector 平行于斜面的移动距离，同时根据 bMaintainHorizontalGroundVelocity 处理沿斜面速度减慢的情况；然后调用 SafeMoveUpdatedComponent，进行 MoveUpdatedComponent，更新位置；在 UPrimitiveComponent::MoveComponentImpl 中，还会进行 World->ComponentSweepMulti 判断是否遇到障碍物；

FindFloor：更新 CurrentFloor : FFindFloorResult 信息；用 CharacterOwner->GetCapsuleComponent() 进行 FloorSweepTest，计算出 ValidPerchRadius 等信息；

CheckLedges：检测是否在 Ledge 附近，如果是，则先尝试寻找新的移动方向（通过 GetLedgeMove 进行 SweepSingleByChannel 计算出边缘法线返回新的反向）；如果找不到新的方向，则尝试跳跃，检测 bMustJump，如果不能跳跃则取消移动；

FloorCheck：校验 Floor 相关数据，如果 Character 处于IsWalkableFloor 的 Floor，AdjustFloorHeight 来调整 Character 的高度，如果在 Floor 中则 GetPenetrationAdjustment 计算需要弹出 Character 的距离并 ResolvePenetration，防止 Floor 和 Character 有冲突卡住；

MaintainHorizontalGroundVelocity：调用之前判断是否依然 IsMovingOnGround，如果是则根据 bMaintainHorizontalGroundVelocity，计算 GravityRelativeVelocity 进而更新 Velocity；

Kinetic : Falling

flowchart LRPerformMovement-->StartNewPhysics-->PhysFallingPhysFalling-->GetFallingLateralAccelerationPhysFalling-->ShouldLimitAirControlPhysFalling-->RestorePreAdditiveRootMotionVelocityPhysFalling-->CalcVelocityPhysFalling-->ApplyRootMotionToVelocityPhysFalling-->NotifyJumpApexPhysFalling-->SafeMoveUpdatedComponentPhysFalling-->|IsSwimming|StartSwimmingPhysFalling-->BlockingHit%%---------------------BlockingHit-->|IsValidLandingPoint|ProcessLandedBlockingHit-->HandleImpact%%---------------------ProcessLanded-->|IsFalling|SetPostLandedPhysicsProcessLanded-->StartNewPhysics_2%%---------------------HandleImpact-.-> CalcVelocity_2-.-> BlockingHit_2

GetFallingLateralAcceleration：计算 Character 在水平方向上的加速度；重点是将 WorldAcceleration 通过RotateWorldToGravity 转为 Gravity 相关坐标系，然后将 Z 的方向设为 0，再转回 World 坐标系，这样以移除垂直方向上的加速度（因为垂直方向的加速度需要由 Gravity 决定，而不是 InputVector）；

RestorePreAdditiveRootMotionVelocity：Apply AdditiveRootMotion 的情况下将 Velocity 设置为 LastPreAdditiveVelocity（ AdditiveRootMotion 表示 RootMotioinVelocity 将与 Character 的原始速度 LastPreAdditiveVelocity，即计算 RootMotionVelocity 前的速度叠加），防止 RootMotion Velocity 被累加；

CalcVelocity：根据 FallAcceleration、Gravity、JumpForce 等数据，计算出 NewFallVelocity；

ApplyRootMotionToVelocity：应用 RootMotion Velocity，根据 HasOverrideVelocity / HasAdditiveVelocity 两种应用速度方式，计算 Velocity；

NotifyJumpApex：当 RotateWorldToGravity(Velocity).Z < 0 时，说明到达了 JumpApex 跳跃顶点，进行通知；

SafeMoveUpdatedComponent：进行位移设置；

BlokingHit：在碰到障碍物时的处理；

ProcessLanded：判断是否 IsValidLandingPoint，如果是，进行着陆；进行通知 Landed 与设置相关物理状态 SetPostLandedPhysics，然后开始新的物理模拟 StartNewPhysics；

HandleImpact：无法着陆时，AddImpactPhysicsForces ，用于后续计算碰撞后的 Velocity与位移；

BlockingHit_2：碰撞移动后再次计算是否再次 BlockingHit，如果无 Hit，则尝试 FindFloor，找到 Floor则尝试着陆；如果是，说明 Character 被卡在了两个障碍物中间；检测是否 IsValidLandingPoint 是着陆点，是则 ProcessLand；如果不是着陆点，特殊处理被卡住 bDitch 的情况（检查 OldHitImpactNormal、Hit.ImpactNormal 是否都具有 Z 即斜坡朝上，且夹角 >90° 即斜坡朝向不同，同时 Character 的 Delta.Z 接近 0 即在垂直方向无移动），如果是，尝试增加 Velocity 与位移，摆脱被卡住的情况；

Kinetic : Other

TODO…

ReplicateMoveToServer

对于 AutonomousProxy Character 将移动同步到服务器，同时进行 Client 本地的预表现；

主要维护三种 Move 数据：

Old Move：当前还未被 DS ACK 的 Move 数据中，最早的一次 Move；
New Move：本次执行（即 Client 进行 Perform）的 Move；
Pending Move：若某次 New Move 还未进行同步（等待并包），将其存储在 Pending Move 中，等待下次同步带上该数据；

在 CallServerMovePacked 时，打包三种 Move 同步；

首先需要了解：FNetworkPredictionData；

FNetworkPredictionData

PredictionData_Client_Character 维护 Client 的 Move 相关数据，同时用于合并、丢弃、比较、标记更新等操作；

classDiagramclass FNetworkPredictionData_Client_Character {SavedMoves : TArray~FSavedMovePtr~FreeMoves : TArray~FSavedMovePtr~PendingMove : FSavedMovePtrLastAckedMove : FSavedMovePtrClientUpdateRealTime : floatbUpdatePosition : uint32...}FNetworkPredictionData_Client_Character-->FSavedMove_Characterclass FSavedMove_Character {        TimeStamp : float        DeltaTime : floatAcceleration : FVectorMaxSpeed : floatStart / End / Saved : Location / ReletiveLocation / Rotation / Velocity / Floor / CapsuleRadius / CapsuleHalfHeight / Base / ActorOverlapCounter ......}

其中：

FSavedMovePtr 是 TSharedPtr；

SavedMoves 保存 Client 执行的 Move，在 CleintAck 后， LastAckedMove 将会被 Free 并从 SavedMoves 中移除；

PendingMove 记录 Client 最新执行的，还未 CallServer 的 Move，每次 Push 到 SavedMoves 中，同时可能会作为 OldMove 被 Combine；

FreeMoves 记录已经被标记 Free 的 Move，后续释放；

classDiagram    class FNetworkPredictionData_Server_Character {    PendingAdjustment : FClientAdjustment}FNetworkPredictionData_Server_Character-->FClientAdjustmentclass FClientAdjustment {TimeStamp : floatDeltaTime : floatbAckGoodMove : boolNew Loc / Vel / Rot / Base ......}

PredictionData_Server_Character 记录在 Server 上的 Move 数据，用于校验、修正等；

其中：

PendingAdjustment 维护了一系列 ClientAdjust 所需的数据；

ReplicateMoveToServer - Logic

flowchart LRReplicateMoveToServer-->GetPredictionData_Client_CharacterReplicateMoveToServer-->ClientData_UpdateTimeStampAndDeltaTimeReplicateMoveToServer-->FindImportantMoveReplicateMoveToServer-->ClientData_CreateSavedMove-.->Move_SetMoveFor-.->Move_CombineReplicateMoveToServer-->PerformMovement-.->Move_PostUpdate-.->ClientData_SaveMoveReplicateMoveToServer-->CallServerMove-.->ClearPending

GetPredictionData_Client_Character：获取 Client 的预测数据 ClientData : FNetworkPredictionData_Client_Character*；

ClientData 会在各个地方被更新，比如

ReplicateMoveToServer 中：
更新物理模拟的 TimeStamp与 DeltaTime：ClientData->UpdateTimeStampAndDeltaTime；
创建新的 SavedMove ：ClientData->CreateSavedMove()；
PerformMovement 之后更新 Location、Rotation、Velocity 等数据：NewMove->PostUpdate(CharacterOwner, FSavedMove_Character::PostUpdate_Record);
CallServerMove / CallServerMovePacked 前更新时间：ClientData->ClientUpdateRealTime = MyWorld->GetRealTimeSeconds();
ClientAckGoodMove：Client 收到 Server 的移动确认时，更新最后的移动 ClientData->LastAckedMove：

FindImportantMove：找到最早的未 Ack 的 ImportantMove 数据，IsImportantMove 指与上一个 Ack 的移动有差异的移动；判定是否 Important 时，会检查 CompressedFlags （压缩了 FLAG_JumpPressed、FLAG_WantsToCrouch 等信息）、Start/End PackedMovementMode、Acceleration 的大小、方向差异是否超过阈值；找到 Unack ImportMove 后，存储在 OldMove 中，后续将其与新的 Move 一起 CallServerMove，确保 Server 可以正确处理。

CreateSavedMove：创建新的 FSavedMove 数据，也就是定义一个新的 Move；

Move_SetMoveFor：根据 CharacterOwner、DeltaTime、NewAcceleration 等数据设置 Move 基本信息；

Move_Combine：尝试将这个新的 Move 与待处理的移动 PendingMove 合并，如果 CanCombine，更新 Rotation、Position 等信息；CanCombine 会校验 TimeStamp、RootMotion、Acceleration、StartVelocity、MaxSpeed、Jump、CompressedFlags、MovementMode、StartCapsule Radius/HalfHeight、AttachParent、TimeDilation、ActorOverlapCounter 这些数据；Combine 时更新 Location、Rotation、Velocity、Floor、Jump 等数据；

PerformMovement：在本地执行移动；

Move_PostUpdate：在 PerformMovement 更新了移动相关数据之后，设置这些状态数据到 Move 中；

ClientData_SaveMove：将 NewMove 保存到移动列表 ClientData->SavedMoves 中；

CallServerMove：根据角色是否正在复制移动 bSendServerMove 将新的移动发动到 Server，根据 ShouldUsePackedMovementRPCs 决定发送的方式 CallServerMovePacked / CallServerMove；

ClearPendingMove：清空 PendingMove，表示没有待处理的移动；

AutonomousProxy

从 ReplicateMoveToServer -> CallServerMovePacked 继续出发：

flowchart LRCallServerMovePacked-->ServerMovePacked_ClientSend-->|DS|ServerMovePacked_Implementation-->ServerMovePacked_ServerReceiveServerMovePacked_ServerReceive-->ServerMove_HandleMoveDataServerMove_HandleMoveData-->SetCurrentNetworkMoveDataServerMove_HandleMoveData-->ServerMove_PerformMovementServerMove_PerformMovement-->MoveAutonomousServerMove_PerformMovement-->ServerMoveHandleClientError-->ServerCheckClientErrorMoveAutonomous-->PerformMovement

通过 CallServerMovedPacked (UnreliableRPC) 将打包的 SaveMoves 数据发送到 DS，DS 根据 Client 发送到的数据应用 Move 数据，进行SetCurrentNetworkMoveData、ServerMove_PerformMovent，同时在 ServerMove_PerformMovent 中 MoveAutonomous （内部还是 PerformMovement）与校验数据合法性 CheckClientError；如果数据差异过大，则 ServerData->PendingAdjustment.bAckGoodMove = false；

Move 数据变化后，通过 Replicate 将其复制到 Client，主要涉及的数据有：

bReplicateMovement：标记是否要进行 Move 的同步；
ReplicatedMovement：移动数据；
ReplicatedBasedMovement：Base 的移动数据；
ReplicatedMovementMode：移动模式（Walk、Fall 等）
其它数据：Transform、RootMotion 等；

flowchart LRUNetDriver::TickFlush-->UNetDriver::ServerReplicateActors-->SendClientAdjustmentSendClientAdjustment-->bAckGoodMovebAckGoodMove-->|true|ServerLastClientGoodMoveAckTime-->ShouldUsePackedMovementRPCs_GoodbAckGoodMove-->|false|ServerLastClientAdjustmentTime-->ShouldUsePackedMovementRPCs_NoGoodShouldUsePackedMovementRPCs_Good-->|false|ClientAckGoodMoveShouldUsePackedMovementRPCs_NoGood-->|false|ClientAdjustPositionShouldUsePackedMovementRPCs_Good-->|true|ServerSendMoveResponseShouldUsePackedMovementRPCs_NoGood-->|true|ServerSendMoveResponseServerSendMoveResponse-->MoveResponsePacked_ServerSend-->ClientMoveResponsePacked-->|Client|MoveResponsePacked_ClientReceive

同步时候，也向 Client 进行 SendClientAdjust，通知 Client 每次 NewMove 的结果；

根据 ShouldUsePackedMovemtnRPCs 决定是否需要 ServerSendMoveResponse；

flowchart LRMoveResponsePacked_ClientReceive-->ClientHandleMoveResponse-->IsGoodMoveIsGoodMove-->|true|ClientAckGoodMove_ImplementationIsGoodMove-->|false|ClientAdjustPosition_Implementation-->SetbUpdatePosition_trueTickComponent-->ClientUpdatePositionAfterServerUpdate

Client 收到 DS 的 SendClientAdjust 后，判定 MoveResponse 是否 IsGoodMove，如果是，Client 进行 Ack，被确认的 Move 将会立刻从 SavedMoves 中移除；否则 Client 需要更新 bUpdatePosition 为 true，后续在 ClientUpdatePositionAfterServerUpdate 中进行修正；

ClientUpdatePositionAfterServerUpdate：判定 bUpdatePosition 是否是 true，如果是则回放 DS 未 Ack 的 ClientData->SavedMoves.Num()，进行 SetCurrentReplayedSavedMove 并 MoveFor；

SimulateProxy

flowchart LRACharacter::OnRep_ReplicatedMovement-->AActor::PostNetReceiveVelocityACharacter::OnRep_ReplicatedMovement-->ACharacter::PostNetReceiveLocationAndRotationAActor::PostNetReceiveVelocity-->UPrimitiveComponent::SetPhysicsLinearVelocityACharacter::PostNetReceiveLocationAndRotation-->SmoothCorrectionACharacter::PostNetReceiveLocationAndRotation-->SetbNetworkUpdateReceived_true

数据同步后，Client 通过 OnRep_ReplicatedBasedMovement、OnRep_ReplicatedMovement 将坐标设置给 Actor；

flowchart LRTickComponent-->SimulatedTick-->SimulateMovementSimulatedTick-->|!bNetworkSmoothingComplete|SmoothClientPosition%% -----------SimulateMovement-->ScopedUpdatesScopedUpdates-->bIsSimulatedProxybIsSimulatedProxy-->bNetworkUpdateReceived_truebNetworkUpdateReceived_true-->|bNetworkGravityDirectionChanged|SetGravityDirectionbNetworkUpdateReceived_true-->|bNetworkMovementModeChanged| ApplyNetworkMovementModebNetworkUpdateReceived_true-->|bJustTeleported OR bForceNextFloorCheck|UpdateFloorFromAdjustmentbNetworkUpdateReceived_false-->|bForceNextFloorCheck|UpdateFloorFromAdjustment%% -----------ScopedUpdates-->UpdateCharacterStateBeforeMovementScopedUpdates-->MaybeUpdateBasedMovementScopedUpdates-->UpdateProxyAccelerationScopedUpdates-->|!bHandledNetUpdate OR !bNetworkSkipProxyPredictionOnNetUpdate|MoveSmooth-->IsMovingOnGroundIsMovingOnGround-->|true|MoveAlongFloorIsMovingOnGround-->|false|SafeMoveUpdatedComponent-->|!bSteppedUp|SlideAlongSurfaceScopedUpdates-->UpdateCharacterStateAfterMovementScopedUpdates-->OnMovementUpdatedSimulateMovement-->CallMovementUpdateDelegateSimulateMovement-->UpdateComponentVelocity%% -----------SmoothClientPosition-->SmoothClientPosition_InterpolateSmoothClientPosition-->SmoothClientPosition_UpdateVisuals

Smooth：

SmoothingServerTimeStamp 表示 Character 在 DS 当前移动时间戳，由 ACharacter::PreReplication 时，同步的 ReplicatedServerLastTransformUpdateTimeStamp 得来；

SmoothingClientTimeStamp 表示 Character 在这个 Client 当前平滑到的移动时间戳；

每次进行 SmoothClientPosition_Interpolate 时；

在 SmoothingMode = ENetworkSmoothingMode::Linear 的情况下：

计算 TargetDelta = LastCorrectionDelta，这里的 LastCorrectionDelta = 上一次( SmoothingServerTimeStamp - SmoothingClientTimeStamp) ，表示实际上相比于 DS 上的数据，Client 在这一次平滑开始前，还剩余多少时间还未执行平滑操作；
更新 SmoothingClientTimeStamp = Min(SmoothingClientTimeStamp + DeltaSeconds, SmoothingServerTimeStamp + MaxTimeAhead);
这里的 DeltaSeconds 表示当帧过去的实际时间；
MaxTimeAhead = TargetDelta * 0.15f，表示允许多往前外插的时间，0.15f 是允许多预测的时间比例；
现在这个新的 SmoothingClientTimeStamp，就表示这一帧 Client 需要平滑到的时间戳；
计算 RemainingTime = SmoothingServerTimeStamp - SmoothingClientTimeStamp，表示在这一帧平滑过后，还剩下多少时间没有平滑；然后 CurrentSmoothTime = TargetDelta - RemainingTime，得到这一帧需要平滑多少时间；
计算 LerpPercent = FMath::Clamp(CurrentSmoothTime / TargetDelta, 0.0f, LerpLimit)，按照 本次平滑多少时间 / 剩余的总共需要平滑的时间，得到这个 LerpPercent；
其中 LerpLimit = 1.15f，也是允许多平滑的比例；
得到 LerpPercent 后，更新 MeshTranslationOffset、MeshRotationOffset；

特别地，如果不是通过 DS 模式来进行同步（比如自定义协议），可以打包 FRepMovement 数据，然后手动进行 Replicate 模拟：

CharacterActor->PreNetReceive();
CharacterActor->SetReplicatedMovementMode();
CharacterActor->PostNetReceive();

CharacterActor->SetReplicatedMovement();
CharacterActor->OnRep_ReplicatedMovement();

参考

UE 5.4 源码

大体框架：UE4 移动的网络同步

核心代码：《Exploring in UE4》移动组件详解[原理分析]

[UE]ToString解决方案

2024-05-31T16:00:00.000Z

ToString解决方案

背景

提供一个通用机制 UStringUtils::ToString(Value) 将其 String 化。

其中 Value 包括：

Base：基础类型（int、bool、float、FString 等）；
Enum；
包含 ToString 或 GetUID 方法的类型、指针；
Pointer：TStrongPtr、TShaerdPtr、TWeakPtr、TUniquePtr；
Variant；
Container：包括 Array、Set、Map 等；

实现

基础类型

template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T& Value)
{
    return FString::FromInt(static_cast(Value));
}

static FString ToString(const uint32& Value)
{
    return FString::Printf(TEXT("%u"), Value);
}

static FString ToString(const int64& Value)
{
    return FString::Printf(TEXT("%lld"), Value);
}

static FString ToString(const uint64& Value)
{
    return FString::Printf(TEXT("%llu"), Value);
}

template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T& Value)
{
    return FString::Printf(TEXT("%.3f"), static_cast<float>(Value));
}

static FString ToString(const bool& Value)
{
    return FString::Printf(TEXT("%s"), Value ? TEXT("true") : TEXT("false"));
}

static FString ToString(const FString& Value)
{
    return Value;
}

Enum

template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T& Value)
{
    if constexpr (google::protobuf::is_proto_enum::value)
    {
        auto String = ::google::protobuf::internal::NameOfEnum(::google::protobuf::template GetEnumDescriptor(), static_cast<int>(Value));
        return UTF8_TO_TCHAR(String.c_str());
    }
    else if constexpr (TIsUEnumClass::Value)
    {
        auto EnumClass = StaticEnum();
        return EnumClass->GetNameStringByValue(static_cast(Value));
    }
    else
    {
        return FString::Printf(TEXT("RawEnum_%s"), *ToString(static_cast<__underlying_type(T)>(Value)));
    }
}

template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const TEnumAsByte& Value)
{
    return ToString(Value.GetValue());
}

注意，这里用到了 TIsUEnumClass 判断是否是 UEnum，这在 UE5 才正式提供，具体代码在 UhtHeaderCodeGeneratorHFile.cs : AppendEnum 中生成；

如果是 UE4，可以自定义该 concept，修改 UHT 的 CodeGenerator ，将其 UEnum : TIsUEnumClass = true生成在 .generated.h 中：

// 1. 新增 TIsUEnumClass
template <typename T>
struct TIsUEnumClass
{
static constexpr bool Value = false;
};

// 2. 修改 UEnum 的 Genrator

void FNativeClassHeaderGenerator::ExportEnum(FOutputDevice& Out, UEnum* Enum) const
{
// ...
    
if (const EUnderlyingEnumType* EnumPropType = GEnumUnderlyingTypes.Find(Enum))
{
        // ...
Out.Logf( TEXT("\r\n") );
Out.Logf( TEXT("enum class %s%s;\r\n"), *Enum->CppType, *UnderlyingTypeString );
Out.Logf( TEXT("template<> %sUEnum* StaticEnum<%s>();\r\n"), *GetAPIString(), *Enum->CppType );
Out.Logf( TEXT("\r\n") );


        // 新增 TIsUEnumClass 判断
Out.Logf(TEXT("template<> struct TIsUEnumClass<%s> { static constexpr bool Value = true; };\r\n"), *Enum->CppType);
Out.Logf(TEXT("\r\n"));
}
}

包含 `ToString` 或 `GetUID` 方法的类型、指针

template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T& Value)
{
    return Value.ToString();
}

template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T* Value)
{
    return Value ? Value->ToString() : TEXT("Invalid");
}

template<typename T>
static typename TEnableIf::Value && !THasToStringFunc::Value, FString>::Type ToString(const T& Value)
{
    if constexpr (THasGetUIDFunc::Value)
    {
        return ToString(Value.GetUID());
    }
    else
    {
        return Value.GetName();
    }
}

template<typename T>
static typename TEnableIf::Value && !THasToStringFunc::Value, FString>::Type ToString(const T* Value)
{
    if (!IsValid(Value)) return TEXT("Invalid");

    if constexpr (THasGetUIDFunc::Value)
    {
        return ToString(Value->GetUID());
    }
    else
    {
        return Value->GetName();
    }
}

这里用了 THasToStringFunc、TGetUIDFunc，需要新增 TypeTraits：

struct TrueType { static constexpr bool Value = true; };
struct FalseType { static constexpr bool Value = false; };

// THas[FunctionName]Func
// Declare type traits to detect if type T has a function named FunctionName with params.

#define DECLARE_HASFUNCTION_TYPETRAITS(FunctionName, ReturnType, ...) \
template \
struct THas##FunctionName##Func\
{ \
private: \
template \
    struct Internal { \
template \
struct THas##FunctionName##FuncInternal : FalseType {}; \
    template \
    struct THas##FunctionName##FuncInternal().FunctionName(DeclVal()...))>::Value>::Type> : TrueType {}; \
    }; \
public: \
static constexpr bool Value = Internal::template THas##FunctionName##FuncInternal::Value; \
};

// ----- Declare -----

// THasToStringFunc: FString T::ToString()
DECLARE_HASFUNCTION_TYPETRAITS(ToString, FString)
// THasGetUIDFunc: uint64 T::GetUID()
DECLARE_HASFUNCTION_TYPETRAITS(GetUID, uint64)

Pointer

public:
template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T& Value)
{
    return Value ? UStringUtils::ToString(*Value) : TEXT("Invalid");
}

template<typename T>
static FString ToString(TStrongObjectPtr Value)
{
    return Value.IsValid() ? UStringUtils::ToString(Value.Get()) : TEXT("Invalid");
}

template<typename T>
static FString ToString(TWeakPtr Value)
{
    return Value.IsValid() ? UStringUtils::ToString(Value.Pin().Get()) : TEXT("Invalid");
}

template<typename T>
static FString ToString(TSharedPtr Value)
{
    return Value.IsValid() ? UStringUtils::ToString(Value.Get()) : TEXT("Invalid");
}

template<typename T>
static FString ToString(const TUniquePtr& Value)
{
    return Value.IsValid() ? UStringUtils::ToString(Value.Get()) : TEXT("Invalid");
}

Variant

template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T& Value)
{
    auto VariantType = Value.GetType();
    switch (VariantType)
    {
    case EVariantTypes::Bool:     return UStringUtils::ToString(Value.template GetValue<bool>());
    case EVariantTypes::Float:    return UStringUtils::ToString(Value.template GetValue<float>());
    case EVariantTypes::String:   return UStringUtils::ToString(Value.template GetValue());
    case EVariantTypes::Int8:     return UStringUtils::ToString(Value.template GetValue());
    case EVariantTypes::Int16:    return UStringUtils::ToString(Value.template GetValue());
    case EVariantTypes::Int32:    return UStringUtils::ToString(Value.template GetValue());
    case EVariantTypes::Int64:    return UStringUtils::ToString(Value.template GetValue());
    case EVariantTypes::UInt8:    return UStringUtils::ToString(Value.template GetValue());
    case EVariantTypes::UInt16:   return UStringUtils::ToString(Value.template GetValue());
    case EVariantTypes::UInt32:   return UStringUtils::ToString(Value.template GetValue());
    case EVariantTypes::UInt64:   return UStringUtils::ToString(Value.template GetValue());
    }

    return TEXT("Unknown");
}

Container

template<typename TContainer, typename TFunctor, typename = typename TEnableIf::Value>::Type>
static FString ContainerToStringHelper(const TContainer& Container, const FString& StartToken, const FString& EndToken, bool Multilines, TFunctor&& ElementToStringFunctor)
{
    if (Container.IsEmpty()) return TEXT("Empty");

    TArray ElementStrings{};

    for (const auto& Element : Container)
    {
        auto String = ElementToStringFunctor(Element);

        if (String.IsEmpty())
        {
            ElementStrings.Emplace(TEXT("None"));
        }
        else
        {
            ElementStrings.Emplace(MoveTemp(String));
        }
    }

    auto Res = FString::Join(ElementStrings, Multilines ? TEXT(",\n") : TEXT(", "));

    if (Multilines)
    {
        return FString::Printf(TEXT("%s\n%s\n%s"), *StartToken, *Res, *EndToken);
    }
    else
    {
        return FString::Printf(TEXT("%s%s%s"), *StartToken, *Res, *EndToken);
    }
}

template<typename T>
static FString ToString(const TArray& Array, bool Multilines = false)
{
    return UStringUtils::ContainerToStringHelper(Array, TEXT("["), TEXT("]"), Multilines, [](const auto& Element) -> FString {
        return UStringUtils::ToString(Element); 
    });
}

template<typename T>
static FString ToString(const TSet& Set, bool Multilines = false)
{
    return UStringUtils::ContainerToStringHelper(Set, TEXT("("), TEXT(")"), Multilines, [](const auto& Element) -> FString {
        return UStringUtils::ToString(Element); 
    });
}

template<typename TKey, typename TValue>
static FString ToString(const TMap& Map, bool Multilines = false)
{
    return UStringUtils::ContainerToStringHelper(Map, TEXT("{"), TEXT("}"), Multilines, [](const auto& Element) -> FString {
        return FString::Printf(TEXT("%s: %s"), *UStringUtils::ToString(Element.Key), *UStringUtils::ToString(Element.Value));
    });
}

这里用到了 TIsContainer ，可以通过是否有 .begin()、.end()、.IsEmpty() 方法简单判断：

// TMakeVoid
template<typename... T>
struct TMakeVoid { using Type = void; };

// TIsContainer
template<typename T, typename = void>
struct TIsContainer : FalseType {};

template<typename T>
struct TIsContainer<T, typename TMakeVoid<
    decltype(DeclVal().begin()), 
    decltype(DeclVal().end()), 
    typename TEnableIfdecltype(DeclVal().IsEmpty()), bool>::Value>::Type
>::Type> : TrueType {};

完整实现

// StringUtils.h

#pragma once

#include "CoreMinimal.h"
#include "Kismet/BlueprintFunctionLibrary.h"
#include "UObject/StrongObjectPtr.h"
#include "TypeTraits.h"
#include "StringUtils.generated.h"

UCLASS()
class UStringUtils : public UBlueprintFunctionLibrary
{
GENERATED_BODY()

#pragma region Base
public:
template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T& Value)
{
return FString::FromInt(static_cast(Value));
}

static FString ToString(const uint32& Value)
{
return FString::Printf(TEXT("%u"), Value);
}

static FString ToString(const int64& Value)
{
return FString::Printf(TEXT("%lld"), Value);
}

static FString ToString(const uint64& Value)
{
return FString::Printf(TEXT("%llu"), Value);
}

template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T& Value)
{
return FString::Printf(TEXT("%.3f"), static_cast<float>(Value));
}

static FString ToString(const bool& Value)
{
return FString::Printf(TEXT("%s"), Value ? TEXT("true") : TEXT("false"));
}

static FString ToString(const FString& Value)
{
return Value;
}

#pragma endregion Base



#pragma region Enum
template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T& Value)
{
if constexpr (google::protobuf::is_proto_enum::value)
{
auto String = ::google::protobuf::internal::NameOfEnum(::google::protobuf::template GetEnumDescriptor(), static_cast<int>(Value));
return UTF8_TO_TCHAR(String.c_str());
}
else if constexpr (TIsUEnumClass::Value)
{
auto EnumClass = StaticEnum();
return EnumClass->GetNameStringByValue(static_cast(Value));
}
else
{
return FString::Printf(TEXT("RawEnum_%s"), *ToString(static_cast<__underlying_type(T)>(Value)));
}
}
template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const TEnumAsByte& Value)
{
return ToString(Value.GetValue());
}
#pragma endregion Enum


#pragma region ToString
public:
template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T& Value)
{
return Value.ToString();
}

template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T* Value)
{
return Value ? Value->ToString() : TEXT("Invalid");
}

template<typename T>
static typename TEnableIf::Value && !THasToStringFunc::Value, FString>::Type ToString(const T& Value)
{
if constexpr (THasGetUIDFunc::Value)
{
return ToString(Value.GetUID());
}
else
{
return Value.GetName();
}
}

template<typename T>
static typename TEnableIf::Value && !THasToStringFunc::Value, FString>::Type ToString(const T* Value)
{
if (!IsValid(Value)) return TEXT("Invalid");

if constexpr (THasGetUIDFunc::Value)
{
return ToString(Value->GetUID());
}
else
{
return Value->GetName();
}
}

#pragma endregion ToString


#pragma region Pointer
public:
template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T& Value)
{
return Value ? UStringUtils::ToString(*Value) : TEXT("Invalid");
}

template<typename T>
static FString ToString(TStrongObjectPtr Value)
{
return Value.IsValid() ? UStringUtils::ToString(Value.Get()) : TEXT("Invalid");
}

template<typename T>
static FString ToString(TWeakPtr Value)
{
return Value.IsValid() ? UStringUtils::ToString(Value.Pin().Get()) : TEXT("Invalid");
}

template<typename T>
static FString ToString(TSharedPtr Value)
{
return Value.IsValid() ? UStringUtils::ToString(Value.Get()) : TEXT("Invalid");
}

template<typename T>
static FString ToString(const TUniquePtr& Value)
{
return Value.IsValid() ? UStringUtils::ToString(Value.Get()) : TEXT("Invalid");
}
#pragma endregion Pointer


#pragma region FVariant
public:
template<typename T>
static typename TEnableIf::Value, FString>::Type ToString(const T& Value)
{
auto VariantType = Value.GetType();
switch (VariantType)
{
case EVariantTypes::Bool:     return UStringUtils::ToString(Value.template GetValue<bool>());
case EVariantTypes::Float:    return UStringUtils::ToString(Value.template GetValue<float>());
case EVariantTypes::String:   return UStringUtils::ToString(Value.template GetValue());
case EVariantTypes::Int8:     return UStringUtils::ToString(Value.template GetValue());
case EVariantTypes::Int16:    return UStringUtils::ToString(Value.template GetValue());
case EVariantTypes::Int32:    return UStringUtils::ToString(Value.template GetValue());
case EVariantTypes::Int64:    return UStringUtils::ToString(Value.template GetValue());
case EVariantTypes::UInt8:    return UStringUtils::ToString(Value.template GetValue());
case EVariantTypes::UInt16:   return UStringUtils::ToString(Value.template GetValue());
case EVariantTypes::UInt32:   return UStringUtils::ToString(Value.template GetValue());
case EVariantTypes::UInt64:   return UStringUtils::ToString(Value.template GetValue());
}

return TEXT("Unknown");
}
#pragma endregion FVariant


#pragma region Container
public:
template<typename TContainer, typename TFunctor, typename = typename TEnableIf::Value>::Type>
static FString ContainerToStringHelper(const TContainer& Container, const FString& StartToken, const FString& EndToken, bool Multilines, TFunctor&& ElementToStringFunctor)
{
if (Container.IsEmpty()) return TEXT("Empty");

TArray ElementStrings{};

for (const auto& Element : Container)
{
auto String = ElementToStringFunctor(Element);

if (String.IsEmpty())
{
ElementStrings.Emplace(TEXT("None"));
}
else
{
ElementStrings.Emplace(MoveTemp(String));
}
}

auto Res = FString::Join(ElementStrings, Multilines ? TEXT(",\n") : TEXT(", "));

if (Multilines)
{
return FString::Printf(TEXT("%s\n%s\n%s"), *StartToken, *Res, *EndToken);
}
else
{
return FString::Printf(TEXT("%s%s%s"), *StartToken, *Res, *EndToken);
}
}

template<typename T>
static FString ToString(const TArray& Array, bool Multilines = false)
{
return UStringUtils::ContainerToStringHelper(Array, TEXT("["), TEXT("]"), Multilines, [](const auto& Element) -> FString {
return UStringUtils::ToString(Element); 
});
}

template<typename T>
static FString ToString(const TSet& Set, bool Multilines = false)
{
return UStringUtils::ContainerToStringHelper(Set, TEXT("("), TEXT(")"), Multilines, [](const auto& Element) -> FString {
return UStringUtils::ToString(Element); 
});
}

template<typename TKey, typename TValue>
static FString ToString(const TMap& Map, bool Multilines = false)
{
return UStringUtils::ContainerToStringHelper(Map, TEXT("{"), TEXT("}"), Multilines, [](const auto& Element) -> FString {
return FString::Printf(TEXT("%s: %s"), *UStringUtils::ToString(Element.Key), *UStringUtils::ToString(Element.Value));
});
}
#pragma endregion Container
    
};

// TypeTraits.h
#pragma once

#include "CoreMinimal.h"

struct TrueType { static constexpr bool Value = true; };
struct FalseType { static constexpr bool Value = false; };

// TMakeVoid
template<typename... T>
struct TMakeVoid { using Type = void; };

#pragma region Container

// TIsContainer
template<typename T, typename = void>
struct TIsContainer : FalseType {};

template<typename T>
struct TIsContainer<T, typename TMakeVoid<
    decltype(DeclVal().begin()), 
    decltype(DeclVal().end()), 
    typename TEnableIfdecltype(DeclVal().IsEmpty()), bool>::Value>::Type
>::Type> : TrueType {};

#pragma endregion Container


#pragma region HasMemberFunction

// THas[FunctionName]Func
// Declare type traits to detect if type T has a function named FunctionName with params.

#define DECLARE_HASFUNCTION_TYPETRAITS(FunctionName, ReturnType, ...) \
template \
struct THas##FunctionName##Func\
{ \
private: \
template \
    struct Internal { \
template \
struct THas##FunctionName##FuncInternal : FalseType {}; \
    template \
    struct THas##FunctionName##FuncInternal().FunctionName(DeclVal()...))>::Value>::Type> : TrueType {}; \
    }; \
public: \
static constexpr bool Value = Internal::template THas##FunctionName##FuncInternal::Value; \
};

// ----- Declare -----

// THasToStringFunc: FString T::ToString()
DECLARE_HASFUNCTION_TYPETRAITS(ToString, FString)
// THasGetUIDFunc: uint64 T::GetUID()
DECLARE_HASFUNCTION_TYPETRAITS(GetUID, uint64)

#pragma endregion HasMemberFunction

[UE]UnLua & C++ 交互

2024-05-26T16:00:00.000Z

UnLua & C++ 交互

在 Lua 中调用一般的 UFUNCTION 反射比较简单直接，这里以从 Lua 中调用 CFUNCTION 为例简单介绍两端交互。

具体为在 Lua 中的调用：local Table = UE.UTestUtils.LuaCFunction(Val0, Val1)，并返回一个 Lua Table : { "Val0" = Val0, "Val1" = Va1 }。

定义

首先通过 ADD_STATIC_CFUNCTION 静态导出这个原生的 FGlueFunction ；

具体的实现可以在 UnLuaEx.h 中找到。

// Test.h
struct lua_State;

UCLASS()
class UTestUtils : public UBlueprintFunctionLibrary
{
GENERATED_BODY()

public:
static int LuaCFunction(lua_State* L);
}

// Test.cpp
BEGIN_EXPORT_REFLECTED_CLASS(UTestUtils)
ADD_STATIC_CFUNTION(LuaCFunction)
END_EXPORT_CLASS(UTestUtils)
IMPLEMENT_EXPORTED_CLASS(UTestUtils)

实现

int UTestUtils::LuaCFunction(lua_State* L)
{
const int Top = lua_gettop(L);
if (Top == 2)
{
int32 Val0 = lua_tointeger(L, 1);
int32 Val1 = lua_tointeger(L, 2);
UUnLuaFunctionLibrary::CreateLuaTable(L, "Val0", Val0, "Val1", Val1);
return 1;
}

luaL_error(L, "Call UTestUtils::LuaCFunction error! argc = %d", Top);
return 0;
}

CFUNCTION 在 Lua 中调用时，会传入当前的 lua_State* L ，可以通过这个L 对 LuaStack 进行访问与写入。

首先这里的 Top = lua_gettop(L) 会根据 cast_int(L->top - (L->ci->func + 1)) 计算出返回参数的个数，比如这里的 (Val0, Val1) 就是 2 个参数。

接着通过 lua_tointeger(L, i) 将第 i 个参数取出。

然后通过 UUnLuaFunctionLibrary::CreateLuaTable，创建一个 Lua Table，进行赋值与写入，这个方法是实现的重点。

最后如果合法，return 1，返回写入 LuaStack 中返回值的个数，也就是有 1 个 LuaTable 被写入了栈。

具体的与 lua 层交互的原始方法实现可以在 lapi.c 中找到。

template<typename... Types>
UnLua::FLuaTable UUnLuaFunctionLibrary::CreateLuaTable(lua_State* L, Types&&... Args)
{
const auto LuaEnv = UnLua::FLuaEnv::FindEnv(L);
lua_newtable(L);

PushKeyValue(L, Forward(Args)...);

return UnLua::FLuaTable(LuaEnv, -1);
}

template<typename K, typename V, typename... Types>
void UUnLuaFunctionLibrary::PushKeyValue(lua_State* L, K&& Key, V&& Value, Types&&... Args)
{
PushKeyValue(L, Forward(Key), Forward(Value));
PushKeyValue(L, Forward(Args)...);
}

template<typename K, typename V>
void UUnLuaFunctionLibrary::PushKeyValue(lua_State* L, K&& Key, V&& Value)
{
UnLua::Push(L, Forward(Key));
UnLua::Push(L, Forward(Value));
lua_rawset(L, -3);
}

这个 UUnLuaFunctionLibrary::CreateLuaTable 向 L 对应的 LuaStack 中写入了一个赋值好的 LuaTable。

首先通过 lua_newtable(L) 创建了一个空的 LuaTable，然后进行 PushKeyValue 的递归调用。

针对一次 PushKeyValue，首先会往 LuaStack 中压入 Key、Value，压入后先前的 LuaTable 处于在 StatckIndex=-3 的位置。

然后针对 StackIndex = -3位置（也就是当前栈里的 LuaTable）调用 lua_rawset 方法，将 Key 和 Value 弹出并打包成参数塞进 LuaTable。

这里的 lua_rawset 实际上类似 lua_settable。对于 lua_settable，会找到元方法 __newindex 并调用，对于 lua_rawset，则会调用默认的 __newindex 方法：

1
2
3

__newindex = function(table, key, value)
    rawset(table, key, value)
end

这样，就完成了一个这样的方法实现。

给出 UUnluaFunctionLibrary 的更多扩展：

// LuaTable

template<typename... Types>
UnLua::FLuaTable UUnLuaFunctionLibrary::CreateLuaTable(lua_State* L, Types&&... Args)
{
const auto LuaEnv = UnLua::FLuaEnv::FindEnv(L);
lua_newtable(L);

PushKeyValue(L, Forward(Args)...);

return UnLua::FLuaTable(LuaEnv, -1);
}

template<typename... Types>
UnLua::FLuaTable UUnLuaFunctionLibrary::CreateLuaArray(lua_State* L, const Types&... Args)
{
const auto LuaEnv = UnLua::FLuaEnv::FindEnv(L);
lua_newtable(L);

PushKeyValue<1>(L, Forward(Args)...);

return UnLua::FLuaTable(LuaEnv, -1);
}

// ------------------------

template<typename K, typename V>
void UUnLuaFunctionLibrary::PushKeyValue(lua_State* L, K&& Key, V&& Value)
{
UnLua::Push(L, Forward(Key));
UnLua::Push(L, Forward(Value));
lua_rawset(L, -3);
}

template<typename K, typename V, typename... Types>
void UUnLuaFunctionLibrary::PushKeyValue(lua_State* L, K&& Key, V&& Value, Types&&... Args)
{
PushKeyValue(L, Forward(Key), Forward(Value));
PushKeyValue(L, Forward(Args)...);
}

template<int N, typename T>
void UUnLuaFunctionLibrary::PushKeyValue(lua_State* L, T&& Arg)
{
UnLua::Push(L, N);
UnLua::Push(L, Forward(Arg));
lua_rawset(L, -3);
}

template<int N, typename T, typename... Types>
void UUnLuaFunctionLibrary::PushKeyValue(lua_State* L, T&& Arg0, Types&&... Args)
{
PushKeyValue(L, Forward(Arg0));
PushKeyValue1>(L, Forward(Args)...);
}

template<typename K, typename T>
void UUnLuaFunctionLibrary::PushKeyValue(lua_State* L, K&& Key, TArray& Array)
{
UnLua::Push(L, Forward(Key));

lua_newtable(L);
for (int Index = 0; Index < Array.Num(); Index++)
{
UnLua::Push(L, Index + 1);
UnLua::Push(L, Array[Index]);
lua_rawset(L, -3);
}

lua_rawset(L, -3);
}

// Struct

template <typename T>
typename TEnableIf::Value, T*>::Type
UUnLuaFunctionLibrary::GetValue(lua_State* L, int32 Index)
{
const auto& Env = UnLua::FLuaEnv::FindEnvChecked(L);

const auto StructType = Env.GetPropertyRegistry()->CreateTypeInterface(L, Index);
if (!StructType)
        return nullptr;

const auto StructProperty = CastField(StructType->GetUProperty());
if (StructProperty == nullptr)
 return nullptr;

if (!StructProperty->Struct->IsChildOf(TBaseStructure::Get()))
 return nullptr;

return static_cast(GetCppInstanceFast(L, Index));
}

// Json

template<typename K>
void UUnLuaFunctionLibrary::PushKeyValue(lua_State* L, K&& Key, const TSharedPtr& Value)
{
UnLua::Push(L, Forward(Key));
PushValue(L, Value);
lua_rawset(L, -3);
}

void UUnLuaFunctionLibrary::PushValue(lua_State* L, const TSharedPtr& JsonObject)
{
lua_newtable(L);
for (const auto& KeyValue : JsonObject->Values)
{
PushKeyValue(L, KeyValue.Key, KeyValue.Value);
}
}

void UUnLuaFunctionLibrary::PushValue(lua_State* L, const TArray>& JsonValues)
{
lua_newtable(L);
for (auto i = 0; i < JsonValues.Num(); i++)
{
PushKeyValue(L, i + 1, JsonValues[i]);
}
}

void UUnLuaFunctionLibrary::PushValue(lua_State* L, const TSharedPtr& Value)
{
switch (Value->Type)
{
case EJson::String: UnLua::Push(L, Value->AsString()); break;
case EJson::Number: UnLua::Push(L, Value->AsNumber()); break;
case EJson::Boolean: UnLua::Push(L, Value->AsBool()); break;
case EJson::Array: PushValue(L, Value->AsArray()); break;
case EJson::Object: PushValue(L, Value->AsObject()); break;
default: lua_pushnil(L); break;
}
}

// ------------------------

int UUnLuaFunctionLibrary::GetLuaTableFromJsonPath(lua_State* L)
{
const int Top = lua_gettop(L);
if (Top != 1)
{
LogWarning(TEXT("Args count error. argc = %d"), Top);
return 0;
}

auto JsonFilePath = FString(UTF8_TO_TCHAR(lua_tostring(L, 1)));
if (!FPaths::FileExists(JsonFilePath))
{
LogWarning(TEXT("Json file path '%s' not found."), *JsonFilePath);
return 0;
}

FString FileContent;
if (FFileHelper::LoadFileToString(FileContent, *JsonFilePath))
{
TSharedPtr JsonObject;
auto JsonReader = TJsonReaderFactory<>::Create(FileContent);
if (FJsonSerializer::Deserialize(JsonReader, JsonObject))
{
PushValue(L, JsonObject);
}
else
{
LogWarning(TEXT("Parse json from file '%s' failed."), *JsonFilePath);
return 0;
}
}
else
{
LogWarning(TEXT("Load file path '%s' failed."), *JsonFilePath);
return 0;
}

return 1;
}

// Call

template <typename... T>
UnLua::FLuaRetValues UUnLuaFunctionLibrary::InnerCall(UObjectBaseUtility* Obj, lua_State *L, const char *FuncName, T&&... Args)
{
    const auto LuaEnv = UnLua::FLuaEnv::FindEnv(L);
    
    if (UnLua::GetObjectLuaInstance(Obj))
    {
        const UnLua::FLuaTable LuaInstance(UnLua::FLuaValue(LuaEnv, -1));
        const UnLua::FLuaFunction LuaFunc(LuaEnv, LuaInstance, FuncName);
        
        if (LuaFunc.IsValid())
        {
            auto Ret = LuaFunc.Call(LuaInstance, Forward(Args)...);
            lua_pop(L, 1);
            return Ret;
        }
    }
    
    return UnLua::FLuaRetValues(LuaEnv, 0);
}

// Class:
template <typename... T>
UnLua::FLuaRetValues InnerCall(const char *FuncName, T&&... Args)
{
    return UUnLuaFunctionLibrary::InnerCall(this, UnLua::GetState(), FuncName, Args);
}

// Helper

bool UUnLuaFunctionLibrary::CheckParamsCount(lua_State* L, int32 Num)
{
return lua_gettop(L) == Num;
}

FString UUnLuaFunctionLibrary::ToString(lua_State* L, int32 Index, bool PushValue)
{
    auto Res = FString(UTF8_TO_TCHAR(luaL_tolstring(L, Index, nullptr)));
if (!PushValue)
{
lua_pop(L, 1);
}
return Res;
}

// Delegate

template<typename... T>
struct FUnLuaTableCallback
{
FUnLuaTableCallback(TSharedPtr Table, TSharedPtr Func) : Table(Table), Func(Func) {}

inline void operator() (T... Args)
{
Func->Call(*Table.Get(), Forward(Args)...);
}

private:
TSharedPtr Table;
TSharedPtr Func;
};


#define DECLARE_MULTICAST_DELEGATE_LUA_HELPER(OwnerType, DelegateName, ...)                                                            \
private:                                                                                                                               \
TMap DelegateName##LuaHandles;                                                                           \
public:                                                                                                                                \
static int Bind##DelegateName(lua_State* L)                                                                                        \
{                                                                                                                                  \
if (!UUnLuaFunctionLibrary::CheckParamsCount(L, 3)) { return luaL_error(L, "Invalid parameters count."); }                   \
auto Self = static_cast(GetCppInstanceFast(L, 1));                                                                 \
auto TableValue = UnLua::FLuaValue(L, 2);                                                                                      \
if (TableValue.GetType() != LUA_TTABLE) { return luaL_error(L, "Parameter 2 is invalid; it should be a table."); }             \
auto Key = UUnLuaFunctionLibrary::ToString(L, 2);                                                                            \
if (Self->DelegateName##LuaHandles.Contains(Key)) { return 0; }                                                                \
auto FuncValue =  UnLua::FLuaValue(L, 3);                                                                                      \
if (FuncValue.GetType() != LUA_TFUNCTION) { return luaL_error(L, "Parameter 3 is invalid; it should be a function."); }        \
TSharedPtr Table = MakeShareable(new UnLua::FLuaTableRef(L, TableValue));                                 \
TSharedPtr Func = MakeShareable(new UnLua::FLuaFunction(L, FuncValue));                                   \
Self->DelegateName##LuaHandles.Emplace(Key, Self->DelegateName.AddLambda(FUnLuaTableCallback<__VA_ARGS__>(Table, Func)));    \
return 0;                                                                                                                      \
}                                                                                                                                  \
static int Unbind##DelegateName(lua_State* L)                                                                                      \
{                                                                                                                                  \
if (!UUnLuaFunctionLibrary::CheckParamsCount(L, 2)) { return luaL_error(L, "Invalid parameters count."); }                   \
auto Self = static_cast(GetCppInstanceFast(L, 1));                                                                 \
auto TableValue = UnLua::FLuaValue(L, 2);                                                                                      \
if (TableValue.GetType() != LUA_TTABLE) { return luaL_error(L, "Parameter 2 is invalid; it should be a table."); }             \
auto Key = UUnLuaFunctionLibrary::ToString(L, 2);                                                                            \
if (!Self->DelegateName##LuaHandles.Contains(Key)) { return 0; }                                                               \
Self->DelegateName.Remove(Self->DelegateName##LuaHandles[Key]);                                                                \
Self->DelegateName##LuaHandles.Remove(Key);                                                                                    \
return 0;                                                                                                                      \
} 


#define ADD_MULTICAST_DELEGATE_LUA_HELPER_FUNC(DelegateName)   \
ADD_STATIC_CFUNTION(Bind##DelegateName)                    \
ADD_STATIC_CFUNTION(Unbind##DelegateName)
#pragma endregion Delegate Lua Helper

参考

Lua 5.4 Reference： 4.6 – Functions and Types

Lua 虚拟栈交互流程

Unlua 解析

[UE]PlayerInfo高频同步解决方案

2024-04-29T16:00:00.000Z

PlayerInfo高频同步解决方案

描述

需求目的

分析一个常见的需求： “在 1P 客户端显示 3P 的 Transform ”。

显然，在客户端存在 3P 的 Pawn 时，可以直接取 Pawn 的 Transform；但出于性能考虑，会进行各种 AOI 机制，在较远距离时客户端会将 3P 的 Pawn 裁剪掉，只留下 PlayerState（或者某个不被剪裁的数据 Channel）用于同步。

一个直观的想法是将 Transform 直接通过对应的 PlayerState 属性同步给所有客户端；但出于性能考虑，对于同步一般会开启 PushModel；这种高频字段会频繁将 PlayerState 对应 ActorChannel 给 MarkDirty，导致 PushModel 功能基本失效，频繁进行同步的 Diff 等大开销的操作；

所以需要一个机制对这种情况进行优化。

核心思路

对于 DS，创建一个 Channel 专门用于同步 Player 的高频变化信息，如 Location、Rotation 等；

对于同步的信息，进行适当的同步降频（不需要每帧同步）、字节压缩（舍弃部分精度，精确到 float 没有意义）；

同时为了保证 Client 的信息相对正确（同步降频会导致 Location 不连续），在 1P Client 进行信息的预测插值；

实现

Replicator

创建一个 Actor - PlayerSyncInfoReplicator 专门用于打包所有 Player 高频 Info（这里特指 Location、Rotation）进行数据同步，在合适的地方进行初始化（比如 ReplicationGraph 初始化后）；

Replicator 包括一个 FPlayerSyncInfoContainer 结构体用于打包数据、进行数据的收集、自定义序列化；

void APlayerSyncInfoReplicator::GetLifetimeReplicatedProps(TArray& OutLifetimeProps) const
{
Super::GetLifetimeReplicatedProps(OutLifetimeProps);

// 不使用 PushModel，始终进行同步操作
FDoRepLifetimeParams Params;
DOREPLIFETIME_WITH_PARAMS(APlayerSyncInfoReplicator, PlayerSyncInfoContainer, Params);
}

void APlayerSyncInfoReplicator::PreReplication(IRepChangedPropertyTracker& ChangedPropertyTracker)
{
    // 收集数据
PlayerSyncInfoContainer.PreReplication();
}

Define Data & Byte Compression

对于每一个 Player，需要收集 FSyncInfo，这里记录了一个 SyncLocation : FVector_NetQuantize 与 Yaw；

USTRUCT()
struct FSyncInfo
{
GENERATED_BODY()

FSyncInfo() = default;
FSyncInfo(const FVector_NetQuantize& InSyncLocation) : SyncLocation(InSyncLocation) { }
bool NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess);

public:
FVector_NetQuantize SyncLocation;
    float Yaw;
};


template<>
struct TStructOpsTypeTraits< FSyncInfo > : public TStructOpsTypeTraitsBase2< FSyncInfo >
{
enum 
{
WithNetSerializer = true,
WithNetSharedSerialization = true,
};
};

FVector_NetQuantize 是一个自定义的类型，进行了对 FVector 的数据压缩。

由于表达一个 float 所需要的 Bit 比较多，但大部分情况不需要同步到 float 这么高精度的数据），比如一个有限范围的大世界， Location 显然不需要那么高的精度表示：

USTRUCT()
struct FVector_NetQuantize : public FVector
{
GENERATED_USTRUCT_BODY()

FORCEINLINE FVector_NetQuantize() {}

explicit FORCEINLINE FVector_NetQuantize(EForceInit E) : FVector(E) 
FORCEINLINE FVector_NetQuantize( float InX, float InY, float InZ ) : FVector(InX, InY, InZ) {}
FORCEINLINE FVector_NetQuantize( const FVector &InVec )
{
FVector::operator=(InVec);
}

bool NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess)
{
bOutSuccess = SerializePackedVector<1, 20>(*this, Ar);
return true;
}
};

template<>
struct TStructOpsTypeTraits< FVector_NetQuantize > : public TStructOpsTypeTraitsBase2< FVector_NetQuantize >
{
enum 
{
WithNetSerializer = true,
WithNetSharedSerialization = true,
};
};

这里除了将 FVector 压缩为一个 20bit 的 FVector_NetQuantize，还可以对 Yaw 这一旋转角度进行压缩：

定义一个 uint8 的 ByteYaw，存储 Yaw 的压缩版本，通过 FRotator::CompressAxisToByte 将其压缩为一个字节；
新增一个标志位 NotZero 判断 ByteRaw 是否是 0（不需要同步 Yaw 时候，该值就为 0，可能清空较多），如果为 0，则只需要存储 NotZero 的值（1位），而不是整个 ByteYaw（8位）；

对于 FSyncInfo，自定义其 NetSerialize 逻辑：

bool FSyncInfo::NetSerialize(FArchive& Ar, UPackageMap* Map, bool& bOutSuccess)
{
SyncLocation.NetSerialize(Ar, Map, bOutSuccess);

uint8 ByteYaw = 0;
if ( Ar.IsSaving() )
ByteYaw = FRotator::CompressAxisToByte(Yaw);

uint8 NotZero = ByteYaw != 0;
Ar.SerializeBits( &NotZero, 1 );
    
if ( NotZero ) Ar << ByteYaw;
    else ByteYaw = 0;

if( Ar.IsLoading() )
{
Yaw= FRotator::DecompressAxisFromByte(ByteYaw);
}

return true;
}

这里就定义完毕了 FSyncInfo，显然需要一个 FSyncInfo 对 Player UID 的映射，打包成一个结构体 FPlayerSyncInfo。

一般使用 uint64 来保存 UID，可以简单的用额外的一个 bit 判断 UID 是否 > MAX_uint32，用来节省一些流量（也可以将 uint64 分为 4 个 16bit，用额外的 2bit 来判断在哪一段范围）

USTRUCT()
struct FPlayerSyncInfo
{
GENERATED_BODY()
FPlayerSyncInfo() = default;
FPlayerSyncInfo(uint64 UID, const FSyncInfo& SyncInfo)
: UID(UID), SyncInfo(SyncInfo) {};

bool NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess);

public:
uint64 UID;
FSyncInfo SyncInfo;
};


template<>
struct TStructOpsTypeTraits< FPlayerSyncInfo > : public TStructOpsTypeTraitsBase2< FPlayerSyncInfo >
{
enum 
{
WithNetSerializer = true,
WithNetSharedSerialization = true,
};
};

// ----------------------------------------

bool FPlayerSyncInfo::NetSerialize(FArchive& Ar, UPackageMap* Map, bool& bOutSuccess)
{
SyncInfo.NetSerialize(Ar, Map, bOutSuccess);

uint8 UID_IsHigh = UID > MAX_uint32;
Ar.SerializeBits(&IsHigh, 1)

if (UID_IsHigh)
{
Ar << UID;
}
else
{
uint32 UID_LowBits = (uint32)UID;
Ar << UID_LowBits;
UID = (uint64)UID_LowBits;
}

return true;
}

Collect Data

FPlayerSyncInfoContainer：

USTRUCT()
struct FPlayerSyncInfoContainer
{
GENERATED_BODY()

public:
FPlayerSyncInfoContainer() {};

bool NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess);
void PreReplication();
#endif

bool operator==(const FPlayerSyncInfoContainer& Other) const
    {
        return FrameCounter == Other.FrameCounter;
    }
bool operator!=(const FPlayerSyncInfoContainer& Other) const
{
return !(*this == Other);
}

private:
void CollectReplicateData();
    
private:
    // 控制同步频率
uint64 FrameCounter = 0;
uint32 PastFrameCounter = 1;

bool bHasCollectDataThisFrame = false;
    
    // 同步信息的数量（对应玩家个数）
uint32 InfoCount = 0;
    // Bit 流
TSharedPtr  WriterPtr;
    
    // Replicator
    TWeakObjectPtr <class APlayerSyncInfoReplicator> Replicator;
};

template<>
struct TStructOpsTypeTraits<FPlayerSyncInfoContainer> : public TStructOpsTypeTraitsBase2
{
enum
{
WithNetSerializer = true,
WithIdenticalViaEquality = true,
WithCopy = false,
};
};

在 PreReplication 中进行 CollectReplicateData；

通过 CVarPlayerSyncInfoReplicateFrameInternal 来控制同步的频率，记录 PastFrameCounter 用于记录过去了多少帧，用于后续判断；

void FPlayerSyncInfoContainer::PreReplication()
{
if (FrameCounter == GFrameCounter) return;
    
    PastFrameCounter = FMath::Clamp(GFrameCounter - FrameCounter, 1, CVarPlayerSyncInfoReplicateFrameInternal + 1);
FrameCounter = GFrameCounter;
bHasCollectDataThisFrame = false;

CollectReplicateData();
}

在 CollectReplicate 中进行数据收集与统计，将收集到的数据字节流写入 Writer：


void FPlayerSyncInfoContainer::CollectReplicateData()
{
if (!Replicator.IsValid()) return;
    
if (bHasCollectDataThisFrame) return;
bHasCollectDataThisFrame = true;

    if (!WriterPtr.IsValid())
    {
        WriterPtr = MakeShared();
        WriterPtr->SetAllowResize(true);
    }
    else
    {
        WriterPtr.Get()->Reset();
        InfoCount = 0;
    }

    FNetBitWriter* Writer = WriterPtr.Get();
    bool bOutSuccess = true;

    const auto SerializePlayerSyncInfo = [&](const auto& PlayerState)
    {
        if (!PlayerState.IsValid()) return;
        
        uint64 UID = PlayerState->GetUID();
        FVector Location = INVALID_LOCATION
        float Yaw = 0;
        if (APawn* PlayerPawn = PlayerState->GetPawn(); IsValid(PlayerPawn))
        {
            const FTransform& Transform = PlayerPawn->GetTransform();
            Location = Transform.GetLocation();
            Yaw = Transform.Rotator().Yaw;
        }

        FVector_NetQuantize SyncLocation(Location.X, Location.Y, Location.Z);
        FPlayerSyncInfo PlayerSyncInfo(UID, {SyncLocation, Yaw});
        PlayerSyncInfo.NetSerialize(*Writer, nullptr, bOutSuccess);
        InfoCount++;
    };


    for (const auto& PlayerState : PlayerArray)
    {
        SerializePlayerSyncInfo(PlayerState);
    }
}

Serialize

对于每一个 Player 的 Connection，判断其是否满足同步帧数限制，每次 NetSerialize ，将 ConnectionDriver->NextReplicateFrameCount -= PlayerSyncInfoContainer.PastFameCounter，若 <= 0 则重置其 NextReplicateFrameCount 为 CVarPlayerSyncInfoReplicateFrameInternal，并认为本次需要对该 Connection 进行同步；若需要同步，将 Writer 中的数据进行序列化；

在反序列化时，找到对应的 Player，将数据设置到其 PlayerState 中；

bool FPlayerSyncInfoContainer::NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess)
{
if (Ar.IsSaving())
{
auto PackageMapClient = Cast(Map);
auto Connection = PackageMapClient->GetConnection();
auto ConnectionDriver = Connection->GetReplicationConnectionDriver();
        
        bool bNeedReplicate = false;
        
        if (ConnectionDriver->NextReplicateFrameCount <= 0)
        {
            bNeedReplicate = true;
            ConnectionDriver->NextReplicateFrameCount = CVarPlayerSyncInfoReplicateFrameInternal
        }


        if (bNeedReplicate)
        {
            Ar.SerializeIntPacked(InfoCount);
            Ar.SerializeBits(WriterPtr->GetData(), WriterPtr->GetNumBits());
        }
        else
        {
            uint32 Count = 0;
            Ar.SerializeIntPacked(Count);
        }
        
        bOutSuccess = true;
}
else
{
        // 将收集到的数据同步到客户端，在客户端进行数据的反序列化，
uint32 Count = 0;
Ar.SerializeIntPacked(Count);
if (Count == 0) return true;

        // 记录当前收包累计次数，用于预测等
const uint64 FrameNum = ++GDSPlayerSyncInfoReplicateFrameNum;
for (int Index = 0; Index < Count; Index++)
{
FPlayerSyncInfo PlayerSyncInfo;
PlayerSyncInfo.NetSerialize( Ar, Map, bOutSuccess );

uint64 UID = PlayerSyncInfo.UID;
if (auto PlayerState = GET_PLAYERSTATE_BY_UID(UID))
{
PlayerState->SetPlayerSyncInfo(PlayerSyncInfo);
}
}
}

return true;
}

Client Predict

对于 Client，会间隔收到 3P 的 PlayerSyncInfo，同时在收包的时候记录了帧号。

对于比如 Location 这样的数据，显然需要保证其连续性。

于是可以根据这些信息做一个简单的预测：

在 Client 存在 Pawn 时，直接使用 Pawn 的位置，并且强制更新预测与期望；
在收到一个新包 CurrentBack 时，使用 PrePack -> CurrentBack 的 LocationDiff / PreFrameInternal 计算出一个新的预测速度 PredictCalcDeltaSyncLocationVelocity，同时可以根据实际情况 * SpeedFactor 来进行适当修改；
每次 GetSyncLocation 时尝试更新预测信息，在当前帧 CurrentFrame，利用 PredictCalcDeltaSyncLocationVelocity * FrameInternal 来外推当前所在 Location，这里的 FrameInternal 是从上一次预测帧 LastPredictFrame 开始经过的帧数，预测完毕更新 LastPredictFrame；
如果当前位置和预测期望位置太远，则直接设置为期望位置，不进行插值；

flowchart LRA(PrePack)B(CurrentBack)C(NextBack)Last([LastPredictFrame])Now([CurrentFrame])A---->|PreFrameInternal| BB-->|Internal|LastLast-->|Internal|NowNow-..->C

void APlayerState::SetSyncLocation(FVector InSyncLocation, int32 CurrentFrameNum)
{
    bool bEnableSet = EnableSetSyncLocation();
    
    if (bEnableSet)
    {
        // --- Predict
        int64 DeltaFrameCount = UKismetSystemLibrary::GetFrameCount() - SyncLocationFrameCount;
        float SpeedUpFactor = 1.05f;
        PredictCalcDeltaSyncLocationVelocity = DeltaFrameCount <= 0 ? 0.0f : FVector::Dist(InSyncLocation, ActorSyncLocation) / DeltaFrameCount * SpeedUpFactor;

        // --- UpdateLocation
        ActorSyncLocation = InSyncLocation;
    }
    else
    {
        PredictCalcDeltaSyncLocationVelocity = 0.0f;
    }
    
    // --- UpdateFrame
SyncLocationUpdateFrameNum = CurrentFrameNum;
SyncLocationFrameCount = UKismetSystemLibrary::GetFrameCount();
}

bool APlayerState::EnableSetSyncLocation() const
{
    // if WeakNet then Disable...
    return true;
}

FVector APlayerState::GetSyncLocation()
{
if (APawn* Pawn = GetPawn(); IsValid(Pawn))
{
        FVector Location = Pawn->GetTransform().GetLocation();
        ActorSyncLocation.Set(Loc.X, Loc.Y, Loc.Z);
        UpdatePredictSyncLocation(ActorSyncLocation, true);
        return ActorSyncLocation;
}

    // 判断是否正常发包，若新的 PlayerSyncInfoPack 中无该 PlayerState 则不采用预测信息
if (GDSPlayerSyncInfoReplicateFrameNum == SyncLocationUpdateFrameNum && SyncLocationUpdateFrameNum != 0)
{
UpdatePredictSyncLocation(ActorSyncLocation);
return PredictSyncLocation;
}

return InvalidSyncLocation;
}


void APlayerState::UpdatePredictSyncLocation(FVector InLocation, bool bForce)
{
int64 CurrentFrame = UKismetSystemLibrary::GetFrameCount();
    
    // 强制更新预测信息
if (bForce == true)
{
LastPredictCalcLocationFrameCount = CurrentFrame;
PredictSyncLocation = InLocation;
        PredictCalcDeltaSyncLocationVelocity = 0.0f;
return;
}

int64 DeltaFrame = CurrentFrame - LastPredictCalcLocationFrameCount;
if (DeltaFrame <= 0) return;

// 预测速度为 0 / 距离超过 DistanceLimit，直接传送
if ( FMath::IsNearlyEqual(PredictCalcDeltaSyncLocationVelocity, 0.0f) || FVector::DistSquared(PredictSyncLocation, InLocation) >= PredictSyncLocationDistanceLimitSquared)
{
PredictSyncLocation = InLocation;
}
else
{
PredictSyncLocation += DeltaFrame * (InLocation - PredictSyncLocation).GetSafeNormal() * PredictCalcDeltaSyncLocationVelocity;
}

LastPredictCalcLocationFrameCount = CurrentFrame;
}

这样，就可以得到一个相对丝滑的 Location 信息。

ACT浅思

2024-04-23T16:00:00.000Z

ACT浅思

ACT 表现

动作

动作节奏：

flowchart LR前摇--->攻击判定--->后摇-->后摇-可打断

需要控制好每个阶段的时间分配，表现不同的节奏；

较长的后摇可以方便玩家明确下一步操作（不攻击、打断后摇继续攻击），判定更明确；
较短的后摇可以增加动作连续性连续，提升手感；

动画配合：

动画曲线配合：从动画中提取曲线，配合曲线调整位移；比如移动，需要在脚落下的那一刻位移速度最大，其余阶段几乎不位移；

攻击方、受击方动画、位移需要匹配；

动作设计：

Anticipation & Follow Through：预期、跟随；在确定性的时间做更多奖励性的动作演出，此时玩家会更加专注，比如支援突击等玩家主动触发的明确时刻；利用跟随增强动画流畅感和力量感，比如格挡时的强化慢镜头，利用一些跟随，同时提供反应时间；再比如局外人物展示界面，在结束阶段利用衣物飘带、尾巴等动力学变化强化演出效果；

Slow In / Slow Out：慢入、快速表演、慢出；同时可以增加蓄力抖动等加强压迫感；

Exaggeration & Strong Posing：夸张和强烈的动作；比如跳跃使用后空翻，提升视觉效果；受击动作，也可以有夸张的表现，具体在硬直、击退、击飞等；同时可以添加骨骼抖动强化反馈；

爽感优化

顿帧：伤害越大顿帧越久，一般发生在攻击方接触受击方、技能或连招开始与结束时；

连招：较长的连招（意味着更大的风险）过后，可以添加夸张的收尾表演，释放压力；

终结技：目标强僵直、残血时可以添加慢镜头终结技；

镜头

运镜逻辑：

镜头内容：需要保证全程看清目标，更多以目标为核心；需要保证目标完整在镜头内（尤其是使用大位移技能时）；尽量避免主角与目标重叠；

镜头构图：可以稍微错位，可以看清目标动作；

镜头效果：

屏幕震动：普攻可以增加左右偏移、重击增加上下纵深偏移；

子弹时间：在合适的时候增加子弹时间，可以表现出力量感；

镜头模糊：径向模糊、动态模糊、空气扭曲等效果；可以表现出速度感；

UI

HUD 的缩放、偏移、光效；
屏幕闪屏：在使用技能或击杀目标时，可以增加闪屏或者黑屏淡入淡出等效果；
准心变化：颜色、大小、特殊形态（骷髅表示击杀、打叉表示命中或爆头）；
跳字：分为普攻、暴击、恢复；主要调整：轨迹（抛物线、弹出、上浮）、缩放、透明度、重力、字体、颜色；比如暴击一般离散范围小、上浮位移大、爆发力可以更强；
连击提示：与击打节奏契合；
受击指向：被攻击的方向；

特殊效果

特效：

普通特效：技能本身效果（武器发光等），保证和场景颜色差异够大；
粒子特效：与目标解除时出现命中/防御/暴击等粒子表现；场景破碎效果等；
环境特效：对环境的氛围影响，场景灯光、场景变色；
角色特效：角色自身的发光等表现；

音效：在进行指定行为时，需要有特定音效反馈，比如冲击、发射、受击等；
背景音乐：战斗和漫游需要有不同的音乐变化；
物理震动：手柄、手机的震动反馈；

ACT 数值

攻击方

基本属性：攻击力、暴击率、属性加成；
攻击范围：
1. 自身：关注攻击碰撞盒，方向、距离、范围等；
2. 抛射物：关注触发方式（时间、瞄准方式）、轨迹等；
攻击强度：
1. 进攻强度：与对方防御强度对比，决定对对方造成的伤害与效果；
2. 维持强度：保证攻击完整的能力，与敌方进攻强度对比，决定攻击是否会被对方攻击打断；
3. 命中效果：硬直时间（防御、命中），特殊表现（击飞、倒地）
攻击节奏：前摇、生效（判定时间、持续时间）、后摇
攻击位移：水平位移、空中位移

防守方

基本属性：防御值、护甲、抗性、伤害减免；
防守范围：
1. 受击判定：是否进行判定（硬直）、无敌帧
2. 受击范围：受击碰撞盒、防守碰撞盒
防守强度：
1. 格挡：格挡强度、格挡范围、移动距离
2. 闪避：移动距离、无敌时间、后摇硬直时间
3. 反击：允许反击的时间与状态、无敌时间、硬直时间
防守体力：
1. 体力上限：最大体力值，受到攻击、进行防守等行为会降低体力，体力为 0 会进入硬直
2. 体力恢复：脱战恢复体力

参考

拳打冥王脚踢地府——《黑帝斯》战斗设计分析

最畅爽的打击感从何而来？

《战双帕弥什》的动作打击感是怎么做出来的

《层层梦境》：小型独立团队如何打造杀手级战斗系统

[UE]Networking源码浅析

2024-04-19T16:00:00.000Z

Networking源码浅析

定义

Bunch：表示一组相关的网络数据，包含 RPC / 属性同步 等信息，UE 中 DS/Client 通信的基本单位。

Packet：UDP 的基本传输单位，可以打包一个或多个 Bunch，在接受端进行解析。

NetDriver：管理网络通信，比如管理连接、处理数据包的发送和接收、处理网络事件。

NetConnection：表示一个网络连接，与一个 NetDriver 关联，并通过 NetDriver 进行实际的网络通信。

Channel：管理网络传输，进行数据分类，提供 SendBunch、ReceivedRawBunch 方法，由 NetConnection 管理，一个 NetConnection 可以包含多种 Channel。

FObjectReplicator：处理对象的网络同步，保存属性快照，进行状态改变发送、更新同步状态、接受与发送消息。

ActorChannel：关联特定的 Actor 负责其同步，包含多个 FObjectReplicator 用于复制其 Actor、ActorComponent 。

FRepLayout：管理复制的属性，定义底层数据内存布局，数据比较、序列化与反序列化等。

RPC

Server RPC

Calling Machine	Owning Connection	Executing Machine
Server	Client	Server
Server	Server	Server
Server	None	Server
Client	Invoking Client	Server
Client	Different Client	Dropped
Client	Server	Dropped
Client	None	Dropped

Client RPC

Calling Machine	Owning Connection	Executing Machine
Server	Owning Client	Owning Client
Server	Server	Server
Server	None	Server
Client	Invoking Client	Invoking Client
Client	Different Client	Invoking Client
Client	Server	Invoking Client
Client	None	Invoking Client

NetMulticast RPC

Calling Machine	Owning Connection	Executing Machine
Server	Client	Server and all Clients the invoking actor is relevant for
Server	Server	Server and all Clients the invoking actor is relevant for
Server	None	Server and all Clients the invoking actor is relevant for
Client	Invoking Client	Invoking Client
Client	Different Client	Invoking Client
Client	Server	Invoking Client
Client	None	Invoking Client

Send RPC

flowchart TBUObject::ProcessEvent-- FunctionCallspace::Remote --> AActor::CallRemoteFunction--> UNetDriver::ProcessRemoteFunctionServerMulticast(bIsServerMulticast)UNetDriver::ProcessRemoteFunction--> ServerMulticastServerMulticast--TRUE-->UNetDriver::GetFunctionRepLayout--Actor IsNetRelevant || FUNC_NetReliable --> FRepLayout::BuildSharedSerializationForRPC--> UNetDriver::InternalProcessRemoteFunctionPrivate--> UNetDriver::ProcessRemoteFunctionForChannelPrivateServerMulticast--FALSE--> UReplicationGraph::ProcessRemoteFunction--> UNetDriver::ProcessRemoteFunctionForChannel--> UNetDriver::ProcessRemoteFunctionForChannelPrivate-- FRepLayout::SendPropertiesForRPC --> QueueBunchQueueBunch(!bReliable & NetMulticast)QueueBunch--TRUE-->UChannel::SendBunchQueueBunch--FALSE-->UActorChannel::QueueRemoteFunctionBunch

Receive RPC

flowchart TBUIpNetDriver::TickDispatch--> UNetConnection::ReceivedRawPacket--> UNetConnection::ReceivedPacket--> UNetConnection::DispatchPacket--> UChannel::ReceivedRawBunch--> UChannel::ReceivedNextBunch--> UChannel::ReceivedSequencedBunch--> UActorChannel::ReceivedBunch--> UActorChannel::ProcessBunch--> FObjectReplicator::ReceivedBunch-- FObjectReplicator::ReceivedRPC--> UObject::ProcessEvent

属性同步

Replicate Diff

flowchart TBUNetDriver::TickFlush--> UNetDriver::ServerReplicateActors--> UActorChannel::ReplicateActor--> FObjectReplicator::ReplicateProperties--> FNetSerializeCB::UpdateChangelistMgr--> FRepLayout::UpdateChangelistMgr--> FRepLayout::CompareProperties

Replicate Send

flowchart TBUNetDriver::TickFlush--> UNetDriver::ServerReplicateActors--> UActorChannel::ReplicateActor--> FObjectReplicator::ReplicateProperties--> FRepLayout::ReplicateProiperties--> FRepLayout::SendProperties--> FProperty::NetSerializeItem--> UChannel::SendBunch

Replicate Receive

flowchart TBUIpNetDriver::TickDispatch--> UNetConnection::ReceivedRawPacket--> UNetConnection::ReceivedPacket--> UNetConnection::DispatchPacket--> UChannel::ReceivedRawBunch--> UChannel::ReceivedNextBunch--> UChannel::ReceivedSequencedBunch--> UActorChannel::ReceivedBunch--> UActorChannel::ProcessBunch--> FObjectReplicator::ReceivedBunch--> FRepLayout::ReceiveProperties--> FRepLayout::ReceivePropertyHelper--> FProperty::NetSerializeItem--> FObjectReplicator::PostReceivedBunch--> FObjectReplicator::CallRepNotifies

[UE]弱网工具Clumsy的使用

2024-04-13T16:00:00.000Z

弱网工具Clumsy的使用

Clumsy 用于弱网测试时，进行本地弱网环境的模拟，基于 WinDivert 实现，可以出模拟延迟、丢包等网络状态。

Downloads

下载地址：Clumsy；官方文档：Clumsy Manual

下载后的几个重点文件：

打开 Clumsy.exe 可以看到以下内容：

可以看出这里有几个重点的 Function，一般重点使用 Lag 延迟、Drop 丢包。

在 Filtering 填入对应的 Command 后，设置 Functions，点击 Start 即可开始模拟。

同时可以在 Config.txt 中，预设一些 Presets 方便下次使用。

UE DS 中的使用

对于 UE的 DS 环境，首先为了具体到某一个 Client / DS，采用 Filter Port 的机制，对某个具体的端口号进行操作。

用 netstat -aon\Findstr 进程ID，查询 DS/Client 进程，通过 UDP 进行链接。

DS 的 port 一般可以在启动命令中找到 -port=17777；

Client 的 port 可以在 DS 的 Log 中，快速查询到对应与指定 Client 连接的对应端口号：

// DS.log
LogNet: NotifyAcceptedConnection: Name: TestMap, TimeStamp: 04/14/24 00:00:00, [UNetConnection] RemoteAddr: 127.0.0.1:58459, Name: IpConnection_0, Driver: GameNetDriver NetDriver_1, IsServer: YES, PC: NULL, Owner: NULL, UniqueId: INVALID
LogNet: AddClientConnection: Added client connection: [UNetConnection] RemoteAddr: 127.0.0.1:58459, Name: IpConnection_0, Driver: GameNetDriver NetDriver_1, IsServer: YES, PC: NULL, Owner: NULL, UniqueId: INVALID

这里的 **58459** 也就是该 `Client` 的 `Connetcion` 对应的端口号。在 `Filtering` 中填入对应的设置即可：1. 关闭上行包：`udp and udp.SrcPort == 58459` ，设置 `Drop = 100%`2. 关闭下行包：`udp and udp.DstPort == 58459`，设置 `Drop = 100%`

[UE]夺旗模式框架

2024-03-19T16:00:00.000Z

夺旗模式框架

描述

夺旗模式：

场景里会按照一定的规则刷新出不同类型的旗帜（不同类型的旗帜有不同的得分、血量、表现等）；

玩家会被分成若干个队伍，抢夺刷新出来的旗帜，将旗帜带到自己队伍目标点进行销毁，则可以获得分数；

玩家持有旗帜时，旗帜可能会掉落或被抢夺：被其它玩家撞击到则旗帜被抢夺到其它玩家身上；旗帜的血量归零则会掉落回场景；

有正式赛与加时赛两种类型的比赛，首先会开启正式赛；对于正式赛，率先达到目标分的队伍获胜；如果平局则开启加时赛，否则进行结算；对于加时赛，率先得分的队伍获胜，如果平局则以两队平局进行结算；

要点总结：

旗帜实体：旗帜本身有自己的类型、得分、血量；
旗帜刷新：场景内根据一定规则（倒计时刷新、旗子上缴）会刷出不同类型旗帜；
旗帜传递：玩家可以拾取场景里的旗帜、相互抢夺旗帜、掉落旗帜（持有旗帜血量归零）、将旗帜送给终点得分等；玩家可以组队，共享队伍得分；同队伍之间的玩家可以传递旗帜；
单局流程：所有玩家就绪分队后，传送到起始点准备开赛；如果一局比赛平分，一定条件下可以触发下一场比赛继续；

模式基础

单局流程

首先，一个完整的夺旗赛，由若干个子比赛构成，子比赛逐渐推进；

flowchart LRM[MainProcess]R0[RaceProcess_0]R1[RaceProcess_1]R2[RaceProcess_2]M-->R0M-->R1M-->R2R0-.->R1R1-.->R2

比赛胜负规则：

单场比赛结束时，判定是否有一方队伍得分更高：
如果有，则全局结束；
如果没有，尝试进入下一场比赛（如果有配置的话），若没有下一场则全局结束；
正式赛：比赛结束条件：有一队达到目标分 / 倒计时结束
加时赛：比赛结束条件：有一队得到分数 / 倒计时结束
其它类型比赛……

局内玩法

从业务出发，先明确有哪些相关逻辑：

最基本的交互显然是：

flowchart LRF0[场景旗帜_0]F1[场景旗帜_1]G0([目标点_0])G1([目标点_1])P0[[Player_0]]P1[[Player_1]]F0--PickUp--->P0--Drop-->F0P0--Reach--->G0P0<--Strike--->P1

PickUp：Player 触碰到 场景旗帜 ，就可以拾取该旗帜到自己身上；
Drop ：Player 持有的旗帜存在血量，其血量归零（可能是被其它 Player 攻击导致扣血），就会触发旗帜的掉落，在对应位置生成场景旗帜；
Reach：Player 将持有的旗帜护送到 目标点，获得分数，同时该旗帜会被销毁；
Strike：Player 撞击另一个 Player，可以抢夺对方的旗帜；

业务拆分

首先，先给出基本的一些元素定义；

游戏玩法的本质是由刷新点刷新出旗帜，旗帜在各个部分之间交互传递，旗帜本身定义为 FlagItem。
旗帜在场景（不在 Player 身上）里的表现为，存在对应的 FlagSceneItem。
场景里存在若干个终点，定义该终点为 GoalPointSceneItem

这里说的交互的本质实际上是一个 Flag 的 Instance 在 各个部分 之间的传递。想一下所谓的 各个部分，到底是什么？

本质可以抽象为一个个持有 Flag 的容器，将其定义为 FlagContainer。

这里显然有三种 Container：

Container_WorldFlag：定义 WorldFlag 为 没有被 Player 持有的旗帜
Container_GoalPoint：定义 GoalPoint 为目标点
Container_Player：每个 Player 持有一个 Container；

细想一下， WorldFlag 、GoalPoint 的具体业务逻辑和具体的某个 Instance 没有太大关系，只需要通过 ID 串联即可，所以对于 WorldFlag、GoalPoint，不需要真的在每一个 Instance 都创建对应 Container，只需要一个单局管理的唯一 Manager 用来代替管理即可。但显然对于每个 Player 都需要有自己的 Container。

可以在单局内创建全局唯一的 Container_WorldFlag 、Container_GoalPoint 实例。

flowchart TDF0[FlagSceneItem_0]F1[FlagSceneItem_1]F2[FlagSceneItem_2]subgraph WorldFlag[Container_WorldFlag]    direction LR    F0-.-F1-.-F2endG0([GoalPoint_0])G1([GoalPoint_1])G2([GoalPoint_2])subgraph GoalPoint[Container_GoalPoint]    direction LR    G0-.-G1-.-G2endP0[[Container_Player_0]]P1[[Container_Player_1]]WorldFlag--PickUp--->P0--Drop--->WorldFlagP0--Reach--->GoalPointP0<--Strike--->P1

这样就可以将交互的逻辑拆得非常简单了：

PickUp ：由 FlagSceneItem 和 Player 的 Overlap 触发，将 Container_WorldFlag 持有的对应该 FlagSceneItem 的 FlagItem ，传递给这个 Player 的 Conatiner_Player
Drop ：由 Player 的血量变化归零触发，将 Container_Player 上的所有 FlagItem 转移给 Cotainer_WorldFlag
Reach：由 Player 和 GoalPointSceneItem 的 Overlap 触发，将 Container_Player 上的所有 FlagItem 转移给 Cotainer_GoalPonit
Strike：由 Player0 和 Player1 的撞击触发，将 Container_Player 上的所有 FlagItem 转移给 Cotainer_Player1

这里的 PickUp、Drop、Reach、Strike 是这张图的边，将其定义为 TransferPolicy。

对于 Container，有各自的 Add(FlagItem)、Remove(FlagItem)，一些基本逻辑：

Container_WorldFlag：
AddItem ：从 FlagItem 上取出位置，将 Item 血量设置为满血，通过调用 FlagSceneItemManager 创建出 FlagItem 对应的 FlagSceneItem；
RemoveItem：调用 FlagSceneItemManager 删除对应的 FlagItem 对应的 FlagSceneItem；

Container_GoalPoint：
AddItem：判断是从哪个 Container 来的，给对应 Player 加分，并且 RemoveItem；
RemoveItem ：销毁对应的 FlagItem；

Container_Player：
AddItem：从 FlagItem 获得 FlagSyncData 同步给自己，并设置 Player 血量为 Item 的血量等逻辑；
RemoveItem：将 Player 血量设置给 Item 血量，清空同步信息等逻辑；

完整的业务拆分完毕，这下需要哪些系统显而易见：

ProcessSystem：负责管理单局流程，创建比赛与推动玩法进程；
TeamSystem ：负责 Player 的组队，管理 Memebr、Score 等；
FlagItemSystem：负责管理所有 FlagItem 实例，提供 Create、Destroy 等方法，维护 Item 基本的生命周期；
ContainerSystem：负责提供基本的 CreateContainer、DestoryContainer 方法，对于具体的 Container，需要支持 AddItem 、RemoveItem、GetItem 等；
TransferSystem：负责管理所有的 TransferPolicy ，提供 TransferItem 方法；
FlagSpawnerSystem：旗帜的刷新点，负责 WorldFlag 的生成，生成 FlagItem 并 Add 到 Container_WorldFlag；
SceneItemSystem ：维护场景里 SceneItem 的生成，提供 Create、Destroy 对应的 SceneItem 的方法；对于某个具体的 SceneItem，需要实现基础的 Overlap、Sync；

具体实现

`ProcesSystem`

首先需要一个挂在 GameState 上的 MainProcess 负责管理全局的流程，串联多个 RaceProcess 推进玩法；

显然，一个最简单的流程可以这样：

flowchart LRM[MainProcess]R0[RaceProcess_0]R1[RaceProcess_1]F[Finish]M---->|1. 开赛|R0R0-.->|2. Result_0|MM-->|3. Check_Result_0|R1R1-.->|4. Result_1|MM-->|5. Check_Result_1|FR0-.->R1R1-.->F

但是这样循环流程需要在 Main 里面关注 RaceProcess 给出的 Result 事件，显然有点不够优雅。

发现这里的主要由两部分组成：

RaceProcess 管理子比赛流程，给出 Result
MainProcess 接受子比赛 Result，校验并判断开启下一场 Race 或者结束比赛

所以可以将其拆成两个 Controller：

MainProcess 负责提供 Dispatch 的功能，

FinishRace_Controller：监听 Dispatcher 的 开赛 事件，并向 Dispatcher 分发 单局结束事件；
CreateRace_Controller：监听 单局结束 事件，进行处理并向 Dispatcher 分发开赛 事件；

flowchart TBM[MainProcess]D[Dispatcher]F[FinishRace_Controller]C[CreateRace_Controller]M-->DF-->|Send_Finsih|DD-.->|Register_Create|FC-->|Send_Create|DD-.->|Register_Finish|C

`TeamSystem`

参考 [UE] TeamSystem 框架

支持玩家的 加入、退出 队伍，以及维护队伍的各种数据（比如 Members、Score），并维护数据，进行同步。

`SceneItemSystem`

classDiagram    UCFSceneItemUtils..>UCFSceneItemManager        UCFSceneItemManager..>UCFScecneItemBase    class UCFSceneItemManager {    frien UCFSceneItemUtils    - CreateItem(Type, UID, Params)    - DestroyItem(UID)    }        UCFScecneItemBase..*UCFScecneItemSyncComponent    UCFScecneItemBase..*UCFScecneItemDisplayComponent    class UCFScecneItemBase {    SyncComponent : UCFScecneItemSyncComponent    OverlapDelegate    # OnInit()    # OnUninit()    # BeginDetect()    # EndDetect()    + CollectSyncData()    }        UCFScecneItem_WorldFlag--|>UCFScecneItemBase    UCFScecneItem_GoalPoint--|>UCFScecneItemBase

首先，需要 UCFSceneItemManager 负责管理所有的 SceneItem，同时通过 UCFSceneItemUtils 提供方法给外部调用。

对于一个具体的 SceneItem，额外对其提供两个 Component，

SyncComponent：在 DS/Client 生成，维护 SceneItem 的同步数据，这一部分数据不会被 AOI 裁剪，保证远距离的数据同步；
DisplayComponent：仅在 Client 生成，随着 SceneItem 被 AOI，用于实现客户端表现。

`FlagItemSystem`、`ContainerSystem`

classDiagramdirection LRUCaptureFlagItemSystem..>FCaptureFlagItem    class UCaptureFlagItemSystem {    ItemInstances : TMap~uint64|TSharedPtr~FCaptureFlagItem~~    + CreateItem(ItemID)    + DestroyItem(ItemUID)    + GetItem(ItemUID)    - GenerateUID()    - RegisterClearTimer()    - UnregisterClearTimer()    - ClearAllItems(bCheckUnused)    }        %% ----- FlagItem -----        namespace FlagItem {        class FCaptureFlagItem        class FCaptureFlagItemSyncData    }        FCaptureFlagItem..FCaptureFlagItemSyncData    FCaptureFlagItem..UCaptureFlagContainerBase    class FCaptureFlagItem {    + InitItem(InUID, ItemID)    + GetSyncData() : FCaptureFlagItemSyncData    + UID / ItemID / Type / Health / MaxHealth...    + Container : TWeakObjectPtr~UCaptureFlagContainerBase~    + TransferReason : ECFTransferReason    }        class FCaptureFlagItemSyncData {    + UID / ItemID / Type / Health / MaxHealth / TransferReason    }        %% ----- FlagContainer -----        namespace FlagContainer {    class UCaptureFlagContainerBase    class UCaptureFlagContainer_WorldFlag    class UCaptureFlagContainer_GoalPoint    class UCaptureFlagContainer_Player    }        class UCaptureFlagContainerBase {    Items : TMap ~uint64|TWeakPtr~FCaptureFlagItem~~    Owner : TWeakObjectPtr~UObject~    + Init(InOwner)    + Uninit()    + AddItem(TWeakPtr~FCaptureFlagItem~Item, Params)    + RemoveItem(TWeakPtr~FCaptureFlagItem~ Item)    + VerifyCanAddItem()    + GetType() : ECFContainerType    # OnInit()    # OnUninit()    # OnAddItem(TWeakPtr~FCaptureFlagItem~Item, Params)    # OnRemoveItem(TWeakPtr~FCaptureFlagItem~ Item)    }        UCaptureFlagContainer_WorldFlag--|>UCaptureFlagContainerBase    UCaptureFlagContainer_GoalPoint--|>UCaptureFlagContainerBase        UCaptureFlagContainer_Player--|>UCaptureFlagContainerBase    class UCaptureFlagContainer_Player{    # GetType() : ECFContainerType        }        %% ----- ContainerOwner -----        namespace ContainerOwner {    class UCaptureFlagManager    class UCaptureFlagComponent    class ICaptureFlagContainerOwnerInterface    }            UCaptureFlagManager..>UCaptureFlagContainer_GoalPoint    UCaptureFlagManager..>UCaptureFlagContainer_WorldFlag    UCaptureFlagManager..|>ICaptureFlagContainerOwnerInterface    class UCaptureFlagManager{    - WorldFlagContainer    - GoalPointContainer    + GetWorldFlagContainer()    + GetGoalPointContainer()    }        UCaptureFlagComponent..|>ICaptureFlagContainerOwnerInterface    UCaptureFlagComponent..>UCaptureFlagContainer_Player    UCaptureFlagComponent..>FCaptureFlagItemSyncData    class UCaptureFlagComponent{    - FlagContainer_Player    - FlagItemSyncData : FCaptureFlagItemSyncData    + GetCaptureFlagContainer()    + UpdateFlagItemSyncData(SyncData)    }        ICaptureFlagContainerOwnerInterface..>UCaptureFlagContainerBase    class ICaptureFlagContainerOwnerInterface{    CreateFlagContainer(InOwner)    DestroyFlagContainer(Container)    }

首先，需要一个 FlagItemSystem 负责管理所有的 FlagItem 实例。提供基本的创建、销毁、查询功能的同时，这个 FlagItemSystem需要 RegisterClearTimer，每隔一段时间，Clear 不被任何一个 Container 持有的 Item。

// UCaptureFlagItemManager

TWeakPtr UCaptureFlagItemManager::CreateItem(int ItemID)
{
auto NewItem = MakeShared();
NewItem->Init( GenerateUID(),  ItemID );
ItemInstances.Add( NewItem->GetUID(), NewItem );

NotifyItemCreated(NewItem);
return NewItem;
}

void UCaptureFlagItemManager::DestoryItem(uint64 ItemUID)
{
if (!ItemInstances.Contains(ItemUID)) return;

auto Item = ItemInstances.FindRef(ItemUID);
if (Item.IsValid())
{
if (Item->GetContainer().IsValid())
{
// 先从 Container 上移除
Item->GetContainer()->RemoveItem(Item);
}
}
ItemInstances.Remove(ItemUID);
}

void UCaptureFlagItemManager::ClearAllItems(bool bUnused)
{
TArray  ItemUIDs;
ItemInstances.GetKeys(ItemUIDs);
for (auto ItemUID : ItemUIDs)
{
auto Item = ItemInstances.FindRef(ItemUID);
if (!Item.IsValid()) return;

if ( bUnused == false
|| /*未被任何 Container 持有*/ Item->GetContainer().IsValid() == false)
{
DestoryItem(ItemUID);
}
}
}

对于 FlagItem，保存 Flag 最基本的信息，同时提供一个 CollectSyncData，用于生成对应的 FlagSyncData，表示需要同步的数据，在 ContainerOwner 需要的时候进行数据同步。

// FlagItem.h

#define GENERATE_CAPTUREFLAG_ITEM_PROPERTY(Visibility, Type, Name) \
public: Type Get##Name() const { return Name; } \
public: void Set##Name(const Type& Value) { Name = Value; } \
Visibility: Type Name


// 需要在 FCaptureFlagItem::GetSyncData 中打包数据

USTRUCT()
struct FCaptureFlagItemSyncData
{
GENERATED_BODY()

FCaptureFlagItemSyncData() = default;

public:
FString ToString() const;
bool operator==(const FCaptureFlagItemSyncData& Other) const;
bool operator!=(const FCaptureFlagItemSyncData& Other) const
{
return !(*this == Other);
}

public:
UPROPERTY()
uint64 UID = 0;
UPROPERTY()
int ItemID = 0;
UPROPERTY()
int Type = 0;
UPROPERTY()
float Health = 0.0f;
UPROPERTY()
float MaxHealth = 0.0f;
UPROPERTY()
ECFTransferReason TransferReason;
};


struct FCaptureFlagItem
{

virtual ~FCaptureFlagItem() = default;

public:
void Init(uint64 InUID, int ItemID);
FCaptureFlagItemSyncData GetSyncData() const;

public:
FString ToString() const;

public:
GENERATE_CAPTUREFLAG_ITEM_PROPERTY(private, uint64, UID);

GENERATE_CAPTUREFLAG_ITEM_PROPERTY(private, int, ItemID);
GENERATE_CAPTUREFLAG_ITEM_PROPERTY(private, int, Type);
GENERATE_CAPTUREFLAG_ITEM_PROPERTY(private, float, Health);
GENERATE_CAPTUREFLAG_ITEM_PROPERTY(private, float, MaxHealth);
GENERATE_CAPTUREFLAG_ITEM_PROPERTY(private, int, Score);

GENERATE_CAPTUREFLAG_ITEM_PROPERTY(private, ECFTransferReason, TransferReason);
GENERATE_CAPTUREFLAG_ITEM_PROPERTY(private, TWeakObjectPtr, Container);
};

需要 Container 来持有 FlagItem，在 AddItem 和 RemoveItem 内写具体的逻辑。

每种 Container 通过重载 UCaptureFlagContainerBase 的 PURE_VIRTUAL 方法 GetType 来定义其类型。

// ContainerBase.h

UCLASS(Abstract)
class UCaptureFlagContainerBase : public UObject
{
GENERATED_BODY()

friend class UCaptureFlagItemUtils;

public:
virtual ECFContainerType GetType() PURE_VIRTUAL( UCaptureFlagContainerBase::GetType, return ECFContainerType::None; ) // 设置 ContainerType
virtual bool VerifyCanAddItem();
virtual void CollectParams(FCaptureFlagParams& Params);

private:
bool CheckCapcityValid();

public:
void Init(UObject* InOwner);
void Uninit();

public:
bool AddItem(TWeakPtr Item, const FCaptureFlagParams& Params = {});
bool RemoveItem(TWeakPtr Item);
TArray > GetAllItems();
TWeakPtr GetItem(uint64 ItemUID) const;
void ClearItems();

protected:
// 各个 Container 自定义逻辑
virtual void OnInit() {}
virtual void OnUninit() {}
virtual void OnAddItem(TWeakPtr Item, const FCaptureFlagParams& Params) {};
virtual void OnRemoveItem(TWeakPtr Item) {};

protected:
TMap > Items {};
TWeakObjectPtr  Owner = nullptr;
};

// ContainerBase.cpp

bool UCaptureFlagContainerBase::AddItem(TWeakPtr Item, const FCaptureFlagParams& Params)
{
if (!Owner.IsValid() || !Item.IsValid()) return false;

uint64 ItemUID = Item.Pin()->GetUID();
if (Item.Pin()->GetContainer().IsValid())
{
// Item 只能被放在一个 Container 内
return false;
}

// 检查是否可以获得
if (VerifyCanAddItem() == false)
{
return false;
}

Item.Pin()->SetContainer( this );
Items.Add( ItemUID, Item );

OnAddItem(Item, Params);
return true;
}

bool UCaptureFlagContainerBase::RemoveItem(TWeakPtr Item)
{
if (!Owner.IsValid() || !Item.IsValid()) return false;

uint64 ItemUID = Item.Pin()->GetUID();
if (!Items.Contains(ItemUID))
{
return false;
}

Item.Pin()->SetContainer(nullptr);
Items.Remove(ItemUID);
OnRemoveItem(Item);

return true;
}

每个 Container 需要一个 ContainerOwner 来持有，这里有三种 Container。

Container_WorldFlag：由 CaptureFlagManager(GS) 持有，一场子比赛持有一个；
Container_GoalPoint：由 CaptureFlagManager(GS) 持有，一场子比赛持有一个；
Container_Player：由 CaptureFlagComponent(PS) 持有，每个 Player 持有一个；

提供一个 ICaptureFlagContainerOwnerInterface 用于支持 Create、Destroy 对应的 Container 方法；

// ContainerOwner.h

UINTERFACE(BlueprintType, Blueprintable)
class UCaptureFlagContainerOwnerInterface : public UInterface
{
GENERATED_BODY()
};

class ICaptureFlagContainerOwnerInterface
{
GENERATED_BODY()

public:
template<class T>
static typename TEnableIf::Value, T*>::Type
CreateFlagContainer(UObject* InOwner) // 传入 this
{
if (!IsValid(InOwner)) return nullptr;
T* Container = NewObject(InOwner);
Container->Init(InOwner);
return Container;
}

void DestroyFlagContainer(UCaptureFlagContainerBase* Container)
{
if (!IsValid(Container)) return;
Container->Uninit();
Container = nullptr;
}
};

`TransferSystem`

classDiagram    direction LR        UCFTransferSystem..>UCFTransferPolicyBase    UCFTransferSystem..UCaptureFlagContainerBase    class UCFTransferSystem {        Policies : FGameplaySubSystemCollection~UCFTransferPolicyBase~        friend UCFTransferPolicyBase        - TransferItem(Item, TargetContainer, TransferReason)    }            UCFTransferPolicyBase..UCaptureFlagContainerBase    class UCFTransferPolicyBase{    # OnInit()    # OnUninit()    # TransferItem(Item, TargetContainer)    # GetTransferReason() : ECFTransferReason    }        UCFTansferPolicy_PickUp--|>UCFTransferPolicyBase    UCFTansferPolicy_Drop--|>UCFTransferPolicyBase    UCFTansferPolicy_Reach--|>UCFTransferPolicyBase    UCFTansferPolicy_Strike--|>UCFTransferPolicyBase

首先需要一个 UCFTransferSystem 持有 Polices，管理并维护所有 TransferPolicy 的生命周期，具体可以参考 [UE] GameplaySubSystem 简单实现。

对于一个具体的 TransferPolicy，通过重载 TransferPolicyBase 的 PURE_VIRTUAL 方法 GetTransferReason ，明确其对应的 TransferReason，在其 OnInit、OnUninit，监听该类型需要的事件，通过对应的 Callback 调用到 Base 提供的 TransferItem 方法，执行 Item 的转移。

对于一次成功的 Transfer，显然会调用到 SourceContainer 的 Remove ，以及 TargetContainer 的 Add。

// TransferManager

bool UCaptureFlagTransferManager::TransferItem(TWeakPtr Item, UCaptureFlagContainerBase* TargetContainer, ECFTransferReason TransferReason)
{
if (!Item.IsValid() || !IsValid(TargetContainer)) return false;

auto SharedItem = Item.Pin();

// 检查是否可以获得
if (TargetContainer->VerifyCanAddItem() == false) return false;
// Source 可以为空
auto SourceContainer = SharedItem->GetContainer();

if (SourceContainer == TargetContainer) return false;

ECFTransferReason LastTransferReason = Item.Pin()->GetTransferReason();
Item.Pin()->SetTransferReason(TransferReason);

// 若有 Source，则尝试移除
if (SourceContainer.IsValid() && SourceContainer->RemoveItem(Item) == false)
{
Item.Pin()->SetTransferReason(LastTransferReason);
return false;
}

FCaptureFlagParams Params{};
if (SourceContainer.IsValid())
{
SourceContainer->CollectParams(Params);
}

// 尝试添加
if (TargetContainer->AddItem(Item, Params) == false)
{
Item.Pin()->SetTransferReason(LastTransferReason);
// 失败则还给 Source
if (SourceContainer.IsValid())
{
SourceContainer->AddItem(Item);
}

return false;
}

return true;
}

// TransferPolicyBase.h
UCLASS(Abstract)
class UCFTransferPolicyBase : public UGameModeSubSystemBase
{
GENERATED_BODY()

protected:
virtual ECFTransferReason GetTransferReason() const PURE_VIRTUAL(UCFTransferPolicyBase::GetTransferReason, return ECFTransferReason::None;);

protected:
virtual void OnInit() override;
virtual void OnUninit() override;

protected:
bool TransferItem(TWeakPtr Item, UCaptureFlagContainerBase* TargetContainer) const;


protected:
TWeakObjectPtr <class UCaptureFlagTransferManager> System = nullptr
};

// TransferPolicy.cpp
void UCFTransferPolicyBase::OnInit()
{
System = Cast(GetOuter());
}

bool UCFTransferPolicyBase::TransferItem(TWeakPtr Item, UCaptureFlagContainerBase* TargetContainer) const
{
if (!System.IsValid() || !Item.IsValid() || !IsValid(TargetContainer)) return false;

bool bSucceed = false;
bSucceed = System->TransferItem( Item, TargetContainer, GetTransferReason() );

return bSucceed;
}

[UE]CommonParams解决方案

2024-03-13T16:00:00.000Z

CommonParams解决方案

在实现业务框架的时候，经常需要支持传参的功能（比如 Buff 系统中，AddBuff 的时候，通常需要支持外部传入一个 BuffParams ，在内部解析出各种 Param 使用。）

这个参数需要支持基本的数据保存、同步等。

初始的想法

一个最简单的想法，是打包一个结构体，支持各种类型的传入，比如：

USTRUCT()
struct Params
{
    UPROPERTY()
    uint64 uVar0;
    UPROPERTY()
    int iVar0;
    UPROPERTY()
    float fVar0;
}

这样虽然很简单，同时可以通过反射来同步。

但是有一个巨大的问题，那就是在解析参数的时候，只知道 Var0 这种没有名字的抽象的概念，使用者需要记住 Var0 对应的是什么数据，很不直观。

CommonVariantParams

维护一个 CommonVariantParams，通过 TMap ValueMap 来保存数据。

为了方便使用，还可以自定义一些构造函数，比如 std::initializer_list> ValuePairs ，这样就可以支持 { {Key0, Val0}, {Key1, Val1} } 形式的构造。

由于 TMap 以及 FVariant 实际上在引擎内部都已经有了合适的重载 operator << Archive，所以自定义 NetSerialize 也很简单。

同时，标记 WithNetSerializer 来自定义 NetSerialize 以支持网络同步；标记 WithIdenticalViaEquality ，在进行同步计算 RepLayout 时，通过自定义的 operator == 来进行 Diff，这样当 CommonVariantParams 作为属性同步时，才能正常判断其发生了变化以进行属性同步。

使用方法

// 创建Params：
FCommonVariantParams Params = { {"ParamA", (float)A}, {"ParamsB", (int)B }, {"ParamsC", (FString)C } /* ... */ });
// 解析Params:
float A = BuffParams.GetValue<float>("ParamA");
int B = BuffParams.GetValue<int>("ParamB");
FString C = BuffParams.GetValue("ParamC");

具体实现

// CommonVariantParams.h
USTRUCT(BlueprintType)
struct FCommonVariantParams
{
GENERATED_BODY()

FCommonVariantParams() = default;
FCommonVariantParams(const FString& Key, FVariant Value);
FCommonVariantParams(std::initializer_listconst FString&, FVariant>> ValuePairs);

void SetValue(const FString& FieldName, FVariant Value);
bool Contains(const FString& FieldName) const;
bool IsEmpty() const;
    
FVariant GetValue(const FString& FieldName) const;
template<typename ValueType> 
ValueType GetValue(const FString& FieldName, ValueType Default = {}) const
{
if (!ValueMap.Contains(FieldName)) return Default;
if (TVariantTraits::GetType() != ValueMap[FieldName].GetType()) return Default;
return ValueMap[FieldName].GetValue();
}
    
    template <typename ValueType> 
bool TryGetValue(const FString& FieldName, ValueType& OutValue) const
{
if (!ValueMap.Contains(FieldName)) return false;
if (TVariantTraits::GetType() != ValueMap[FieldName].GetType()) return false;
OutValue = ValueMap[FieldName].GetValue();
return true;
}

FString ToString() const;
const TMap& GetValueMap() const;

bool NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess);
    
bool operator==(const FCommonVariantParams& Other) const;
bool operator!=(const FCommonVariantParams& Other) const
{
return !(*this == Other);
}

FCommonVariantParams operator+(const FCommonVariantParams& OtherParams);
FCommonVariantParams& operator=(const FCommonVariantParams& OtherParams)
{
ValueMap = OtherParams.GetValueMap();
return *this;
}

void Merge(const FCommonVariantParams& OtherParams);
void Clear();

decltype(auto) begin() { return ValueMap.begin(); }
decltype(auto) begin() const { return ValueMap.begin(); }
decltype(auto) end() { return ValueMap.end(); }
decltype(auto) end() const { return ValueMap.end(); }

protected:
TMap ValueMap;
};

template<>
struct TStructOpsTypeTraits<FCommonVariantParams> : TStructOpsTypeTraitsBase2
{
enum
{
WithNetSerializer = true,
        WithIdenticalViaEquality = true,
};
};

// CommonVariantParams.cpp
FCommonVariantParams::FCommonVariantParams(const FString& Key, FVariant Value)
{
ValueMap.Add(Key, Value);
}

FCommonVariantParams::FCommonVariantParams(std::initializer_listconst FString&, FVariant>> ValuePairs)
{
for (const auto& Pair : ValuePairs)
{
ValueMap.Add(Pair.Key, Pair.Value);
}
}

void FCommonVariantParams::SetValue(const FString& FieldName, FVariant Value)
{
ValueMap.Add(FieldName, FVariant(Value));
}

bool FCommonVariantParams::Contains(const FString& FieldName) const
{
return ValueMap.Contains(FieldName);
}

bool FCommonVariantParams::IsEmpty() const
{
return ValueMap.IsEmpty();
}

FVariant FCommonVariantParams::GetValue(const FString& FieldName) const
{
if (auto Value = ValueMap.Find(FieldName))
{
return *Value;
}
return {};
}

const TMap& FCommonVariantParams::GetValueMap() const
{
return ValueMap;
}

bool FCommonVariantParams::NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess)
{
bOutSuccess = true;
Ar << ValueMap;
return true;
}


bool FCommonVariantParams::operator==(const FCommonVariantParams& Other) const
{
TArray Keys, OtherKeys;
ValueMap.GenerateKeyArray(Keys);
Other.ValueMap.GenerateKeyArray(OtherKeys);

if (Keys != OtherKeys) return false;
for (auto Key : Keys)
{
if (ValueMap[Key] != Other.ValueMap[Key])
return false;
}

return true;
}

FCommonVariantParams FCommonVariantParams::operator+(const FCommonVariantParams& OtherParams)
{
FCommonVariantParams CombinedParams = *this;
CombinedParams.Merge(OtherParams);
return CombinedParams;
}

void FCommonVariantParams::Merge(const FCommonVariantParams& OtherParams)
{
for (const auto& [Key, Value] : OtherParams.GetValueMap())
{
// 覆盖
SetValue(Key, Value);
}
}

void FCommonVariantParams::Clear()
{
ValueMap.Empty();
}

Lua

对于这个 CommonVariantParams，还可以扩展一些方法，让这些参数可以通过 Unlua 在 Lua 脚本中设置与访问。

void SetIntValue(const FString& FieldName, int32 Value);
void SetUInt64Value(const FString& FieldName, uint64 Value);
void SetFloatValue(const FString& FieldName, float Value);
void SetBoolValue(const FString& FieldName, bool Value);
void SetStringValue(const FString& FieldName, const FString& Value);
void SetTransformValue(const FString& FieldName, const FTransform& Value);
void SetVectorValue(const FString& FieldName, const FVector& Value);

int32 GetIntValue(const FString& FieldName, int32 Default = {}) const;
uint64 GetUInt64Value(const FString& FieldName, uint64 Default = {}) const;
float GetFloatValue(const FString& FieldName, float Default = {}) const;
bool GetBoolValue(const FString& FieldName, bool Default = {}) const;
FString GetStringValue(const FString& FieldName, const FString& Default = {}) const;
FTransform GetTransformValue(const FString& FieldName, const FTransform& Default = {}) const;
FVector GetVectorValue(const FString& FieldName, const FVector& Default = {}) const;

void FCommonVariantParams::SetIntValue(const FString& FieldName, int32 Value)
{
SetValue(FieldName, Value);
}

void FCommonVariantParams::SetUInt64Value(const FString& FieldName, uint64 Value)
{
SetValue(FieldName, Value);
}

void FCommonVariantParams::SetFloatValue(const FString& FieldName, float Value)
{
SetValue(FieldName, Value);
}

void FCommonVariantParams::SetBoolValue(const FString& FieldName, bool Value)
{
SetValue(FieldName, Value);
}

void FCommonVariantParams::SetStringValue(const FString& FieldName, const FString& Value)
{
SetValue(FieldName, Value);
}


void FCommonVariantParams::SetTransformValue(const FString& FieldName, const FTransform& Value)
{
SetValue(FieldName, Value);
}


void FCommonVariantParams::SetVectorValue(const FString& FieldName, const FVector& Value)
{
SetValue(FieldName, Value);
}

int32 FCommonVariantParams::GetIntValue(const FString& FieldName, int32 Default /*= {}*/) const
{
return GetValue(FieldName, Default);
}

uint64 FCommonVariantParams::GetUInt64Value(const FString& FieldName, uint64 Default /*= {}*/) const
{
return GetValue(FieldName, Default);
}

float FCommonVariantParams::GetFloatValue(const FString& FieldName, float Default /*= {}*/) const
{
return GetValue<float>(FieldName, Default);
}

bool FCommonVariantParams::GetBoolValue(const FString& FieldName, bool Default /*= {}*/) const
{
return GetValue<bool>(FieldName, Default);
}

FString FCommonVariantParams::GetStringValue(const FString& FieldName, const FString& Default /*= {}*/) const
{
return GetValue(FieldName, Default);
}


FTransform FCommonVariantParams::GetTransformValue(const FString& FieldName, const FTransform& Default /*= {}*/) const
{
return GetValue(FieldName, Default);
}

FVector FCommonVariantParams::GetVectorValue(const FString& FieldName, const FVector& Default /*= {}*/) const
{
return GetValue(FieldName, Default);
}

同时，可以添加自定义的 Lua 方法，让其在 Lua 中可以支持 ToTable 等，参考 UnLua & C++ 交互；

static FCommonVariantParams* GetCommonVariantParams(lua_State* L, int32 Index)
{
return UUnLuaFunctionLibrary::GetValue(L, Index);
}

static int32 FCommonVariantParams_Index(lua_State* L)
{
if (!UUnLuaFunctionLibrary::CheckParamsCount(L, 2))
        return luaL_error(L, "invalid parameters");

auto CommonVariantParams = GetCommonVariantParams(L, 1);
if (CommonVariantParams == nullptr)
return luaL_error(L, "invalid struct type");

const char* KeyStringPtr = nullptr;

    if (lua_isstring(L, 2))
    {
KeyStringPtr = lua_tostring(L, 2);
    }

if (KeyStringPtr == nullptr)
{
lua_pushnil(L);
return 1;
}

auto Key = FString(UTF8_TO_TCHAR(KeyStringPtr));
if (CommonVariantParams->Contains(Key))
{
auto Value = CommonVariantParams->GetValue(Key);
UUnLuaFunctionLibrary::PushValue(L, Value);
}
else
{
lua_getmetatable(L, 1);
if (lua_compare(L, 1, -1, LUA_OPEQ))
lua_pushnil(L);
else
{
lua_pushvalue(L, 2);
lua_rawget(L, -2);
}
lua_remove(L, -2);
}

    return 1;
}

static int FCommonVariantParams_ToTable(lua_State* L)
{
if (!UUnLuaFunctionLibrary::CheckParamsCount(L, 1))
        return luaL_error(L, "invalid parameters");

auto CommonVariantParams = GetCommonVariantParams(L, 1);
if (CommonVariantParams == nullptr)
return luaL_error(L, "invalid struct type");

    lua_newtable(L);
for (const auto& [Key, Value] : *CommonVariantParams)
{
UnLua::Push(L, Key);
UUnLuaFunctionLibrary::PushValue(L, Value);
lua_rawset(L, -3);
}
    return 1;
}


static const luaL_Reg FCommonVariantParamsLib[] =
{
    {"ToTable", FCommonVariantParams_ToTable},
    {"__index", FCommonVariantParams_Index},
    {nullptr, nullptr}
};

最后进行导出：

// 导出：
// define 在 UnluaEx.h 中
BEGIN_EXPORT_REFLECTED_CLASS(FCommonVariantParams)
ADD_LIB(FCommonVariantParamsLib)

    ADD_FUNCTION(Contains)
    ADD_FUNCTION(IsEmpty)
    ADD_FUNCTION(ToString)

    ADD_FUNCTION(SetIntValue)
ADD_FUNCTION(SetUInt64Value)
    ADD_FUNCTION(SetFloatValue)
    ADD_FUNCTION(SetBoolValue)
    ADD_FUNCTION(SetStringValue)
    ADD_FUNCTION(SetTransformValue)

ADD_FUNCTION(GetIntValue)
ADD_FUNCTION(GetUInt64Value)
ADD_FUNCTION(GetFloatValue)
ADD_FUNCTION(GetBoolValue)
ADD_FUNCTION(GetStringValue)
ADD_FUNCTION(GetTransformValue)
END_EXPORT_CLASS()
IMPLEMENT_EXPORTED_CLASS(FCommonVariantParams)

具体业务

特别地，具体业务使用的时候，可以继承一个自己的 Params 来使用，以 FGameplayBuffParams 为例：

USTRUCT()
struct FGameplayBuffParams : public FCommonVariantParams
{
GENERATED_BODY()
using FCommonVariantParams::FCommonVariantParams;
}

[UE]TeamSystem框架

2024-03-13T16:00:00.000Z

TeamSystem框架

基本架构

支持基本的加入、退出队伍，以及维护队伍的基本数据（TeamID、 MemberUIDs）

提供继承扩展，维护自定义业务逻辑与队伍数据；

对于挂载组件：由 Manager 级别的 TeamManager ，与 Player 身上的 TeamComponent 组成；

以及队伍数据同步，自定义不同方式的数据同步；

classDiagram    UTeamManager..>UTeamBase    UTeamManager..>UTeamSyncDataBase    class UTeamManager {        SubSystemCollections : FGameplaySubSystemCollection~UTeamCommonSubSystemBase~        Teams : TMap~uint64|UTeamBase*~         TeamSyncDatas : TArray~UTeamSyncDataBase*~                CreateTeam(TeamID)        DestoryTeam(TeamID)        GetTeam(TeamID)                JoinTeam(TeamID, PlayerUID)        LeaveTeam(PlayerUID)    }        UTeamComponent..>UTeamSyncDataBaseclass UTeamComponent {        TeamID : uint64        SubSystemCollection : FGameplaySubSystemCollection~UTeamPlayerSubSystemBase~        UpdateTeamID()        CreateSyncData()        DestroySyncData()    }           class UTeamBase {    TeamID : uint64    MemberUIDs : TArray~uint64~    OnDataDirty        Init(TeamID)    Uninit()    AddMember(PlayerUID)    RemoveMember(PlayerUID)        MarkDirty()    }        class UTeamSyncDataBase {    BoundTeam : TWeakObjectPtr~UTeamBase~    TeamID : uint64    MemberUIDs : TArray~uint64~        BindTeam(InTeam)    Unbind()        OnDataDirty()    CollectSyncData(InTeam)    }

TeamManager

持有 Teams 保存队伍的原始指针，提供 CreateTeam、DestroyTeam 方法；

// TeamManager.cpp

#pragma region Team

UTeamBase* UTeamManager::GetTeam(uint64 TeamID)
{
return Teams.FindRef(TeamID);
}

const TMap& UTeamManager::GetTeams() const
{
return Teams;
}

// ----------

uint64 UTeamManager::GetHashValue(uint64 Value)
{
uint64 HashValue = HashCombine( GetHashCode(), GetTypeHash(Value)));
LogD(TEXT("UTeamManager::GetHashValue, HashValue=%llu, [Value=%llu | HashCode=%llu]"), HashValue, Value, GetHashCode());
return HashValue;
}

UTeamBase* UTeamManager::GetOrCreateTeam(uint64 TeamID)
{
if (auto Team = GetTeam(TeamID); !IsValid(Team))
{
CreateTeam(TeamID);
}

return GetTeam(TeamID);
}

UTeamBase* UTeamManager::CreateTeam(uint64 TeamID)
{
if (GetTeam(TeamID) != nullptr)
{
LogW(TEXT("UTeamManager::CreateTeam, Team is existed! TeamID=%llu"), TeamID);
return nullptr;
}

LogD(TEXT("UTeamManager::CreateTeam, Begin, TeamID=%llu"), TeamID);

// CreateTeam
auto TeamClass = GetTeamClass();
if (!IsValid(TeamClass) || !TeamClass->IsChildOf(UTeamBase::StaticClass()))
{
LogE(TEXT("UTeamManager::CreateTeam, TeamClass is invalid! TeamID=%llu"), TeamID);
return nullptr;
}

UTeamBase* NewTeam = NewObject(this, GetTeamClass());
if (!IsValid(NewTeam))
{
LogE(TEXT("UTeamManager::CreateTeam, NewTeam is invalid! TeamID=%llu"), TeamID);
return nullptr;
}


LogD(TEXT("UTeamManager::CreateTeam, CreateTeam, TeamID=%llu"), TeamID);
NewTeam->Init(TeamID);
Teams.Add( TeamID, NewTeam );

// SyncData
{
auto NewTeamSyncData = UTeamUtils::CreateTeamSyncData( this, NewTeam, GetTeamSyncDataClass() );
if (IsValid(NewTeamSyncData))
{
LogD(TEXT("UTeamManager::CreateTeam, CreateTeamSyncData, TeamID=%llu"), TeamID);
TeamSyncDatas.Add( NewTeamSyncData );
MARK_PROPERTY_DIRTY_FROM_NAME(UTeamManager, TeamSyncDatas, this);
}
}

return NewTeam;
}

void UTeamManager::DestoryTeam(uint64 TeamID)
{
auto Team = GetTeam(TeamID);
if (!IsValid(Team)) return;
LogD(TEXT("UTeamManager::DestoryTeam, TeamID=%llu"), TeamID);

// SyncData
for (auto Iter = TeamSyncDatas.CreateIterator(); Iter; ++Iter)
{
auto SyncData = *Iter;
if (!IsValid(SyncData) || SyncData->GetTeamID() == TeamID)
{
UTeamUtils::DestoryTeamSyncData(SyncData);
Iter.RemoveCurrent();
}
}
MARK_PROPERTY_DIRTY_FROM_NAME(UTeamManager, TeamSyncDatas, this);

Team->Uninit();
Teams.Remove(TeamID);
}

#pragma endregion Team

提供 Player 的 JoinTeam、LeaveTeam；

// TeamManager.cpp

#pragma region Join/Leave

void UTeamManager::JoinTeam(uint64 TeamID, uint64 PlayerUID, bool bNeedHash)
{
if (!IsStandaloneOrDS(this)) return;

if (TeamID == 0)
{
LogD(TEXT("UTeamManager::JoinTeam, TeamID is 0! PlayerUID=%llu, TeamID=%llu, bNeedHash=%d"), PlayerUID, TeamID, bNeedHash);
return;
}

auto TeamComponent = UTeamUtils::GetComponentByUID(GetWorld(), PlayerUID);
if (!IsValid(TeamComponent)) return;

LogD(TEXT("UTeamManager::JoinTeam, PlayerUID=%llu, TeamID=%llu, bNeedHash=%d"), PlayerUID, TeamID, bNeedHash);
if (bNeedHash)
{
TeamID = GetHashValue(TeamID);
LogD(TEXT("UTeamManager::JoinTeam, ProcessID, PlayerUID=%llu, HashTeamID=%llu"), PlayerUID, TeamID);
}

// 如果玩家已经存在于某个队伍则无法再次加入
if (auto ExistTeam = GetTeam(TeamComponent->GetTeamID()); IsValid(ExistTeam))
{
LogE(TEXT("UTeamManager::JoinTeam, Player already exist Team! PlayerUID=%llu, ExistTeamID=%llu"), PlayerUID, ExistTeam->GetTeamID());
return;
}

auto Team = GetOrCreateTeam(TeamID);
if (!IsValid(Team))
{
LogE(TEXT("UTeamManager::JoinTeam, Team is invalid! PlayerUID=%llu, TeamID=%llu"), PlayerUID, TeamID);
return;
}

LogD(TEXT("UTeamManager::JoinTeam, Begin, PlayerUID=%llu, TeamID=%llu"), PlayerUID, TeamID);
TeamComponent->UpdateTeamID(Team->GetTeamID());
TeamComponent->CreateSyncData(Team);

Team->AddMember(PlayerUID);
}

void UTeamManager::LeaveTeam(uint64 PlayerUID)
{
if (!IsStandaloneOrDS(this)) return;

auto TeamComponent = UTeamUtils::GetComponentByUID(GetWorld(), PlayerUID);
if (!IsValid(TeamComponent)) return;

auto Team = GetTeam(TeamComponent->GetTeamID());
if (!IsValid(Team))
{
LogE(TEXT("UTeamManager::LeaveTeam, Player isn't in any team! PlayerUID=%llu"), PlayerUID);
return;
}

uint64 TeamID = Team->GetTeamID();
LogD(TEXT("UTeamManager::LeaveTeam, Begin, PlayerUID=%llu, TeamID=%llu"), PlayerUID, TeamID);
Team->RemoveMember(PlayerUID);
TeamComponent->UpdateTeamID(0);
TeamComponent->DestroySyncData();

if (Team->GetMemberUIDs().Num() == 0)
{
DestoryTeam( TeamID );
}
}

#pragma endregion Join/Leave

持有 TeamCommonSubSystem，支持业务扩展拆分为若干个子系统，参考：[UE]GameplaySubSystem 实现

// TeamManager.cpp

void UTeamManager::RegisterSubSystems()
{
if (!IsStandaloneOrDS(this)) return;
LogD(TEXT("UTeamManager::RegisterSubSystems"));

SubSystemCollection.Init( this, GetSubSystemClasses() );
}

void UTeamManager::UnregisterSubSystems()
{
if (!IsStandaloneOrDS(this)) return;
LogD(TEXT("UTeamManager::UnregisterSubSystems"));

SubSystemCollection.Uninit();
}

同步 TeamSyncDatas，其中类型为 TeamSyncData_Common，记录所有人都需要关心的队伍同步数据；

// TeamManager.cpp

#pragma region Replicate

void UTeamManager::OnRep_TeamSyncDatas(const TArray& LastTeamSyncDatas)
{
LogD(TEXT("UTeamManager::OnRep_TeamSyncDatas, TeamSyncDatas=%s, LastTeamSyncDatas=%s"), *UStringUtils::ToString(TeamSyncDatas), *UStringUtils::ToString(LastTeamSyncDatas));
}

bool UTeamManager::ReplicateSubobjects(UActorChannel* Channel, FOutBunch* Bunch, FReplicationFlags* RepFlags)
{
bool WroteSomething = Super::ReplicateSubobjects(Channel, Bunch, RepFlags);


if (IsValid(Channel) && RepFlags->bNetInitial == false)
{
for (const auto& SyncData : TeamSyncDatas)
{
WroteSomething |= Channel->ReplicateSubobject( SyncData, *Bunch, *RepFlags);
}
}

return WroteSomething;
}

#pragma endregion Replicate

TeamComponent

维护 TeamID；

// TeamComponent.cpp

#pragma region TeamID

void UTeamComponent::UpdateTeamID(uint64 InTeamID)
{
if (InTeamID == TeamID) return;
LogD(TEXT("UTeamComponent::UpdateTeamID, UID=%llu, TeamID=%llu"), GetUID(), InTeamID);
SetTeamID(InTeamID);
OnRep_TeamID();

if (IsDS(this))
{
S2C_NotifyTeamIDChanged(InTeamID);
}
}

void UTeamComponent::S2C_NotifyTeamIDChanged_Implementation(uint64 InTeamID)
{
if (!IsClient(this)) return;
if (InTeamID == TeamID) return;
LogD(TEXT("UTeamComponent::S2C_NotifyTeamIDChanged_Implementation, UID=%llu, TeamID=%llu"), GetUID(), TeamID);
SetTeamID(InTeamID);
OnRep_TeamID();
}

void UTeamComponent::OnRep_TeamID()
{
LogD(TEXT("UTeamComponent::OnRep_TeamID, UID=%llu, TeamID=%llu"), GetUID(), TeamID);
OnPlayerTeamIDChanged.Broadcast(TeamID);
UTeamDelegate::GetDelegate()->OnPlayerTeamIDChanged.Broadcast(GetUID(), TeamID);
}

#pragma endregion TeamID

持有 TeamPlayerSubSystem，支持业务扩展拆分为若干个子系统；

// TeamComponent.cpp

#pragma region SubSystem

void UTeamComponent::RegisterSubSystems()
{
if (!IsStandaloneOrDS(this)) return;
LogD(TEXT("UTeamComponent::RegisterSubSystems, UID=%llu"), GetUID());

SubSystemCollection.Init( this, GetSubSystemClasses() );
}

void UTeamComponent::UnregisterSubSystems()
{
if (!IsStandaloneOrDS(this)) return;
LogD(TEXT("UTeamComponent::UnregisterSubSystems, UID=%llu"), GetUID());

SubSystemCollection.Uninit();
}


// -----

UTeamPlayerSubSystemBase* UTeamComponent::GetSubSystem(UClass* InClass) const
{
if (!IsValid(InClass)) return nullptr;
return SubSystemCollection.GetSubSystem(InClass);
}

#pragma endregion SubSystem

同步 TeamSyncData，其中类型为 TeamSyncData_OwnerOnly，记录仅自己队伍成员关心的队伍同步数据；

// ComponentBase.cpp

bool UComponentBase::ReplicateSubobjects(UActorChannel* Channel, FOutBunch* Bunch, FReplicationFlags* RepFlags)
{
bool WroteSomething = Super::ReplicateSubobjects(Channel, Bunch, RepFlags);

if (IsValid(Channel) && IsValid(Channel->Connection))
{
if (Channel->Connection->PlayerController == GetPlayerController())
{
WroteSomething |= ReplicateSubobjects_OwnerOnly(Channel, Bunch, RepFlags);
}
}

return WroteSomething;
}

// TeamComponent.cpp

#pragma region SyncData

bool UTeamComponent::ReplicateSubobjects_OwnerOnly(UActorChannel* Channel, FOutBunch* Bunch, FReplicationFlags* RepFlags)
{
bool WroteSomething = Super::ReplicateSubobjects_OwnerOnly(Channel, Bunch, RepFlags);

WroteSomething |= SubSystemCollection.ReplicateSubSystems(Channel, Bunch, RepFlags);

if (IsValid(Channel) && RepFlags->bNetInitial == false)
{
WroteSomething |= Channel->ReplicateSubobject( SyncData, *Bunch, *RepFlags);
}

return WroteSomething;
}

void UTeamComponent::CreateSyncData(UTeamBase* InTeam)
{
if (!IsValid(InTeam)) return;
LogD(TEXT("UTeamComponent::CreateSyncData, UID=%llu, InTeamID=%llu, TeamID=%llu"), GetUID(), InTeam->GetTeamID(), TeamID);

auto NewSyncData = UTeamUtils::CreateTeamSyncData( this, InTeam, GetSyncDataClass() );
if (IsValid(NewSyncData))
{
SetSyncData(NewSyncData);
LogD(TEXT("UTeamComponent::CreateSyncData, UID=%llu, SyncData=%s"), GetUID(), *SyncData->ToString());
OnRep_SyncData();
}
}


void UTeamComponent::DestroySyncData()
{
LogD(TEXT("UTeamComponent::DestroySyncData, UID=%llu, TeamID=%llu"), GetUID(), TeamID);
UTeamUtils::DestoryTeamSyncData(SyncData);
SetSyncData( nullptr );
}

void UTeamComponent::OnRep_SyncData()
{
LogD(TEXT("UTeamComponent::OnRep_SyncData, UID=%llu, SyncData=%s"), GetUID(), *UStringUtils::ToString(SyncData));
}

Team

维护队伍信息： TeamID、MemberUIDs，以及可能继承的属性；
当属性变化时，进行 MarkDirty 通知 OnDataDirty；

完整实现

// TeamMacro.h

#pragma region Property


#define TEAM_GENERATE_PROPERTY(Visibility, Type, Name) \
Visibility: Type Name{}; \
TEAM_GENERATE_PROPERTY_FUNCTIONS_INTERNAL(Name)

// ----

#define TEAM_GENERATE_PROPERTY_MARKDIRTY(Visibility, Type, Name) \
Visibility: Type Name{}; \
TEAM_GENERATE_PROPERTY_MARKDIRTY_FUNCTIONS(Name)


#pragma endregion Property


#pragma region Function

#define TEAM_GENERATE_PROPERTY_FUNCTIONS(Name) \
TEAM_EXPAND(TEAM_GENERATE_PROPERTY_FUNCTIONS_INTERNAL(decltype(Name), Name))

#define TEAM_GENERATE_PROPERTY_FUNCTIONS_INTERNAL(Type, Name) \
public: const Type& Get##Name() const { return Name; } \
public: void Set##Name(const Type& Value) { \
Name = Value; \
}


// -----

#define TEAM_GENERATE_PROPERTY_MARKDIRTY_FUNCTIONS(Name) \
TEAM_EXPAND(TEAM_GENERATE_PROPERTY_MARKDIRTY_FUNCTIONS_INTERNAL(decltype(Name), Name))

#define TEAM_GENERATE_PROPERTY_MARKDIRTY_FUNCTIONS_INTERNAL(Type, Name) \
public: const Type& Get##Name() const { return Name; } \
public: void Set##Name(const Type& Value) { \
if (Name == Value) return; \
Name = Value; \
this->MarkDirty(); \
}

#pragma endregion Function

// Team.h

UCLASS(Blueprintable, BlueprintType)
class UTeamBase : public UObject
{
GENERATED_BODY()

public:
void Init(uint64 InTeamID);
void Uninit();

public:
virtual FString ToString() const;

#pragma region Dirty

public:
DECLARE_MULTICAST_DELEGATE(FDataDirty)
FDataDirty OnDataDirty;

protected:
virtual void MarkDirty();

#pragma endregion Dirty


#pragma region Member

public:
void AddMember(uint64 MemberUID);
void RemoveMember(uint64 MemberUID);

#pragma endregion Member

private:
TEAM_GENERATE_PROPERTY_MARKDIRTY(protected, uint64, TeamID);
TEAM_GENERATE_PROPERTY_MARKDIRTY(protected, TArray, MemberUIDs);
};

// Team.cpp

void UTeamBase::Init(uint64 InTeamID)
{
TeamID = InTeamID;
LogD(TEXT("UTeamBase::Init, TeamID=%llu"), TeamID);
MemberUIDs.Empty();
}

void UTeamBase::Uninit()
{
LogD(TEXT("UTeamBase::Uninit, TeamID=%llu"), TeamID);
}


#pragma region Dirty

void UTeamBase::MarkDirty()
{
OnDataDirty.Broadcast();
}

#pragma endregion Dirty


#pragma region Member

void UTeamBase::AddMember(uint64 MemberUID)
{
if (MemberUIDs.Contains( MemberUID )) return;
MemberUIDs.Add( MemberUID );
LogD(TEXT("UTeamBase::AddMember, TeamID=%llu, MemberUID=%llu, MemberUIDs=%s"), TeamID, MemberUID, *UStringUtils::ToString(MemberUIDs));
MarkDirty();
}

void UTeamBase::RemoveMember(uint64 MemberUID)
{
if (!MemberUIDs.Contains( MemberUID )) return;
MemberUIDs.Remove( MemberUID ); 
LogD(TEXT("UTeamBase::RemoveMember, TeamID=%llu, MemberUID=%llu, MemberUIDs=%s"), TeamID, MemberUID, *UStringUtils::ToString(MemberUIDs));
MarkDirty();
}


#pragma endregion Member

TeamSyncData

与对应的 Team 进行绑定；

// TeamSyncData.cpp

#pragma region Bind

void UTeamSyncDataBase::BindTeam(UTeamBase* InTeam)
{
if (!IsValid(InTeam)) return;
BoundTeam = InTeam;
InTeam->OnDataDirty.AddUObject(this, &ThisClass::OnDataDirty);
CollectSyncData(InTeam);

LogD(TEXT("UTeamSyncDataBase::BindTeam, %s"), *ToString());
}

void UTeamSyncDataBase::Unbind()
{
if (!BoundTeam.IsValid()) return;
BoundTeam->OnDataDirty.RemoveAll(this);
LogD(TEXT("UTeamSyncDataBase::Unbind, %s"), *ToString());
}


#pragma endregion Bind

当 Team 进行 OnDataDirty 时，重新对 Team 进行 CollectSyncData 收集并设置同步数据；

// TeamSyncData.cpp

#pragma region CollectData

void UTeamSyncDataBase::OnDataDirty()
{
if (BoundTeam.IsValid())
{
CollectSyncData( BoundTeam.Get() );
}
}


void UTeamSyncDataBase::CollectSyncData(UTeamBase* InTeam)
{
if (!IsValid(InTeam)) return;

SetTeamID( InTeam->GetTeamID() );
SetMemberUIDs( InTeam->GetMemberUIDs() );

LogD(TEXT("UTeamSyncDataBase::CollectSyncData, %s"), *ToString());
}

#pragma endregion CollectData

提供 Create / Destroy TeamSyncData 的方法：

// TeamUtils.cpp

UTeamSyncDataBase* UTeamUtils::CreateTeamSyncData(UObject* Outer, UTeamBase* InTeam, UClass* InClass)
{
if (!IsValid(Outer)) return nullptr;
if (!IsValid(InClass) || !InClass->IsChildOf(UTeamSyncDataBase::StaticClass())) return nullptr;

UTeamSyncDataBase* NewSyncData = NewObject(Outer, InClass);
if (!IsValid(NewSyncData)) return nullptr;

NewSyncData->BindTeam( InTeam );
return NewSyncData;
}

void UTeamUtils::DestoryTeamSyncData(UTeamSyncDataBase* SyncData)
{
if (!IsValid(SyncData)) return;
SyncData->Unbind();
SyncData = nullptr;
}

完整实现

// TeamSyncData.h

UCLASS()
class UTeamSyncDataBase : public UObject
{
GENERATED_BODY()


#pragma region Base

protected:
virtual bool IsSupportedForNetworking() const override { return true; }

protected:
virtual void GetLifetimeReplicatedProps(TArray& OutLifetimeProps) const override;


#pragma endregion Base



#pragma region Bind

public:
void BindTeam(UTeamBase* InTeam);
void Unbind();

private:
TWeakObjectPtr  BoundTeam;

#pragma endregion Bind


#pragma region CollectData

private:
void OnDataDirty();

protected:
virtual void CollectSyncData(UTeamBase* InTeam);

#pragma endregion CollectData


#pragma region Data

public:
virtual FString ToString() const;

protected:
UFUNCTION()
virtual void OnRep_TeamID();

UFUNCTION()
virtual void OnRep_MemberUIDs(const TArray& LastMemberUIDs);

private:

UPROPERTY(ReplicatedUsing=OnRep_TeamID)
uint64 TeamID;

UPROPERTY(ReplicatedUsing=OnRep_MemberUIDs)
TArray  MemberUIDs;

#pragma endregion Data


};

// TeamSyncData.cpp

#pragma region Base

void UTeamSyncDataBase::GetLifetimeReplicatedProps(TArray& OutLifetimeProps) const
{
Super::GetLifetimeReplicatedProps(OutLifetimeProps);

FDoRepLifetimeParams SharedParams;
SharedParams.bIsPushBased = true;

DOREPLIFETIME_WITH_PARAMS_FAST(UTeamSyncDataBase, TeamID, SharedParams);
DOREPLIFETIME_WITH_PARAMS_FAST(UTeamSyncDataBase, MemberUIDs, SharedParams);
}


#pragma endregion Base


#pragma region Bind

void UTeamSyncDataBase::BindTeam(UTeamBase* InTeam)
{
if (!IsValid(InTeam)) return;
BoundTeam = InTeam;
InTeam->OnDataDirty.AddUObject(this, &ThisClass::OnDataDirty);
CollectSyncData(InTeam);

LogD(TEXT("UTeamSyncDataBase::BindTeam, %s"), *ToString());
}

void UTeamSyncDataBase::Unbind()
{
if (!BoundTeam.IsValid()) return;
BoundTeam->OnDataDirty.RemoveAll(this);
LogD(TEXT("UTeamSyncDataBase::Unbind, %s"), *ToString());
}



#pragma endregion Bind




#pragma region CollectData

void UTeamSyncDataBase::OnDataDirty()
{
if (BoundTeam.IsValid())
{
CollectSyncData( BoundTeam.Get() );
}
}


void UTeamSyncDataBase::CollectSyncData(UTeamBase* InTeam)
{
if (!IsValid(InTeam)) return;

SetTeamID( InTeam->GetTeamID() );
SetMemberUIDs( InTeam->GetMemberUIDs() );

LogD(TEXT("UTeamSyncDataBase::CollectSyncData, %s"), *ToString());
}

#pragma endregion CollectData



#pragma region Data

FString UTeamSyncDataBase::ToString() const
{
return FString::Printf(TEXT("UID=%llu, TeamID=%llu, Members=%s"), GetUID(), TeamID, *UStringUtils::ToString(MemberUIDs));
}


void UTeamSyncDataBase::OnRep_TeamID()
{
LogD(TEXT("UTeamSyncDataBase::OnRep_TeamID, %s"), *ToString());
}


void UTeamSyncDataBase::OnRep_MemberUIDs(const TArray& LastMemberUIDs)
{
LogD(TEXT("UTeamSyncDataBase::OnRep_MemberUIDs, LastMemberUIDs=%s, %s"), *UStringUtils::ToString(LastMemberUIDs), *ToString());
}


#pragma endregion Data