Antigravity × Unreal Engine 5 プラグイン本番設計ガイド — AIで再利用可能なゲームシステムを複数タイトルに展開する

// Public/Inventory/InventoryComponent.h
#pragma once
 
#include "CoreMinimal.h"
#include "Components/ActorComponent.h"
#include "GameplayTagContainer.h"
#include "InventoryComponent.generated.h"
 
USTRUCT(BlueprintType)
struct COMMONGAMESYSTEMSRUNTIME_API FInventoryItem
{
    GENERATED_BODY()
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    FGameplayTag ItemTag;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    int32 Quantity = 0;
 
    UPROPERTY(EditAnywhere, BlueprintReadWrite)
    int32 MaxStack = 99;
};
 
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(
    FOnInventoryChanged, FGameplayTag, ItemTag, int32, NewQuantity);
 
UCLASS(ClassGroup = (CommonGameSystems), meta = (BlueprintSpawnableComponent))
class COMMONGAMESYSTEMSRUNTIME_API UInventoryComponent : public UActorComponent
{
    GENERATED_BODY()
public:
    UInventoryComponent();
 
    UFUNCTION(BlueprintCallable, Category = "Inventory")
    bool AddItem(FGameplayTag ItemTag, int32 Quantity);
 
    UFUNCTION(BlueprintCallable, Category = "Inventory")
    bool RemoveItem(FGameplayTag ItemTag, int32 Quantity);
 
    UFUNCTION(BlueprintPure, Category = "Inventory")
    int32 GetQuantity(FGameplayTag ItemTag) const;
 
    UPROPERTY(BlueprintAssignable, Category = "Inventory")
    FOnInventoryChanged OnInventoryChanged;
 
private:
    UPROPERTY()
    TArray<FInventoryItem> Items;
};

// Private/Inventory/InventoryComponent.cpp
#include "Inventory/InventoryComponent.h"
 
UInventoryComponent::UInventoryComponent()
{
    PrimaryComponentTick.bCanEverTick = false;
}
 
bool UInventoryComponent::AddItem(FGameplayTag ItemTag, int32 Quantity)
{
    if (!ItemTag.IsValid() || Quantity <= 0) { return false; }
 
    for (FInventoryItem& Slot : Items)
    {
        if (Slot.ItemTag == ItemTag && Slot.Quantity < Slot.MaxStack)
        {
            const int32 Add = FMath::Min(Quantity, Slot.MaxStack - Slot.Quantity);
            Slot.Quantity += Add;
            Quantity -= Add;
            OnInventoryChanged.Broadcast(ItemTag, Slot.Quantity);
            if (Quantity == 0) { return true; }
        }
    }
 
    while (Quantity > 0)
    {
        FInventoryItem NewSlot;
        NewSlot.ItemTag  = ItemTag;
        NewSlot.Quantity = FMath::Min(Quantity, NewSlot.MaxStack);
        Quantity        -= NewSlot.Quantity;
        OnInventoryChanged.Broadcast(NewSlot.ItemTag, NewSlot.Quantity);
        Items.Add(NewSlot);
    }
    return true;
}
 
bool UInventoryComponent::RemoveItem(FGameplayTag ItemTag, int32 Quantity)
{
    int32 Remaining = Quantity;
    for (int32 i = Items.Num() - 1; i >= 0 && Remaining > 0; --i)
    {
        if (Items[i].ItemTag != ItemTag) { continue; }
        const int32 Sub = FMath::Min(Remaining, Items[i].Quantity);
        Items[i].Quantity -= Sub;
        Remaining          -= Sub;
        OnInventoryChanged.Broadcast(ItemTag, Items[i].Quantity);
        if (Items[i].Quantity == 0) { Items.RemoveAt(i); }
    }
    return Remaining == 0;
}
 
int32 UInventoryComponent::GetQuantity(FGameplayTag ItemTag) const
{
    int32 Total = 0;
    for (const FInventoryItem& Slot : Items)
    {
        if (Slot.ItemTag == ItemTag) { Total += Slot.Quantity; }
    }
    return Total;
}

// Public/SaveSystem/GameSaveSubsystem.h
#pragma once
 
#include "CoreMinimal.h"
#include "Subsystems/GameInstanceSubsystem.h"
#include "GameSaveSubsystem.generated.h"
 
DECLARE_DYNAMIC_DELEGATE_OneParam(FOnSaveCompleted, bool, bSucceeded);
 
UCLASS(BlueprintType)
class COMMONGAMESYSTEMSRUNTIME_API UGameSaveSubsystem : public UGameInstanceSubsystem
{
    GENERATED_BODY()
public:
    virtual void Initialize(FSubsystemCollectionBase& Collection) override;
 
