game-build-log-triage（游戏构建日志分类）

Game Build Log Triage

Use this skill to turn noisy Unity and Unreal logs into a short, prioritized debugging brief.

The goal is not to explain every line. The goal is to find the first non-cascading failure, identify the most likely subsystem, and tell the user what to inspect next.

Read references/engine-patterns.md before classifying unfamiliar engine-specific errors.

If the user is not asking about one failing log but about repeated CI instability, cache policy, packaging workflow shape, or release automation for Unity/Unreal projects, route that broader workflow design work to game-ci-cd-pipeline after or alongside this triage.

When to use this skill

• Unity build, import, compile, package, or play-mode startup failures
• Unreal build, UBT/UHT, cook, package, shader, plugin, or module failures
• CI logs from game projects where the raw output is long and noisy
• Asset moves, redirectors, missing references, .meta/GUID, module, or plugin breakages
• Users who provide Editor.log, package output, BuildCookRun logs, stack traces, or console excerpts and want the next debugging steps

Instructions

Step 1: Confirm the engine and log scope

1. Detect whether the material is mainly Unity, Unreal, or mixed/unknown.
2. Record the log source when visible:

- Unity: Editor.log, Console output, package manager output, player build output, CI transcript - Unreal: UBT/UHT output, cook/package logs, Output Log, Message Log, crash log, CI transcript

1. Identify the time window or failing command if present.
2. If the log is huge, focus first on:

- lines containing error, exception, fatal, failed, UHT, UBT, NullReferenceException, MissingReferenceException, Cook failed, AutomationTool exiting, Script compilation error - the first error cluster before a flood of repeated follow-on errors

Step 2: Find the first actionable failure

Work top-down and separate root-cause candidates from cascade noise.

Use this decision order:

1. Hard stop / fatal line — first line that clearly aborts the run
2. Configuration or dependency blocker — missing module, SDK, package, plugin, target, or assembly definition
3. Compile/reflection blocker — C# compiler error, UHT/UBT error, macro/reflection issue, missing symbol, duplicate class, circular dependency
4. Asset/reference blocker — missing asset, redirector fallout, GUID/meta mismatch, bad import, broken prefab/Blueprint reference
5. Environment/platform blocker — Android/iOS/console SDK issue, signing/provisioning, toolchain path, unsupported target
6. Secondary noise — repeated exceptions, retries, or downstream "could not complete" messages

Do not summarize 20 symptoms as if they are 20 causes.

Step 3: Classify the failure bucket

Map the log to one primary bucket and optional secondary bucket.

Primary buckets

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

Typical Unity mappings

• CS0246, CS0103, Assembly has reference to non-existent assembly → compile-code or package-plugin-config
• MissingReferenceException, NullReferenceException during import/build, missing GUID/meta issues → asset-reference
• Package Manager resolution failures, invalid asmdef references, scripting define mismatch → package-plugin-config
• Android SDK/JDK/Gradle/Xcode signing failures → platform-sdk

Typical Unreal mappings

• Unable to instantiate module, missing plugin/module, bad .Build.cs, target rules failures → package-plugin-config
• UHT/UObject/reflection macro errors, generated code issues → compile-reflection
• Cook failed, missing content, redirector/moved asset fallout → asset-reference or build-pipeline-state
• Visual Studio/toolchain/SDK/platform packaging blockers → platform-sdk

Step 4: Produce the triage brief

Return a concise report with this exact structure:

# 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

optional read-only inspection commands only

## What not to do yet

- Avoid shotgun cleanup or broad asset deletion until the primary blocker is verified

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
• Unity Log Files
• Unity Version Control / Smart Merge Support
• Unreal Logging
• Unreal Packaging Projects
• Unreal Redirectors