ue-project-context

UE 项目上下文

目标引擎：UE 5.8。下文中的 API 均已根据 5.8 头文件验证；较旧的形式列在“已弃用——请勿使用”下。

此技能会生成并维护 .agents/ue-project-context.md，这是其他 UE 技能读取的唯一文件，用于了解项目的引擎版本、模块布局、已启用的插件、编码约定、游戏框架类、网络模型和构建目标。它仅读取项目文件（.uproject、*.Build.cs、*.Target.cs、Config/Default*.ini、Plugins/*/*.uplugin）；不会调用任何引擎 API。这是此技能集里刻意采用对话式流程的唯一技能：它写入的每一行都必须来自代码库或用户，绝不能凭猜测。

上下文

如果 .agents/ue-project-context.md 存在，请读取它（模块名称、约定、已启用的插件、GAS／网络设置）。如果文件不存在，也不要停止——此技能就是用来创建它的。

默认流程是先扫描，再访谈。先根据代码库起草内容，再询问用户，让用户进行修正。不要一开始就列出选项菜单。

请求内容……	前往
首次设置，或文件不存在	步骤 1：扫描并起草
要读取的内容及每个文件中要提取的信息	扫描内容
为项目已启用的插件命名	插件检查清单
与用户一起审阅草稿	步骤 2：修正草稿
保存或刷新现有上下文文件	步骤 3：保存并确认
没有 C++ 源码可扫描（仅限蓝图，或全新的空项目）	备用问卷
输出文件的结构	文档模板

步骤 1：扫描并起草

1. 检查 .agents/ue-project-context.md 是否存在。如果存在，请读取它，并将其视为之前的草稿，而不是从头开始。
2. 扫描扫描内容中列出的文件。填写所有能从文件中证实的字段。
3. 将文件无法回答的内容在草稿中标记为 [unknown]。绝不要编造团队规模、编码规则或网络模型。
4. 在一条消息中展示完整草稿，然后转到步骤 2。

即使只完成部分扫描，也值得展示结果。引擎版本、模块列表和插件列表几乎都可以直接从文件中获取，这样能省去大部分访谈。

要扫描的内容

文件	提取内容
*.uproject	EngineAssociation（例如 "EngineAssociation": "5.8"；GUID 表示已注册的源码构建；空值表示引擎目录树中的原生项目）、Modules[]（Name、Type、LoadingPhase）、Plugins[]（Name、Enabled）、TargetPlatforms[]
Source/*/*.Build.cs	模块类名、PublicDependencyModuleNames、PrivateDependencyModuleNames、PublicIncludePathModuleNames、第三方包含路径/库路径，以及任何 PublicDefinitions
Source/*.Target.cs	Type（TargetType.Game、Editor、Client、Server、Program）、ExtraModuleNames、DefaultBuildSettings、IncludeOrderVersion、平台条件
Config/DefaultEngine.ini	[/Script/EngineSettings.GameMapsSettings] — GameDefaultMap、ServerDefaultMap、GlobalDefaultGameMode、GameInstanceClass（模块是 EngineSettings，不是 Engine）；[/Script/Engine.RendererSettings] 用于确定渲染功能集
Config/DefaultGame.ini	项目显示名称和版本；[/Script/Engine.AssetManagerSettings] — PrimaryAssetTypesToScan，可揭示数据驱动的资源布局
Config/DefaultInput.ini	[/Script/Engine.InputSettings] — DefaultPlayerInputClass / DefaultInputComponentClass（/Script/EnhancedInput.EnhancedPlayerInput / EnhancedInputComponent 表示 Enhanced Input 已启用；InputSettings.h:219,223）；遗留的 ActionMappings/AxisMappings；[/Script/EnhancedInput.EnhancedInputDeveloperSettings] 用于 Enhanced Input 项目设置
Config/DefaultGameplayTags.ini	[/Script/GameplayTags.GameplayTagsSettings] — GameplayTagList、GameplayTagTableList、ImportTagsFromConfig
Plugins/*/*.uplugin	内部插件名称、其 Modules[] 及其 Plugins[] 依赖项
Source/*/Public/**（抽查 3–5 个头文件）	实际使用的命名前缀、TObjectPtr 与原始指针、API 宏风格（每个声明都使用 MYGAME_API，或每个头文件定义 #define UE_API MYGAME_API）、DEFINE_LOG_CATEGORY 名称、check/ensure 的用法

还要对 Config/Default*.ini 执行 grep，找出项目自定义的所有其他 [/Script/...] 节；这些节能指出团队实际配置的系统。

插件检查清单

将 .uproject 中的 Plugins[] 与此列表交叉核对，并记录成熟度信息（如果这会改变其他技能给出的建议）。这些是 5.8 中的 .uplugin 名称。

领域	要查找的插件
能力与模块化	GameplayAbilities、GameFeatures（Beta）、ModularGameplay（Beta）、SmartObjects、InstancedActors（Experimental）
输入	EnhancedInput
UI	CommonUI、ModelViewViewModel（Beta）
AI 与模拟	StateTree、GameplayStateTree、MassGameplay（Experimental）、MassAI（Experimental）
动画与移动	Mover（Experimental）、MotionWarping（Beta）、PoseSearch、Chooser、AnimationBudgetAllocator
摄像机	GameplayCameras（Experimental）、EngineCameras
网络	Iris（Beta）、ReplicationGraph（Beta）
音频	Metasound、AudioModulation
特效与程序化生成	Niagara、PCG、ProceduralMeshComponent、GeometryScripting
数据与服务	DataRegistry（Beta）、OnlineSubsystem、OnlineServices、SignificanceManager
流送与消息传递	LevelStreamingPersistence（Experimental）、AsyncMessageSystem（Experimental）

记录 .uplugin 名称，而不是易读的显示名称，以便其他技能能够匹配。如果 Plugins/ 下的项目插件未出现在 .uproject 的 Plugins[] 中，只要其 .uplugin 未设置 "EnabledByDefault": false，它仍处于启用状态（FPlugin::IsEnabledByDefault，Projects/Private/PluginManager.cpp:421-435）；未出现在 Plugins[] 中的引擎插件，只有在其 .uplugin 设置了 "EnabledByDefault": true 时才处于启用状态。记录适用的是哪条规则。

第 2 步：修正草稿

展示草稿，然后向用户提出两个问题：

这份草稿有哪些错误？还缺少什么？

根据用户的回答进行修改，然后只重新展示有改动的部分。重复此过程，直到用户确认内容准确无误。

同样逐步填写 [unknown] 字段，每次填写少量内容，优先处理价值最高的字段：

1. 无法从代码中直接看出的约定——断言策略、头文件组织方式、审查中执行的规则。
2. 游戏框架类名称——GameMode、GameState、PlayerController、PlayerState、Pawn/Character、GameInstance。询问类名称，而不是询问是否存在此类。
3. 联网模型——监听服务器还是专用服务器、经典复制还是 Iris、是否启用推送模型、是否使用 ReplicationGraph。
4. 存档系统、流送模型、AI 技术栈——仅补充文件中尚未能确认的部分。
5. 团队和源代码管理——单人开发者请完全跳过。

[unknown] 和“尚未确定”都是有效的最终答案。团队尚未决定的事项，明确记录为未决定，比根据猜测填写更有价值。

第 3 步：保存并确认

• 将文件写入 .agents/ue-project-context.md，如有需要，创建 .agents/。
• 在文件开头注明引擎版本和日期。
• 告知用户，其他 UE 技能现在会自动读取此文件；项目发生变化时，重新运行此技能即可刷新文件。
• 刷新时，保留用户未重新讨论的部分，并更新日期。

此仓库中的技能以 UE 5.8 为目标。请从 EngineAssociation 中逐字记录项目的实际引擎版本，以便项目使用其他版本时调整相关建议，并注明这是启动器版本还是源码版本。

备用问卷

仅在没有 Source/ 目录树可供扫描时使用（仅有 Blueprint 的项目，或正在规划的空项目）。每次讨论一组，并在继续之前逐项确认。

引擎和项目。 项目名称和一句话描述。引擎版本、启动器版本或源码构建版本。项目类型（游戏、模拟、可视化、工具、插件）和类型。目标平台。

模块。 模块名称、哪个是主游戏模块，以及每个模块的宿主类型（Runtime、Editor、Developer、CookedOnly、UncookedOnly、Program）。各模块的关键依赖项。

插件。 按领域逐项检查插件清单，而不是照着名称念。然后列出 Plugins/ 下的自研插件、对游戏玩法至关重要的 Fab/Marketplace 插件，以及值得记录的任何许可限制。

约定。 使用 Epic 的 F/U/A/E/I 前缀，还是团队自定变体。UPROPERTY 对象引用使用 TObjectPtr，还是裸指针。模块 API 宏风格——在每个声明上使用 MYGAME_API，还是在每个头文件中使用 #define UE_API MYGAME_API。日志类别名称。断言策略（check、checkf、ensure、ensureMsgf、verify）及各自允许使用的位置。Public/Private 头文件布局。代码审查中执行的任何规则。

游戏玩法框架。 GameMode、GameState、PlayerController、PlayerState、Pawn/Character、GameInstance 的类名。正在使用的子系统类及其各自负责的内容。

GAS。 是否启用了 GameplayAbilities；如果启用，说明 AbilitySystemComponent 子类、AttributeSet 类名、能力基类，以及标签层级的定义位置。

联网。 监听服务器、专用服务器还是单人游戏。使用 Iris 还是经典复制。推送模型启用还是关闭。是否使用 ReplicationGraph。预期玩家人数和帧时间预算。

输入。 使用 EnhancedInput 还是旧版映射。UInputMappingContext 和 UInputAction 资源所在位置，以及负责添加上下文的类。

UI。 仅使用 UMG、使用 CommonUI，还是使用 CommonUI 加 ModelViewViewModel。基础 Widget 类，以及 HUD/菜单堆栈的管理方式。

AI。 使用行为树、StateTree/GameplayStateTree、Mass，还是自定义架构。导航设置，以及是否使用 SmartObjects。

流送。 使用带数据层的 World Partition，还是经典子关卡。关卡实例化方案。

存档。 USaveGame 子类名称、存档槽命名和版本管理方案。

构建。 发布哪些目标类型。自定义预处理器定义。第三方库及其集成方式。平台专属代码路径。引擎分支或修改。

团队。 团队规模和角色。源代码管理工具（Perforce、Git、Plastic）。分支和资源锁定策略。审查标准。文档存放位置。

文档模板

按此结构编写 .agents/ue-project-context.md。对于项目确实没有内容可写的部分，删除对应章节。

# UE Project Context

*Engine: UE 5.8 · Last updated: [date]*

## Engine & Project
**Engine version:** [5.8 — launcher build / source build at [path]]
**Project name:** [name] · **Type:** [game / sim / tool] · **Genre:** [genre]
**Description:** [one sentence]
**Target platforms:** [list]

## Modules
**Primary game module:** [ModuleName]

| Module | Host type | Public deps | Private deps | Notes |
|---|---|---|---|---|
| [MyGame] | Runtime | Core, CoreUObject, Engine, InputCore | [list] | [purpose] |
| [MyGameEditor] | Editor | [list] | [list] | [purpose] |

## Plugins
| Plugin | Maturity | Used for |
|---|---|---|
| [EnhancedInput] | [stable] | [input] |
| [Mover] | [Experimental] | [locomotion prototype] |

**In-house plugins:** [Name — purpose]
**Fab / marketplace:** [Name — purpose, licence notes]

## Coding conventions
**Prefixes:** [standard F/U/A/E/I, exceptions]
**Object references:** [TObjectPtr in UPROPERTY / raw pointers]
**API macro style:** [MYGAME_API per declaration / per-header #define UE_API MYGAME_API]
**Log categories:** `[LogMyGame]` — [scope]
**Assertions:** [check where / ensure where / verify where]
**Header layout:** [Public/Private per module / flat]
**Enforced rules:** [list]

## Gameplay framework
| Role | Class |
|---|---|
| GameMode | `[AMyGameMode]` |
| GameState | `[AMyGameState]` |
| PlayerController | `[AMyPlayerController]` |
| PlayerState | `[AMyPlayerState]` |
| Pawn / Character | `[AMyCharacter]` |
| GameInstance | `[UMyGameInstance]` |

**Subsystems:** `[UMyClass]` ([UGameInstanceSubsystem / UWorldSubsystem / ULocalPlayerSubsystem]) — [owns]

## GAS
**Enabled:** [yes / no]
**AbilitySystemComponent:** `[UMyAbilitySystemComponent]` — lives on [PlayerState / Pawn]
**AttributeSets:** `[UMyAttributeSet]` — [attributes]
**Ability base:** `[UMyGameplayAbility]`
**Tag source:** [Config/DefaultGameplayTags.ini / native tags in [file]]

## Networking
**Model:** [single-player / listen server / dedicated server]
**Replication stack:** [classic / Iris (Beta)]
**Push model:** [on / off] · **ReplicationGraph:** [yes / no]
**Budget:** [N players, tick rate]

## Input
**Stack:** [EnhancedInput / legacy]
**Mapping contexts:** [asset paths] · **Added by:** `[class]`

## UI
**Stack:** [UMG / CommonUI / CommonUI + ModelViewViewModel]
**Base widgets:** `[UMyUserWidget]` · **Layer / stack management:** [description]

## AI
**Stack:** [Behavior Trees / StateTree / GameplayStateTree / Mass / custom]
**Navigation:** [NavMesh setup] · **SmartObjects:** [yes / no]

## Streaming
**Model:** [World Partition + Data Layers / sub-levels]
**Notes:** [cell size, streaming sources, level instances]

## Saves
**SaveGame classes:** `[UMySaveGame]` · **Slots:** [naming] · **Versioning:** [approach]

## Build
**Targets:** [Game, Editor, Client, Server]
**Defines:** `[MYGAME_WITH_CHEATS]` — [purpose]
**Third-party:** [Library — binary / source]
**Platform notes:** [platform: constraint]
**Engine modifications:** [none / fork at [repo] — [what changed]]

## Team
**Size & roles:** [N engineers, N designers, N artists]
**Source control:** [Perforce / Git / Plastic] · **Branching:** [strategy]
**Review bar:** [description] · **Docs:** [where]

已弃用 — 请勿使用

Agent 可能会写入上下文文档，或写入根据上下文文档生成的代码中的旧形式。

不要生成	在 5.8 中使用	来源
GENERATED_UCLASS_BODY()	GENERATED_BODY()	CoreUObject/Public/UObject/ObjectMacros.h:803 中的 #define GENERATED_UCLASS_BODY(...) GENERATED_BODY_LEGACY()
UPROPERTY() UObject* Ptr;	UPROPERTY() TObjectPtr<UObject> Ptr;	CoreUObject/Public/UObject/ObjectPtr.h:519 中的 struct TObjectPtr
NetUpdateFrequency = 10.f;	SetNetUpdateFrequency(10.f) / GetNetUpdateFrequency()	Engine/Classes/GameFramework/Actor.h:903 中的 UE_DEPRECATED(5.5)
MinNetUpdateFrequency = 2.f;	SetMinNetUpdateFrequency(2.f) / GetMinNetUpdateFrequency()	Engine/Classes/GameFramework/Actor.h:908 中的 UE_DEPRECATED(5.5)
UDataLayerSubsystem 访问器	对应的 UDataLayerManager 访问器	Engine/Public/WorldPartition/DataLayer/DataLayerSubsystem.h:37 中的 UE_DEPRECATED(5.3)
DefaultInput.ini 中的 bEnableDynamicComponentInputBinding	删除该键	Engine/Classes/GameFramework/InputSettings.h:96 中的 UE_DEPRECATED(5.7)
DefaultInput.ini 中的 SpeechMappings	删除该键	Engine/Classes/GameFramework/InputSettings.h:211 中的 UE_DEPRECATED(5.7)
[/Script/Engine.GameMapsSettings]	[/Script/EngineSettings.GameMapsSettings]	Runtime/EngineSettings/Classes/GameMapsSettings.h:101 中的 class UGameMapsSettings
将 MetaSounds 用作插件名称	Metasound	Engine/Plugins/Runtime/Metasound/Metasound.uplugin

常见错误

开头先提问，而不是先起草：.uproject、*.Build.cs 文件和 Config/Default*.ini 已经能回答文档中的大部分问题。先扫描并起草，再找出问题所在——不要让用户口述磁盘上已有的信息。

**猜测以填补空缺：**捏造团队规模或断言策略，比留空更糟，因为其他技能都会据此采取行动。写上 [unknown]，然后继续。

**填写友好的插件名称：**记录 .uplugin 名称（ModelViewViewModel、Metasound、GameplayAbilities），而不是显示名称，这样其他技能才能将其与 .uproject 中的 Plugins[] 匹配。

**误判插件状态：**如果 .uproject 的 Plugins[] 条目包含 "Enabled": true，或者插件默认启用且未在该处禁用，则插件处于启用状态；而对于 Plugins/ 下的项目插件，如果没有 EnabledByDefault 键，则默认视为启用。

**将 GameMapsSettings 放在 Engine 模块下：**该类位于 EngineSettings 模块，因此对应的节是 [/Script/EngineSettings.GameMapsSettings]。错误的节会被静默忽略。

**遗漏成熟度信息：**Experimental 或 Beta 插件会影响其他技能应给出的建议。Mover（Experimental）、Iris（Beta）和 GameplayCameras（Experimental）都需要在名称旁标注成熟度。

**遗漏模块依赖项：**大多数 UE 链接错误都源于 PublicDependencyModuleNames/PrivateDependencyModuleNames 中缺少条目。逐字记录每个模块的两个列表。

**刷新时覆盖内容：**重新运行时，应合并到现有文件中。用户未重新查看的部分要保留其内容。

相关技能

会读取 .agents/ue-project-context.md 的技能，以及它们从中获取的信息：

• ue-module-build-system — 模块列表、宿主类型、Build.cs 依赖列表、目标类型
• ue-cpp-foundations — 命名前缀、TObjectPtr 策略、API 宏风格、断言策略
• ue-gameplay-framework — GameMode、GameState、PlayerController、PlayerState、Pawn 类
• ue-gameplay-abilities — GAS 设置、AbilitySystemComponent 所有者、AttributeSet 名称
• ue-gameplay-tags-messaging — 标签来源（DefaultGameplayTags.ini 或原生标签）和消息传递栈
• ue-networking-replication — 网络模型、Iris 与经典模式的选择、推送模型、ReplicationGraph
• ue-input-system — Enhanced Input 状态、映射上下文位置、PlayerController 类
• ue-ui-umg-slate — CommonUI / ModelViewViewModel 状态和基础 Widget 类
• ue-blueprint-cpp-interop — API 宏风格，以及哪些系统面向 Blueprint
• ue-actor-component-architecture — 子系统列表和组件约定
• ue-character-movement — Character 类和移动栈
• ue-mover — 是否启用了 Mover 插件（Experimental）
• ue-gameplay-cameras — 是否启用了 GameplayCameras（Experimental）
• ue-ai-navigation — AI 栈、导航设置、SmartObjects 状态
• ue-state-trees — StateTree / GameplayStateTree 插件状态
• ue-world-level-streaming — World Partition 与子关卡的选择、Data Layer 用法
• ue-serialization-savegames — SaveGame 类、插槽命名、版本控制
• ue-testing-debugging — 日志类别、断言策略、模块列表
• ue-editor-tools — Editor 模块名称和编辑器插件列表
• ue-game-features — GameFeatures / ModularGameplay 插件状态