    UFUNCTION(BlueprintCallable, Category = "SaveSystem")
    void SaveSlotAsync(const FString& SlotName, const FOnSaveCompleted& OnDone);
 
    UFUNCTION(BlueprintCallable, Category = "SaveSystem")
    bool LoadSlot(const FString& SlotName);
 
    UFUNCTION(BlueprintCallable, Category = "SaveSystem")
    void Set(const FString& Key, const FString& Value);
 
    UFUNCTION(BlueprintPure, Category = "SaveSystem")
    FString Get(const FString& Key, const FString& Default = TEXT("")) const;
 
private:
    UPROPERTY()
    TMap<FString, FString> KV;
};

// Private/SaveSystem/GameSaveSubsystem.cpp
#include "SaveSystem/GameSaveSubsystem.h"
#include "GameFramework/SaveGame.h"
#include "Kismet/GameplayStatics.h"
#include "Serialization/JsonSerializer.h"
 
UCLASS()
class UCommonSaveContainer : public USaveGame
{
    GENERATED_BODY()
public:
    UPROPERTY() TMap<FString, FString> KV;
};
 
void UGameSaveSubsystem::Initialize(FSubsystemCollectionBase& Collection)
{
    Super::Initialize(Collection);
    UE_LOG(LogTemp, Log, TEXT("[GameSaveSubsystem] Initialized"));
}
 
void UGameSaveSubsystem::SaveSlotAsync(const FString& SlotName, const FOnSaveCompleted& OnDone)
{
    UCommonSaveContainer* Container = Cast<UCommonSaveContainer>(
        UGameplayStatics::CreateSaveGameObject(UCommonSaveContainer::StaticClass()));
    if (!Container) { OnDone.ExecuteIfBound(false); return; }
 
    Container->KV = KV;
    UGameplayStatics::AsyncSaveGameToSlot(Container, SlotName, 0,
        FAsyncSaveGameToSlotDelegate::CreateLambda(
            [OnDone](const FString&, const int32, bool bOk) { OnDone.ExecuteIfBound(bOk); }));
}
 
bool UGameSaveSubsystem::LoadSlot(const FString& SlotName)
{
    if (auto* Container = Cast<UCommonSaveContainer>(
            UGameplayStatics::LoadGameFromSlot(SlotName, 0)))
    {
        KV = Container->KV;
        return true;
    }
    return false;
}
 
void UGameSaveSubsystem::Set(const FString& K, const FString& V) { KV.Add(K, V); }
 
FString UGameSaveSubsystem::Get(const FString& K, const FString& Def) const
{
    const FString* Found = KV.Find(K);
    return Found ? *Found : Def;
}

// Public/Achievements/AchievementSubsystem.h
#pragma once
 
#include "CoreMinimal.h"
#include "Subsystems/GameInstanceSubsystem.h"
#include "AchievementSubsystem.generated.h"
 
UCLASS()
class COMMONGAMESYSTEMSRUNTIME_API UAchievementSubsystem : public UGameInstanceSubsystem
{
    GENERATED_BODY()
public:
    UFUNCTION(BlueprintCallable, Category = "Achievements")
    void Unlock(FName AchievementId);
 
    UFUNCTION(BlueprintCallable, Category = "Achievements")
    void ReportProgress(FName AchievementId, float Percent);
 
private:
    void FlushPending();
    TMap<FName, float> Pending;
};

# CommonGameSystems プラグイン — エージェント向け指示
 
## モジュール境界
- 公開API: `Plugins/CommonGameSystems/Source/CommonGameSystemsRuntime/Public/`
- 内部実装: `Plugins/CommonGameSystems/Source/CommonGameSystemsRuntime/Private/`
- エディタ専用: `Plugins/CommonGameSystems/Source/CommonGameSystemsEditor/`
 
## コード生成時のルール
1. 公開する型・関数には必ず `COMMONGAMESYSTEMSRUNTIME_API` を付与すること
2. `Public/` のヘッダから `Private/` のヘッダを `#include` しないこと
3. 新しい依存モジュールを `Build.cs` に追加するときは、必ず理由をコメントで残すこと
4. `OnlineSubsystem` 関連のコードは null チェックを必須とし、未取得時はローカルキューに溜めること
 
## 命名規約
- サブシステム: `UXxxSubsystem`（GameInstanceSubsystem派生）
- アクターコンポーネント: `UXxxComponent`
- ブループリント呼出可能関数: `BlueprintCallable` または `BlueprintPure`
 
## 禁止事項
- `Plugins/CommonGameSystems/` 配下に `#include "<GameName>/..."` を書くこと（循環依存を生む）
- `Editor` モジュールのヘッダを `Runtime` モジュールから参照すること

