game-build-log-triage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

使用该技能将Unity和Unreal的冗余日志转化为简短、优先级明确的调试简报。

目标并非解释每一行日志，而是找到首个非连锁故障，确定最可能涉及的子系统，并告知用户下一步检查方向。

在分类不熟悉的引擎特定错误前，请阅读references/engine-patterns.md。

若用户询问的并非单一故障日志，而是Unity/Unreal项目的重复CI不稳定问题、缓存策略、打包工作流架构或发布自动化等内容，请将这类更宽泛的工作流设计任务引导至

game-ci-cd-pipeline

，可在分诊之后或同时进行。

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

Unity构建、资源导入、编译、打包或播放模式启动失败
Unreal构建、UBT/UHT、烘焙、打包、着色器、插件或模块失败
游戏项目的CI日志输出冗长且冗余
资源移动、重定向器缺失、引用丢失、
```
.meta
```
/GUID、模块或插件损坏
用户提供
```
Editor.log
```
、打包输出、BuildCookRun日志、堆栈跟踪或控制台片段，并希望获取下一步调试步骤

Instructions

操作步骤

Step 1: Confirm the engine and log scope

步骤1：确认引擎及日志范围

Detect whether the material is mainly Unity, Unreal, or mixed/unknown.
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
Identify the time window or failing command if present.

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

判断内容主要属于Unity、Unreal还是混合/未知。
记录可见的日志来源：
- Unity：
```
Editor.log
```
  、控制台输出、包管理器输出、玩家构建输出、CI记录
- Unreal：UBT/UHT输出、烘焙/打包日志、输出日志、消息日志、崩溃日志、CI记录
若存在，确定时间窗口或失败命令。

若日志过大，优先关注：

包含

error

、

exception

、

fatal

、

failed

、

UHT

、

UBT

、

NullReferenceException

、

MissingReferenceException

、

Cook failed

、

AutomationTool exiting

、

Script compilation error

的行

大量后续重复错误出现前的首个错误集群

Step 2: Find the first actionable failure

步骤2：定位首个可处理故障

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

Use this decision order:

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

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

自上而下分析，区分根因候选与连锁冗余错误。

遵循以下判断顺序：

强制终止/致命行 —— 明确终止运行的第一行
配置或依赖阻塞 —— 缺失模块、SDK、包、插件、目标或程序集定义
编译/反射阻塞 —— C#编译器错误、UHT/UBT错误、宏/反射问题、缺失符号、重复类、循环依赖
资源/引用阻塞 —— 缺失资源、重定向器失效、GUID/meta不匹配、导入失败、预制件/蓝图引用损坏
环境/平台阻塞 —— Android/iOS/主机SDK问题、签名/配置、工具链路径、不支持的目标平台
次要冗余错误 —— 重复异常、重试或下游“无法完成”消息

请勿将20个症状总结为20个原因。

Step 3: Classify the failure bucket

步骤3：分类故障类别

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

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
```

将日志映射至一个主类别和可选的次要类别。

主类别

```
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

