game-build-log-triage

ゲームビルドログのトリアージ

このスキルを使って、ノイズの多い Unity および Unreal のログを、簡潔で優先順位付けされたデバッグ概要にまとめます。

目的は、すべての行を説明することではありません。後続エラーを引き起こしていない最初の失敗を見つけ、最も可能性の高いサブシステムを特定し、次に確認すべき項目をユーザーに伝えることです。

不慣れなエンジン固有のエラーを分類する前に、references/engine-patterns.md を読んでください。

ユーザーが単一の失敗ログについてではなく、CI の不安定さが繰り返し発生する問題、キャッシュポリシー、パッケージングのワークフロー構成、または Unity／Unreal プロジェクトのリリース自動化について尋ねている場合は、このトリアージの後、または並行して、より広範なワークフロー設計の作業を game-ci-cd-pipeline に引き継いでください。

このスキルを使用する場面

• Unity のビルド、インポート、コンパイル、パッケージ、またはプレイモード起動の失敗
• Unreal のビルド、UBT／UHT、クック、パッケージ、シェーダー、プラグイン、またはモジュールの失敗
• 生の出力が長く、ノイズの多いゲームプロジェクトの CI ログ
• アセットの移動、リダイレクター、参照切れ、.meta／GUID、モジュール、またはプラグインの不具合
• Editor.log、パッケージ出力、BuildCookRun ログ、スタックトレース、またはコンソール出力を提示し、次のデバッグ手順を求めるユーザー

手順

ステップ 1：エンジンとログの範囲を確認する

1. 提示された情報が主に Unity、Unreal、または 混在／不明 のどれに該当するかを判定します。
2. 確認できる場合は、ログのソースを記録します。
   • Unity：Editor.log、Console 出力、パッケージマネージャー出力、プレイヤービルド出力、CI の記録
   • Unreal：UBT／UHT 出力、クック／パッケージログ、Output Log、Message Log、クラッシュログ、CI の記録
3. 該当する場合は、時間範囲または失敗したコマンドを特定します。
4. ログが非常に大きい場合は、まず次の項目に注目します。
   • error、exception、fatal、failed、UHT、UBT、NullReferenceException、MissingReferenceException、Cook failed、AutomationTool exiting、Script compilation error を含む行
   • 繰り返し発生する後続エラーが大量に出る前の、最初のエラー群

ステップ 2：最初の対処可能な失敗を見つける

上から順に確認し、根本原因の候補と連鎖的なノイズを切り分けます。

次の順序で判定します。

1. 停止／致命的な行 — 実行を明確に中断させた最初の行
2. 設定または依存関係の阻害要因 — モジュール、SDK、パッケージ、プラグイン、ターゲット、またはアセンブリ定義の不足
3. コンパイル／リフレクションの阻害要因 — C# コンパイラーエラー、UHT／UBT エラー、マクロ／リフレクションの問題、シンボル不足、クラスの重複、循環依存
4. アセット／参照の阻害要因 — アセットの不足、リダイレクターの影響、GUID／meta の不一致、不正なインポート、壊れたプレハブ／Blueprint 参照
5. 環境／プラットフォームの阻害要因 — Android／iOS／コンソール SDK の問題、署名／プロビジョニング、ツールチェーンのパス、非対応ターゲット
6. 二次的なノイズ — 例外の繰り返し、再試行、または後続の「完了できませんでした」というメッセージ

20 個の症状を、あたかも20個の原因であるかのように要約してはいけません。

ステップ 3：失敗の分類を判定する

ログを1つの主要な分類と、任意で1つの副次的な分類に割り当てます。

主要な分類

• compile-code
• compile-reflection
• asset-reference
• package-plugin-config
• platform-sdk
• build-pipeline-state
• runtime-startup
• unknown-needs-more-context

Unity の一般的な分類例

• CS0246、CS0103、Assembly has reference to non-existent assembly → compile-code または package-plugin-config
• インポート／ビルド中の MissingReferenceException、NullReferenceException、GUID／meta の不足に関する問題 → asset-reference
• Package Manager の解決失敗、無効な asmdef 参照、スクリプティング定義の不一致 → package-plugin-config
• Android SDK／JDK／Gradle／Xcode の署名に関する失敗 → platform-sdk

Unreal の一般的な分類例

• Unable to instantiate module、プラグイン／モジュールの不足、不正な .Build.cs、ターゲットルールの失敗 → package-plugin-config
• UHT／UObject／リフレクションマクロのエラー、生成コードの問題 → compile-reflection
• Cook failed、コンテンツの不足、リダイレクター／移動済みアセットの影響 → asset-reference または build-pipeline-state
• Visual Studio／ツールチェーン／SDK／プラットフォームのパッケージングを妨げる問題 → platform-sdk

ステップ 4：トリアージ概要を作成する

次の正確な構成で、簡潔なレポートを返してください。

# Game Log Triage

## Engine
- Unity | Unreal | Mixed/Unknown

## Log scope
- Source: ...
- Failing command/stage: ...
- Confidence: high | medium | low

