claude-code-arcane 2.3.0 → 2.5.0

package/skills/ue-module-build-system/references/common-build-errors.md

@@ -0,0 +1,381 @@
+# Common UE Build Errors: Causes and Solutions
+
+This reference maps common Unreal Build Tool (UBT) and compiler/linker error messages to their root causes and concrete fixes.
+
+---
+
+## Linker Errors (LNK)
+
+### LNK2019 — Unresolved External Symbol
+
+**Full message pattern**:
+```
+error LNK2019: unresolved external symbol "public: void __cdecl FSomeClass::SomeMethod(void)"
+    referenced in function "..."
+```
+
+**Cause A: Missing module dependency**
+
+The module containing `FSomeClass` is not listed as a dependency.
+
+Fix: Add the module to `Build.cs`:
+```csharp
+PrivateDependencyModuleNames.Add("TheModuleThatDefinesFSomeClass");
+```
+
+**Cause B: Missing `MODULENAME_API` export macro**
+
+`FSomeClass` exists in another module but was never marked for DLL export.
+
+Fix: Add the macro to the class or function declaration:
+```cpp
+// Before:
+class FSomeClass { void SomeMethod(); };
+
+// After:
+class MYMODULE_API FSomeClass { void SomeMethod(); };
+```
+
+**Cause C: Function defined in a .cpp but declared in a header without the macro**
+
+```cpp
+// Header — export the declaration
+MYMODULE_API void SomeFreeFunction();
+
+// .cpp — no macro needed here, definition is in the same module
+void SomeFreeFunction() { ... }
+```
+
+**Cause D: Dependency listed in PrivateDependencyModuleNames but type appears in a public header**
+
+A type from a private dependency cannot be used in your public headers. Either:
+- Move the type usage to your Private/ .cpp files, OR
+- Promote the dependency to `PublicDependencyModuleNames`
+
+### LNK2001 — Unresolved External Symbol (variant)
+
+```
+error LNK2001: unresolved external symbol __declspec(dllimport) ...
+```
+
+This is the same problem as LNK2019. Follow the same fixes.
+
+### LNK4099 — PDB Not Found
+
+```
+warning LNK4099: PDB 'SomeLib.pdb' was not found
+```
+
+Usually harmless for third-party libraries. Suppress with a linker flag in Build.cs:
+```csharp
+// Suppress PDB warnings for external libraries
+PublicAdditionalLibraries can omit .pdb — or suppress via:
+// bDisableSymbolLocalization = true  (or ignore in project linker settings)
+```
+
+### LNK1104 — Cannot Open File
+
+```
+fatal error LNK1104: cannot open file 'SomeLib.lib'
+```
+
+**Cause**: A library path in `PublicAdditionalLibraries` points to a file that doesn't exist.
+
+**Fix**: Verify the path. Use `Path.Combine` to build platform-correct paths:
+```csharp
+string LibPath = Path.Combine(ModuleDirectory, "lib", "Win64", "SomeLib.lib");
+if (File.Exists(LibPath))
+{
+    PublicAdditionalLibraries.Add(LibPath);
+}
+```
+
+---
+
+## Compiler Errors (C-series, clang)
+
+### C1083 — Cannot Open Include File
+
+```
+fatal error C1083: Cannot open include file: 'SomeHeader.h': No such file or directory
+```
+
+**Cause A: Missing module dependency**
+
+The module that owns `SomeHeader.h` is not a dependency.
+
+Fix:
+```csharp
+PublicDependencyModuleNames.Add("TheModuleThatOwnsSomeHeader");
+// or
+PrivateDependencyModuleNames.Add("TheModuleThatOwnsSomeHeader");
+```
+
+**Cause B: Wrong include path in IWYU mode**
+
+UE5 with `PCHUsage = UseExplicitOrSharedPCHs` requires full paths relative to a module's `Public/` root.
+
+```cpp
+// Wrong — works only if PCH pulls it in transitively
+#include "Actor.h"
+
+// Correct — explicit path from module root
+#include "GameFramework/Actor.h"
+```
+
+**Cause C: Third-party header not on include path**
+
+```csharp
+// In Build.cs:
+PublicSystemIncludePaths.Add(Path.Combine(ThirdPartyDir, "include"));
+```
+
+**Cause D: Missing header generated by UHT**
+
+If the included file is a `.generated.h`, you may need to regenerate project files. Run "Generate Project Files" from the .uproject or from the Unreal Editor.
+
+### C2039 — Member Not Found
+
+```
+error C2039: 'SomeMember': is not a member of 'FSomeClass'
+```
+
+Often caused by:
+- Stale generated header (`.generated.h`) — regenerate project files
+- Forward declaration without full include — add `#include "SomeClass.h"` in the .cpp
+- IWYU violation — the type was previously pulled in by a PCH header that's no longer included
+
+### C2027 / C2371 — Incomplete Type / Type Redefinition
+
+```
+error C2027: use of undefined type 'FSomeClass'
+error C2371: 'FSomeClass': redefinition; different basic types
+```
+
+**Cause**: Forward declaration used where full definition is needed, OR the same header included via two different paths (`SomeClass.h` vs `SubDir/SomeClass.h`).
+
+**Fix for incomplete type**: Replace forward declaration with full include in the .cpp:
+```cpp
+// Header — keep forward declaration for pointer/reference params
+class FSomeClass;
+class MYMODULE_API FMyClass
+{
+    void DoThing(FSomeClass* Param);
+};
+
+// CPP — include the full definition
+#include "SomeClass.h"
+void FMyClass::DoThing(FSomeClass* Param) { ... }
+```
+
+**Fix for redefinition**: Use consistent paths. Prefer includes from a module root:
+```cpp
+// Inconsistent — may cause ODR violations
+#include "SomeClass.h"           // resolved via PublicIncludePaths
+#include "SubDir/SomeClass.h"   // different resolved path, same file
+
+// Consistent — always use full path from module root
+#include "SubDir/SomeClass.h"
+```
+
+---
+
+## UHT Errors (Unreal Header Tool)
+
+### Missing #include for generated header
+
+```
+error: include 'MyClass.generated.h' must be the last include in the header
+```
+
+**Fix**: Move the `.generated.h` include to the very last line of your header's includes:
+```cpp
+#pragma once
+
+#include "CoreMinimal.h"
+#include "GameFramework/Actor.h"
+#include "MyClass.generated.h"   // MUST be last
+```
+
+### UCLASS / USTRUCT not found by UHT
+
+```
+error: Expected type name after 'class' keyword
+```
+
+Common causes:
+- The file is in the wrong directory (UHT only scans `Public/` and `Private/`)
+- The file is not listed in the project (ensure .uproject or .uplugin has the module)
+- `GENERATED_BODY()` or `GENERATED_USTRUCT_BODY()` is missing inside the class/struct
+
+### Missing MODULE_API on exported UCLASS
+
+UHT-generated reflection requires that classes with `UCLASS()` macro are exported if they're in a module:
+
+```cpp
+UCLASS()
+class MYMODULE_API UMyObject : public UObject
+{
+    GENERATED_BODY()
+    // ...
+};
+```
+
+Omitting `MYMODULE_API` here will compile but causes reflection failures when the class is referenced across module boundaries.
+
+---
+
+## IWYU Violations
+
+### Symptom: Builds in unity mode, fails with standalone compile
+
+With `bUseUnityBuild = true` (default), UBT combines multiple .cpp files. A violation is only caught when:
+- `bUseUnityBuild = false` (set in Target.cs for iteration)
+- `bEnforceIWYU = true` (set in Build.cs)
+- Building with `-singlefile` flag
+
+**Fix pattern**: For each compilation unit, include exactly what it uses:
+
+```cpp
+// MyActor.cpp
+#include "MyActor.h"              // own header first — always
+#include "Engine/World.h"         // uses GetWorld()
+#include "GameFramework/PlayerController.h"  // uses APlayerController
+// Do NOT include "CoreMinimal.h" and rely on it to pull in FString — include what you need
+```
+
+### Relying on Transitive Includes
+
+```cpp
+// ActorA.h includes Engine.h which includes World.h
+// Your file:
+#include "ActorA.h"
+// ... uses UWorld without including Engine/World.h
+
+// This breaks when ActorA.h changes its includes
+```
+
+**Fix**: Include every header you directly use.
+
+---
+
+## Module Not Found at Runtime
+
+### Symptom
+
+```
+LogModuleManager: Warning: ModuleNotFound: Could not find module 'MyModule'
+```
+
+or a crash at startup with module load failure.
+
+**Checklist**:
+1. Module is listed in `.uproject` or `.uplugin` `Modules` array
+2. `LoadingPhase` is appropriate — if you load the module via C++ at a specific time, the module must have loaded by then
+3. The module binary exists — rebuild the project
+4. If it's a plugin module, the plugin is enabled in `.uproject`'s `Plugins` array
+
+---
+
+## Circular Dependency
+
+### Symptom
+
+```
+Error: Circular dependency detected: ModuleA -> ModuleB -> ModuleA
+```
+
+UBT cannot build a static dependency graph that includes cycles.
+
+**Resolution strategies**:
+
+**Strategy 1: Extract a shared interface module**
+
+Before:
+- `ModuleA` depends on `ModuleB` (for `IServiceB`)
+- `ModuleB` depends on `ModuleA` (for `IServiceA`)
+
+After:
+- `ModuleInterfaces` defines both `IServiceA` and `IServiceB`
+- `ModuleA` depends on `ModuleInterfaces`
+- `ModuleB` depends on `ModuleInterfaces`
+
+**Strategy 2: Use DynamicallyLoadedModuleNames**
+
+```csharp
+// ModuleB.Build.cs — no compile-time dependency on ModuleA
+DynamicallyLoadedModuleNames.Add("ModuleA");
+```
+
+Then at runtime:
+```cpp
+IModuleA* ModuleA = FModuleManager::GetModulePtr<IModuleA>("ModuleA");
+if (ModuleA) { ModuleA->DoThing(); }
+```
+
+**Strategy 3: Forward declare and use pointers/references**
+
+Move full includes from headers to .cpp files and use forward declarations in the header.
+
+---
+
+## Hot Reload Failures
+
+### Symptom: Changes not reflected after recompile
+
+Hot Reload (Live Coding in UE5) has limitations:
+- New UPROPERTY fields on existing UClasses are not applied to existing instances
+- New UFUNCTIONs added to existing classes may not bind correctly
+- Changes to class hierarchy require a full restart
+
+**Fix**: For structural changes to UObject classes, always do a full restart rather than hot reload.
+
+### Symptom: Crash on hot reload
+
+```
+Assertion failed: Class->ClassDefaultObject ...
+```
+
+Caused by:
+- Adding/removing fields from USTRUCTs without restarting
+- Changing the memory layout of UObjects that already have instances
+
+**Fix**: Full rebuild and editor restart.
+
+---
+
+## Packaging / Cooking Errors
+
+### Missing module in cooked build
+
+```
+LogPackageName: Error: DoesPackageExist: DoesPackageExistFast FAILED: 'MyModule'
+```
+
+**Cause**: A module with `Type: "Editor"` or `Type: "Developer"` was referenced from runtime code.
+
+**Fix**:
+- In C++: guard editor-only code with `#if WITH_EDITOR`
+- In Build.cs: use `if (Target.bBuildEditor)` for editor-only dependencies
+- In .uproject: ensure the module type matches actual usage
+
+### Blueprint assets referencing stripped modules
+
+If Blueprint graphs reference C++ functions from editor-only modules, cooking strips the module and breaks the Blueprint.
+
+**Fix**: Move the referenced functions to a Runtime module, or use `CallInEditor = true` UFUNCTION specifier for functions that should only call from editor — ensuring they're never called from game code paths.
+
+---
+
+## Build Configuration Quick Reference
+
+| Error type | First thing to check |
+|---|---|
+| LNK2019 unresolved symbol | Missing dependency or missing `MODULENAME_API` |
+| C1083 cannot open include | Missing dependency or wrong include path |
+| IWYU violation | Missing direct include, relying on transitive pull |
+| UHT parse error | Missing `.generated.h` last, missing `GENERATED_BODY()` |
+| Module not found at runtime | Not listed in .uproject/.uplugin, or wrong LoadingPhase |
+| Circular dependency | Extract interface module or use dynamic loading |
+| Cooking failure | Editor-only code/module referenced from runtime path |
+| Hot reload crash | Structural UObject change — full restart required |

