unreal-engine

Unreal Engine 開発アシスタント

基本理念：思い込みをしない

重要：ユーザーのプロジェクトについて、決して思い込みで判断しないでください。Unreal プロジェクトごとに、構造、アセット、設定は異なります。コードやアセットを提案する前に、必ず確認してください。

事前調査プロトコル

ユーザーから Unreal Engine について質問された場合、必ず最初に次の調査手順を実行してください。

1. .uproject ファイルを探す

find . -maxdepth 2 -name "*.uproject" -type f

見つかった場合：ファイルを読み取り、次の情報を抽出します。

• "EngineAssociation" フィールドからエンジンのバージョン
• ファイル名からプロジェクト名
• "Plugins" 配列から有効なプラグイン
• "Modules" 配列からモジュールの依存関係

.uproject の構造例：

{
  "FileVersion": 3,
  "EngineAssociation": "5.7",  // ← Engine version
  "Category": "",
  "Description": "",
  "Modules": [
    {
      "Name": "ProjectName",  // ← Module name
      "Type": "Runtime",
      "LoadingPhase": "Default",
      "AdditionalDependencies": ["Engine", "GameplayAbilities"]
    }
  ],
  "Plugins": [
    {"Name": "EnhancedInput", "Enabled": true},
    {"Name": "GameplayAbilities", "Enabled": true}
  ]
}

2. プロジェクト構造を把握する

Unreal プロジェクトの標準的な構成：

ProjectRoot/
├── ProjectName.uproject       ← Project file
├── Source/                    ← C++ source code
│   ├── ProjectName/           ← Main module
│   │   ├── Public/            ← Header files (.h)
│   │   ├── Private/           ← Implementation files (.cpp)
│   │   └── ProjectName.Build.cs ← Build configuration
│   └── ProjectNameEditor/ (optional) ← Editor-only code
├── Content/                   ← All assets (.uasset files)
│   ├── Blueprints/           ← Common location for BPs
│   ├── Input/                ← Input Actions & Mapping Contexts
│   ├── Characters/           ← Character assets
│   ├── UI/                   ← UMG widgets
│   └── [project-specific folders]
├── Config/                    ← Configuration .ini files
│   ├── DefaultEngine.ini     ← Engine settings
│   ├── DefaultInput.ini      ← Legacy input config
│   └── DefaultGame.ini       ← Game-specific config
├── Plugins/                   ← Project plugins
├── Intermediate/              ← Build artifacts (ignore)
├── Saved/                     ← Logs, configs (ignore)
└── Binaries/                  ← Compiled executables (ignore)

次の調査コマンドを実行します。

# Find C++ classes
view Source/*/Public
view Source/*/Private

# Discover Content assets (especially Input Actions)
find Content -type f -name "*.uasset" | head -50

# For Input Actions specifically
find Content -type f -name "*IA_*" -o -name "*InputAction*"

# For Input Mapping Contexts
find Content -type f -name "*IMC_*" -o -name "*InputMappingContext*"

# Find Blueprint classes
find Content -type f -name "BP_*.uasset"

3. 既存のコードを理解する

コードを提案する前に、必ず次のことを行います。

• 既存のキャラクター／コントローラークラスを読み、パターンを理解します
• 追加済みのコンポーネントを確認します
• 命名規則（例：Input Action の IA_ プレフィックス）を特定します
• 既存のヘルパークラスや基底クラスを探します

# Example: Find character class
find Source -name "*Character.h" -o -name "*Character.cpp"

入力システムの取り扱い

Enhanced Input System（UE5 以降）

入力アクションの名前を決して思い込みで判断しないでください。必ず最初に調べます。

# Find Input Actions in Content
find Content -type f \( -name "IA_*.uasset" -o -name "*InputAction*.uasset" \)

# Find Input Mapping Contexts
find Content -type f \( -name "IMC_*.uasset" -o -name "*MappingContext*.uasset" \)

一般的な Input Action のパターン：

• IA_Move または IA_Movement（Axis2D）
• IA_Look（Axis2D）
• IA_Jump（Boolean）
• IA_Interact（Boolean）

ただし、プロジェクトごとに異なる命名規則が使われているため、必ず確認してください。

C++ での Input Action のバインド

Enhanced Input をバインドするテンプレート：

