# Unified Unreal Engine C++ Coding Standards

## Core Principles (The Unreal Way)

### Type System & Memory Management
- **ALWAYS** use Unreal types: FString, FName, FText, TArray, TMap, TSet (never STL containers with UObjects!)
- Use Unreal's smart pointers: TSharedPtr, TUniquePtr, TWeakPtr (not std:: variants)
- UObjects are garbage collected - use UPROPERTY() to keep them alive
- Use NewObject<T>() for UObject creation, MakeShareable() for shared pointers
- Use Cast<T>() or CastChecked<T>() for type casting (never C-style casts)
- TSoftObjectPtr for asset references, TWeakObjectPtr for weak UObject references

### Naming & Code Organization
- Follow Unreal prefixes strictly: U for UObject classes, A for Actors, F for structs, I for interfaces, E for enums
- PascalCase for types, camelCase for variables and functions
- Use forward declarations in headers to reduce compile times
- One class per file, matching filename to class name
- Keep headers minimal - implementation details in .cpp files

### Blueprint Integration (Grug say: "Blueprint friend make game ship!")
- Apply UCLASS(), UPROPERTY(), UFUNCTION() generously for Blueprint access
- Use BlueprintCallable for functions Blueprints should call
- Use BlueprintImplementableEvent for Blueprint-only implementations
- Use BlueprintNativeEvent for C++ implementations with Blueprint overrides
- Document all exposed properties with tooltips
- Test your C++ in Blueprint before calling it done

### Core Unreal Patterns
- Prefer actor-component architecture (composition over inheritance)
- Use Gameplay Tags (FGameplayTag) instead of strings or enums for categorization
- Leverage delegates (DECLARE_DELEGATE) and events for loose coupling
- Use Subsystems for manager classes (not singletons or globals)
- Data-driven design with DataAssets and DataTables
- Use Gameplay Ability System for complex ability mechanics (when appropriate)

### Performance & Optimization (Grug wisdom: "Fast code that no ship worse than slow code that ship")
- Profile first with Unreal Insights and stat commands
- Use SCOPE_CYCLE_COUNTER for timing critical sections
- Prefer events and timers over Tick() when possible
- Use object pooling for frequently spawned actors
- Async load assets with TSoftObjectPtr
- Cache component and actor references when used frequently
- Early out of functions when possible

### Debugging & Safety
- Use UE_LOG with descriptive categories (not just LogTemp)
- Apply check() for programmer errors, ensure() for runtime validation
- Test in Shipping builds regularly (editor lies about performance!)
- Use source control integration - small, frequent commits
- Comment the "why", not the "what"
- Write defensive code - validate inputs, especially from Blueprint

### Modern C++ with Unreal Constraints
- Use auto when type is obvious (but not for UObject pointers)
- Range-based for loops with Unreal containers
- Move semantics for non-UObject types
- constexpr where beneficial (Unreal has some limitations)
- Use nullptr (never NULL or 0)
- UENUM with enum class for type safety
- Apply const-correctness (but remember const UObject* can still modify the object)

### Localization & UI
- **NEVER** hardcode display text - use FText with LOCTEXT/NSLOCTEXT
- FString for mutable gameplay strings, FName for immutable identifiers
- Use Slate for editor tools, UMG for game UI
- Respect the game thread for all UI operations

### Platform & Build Considerations
- Use WITH_EDITOR for editor-only code
- Use WITH_EDITORONLY_DATA for editor-only data
- Platform-specific code in platform abstraction layers
- Test packaged builds on target platforms
- Consider console memory limitations
- Hot reload works... sometimes (grug say: "when in doubt, close editor and rebuild")

### Additional Grug Wisdom
- If it works in PIE but not in packaged build, you forgot something
- The engine source code is the best documentation
- Simple code is debuggable code
- Your game needs to ship - perfect code that never ships helps nobody
- When Unreal way seems weird, remember: Unreal way keeps game shipping
- Don't fight the engine - work with it
- Comment your hacky workarounds so future you knows why

## Forbidden Practices (Grug Say: "These Make Unreal Angry!")

### Memory & Type System Violations
- **NEVER** use std::vector, std::map, etc. with UObjects (instant crash in packaged builds!)
- **NEVER** use raw new/delete - NewObject<T>() for UObjects, MakeShareable for others
- **NEVER** hold raw pointers to UObjects without UPROPERTY() (garbage collector will eat them)
- **NEVER** use static_cast with UObjects (use Cast<T>() or your game will crash)
- **NEVER** bypass serialization - let the reflection system handle it
- **NEVER** create circular hard references between UObjects (use TWeakObjectPtr)
- **NEVER** mix engine types with STL types in serialized properties

### Blueprint & Integration Sins
- Don't make Blueprint-hostile APIs (no raw pointers in UFUNCTION)
- Don't use multiple inheritance with UObjects (I prefix interfaces exist for a reason)
- Don't ignore const-correctness in exposed functions
- Don't expose complex templates to Blueprint
- Don't forget BlueprintCallable on functions Blueprints need

### Performance Crimes
- Don't use Tick() for everything (timers and delegates exist)
- Don't block the game thread (your framerate will die)
- Don't ignore the difference between Development and Shipping builds
- Don't load all assets at once (use async loading)
- Don't spawn/destroy actors every frame (pool them)
- Don't ignore profiler results because "it works on my machine"

### Build & Platform Taboos
- Don't hardcode paths (use FPaths and content browser references)
- Don't ignore cooking errors (they will haunt you at 3am before ship)
- Don't assume your code works the same in PIE and packaged
- Don't ignore platform memory limits ("it works on PC" isn't enough)
- Don't skip testing on min spec hardware
- Don't forget WITH_EDITOR guards (or your shipping build won't compile)

### Code Quality Disasters
- Don't write "clever" code (grug say: "clever code is debugging nightmare")
- Don't ignore compiler warnings (they're trying to save you)
- Don't copy-paste code everywhere (make a function, grug beg you)
- Don't use magic numbers (UPROPERTY with EditAnywhere is your friend)
- Don't comment out code "just in case" (source control remembers everything)
- Don't fight Unreal's patterns (the engine always wins)

### The Ultimate Sins (Grug's Sacred Laws)
- Don't assume hot reload always works (it doesn't, restart the editor)
- Don't trust PIE performance (shipping builds tell the truth)
- Don't ignore artists and designers (they use your code more than you do)
- Don't overcomplicate simple problems (shipped is better than perfect)
- Don't forget to test your Blueprint exposed functions IN Blueprint
- Don't code like you're writing a C++ textbook (this is game development)
- Don't ignore the engine source (it has all the answers)
- Don't forget: if Unreal Sensei cannot understand your code, dojo burns down!

---
## The Final Wisdom

**Grug's Ultimate Truth:** "Unreal way seem strange sometimes. But Unreal way make game ship. STL way make game crash. Choose wisely."

**Remember:** When in doubt, look at how Epic does it in the engine source. They've shipped more games than most of us ever will. The Unreal Way is the way of shipped games, happy teams, and sleeping peacefully at night knowing your packaged builds work.

*Now go forth and code, but always remember: The Unreal Sensei is watching, and the dojo's structural integrity depends on your adherence to these sacred standards.*