"Plugins": [
  {
    "Name": "CommonGameSystems",
    "Enabled": true,
    "MarketplaceURL": "git+https://github.com/yourstudio/CommonGameSystems.git@1.0.0"
  }
]

# .github/workflows/plugin-build.yml
name: Plugin Build
on: [push, pull_request]
 
jobs:
  build:
    runs-on: windows-2022
    steps:
      - uses: actions/checkout@v4
      - name: Setup UE5
        run: |
          # 自社のUE5バイナリパスをマウントする想定
          $env:UE5_ROOT = "C:\UE_5.4"
      - name: Build Plugin
        shell: pwsh
        run: |
          & "$env:UE5_ROOT\Engine\Build\BatchFiles\RunUAT.bat" `
            BuildPlugin `
            -Plugin="$pwd\CommonGameSystems.uplugin" `
            -Package="$pwd\Build\CommonGameSystems-1.0.0" `
            -TargetPlatforms=Win64

// Source/CommonGameSystemsTests/CommonGameSystemsTests.Build.cs
using UnrealBuildTool;
public class CommonGameSystemsTests : ModuleRules
{
    public CommonGameSystemsTests(ReadOnlyTargetRules Target) : base(Target)
    {
        bUseUnity = false;
        PublicDependencyModuleNames.AddRange(new[] {
            "Core", "CoreUObject", "Engine",
            "CommonGameSystemsRuntime", // <- テスト対象モジュール
        });
        PrivateDependencyModuleNames.AddRange(new[] { "AutomationController" });
    }
}

// Private/InventoryStackingTest.cpp
#include "Misc/AutomationTest.h"
#include "Inventory/InventoryComponent.h"
 
IMPLEMENT_SIMPLE_AUTOMATION_TEST(
    FInventoryStackingTest,
    "CommonGameSystems.Inventory.Stacking",
    EAutomationTestFlags::ApplicationContextMask | EAutomationTestFlags::SmokeFilter)
 
bool FInventoryStackingTest::RunTest(const FString& Parameters)
{
    UInventoryComponent* Inv = NewObject<UInventoryComponent>();
    FGameplayTag Tag = FGameplayTag::RequestGameplayTag(FName("Item.Health"));
 
    // 250個のヘルスポーションを追加 — 99 + 99 + 52 の3スロットに分割される想定
    TestTrue(TEXT("Add 250"), Inv->AddItem(Tag, 250));
    TestEqual(TEXT("Total"), Inv->GetQuantity(Tag), 250);
 
    // 100個削除 — 残り150個
    TestTrue(TEXT("Remove 100"), Inv->RemoveItem(Tag, 100));
    TestEqual(TEXT("After remove"), Inv->GetQuantity(Tag), 150);
 
    return true;
}

// PERF: このコンポーネントはサバイバルゲームで最大1万スロットまで使われる想定。
// AddItem/RemoveItem/GetQuantityは特定タグに対し平均O(1)で動くこと。
// 補助インデックスを維持し、Items[]を真実の源とする。

jobs:
  build:
    strategy:
      matrix:
        os: [windows-2022, macos-14]
        engine_version: ["5.4", "5.5"]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - name: Build Plugin
        shell: bash
        run: |
          if [ "${{ matrix.os }}" = "windows-2022" ]; then
            UAT="$UE5_ROOT/Engine/Build/BatchFiles/RunUAT.bat"
          else
            UAT="$UE5_ROOT/Engine/Build/BatchFiles/RunUAT.sh"
          fi
          "$UAT" BuildPlugin -Plugin="$PWD/CommonGameSystems.uplugin" \
            -Package="$PWD/Build/${{ matrix.os }}-${{ matrix.engine_version }}" \
            -TargetPlatforms=Win64+Mac

// Public/CommonGameSystemsRuntime.h
#pragma once
#include "CoreMinimal.h"
DECLARE_LOG_CATEGORY_EXTERN(LogCommonGameSystems, Log, All);

// Private/CommonGameSystemsRuntime.cpp
#include "CommonGameSystemsRuntime.h"
DEFINE_LOG_CATEGORY(LogCommonGameSystems);
 
class FCommonGameSystemsRuntimeModule : public IModuleInterface
{
public:
    virtual void StartupModule() override
    {
        UE_LOG(LogCommonGameSystems, Log, TEXT("CommonGameSystems starting up"));
    }
    virtual void ShutdownModule() override
    {
        UE_LOG(LogCommonGameSystems, Log, TEXT("CommonGameSystems shutting down"));
    }
};
 
IMPLEMENT_MODULE(FCommonGameSystemsRuntimeModule, CommonGameSystemsRuntime)