#include "EnhancedInputComponent.h"
#include "EnhancedInputSubsystems.h"
#include "InputAction.h"

// In SetupPlayerInputComponent
void AMyCharacter::SetupPlayerInputComponent(UInputComponent* PlayerInputComponent)
{
    Super::SetupPlayerInputComponent(PlayerInputComponent);
    
    // Cast to Enhanced Input Component
    if (UEnhancedInputComponent* EnhancedInput = Cast<UEnhancedInputComponent>(PlayerInputComponent))
    {
        // Bind actions - VERIFY THESE ASSET PATHS EXIST
        EnhancedInput->BindAction(MoveAction, ETriggerEvent::Triggered, this, &AMyCharacter::Move);
        EnhancedInput->BindAction(LookAction, ETriggerEvent::Triggered, this, &AMyCharacter::Look);
        EnhancedInput->BindAction(JumpAction, ETriggerEvent::Started, this, &AMyCharacter::Jump);
    }
}

ヘッダーの宣言：

UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Input")
UInputAction* MoveAction;

UPROPERTY(EditAnywhere, BlueprintReadOnly, Category = "Input")
UInputAction* LookAction;

.uasset ファイルと Blueprint の読み取り

.uasset ファイルはバイナリ形式で、テキストエディターではほとんど読み取れません。ただし、次の情報は確認できる場合があります。

• 一部のメタデータ（アセット名、パス、GUID）
• プロパティ名と文字列値
• アセット参照や依存関係の特定に役立つ情報

実装の詳細を把握するために、.uasset の内容に依存しないでください。

より良い方法：find を使ってアセットを見つけてから、ユーザーに確認するか、内容を説明してもらいます。

Gameplay Ability System（GAS）

GAS を使用するプロジェクトで作業する場合は（.uproject で "GameplayAbilities" プラグインを確認してください）：

GAS の重要な設定要件

1. Build.cs の依存関係：

PublicDependencyModuleNames.AddRange(new string[] { 
    "Core", "CoreUObject", "Engine", "InputCore",
    "GameplayAbilities",
    "GameplayTags", 
    "GameplayTasks"
});

2. Ability System Component の配置：

• シングルプレイヤーまたはリッスンサーバーの場合：Character に配置できます
• 専用サーバーの場合：通常は PlayerState に配置します（プレイヤー所有のアクターの場合）
• AI／NPC の場合：Character またはカスタムアクターに配置できます

3. 主な GAS クラス：

• UAbilitySystemComponent - 中核となるコンポーネント
• UGameplayAbility - アビリティの基底クラス
• UAttributeSet - ゲームプレイ属性（体力、スタミナなど）を保持します
• UGameplayEffect - 属性を変更します
• FGameplayTag - アビリティシステムのタグ

一般的な GAS のパターン

アビリティの付与：

// In C++
AbilitySystemComponent->GiveAbility(
    FGameplayAbilitySpec(AbilityClass, 1, INDEX_NONE, this)
);

アビリティの有効化：

// By class
AbilitySystemComponent->TryActivateAbilityByClass(AbilityClass);

// By tag
FGameplayTagContainer TagContainer;
TagContainer.AddTag(FGameplayTag::RequestGameplayTag(FName("Ability.Dash")));
AbilitySystemComponent->TryActivateAbilitiesByTag(TagContainer);

プラグイン固有のガイダンス

不明または実験的なプラグイン

不慣れなプラグイン（例：Mutable、MutableClothing、RelativeIKOp）に遭遇した場合：

1. 公式ドキュメントを検索します：

web_search: "Unreal Engine [PluginName] documentation API"
web_search: "Unreal Engine [PluginName] usage examples"

2. アクセスできる場合は、ソースコードを確認します：

# Engine plugins location (if user has source build)
find /path/to/UE5/Engine/Plugins -name "PluginName"

3. 率直に伝えます：「このプラグインは実験的で、ドキュメントも十分ではありません。最新情報を検索します……」

API に関する知識が不十分な場合

API の使い方が不確かな場合：

1. Epic のドキュメントを検索します：

web_search: "Unreal Engine [ClassName] API [EngineVersion]"

2. コミュニティのリソースを検索します：

web_search: "Unreal Engine [feature] example code C++"

3. Epic Developer Community のフォーラムを確認します
4. サンプルプロジェクト（Lyra、Valley of the Ancient、ActionRPG）を探します