## First actionable failure
- Line or excerpt: `...`
- Why it matters: ...
- Why later errors look secondary: ...

## Classification
- Primary bucket: ...
- Secondary bucket: ...

## Most likely root cause
- 1-3 sentence explanation grounded in the log

## Next checks
1. ...
2. ...
3. ...

## Files / settings to inspect
- ...
- ...
- ...

## Safe follow-up commands
```bash
# optional read-only inspection commands only

まだ行わないこと

• 主な阻害要因が確認されるまでは、手当たり次第のクリーンアップや広範囲にわたるアセットの削除を避けてください

### Step 5: Tailor the next checks to the engine
**For Unity, prefer checks like:**
- `Packages/manifest.json`, `Packages/packages-lock.json`
- `.asmdef` references and scripting define symbols
- `ProjectSettings/`, platform build settings, signing/toolchain paths
- recent asset moves, `.meta` files, GUID stability, prefab/scene references
- the first compiler error before any `NullReferenceException` flood

**For Unreal, prefer checks like:**
- `.uproject`, plugin enablement, `Source/*/*.Build.cs`, target files
- first UBT/UHT error before package/cook fallout
- redirectors, missing assets, moved content, generated code mismatches
- platform SDK/toolchain prerequisites and AutomationTool stage
- whether the failure started after renaming classes/assets or changing modules/plugins

### Step 6: Escalate carefully when evidence is weak
If the log excerpt is too short or starts mid-cascade:
1. Say that confidence is low.
2. Ask for the earliest error cluster or the failing command section.
3. List the minimum extra context required:
   - first 50-150 lines around the first error
   - engine version
   - target platform
   - whether the breakage followed code/package/asset/plugin changes

Do not pretend certainty from a truncated excerpt.

## Output format
Always return a short debugging brief, not a stream-of-consciousness analysis.

Required qualities:
- prioritize the first actionable blocker
- separate root cause from cascade noise
- keep the report under roughly 250-400 words unless the user asks for more
- include file paths/settings to inspect when the engine suggests them
- keep shell suggestions read-only unless the user explicitly asks for fixes

## Examples

### Example 1: Unity compile + package drift
**Input**
> Unity build failed after we updated a package. The log shows `CS0246: The type or namespace name 'InputSystem' could not be found` and then dozens of `NullReferenceException` lines.

**Output sketch**
- Engine: Unity
- First actionable failure: `CS0246` for `InputSystem`
- Classification: `package-plugin-config`
- Root cause: package or asmdef reference drift is blocking compilation; the later null refs are likely fallout from the failed compile/import state
- Next checks:
  1. confirm `Packages/manifest.json` still includes the Input System package
  2. inspect asmdef references for the affected assembly
  3. verify scripting define symbols or package migration notes

### Example 2: Unreal cook failure after asset moves
**Input**
> Unreal cook started failing after we renamed folders. The log shows `Cook failed` and multiple missing asset warnings.

**Output sketch**
- Engine: Unreal
- First actionable failure: earliest missing asset / redirector-related line before `Cook failed`
- Classification: `asset-reference`
- Root cause: moved content likely left broken references or redirectors that were not fixed up before cook
- Next checks:
  1. inspect moved asset paths and redirectors
  2. run a read-only audit of referenced missing assets from the log
  3. verify whether plugin/content paths changed with the rename

### Example 3: Unreal UHT blocker
**Input**
> CI says `UnrealHeaderTool failed` after a refactor.

**Output sketch**
- Engine: Unreal
- First actionable failure: first UHT reflection/macros error, not later AutomationTool exit lines
- Classification: `compile-reflection`
- Root cause: header/reflection metadata mismatch during generated code step
- Next checks:
  1. inspect the referenced header and macro usage
  2. compare recent renamed classes or moved modules
  3. verify generated-code dependencies in the owning module

## Best practices
1. **Lead with the earliest blocker** — game-engine logs cascade badly.
2. **Name the subsystem** — compile, reflection, asset/reference, plugin/config, or platform SDK.
3. **Prefer specific inspection targets** over generic advice like "rebuild everything."
4. **Keep remediation safe-first** — read-only commands and targeted checks before destructive cleanup.
5. **Treat asset moves as high-suspicion events** in both engines.
6. **Explain confidence** when the excerpt is partial or noisy.
7. **Use engine language the team already uses**: asmdef, GUID/meta, UBT/UHT, redirectors, BuildCookRun, etc.

## References
- [Unity Console](https://docs.unity3d.com/Manual/Console.html)
- [Unity Log Files](https://docs.unity3d.com/Manual/log-files.html)
- [Unity Version Control / Smart Merge Support](https://docs.unity3d.com/Manual/ExternalVersionControlSystemSupport.html)
- [Unreal Logging](https://dev.epicgames.com/documentation/en-us/unreal-engine/logging-in-unreal-engine)
- [Unreal Packaging Projects](https://docs.unrealengine.com/5.0/en-US/packaging-unreal-engine-projects/)
- [Unreal Redirectors](https://docs.unrealengine.com/5.0/en-US/redirectors-in-unreal-engine/)