# Unreal Engine — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "Unreal Engine Knowledge Base — Index" type: index updated: 2026-07-17 unreal_version: "5.8" --- # Unreal Engine — Knowledge Base The developer core of Unreal Engine 5.8 for engineers and agents building UE projects: programming with C++ and the reflection system, Blueprints visual scripting, the gameplay framework, AI, input and physics, the rendering feature set (Lumen, Nanite, materials, lighting), and the content/asset pipeline. Scope is the developer surface — not art tutorials, marketplace content, or the full C++/Blueprint API reference. Master catalog — every page appears here. ## Concepts ### Editor & project basics - [[concepts/unreal-editor-and-projects]] — the editor, project & directory structure, plugins - [[concepts/unreal-terminology-and-conventions]] — core terms, units (1 uu = 1 cm), coordinate system ### Programming - [[concepts/programming-with-cpp]] — the gameplay class hierarchy, modules, live coding - [[concepts/unreal-reflection-system]] — UCLASS/UPROPERTY/UFUNCTION macros & metadata specifiers - [[concepts/actors-and-components]] — AActor lifecycle, components, attachment, spawning - [[concepts/blueprints-visual-scripting]] — the Blueprint editor, graphs, variables, flow control - [[concepts/blueprint-communication]] — interfaces, event dispatchers, function libraries ### Gameplay - [[concepts/gameplay-framework]] — GameMode/GameState, Controller, Pawn, PlayerState, GameInstance - [[concepts/input-system]] — input mappings and the player controller's role - [[concepts/physics-and-collision]] — collision queries, traces, Chaos physics - [[concepts/ai-behavior-trees]] — Behavior Trees, EQS, StateTree, AI debugging - [[concepts/cameras-and-ui]] — cameras, view targets, UMG/HUD ### Rendering - [[concepts/lumen-global-illumination]] — dynamic global illumination & reflections - [[concepts/nanite-virtualized-geometry]] — virtualized micropolygon geometry - [[concepts/materials-and-substrate]] — the material graph, PBR inputs, Substrate - [[concepts/lighting-and-shadows]] — lighting, Virtual Shadow Maps, the Path Tracer ### Content - [[concepts/content-import-pipeline]] — Interchange, FBX/glTF/USD/Alembic/Datasmith - [[concepts/meshes-and-modeling]] — static & skeletal meshes, Modeling Mode, geometry scripting ## Entities - [[entities/unreal-engine]] — the engine as a platform - [[entities/unreal-editor]] — the editor application ## Syntheses - [[syntheses/blueprints-vs-cpp]] — Blueprints vs C++: which to use - [[syntheses/rendering-feature-map]] — Lumen vs Nanite vs Path Tracer vs Substrate - [[syntheses/choosing-gameplay-systems]] — GameMode/Pawn/Controller & AI system choices ## XL edition (Pro) Deeper per-item reference is available to Pro subscribers under this wiki's XL edition (not listed above): the full UPROPERTY/UFUNCTION/UCLASS reflection specifier tables, the C++ core types (FString/FName/FText, UObject & memory), the module/build system (.Build.cs, UHT, CLI args), Enhanced Input, gameplay tags & GAS, data assets/tables/registries, asset management, and networking & replication — 17 pages. Subscribe at /pro. ## Statistics - **Total pages**: 23 - **Concepts**: 18 - **Entities**: 2 - **Summaries**: 0 - **Syntheses**: 3 --- title: "Actors & Components" type: concept tags: [actor, component, scenecomponent, attachment, tick] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/cpp/components-in-unreal-engine.md", "raw/cpp/gameplay-classes-in-unreal-engine.md"] confidence: high --- # Actors & Components ## Definition An **Actor** (`AActor`) is a spawnable gameplay object that can be placed or spawned directly into the world. **Components** are a special type of Object that Actors attach to themselves as sub-objects. Components are useful for sharing common behaviors — displaying a visual representation, playing sounds, or project-specific concepts such as how a vehicle interprets input and changes its velocity and orientation. Because Components are the only way to render meshes and images, implement collision, and play audio, everything the player sees or interacts with in the world is ultimately the work of some type of Component. ## How It Works Components come in a layered hierarchy, each level adding capability: - **Actor Components** (class `UActorComponent`) are the base class for all Components. They are most useful for abstract behaviors such as movement, inventory or attribute management, and other non-physical concepts. Actor Components do not have a transform — no physical location or rotation in the world. - **Scene Components** (class `USceneComponent`, a child of `UActorComponent`) support location-based behaviors that do not require a geometric representation, such as spring arms, cameras, physical forces and constraints, and audio. Their position is defined by a `transform` (class `FTransform`) containing location, rotation, and scale. - **Primitive Components** (class `UPrimitiveComponent`, a child of `USceneComponent`) are Scene Components with geometric representation, used to render visual elements or to collide/overlap with physical objects — static or skeletal meshes, sprites or billboards, particle systems, and box/capsule/sphere collision volumes. Each primitive's render data is held by a Scene Proxy (class `FPrimitiveSceneProxy`) that the engine uses to render the Component in parallel to the game thread. **Lifecycle (registration and ticking).** For Actor Components to update each frame and affect the scene, the engine must **register** them. This happens automatically for Components created as sub-objects of an Actor during that Actor's spawning process; the `RegisterComponent` function provides manual registration for Components created during play (with the requirement that the Component is associated with an Actor). Registration runs `OnRegister`, `CreateRenderState`, and `OnCreatePhysicsState`; unregistering with `UnregisterComponent` runs `OnUnregister`, `DestroyRenderState`, and `OnDestroyPhysicsState`. Actor Components can update each frame in a manner similar to Actors via the `TickComponent` function. By default, Actor Components do **not** update. To make one tick, set `PrimaryComponentTick.bCanEverTick` to `true` in its constructor, then call `PrimaryComponentTick.SetTickFunctionEnable(true)` to turn updates on; `PrimaryComponentTick.SetTickFunctionEnable(false)` deactivates ticking. Leaving `bCanEverTick` at its default `false` gives a slight performance boost. (This per-frame Tick is the component-level counterpart of the Actor's own BeginPlay / Tick / EndPlay lifecycle, which the [[concepts/gameplay-framework]] page covers.) **Render and physics state.** To render, an Actor Component must create a render state; call `MarkRenderStateDirty` when render data changes. Scene Components (including Primitive Components) create render states by default, while Actor Components do not. To interact with physics, a Component needs a physics state; by default Actor Components and Scene Components do not have physics states, but Primitive Components do. Override `ShouldCreatePhysicsState` to decide whether instances of your Component class need one. **Attachment.** Only Scene Components (`USceneComponent` and its child classes) can attach to one another, because transforms are required to describe the child/parent spatial relationship. A Scene Component can have any number of children but only one parent; attachment cycles are not supported. An Actor can designate a single Scene Component as its **root**, so the Actor's world location, rotation, and scale are drawn from that Component. The two primary attachment methods are `SetupAttachment` (useful in constructors and for Components not yet registered) and `AttachToComponent` (attaches immediately, useful during play). ## Key Parameters - **Spawning Actors and creating subobjects.** Component subobjects are created and attached to the Actor's hierarchy inside the constructor. When spawning an Actor, its components are cloned from the Class Default Object (CDO). Use `CreateDefaultSubobject(TEXT("Name"))` to create a component, then set it as `RootComponent` or attach it to the existing root. A pointer to every component created in the constructor should be stored in a `UPROPERTY` of the owning class so components are always created, destroyed, and properly garbage-collected. Actors are created at runtime with `SpawnActor`. - **Common Primitive Components** — Box Component, Capsule Component, Static Mesh Component, and Skeletal Mesh Component are the most common. Box and Capsule Components generate invisible geometry for collision detection; Static Mesh and Skeletal Mesh Components contain pre-built geometry that is rendered and can also be used for collision. `USkeletalMeshComponent` uses its `TickComponent` to update animations and skeletal controllers; `UParticleSystemComponent` updates its emitters and handles particle events. - **Hierarchy queries** — `GetAttachParent`, `GetParentComponents`, `GetNumChildrenComponents`, `GetChildrenComponents`, and `GetChildComponent` are available on any `USceneComponent`, including the root. - **Visualization Components** — ordinary Components that exist only in the Editor. Create a regular Component and call `SetIsVisualizationComponent` on it; guard all references with `WITH_EDITORONLY_DATA` or `WITH_EDITOR` preprocessor checks so packaged builds are unaffected. For example, the Camera Component uses a Draw Frustum Component to show its view frustum in-Editor. ## When To Use Use an Actor for anything that lives in the world as a spawnable entity, and split its capabilities into Components so behaviors can be shared and swapped. Choose a `UActorComponent` for non-spatial logic (inventory, attributes), a `USceneComponent` for something that needs a transform but no geometry (a spring arm or camera mount), and a `UPrimitiveComponent` subclass when you need rendered geometry or collision. These types are created and exposed through the [[concepts/unreal-reflection-system]] and used from both C++ and [[concepts/blueprints-visual-scripting|Blueprints]]. ## Risks & Pitfalls - Registering a Component during play can impact performance; do it only when necessary. - Only Scene Components can be attached — Actor Components have no transform and cannot participate in attachment. - For physics, simply returning `true` from `ShouldCreatePhysicsState` is not advised; consult the `UPrimitiveComponent` version for situations (such as during destruction) where you should not create a physics state, and consider returning `Super::ShouldCreatePhysicsState`. - Component pointers not stored in a `UPROPERTY` risk incorrect creation/destruction and garbage collection. ## Related Concepts - [[concepts/programming-with-cpp]] - [[concepts/unreal-reflection-system]] - [[concepts/gameplay-framework]] - [[concepts/blueprints-visual-scripting]] ## Sources - raw/cpp/components-in-unreal-engine.md - raw/cpp/gameplay-classes-in-unreal-engine.md --- title: "AI: Behavior Trees, EQS & StateTree" type: concept tags: [ai, behavior-trees, eqs, statetree, ai-controller] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/gameplay/behavior-trees-in-unreal-engine.md", "raw/gameplay/environment-query-system-in-unreal-engine.md", "raw/gameplay/state-tree-in-unreal-engine.md", "raw/gameplay/ai-debugging-in-unreal-engine.md", "raw/gameplay/controllers-in-unreal-engine.md"] confidence: high --- # AI: Behavior Trees, EQS & StateTree ## Definition Unreal Engine drives non-player-character (NPC) artificial intelligence through three cooperating systems. A **Behavior Tree** asset executes branches of logic to decide what an AI does, reading state from a companion **Blackboard** asset that acts as the tree's "brain." The **Environment Query System (EQS)** gathers data about the world so the AI can pick the best location or Actor to act on. **StateTree** is a newer general-purpose hierarchical state machine that blends behavior-tree selection with classic states and transitions. All of these run on a Pawn possessed by an **AIController**, and can be inspected live with the built-in AI Debugging tools. ## How It Works **Behavior Trees.** The Behavior Tree asset executes branches containing logic to determine which branches should run. It does not hold state itself; it relies on the **Blackboard**, which contains several user-defined **Keys** that hold the information the tree references to make decisions. A Boolean Key such as `Is Light On` can steer the tree down one branch when true and another when false. Behavior Trees scale from trivial (a roach that flees or wanders) to a full simulated multiplayer opponent that finds cover, shoots, and collects pickups. The currently running node of the tree is a **Task**; the debugger surfaces the "currently ticking Task of the assigned Behavior Tree." **Environment Query System (EQS).** EQS is a feature within the AI system used to collect data from the environment. An **EQS Query** asks questions through a variety of **Tests** and returns the **Item** that best fits the question. Queries are primarily built from **Generators** (which produce the locations or Actors that will be tested and weighted) and **Contexts** (a frame of reference for Tests and Generators). A Query is typically called from a Behavior Tree, letting the AI find, for example, the best position with line of sight to the player, the nearest health or ammo pickup, or the closest cover point. Each candidate is weighted with a numerical value, and the highest-weighted result is the "winner" the AI moves to. **StateTree.** StateTree is a general-purpose hierarchical state machine that combines the **Selectors** from behavior trees with the **States** and **Transitions** from state machines. The goal is highly performant logic that stays flexible and organized — an alternative structuring of AI (or general) logic alongside Behavior Trees. **AIControllers.** Controllers are non-physical Actors that possess a Pawn (or a Pawn-derived class like Character) to control its actions. A **PlayerController** serves human players; an **AIController** implements the AI for the Pawns it controls. Control is taken with the **Possess** function and released with the **Unpossess** function. By default there is a one-to-one relationship between Controllers and Pawns. To use the AI Debugging tools you need a Pawn with an AIController in the Level that is running a Behavior Tree or has an AI Perception component. ## Key Parameters - **Blackboard Keys** — user-defined keys (e.g. a Boolean `Is Light On`) that the Behavior Tree reads; live values are shown in the Blackboard debug panel. - **EQS building blocks** — **Generators**, **Contexts**, **Tests**, and the returned **Item**; a **Simple Grid** is one Generator that produces grid points. - **StateTree building blocks** — **Selectors**, **States**, **Transitions**. - **AIController functions** — **Possess** / **Unpossess**. - **AI Debugging keys** — `' (apostrophe)` enables/closes the tools; **Numpad 0** = Nav Mesh, **Numpad 1** = general AI, **Numpad 2** = Behavior Tree, **Numpad 3** = EQS, **Numpad 4** = AI Perception. `Ctrl + ` (backtick) toggles the HUD class display, `Ctrl + Tab` toggles Debug Messages, and `/` (divide) shows the detailed EQS Test result table. Numpad values can be extended 0–9 per project. - **Nav Mesh** — `show Navigation true` / `show Navigation false` toggles the Nav Mesh at runtime; the navigable area comes from a **Nav Mesh Bounds Volume**. - **AI Perception** — **Senses** are defined under **Senses Config** on the AI Perception Component (e.g. Sight in green, Hearing in yellow); the **Debug Color** property sets a sense's debug color, and sighted stimuli mark a **Last Known Location**. ## When To Use Use a **Behavior Tree + Blackboard** for most reactive NPC decision-making where you want visual, branch-based logic driven by shared state. Add an **EQS Query** whenever the AI must reason spatially about the environment — choosing an attack position, cover, or the nearest pickup — and call it from the tree. Reach for **StateTree** when you want a hierarchical state machine that stays performant and organized, combining selection with explicit states and transitions. Always pair these with an **AIController** possessing the Pawn. ## Risks & Pitfalls - The Behavior Tree holds no memory of its own — if the AI misbehaves, inspect the **Blackboard keys** (Numpad 2 shows the tree on the left and the Blackboard on the right) to see why a branch did or did not run. - The AI Debugging tools require a Pawn with an **AIController** actually running a Behavior Tree or carrying an AI Perception component; without that, there is nothing to display. - EQS Test weighting matters: only the highest-weighted candidate wins, so poorly designed Tests or Generators can send the AI to the wrong location. Debug with Numpad 3, the `/` result table, or the **EQS Testing Pawn** / **Visual Logger** (which lets you inspect queries while the game is not running). - Default Controller-to-Pawn is one-to-one; games needing one controller over many units (e.g. RTS) must adjust this themselves. ## Related Concepts - [[concepts/gameplay-framework]] — where Pawns, Controllers, and the game loop live. - [[concepts/input-system]] — how PlayerControllers receive human input. - [[concepts/actors-and-components]] — AI Perception and camera components are Actor components. - [[concepts/cameras-and-ui]] — the AI debugger can overlay the active HUD class. ## Sources - raw/gameplay/behavior-trees-in-unreal-engine.md - raw/gameplay/environment-query-system-in-unreal-engine.md - raw/gameplay/state-tree-in-unreal-engine.md - raw/gameplay/ai-debugging-in-unreal-engine.md - raw/gameplay/controllers-in-unreal-engine.md --- title: "Blueprint Communication" type: concept tags: [blueprints, communication, interfaces, event-dispatchers, casting] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/blueprints/blueprint-interface-in-unreal-engine.md", "raw/blueprints/event-dispatchers-in-unreal-engine.md", "raw/blueprints/blueprint-function-libraries-in-unreal-engine.md", "raw/blueprints/functions-in-unreal-engine.md", "raw/blueprints/construction-script-in-unreal-engine.md"] confidence: high --- # Blueprint Communication ## Definition Blueprint Communication is the set of techniques a Blueprint uses to send data to, and trigger behavior in, other Blueprints. Unreal Engine offers several mechanisms — direct calls through a reference (often via casting), Blueprint Interfaces, Event Dispatchers, and shared Blueprint Function Libraries — each suited to a different coupling and direction of communication. Choosing among them is largely a question of how much the caller needs to know about the receiver's type. ## How It Works **Direct communication (casting).** You can call a Function in one Blueprint from inside another as long as you have a reference to the Blueprint that contains it. A common pattern is to obtain a reference and cast it to the target class: for example, dragging off the `Other` pin of an `Event Hit` and `Casting To` the `MyCharacter` Blueprint yields a typed reference, and dragging off the resulting `As My Character` pin lets you call a Function such as `Take Damage` that lives in that Blueprint. This is the most direct method but requires the caller to know the concrete target type. **Blueprint Interfaces.** A Blueprint Interface is a collection of one or more functions — name only, no implementation — that can be added to other Blueprints. Any Blueprint that has the Interface added is guaranteed to have those functions, and each implementing Blueprint can give them its own functionality. This mirrors the general-programming concept of an interface: multiple different types of Objects can all share and be accessed through a common interface. The classic example is a car and a tree — completely different types — that both implement a Blueprint Interface containing an `OnTakeWeaponFire` function, so weapon-fire logic can treat them as the same type and simply call `OnTakeWeaponFire` on whichever is hit. **Event Dispatchers.** By binding one or more events to an Event Dispatcher, you cause all of those events to fire once the Event Dispatcher is called. Events can be bound within a Blueprint Class, and Event Dispatchers also allow events to be fired within the Level Blueprint. Adding inputs to an Event Dispatcher lets you send variables to each bound event, enabling data flow both within a Blueprint Class and between a Blueprint Class and the Level Blueprint. The bind, unbind, and assign methods add events to the dispatcher's event list, while the call method activates all events stored in that list. **Blueprint Function Libraries.** These are a collection of static functions that provide utility functionality not tied to a particular gameplay object. They are typically stateless and reused across a variety of gameplay code, and can be grouped into logical sets (e.g. AI Blueprint Library) or provide broad utility (e.g. System Blueprint Library). In C++, a library inherits from `UBlueprintFunctionLibrary` and should contain only static methods, decorating the ones callable from Blueprints with `UFUNCTION()`. **Construction Script's role.** Communication that must run when an instance is created belongs in the Construction Script, which runs following the Components list when an instance of a Blueprint Class is created. It can perform initialization such as traces into the world and setting meshes and materials. Only Blueprint Classes contain Construction Scripts; Level Blueprints do not. ## Key Parameters - **Interface limitations.** Blueprint Interfaces cannot: add new variables, edit graphs, or add Components. Interface functions have no implementation — they exist only as a definition of typed inputs and outputs — and can be overridden within any Blueprint that implements the Interface. Use the `Replicates` checkbox (under `Class Settings` in the Details tab) for Interfaces whose functions need to replicate across the server. - **Event Dispatcher `Target` pin.** Every node except the Event node has a `Target` input pin. In the Blueprint Class it is automatically set to `Self`, so the event list changes for the class and thus every instance. In the Level Blueprint it must be connected to a reference to a specific instance in the level, so only that instance's event list changes. - **Function Library declaration.** Requires the standard `UCLASS()` and `GENERATED_UCLASS_BODY()` macros; individual functions are marked `BlueprintCallable` or `BlueprintPure` depending on whether the call has side effects. Rolling multiple Blueprint nodes into a single C++ library node yields better performance when called often. ## When To Use - **Direct / casting** — when the caller has, or can obtain, a reference and knows the target's concrete type; simplest for one-to-one, type-specific calls. - **Blueprint Interface** — when disparate object types must share a common method (a car and a tree both taking weapon fire) and you want to call it without knowing each concrete type. - **Event Dispatcher** — for one-to-many, event-driven notification, especially communicating from a Blueprint Class out to the Level Blueprint, or letting many listeners react when one thing happens. - **Blueprint Function Library** — for stateless utility functions reused across gameplay code that should not be tied to any single object type. ## Risks & Pitfalls - Casting couples the caller to a specific class; if the reference is not actually that type the cast fails, so it is the least flexible option for mixed types. - Blueprint Interfaces trade implementation for flexibility: because you cannot add variables, graphs, or components to them, they carry only function signatures — shared state must live elsewhere. - An Event Dispatcher's graph is locked; double-clicking its entry opens it but you cannot modify the dispatcher directly. In the Level Blueprint, forgetting to wire the `Target` pin to a specific instance changes nothing meaningful. - Function Libraries should contain only static methods and must not hold per-instance state, since they are not tied to a gameplay object. ## Related Concepts - [[concepts/blueprints-visual-scripting]] - [[concepts/programming-with-cpp]] - [[syntheses/blueprints-vs-cpp]] ## Sources - raw/blueprints/blueprint-interface-in-unreal-engine.md - raw/blueprints/event-dispatchers-in-unreal-engine.md - raw/blueprints/blueprint-function-libraries-in-unreal-engine.md - raw/blueprints/functions-in-unreal-engine.md - raw/blueprints/construction-script-in-unreal-engine.md --- title: "Blueprints Visual Scripting" type: concept tags: [blueprints, scripting, functions, flow-control, gameplay] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/blueprints/blueprints-visual-scripting-in-unreal-engine.md", "raw/blueprints/functions-in-unreal-engine.md", "raw/blueprints/flow-control-in-unreal-engine.md", "raw/blueprints/construction-script-in-unreal-engine.md"] confidence: high --- # Blueprints Visual Scripting ## Definition The Blueprint Visual Scripting system in Unreal Engine is a complete gameplay scripting system based on the concept of using a node-based interface to create gameplay elements from within Unreal Editor. As with many common scripting languages, it is used to define object-oriented (OO) classes or objects in the engine. It is designed so designers can use virtually the full range of concepts and tools generally only available to programmers, while Blueprint-specific markup in Unreal Engine's C++ implementation lets programmers create baseline systems that designers can then extend. ## How It Works Blueprints are authored in the Blueprint Editor, which hosts one or more node graphs. Nodes are connected by two kinds of wires. **Execution pins** carry an execution pulse that determines *when* logic runs, threading through nodes in order; **data pins** carry typed values (the *what*) that feed into a node's inputs and out of its outputs. A node fires when a pulse reaches its execution input, then pushes a pulse out of its execution output to the next node. A Blueprint Class typically contains an **EventGraph** where gameplay logic is wired to events (such as an event that fires every tick), plus a **Construction Script**. The Construction Script runs following the Components list when an instance of a Blueprint Class is created, executing a node graph so the instance can perform initialization operations — traces into the world, setting meshes and materials, and other context-specific setup. Only Blueprint Classes contain Construction Scripts; Level Blueprints do not have them. The entry point into the graph is a `ConstructionScript` node that is always present. **Variables** hold the Blueprint's state. They are created in the My Blueprint tab, given a type, and can be marked public with a default value; for example, a public vector variable with `Show 3D Widget` set to True exposes a draggable 3D widget in the viewport so its value can be edited by moving it. **Functions** are node graphs belonging to a particular Blueprint that can be executed, or called, from another graph. A Function has a single entry point — a node named after the Function with a single exec output pin — and you define behavior by wiring a node network between its entry and result nodes. Functions are created from the My Blueprint tab and open in their own tab in the Graph Editor. Compared with **Blueprint Macros**, a key difference is that you can only add *data* inputs and outputs to Functions. ## Key Parameters - **Access Specifier** (Details panel): `Public` (any other object can call this Function — the default), `Protected` (callable only by the current Blueprint and Blueprints that derive from it), and `Private` (callable only from within the current Blueprint). - **Pure vs. Impure Functions.** Pure Functions promise not to modify state or class members and are typically getters or operators that output a data value; they wire to Data Pins and are automatically executed by the compiler when their data is required — meaning a Pure Function is called once for each node it connects to. Impure Functions are free to modify state and must be explicitly executed by connecting exec wires. In code these use the `BlueprintPure` and `BlueprintCallable` keywords in the `UFUNCTION` declaration; in the editor they map to the `Pure` checkbox (checked = Pure, unchecked = Impure). - **Flow control nodes** govern execution order in a graph: - **Branch** — routes execution to `True` or `False` based on a boolean `Condition`. - **Sequence** — a single pulse triggers each `Out` output in order, without delay; add outputs with `Add pin`. - **ForLoop** / **ForLoopWithBreak** — fire a pulse for each index between `First Index` and `Last Index`, exposing `Loop Body`, `Index`, and `Completed`; the WithBreak variant adds a `Break` execution input. - **WhileLoop** — repeats `Loop Body` while its `Condition` remains true, then fires `Completed`. - **Gate** — `Enter` pulses pass to `Exit` only while open; `Open`, `Close`, and `Toggle` set state, and `Start Closed` sets the initial state. - **DoOnce** / **DoN** — fire once (or N times) then stop until `Reset`; DoOnce is a DoN where N = 1. - **FlipFlop** — alternates between outputs `A` and `B` on successive calls, with an `Is A` boolean. - **MultiGate** — routes a single pulse across many outputs, optionally `Is Random` and/or `Loop`. - **Switch nodes** — read a data input and branch to the matching execution output; available as `Int`, `String`, `Name`, and `Enum` (Enum switches auto-generate pins from the Enum's properties). ## When To Use Reach for Blueprints when designers or gameplay engineers need to author or extend behavior directly in the editor without recompiling C++. Use the Construction Script for setup that must respond to how an instance is placed (choosing a mesh by ground type, sizing a fence by trace). Use Functions to encapsulate reusable, callable logic with typed inputs and outputs; prefer Pure Functions for stateless getters and Impure for anything that changes state. ## Risks & Pitfalls - Loop iterations take place between frames, so large loops (ForLoop, ForLoopWithBreak) may incur a performance hit. - WhileLoop can produce infinite loops that make the game unresponsive or crash; verify the terminating condition is initialized before the first test and updated each cycle. - A Pure Function is re-evaluated for *every* node that consumes its output, so an expensive Pure Function wired widely can be costly. - If a Function call node shows a `Warning!` bar with "Unable to find function with name [FunctionName]", or if you change the number of input/output parameters, you must Compile the Blueprint. ## Related Concepts - [[concepts/blueprint-communication]] - [[concepts/programming-with-cpp]] - [[syntheses/blueprints-vs-cpp]] ## Sources - raw/blueprints/blueprints-visual-scripting-in-unreal-engine.md - raw/blueprints/functions-in-unreal-engine.md - raw/blueprints/flow-control-in-unreal-engine.md - raw/blueprints/construction-script-in-unreal-engine.md --- title: "Cameras & User Interfaces (UMG/HUD)" type: concept tags: [camera, hud, ui, slate, viewport] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/gameplay/cameras-in-unreal-engine.md", "raw/gameplay/user-interfaces-and-huds-in-unreal-engine.md"] confidence: high --- # Cameras & User Interfaces (UMG/HUD) ## Definition The **Camera** represents the player's point of view — how the player sees the world — so cameras only matter for human-controlled players. A **PlayerController** specifies a camera class and instantiates a **Camera Actor** (`ACameraActor`) whose settings live on a **Camera Component**. On the presentation side, **User Interfaces (UIs)** and **Heads-up Displays (HUDs)** are the game's way of conveying information to the player and, in some cases, taking directed input. Each human-controlled player has its own **HUD** (`AHUD`) instance that draws to its Viewport, and lower-level drawing is done through the **Canvas** and the **Slate** UI framework. ## How It Works **CameraActor and CameraComponent.** All of a camera's behavior and properties are configured on the **Camera Component**; the `CameraActor` class primarily acts as a wrapper so the camera can be placed directly in the level. A **CameraComponent** represents a viewpoint and its settings — **Projection Type**, **Field Of View**, and **Post-Process Overrides**. In the Editor, `Details > Camera Settings` sets whether the camera is **Perspective** or **Orthographic**: perspective mode uses a vertical **field of view (FOV)**, while orthographic mode uses a width in world units. Both modes support an aspect ratio (with device presets) and scalable **Post process effects**. A **FrustumComponent** (shown via `Show > Advanced > Camera Frustums`) visualizes the FOV in the editor but is hidden during gameplay. **View targets.** An Actor becomes the camera source (**ViewTarget**) if it is a CameraActor or contains a CameraComponent and has `bFindCameraComponentWhenView Target` set to `true`. Any Pawn with `bTakeCameraControlWhenPossessed` set will automatically become the ViewTarget when possessed by the PlayerController. Both PlayerControllers and Actors expose a **CalcCamera** function: an Actor's CalcCamera returns the view of its first CameraComponent (when `bFindCameraComponentWhenView Target` is true), otherwise its location and rotation; the PlayerController's version returns the possessed Pawn's location with the controller's control rotation. **PlayerCameraManager.** The **PlayerCameraManager** manages the camera for one player and defines the final view properties used by systems like the Renderer. It can compute camera properties directly or blend between Actors (for example, blending from one CameraActor to another). It answers `Get()` functions such as **GetCameraViewPoint**, maintains a view target, and can apply post effects. If you subclass it in Blueprint rather than C++, override **BlueprintUpdateCamera** (return `true` to use its values, `false` to ignore them); **UpdateViewTarget** queries the ViewTarget and calls BlueprintUpdateCamera when you are not looking through a CameraComponent. The **ViewTarget** struct carries the target Actor, its Controller, and the PlayerState, and passes its point of view as an **FMinimalViewInfo** struct containing Location, Rotation, Projection Mode, FOV, Orthographic Width, Aspect Ratio, and Post Process Effects. This whole flow is the **camera "responsibility chain"**, which passes down through `ALocalPlayer` and ends with Rendering, **Scene View** (`FSceneView`), and related systems. **HUD, Canvas and Slate.** The **HUD** is the base object for elements overlaid on the screen — score, health, remaining time — and is usually non-interactive. Every human player has its own `AHUD` instance drawing to its Viewport (in splitscreen, each HUD still draws to its own Viewport), and the HUD class is specified by the gametype in use. During the HUD's render loop, the **Canvas** object draws text, texture and material tiles, arbitrary triangles, and simple primitive shapes; unless you use a specialized alternative, Canvas is the standard way to build HUDs and UIs. **Slate** is Unreal's custom, platform-agnostic UI framework — the declarative foundation for editor tools and in-game interfaces (the widget-based UI built on top of it, UMG, sits on this framework). Menus and interactive UIs are usually overlaid on the screen like the HUD, but can also be rendered onto a surface in the world. ## Key Parameters - **Camera classes** — `ACameraActor` (level-placeable wrapper), **CameraComponent** (holds the actual settings), **PlayerCameraManager**, and the **ViewTarget** struct. - **CameraComponent settings** — **Projection Type** (Perspective / Orthographic), **Field Of View**, **Post-Process Overrides**; vertical FOV for perspective, world-unit width for orthographic, plus aspect ratio. - **View-target flags** — `bFindCameraComponentWhenViewTarget` and `bTakeCameraControlWhenPossessed`. - **Camera functions** — `CalcCamera`, `GetCameraViewPoint`, `BlueprintUpdateCamera`, `UpdateViewTarget`; view data travels as an **FMinimalViewInfo** struct. - **Editor visualization** — **FrustumComponent** via `Show > Advanced > Camera Frustums`. - **UI classes** — **HUD** (`AHUD`), **Canvas**, **Slate**; each HUD draws to its own **Viewport** and its class is set by the gametype. ## When To Use Place a **CameraActor** in the level when you want a fixed or blended cinematic viewpoint, and drive per-frame camera logic through the **PlayerCameraManager** (via `BlueprintUpdateCamera` for custom behavior). Use **ViewTarget** flags to let a possessed Pawn automatically own the view. For on-screen information, draw non-interactive status through the **HUD**/**Canvas**; for menus and richer interactive interfaces, build on **Slate** (and its widget layer). ## Risks & Pitfalls - Cameras only have relevance to human-controlled players — there is no meaningful camera for a purely AI-driven Pawn. - If a Pawn's camera does not activate on possession, check `bFindCameraComponentWhenViewTarget` and `bTakeCameraControlWhenPossessed`. - The **FrustumComponent** is editor-only and never visible during gameplay, so do not rely on it as an in-game indicator. - The HUD/UI boundary is a gray area: HUDs are meant to be non-interactive, so interactive elements generally belong in a Slate-based UI, not the HUD. ## Related Concepts - [[concepts/gameplay-framework]] — PlayerController, Pawn possession, and gametype that select the camera and HUD classes. - [[concepts/ai-behavior-trees]] — the AI debugger can overlay the active HUD class. - [[concepts/actors-and-components]] — CameraComponent and FrustumComponent are Actor components. - [[concepts/blueprints-visual-scripting]] — subclassing PlayerCameraManager in Blueprint via BlueprintUpdateCamera. ## Sources - raw/gameplay/cameras-in-unreal-engine.md - raw/gameplay/user-interfaces-and-huds-in-unreal-engine.md --- title: "The Content Import Pipeline" type: concept tags: [import, interchange, fbx, usd, datasmith] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/content/interchange-framework-in-unreal-engine.md", "raw/content/fbx-content-pipeline.md", "raw/content/the-gl-transmission-format-gltf-in-unreal-engine.md", "raw/content/universal-scene-description-usd-in-unreal-engine.md", "raw/content/datasmith-plugins-for-unreal-engine.md", "raw/content/alembic-file-importer-in-unreal-engine.md"] confidence: high --- # The Content Import Pipeline ## Definition Unreal Engine supports a variety of file formats for importing content into your project, and the modern entry point for that work is the **Interchange Framework** — Unreal Engine's import and export framework. Interchange is file-format agnostic, asynchronous, customizable, and can be used at runtime. Alongside it sit format-specific paths (FBX, glTF, USD, Alembic) and the enterprise-focused Datasmith toolset, each suited to a different kind of source content. ## How It Works Interchange is built on an extensible code base that provides a customizable **pipeline stack**, giving you the freedom to edit the import pipeline using Blueprint or Python to fit your project's needs. Most format-specific importers deposit assets into the project through the **Content Browser**, either via the **Import** button or by dragging files in from the operating system. Each format targets different source content: - **FBX** is a flexible file format owned by Autodesk that provides interoperability between digital content creation (DCC) applications. The Unreal FBX import pipeline uses **FBX 2020.2** — using a different version during export may cause incompatibilities. Its advantages: a single file format for Static Mesh, Skeletal Mesh, animation, and morph targets; importing multiple LODs and Morphs/Blendshapes in one operation; and importing Material and Texture assets that are automatically applied to Static Meshes. - **glTF** (GL Transmission Format) is an extensible, open-standard format developed and maintained by the Khronos Group, designed to create compact files that load quickly and represent scenes completely. It is used to share rich 3D content between applications including Unreal Engine, Twinmotion, and Sketchfab. - **USD** (Universal Scene Description) is an open-source format developed by Pixar to robustly and scalably interchange and augment arbitrary 3D scenes composed of many elemental assets. It provides a rich toolset for reading, writing, editing, and rapidly previewing 3D geometry and shading, plus interchange of elemental assets (models) and animations. **USD is a Beta feature — use caution when shipping with it.** - **Alembic** (ABC) is an open interchange framework that distills complex, animated scenes into a non-procedural, application-independent set of baked geometric results, imported through the **Alembic Importer**. - **Datasmith** is a collection of tools and plugins that bring entire pre-constructed scenes and complex assets — created in industry-standard design applications — into Unreal Engine. ## Key Parameters - **Interchange customization** — edit the import pipeline with Blueprint or Python; asynchronous and runtime-capable. - **FBX version** — **FBX 2020.2** is the supported version. - **Alembic Import Type** — set on import via the **Alembic Cache Import Options** window; defaults to **Static Mesh**, with **Geometry Cache** and **Skeletal** as the alternatives. - *Static Mesh* imports a single frame (set by **Frame Start** in the **Sampling** section). Options include **Merge Meshes**, **Propagate Matrix Transformations**, and **Generate Lightmap UVs**. - *Geometry Cache* creates an animation asset that plays back vertex-varying sequences as a flipbook, adding Material support (Materials created from found **Face Set** names) and **Motion Vectors** options (No Motion Vectors / Import Abc Velocities as Motion Vectors / Calculate Motion Vectors During Import). - *Skeletal* imports base poses as morph targets, compressing the sequence with a Principal Component Analysis (PCA) scheme — the most efficient playback path as long as the vertex count does not change. - Alembic supports only meshes with three- and four-sided polygons; NURBS, SubDiv surfaces, or polygons with more than four sides will fail to load. - **Datasmith features** — Direct Link (live connection), Dataprep (reusable import recipes), reimport workflow, metadata access, and Blueprint/Python customization. Supported applications include 3ds Max, Revit, Rhino, SketchUp Pro, Solidworks, Cinema 4D, Archicad, Navisworks, Deltagen and VRED, plus CAD and IFC file formats. ## When To Use - **FBX** — the general-purpose path for individual Static Meshes, Skeletal Meshes, and their animations/morph targets coming out of Maya, 3ds Max, MotionBuilder, or Blender, especially when you want LODs and materials in one import. - **glTF** — when sharing compact, quick-loading 3D content across an open-standard ecosystem (Unreal, Twinmotion, Sketchfab). - **USD** — when interchanging large, composed scenes made of many elemental assets across a studio pipeline, and you need to preview/edit geometry and shading non-destructively (Beta). - **Alembic** — for baked, application-independent vertex animation caches (simulations, complex externally authored animation) rendered in real time. - **Datasmith** — for enterprise, architectural, and manufacturing workflows where you need to bring an entire pre-constructed scene and its complex assets from a design/CAD application into Unreal at once. ## Risks & Pitfalls - Exporting FBX from a version other than **FBX 2020.2** may result in incompatibilities. - USD is a Beta feature — validate before shipping. - Alembic **Merge Meshes** can cause problems with overlapping UV sets; without **Propagate Matrix Transformations** merged meshes collapse to the 0,0,0 origin. Face Set names are required in the source file for Materials to be created on Geometry Cache import. - Alembic Skeletal imports with a large normal delta can produce incorrect-looking normals (a known morph-target issue); the experimental skin cache is a workaround. ## Related Concepts - [[concepts/meshes-and-modeling]] - [[concepts/materials-and-substrate]] - [[concepts/unreal-editor-and-projects]] ## Sources - raw/content/interchange-framework-in-unreal-engine.md - raw/content/fbx-content-pipeline.md - raw/content/the-gl-transmission-format-gltf-in-unreal-engine.md - raw/content/universal-scene-description-usd-in-unreal-engine.md - raw/content/datasmith-plugins-for-unreal-engine.md - raw/content/alembic-file-importer-in-unreal-engine.md --- title: "The Gameplay Framework" type: concept tags: [gameplay-framework, gamemode, playercontroller, pawn, replication] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/gameplay/gameplay-framework-in-unreal-engine.md", "raw/gameplay/game-mode-and-game-state-in-unreal-engine.md", "raw/gameplay/actors-in-unreal-engine.md", "raw/gameplay/controllers-in-unreal-engine.md"] confidence: high --- # The Gameplay Framework ## Definition The Gameplay Framework is Unreal Engine's collection of cooperating classes that provide a modular foundation for building a gameplay experience. You pick and choose the elements right for your game, knowing these classes are designed to work with and complement one another. Together they define who runs the rules (the game mode), what the shared and per-player state is (game state and player state), how a player is represented (a controller possessing a pawn), and what persists across levels (the game instance). ## How It Works The classes come to life in a specific order and with distinct lifetimes and replication behavior: - **Game Instance** is instantiated on engine launch and remains active until the engine shuts down. It is a manager class with no physical presence in the game; it tracks data and runs code. It is **not replicated** and exists independently on the server and every client. Anything that must persist between level loads (for example, a save game system) belongs here. It also manages any number of **game instance subsystems** (such as the Online Subsystems) that share its lifetime. - **Game Mode** is instantiated immediately after the level loads and the world is created. It is a server-based manager class inherited from the Actor class, is the first actor to instantiate on level load, and can be set on a map-by-map basis. It sits at the heart of the framework, managing the rules and structure of a session and spawning the remaining framework actors — first the game state and player state. It is **not persistent across levels**. - **Game State** and **Player State** are non-physical actors that track the state of the game and of individual players, respectively. Both **replicate** their state between the authoritative server and all connected clients. Game state holds data relevant to all players (team scores, objectives, and a list of all players and their player states); player state holds data relevant to one player (health, ammo count, inventory). One game state is created by the game mode; a player state is created for each player as they join. - A **player** primarily consists of a **controller** and a **pawn**. The game mode spawns players when they join. Controllers are non-physical actors that possess a pawn to control its actions, using the `Possess` function and relinquishing it with `Unpossess`. There is by default a one-to-one relationship between a controller and a pawn. A `PlayerController` processes input from a human, displays heads-up information, and possesses physical representations; an `AIController` possesses pawns and dictates their actions using AI such as behavior trees, state trees, and navigation. Controllers receive notifications for many events occurring on the pawn they control, letting them intercept and supersede the pawn's default behavior. The **pawn** is the physical manifestation of the player in the world and is the base class for any actor controllable by a player or AI. Pawns are built from actor components such as a collision component, static mesh component, and movement component. The **character** is a pawn-derived subclass adding feature-rich components: a character movement component, skeletal mesh component, and capsule component. Every one of these is an **Actor** (`AActor` in C++) — any object placeable in a level, supporting translation, rotation, and scaling, spawnable and destroyable through gameplay code. Actors are containers for **components** and are the unit of network **replication** for both property values and function calls. The **World** is the top-level object representing the map in which actors and components exist, holding the persistent level plus the game state, game mode, and lists of pawns and controllers currently on the map. ## Key Parameters - **`AActor`** — base class of all Actors; parent of Pawn, Controller, Game Mode, Game State, Player State, HUD, Camera, and more. - **`AGameModeBase`** — base class for all game modes; the streamlined default in new code projects. Common overrides include `InitGame`, `PreLogin`, `PostLogin`, `HandleStartingNewPlayer`, `RestartPlayer`, `SpawnDefaultPawnAtTransform`, and `Logout`. - **`AGameMode`** — subclass of `AGameModeBase` adding a match state machine for multiplayer; pair it with `AGameState`. - **`AGameStateBase`** — base game state; exposes `GetServerWorldTimeSeconds`, the `PlayerArray` of all `APlayerState` objects, and `HasBegunPlay`. - **Player State** — per-player data (`APlayerState`), created per player on join. - **Game Instance** / **Game Instance Subsystem** — engine-lifetime managers; not replicated. - **HUD** — base object for elements overlaid on the screen; every human-controlled player has its own instance drawing to its viewport. - **Gameplay Statics** — static class for common game functions (playing sounds, spawning actors, applying damage, getting the player pawn or player controller). ## When To Use Use the Gameplay Framework as the backbone of essentially any UE game. Reach for the **game mode** to define rules (player counts, spawn/respawn behavior, pausing, level transitions) and to specify which pawn, HUD, controller, spectator, game state, and player state classes to use. Store globally-visible, game-wide, changing data on the **game state**; store per-player data on the **player state**. Put anything that must survive level travel on the **game instance**. Most classes can be customized in C++, Blueprint, or a combination. ## Risks & Pitfalls - **The game mode exists only on the server** and is not replicated. Clients see only the stock class, not the live instance or its variables. Route client-visible information through the replicated game state instead. - Because the game mode is created on level load, it is **not persistent across levels** — do not store cross-level data there; use the game instance. - Don't keep player-specific data (like one player's score) on the game state; the player state handles that more cleanly. - If you inherit from `AGameMode` for match-state behavior, remember to also inherit your game state from `AGameState`. ## Related Concepts - [[concepts/actors-and-components]] - [[concepts/input-system]] - [[concepts/physics-and-collision]] - [[concepts/cameras-and-ui]] - [[syntheses/choosing-gameplay-systems]] ## Sources - raw/gameplay/gameplay-framework-in-unreal-engine.md - raw/gameplay/game-mode-and-game-state-in-unreal-engine.md - raw/gameplay/actors-in-unreal-engine.md - raw/gameplay/controllers-in-unreal-engine.md --- title: "The Input System" type: concept tags: [input, playerinput, playercontroller, pawn, gameplay-framework] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/gameplay/input-in-unreal-engine.md", "raw/gameplay/controllers-in-unreal-engine.md", "raw/gameplay/gameplay-framework-in-unreal-engine.md"] confidence: medium --- # The Input System ## Definition Unreal Engine's input system is the processing flow that turns raw hardware input from a player into data that actors can understand and act on. At its core is the `PlayerInput` object, which converts player input into game events and movement. The input path connects a physical device, through player input mappings and input components, to the actors — chiefly the `PlayerController` and the `Pawn` — that respond to it. ## How It Works The `PlayerInput` object is responsible for converting input from the player into data that actors (like `PlayerController`s or `Pawn`s) can understand and use. It is part of an input processing flow that translates hardware input into game events and movement using **player input mappings** and **input components**. In other words, a device event enters the pipeline, is interpreted against the configured mappings, and is delivered as a meaningful gameplay signal to the actors that have registered to receive it. The `PlayerController` is the framework's designated recipient of human input. In the Gameplay Framework, the player controller is the manager class that **processes input from a human**, displays heads-up information, and possesses physical representations in the game world. A controller possesses a pawn with the `Possess` function and gives up control with `Unpossess`; while possessing, it directs the pawn to perform actions. This split is deliberate: the controller (a non-physical actor) holds the input-and-decision logic, while the pawn holds the physical representation that the input ultimately drives. Because controllers receive notifications for many of the events occurring on the pawn they control, a controller can implement behavior in response to an event, intercepting it and superseding the pawn's default behavior. It is also possible to make the controller **tick before a given pawn**, which minimizes latency between input processing and pawn movement — a useful property for input-driven gameplay. By default there is a one-to-one relationship between a controller and a pawn, so each controller processes input for exactly one pawn at a time, though some game types (such as real-time strategy) may need to adjust this to control multiple entities. Some actor components exist specifically for interpreting input. Actor components used for "conceptual functionality, like AI or interpreting player input" are associated with a specific actor but do not exist at any specific place in the world, which is exactly the profile of an input-handling component attached to the controller or pawn. ## Key Parameters - **`PlayerInput`** — the object responsible for converting player input into data that actors can use; the entry point of the input processing flow. - **Player input mappings** — the configured mappings the flow uses to translate hardware input into game events and movement. - **Input components** — the components that carry input bindings on an actor and participate in the translation of hardware input into gameplay signals. - **`PlayerController`** — the manager class that processes input from a human player; the primary consumer of input in the Gameplay Framework. - **`Possess` / `Unpossess`** — the controller functions that take and release control of a pawn, connecting processed input to a physical representation. - **Controller tick ordering** — making the controller tick before its pawn minimizes latency between input processing and pawn movement. ## When To Use Route all human player input through the `PlayerController` rather than reading devices directly in a pawn — this keeps input logic on the non-physical actor that survives possession changes and lets a single controller drive different pawns over a session. Bind input via input components and player input mappings so that hardware events are translated into game events and movement in one consistent flow. When responsiveness matters, ensure the controller ticks before the pawn so processed input reaches movement with minimal latency. Use the controller's event notifications to intercept pawn events and override default behavior where your game needs custom responses. ## Risks & Pitfalls - Reading hardware input directly on a pawn ties input handling to a specific physical representation; because controllers persist across `Possess` / `Unpossess`, input logic belongs on the controller. - The default one-to-one controller-to-pawn relationship is an assumption, not a guarantee — games that control multiple entities at once must design for it explicitly. - Tick ordering affects perceived input latency; if the pawn ticks before its controller, input can lag movement by a frame. > Scope note: this page is grounded in the Gameplay Framework input flow > (`PlayerInput`, player input mappings, input components, and the > `PlayerController`'s role) as described in the assigned sources. Enhanced Input > specifics — Input Actions, Input Mapping Contexts, and their triggers and > modifiers — are not covered in the assigned raw material, so their exact class > names are intentionally omitted rather than fabricated. ## Related Concepts - [[concepts/gameplay-framework]] - [[concepts/actors-and-components]] - [[concepts/blueprints-visual-scripting]] ## Sources - raw/gameplay/input-in-unreal-engine.md - raw/gameplay/controllers-in-unreal-engine.md - raw/gameplay/gameplay-framework-in-unreal-engine.md --- title: "Lighting, Shadows & the Path Tracer" type: concept tags: [rendering, lighting, shadows, virtual-shadow-maps, path-tracer] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/rendering/lighting-the-environment-in-unreal-engine.md", "raw/rendering/global-illumination-in-unreal-engine.md", "raw/rendering/virtual-shadow-maps-in-unreal-engine.md", "raw/rendering/path-tracer-in-unreal-engine.md"] confidence: high --- # Lighting, Shadows & the Path Tracer ## Definition Lighting an environment in Unreal Engine means combining light sources, a global illumination (GI) solution, a shadowing method, and post-process exposure into a coherent look. GI simulates indirect lighting — light bouncing off geometry, picking up material color and reflectivity. Unreal offers two GI paths that can be blended in the same scene: **precomputed** (baked) lighting via Lightmass, and **dynamic** lighting via [[concepts/lumen-global-illumination|Lumen]]. Shadowing is handled primarily by **Virtual Shadow Maps** (VSMs), and the **Path Tracer** provides an offline, physically correct ground-truth renderer. This page covers those pieces beyond Lumen itself. ## How It Works **GI paths.** Precomputed lighting is computed by the **Lightmass** GI system, either **CPU-based Lightmass** (using a separate program, Unreal Swarm, to distribute across machines) or **GPU-based Lightmass** (using an NVIDIA GPU with DirectX 12 and ray tracing). Baked results are stored in lightmap textures; Static Meshes require a Lightmap UV to store the data, and lighting cannot change at runtime — ideal where lighting is static or for mobile. Dynamic GI (Lumen) supports all geometry types and time-of-day changes at higher real-time cost. Precomputed and dynamic can be combined. **Virtual Shadow Maps.** VSMs are the shadow-mapping method built for film-quality Nanite assets and large dynamically lit worlds. Conceptually they are very high-resolution shadow maps with a virtual resolution of 16k x 16k pixels, split into 128x128 **Pages** allocated and rendered only as needed based on depth-buffer analysis, and cached between frames unless invalidated. Directional Lights use a **clipmap** structure (each level its own 16K VSM covering twice the radius of the previous), Spot Lights use a single 16k VSM with a mip chain, and Point Lights use a cube map of 16k VSMs. **Shadow Map Ray Tracing (SMRT)** produces soft shadows and contact hardening by projecting samples along rays toward the light, distributed by **Source Radius** (local lights) or **Source Angle** (Directional Lights). **Path Tracer.** The Path Tracer is a progressive, hardware-accelerated rendering mode giving physically correct, compromise-free GI, reflection, and refraction. It shares Unreal's ray-tracing architecture and integrates with Sequencer and Movie Render Queue for film/TV-quality output. It progressively accumulates samples while the camera is still, then denoises; scene changes (moving the camera, editing materials, adding objects) invalidate samples and restart accumulation. ## Key Parameters **Enabling Virtual Shadow Maps** — in Project Settings under `Engine > Rendering` in the `Shadows` section, set **Shadow Map Method** to **Virtual Shadow Maps** (or the conventional Shadow Maps). Pre-5.0 projects opt in via `r.Shadow.Virtual.Enable`; new projects use VSMs by default. VSMs are designed to be used with Nanite. VSM console variables (verbatim): - `r.Shadow.Virtual.SMRT.RayCountLocal` / `r.Shadow.Virtual.SMRT.RayCountDirectional` — number of rays (eight by default at Epic Shadow scalability); 0 disables SMRT and reverts to single-sample hard shadows. - `r.Shadow.Virtual.SMRT.SamplesPerRayLocal` / `r.Shadow.Virtual.SMRT.SamplesPerRayDirectional` — samples per ray (values between 4 and 8 work well). - `r.Shadow.Virtual.Clipmap.FirstLevel` / `r.Shadow.Virtual.Clipmap.LastLevel` — clipmap range (default levels 6 through 22). - `r.Shadow.Virtual.ResolutionLodBiasDirectional` / `r.Shadow.Virtual.ResolutionLodBiasLocal` — resolution bias. - `r.Shadow.Virtual.Cache 0` — disable page caching (debug only). - `r.Shadow.Virtual.NormalBias` — default 0.5; raises bias to reduce shadow-terminator artifacts on low-poly meshes. - `r.Shadow.Virtual.MaxPhysicalPages` — page pool size; enable stats with `r.ShaderPrintEnable 1` then `r.Shadow.Virtual.ShowStats 2`. - `r.Shadow.Virtual.Visualize [mode]` — visualization channels (`cache`, `vpage`, `mask`, `mip`, `naniteoverdraw`, `raycount`, `clipmapvirtual`, `none`). **Path Tracer enabling** — requires Hardware Ray Tracing. Set Default RHI to DirectX 12, and under `Engine > Rendering > Hardware Ray Tracing` enable **Support Hardware Ray Tracing** and **Path Tracing**; enabling HWRT also requires **Support Compute Skin Cache** (`Engine > Rendering > Optimizations`). Restart the engine. Select **Path Tracing** from the Level Viewport **View Modes** dropdown. Path Tracer Post Process Volume settings (under the `PathTracing` category): **Max. Bounces**, **Samples Per Pixel**, **Max Path Intensity**, **Emissive Materials**, **Reference Depth of Field**, **Reference Atmosphere**, and **Denoiser** (uses the NNE Denoiser plugin by default). Path Tracer console variables (verbatim): `r.PathTracing.VisibleLights` (set to 2 to make only the Skylight visible), `r.PathTracing.ProgressDisplay`, `r.PathTracing.Denoiser`, `r.PathTracing.CompactionDepth` (default 6), `r.PathTracing.ShaderExecutionReordering`, and `r.PathTracing.EnableEmissive 0`. ## When To Use Use **Lightmass** baked GI when lighting never changes or for mobile projects where dynamic lighting is limited; use **Lumen** for dynamic scenes. Use **Virtual Shadow Maps** whenever a project uses Nanite — if you use Nanite you must use either Movable Lights or VSMs, since Nanite does not support many Stationary Light shadowing techniques. Use the **Path Tracer** for ground-truth comparisons and production/offline film renders where physical accuracy matters more than real-time speed. ## Risks & Pitfalls - **VSM caching:** light movement/rotation invalidates all cached pages for that light; moving/added/removed shadow casters invalidate overlapping pages; WPO/PDO materials and skeletal animation invalidate cached pages every frame. Keep object bounds tight, and prefer Nanite on large shadow casters like buildings. If `Pages` exceeds `Max Pages`, corruption (checkerboard/missing shadows) occurs. - **Non-Nanite geometry** is much more expensive to render into VSMs — enable Nanite on all supported geometry including low-poly meshes, set up full Mesh LOD hierarchies on non-Nanite meshes, and use `r.Shadow.RadiusThreshold` for CPU culling. - **VSM materials:** only simple subsurface materials are supported; Subsurface Profile and transmission are shadowed as opaque. - **Exposure / fireflies:** in the Path Tracer, the **Max Path Intensity** Post Process setting clamps maximum intensity to reduce firefly artifacts; it is relative to current exposure, so it can be kept constant. Its default clamps fireflies aggressively and rarely needs changing — raising it gives more accurate but noisier renders. Interior scenes with material albedos close to 1.0 produce long light paths and long render times. - **VSM platforms:** PS5, Xbox Series S|X, and PCs with DirectX 12 (Shader Model 6.6 atomics) or Vulkan; NVIDIA Maxwell / AMD GCN or newer. ## Related Concepts - [[concepts/lumen-global-illumination]] - [[concepts/nanite-virtualized-geometry]] - [[concepts/materials-and-substrate]] - [[syntheses/rendering-feature-map]] ## Sources - raw/rendering/lighting-the-environment-in-unreal-engine.md - raw/rendering/global-illumination-in-unreal-engine.md - raw/rendering/virtual-shadow-maps-in-unreal-engine.md - raw/rendering/path-tracer-in-unreal-engine.md --- title: "Lumen Global Illumination & Reflections" type: concept tags: [rendering, lighting, global-illumination, reflections, ray-tracing] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/rendering/lumen-global-illumination-and-reflections-in-unreal-engine.md", "raw/rendering/lumen-technical-details-in-unreal-engine.md"] confidence: high --- # Lumen Global Illumination & Reflections ## Definition Lumen is Unreal Engine's fully dynamic global illumination (GI) and reflections system, designed for next-generation consoles, and it is the default GI and reflections system. Lumen renders diffuse interreflection with infinite bounces and indirect specular reflections in large, detailed environments at scales ranging from millimeters to kilometers. It replaces Distance Field Ambient Occlusion (DFAO) for GI and Screen Space Reflections for reflections. Because Lumen is fully dynamic, when it is enabled precomputed static lighting contributions are disabled and all lightmaps are hidden. ## How It Works Lumen solves lighting in two passes: Screen Traces are done first, followed by a more reliable ray-tracing method if no screen-space hit is found. It uses two ray-tracing methods: - **Software Ray Tracing** traces against Mesh Distance Fields (signed distance fields) merged into a Global Distance Field. It runs on any hardware supporting Shader Model 6 (SM6) and only requires that `Generate Mesh Distance Fields` be enabled. By default it traces each mesh's distance field for the first two meters for accuracy and the Global Distance Field for the rest of each ray. - **Hardware Ray Tracing** traces against actual triangles and can evaluate lighting at the ray hit instead of the lower-quality Surface Cache. It is enabled by default, gives higher quality (including mirror reflections and skinned-mesh support), but requires supported video cards and has significant scene update cost with more than 100,000 instances. Lumen builds an automatic parameterization of the nearby scene called the **Surface Cache**, capturing material properties from multiple angles at positions called **Cards** (generated offline per mesh; 12 Cards by default). It is used to quickly look up lighting at ray hit points. Sky lighting is solved as part of Lumen's **Final Gather** process, including sky shadowing. Lumen relies on Nanite's LOD and multi-view rasterization for fast scene captures; it does not require Nanite, but scene capturing becomes very slow with many high-poly non-Nanite meshes. When using Software Ray Tracing, Lumen Scene covers 200 meters from the camera, extendable up to 800 m via `Lumen Scene View Distance`. ## Key Parameters Settings live in two places: **Project Settings** (`Engine > Rendering`) and the **Post Process Volume**. Project Settings: - **Dynamic Global Illumination Method** — set to `Lumen` (under Dynamic Global Illumination). - **Reflection Method** — set to `Lumen`. GI and Reflections can be set independently. - **Use Hardware Ray Tracing when available** — uses HWRT when supported by card/RHI/OS, falling back to Software otherwise. - **Ray Lighting Mode** — `Surface Cache` (default, best performance) or `Hit Lighting for Reflections` (higher quality). - **Software Ray Tracing Mode** — `Detail Tracing` (per-mesh distance fields, highest quality) or `Global Tracing` (Global Distance Field, fastest; engine default). - **Support Hardware Ray Tracing** — enables ray tracing; changing it requires an engine restart. - **Generate Mesh Distance Fields** — required for Software Ray Tracing; **Distance Field Voxel Density** controls default voxel dimensions. - **High Quality Translucency Reflections** — mirror reflections on the front layer of translucent surfaces. Post Process Volume (Global Illumination): - **Lumen Scene Lighting Quality**, **Lumen Scene Detail**, **Lumen Scene View Distance** — higher values increase fidelity/range at higher GPU cost. - **Final Gather Quality** — raises GI quality and reduces noise. - **Screen Traces** — toggles screen-space traces for GI. - **Max Trace Distance** — max distance Lumen traces; too small leaks light into large areas (e.g. caves). - **Diffuse Color Boost**, **Skylight Leaking**, **Full Skylight Leaking Distance** — art-direction knobs (non-physical). Post Process Volume (Reflections): - **Quality**, **Ray Lighting Mode**, **Max Roughness To Trace**. - **Max Reflection Bounces** — default is 1; can be raised up to 8 in the Post Process setting. Use `r.Lumen.Reflections.MaxBounces` to override up to 64 bounces (requires Hardware Ray Tracing with Hit Lighting). - **Max Refraction Bounces** — refraction events to trace. Useful console commands: `r.Lumen.Visualize.CardPlacement 1` (visualize Cards), `r.DistanceFields.LogAtlasStats 1`, `r.LumenScene.FarField=1` (Far Field traces to 1 km, requires HLOD1), `r.RayTracing.Culling.Radius`, and `r.MeshCardRepresentation.SkeletalMesh` (skeletal Surface Cache, on by default). ## When To Use Use Lumen as the default for any project needing dynamic GI and reflections — time-of-day, movable lights, and detailed interiors/exteriors on next-gen consoles and high-end PCs. Choose Software Ray Tracing for the widest hardware support and scenes with many overlapping instances; choose Hardware Ray Tracing for the highest quality mirror reflections and skinned-mesh tracing. Lumen Reflections can also be used standalone with baked static GI (requires Lumen Hardware Ray Tracing mode) to scale reflection quality beyond placed reflection captures. ## Risks & Pitfalls - Lumen is **not** compatible with Forward Shading, cannot be combined with static GI in lightmaps (Reflections can), and does not support VR or previous-generation consoles (PS4/Xbox One). - Global lighting changes (e.g. disabling the sun) can take multiple seconds to propagate; use `Lumen Scene Lighting Update Speed` and `Final Gather Lighting Update Speed` to work around this at higher GPU cost. - Static-mobility lights are unsupported — their contribution is stored in lightmaps and disabled under Lumen. - Areas lacking Surface Cache coverage appear pink in the Surface Cache view mode and render black in reflections; fix by raising **Max Lumen Mesh Cards** or splitting complex meshes. Only meshes with simple interiors are supported — model walls, floors, and ceilings as separate meshes rather than importing a whole furnished room as one mesh. - Software Ray Tracing does not support World Position Offset (WPO); walls thinner than 10 cm can leak light; a mesh imported small and scaled up on the component will lack distance field resolution — set it in the Static Mesh Editor Build Settings instead. ## Related Concepts - [[concepts/nanite-virtualized-geometry]] - [[concepts/lighting-and-shadows]] - [[concepts/materials-and-substrate]] - [[syntheses/rendering-feature-map]] ## Sources - raw/rendering/lumen-global-illumination-and-reflections-in-unreal-engine.md - raw/rendering/lumen-technical-details-in-unreal-engine.md --- title: "Materials, PBR & Substrate" type: concept tags: [materials, pbr, substrate, textures, shaders] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/rendering/unreal-engine-materials.md", "raw/rendering/physically-based-materials-in-unreal-engine.md", "raw/rendering/substrate-materials-in-unreal-engine.md", "raw/rendering/textures-in-unreal-engine.md"] confidence: high --- # Materials, PBR & Substrate ## Definition A Material in Unreal Engine defines the surface properties of the objects in your scene — in the broadest sense, the "paint" applied to a mesh to control its visual appearance. More technically, a Material tells the render engine exactly how a surface should interact with the light in your scene, defining color, reflectivity, bumpiness, transparency, and so on. These calculations are driven by data input from images (textures), node-based Material expressions, and property settings inherent to the Material itself. ## How It Works Materials are authored in the node-based **Material Editor**, which provides dozens of **Material Expressions** and **Functions**, each meant to perform a specific task in your Material graph. Expressions are organized in the Materials palette by category — for example, Blends, Gradients, Math, and Coordinates. Data flows through the graph as one of four float data types (see Material Data Types) and is wired into the inputs of the Main Material node. Unreal's default shading follows **physically based rendering** (PBR): surfaces approximate the way light behaves in the real world rather than the way we intuitively think it should. PBR Materials are more accurate and typically more natural-looking, work equally well in all lighting environments, and keep Material values less complex and interdependent — a more user-friendly workflow that applies even to non-photorealistic rendering. Several workflow features build on this foundation. **Material Instances** create hierarchical parent/child relationships so you can alter a child Material's appearance without recompiling the shader. **Material Functions** package part of a graph into a single reusable node. **Layered Materials** provide two methods for layering Materials to build complex, unique surfaces. ## Key Parameters **Physically based inputs** (all designed to accept values between 0 and 1): - **Base Color** — defines the overall color of the Material. Accepts a **Vector3 (RGB)** value where each channel is automatically clamped between 0 and 1. Measured metal values include Iron (0.560, 0.570, 0.580), Gold (1.000, 0.766, 0.336), Copper (0.955, 0.637, 0.538), and Silver (0.972, 0.960, 0.915). - **Roughness** — controls how rough or smooth the surface is, manifesting as how sharp or blurry reflections appear. A Roughness of 0 (smooth) gives a mirror reflection; a Roughness of 1 (rough) gives a diffuse, matte surface. Frequently mapped with a grayscale texture, where dark areas appear mirrorlike and light areas appear rough. - **Metallic** — defines whether the Material behaves as a metal or nonmetal. Treat it as binary: nonmetals are 0 (the default) and metals are 1. Use black-and-white masks (no intermediate grayscale) for surfaces that mix the two, such as painted metal; reserve in-between values for hybrids like corroded or rusty metal. - **Specular** — controls how much specular light the surface reflects. The default of **0.5** represents approximately 4% specular reflection and is accurate for the vast majority of materials. It is *not* used for reflection maps or surface variation — handle those in the Roughness map. To make very diffuse Materials, raise Roughness rather than lowering Specular. **Roughness vs. Specular:** Specularity is inherent to the Material type; the default 0.5 is usually correct. Micro-occlusion (cavities) can be added with a **cavity map** — typically an AO map with a very short trace distance — multiplied into the final Base Color and multiplied with the 0.5 Specular default. **Normal and packed maps:** A Material may sample several textures — for example a Base Color texture, a Specular texture, and a **Normal Map** texture — and can pack additional values such as Emissive and Roughness into the alpha channels of those textures to save draw calls and disk space. **Substrate framework:** **Substrate** is Unreal Engine 5's approach to authoring materials. It replaces the fixed suite of shading models and blend modes — such as Default Lit and Clear Coat — with a more expressive and modular framework for principled, BSDF-based material authoring. Substrate concepts include F0, F90 and Specular Color; BSDF Layering with Substrate Operators; Mean Free Path (MFP); thin film interference and secondary roughness; and fuzz. Programmers can work directly with Substrate's GBuffer formats in shader code. **Note: Substrate is a Beta feature — use caution when shipping with it.** ## When To Use Use the standard PBR inputs (Base Color, Roughness, Metallic, Specular) for the vast majority of surfaces; measured real-world values give a reliable starting point. Reach for Material Instances to spin up variations of a parent Material cheaply, and Material Functions to share graph logic across many Materials. Adopt Substrate when you need layered or blended surfaces (multi-lobe metals, thin films, coatings) that the fixed shading-model set cannot express — accepting its Beta status. ## Risks & Pitfalls - Resist using partial Metallic values without good reason; pure surfaces should be 0 or 1, and Metallic masks should be pure black and white. - Do not zero out Specular for diffuse Materials — all Materials have specular; use high Roughness instead. - Substrate is Beta; validate before shipping production titles with it. - **Textures:** use power-of-two sizes (32, 64, 128, 2048, …) — power-of-two textures can be mipmapped and streamed, while non-power-of-two sizes are never streamed and generate no mipmaps. Some GPUs cannot support textures larger than 8192 pixels (8k). Textures are imported through the Content Browser (Import button or drag-and-drop) and support formats including `.png`, `.tga`, `.psd`, `.exr` (HDR), `.dds`, and `.tif`. The **Texture Graph Editor** procedurally authors textures, and the **Texture Asset Editor** configures compression, brightness/saturation, and level of detail. ## Related Concepts - [[concepts/nanite-virtualized-geometry]] - [[concepts/lumen-global-illumination]] - [[concepts/lighting-and-shadows]] - [[syntheses/rendering-feature-map]] ## Sources - raw/rendering/unreal-engine-materials.md - raw/rendering/physically-based-materials-in-unreal-engine.md - raw/rendering/substrate-materials-in-unreal-engine.md - raw/rendering/textures-in-unreal-engine.md --- title: "Meshes & In-Editor Modeling" type: concept tags: [static-mesh, skeletal-mesh, modeling, geometry-scripting, content] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/content/static-meshes.md", "raw/content/skeletal-mesh-assets-in-unreal-engine.md", "raw/content/modeling-and-geometry-scripting-in-unreal-engine.md", "raw/content/fbx-content-pipeline.md"] confidence: high --- # Meshes & In-Editor Modeling ## Definition Meshes are the geometric building blocks of an Unreal Engine scene. **Static Mesh** assets are the basic unit used to create world geometry, while **Skeletal Mesh** assets are the foundational asset for characters, combining a visual mesh with an animatable skeleton. Both are typically authored in external modeling applications and imported through the Content Browser, but Unreal also ships in-editor authoring through **Modeling Mode** and the **Geometry Scripting** plugin for procedural generation. ## How It Works **Static Meshes** are 3D models created in external modeling applications (such as 3ds Max, Maya, or Blender) and imported into the Unreal Editor through the Content Browser. The vast majority of any level made with Unreal Engine consists of Static Meshes, generally placed as **Static Mesh Actors**. Because Static Meshes are cached in video memory, they can be translated, rotated, and scaled, and can be more complex than other types of geometry. **Skeletal Meshes** contain a character's visual mesh (its geometric model) plus a **skeleton** that holds bone data used to animate it. A Skeletal Mesh is created in Digital Content Creation (DCC) software and exported as an `.fbx` file, then imported into Unreal. The skeleton comes in as a separate **Skeleton asset**, editable in the **Skeleton Editor**; the mesh, skeleton, physics asset, and animation-sequence properties are editable in the **Skeletal Mesh Editors**. FBX files can also carry animations, which import as **Animation Sequence assets**. To use a Skeletal Mesh in gameplay you create a **Character Blueprint** and add the Skeletal Mesh as a **Mesh component**; you set the component's **Skeletal Mesh** property in the Details panel and align it in the Viewport with the Arrow and Capsule components. Animation is driven either by setting the Mesh component's **Animation Mode** to **Use Animation Asset** and choosing an **Anim to Play**, or through an **Animation Blueprint** whose **Anim Graph** dynamically selects Animation Sequences (using constructs such as blend spaces). **Modeling Mode** is Unreal's dedicated editor mode containing artist-friendly tools for creating and editing 3D geometry directly in the editor. The **Geometry Scripting** plugin exposes a range of functions to Blueprints and Python for advanced, procedural modeling workflows. Together these toolkits are designed to enhance workflows at all skill levels. ## Key Parameters - **Static Mesh Actor** — the placed instance form of a Static Mesh used to build level geometry; transformable (translate/rotate/scale) because meshes are cached in video memory. - **Skeleton asset** — the bone-data asset imported alongside a Skeletal Mesh; editable in the Skeleton Editor and shareable between meshes with the same or very similar skeleton structures (skeleton compatibility set via identical naming conventions). - **Mesh component** — the component on a Character Blueprint that hosts the Skeletal Mesh; exposes the **Skeletal Mesh** property and **Animation Mode** (`Use Animation Asset` + `Anim to Play`). - **Animation Blueprint / Anim Graph** — logic layer for dynamically selecting and blending Animation Sequences at runtime. - **LODs and morph targets** — a single FBX import can bring in multiple LODs and Morphs/Blendshapes in one operation, and Skeletal Meshes can be animated with morph targets (deformer techniques that transform mesh geometry rather than bones, for facial expressions, skin, cloth, or muscle movement). - **Modeling Mode** — in-editor tools for creating and editing 3D geometry. - **Geometry Scripting** — plugin providing modeling functions to Blueprints and Python for procedural mesh generation. ## When To Use - Use **Static Meshes** for the bulk of world/level geometry — environment pieces, props, and architecture that do not deform. - Use **Skeletal Meshes** for characters and any object whose geometry is driven by a skeleton or deformers; build a Character Blueprint (or use modular characters assembled from multiple skeletal mesh components) to control them at runtime. - Use **Modeling Mode** to block out, create, or edit geometry without leaving the editor. - Use **Geometry Scripting** when you need procedural or data-driven mesh generation from Blueprints or Python. ## Risks & Pitfalls - Skeletal Mesh assets depend on a correctly structured **Skeleton asset**; sharing animations across meshes requires compatible skeletons with identical naming conventions. - Modular characters assembled from multiple skeletal mesh components must be kept in sync so parts align in the level. - Morph-target (deformer) animation with large vertex deltas can produce normal artifacts on Skeletal Meshes (see the import pipeline notes for the skin-cache workaround). ## Related Concepts - [[concepts/content-import-pipeline]] - [[concepts/nanite-virtualized-geometry]] - [[concepts/materials-and-substrate]] - [[concepts/actors-and-components]] ## Sources - raw/content/static-meshes.md - raw/content/skeletal-mesh-assets-in-unreal-engine.md - raw/content/modeling-and-geometry-scripting-in-unreal-engine.md - raw/content/fbx-content-pipeline.md --- title: "Nanite Virtualized Geometry" type: concept tags: [rendering, nanite, geometry, optimization, performance] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/rendering/nanite-virtualized-geometry-in-unreal-engine.md"] confidence: high --- # Nanite Virtualized Geometry ## Definition Nanite is Unreal Engine's virtualized geometry system, which uses an internal mesh format and rendering technology to render pixel-scale detail and high object counts. It intelligently does work on only the detail that is visible on-screen and no more. Its data format is highly compressed and supports fine-grained streaming with automatic level of detail (LOD). The result is a multiple-orders-of-magnitude increase in geometry complexity: frame budgets are no longer constrained by polycounts, draw calls, or mesh memory usage, and film-quality source art (ZBrush sculpts, photogrammetry scans) can be imported directly instead of baked into normal maps. ## How It Works During import, meshes are analyzed and broken down into hierarchical clusters of triangle groups. During rendering, clusters are swapped on the fly at varying levels of detail based on the camera view and connect perfectly without cracks to neighboring clusters within the same object. Data is streamed in on demand so only visible detail needs to reside in memory. Nanite runs in its own rendering pass that completely bypasses traditional draw calls. Because it relies on rapidly streaming mesh data from disk on demand, Epic recommends solid-state drives (SSDs) for runtime storage. A Nanite mesh is just a Static Mesh with Nanite enabled — still a triangle mesh at its core, only with LOD and compression applied and rendered through Nanite's efficient pipeline. Move the camera close enough and Nanite draws the original source triangles that were imported. Nanite supports multiple UVs and vertex colors, per-section material assignments (which can be swapped dynamically with no bake step), and does not require Virtual Textures, though they are highly recommended. ## Key Parameters Nanite Project Settings are under `Engine > Rendering`, in the Nanite section. Per-asset Nanite settings live in each mesh's asset editor Details panel. Enabling Nanite: - **On import** — check the box for **Build Nanite**. When not using precomputed lighting with Lightmass, Epic recommends disabling **Generate Lightmap UVs**, since that adds an extra UV channel and significant data for dense meshes. - **Batched** — in the Content Browser, select assets, right-click and choose **Nanite > Enable**. - **Per-mesh** — in the Static Mesh Editor or Skeletal Mesh Editor, under **Nanite Settings**, check **Enable Nanite Support**; in the Geometry Collections Editor, under the **Nanite** section, check **Enable Nanite**. Converting geometry to Nanite requires processing time per mesh; a shared Derived Data Cache (DDC) helps on large projects. Key controls: - **Fallback Relative Error** (Static Mesh Editor) — lower this to use more of the source mesh's triangles in the Fallback Mesh (used where full-detail Nanite cannot be, e.g. ray tracing). - **Max World Position Offset Displacement** (material) — clamp WPO displacement to control how many clusters get culled. - `r.RayTracing.Nanite.Mode 1` — (Experimental) enables initial native ray-tracing of Nanite meshes, preserving detail while using far less GPU memory than zero-error Fallback Meshes. ## When To Use Nanite should generally be enabled wherever possible on platforms that support it — any mesh with it enabled typically renders faster and uses less memory and disk space. A mesh is an especially good candidate if it: contains many triangles or triangles that will be very small on screen; has many instances in the scene; acts as a major occluder of other Nanite geometry; or casts shadows using [[concepts/lighting-and-shadows|Virtual Shadow Maps]]. Nanite Static Meshes use no geometry LODs, scaling polygon count dynamically to screen resolution, and fully support Lumen GI/reflections. Nanite also supports Skeletal Meshes (one draw call per mesh, animation LODs instead of geometry LODs), landscapes, foliage, splines, and static displacement/tessellation. Nanite works on Static Meshes and Geometry Collections, and Nanite-enabled meshes can be used with Static Mesh, Skeletal Mesh, Instanced Static Mesh, Spline Mesh, Hierarchical Instanced Static Mesh, Geometry Collection, Foliage Painter, and Landscape Grass components. An exception where Nanite adds little is something like a sky sphere (large on-screen triangles, no occlusion, single instance) — but the performance loss there is minimal, so don't over-worry about where Nanite shouldn't be used. ## Risks & Pitfalls - **Instance cap:** the maximum number of instances streamed into a scene is hard-locked to **16 million** (counting all streamed-in instances, not just Nanite ones). - **Materials:** Nanite supports only **Opaque** and **Masked** Blend Modes; unsupported types get a default material plus an Output Log warning. Mesh Decals (which need Translucent blend) are not supported, the Wireframe checkbox is unsupported, and `Custom` expression nodes (e.g. `ParallaxOcclusionMapping`) may cause artifacts because Nanite lacks analytic derivative support. - **Deformation:** supports dynamic translation, rotation, and non-uniform scaling. WPO is supported but limited — meshes using WPO are split into smaller individually-culled clusters, so displacement must be clamped. **Morph Targets are not supported.** - **Per-vertex tangents** are not stored (tangent space is derived in the pixel shader), which can cause edge discontinuities. - **Unsupported rendering features:** view-specific filtering (Minimum Screen Radius, distance culling), Forward Rendering, stereo/VR rendering, MSAA, Lighting Channels, and ray-tracing against Nanite meshes (the Fallback Mesh is used by default; native ray-tracing is experimental via `r.RayTracing.Nanite.Mode 1`). - **Platforms:** requires current console/desktop platforms with DirectX 12 and Shader Model 6 (SM6) and latest drivers. ## Related Concepts - [[concepts/lumen-global-illumination]] - [[concepts/lighting-and-shadows]] - [[concepts/materials-and-substrate]] - [[syntheses/rendering-feature-map]] ## Sources - raw/rendering/nanite-virtualized-geometry-in-unreal-engine.md --- title: "Physics & Collision" type: concept tags: [physics, collision, chaos, traces, raycasts] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/gameplay/physics-in-unreal-engine.md", "raw/gameplay/traces-with-raycasts-in-unreal-engine.md", "raw/gameplay/actors-in-unreal-engine.md"] confidence: high --- # Physics & Collision ## Definition Physics and collision in Unreal Engine cover two related jobs: detecting spatial relationships between objects (collision and trace queries) and simulating the motion of bodies under forces and constraints (rigid-body and soft-body simulation). Simulation is powered by **Chaos Physics**, a light-weight physics solution built from the ground up for next-generation games. Collision geometry and settings live on primitive components, and queries against the world are run either as object queries or as trace-channel queries. ## How It Works **Where collision lives.** Collision settings belong to components. A `UPrimitiveComponent` is a `USceneComponent` that has a graphical representation of some kind (a mesh or particle system), and "many of the interesting physics and collision settings are here." A typical actor hierarchy pairs such a primitive with a collision volume — for example, a `BoxComponent` used as a trigger for an overlap event. **Trace queries (raycasts).** A **Trace** (or **Raycast**) shoots an invisible ray to detect geometry between two points and returns what was hit so you can act on it — for example, detecting whether the player is looking at something or whether an enemy can see the player. There are two ways to select what a trace reports: - **By Objects** — run a trace to check for collision with any objects, where hit objects are returned. - **By Trace Channel** — run a trace where any object hit returns hit information only if that object is set to specifically respond to the specified **Trace Channel**. This response is configured via **Collision Settings**. Traces can be run for **Single** hits (returns a singular hit result) or **Multi** hits (returns multiple hits from the trace). You also choose the shape of the swept ray: a **straight line**, a **box**, a **capsule**, or a **sphere** — making a "raycast" also serve as a box, capsule, or sphere sweep. **Simulation with Chaos.** Chaos Physics provides rigid-body dynamics including **collision responses, physics constraints, and damping and friction**, plus asynchronous physics simulation and networked physics. Related systems build on this base: - **Physics Constraints** constrain physics objects together and to the world. - **Physics Components** include the Physical Animation, Thruster, and Force components. - **Rigid Body Animation Nodes and Physical Animation** use the Physics Asset Editor to set up rigid bodies attached to a character's Skeletal Mesh, so they simulate alongside animation (including ragdoll physics). - **Chaos Destruction** uses **Geometry Collections** (built from one or more Static Meshes) that can be fractured for real-time destruction, with **Damage Thresholds** per cluster and **Connection Graphs** to control collapse. - **Physics Fields** affect Chaos simulations at runtime in a region of space — exerting force on rigid bodies, breaking Geometry Collection clusters, and anchoring or disabling fractured rigid bodies. **Networked physics.** In UE, physics replication means actors with replicated movement that simulate physics; these simulations run on the local client. Chaos provides three replication modes: - **Default** — the legacy mode, active on actors that replicate their movement and whose **root component** is set to **simulate physics**. - **Predictive Interpolation** — for server-authoritative actors; alters each object's velocity on the client to match the server's, handling local predictive alterations better than Default. - **Resimulation** — for server-authoritative pawns and actors; compares received server state against a cached physics history and triggers a physics resimulation when they differ enough, enabling physics pawns via client prediction. ## Key Parameters - **`UPrimitiveComponent`** — scene component with a graphical representation; holds the physics and collision settings. - **Trace by Objects vs. Trace by Trace Channel** — the two query modes; channel responses are set via Collision Settings. - **Single vs. Multi** trace — one hit result vs. multiple. - **Ray shapes** — straight line, box, capsule, sphere. - **Simulate physics** on the **root component** — the flag that puts an actor under rigid-body simulation (and drives Default replication). - **Replication modes** — `Default`, `Predictive Interpolation`, `Resimulation`. - **Chaos systems** — Chaos Destruction (Geometry Collections, Damage Thresholds, Connection Graphs), Physics Constraints, Physics Fields (World Field / Chaos Field), Chaos Vehicles, Chaos Cloth, Chaos Flesh. - **Chaos Visual Debugger (CVD)** — records and replays physics simulation state for inspection per frame or sub-step. ## When To Use Use **traces** when you need to answer a spatial question — line of sight, what the player is aiming at, what lies between two points — choosing an object query when you care about categories of objects, or a trace-channel query when objects should opt into responding to a specific channel. Use **shaped** traces (box, capsule, sphere) when a single line is too thin to represent the interaction. Set a body to **simulate physics** on its root component when you want Chaos rigid-body dynamics, and pick a replication mode by authority model — Default for simple replicated-movement bodies, Predictive Interpolation for server-authoritative actors, and Resimulation for server-authoritative physics pawns. Reach for Geometry Collections and Physics Fields for destruction and runtime physics influence. ## Risks & Pitfalls - A trace-channel query returns nothing for objects that aren't configured (via Collision Settings) to respond to that channel — the object must opt in. - Networked physics runs on the local client; choosing the wrong replication mode for your authority model leads to divergence between server and clients. Resimulation exists precisely because naive replication of simulated pawns is hard. - Simulating physics interacts with movement replication — only actors that replicate their movement and have a simulate-physics root component use the Default mode. - Cached destruction simulations can still be interactive, so treat "baked" destruction as potentially live on interaction. > Scope note: this page uses the collision terms present in the assigned sources > — Trace Channel, object query, Collision Settings, and simulate physics. The > specific per-channel collision-response keywords (Block / Overlap / Ignore) and > named collision channel enumerations are not spelled out in the assigned raw > material, so they are omitted rather than fabricated. ## Related Concepts - [[concepts/actors-and-components]] - [[concepts/gameplay-framework]] - [[concepts/meshes-and-modeling]] ## Sources - raw/gameplay/physics-in-unreal-engine.md - raw/gameplay/traces-with-raycasts-in-unreal-engine.md - raw/gameplay/actors-in-unreal-engine.md --- title: "Programming with C++ in Unreal Engine" type: concept tags: [cpp, gameplay, programming, uobject, actor] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/cpp/programming-with-cplusplus-in-unreal-engine.md", "raw/cpp/programming-with-cpp-in-unreal-engine.md", "raw/cpp/gameplay-classes-in-unreal-engine.md", "raw/cpp/using-the-cplusplus-class-wizard-in-unreal-engine.md", "raw/cpp/epic-cplusplus-coding-standard-for-unreal-engine.md"] confidence: high --- # Programming with C++ in Unreal Engine ## Definition Unreal Engine provides a framework for writing gameplay in C++ on top of a hierarchy of engine base classes. You write standard C++ classes, functions, and variables using standard C++ syntax, and then tag them with a small set of macros so the engine becomes aware of them. Each C++ class defines a template for a new Actor or Object, and every gameplay class is split across a header file (`.h`) that declares the class and its members and a source file (`.cpp`) that implements them. After you compile with Visual Studio or Xcode, all changes are reflected in the Unreal Editor. This section assumes you already have some experience with C++. ## How It Works Gameplay code is organized into **modules**, and each module can contain many C++ classes. Classes derive from Unreal's base classes and follow a standardized naming scheme so you can tell what kind of class something is from its prefix alone: - **`U`** — extends `UObject`, the base class of all gameplay objects. These cannot be instanced directly into the world; they must belong to an Actor, and are generally objects like [[concepts/actors-and-components|Components]]. - **`A`** — extends `AActor`, the base class of spawnable gameplay objects. Actors can be spawned directly into the world. Beyond `UObject` and `AActor`, the gameplay framework layers more specialized bases (for example `APawn` and its subclasses) that ship boilerplate variables and functions for interactive experiences — see [[concepts/gameplay-framework]]. The coding standard formalizes the prefixes: classes inheriting from `UObject` are prefixed by `U` (`class UActorComponent`), classes inheriting from `AActor` are prefixed by `A` (`class AActor`), Slate widget classes inheriting from `SWidget` are prefixed by `S`, abstract interface classes are prefixed by `I`, template classes are prefixed by `T`, enums are prefixed by `E`, and most other classes (plain structs) are prefixed by `F`. Unreal Header Tool requires the correct prefixes in most cases. Standard C++ classes work fine, but the `UCLASS()`, `UFUNCTION()`, and `UPROPERTY()` macros make the engine aware of your classes, functions, and variables. A variable declared with `UPROPERTY()` can be garbage collected by the engine and displayed and edited in the Unreal Editor. There are also `UINTERFACE()` and `USTRUCT()` macros, plus a `UPARAM()` macro used primarily when exposing C++ to Blueprints. This reflection layer is detailed in [[concepts/unreal-reflection-system]]. A gameplay class header includes its generated header at the top — `#include "ClassName.generated.h"` — and places the `GENERATED_BODY()` macro at the very beginning of the class body. `UObject`s use **constructors** to set default values on the Class Default Object (CDO), the master copy from which future instances are cloned. ## Key Parameters - **C++ Class Wizard** — the fast, easy way to add native C++ code classes. In the main editor, select **Tools > New C++ Class...**. The wizard shows **Common Classes** by default; select **All Classes** to see the full hierarchy. Choose a class (for example, `Actor`), click **Next >**, enter a **Name**, then click **Create Class**. This creates the header (`.h`) and source (`.cpp`) files, sets up the `UCLASS()` macro and constructor, and updates your game module accordingly. Class names may contain only alphanumeric characters and no spaces. Creating a class this way converts a content-only project into a code project. - **Live Coding** — now enabled by default. When you create a class, a Live Coding window appears and compiles the new files, after which the code opens in Visual Studio (or Xcode) ready for editing. - **`GENERATED_BODY()`** — required macro placed at the start of every gameplay class body so the class is implemented properly. - **Coding standard highlights** — U.S. English spelling; PascalCase with the first letter of each word capitalized and usually no underscores between words; boolean variables must be prefixed by `b` (for example `bPendingDestruction`, `bHasFadedIn`); macro names should be fully capitalized with underscores and prefixed with `UE_`; type and variable names are nouns while method names are verbs; boolean-returning functions should ask a true/false question such as `IsVisible()` or `ShouldClearBuffer()`; and out-parameters passed by reference should be prefixed with `Out`. ## When To Use Reach for C++ when you need performance-critical logic, access to engine systems not exposed to visual scripting, or a reusable native base class that designers extend in [[concepts/blueprints-visual-scripting|Blueprints]]. Structs (`USTRUCT()`) organize related properties, interfaces (`UINTERFACE()`) add shared gameplay behavior across different classes, and delegates let you call member functions on C++ objects in a generic, type-safe way. The trade-offs against visual scripting are covered in [[syntheses/blueprints-vs-cpp]]. ## Risks & Pitfalls - Forgetting `#include "ClassName.generated.h"` at the top of the header, or omitting `GENERATED_BODY()`, breaks code generation. - Using the wrong class prefix will fail Unreal Header Tool's expectations. - Component pointers created in a constructor must be stored in a `UPROPERTY` of the owning class so they are created, destroyed, and garbage-collected correctly. - Metadata only exists in the editor; do not write game logic that accesses metadata. ## Related Concepts - [[concepts/unreal-reflection-system]] - [[concepts/actors-and-components]] - [[concepts/gameplay-framework]] - [[concepts/blueprints-visual-scripting]] - [[syntheses/blueprints-vs-cpp]] ## Sources - raw/cpp/programming-with-cplusplus-in-unreal-engine.md - raw/cpp/programming-with-cpp-in-unreal-engine.md - raw/cpp/gameplay-classes-in-unreal-engine.md - raw/cpp/using-the-cplusplus-class-wizard-in-unreal-engine.md - raw/cpp/epic-cplusplus-coding-standard-for-unreal-engine.md --- title: "The Unreal Editor & Project Structure" type: concept tags: [project-structure, directories, plugins, uproject, workflow] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/basics/unreal-engine-directory-structure.md", "raw/basics/unreal-engine-terminology.md", "raw/basics/working-with-plugins-in-unreal-engine.md", "raw/basics/tools-and-editors-in-unreal-engine.md", "raw/basics/content-browser-in-unreal-engine.md"] confidence: high --- # The Unreal Editor & Project Structure ## Definition An Unreal Engine project holds all the contents of your game as a set of folders on disk, paired with a `.uproject` file that is how you create, open, or save the project. The [[entities/unreal-editor|Unreal Editor]] is the application you use to edit that project: the Content Browser panel inside the editor shows the same directory structure found inside the project folder on disk. On disk, the top level holds the shared `Engine` directory (the engine and all its tools) alongside one directory per game project, each containing only that project's files. ## How It Works At the root there is the `Engine` directory plus any game projects. The `Engine` directory contains all source code, content, and tools that make up the engine. Notable root files include `GenerateProjectFiles.bat` (creates the Visual Studio solution and project files) and `Default.uprojectdirs` (lets the engine discover projects in subdirectories); a `Templates` directory holds the project templates available when creating new projects. Several subdirectories are **common** to both the Engine and game directories: - **Binaries** — executable and other files created during compiling. - **Build** — files needed for building, including platform-specific builds. - **Config** — configuration files controlling engine behavior. Values in a game project's Config files override the values set in `Engine\Config`. - **Content** — asset packages and maps. A `Content` directory can exist both in the engine (`../Engine/Content`) and in your game (`../GAME_DIR/Content`); engine content is accessible by any project on that distribution, while game content is only accessible within that game. - **DerivedDataCache** — derived data generated on-load for referenced content; missing cache can increase load times dramatically. - **Intermediate** — temporary files generated during building; can be deleted and rebuilt. In game directories, Shaders are stored here. - **Plugins** — plugins used in the engine. - **Saved** — autosaves, configuration (`.ini`) files, and logs. - **Source** — all source files for the engine or game. In a **game project's Source**, files are organized by module (one directory per module). Each module contains `Classes` (gameplay class header `.h` files — not to be added to in the future), `Internal` (cross-module includes within the same plugin or module), `Private` (source `.cpp` files, including gameplay class implementations and the module implementation), and `Public` (the module header file). **The editor workflow.** By default, opening or creating a project opens the Level Editor, the primary editor for building levels. From there you open specialized editors (Material Editor, Blueprint Editor, and so on) as needed, and manage all Assets through the Content Browser, the primary area for creating, importing, organizing, viewing, and managing content. See [[concepts/unreal-terminology-and-conventions|terminology and conventions]] for the Actor, Level, and World vocabulary the editor operates on. ## Key Parameters - **`.uproject`** — the per-project file used to create, open, or save a project. - **`.uplugin`** — a plugin's descriptor file; plugins contain their own source files, binaries, and a `.uplugin` file. - **`*.Build.cs`** — the build script that defines a module. When you create a project, its source code is organized into a module with a `*.Build.cs` file. - **`Config\*.ini`** — configuration files; game-project values override `Engine\Config`. - **Plugin install locations** — Unreal stores plugins at `C:\Program Files\Epic Games\UE_[version]\Engine\Plugins` on Windows and `/Users/Shared/Epic Games/UE_[version]/Engine/Plugins` on macOS. **Modules vs plugins.** Both organize engine functionality, but a **module** only contains code, while a **plugin** contains its own source files, binaries, and a `.uplugin` file — and can also contain assets, which modules cannot. Because a plugin is self-contained, you can redistribute it to use in other UE projects. A plugin is an optional component that adds functionality without modifying the engine code directly; you enable or disable plugins independently for each project. To enable one, go to **Edit > Plugins**, find or search for the plugin, click the checkbox next to it, then save your work and restart Unreal Engine. Disabling follows the same path (clear the checkbox); if the plugin is a dependency for others, you are warned, and disabling it may break existing functionality. ## When To Use - Reach for **project structure** knowledge when deciding what to commit to source control (Binaries, Intermediate, DerivedDataCache, and Saved are generated and can be rebuilt) or when Config overrides behave unexpectedly. - Use a **plugin** when you want redistributable, self-contained functionality (code plus assets) that can be toggled per project; use a **module** for code-only organization within a single project. - Enable/disable plugins through **Edit > Plugins** whenever a feature or editor you need is optional rather than built in. ## Risks & Pitfalls - Game-project Config values silently **override** `Engine\Config`, so an unexpected setting may originate from the project rather than the engine. - Deleting `DerivedDataCache` is safe but can dramatically increase the next load's time while the cache regenerates. - Disabling a plugin that other plugins **depend on** can break functionality you built with those plugins. - Enabling or disabling a plugin requires **saving and restarting** the editor to take effect. - The `Classes` directory (gameplay class headers) "should not be added to in the future" per Epic's own structure guidance — prefer `Public`/`Private`. ## Related Concepts - [[concepts/unreal-terminology-and-conventions]] - [[entities/unreal-editor]] - [[entities/unreal-engine]] - [[concepts/programming-with-cpp]] - [[concepts/content-import-pipeline]] ## Sources - raw/basics/unreal-engine-directory-structure.md - raw/basics/unreal-engine-terminology.md - raw/basics/working-with-plugins-in-unreal-engine.md - raw/basics/tools-and-editors-in-unreal-engine.md - raw/basics/content-browser-in-unreal-engine.md --- title: "The Unreal Reflection System (UCLASS/UPROPERTY/UFUNCTION)" type: concept tags: [reflection, uclass, uproperty, ufunction, garbage-collection] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/cpp/reflection-system-in-unreal-engine.md", "raw/cpp/programming-with-cpp-in-unreal-engine.md", "raw/cpp/gameplay-classes-in-unreal-engine.md", "raw/cpp/metadata-specifiers-in-unreal-engine.md"] confidence: high --- # The Unreal Reflection System (UCLASS/UPROPERTY/UFUNCTION) ## Definition The Unreal Engine Reflection System encapsulates your classes with a set of macros that give them engine and editor functionality on top of standard C++. The base class for objects in Unreal is `UObject`, and each class defines a template for a new Actor or Object. You tag classes derived from `UObject` with the `UCLASS` macro so the UObject handling system becomes aware of them, and you tag functions and variables with `UFUNCTION` and `UPROPERTY` so the engine can manage, display, and edit them. These reflected members are garbage collected by the engine, and can be edited and displayed within the Unreal Editor. ## How It Works Reflection is driven by macros processed at build time. The main ones are: - **`UCLASS`** — tags a `UObject`-derived class so the engine's UObject handling system knows about it and can build its `UClass` (the engine's specialized representation of the class). - **`USTRUCT()`** — defines a struct as a reflected data structure. Structs help organize and manipulate related member properties and can be defined on their own. - **`UENUM`** — reflects an enumerated type (for example `enum class EMyEnum : uint8`). - **`UPROPERTY`** — reflects a member variable so it can be garbage collected, serialized, replicated, and shown in the editor. - **`UFUNCTION`** — reflects a member function, enabling editor/Blueprint exposure and other engine behavior. - **`UINTERFACE()`** — reflects an interface. Interfaces provide functions and additional gameplay behavior you can implement in multiple or different classes. A reflected class header includes its generated header (`#include "ClassName.generated.h"`) and places `GENERATED_BODY()` at the very beginning of the class body. The declaration syntax passes optional specifiers and metadata to the macro: ``` UCLASS([specifier, specifier, ...], [meta(key=value, key=value, ...)]) class ClassName : public ParentName { GENERATED_BODY() } ``` Supporting types round out the system: `TSubclassOf` is a template class that provides `UClass` type safety (useful for exposing "which class to spawn" to Blueprint designers); the Unreal Smart Pointer Library is a custom implementation of C++11 smart pointers (Shared Pointers, Weak Pointers, Unique Pointers, and Shared References, which act like non-nullable Shared Pointers). **Garbage collection & UPROPERTY:** the engine garbage-collects objects reached through reflected properties. A pointer to every component created in a constructor should be stored in a `UPROPERTY` of the owning class to ensure components are always created, destroyed, and properly garbage-collected. ## Key Parameters Metadata Specifiers control how classes, interfaces, structs, enums, functions, or properties interact with the engine and editor; each type has its own list. Add them with the `meta` keyword: ``` {UCLASS/UENUM/UINTERFACE/USTRUCT/UFUNCTION/UPROPERTY}(SpecifierX, meta=(MetaTag1="Value1", MetaTag2, ..), SpecifierY) ``` Individual enum values instead use the top-level `UMETA` tag placed after the value. Commonly used **UCLASS** specifiers include: - `Blueprintable` — exposes the class as an acceptable base class for creating Blueprints. The default is `NotBlueprintable` unless inherited otherwise; inherited by subclasses. - `BlueprintType` — exposes the class as a type usable for variables in Blueprints. - `Abstract` — declares an "abstract base class", preventing users from adding Actors of this class to Levels. - `Config=ConfigName` — allows the class to store data in a configuration file (`.ini`). Common `ConfigName` values are "Engine", "Editor", "Input", and "Game". - `Transient` — objects of this class are never saved to disk. Widely used **property/function metadata and specifiers** (verbatim) include: - `EditAnywhere` / `BlueprintReadWrite` — the standard specifiers for exposing a property to editing in details panels and to reading/writing from Blueprints. (Behavioral note: these two canonical specifiers are referenced widely across UE but are not defined in the metadata-specifier tables cited here.) - `EditFixedOrder` — keeps the elements of an array from being reordered by dragging. - `EditCondition="BooleanPropertyName"` — names a boolean property used to indicate whether editing of this property is disabled ("!" before the name inverts the test); now evaluated with a full C++ expression parser. - `Category` — groups the property in the editor. Categories are referenced by many class specifiers such as `HideCategories`, `ShowCategories`, and `AutoExpandCategories`. - `ClampMin="N"` / `ClampMax="N"` — minimum/maximum value for float and integer properties. - `DisplayName="Property Name"` — the name to display instead of the code-generated name. - `ExposeOnSpawn="true"` — exposes the property on a Spawn Actor node for this class type. - `BlueprintCallable`, `BlueprintPure`, `DeprecatedFunction`, `WorldContext="Parameter"` — common function-level behaviors. - `BlueprintSpawnableComponent` — class metadata; if present, the component class can be spawned by a Blueprint. ## When To Use Use the reflection macros whenever a class, property, or function must be visible to the editor, garbage collector, serialization, networking, or [[concepts/blueprints-visual-scripting|Blueprints]]. Plain C++ that never interacts with those systems does not need the macros. For the full Blueprint-versus-C++ trade-off, see [[syntheses/blueprints-vs-cpp]]. ## Risks & Pitfalls - Metadata only exists in the editor; do not write game logic that accesses metadata. - Object references not held in a `UPROPERTY` are invisible to the garbage collector and can be collected out from under you. - Missing `#include "*.generated.h"` or a misplaced `GENERATED_BODY()` breaks the generated boilerplate. ## Related Concepts - [[concepts/programming-with-cpp]] - [[concepts/actors-and-components]] - [[concepts/blueprints-visual-scripting]] - [[syntheses/blueprints-vs-cpp]] ## Sources - raw/cpp/reflection-system-in-unreal-engine.md - raw/cpp/programming-with-cpp-in-unreal-engine.md - raw/cpp/gameplay-classes-in-unreal-engine.md - raw/cpp/metadata-specifiers-in-unreal-engine.md --- title: "Unreal Terminology, Units & Coordinate System" type: concept tags: [terminology, actor, units, coordinate-system, conventions] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/basics/unreal-engine-terminology.md", "raw/basics/units-of-measurement-in-unreal-engine.md", "raw/basics/coordinate-system-and-spaces-in-unreal-engine.md"] confidence: high --- # Unreal Terminology, Units & Coordinate System ## Definition This page collects the core vocabulary, measurement units, and spatial conventions you need before working in [[entities/unreal-engine|Unreal Engine]]. In short: the building blocks of a project are Objects, Actors, and Components; content lives in Levels held by a World; the default unit of distance is the centimeter (1 unit = 1 cm); and space is a left-handed, Z-up Cartesian coordinate system. Getting these right up front prevents scaling and orientation surprises, especially when importing from other tools. ## How It Works **Core terminology.** In C++, a class is a code template of variables and behavior that can be extended; a subclass inherits from a parent. The key gameplay types: - **Object** — the most basic class; almost everything inherits from it. In C++, `UObject` is the base class of all objects and implements garbage collection, metadata (`UProperty`) support for exposing variables to the editor, and serialization. - **Class** — defines the behaviors and properties of an Actor or Object; hierarchical and creatable in C++ or [[concepts/blueprints-visual-scripting|Blueprints]]. - **Actor** — any object that can be placed into a Level (a Camera, static mesh, player start, and so on). Actors support translation, rotation, and scaling, and can be spawned or destroyed through gameplay code. In C++, `AActor` is the base class of all Actors. - **Component** — a piece of functionality added to an Actor (for example, a Spot Light Component, Rotating Movement Component, or Audio Component). Components must be attached to an Actor and cannot exist by themselves. - **Pawn** — a subclass of Actor that serves as an in-game avatar; can be controlled by a player or AI. A controlled Pawn is **Possessed**; otherwise **Unpossessed**. - **Character** — a subclass of Pawn intended as a player character, including a collision setup, input bindings for bipedal movement, and player-controlled movement code. - **Level** — a gameplay area containing everything a player can see and interact with. Unreal saves each Level as a separate `.umap` file, which is why Levels are sometimes called **Maps**. - **World** — a container for all the Levels that make up your game; it handles Level streaming and the spawning of dynamic Actors. Other common terms: **Blueprint** (a node-based visual scripting system, and colloquially the objects defined with it), **Casting** (treating an Actor of one class as another; succeeds or fails), **Brush** (a BSP Actor describing a 3D shape, useful for blocking out levels), and **Volume** (a bounded 3D space such as a Blocking Volume, Pain Causing Volume, or Trigger Volume). See [[concepts/gameplay-framework|the gameplay framework]] for Player Controller, AI Controller, Player State, Game Mode, and Game State. **Units of measurement.** Unreal defaults to International System (SI) units. The most load-bearing default: **distance/length is centimeters (cm)** — so 1 Unreal unit (uu) equals 1 cm. Full defaults: | Quantity | Default Unit | | --- | --- | | Distance/Length | Centimeters (cm) | | Mass | Kilograms (kg) | | Time | Minutes (min), Seconds (s) | | Angles | Degrees (deg) | | Speed/Velocity | Meters per Second (m/s) | | Temperature | Celsius (C) | | Force | Newtons (N) | | Torque | Newton Meters (N·m) | You can change these under **Edit > Project Settings... > Editor > Appearance**, then expand **Units > Advanced** and pick a new unit from the dropdown next to each quantity. Distance/Length, Mass, and Time can use compound units. **Coordinate system.** Unreal uses a Cartesian coordinate system in three-dimensional Euclidean space that is **left-handed and Z-up**. Axis colors and directions in the editor: - **X-axis: Red** — forward/backward; positive values are forward. - **Y-axis: Green** — left/right; positive values are to the right. - **Z-axis: Blue** — up/down; positive values are upwards. The **origin** is the point `(0, 0, 0)` where the axes intersect. It is "left-handed" because the cross product and axes follow the left-hand rule. To locate `(2, 1, -3)`: travel 2 units forward on +X, 1 unit right on +Y, and 3 units down on -Z. **Coordinate spaces.** Each space has its own origin: - **World space** — the fixed coordinate system for the entire level; origin is the center of the scene (world grid). You cannot transform it. - **Local space** (object space) — relative to the scene component the Actor is attached to, centered on the Actor's pivot point. - **Screen space** — the projection of 3D world space onto the 2D screen. - **UV space** — a normalized (0-1) 2D parameterization (U horizontal, V vertical) of a 3D surface mesh; also called texture space. - **Instance and particle space** — relative to an instanced static mesh (ISM) component or particle emitter; provides per-instance transform. ## Key Parameters - **1 uu = 1 cm** — the default distance scale; assume centimeters unless changed. - **`AActor`** — base C++ class of all Actors; **`UObject`** — base C++ class of all objects; **`UProperty`** — metadata that exposes variables to the editor. - **`.umap`** — the file each Level is saved as (hence "Map"). - **Left-handed, Z-up** — the handedness and up-axis to match when importing. - **Axis colors** — X Red, Y Green, Z Blue. - **Move (W) / Rotate (E) / Scale (R)** — the transform gizmos, color-matched to the axes. ## When To Use - Confirm the **1 uu = 1 cm** scale whenever sizing geometry or reading physics values. - Check **handedness and up-axis** before importing from Maya, Houdini, ZBrush, Blender, or 3ds Max — those tools use different up-axes and handedness. - Choose the right **coordinate space** for a transform: world space for absolute/level-relative placement, local space to transform relative to a parent. ## Risks & Pitfalls - Importing from other DCC tools without accounting for Unreal's **left-handed, Z-up** convention causes mirrored or misoriented assets. - Changing default **units** in Project Settings alters how values are displayed and entered across the project — coordinate expectations shift with it. - **Casting** can fail; code that assumes a successful cast will not access the target class's functionality when the cast returns nothing. - A **Component** cannot exist without an Actor to attach to. ## Related Concepts - [[concepts/unreal-editor-and-projects]] - [[concepts/actors-and-components]] - [[concepts/gameplay-framework]] - [[entities/unreal-editor]] - [[entities/unreal-engine]] ## Sources - raw/basics/unreal-engine-terminology.md - raw/basics/units-of-measurement-in-unreal-engine.md - raw/basics/coordinate-system-and-spaces-in-unreal-engine.md --- title: "Unreal Editor" type: entity tags: [unreal-editor, content-browser, viewport, tools, ui] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/basics/tools-and-editors-in-unreal-engine.md", "raw/basics/content-browser-in-unreal-engine.md", "raw/basics/content-browser-interface-in-unreal-engine.md", "raw/basics/coordinate-system-and-spaces-in-unreal-engine.md", "raw/basics/unreal-engine-terminology.md"] confidence: high --- # Unreal Editor ## Overview The Unreal Editor is the authoring application for [[entities/unreal-engine|Unreal Engine]]. It is where you assemble levels, import and manage content, script behavior, and test your project. The editor is not one window but a family of tools and specialized editors sharing a common frame. By default, when you create or open a project, Unreal Engine opens the **Level Editor**, the primary editor for constructing gameplay levels by placing Actors and Geometry, Blueprints, Niagara effects, and more. Unreal distinguishes three terms the editor is built from: a **tool** performs a specific task (like placing Actors or painting terrain); an **editor** is a collection of tools for something more complex (like the Level Editor or the Material Editor); and a **system** is a large collection of features that work together (like Blueprint, used to visually script gameplay). Some tools and editors are built in, while others come as optional [[concepts/unreal-editor-and-projects|plugins]] you enable per project. ## Characteristics **Main panels and areas.** The Level Editor's key panels are: - **Viewport** — the 3D scene view where you place and transform Actors. Each Viewport shows a gizmo icon in the lower-left corner indicating the positive direction of the X (red), Y (green), and Z (blue) axes relative to your view. Transform controls are color-coordinated to match the axes: the **Move Tool (W)**, **Rotate Tool (E)**, and **Scale Tool (R)**. A globe/cube icon near the top-right toggles between world space and local space. Orthographic Viewports include Perspective (3D), Front (X-Axis), Side (Y-Axis), and Top (Z-Axis). - **Content Browser** — the primary area for creating, importing, organizing, viewing, and managing content Assets (detailed under How to Use below). - **Details** — where you view and edit the properties of the currently selected Actor or object. - **Outliner** — the hierarchical list of everything placed in the current Level. **Specialized editors.** UE5 ships many editors, each for a class of Asset: - **Level Editor** — build gameplay levels. - **Static Mesh Editor** — preview look, collision, UV mapping, and set LODs for [[concepts/meshes-and-modeling|Static Meshes]]. - **Material Editor** — create and edit [[concepts/materials-and-substrate|Materials]]. - **Blueprint Editor** — work with [[concepts/blueprints-visual-scripting|Blueprints]]. - **Physics Asset Editor** — create Physics Assets for Skeletal Meshes. - **Behavior Tree Editor** — script AI through a visual node-based system. - **Niagara Editor** — create particle effects from modular emitters. - **UMG (Unreal Motion Graphics) UI Editor** — author UI such as HUDs and menus. - **Sequencer Editor** — create in-game cinematics with a multi-track editor. - **Animation Editor** and **Control Rig Editor** — edit and rig animation assets. - **Font Editor**, **Sound Cue Editor**, **Media Editor**, **nDisplay 3D Config Editor**, and **DMX Library Editor** round out the set. ## How to Use **Open the Content Browser.** There are three ways: from the **Window** menu in the top menu bar, from the **Create** menu on the Main Toolbar, or by clicking the **Content Drawer** button on the bottom toolbar. The Content Drawer is a special instance that opens temporarily and minimizes when it loses focus; open it quickly with **Ctrl + Space Bar** (Windows) or **Cmd + Space Bar** (macOS), and click **Dock in Layout** to keep it. By default the Content Browser docks along the bottom of the window; you can re-dock, float it, or right-click its tab and select **Move to Sidebar**. You can open up to four instances at once. **Navigate the Content Browser.** Its interface is divided into seven areas: 1. **Navigation Bar** — Asset control buttons (**Add**, **Import**, **Save All**), history Back/Forward buttons, and a breadcrumb trail path. 2. **Sources Panel** — a hierarchical Asset Tree of all folders in the project, behaving like Windows Explorer or macOS Finder. Prefix search text with a hyphen (`-`) to exclude folders (for example, `-anim` hides folders named Animation or Animator). 3. **Collections** — group Assets into private, local, or shared collections. 4. **Filters** — click a filter to enable or disable it. 5. **Search Bar** — filter Assets by name in real time; save a search as a filter or Collection. 6. **Asset View** — shows all Assets in the selected folder or Collection. Drag and drop Assets directly into the Level, or right-click for a context menu to create and import Assets. 7. **Settings Button** — adjust View style (**Tiles**, **Lists**, or **Columns**), search filters, and content to include or exclude. **Work in a Viewport.** Select an Actor, then press **W**/**E**/**R** to move, rotate, or scale it. To temporarily move an Actor's pivot, hover where you want the pivot and use **ALT + MMB** (Middle Mouse Button); to set it permanently, right-click and choose **Pivot > Set as Pivot Offset**. To visualize an Actor in screen space, right-click it and select **Pilot** to fly its camera. ## Related Entities - [[entities/unreal-engine]] — the platform this editor authors content for. - [[concepts/unreal-editor-and-projects]] — how projects, directories, and plugins are organized behind the editor. - [[concepts/unreal-terminology-and-conventions]] — the Actors, Levels, and spaces the editor manipulates. - [[concepts/content-import-pipeline]] — importing Assets into a project. ## Sources - raw/basics/tools-and-editors-in-unreal-engine.md - raw/basics/content-browser-in-unreal-engine.md - raw/basics/content-browser-interface-in-unreal-engine.md - raw/basics/coordinate-system-and-spaces-in-unreal-engine.md - raw/basics/unreal-engine-terminology.md --- title: "Unreal Engine" type: entity tags: [unreal-engine, platform, editor, cpp, blueprints] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/basics/understanding-the-basics-of-unreal-engine.md", "raw/basics/install-unreal-engine.md", "raw/basics/tools-and-editors-in-unreal-engine.md", "raw/basics/unreal-engine-directory-structure.md"] confidence: high --- # Unreal Engine ## Overview Unreal Engine (UE) is a real-time 3D creation platform for building games and applications. The current major generation is Unreal Engine 5 (UE5). It combines an authoring application, the [[entities/unreal-editor|Unreal Editor]], with a runtime that executes your content, so you build, test, and package from a single toolset. A project can be scripted two ways: in C++ through the engine's gameplay classes, or visually with [[concepts/blueprints-visual-scripting|Blueprint Visual Scripting]], a node-based system that creates gameplay elements without writing C++. Most projects mix both. Unreal is delivered as two cooperating halves that live side by side in its directory structure. The `Engine` directory contains all source code, content, and tools that make up the engine itself; each game project you create sits in its own directory alongside it and holds only the files for that project. Functionality is organized into many modules and plugins, so features can be enabled per project rather than shipped as one monolith. To learn what you can build and where to go next, new users are pointed at three foundations: the Unreal Editor interface, Blueprint visual scripting, and the types of content (Assets) you can use inside a project. ## Characteristics - **Editor plus runtime.** The Unreal Editor is where you construct content; the engine runtime executes it. By default, opening or creating a project opens the [[concepts/unreal-editor-and-projects|Level Editor]], the primary editor for building gameplay levels. - **Two scripting paths.** Gameplay can be authored in C++ or in Blueprints. Blueprints let you control Actors, script events, modify Materials, and implement many engine features without writing any C++ code. - **Real-time 3D.** Unreal uses a Cartesian coordinate system to represent positions in three-dimensional Euclidean space, with a left-handed, Z-up convention (see [[concepts/unreal-terminology-and-conventions|terminology, units, and coordinate system]]). - **Modular tools and editors.** Beyond the Level Editor, UE ships specialized editors such as the [[entities/unreal-editor|Material Editor, Blueprint Editor, Niagara Editor, and Sequencer]]. Some tools are built in; others come as optional plugins you enable or disable per project. - **Cross-platform targets.** During installation you can add a **Target Platform** component that supplies source code to develop for platforms such as Android, iOS, Linux, and TVOS. These platforms require additional SDKs. Console development requires a source-code build of the engine from GitHub rather than the pre-compiled Launcher version. - **Content organized as Assets.** Any piece of content in a project is called an Asset, managed through the [[entities/unreal-editor|Content Browser]]. ## How to Use **Install the engine.** You only need the Epic Games Launcher to install Unreal. 1. Access the **Download Unreal Engine** page and click **Download Launcher** to get the installer, then run the Setup Wizard. 2. Open the **Epic Games Launcher** and sign in with an Epic Games account (you must be signed in to download the engine). 3. Click **Unreal Engine** in the left-hand navigation panel, then the **Library** tab. Click the **Add (+)** button next to **ENGINE VERSIONS** to add an engine tile. By default the latest version is selected; use the version dropdown to pick an older version if needed. 4. Click **Install** on the tile, accept the Pricing options and the End User License Agreement, choose an install location, and (optionally) click **Options** to select components. **Core Components** are required; optional components include **Starter Content**, **Templates and Feature Packs**, **Engine Source**, **Editor symbols for debugging**, and **Target Platform**. 5. When installation completes, click **Launch** on the engine tile. Additional software may be needed depending on your role, including Microsoft Visual Studio (for C++), and mobile or console platform SDKs. **Create a project.** Unreal projects hold the contents of anything you build. Use templates as starting points; two of the basic templates set up a first-person or third-person experience. Every project has a `.uproject` file, which is how you create, open, or save it (see [[concepts/unreal-editor-and-projects|project structure]]). **Keep the engine current.** A **HotFix** update is a targeted release of bug and crash fixes, identified by its third decimal value (for example 5.5.0 -> 5.5.1 -> 5.5.2). When one is available, the engine tile's **Launch** button becomes an **Update** button. You can install multiple engine versions side by side (back to Unreal Engine 4.0), but only one of each version at a time. ## Related Entities - [[entities/unreal-editor]] — the editor application you use to build content. - [[concepts/unreal-editor-and-projects]] — project and directory structure, plus the editor workflow. - [[concepts/unreal-terminology-and-conventions]] — Actors, Levels, Worlds, units, and the coordinate system. - [[concepts/blueprints-visual-scripting]] — the node-based scripting system. - [[concepts/programming-with-cpp]] — the C++ path for gameplay code. ## Sources - raw/basics/understanding-the-basics-of-unreal-engine.md - raw/basics/install-unreal-engine.md - raw/basics/tools-and-editors-in-unreal-engine.md - raw/basics/unreal-engine-directory-structure.md --- title: "Blueprints vs C++: which to use" type: synthesis tags: [blueprints, cpp, workflow, gameplay, decision] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/blueprints/blueprints-visual-scripting-in-unreal-engine.md", "raw/cpp/programming-with-cplusplus-in-unreal-engine.md", "raw/cpp/gameplay-classes-in-unreal-engine.md", "raw/gameplay/gameplay-framework-in-unreal-engine.md"] confidence: high --- # Blueprints vs C++: which to use Unreal Engine gives you two ways to author gameplay logic on top of the same class hierarchy: **Blueprint Visual Scripting**, a node-based system inside Unreal Editor, and **C++**, compiled through Visual Studio or Xcode. They are not rival engines — they are two front ends onto the same [[concepts/gameplay-framework|Gameplay Framework]] classes, and the standard answer for most projects is "both." This page compares them so you can decide which layer a given piece of work belongs in. ## Comparison | Dimension | [[concepts/blueprints-visual-scripting]] | [[concepts/programming-with-cpp]] | | --- | --- | --- | | Authoring surface | Node graph inside Unreal Editor | Header (`.h`) + source (`.cpp`) files, standard C++ syntax | | Who it targets | Designers and artists; "the full range of concepts and tools generally only available to programmers" | Programmers with existing C++ experience | | Iteration loop | Edit graph, hit play — no compile step outside the editor | Edit code, compile in Visual Studio/Xcode; changes reflected in editor after compile | | Execution | Runs on a virtual machine (interpreted graph) | Native compiled code | | Reach | Extends systems exposed to Blueprints via markup | Full engine API; can create baseline systems designers then extend | | Defining new classes | Derives from any `Blueprintable` C++ base class | `UCLASS()` + `GENERATED_BODY()`, `A` prefix (Actors) / `U` prefix (other `UObject`s) | | Assets | Hardcoded asset references discouraged; Blueprints are the *preferred* place to configure asset properties | Supports `ConstructorHelpers::FObjectFinder` / `FClassFinder`, but references are "brittle" | | Source control / diffs | Binary assets, hard to merge | Text, mergeable and reviewable | | Interop direction | Consumes what C++ exposes | Exposes to Blueprints via specifiers/metadata | ## Analysis **The interop layer is the whole story.** C++ classes decide what designers can touch through **class specifiers** and **metadata** declared on the `UCLASS()`. `Blueprintable` "exposes this class as an acceptable base class for creating Blueprints" (the default is `NotBlueprintable`), and `BlueprintType` "exposes this class as a type that can be used for variables in Blueprints." At the member level, programmers expose functions and properties with markup so designers can call and tune them. Metadata such as `BlueprintSpawnableComponent`, `DisplayName`, and `ToolTip` further shapes how the C++ surface appears in graphs. This is the intended division of labor: "programmers create baseline systems that can be extended by designers." **Iteration speed favors Blueprints; performance and reach favor C++.** A Blueprint change is live the moment you press play — there is no external compile — which is why rapid prototyping, per-actor tuning, and design-owned behavior tend to live there. C++ runs as native compiled code and reaches the full engine API, so performance-critical inner loops, large systems, and anything that must be shared as a reusable base class belong there. Blueprint graphs execute on a virtual machine, so hot per-frame logic (tight loops, math-heavy tick work) is measurably cheaper moved to C++. **Assets and configuration.** The gameplay-classes guidance is explicit that hardcoded asset references in C++ are brittle and that "the preferred method is to use Blueprints for configuring asset properties." A common, robust pattern is a C++ base class that declares behavior and exposes tunable `UPROPERTY` values, with a Blueprint child that wires up meshes, sounds, and parameters. This keeps content choices in a designer-friendly, per-instance place while logic stays in reviewable code. **Team roles.** Blueprints let designers "use virtually the full range of concepts and tools generally only available to programmers" without writing C++, while C++ assumes existing C++ experience. On mixed teams this maps cleanly: engineers own systems and shared base classes; designers own the Blueprint subclasses and data. ## Recommendations - **Prefer C++ when:** the logic is performance-sensitive or runs every frame; it is a foundational system many other classes derive from; it needs the full engine API; or you want text-based diffs and code review. Define such classes with `UCLASS()`/`GENERATED_BODY()` and mark them `Blueprintable`/`BlueprintType` if designers should extend them. - **Prefer Blueprints when:** you are prototyping, iterating on feel, wiring up assets, or handing behavior to designers who do not write C++. Fast iteration with no external compile is the main win. - **Mix by default:** the framework classes are designed to be used "in either C++, Blueprint, or, the most common, a combination of both." The idiomatic shape is a C++ base class (logic, exposed via specifiers) with a Blueprint child (data, asset wiring, designer tweaks). - **Move logic down when it gets hot or shared:** once a Blueprint graph becomes a performance bottleneck or is copied across many actors, promote it to a C++ base class and keep only the data and light glue in Blueprint. - **Keep asset references out of C++ constructors** where practical; configure them in Blueprints instead of hardcoding paths. ## Pages Compared - [[concepts/blueprints-visual-scripting]] — the node-based visual scripting system. - [[concepts/programming-with-cpp]] — the compiled C++ path for gameplay code. - [[concepts/gameplay-framework]] — the shared class hierarchy both author against. ## Sources - raw/blueprints/blueprints-visual-scripting-in-unreal-engine.md - raw/cpp/programming-with-cplusplus-in-unreal-engine.md - raw/cpp/gameplay-classes-in-unreal-engine.md - raw/gameplay/gameplay-framework-in-unreal-engine.md --- title: "Choosing Gameplay & AI Systems" type: synthesis tags: [gameplay, ai, behavior-trees, statetree, framework] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/gameplay/gameplay-framework-in-unreal-engine.md", "raw/gameplay/game-mode-and-game-state-in-unreal-engine.md", "raw/gameplay/behavior-trees-in-unreal-engine.md", "raw/gameplay/state-tree-in-unreal-engine.md", "raw/gameplay/input-in-unreal-engine.md"] confidence: high --- # Choosing Gameplay & AI Systems Unreal's [[concepts/gameplay-framework|Gameplay Framework]] is "a collection of classes that provides you with a modular foundation" — you pick the pieces your game needs. The recurring questions are: which class owns which responsibility (GameMode vs Pawn vs Controller), and which AI system drives your NPCs (Behavior Trees vs StateTree). This page maps responsibilities and helps you choose. ## Comparison ### Framework class responsibilities | Class | Lifetime | Physical? | Owns | | --- | --- | --- | --- | | Game Instance | Engine launch to shutdown; persists across level loads | No | Cross-level data, save systems, Game Instance Subsystems (e.g. Online) | | Game Mode | Created on level load; **not** persistent across levels; server-only | No (Actor-derived manager) | Rules of the session — player counts, spawn/respawn, pausing, level transitions | | Game State | Created by Game Mode; replicated to all clients | No | Data relevant to all players — scores, objectives, list of player states | | Player State | One per player on join; replicated | No | Data for one player — health, ammo, inventory | | Controller | Possesses a Pawn | No (non-physical) | Decision logic; Player Controller (human input, HUD) or AI Controller (AI) | | Pawn / Character | Spawned into world | Yes | Physical presence; Character adds movement/skeletal-mesh/capsule components | ### AI: Behavior Trees vs StateTree | Aspect | [[concepts/ai-behavior-trees]] | StateTree | | --- | --- | --- | | Model | Tree of branches executed to pick behavior | Hierarchical state machine (Selectors from BTs + States/Transitions from state machines) | | Data / "brain" | Separate **Blackboard** asset holding user-defined **Keys** | Self-contained states with transitions | | Strengths | Mature, readable decision branching; large ecosystem of node types | "Highly performant logic that stays flexible and organized" | | Driven by | An AI Controller | An AI Controller (or general-purpose logic) | | Best for | Classic NPC decision-making (patrol, chase, flee, cover) | Performance-sensitive or state-heavy logic; general-purpose state machines | ## Analysis **Match responsibility to lifetime and authority.** The framework separates classes by how long they live and who owns them. The **Game Instance** "is instantiated on engine launch and remains active until the engine shuts down" — the only place for anything that must survive level loads, like a save system; it is not replicated and exists independently on server and clients. The **Game Mode** "is instantiated immediately after your level is loaded," is server-only, and "is not persistent across levels"; it holds the rules — player/spectator counts, spawn and respawn behavior, whether the game can be paused, and level transitions. **Game State** and **Player State** are the replicated data carriers: Game State holds what all players share (scores, objectives), Player State holds per-player data (health, ammo, inventory). **Controller vs Pawn is the brain/body split.** Controllers "are non-physical actors that can possess a pawn to control its actions." A **Player Controller** processes human input and drives HUD; an **AI Controller** "possesses physical representations in the game and dictates their actions with the help of UE's artificial intelligence, including: behavior trees, state trees, navigation." The **Pawn** is the physical manifestation, and **Character** is a Pawn subclass with richer components (character movement, skeletal mesh, capsule) for a vertically-oriented walker. Keep decision logic in the Controller and physical/animation state in the Pawn. **Input feeds the Controller/Pawn.** The `PlayerInput` object "is responsible for converting input from the player into data that Actors (like PlayerControllers or Pawns) can understand and use," translating hardware input into game events via input mappings and Input Components. Input therefore sits at the top of the same chain: hardware to Player Input to Player Controller to possessed Pawn. See [[concepts/input-system|the input system]]. **Behavior Trees vs StateTree.** Behavior Trees "can be used to create artificial intelligence for non-player characters," executing branches of logic while relying on a separate **Blackboard** asset that "serves as the 'brain'" — a set of user-defined **Keys** (for example a Boolean `Is Light On`) the tree reads to choose a branch. They scale from a trivial roach to "simulating another human player." **StateTree** is "a general-purpose hierarchical state machine that combines the Selectors from behavior trees with States and Transitions from state machines," letting you "create highly performant logic that stays flexible and organized." Both are driven through an AI Controller; the difference is the mental model — branch selection with a shared blackboard (BT) versus explicit states and transitions (StateTree). ## Recommendations - **Persist across levels:** put it in the **Game Instance** (save data, online subsystems). Do not rely on Game Mode for anything that must survive a level change. - **Session rules and spawning:** put in the **Game Mode** (server authority). Keep it thin — it defines rules and which classes to use, not per-player data. - **Replicated state:** shared game data goes in **Game State**; per-player data goes in **Player State**. Do not stuff player data into the Pawn if it must replicate and survive respawns. - **Brain vs body:** decision logic and input handling live in the **Controller**; physical presence and movement live in the **Pawn/Character**. Use **Character** when you need a walking/jumping humanoid; a plain **Pawn** for vehicles or non-humanoid agents. - **AI system:** reach for **Behavior Trees** for classic NPC decision-making and when you want the mature Blackboard-driven node ecosystem. Choose **StateTree** when logic is naturally state-based or performance-sensitive, or when you want a general-purpose hierarchical state machine beyond AI. Both run under an AI Controller, so you can pick per-agent. ## Pages Compared - [[concepts/gameplay-framework]] — GameMode, Pawn, Controller, and the class hierarchy. - [[concepts/ai-behavior-trees]] — Behavior Trees and the Blackboard. - [[concepts/input-system]] — converting hardware input into game actions. ## Sources - raw/gameplay/gameplay-framework-in-unreal-engine.md - raw/gameplay/game-mode-and-game-state-in-unreal-engine.md - raw/gameplay/behavior-trees-in-unreal-engine.md - raw/gameplay/state-tree-in-unreal-engine.md - raw/gameplay/input-in-unreal-engine.md --- title: "Rendering Feature Map: Lumen, Nanite, Path Tracer & Substrate" type: synthesis tags: [rendering, lumen, nanite, path-tracer, substrate] created: 2026-07-17 updated: 2026-07-17 sources: ["raw/rendering/lumen-global-illumination-and-reflections-in-unreal-engine.md", "raw/rendering/nanite-virtualized-geometry-in-unreal-engine.md", "raw/rendering/path-tracer-in-unreal-engine.md", "raw/rendering/substrate-materials-in-unreal-engine.md"] confidence: high --- # Rendering Feature Map: Lumen, Nanite, Path Tracer & Substrate UE5's headline rendering features solve different problems and are easy to confuse. **Lumen** does dynamic lighting, **Nanite** does geometry, **Substrate** does material authoring, and the **Path Tracer** is an offline ground-truth renderer, not a real-time feature at all. They are largely orthogonal and are designed to work together — Nanite meshes fully support Lumen and Virtual Shadow Maps, and the Path Tracer can render Nanite and Substrate content. This page maps what each solves and when to enable it. ## Comparison | Feature | What it solves | Real-time or offline | Default state | Key requirement | | --- | --- | --- | --- | --- | | [[concepts/lumen-global-illumination]] | Fully dynamic global illumination + reflections (infinite diffuse bounces, indirect specular) | Real-time | **On** for new UE5 projects | Generate Mesh Distance Fields (software RT); optional Hardware Ray Tracing | | [[concepts/nanite-virtualized-geometry]] | Virtualized geometry — pixel-scale detail, huge triangle/instance counts, automatic LOD | Real-time | Off per-mesh (opt-in flag) | DirectX 12 + Shader Model 6 (SM6); SSD recommended for streaming | | Path Tracer | Physically correct, unbiased GI/reflection/refraction for film-quality stills and sequences | **Offline** (progressive accumulation) | Off | Hardware Ray Tracing; DX12 RHI; NVIDIA RTX / DXR-enabled GPU | | [[concepts/materials-and-substrate]] | Modular material authoring replacing the fixed shading-model/blend-mode suite | Real-time (also path-traced) | Off (**Beta**) | Enabled as a project feature | ## Analysis **Lumen — the default lighting system.** Lumen is "Unreal Engine's fully dynamic global illumination and reflections system" and is enabled by default on newly-created UE5 projects; UE4 projects converted to UE5 do **not** get it automatically. Enabling Lumen turns off precomputed static lighting — "all lightmaps are hidden" and Static-mobility lights are unsupported because they live in lightmaps. It has two tracing paths: **Software Ray Tracing** (needs `Generate Mesh Distance Fields`, with Detail vs Global tracing modes) and **Hardware Ray Tracing** ("Use Hardware Ray Tracing when available"), which "has significant scene update costs for scenes with more than 100,000 instances." GI and Reflections are set independently under `Rendering > Dynamic Global Illumination` and `Reflections`, and Lumen Reflections can even be used standalone over baked static lighting (which requires Hardware Ray Tracing mode). **Nanite — the geometry system.** Nanite renders "pixel scale detail and high object counts," doing work "only on the detail that is visible on-screen." A Nanite mesh is just a Static Mesh with the flag set; it handles LOD automatically and streams compressed data on demand (SSDs recommended). It should "generally be enabled wherever possible on platforms that support it," and is an especially good candidate for meshes with many triangles, many instances, that occlude other Nanite geometry, or that cast Virtual Shadow Maps. Hard limits matter: the scene is "hard-locked to 16 million instances"; only `Opaque` and `Masked` blend modes are supported; Morph Targets and per-vertex tangents are not stored; ray tracing against Nanite meshes uses a Fallback Mesh unless the experimental `r.RayTracing.Nanite.Mode 1` is set. Platform floor: DX12 with SM6. **Path Tracer — the offline reference.** The Path Tracer is "a progressive, hardware-accelerated rendering mode" that produces "physically correct and compromise-free global illumination, reflection and refraction." It accumulates samples while the camera is still and denoises at the target sample count; moving the camera, editing materials, or moving objects invalidates the samples. It is "ideal for static scenes and less so for dynamic scenes" — animated/skinned meshes and VFX streak in the viewport and must be finalized through **Movie Render Queue**. Requirements are strict: Windows 10 1809+, an NVIDIA RTX / DXR-enabled GPU, DirectX 12 RHI, and Hardware Ray Tracing + Path Tracing enabled. It shares the real-time ray tracing code path and supports Nanite (via Fallback Mesh) and Substrate (experimental). **Substrate — the material framework.** Substrate is UE5's replacement for the fixed suite of shading models and blend modes (Default Lit, Clear Coat, and so on) with a "more expressive and modular framework" built on principled BSDF layering and Substrate operators. It is a **Beta** feature — "use caution when shipping with it" — and is orthogonal to the other three: it changes how materials are authored, and those materials are then lit by Lumen in real time or by the Path Tracer offline. **How they combine.** These are not either/or choices. Nanite geometry is lit by Lumen and shadowed by Virtual Shadow Maps in real time; the same scene can be re-rendered by the Path Tracer for a marketing still; and any of those materials can be authored with Substrate. The decisions are mostly independent. ## Recommendations - **Lighting:** Leave **Lumen on** for new real-time UE5 projects that want dynamic GI. If you require baked/static lighting, be aware Lumen disables lightmaps — either accept dynamic GI or keep static lighting and consider standalone Lumen Reflections (Hardware Ray Tracing) for better reflections. - **Geometry:** **Enable Nanite wherever supported** (DX12/SM6), especially for dense meshes, high instance counts, occluders, and VSM shadow casters. Keep it off only for unsupported cases — translucent-blend materials, Morph Target deformation, or trivial meshes like a sky sphere (where the loss is minimal anyway). - **Offline / marketing renders:** Use the **Path Tracer** through **Movie Render Queue** for photoreal stills and film/TV output and for ground-truth comparisons. Do not treat it as a gameplay renderer — it needs RTX-class hardware and a static scene to converge. - **Materials:** Reach for **Substrate** when you need layered/complex material expression beyond the legacy shading models, but treat it as Beta and validate before shipping; the fixed shading models remain the safe default for production. - **Budget check:** Even with Nanite and Lumen, measure — instance counts, material complexity, and Lumen's per-instance Hardware RT scene-update cost (>100k instances) can still blow a frame budget. ## Pages Compared - [[concepts/lumen-global-illumination]] — dynamic global illumination and reflections. - [[concepts/nanite-virtualized-geometry]] — virtualized geometry and automatic LOD. - [[concepts/lighting-and-shadows]] — light types, mobility, and shadowing. - [[concepts/materials-and-substrate]] — material authoring and the Substrate framework. ## Sources - raw/rendering/lumen-global-illumination-and-reflections-in-unreal-engine.md - raw/rendering/nanite-virtualized-geometry-in-unreal-engine.md - raw/rendering/path-tracer-in-unreal-engine.md - raw/rendering/substrate-materials-in-unreal-engine.md