unreal-cpp
Unreal Engine C++ workflow for modules, UHT/reflection, Build.cs, engine API verification, diagnostic logging, and build/test validation. Use for C++ code, reflected types, module dependencies, compile/link/UHT errors, or behavior bugs requiring native investigation.
- License 许可
- MIT
- 最近更新
- 2026-11-12
- Stars
- ★ 3
- Forks
- 1
01 前言 Front Matter
- name
- unreal-cpp
- description
- Unreal Engine C++ workflow for modules, UHT/reflection, Build.cs, engine API verification, diagnostic logging, and build/test validation. Use for C++ code, reflected types, module dependencies, compile/link/UHT errors, or behavior bugs requiring native investigation.
02 资源文件 21
- 参考文档examples/00-examples-index.md2.4 KB
- 参考文档examples/actor-component-health.md4.4 KB
- 参考文档examples/add-reflected-uobject.md7.5 KB
- 参考文档examples/ai-controller-behavior.md1.9 KB
- 参考文档examples/animation-instance-boundary.md1.3 KB
- 参考文档examples/async-timer-lifetime.md2.1 KB
- 参考文档examples/automation-test.md1.8 KB
- 参考文档examples/buildcs-dependencies.md2.1 KB
- 参考文档examples/commonui-activatable-widget.md1.7 KB
- 参考文档examples/dataasset-driven-weapon.md3.8 KB
- 参考文档examples/delegates-events.md6.5 KB
- 参考文档examples/enhanced-input-binding.md3.5 KB
- 参考文档examples/hud-widget-controller.md2.4 KB
- 参考文档examples/interactable-interface.md4.1 KB
- 参考文档examples/logging-and-debug.md7.4 KB
- 参考文档examples/mvvm-status-hud.md6.8 KB
- 参考文档examples/network-replication.md7.6 KB
- 参考文档examples/preset-cvar-bounded-bfs.md4.6 KB
- 参考文档examples/simple-actor-example.md4.2 KB
- 参考文档examples/umg-userwidget.md2.6 KB
- 参考文档examples/ustruct-and-uenum.md5.6 KB
03 SKILL.md 正文
Unreal C++ Skill
Context
- Repository rules:
AGENTS.md - Related skills: Editor workflows, UEEditorMCP, Editor restart, Blueprint/Widget MCP, Material MCP, Niagara MCP, Python
Use this skill for C++ implementation, reflected types, module dependencies, UHT/build/link failures, native editor extensions, replication, automation tests, or behavior bugs that need source-level diagnosis.
Risk And Gate
Classify the touched surface before editing. The classification controls validation; it does not justify widening scope.
| Risk | Typical changes | Minimum gate |
|---|---|---|
| Low | .cpp-only local logic, null check, bounded algorithm, diagnostic repair |
Focused build or test, then diff review |
| Medium | Header/API change without reflection, new native class in an existing module, minimal .Build.cs dependency |
Full Editor target build, focused test, diff review |
| High | Reflection, UObject lifetime, replication/RPC, GAS, async/threading, serialization, module/plugin architecture, Blueprint-visible API | Full Editor target build, launcher restart when required, focused automation or PIE smoke, fresh review |
Never edit generated files or binary assets as C++ source. Do not modify Binaries/, Intermediate/, Saved/, DerivedDataCache/, *.generated.h, or *.gen.cpp.
Default Workflow
- Discover the project shape from
.uproject,Source/*/*.Build.cs,Plugins/*, and existing naming. Do not assume module names or test prefixes. - Keep Runtime and Editor boundaries strict. Runtime modules must not depend on Editor-only modules; editor tools belong in Editor modules or plugins.
- For every unfamiliar engine API, verify the symbol with LSP definition/hover first. If LSP is unavailable, resolve
<EngineRoot>/Engine/Sourcefrom.uprojectand search the engine source read-only. - Put reflected types in headers, include
*.generated.hlast, forward declare in headers where possible, and include concrete headers in.cpp. - Add the smallest needed
.Build.csdependency as soon as a cross-module type is used. - Build and test through the launcher workflow from
AGENTS.md; use MCP log tools, not rawSaved/Logsreads.
Engine Source Resolution
Resolve engine source from the target project, never from a hard-coded install path:
- Read
EngineAssociationfrom the workspace.uproject. - Prefer launcher/editor context or
UE_ENGINE_ROOT/UNREAL_ENGINE_ROOTwhen present; verifyEngine/Sourceexists. - On Windows, check
HKLM:\SOFTWARE\EpicGames\Unreal Engine\<EngineAssociation>InstalledDirectory, thenHKCU:\SOFTWARE\Epic Games\Unreal Engine\Buildsfor source/custom builds. - Fall back to conventional installs only after registry/context lookup.
- If
<EngineRoot>/Engine/Sourceis missing, say local engine source is unavailable and use public docs or reflected metadata instead.
Coding Rules
- Follow Epic style: PascalCase, UE type prefixes,
bbool fields,Outout params,int32/uint8,TEXT(), braces on all control blocks, tab indentation. - Use
TObjectPtrfor reflected UObject references in UE5-era code unless local style differs. - Avoid global
using; UCLASS/USTRUCT/UENUM cannot live in namespaces. - Prefer forward declarations and minimal includes; avoid adding umbrella headers to fix missing dependencies.
- Prefer enum/parameter structs over bool flag APIs.
- Reuse existing log categories where practical; Tick logs must be throttled.
Unreal Lifetime And Execution Rules
- Create default subobjects with
CreateDefaultSubobject, runtime UObjects withNewObject, and actors withSpawnActor; never use rawnew/deletefor UObjects. - Keep owned UObject references visible to GC with the project-standard reflected pointer type. Use weak/soft references when ownership or loading semantics require them.
- Keep world-dependent work out of constructors. Use lifecycle hooks such as
BeginPlay,OnRegister,InitializeComponent, or subsystem initialization. - Do not access UObjects from worker threads unless the API explicitly permits it. Return UObject/world work to the game thread and guard delayed callbacks with weak lifetime checks.
- Clear timers, delegates, and subscriptions at the owning lifecycle boundary when callbacks can outlive the receiver.
Networking And Data Rules
- For replication, state the authority and ownership model before editing. Verify actor/component replication, property registration,
OnRepsignatures, RPC ownership, and dedicated-server behavior. - Treat GAS owner/avatar selection, prediction, replication mode, attribute replication, and ability-task lifetime as explicit design decisions.
- For SaveGame or serialized data, preserve stable identifiers and version/migration behavior. Do not serialize transient UObject pointers as durable state.
- For GameplayTags, discover the project's real tag source and usages; do not parse
.uassetfiles or invent tags from stale examples.
Diagnostic Logging Loop
Use temporary logs only when static reading cannot establish the runtime cause.
- Add short
[DIAG-<TaskTag>]logs at the write/read/fallback points that can explain the mismatch. - Reproduce with launcher automation or PIE, then fetch filtered logs with
unreal.logs.get(filter.contains="DIAG-<TaskTag>", filter.minVerbosity="Warning"). - Identify the exact bad state or call site before changing behavior.
- Fix the root cause, rerun the smallest validation, and remove all
[DIAG-<TaskTag>]logs before delivery unless the user explicitly wants them kept.
Root-Cause Guard
Before a bug fix, answer these briefly in your own reasoning:
- Am I changing the source of the behavior rather than masking the symptom?
- Have I checked every write path, read path, and fallback branch involved?
- Which callers/tests can regress?
- Are temporary logs, TODOs, or stopgap branches being cleaned up?
Patch-style mitigation is acceptable only for urgent breakage or third-party/engine bugs the repo cannot fix directly; mark it with PATCH(<reason>) and the relevant engine/plugin version.
Reflection And Restart
Full rebuild + editor restart is required after:
- USTRUCT/UCLASS/UENUM field or metadata changes.
- UFUNCTION/UPROPERTY signature or reflection metadata changes.
.Build.csdependency changes.- Adding/removing
.cppfiles or modules.
Live Coding is suitable only for implementation body changes that do not alter reflected layout or module graph.
Automation Tests
- Put tests in the owning module's
Tests/directory and guard them with#if WITH_DEV_AUTOMATION_TESTS. - Use project-local naming discovered from existing tests, commonly
<Project>.<Module>.<Subsystem>.<Case>. - Prefer in-memory objects; do not read/write production
Content/assets unless the task is explicitly asset-level.
Common Failures
| Symptom | First checks |
|---|---|
Missing *.generated.h |
Header included by target, generated include is last, reflected macro/body exist. |
| UHT unknown type | Add real include or forward declaration; avoid unsupported template types in reflected signatures. |
| Linker unresolved external | Implementation compiled, module dependency present, symbol exported if cross-module. |
| Runtime object GC issue | Reflected owner uses UPROPERTY / TObjectPtr; async references are guarded. |
| API guessed wrong | Re-check LSP or engine source and cite the actual declaration. |
Examples
Load only the matching card. Every example is a pattern, not project truth: replace module names, API paths, ownership choices, and test suites with discovered local values. The build/test commands in examples are subordinate to AGENTS.md and the launcher workflow.
Existing project examples:
- Adding a reflected UObject type
- Simple AActor-derived class
- USTRUCT and UENUM
- Delegates and events
- Network replication
- Logging and debugging
- MVVM status HUD
- Preset + CVar + bounded BFS
Imported production patterns:
- Examples index and routing
- Actor component health
- UINTERFACE interaction
- DataAsset-driven weapon configuration
- C++ UMG BindWidget
- PlayerController-owned HUD
- Enhanced Input binding
- AIController and Behavior Tree
- Async and timer lifetime
- Build.cs dependency ownership
- Automation test skeleton
- Animation instance boundary
- CommonUI activatable widget
Delivery
Report changed files/symbols, Build.cs impact, whether reflection restart is needed, validation run or recommended launcher suite, temporary log status, and any engine API source references used.
04 同仓库更多 Skills
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
internal-comms
A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).
web-artifacts-builder
Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
frontend-design
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
algorithmic-art
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
theme-factory
Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.