package/skills/ue-naming-conventions/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: ue-naming-conventions
+description: "Asset naming y estructura de Content — Prefix_BaseAssetName_Variant_Suffix, prefijos por tipo de asset, layout de carpetas, identifiers seguros"
+category: "gamedev"
+argument-hint: "[asset, folder o review]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+
+# UE Naming Conventions & Content Structure
+
+Names and folder layout are the cheapest consistency win in an Unreal project and the most expensive thing to fix later — renaming assets breaks references, and redirectors accumulate. Settle the convention once, record it in the project context, then hold the line.
+
+Ask before writing: this skill renames assets and moves folders, which rewrites references across the project. Never rename in bulk without approval, a clean source-control state, and a Fix Up Redirectors pass afterwards.
+
+## Context Check
+
+Read `docs/unreal/project-context.md` before proposing anything. Confirm:
+
+- **Whether the project already has a naming convention.** If it does, that convention wins — even where it disagrees with this skill. Consistency beats correctness here.
+- The top-level content folder name and whether `Developers/` is in use
+- Source control system, because a rename is a source-control operation before it is an editor one
+
+## The Prime Directive
+
+> An existing convention beats a better one. All structure, assets and code in the project should look like a single person created it, no matter how many people contributed.
+
+If the project has no convention yet, propose the one below, get it agreed, and write it into `docs/unreal/project-context.md` so every other `ue-*` skill follows it.
+
+## Base Asset Name
+
+Every asset follows `Prefix_BaseAssetName_Variant_Suffix`:
+
+- **`Prefix`/`Suffix`** — determined by asset type. See the reference table.
+- **`BaseAssetName`** — a short, recognizable name for the logical group. Every asset belonging to the character Bob uses `Bob`.
+- **`Variant`** — either a recognizable name (`Bob_Evil`, `Bob_Retro`) or a two-digit number starting at `01` for generic variations (`Rock_01`, `Rock_02`). Three digits means you should have split the base name instead. Variants can chain: `Flooring_Marble_01`.
+
+```
+SK_Bob            Skeletal mesh
+M_Bob             Material
+T_Bob_D           Diffuse texture
+T_Bob_N           Normal texture
+T_Bob_Evil_D      Diffuse for the Evil variant
+MI_Rock_Snow      Material instance variant
+```
+
+## Identifier Charset
+
+In **any** identifier — asset, folder, C++ symbol, path — restrict to `[A-Za-z0-9_]` and use `_` sparingly. Never use:
+
+- Whitespace of any kind
+- Backslashes, or symbols like `#!@$%`
+- Any Unicode character
+
+A character named `Zoë` gets a folder named `Zoe`. This is not pedantry: spaces and Unicode break batch tools, cooking, and source control in ways that surface as unexplained failures far from the cause. The same applies to the project's own path on disk — prefer `D:\Project` over a `My Documents` subfolder.
+
+## Content Directory Structure
+
+- **One top-level folder named after the project.** All project content lives in `Content/MyProject/`, never loose in `Content/`. This is what makes the project safely mergeable with marketplace and plugin content.
+- **`PascalCase` folder names, no spaces, no Unicode.**
+- **`Maps/`** — every level lives under `Content/MyProject/Maps`, subfolders welcome. Keeps cooking, lighting and QA scripts sane, and means "open this map" needs no directions.
+- **`Core/`** — the fundamental classes: base GameMode, GameState, PlayerController, PlayerState, Character. A visible "don't touch" boundary. Designers tweak child classes elsewhere.
+- **`MaterialLibrary/`** — master materials, layered materials, material functions and shared utility textures. Makes a "material instances only" policy enforceable: any plain material outside this folder is a violation you can grep for. Put debug materials in `MaterialLibrary/Debug` so they are trivial to strip and obvious if referenced.
+- **`Developers/`** — per-person sandbox, hidden in the Content Browser by default. Work here cannot be accidentally depended on. Promote an asset by moving it into the project folder and fixing up redirectors.
+- **No folders named `Assets` or `AssetTypes`** — everything is an asset, and grouping by type instead of purpose fights the Content Browser's own filters.
+- **No empty folders.** They clutter the browser and usually mean a redirector was never fixed up.
+
+> → Read references/content-structure.md for the example project layout, the very-large-asset-set exception, and the safe procedure for deleting a stubborn empty folder
+
+## Asset Prefixes
+
+> → Read references/asset-name-modifiers.md for the full prefix/suffix tables by asset type, including the UE5 types the original guide predates and the texture packing suffixes
+
+The ones worth memorizing:
+
+| Type | Prefix | Type | Prefix |
+|------|--------|------|--------|
+| Blueprint | `BP_` | Widget Blueprint | `WBP_` |
+| Blueprint Interface | `BPI_` | Animation Blueprint | `ABP_` |
+| Material | `M_` | Material Instance | `MI_` |
+| Static Mesh | `SM_` | Skeletal Mesh | `SK_` |
+| Texture | `T_` | Niagara System | `NS_` |
+| Data Asset | `DA_` | Data Table | `DT_` |
+| Input Action | `IA_` | Input Mapping Context | `IMC_` |
+| Behavior Tree | `BT_` | Blackboard | `BB_` |
+
+## Two Conflicts To Resolve Explicitly
+
+**Static Mesh: `SM_` or `S_`?** The Gamemakin guide specifies `S_` and notes that many teams use `SM_`. Epic's own tooling — including the asset prefixes its MCP server keys off — assumes `SM_`. This skill defaults to **`SM_`** for that reason. If the project already uses `S_`, keep `S_` and record it in the project context.
+
+**Structs and enums.** The guide uses `F`/`S` for structs and `E` for enums with no underscore, matching C++. For Blueprint-authored types many teams prefer `F_`/`E_` to keep them visually distinct from C++ types. Either is fine; pick one and record it.
+
+## Common Mistakes
+
+- **Renaming assets without a redirector pass**, leaving dangling references that only surface at cook time
+- **Bulk renames without source control clean**, making the change impossible to revert cleanly
+- **Content loose in `Content/`** rather than under a project folder, which collides with plugin and marketplace content
+- **Grouping by asset type** (`Content/Meshes`, `Content/Textures`) instead of by feature — the Content Browser already filters by type
+- **Spaces or Unicode** in a name, a folder, or the project path
+- **Plain materials outside `MaterialLibrary/`**, quietly defeating a material-instance policy
+- **Levels scattered outside `Maps/`**, making cook and lighting scripts fragile
+- **Treating a UE4-era prefix list as current** — Cascade `PS_` is Niagara `NS_`/`NE_` now, Matinee is Sequencer, Destructible Mesh is Chaos
+
+---
+
+## Related Skills
+
+- `/ue-project-context` — the document that records which convention this project actually uses
+- `/ue-data-assets-tables` — `DA_`/`DT_` assets and the Asset Manager paths that depend on stable names
+- `/ue-materials-rendering` — the `MaterialLibrary/` policy and `M_`/`MI_` split
+- `/ue-blueprints` — Blueprint variable and function naming inside the graph
+- `/ue-world-level-streaming` — `Maps/` layout, persistent level `_P` suffix, data layers
+- `/asset-audit` — cross-engine audit for naming, size, format and orphaned assets
+
+## Reference Files
+
+- `references/asset-name-modifiers.md` — full prefix/suffix tables by asset type, plus UE5 additions and texture packing
+- `references/content-structure.md` — example project layout, folder rules in depth, empty-folder removal procedure
+
+---
+
+## Checklist
+
+Validate before considering the work done:
+
+- [ ] The project's existing convention was checked first and takes precedence
+- [ ] Every new asset follows `Prefix_BaseAssetName_Variant_Suffix` with the right prefix for its type
+- [ ] No identifier, folder or path contains spaces, Unicode or symbols outside `[A-Za-z0-9_]`
+- [ ] Project content sits under a single top-level project folder, with levels under `Maps/`
+- [ ] Any rename ran with clean source control and a Fix Up Redirectors pass afterwards
+- [ ] The agreed convention is written into `docs/unreal/project-context.md`
+- [ ] Conventions in `docs/unreal/project-context.md` were read and followed
+- [ ] The Common Mistakes section of this skill was reviewed against the change
+
+**PASS** — every item holds. **CONCERNS** — the work stands but at least one item is unresolved and worth flagging to the user. **FAIL** — an item is violated in a way that breaks asset references or leaves the project inconsistent; fix it before handing the work over.
+
+## Next Steps
+
+- `/ue-project-context` — record the convention so the rest of the `ue-*` skills follow it
+- `/asset-audit` — sweep the existing project for violations
+- `/code-review` — architectural and quality review of the change
+- `/commit` — conventional commit once the change is verified