CLAUDE.md for Unreal

# CLAUDE.md

Project memory for Claude Code in this Unreal repository. Read it before editing. Other agents can follow the same rules.

## Stack

This repository is an Unreal Engine project using C++. UObject memory is owned by the engine. Gameplay stays out of constructors that run before the world exists.

## Layout

- Runtime code lives in the game module. Editor-only code lives in an editor module.
- Generated headers stay included last, the way the module already does.
- Blueprints are data. Do not hard-code tuning that a designer already edits.

## Commands

- Build: `Build the editor target for this project`
- Tests: `Run the Unreal automation tests for the module you changed`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Mark reflected fields with UPROPERTY and the specifiers the class already uses.
- Do not `new` a UObject. Use `NewObject`, `CreateDefaultSubobject`, or `SpawnActor`.
- Do not tick a component that only needs to react to an event.
- Keep gameplay off the garbage-collected raw pointer across a frame without a UPROPERTY or TWeakObjectPtr.
- Name types with the project's prefix if it has one.
- Hot-reload limitations are real. A header change may need a full rebuild.

## Testing

Add or update tests when behavior changes.

Add an Unreal automation test when the rule is pure C++. Otherwise say which PIE case you ran.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Use `ensure` or a logged early return for a missing asset. Do not check() on data a content change can break.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not call into UObjects from a worker thread.
- Do not store a raw UObject pointer in a non-reflected struct and expect it to stay alive.
- Do not edit generated files under Intermediate.
- Do not commit Binaries, DerivedDataCache, or Saved unless the project already vendors a specific binary.

## Done when

- The requested behavior works.
- The editor target compiles and the automation test or PIE session for the change was run.
- The diff stays inside the task.
- You list anything you could not run.