包管理器解析失败、无效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
```

Step 4: Produce the triage brief

步骤4：生成分诊简报

Return a concise report with this exact structure:

markdown

undefined

返回结构严格一致的简洁报告：

markdown

undefined

Game Log Triage

游戏日志分诊

Engine

引擎

Unity | Unreal | Mixed/Unknown

Unity | Unreal | Mixed/Unknown

Log scope

日志范围

Source: ...
Failing command/stage: ...
Confidence: high | medium | low

来源: ...
失败命令/阶段: ...
置信度: high | medium | low

First actionable failure

首个可处理故障

Line or excerpt:
```
...
```
Why it matters: ...
Why later errors look secondary: ...

行或片段:
```
...
```
影响原因: ...
后续错误为何属于次要: ...

Classification

Most likely root cause

最可能的根因

1-3 sentence explanation grounded in the log

基于日志的1-3句解释

Next checks

下一步检查

Files / settings to inspect

需检查的文件/设置

Safe follow-up commands

安全的后续命令

bash

undefined

bash

undefined

optional read-only inspection commands only

仅可选的只读检查命令

undefined

undefined

What not to do yet

暂勿执行的操作

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

undefined

在确认主阻塞问题前，避免随意清理或大范围删除资源

undefined

Step 5: Tailor the next checks to the engine

步骤5：针对引擎调整下一步检查

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

针对Unity，优先检查以下内容:

Packages/manifest.json

、

Packages/packages-lock.json

```
.asmdef
```
引用及脚本定义符号
```
ProjectSettings/
```
、平台构建设置、签名/工具链路径
近期资源移动、
```
.meta
```
文件、GUID稳定性、预制件/场景引用
出现大量
```
NullReferenceException
```
之前的首个编译器错误

针对Unreal，优先检查以下内容:

```
.uproject
```
、插件启用状态、
```
Source/*/*.Build.cs
```
、目标文件
打包/烘焙失效之前的首个UBT/UHT错误
重定向器、缺失资源、移动的内容、生成代码不匹配
平台SDK/工具链前置条件及AutomationTool阶段
故障是否在重命名类/资源或修改模块/插件后出现

Step 6: Escalate carefully when evidence is weak

步骤6：证据不足时谨慎升级

If the log excerpt is too short or starts mid-cascade:

Say that confidence is low.
Ask for the earliest error cluster or the failing command section.
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.

若日志片段过短或从连锁错误中间开始：

说明置信度较低。
请求提供首个错误集群或失败命令部分。
列出所需的最少额外上下文：
- 首个错误前后50-150行内容
- 引擎版本
- 目标平台
- 故障是否在代码/包/资源/插件变更后出现

请勿对截断的片段做出确定性结论。

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

始终返回简短的调试简报，而非流水账式分析。

必备特质：

优先处理首个可处理的阻塞问题
区分根因与连锁冗余错误
报告字数控制在约250-400字以内，除非用户要求更多内容
若引擎提示相关路径，需包含需检查的文件路径/设置
仅提供只读Shell建议，除非用户明确要求修复方案

Examples

示例

Example 1: Unity compile + package drift

示例1：Unity编译 + 包版本偏移

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

输入

Unity构建在我们更新某个包后失败。日志显示
CS0246: The type or namespace name 'InputSystem' could not be found
，随后出现数十条
NullReferenceException
行。

输出概要

引擎: Unity
首个可处理故障:
```
CS0246
```
关于
```
InputSystem
```
分类:
```
package-plugin-config
```
根因: 包或asmdef引用偏移导致编译阻塞；后续空引用异常可能是编译/导入失败状态引发的连锁问题
下一步检查:
1. 确认
```
Packages/manifest.json
```
  仍包含Input System包
2. 检查受影响程序集的asmdef引用
3. 验证脚本定义符号或包迁移说明

Example 2: Unreal cook failure after asset moves

示例2：资源移动后Unreal烘焙失败

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

输入

我们重命名文件夹后，Unreal烘焙开始失败。日志显示
Cook failed
及多条缺失资源警告。

输出概要

引擎: Unreal
首个可处理故障:
```
Cook failed
```
之前最早的缺失资源/重定向器相关行
分类:
```
asset-reference
```
根因: 移动的内容可能留下未修复的损坏引用或重定向器，导致烘焙失败
下一步检查:
1. 检查移动资源的路径及重定向器
2. 对日志中引用的缺失资源执行只读审计
3. 验证插件/资源路径是否随重命名发生变化

Example 3: Unreal UHT blocker

示例3：Unreal UHT阻塞

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

输入

CI显示重构后
UnrealHeaderTool failed
。

输出概要

引擎: Unreal
首个可处理故障: 首个UHT反射/宏错误，而非后续AutomationTool退出行
分类:
```
compile-reflection
```
根因: 生成代码步骤中头文件/反射元数据不匹配
下一步检查:
1. 检查相关头文件及宏使用
2. 对比近期重命名的类或移动的模块
3. 验证所属模块中的生成代码依赖

Best practices

最佳实践

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

优先处理最早的阻塞问题 —— 游戏引擎日志的连锁效应严重。
明确子系统 —— 编译、反射、资源/引用、插件/配置或平台SDK。
优先指定具体检查目标 —— 而非“全部重建”这类通用建议。
优先安全修复 —— 在执行破坏性清理前，先使用只读命令和针对性检查。
高度关注资源移动操作 —— 两款引擎中均需重点排查。
说明置信度 —— 当片段不完整或冗余时。
使用团队已熟悉的引擎术语: asmdef、GUID/meta、UBT/UHT、重定向器、BuildCookRun等。

game-build-log-triage

Original

Translation

Game Build Log Triage

游戏构建日志故障分诊

When to use this skill

何时使用该技能

Instructions

操作步骤

Step 1: Confirm the engine and log scope

步骤1：确认引擎及日志范围

Step 2: Find the first actionable failure

步骤2：定位首个可处理故障

Step 3: Classify the failure bucket

步骤3：分类故障类别

Step 4: Produce the triage brief

步骤4：生成分诊简报

Game Log Triage

游戏日志分诊

Engine

引擎

Log scope

日志范围

First actionable failure

首个可处理故障

Classification

分类

Most likely root cause

最可能的根因

Next checks

下一步检查

Files / settings to inspect

需检查的文件/设置

Safe follow-up commands

安全的后续命令

optional read-only inspection commands only

仅可选的只读检查命令

What not to do yet

暂勿执行的操作

Step 5: Tailor the next checks to the engine

步骤5：针对引擎调整下一步检查

Step 6: Escalate carefully when evidence is weak

步骤6：证据不足时谨慎升级

Output format

输出格式

Examples

示例

Example 1: Unity compile + package drift

示例1：Unity编译 + 包版本偏移

Example 2: Unreal cook failure after asset moves

示例2：资源移动后Unreal烘焙失败

Example 3: Unreal UHT blocker

示例3：Unreal UHT阻塞

Best practices

最佳实践

References

参考资料