避けるべきよくある落とし穴

❌ 誤り：思い込みで判断する

// DON'T assume this exists
EnhancedInput->BindAction(IA_Jump, ETriggerEvent::Started, this, &AMyCharacter::Jump);

✓ 正解：まず調査する

# Find what Input Actions actually exist
find Content -name "*IA_*"
# Then ask user or use discovered names

❌ 誤り：汎用的なアクション名を使う

// Too generic - what if they use IA_PlayerJump?
UPROPERTY(EditAnywhere, Category = "Input")
UInputAction* JumpAction;

✓ 正解：アセット名を確認する

# Discover actual naming convention
find Content/Input -name "*.uasset"
# Results might show: IA_Jump, IA_PlayerJump, InputAction_Jump, etc.

バージョン固有の注意点

エンジンのバージョンを特定する

必ず .uproject の "EngineAssociation" を確認してください。

• 5.0-5.4：Enhanced Input は安定版、GAS の改善は実験的
• 5.5+：Mutable／Customization システム、新しい入力機能
• 4.27：レガシー入力システム。Enhanced Input の手動設定が必要

バージョン固有の機能

コードを提案する際は、そのバージョンに機能が存在するか確認してください：

web_search: "Unreal Engine [feature] [version] availability"

ワークフローの判断ツリー

User asks for Unreal help
    │
    ├─> Find .uproject ─> Extract version & plugins
    │
    ├─> Map project structure ─> View Source/ and Content/
    │
    ├─> Identify question type:
    │   ├─> Input system? ─> Discover Input Actions/Contexts
    │   ├─> GAS-related? ─> Check GAS setup, discover abilities
    │   ├─> Plugin-specific? ─> Search documentation
    │   └─> General C++? ─> Read existing classes for patterns
    │
    ├─> Provide solution with:
    │   ├─> Verified asset references
    │   ├─> Version-appropriate code
    │   └─> Project-specific patterns
    │
    └─> If uncertain about API/plugin ─> Search documentation

ベストプラクティスのチェックリスト

コードを提案する前に、必ず以下を確認してください：

• .uproject ファイルを見つけて読みました
• エンジンのバージョンを特定しました
• Source/ ディレクトリの構造を把握しました
• Content/ アセットを確認しました（特に入力／ブループリント関連）
• 既存のクラスファイルを読み、パターンを把握しました
• アセットのパスと名前を確認しました
• プラグインが利用可能か確認しました
• 不確かな API についてドキュメントを検索しました
• プロジェクト固有の命名規則を使用しました

コマンド早見表

# Engine version
grep "EngineAssociation" *.uproject

# Find C++ classes
find Source -name "*.h" -o -name "*.cpp" | head -20

# Find Input Actions
find Content -name "IA_*.uasset" -o -name "*InputAction*.uasset"

# Find Blueprints
find Content -name "BP_*.uasset" | head -20

# Find config files
ls -la Config/

# Check for GAS
grep -i "GameplayAbilities" *.uproject

詳細なリファレンス

このスキルには、特定のトピックに関する包括的なリファレンスドキュメントが含まれています。必要に応じて読み込んでください：

references/enhanced_input.md

Enhanced Input System を使用する場合に読み込みます：

• Input Actions、Mapping Contexts、Triggers の詳細な API リファレンス
• バインドの完全な例とパターン
• 値の型の扱い（Digital、Axis1D、Axis2D、Axis3D）
• コンソールコマンドとデバッグのヒント
• レガシー入力システムからの移行

references/gameplay_ability_system.md

GAS を使用する場合に読み込みます：

• 完全なセットアップガイド（ASC、AttributeSet、Abilities、Effects）
• レプリケーション戦略（PlayerState と Character の配置）
• アビリティの付与と有効化
• Gameplay Tags の使用方法
• 属性変更のパターン
• 一般的な GAS のパターン（ダメージ、クールダウン、コスト）
• デバッグとベストプラクティス

references/common_pitfalls.md

トラブルシューティングを行う場合やエラーが発生した場合に読み込みます：

• 入力システムの問題と解決策
• GAS の有効化に関する問題
• ビルドとコンパイルのエラー
• ブループリント／C++ の連携に関する問題
• アセット参照の問題
• プラグインのトラブルシューティング
• パフォーマンスのデバッグ
• 緊急時の復旧手順