Unreal Engine Style Guide
- Important Terminology
- 00. Globally Enforced Opinions
- 1. Asset Naming Conventions
- 2. Content Directory Structure
- 2e1 Example Project Content Structure
- 2.1 Folder Names
- 2.2 Use A Top Level Folder For Project Specific Assets
- 2.3 Use Developers Folder For Local Testing
- 2.4 All Map* Files Belong In A Folder Called Maps
- 2.5 Use A
CoreFolder For Critical Blueprints And Other Assets - 2.6 Do Not Create Folders Called
AssetsorAssetTypes - 2.7 Very Large Asset Sets Get Their Own Folder Layout
- 2.8
MaterialLibrary - 2.9 No Empty Folders
- 3. Blueprints
- 3.1 Compiling
- 3.2 Variables
- 3.3 Functions, Events, and Event Dispatchers
- 3.3.1 Function Naming
- 3.3.1.1 All Functions Should Be Verbs
- 3.3.1.2 Property RepNotify Functions Always
OnRep_Variable - 3.3.1.3 Info Functions Returning Bool Should Ask Questions
- 3.3.1.4 Event Handlers and Dispatchers Should Start With
On - 3.3.1.5 Remote Procedure Calls Should Be Prefixed With Target
- 3.3.2 All Functions Must Have Return Nodes
- 3.3.3 No Function Should Have More Than 50 Nodes
- 3.3.4 All Public Functions Should Have A Description
- 3.3.5 All Custom Static Plugin
BlueprintCallableFunctions Must Be Categorized By Plugin Name
- 3.4 Blueprint Graphs
- 4. Static Meshes
- 5. Niagara
- 6. Levels / Maps
- 7. Textures
An Identifier is anything that resembles or serves as a "name". For example, the name of an asset, or the name of a material later, or a blueprint property, a variable, or a folder name, or for a data table row name, etc...
There are a few different ways you can CaseWordsWhenNaming. Here are some common casing types:
Capitalize every word and remove all spaces, e.g.
DesertEagle,StyleGuide,ASeriesOfWords.The first letter is always lowercase but every following word starts with uppercase, e.g.
desertEagle,styleGuide,aSeriesOfWords.Words can arbitrarily start upper or lowercase but words are separated by an underscore, e.g.
desert_Eagle,Style_Guide,a_Series_of_Words.
In any Identifier of any kind, never use the following unless absolutely forced to:
- White space of any kind
- Backward slashes
\ - Symbols i.e.
#!@$% - Any Unicode character
Any Identifier should strive to only have the following characters when possible (the RegEx [A-Za-z0-9_]+)
- ABCDEFGHIJKLMNOPQRSTUVWXYZ
- abcdefghijklmnopqrstuvwxyz
- 1234567890
- _ (almost never) *The ONLY exception to this is when using FJsonObjectConverter::JsonObjectStringToUStruct and working with existing APIs
Most things are prefixed with prefixes being generally an acronym of the asset type followed by an underscore.
All assets should have a Base Asset Name. A Base Asset Name represents a logical grouping of related assets. Any asset that is part of this logical group should follow the standard of Prefix_BaseAssetName_Variant_Suffix.
Prefix and Suffix are to be determined by the asset type through the following Asset Name Modifier tables.
BaseAssetName should be determined by a short and easily recognizable name related to the context of this group of assets. For example, if you had a character named Bob, all of Bob's assets would have the BaseAssetName of Bob.
For unique and specific variations of assets, Variant is either a short and easily recognizable name that represents logical grouping of assets that are a subset of an asset's base name. For example, if Bob had multiple skins these skins should still use Bob as the BaseAssetName but include a recognizable Variant. An 'Evil' skin would be referred to as Bob_Evil and a 'Retro' skin would be referred to as Bob_Retro.
For unique but generic variations of assets, Variant is a two digit number starting at 01. For example, if you have an environment artist generating nondescript rocks, they would be named Rock_01, Rock_02, Rock_03, etc. Except for rare exceptions, you should never require a three digit variant number. If you have more than 100 assets, you should consider organizing them with different base names or using multiple variant names.
Depending on how your asset variants are made, you can chain together variant names. For example, if you are creating flooring assets for an Arch Viz project you should use the base name Flooring with chained variants such as Flooring_Marble_01, Flooring_Maple_01, Flooring_Tile_Squares_01.
| Asset Type | Asset Name |
|---|---|
| Skeletal Mesh | SKM_Bob |
| Material | M_Bob |
| Texture (Diffuse/Albedo) | TX_Bob_D |
| Texture (Normal) | TX_Bob_N |
| Texture (Evil Diffuse) | TX_Bob_Evil_D |
| Asset Type | Asset Name |
|---|---|
| Static Mesh (01) | SM_Rock_01 |
| Static Mesh (02) | SM_Rock_02 |
| Static Mesh (03) | SM_Rock_03 |
| Material | M_Rock |
| Material Instance (Snow) | MI_Rock_Snow |
When naming an asset, use these tables to determine the prefix and suffix to use with an asset's Base Asset Name.
| Asset Type | Prefix | Suffix | Notes |
|---|---|---|---|
| Level / Map | |||
| Level (Persistent) | _P | ||
| Level (Audio) | _Audio | ||
| Level (Lighting) | _Lighting | ||
| Level (Geometry) | _Geo | ||
| Level (Gameplay) | _Gameplay | ||
| Blueprint | BP_ | ||
| Material | M_ | ||
| Static Mesh | SM_ | ||
| Skeletal Mesh | SKM_ | ||
| Texture | TX_ | _? | See Textures |
| Particle System | PS_ | ||
| Widget Blueprint | WBP_ |
| Asset Type | Prefix | Suffix | Notes |
|---|---|---|---|
| Aim Offset | AO_ | ||
| Aim Offset 1D | AO_ | ||
| Animation Blueprint | ABP_ | ||
| Animation Composite | AC_ | ||
| Animation Montage | AM_ | ||
| Animation Sequence | A_ | ||
| Blend Space | BS_ | ||
| Blend Space 1D | BS_ | ||
| Level Sequence | LS_ | ||
| Morph Target | MT_ | ||
| Paper Flipbook | PFB_ | ||
| Rig | Rig_ | ||
| Skeletal Mesh | SKM_ | ||
| Skeleton | SKEL_ |
| Asset Type | Prefix | Suffix | Notes |
|---|---|---|---|
| AI Controller | AIC_ | ||
| Behavior Tree | BT_ | ||
| Blackboard | BB_ | ||
| Decorator | BTDecorator_ | ||
| Service | BTService_ | ||
| Task | BTTask_ | ||
| Environment Query | EQS_ | ||
| EnvQueryContext | EQS_ | Context |
| Asset Type | Prefix | Suffix | Notes |
|---|---|---|---|
| Blueprint | BP_ | ||
| Blueprint Component | BP_ | Component | I.e. BP_InventoryComponent |
| Blueprint Function Library | BPFL_ | ||
| Blueprint Interface | BPI_ | ||
| Blueprint Macro Library | BPML_ | Do not use macro libraries if possible. | |
| Enumeration | E | No underscore. | |
| Structure | F | No underscore. | |
| Tutorial Blueprint | TBP_ | ||
| Widget Blueprint | W_ | ||
| Gameplay Ability | GA_ |
| Asset Type | Prefix | Suffix | Notes |
|---|---|---|---|
| Material | M_ | ||
| Material (Post Process) | PP_ | ||
| Material Function | MF_ | ||
| Material Instance | MI_ | ||
| Material Parameter Collection | MPC_ | ||
| Subsurface Profile | SP_ | ||
| Physical Materials | PM_ | ||
| Decal | M_, MI_ | _Decal |
| Asset Type | Prefix | Suffix | Notes |
|---|---|---|---|
| Texture | TX_ | ||
| Texture (Diffuse/Albedo/Base Color) | TX_ | _D | |
| Texture (Normal) | TX_ | _N | |
| Texture (Roughness) | TX_ | _R | |
| Texture (Alpha/Opacity) | TX_ | _A | |
| Texture (Ambient Occlusion) | TX_ | _O | |
| Texture (Bump) | TX_ | _B | |
| Texture (Emissive) | TX_ | _E | |
| Texture (Mask) | TX_ | _M | |
| Texture (Specular) | TX_ | _S | |
| Texture (Metallic) | TX_ | _M | |
| Texture (Packed) | TX_ | _* | See notes below about packing. |
| Texture Cube | TXC_ | ||
| Media Texture | MTX_ | ||
| Render Target | RT_ | ||
| Cube Render Target | RTC_ | ||
| Texture Light Profile | TLP |
It is common practice to pack multiple layers of texture data into one texture. An example of this is packing Emissive, Roughness, Ambient Occlusion together as the Red, Green, and Blue channels of a texture respectively. To determine the suffix, simply stack the given suffix letters from above together, e.g. _ERO.
It is generally acceptable to include an Alpha/Opacity layer in your Diffuse/Albedo's alpha channel and as this is common practice, adding
Ato the_Dsuffix is optional.
Packing 4 channels of data into a texture (RGBA) is not recommended except for an Alpha/Opacity mask in the Diffuse/Albedo's alpha channel as a texture with an alpha channel incurs more overhead than one without.
| Asset Type | Prefix | Suffix | Notes |
|---|---|---|---|
| Animated Vector Field | AVF_ | ||
| Camera Anim | CA_ | ||
| Color Curve | Curve_ | _Color | |
| Vector Curve | Curve_ | _Vector | |
| Float Curve | Curve_ | _Float | |
| Curve Table | Curve_ | _Table | |
| Data Asset | DA_ | ||
| Data Table | DT_ | ||
| Foliage Type | FT_ | ||
| Force Feedback Effect | FFE_ | ||
| Landscape Grass Type | LG_ | ||
| Landscape Layer | LL_ | ||
| Matinee Data | Matinee_ | ||
| Media Player | MP_ | ||
| File Media Source | FMS_ | ||
| Object Library | OL_ | ||
| Redirector | These should be fixed up ASAP. | ||
| Sprite Sheet | SS_ | ||
| Static Vector Field | VF_ | ||
| Substance Graph Instance | SGI_ | ||
| Substance Instance Factory | SIF_ | ||
| Touch Interface Setup | TI_ |
| Asset Type | Prefix | Suffix | Notes |
|---|---|---|---|
| Paper Flipbook | PFB_ | ||
| Sprite | SPR_ | ||
| Sprite Atlas Group | SPRG_ | ||
| Tile Map | TM_ | ||
| Tile Set | TS_ |
| Asset Type | Prefix | Suffix | Notes |
|---|---|---|---|
| Physical Material | PM_ | ||
| Physics Asset | PHYS_ | ||
| Destructible Mesh | DM_ |
| Asset Type | Prefix | Suffix | Notes |
|---|---|---|---|
| Dialogue Voice | DV_ | ||
| Dialogue Wave | DW_ | ||
| Media Sound Wave | MSW_ | ||
| Reverb Effect | Reverb_ | ||
| Sound Attenuation | ATT_ | ||
| Sound Class | No prefix/suffix. Should be put in a folder called SoundClasses | ||
| Sound Concurrency | _SC | Should be named after a SoundClass | |
| Sound Cue | A_ | _Cue | |
| Sound Mix | Mix_ | ||
| Sound Wave | A_ |
| Asset Type | Prefix | Suffix | Notes |
|---|---|---|---|
| Font | Font_ | ||
| Slate Brush | Brush_ | ||
| Slate Widget Style | Style_ | ||
| Widget Blueprint | WBP_ |
| Asset Type | Prefix | Suffix | Notes |
|---|---|---|---|
| Particle System | PS_ | ||
| Material (Post Process) | PP_ |
Equally important as asset names, the directory structure style of a project should be considered law. Asset naming conventions and content directory structure go hand in hand, and a violation of either causes unneeded chaos.
As a rule of thumb, there is a organizational format we follow at the project level, but this same format also works when implementing/organizing different game modes.
If you are using the prefix naming convention above, using folders to contain assets of similar types such as
Meshes,Textures, andMaterialsis a redundant practice as asset types are already both sorted by prefix as well as able to be filtered in the content browser.
|-- Content
|-- GenericShooter
|-- Art
| |-- Industrial
| | |-- Ambient
| | |-- Machinery
| | |-- Pipes
| |-- Nature
| | |-- Ambient
| | |-- Foliage
| | |-- Rocks
| | |-- Trees
| |-- Office
|-- Characters
| |-- Bob
| |-- Common
| | |-- Animations
| | |-- Audio
| |-- Zoe
|-- Core
| |-- Characters
| |-- Interactables
| |-- Pickups
| |-- Weapons
| |-- BP_GenericShooterGameMode
| |-- BP_GenericShooterGameState
| |-- BP_GenericShooterGameSession
| |-- BP_GenericShooterPlayerController
|-- Effects
| |-- Electrical
| |-- Fire
| |-- Weather
|-- Maps
| |-- MainMenu
| |-- Campaign1
|-- MaterialLibrary
| |-- Debug
| |-- Metal
| |-- Paint
| |-- Utility
| |-- Weathering
|-- GameModes
| |-- CaptureTheFlag
| | |-- Art
| | | |-- Flags
| | |-- Characters
| | |-- Core
| | | | -- BP_CaptureTheFlagGameMode
| | | | -- BP_CaptureTheFlagGameState
| | | | -- BP_CaptureTheFlagGameSession
| | | | -- BP_CaptureTheFlagPlayerController
| | |-- Effects
| | |-- Maps
| | | |-- Rust
| | | |-- TheFactory
| | |-- MaterialLibrary
|-- Placeables
| |-- Pickups
|-- Weapons
|-- Common
|-- Pistols
| |-- DesertEagle
| |-- RocketPistol
|-- Rifles
###Content Structutre Clarification
The general idea with this project structure is to narrow down organization to simple questions:
-
Is this asset specific to a game mode? If Yes /Content/GenericShooter/GameModes// If No /Content/GenericShooter/
-
Is this critical to the game (i.e. BaseClass)? If Yes /Content/GenericShooter/Core/ If No See 1)
These are common rules for naming any folder in the content structure.
2.1.1 Always Use PascalCase*
PascalCase refers to starting a name with a capital letter and then instead of using spaces, every following word also starts with a capital letter. For example, DesertEagle, RocketPistol, and ASeriesOfWords.
See Cases.
Re-enforcing 2.1.1, never use spaces. Spaces can cause various engineering tools and batch processes to fail. Ideally, your project's root also contains no spaces and is located somewhere such as D:\Project instead of C:\Users\My Name\My Documents\Unreal Projects.
If one of your game characters is named 'Zoë', its folder name should be Zoe. Unicode characters can be worse than Spaces for engineering tool and some parts of UE4 don't support Unicode characters in paths either.
Related to this, if your project has unexplained issues and your computer's user name has a Unicode character (i.e. your name is Zoë), any project located in your My Documents folder will suffer from this issue. Often simply moving your project to something like D:\Project will fix these mysterious issues.
Using other characters outside a-z, A-Z, and 0-9 such as @, -, _, ,, *, and # can also lead to unexpected and hard to track issues on other platforms, source control, and weaker engineering tools.
All of a project's assets should exist in a folder named after the project. For example, if your project is named 'Generic Shooter', all of it's content should exist in Content/GenericShooter.
The
Developersfolder is not for assets that your project relies on and therefore is not project specific. See Developer Folders for details about this.
Any DLC, sub-project(s), or unrelated assets should have their own separate top level content folder. This makes it far easier to cook these separately from the main project. If there needs to be specific asset/material override behavior in a patch, you can easily put these changes in a patch folder and work safely without the chance of breaking the core project.
Use the Developer folder to create your own 'sandbox'. This allows you to experiment with assets freely, without risking the core project. The Content Browser has specific View Options that will hide Developer folders (they are hidden by default). Once the assets are ready for use, simply move the assets into the project specific folder and fix up redirectors. This is essentially 'promoting' the assets from experimental to production.
2.4 All Map* Files Belong In A Folder Called Maps
All maps should belong in /Content/Project/Maps, or Content/Project/GameModes/GameModeName/Maps
It is common for levels to be within sub-folders of Maps, such as Maps/Campaign1/ or Maps/Arenas.
Use /Content/Project/Core folder for assets that are absolutely fundamental to a project's workings. For example, base GameMode, Character, PlayerController, GameState, PlayerState, and related Blueprints should live here.
For example, if your project requires pickups that can be placed in a level, there should exist a base Pickup class in Core/Pickups that defines base behavior for a pickup. Specific pickups such as a Health or Ammo should exist in a folder such as /Content/Project/Placeables/Pickups/. Game designers can define and tweak pickups in this folder however they please, but they should not touch Core/Pickups as they may unintentionally break pickups project-wide.
All assets are assets.
All asset names are named with their asset type in mind. These folders offer only redundant information and the use of these folders can easily be replaced with the robust and easy to use filtering system the Content Browser provides.
Want to view only static mesh in Environment/Rocks/? Simply turn on the Static Mesh filter. If all assets are named correctly, they will also be sorted in alphabetical order regardless of prefixes. Want to view both static meshes and skeletal meshes? Simply turn on both filters. This eliminates the need to potentially have to Control-Click select two folders in the Content Browser's tree view.
This also extends the full path name of an asset for very little benefit. The
S_prefix for a static mesh is only two characters, whereasMeshes/is seven characters.
Not doing this also prevents the inevitability of someone putting a static mesh or a texture in a Materials folder.
This can be seen as a pseudo-exception to 2.6.
There are certain asset types that have a huge volume of related files where each asset has a unique purpose. The two most common are Animation and Audio assets. If you find yourself having 15+ of these assets that belong together, they should be together.
For example, animations that are shared across multiple characters should lay in Characters/Common/Animations and may have sub-folders such as Locomotion or Cinematic.
This does not apply to assets like textures and materials. It is common for a
Rocksfolder to have a large amount of textures if there are a large amount of rocks, however these textures are generally only related to a few specific rocks and should be named appropriately. Even if these textures are part of a Material Library.
If your project makes use of master materials, layered materials, or any form of reusable materials or textures that do not belong to any subset of assets, these assets should be located in Content/Project/MaterialLibrary.
This way all 'global' materials have a place to live and are easily located.
This also makes it incredibly easy to enforce a 'use material instances only' policy within a project. If all artists and assets should be using material instances, then the only regular material assets that should exist are within this folder. You can easily verify this by searching for base materials in any folder that isn't the
MaterialLibrary.
The MaterialLibrary doesn't have to consist of purely materials. Shared utility textures, material functions, and other things of this nature should be stored here as well within folders that designate their intended purpose. For example, generic noise textures should be located in MaterialLibrary/Utility.
Any testing or debug materials should be within MaterialLibrary/Debug. This allows debug materials to be easily stripped from a project before shipping and makes it incredibly apparent if production assets are using them if reference errors are shown.
There simply shouldn't be any empty folders. They clutter the content browser.
If you find that the content browser has an empty folder you can't delete, you should perform the following:
- Be sure you're using source control.
- Immediately run Fix Up Redirectors on your project.
- Navigate to the folder on-disk and delete the assets inside.
- Close the editor.
- Make sure your source control state is in sync (i.e. if using Perforce, run a Reconcile Offline Work on your content directory)
- Open the editor. Confirm everything still works as expected. If it doesn't, revert, figure out what went wrong, and try again.
- Ensure the folder is now gone.
- Submit changes to source control.
This section will focus on Blueprint classes and their internals. When possible, style rules conform to Epic's Coding Standard.
All blueprints should compile with zero warnings and zero errors. You should fix blueprint warnings and errors immediately as they can quickly cascade into very scary unexpected behavior.
Do not submit broken blueprints to source control. If you must store them on source control, shelve them instead.
Broken blueprints can cause problems that manifest in other ways, such as broken references, unexpected behavior, cooking failures, and frequent unneeded recompilation. A broken blueprint has the power to break the entire game.
The words variable and property may be used interchangeably.
All non-boolean variable names must be clear, unambiguous, and descriptive nouns.
All non-boolean variables should be in the form of PascalCase.
ScoreTargetPlayerCrosshairColorAbilityId
All booleans should be named in PascalCase but prefixed with a lowercase b.
Example: Use bDead and bEvil, not Dead and Evil.
UE4 Blueprint editors know not to include the b in user-friendly displays of the variable.
All booleans should be named as descriptive adjectives when possible if representing general information. Do not include words that phrase the variable as a question, such as Is. This is reserved for functions.
Example: Use bDead and bHostile not bIsDead and bIsHostile.
Try to not use verbs such as bRunning. Verbs tend to lead to complex states.
Do not to use booleans to represent complex and/or dependent states. This makes state adding and removing complex and no longer easily readable. Use an enumeration instead.
Example: When defining a weapon, do not use bReloading and bEquipping if a weapon can't be both reloading and equipping. Define an enumeration named EWeaponState and use a variable with this type named WeaponState instead. This makes it far easier to add new states to weapons.
Example: Do not use bRunning if you also need bWalking or bSprinting. This should be defined as an enumeration with clearly defined state names.
All variable names must not be redundant with their context as all variable references in Blueprint will always have context.
Consider a Blueprint called BP_PlayerCharacter.
Bad
PlayerScoreMyTargetPlayerMyCharacterNameCharacterSkillsChosenCharacterSkin
All of these variables are named redundantly. It is implied that the variable is representative of the BP_PlayerCharacter it belongs to because it is BP_PlayerCharacter that is defining these variables.
Good
ScoreTargetPlayerNameSkillsSkin
Atomic or primitive variables are variables that represent data in their simplest form, such as booleans, integers, floats, and enumerations.
Strings and vectors are considered atomic in terms of style when working with Blueprints, however they are technically not atomic.
While vectors consist of three floats, vectors are often able to be manipulated as a whole, same with rotators.
Do not consider Text variables as atomic, they are secretly hiding localization functionality. The atomic type of a string of characters is
String, notText.
Atomic variables should not have their type name in their name.
Example: Use Score, Kills, and Description not ScoreFloat, FloatKills, DescriptionString.
The only exception to this rule is when a variable represents 'a number of' something to be counted and when using a name without a variable type is not easy to read.
Example: A fence generator needs to generate X number of posts. Store X in NumPosts or PostsCount instead of Posts as Posts may potentially read as an Array of a variable type named Post.
Non-atomic or complex variables are variables that represent data as a collection of atomic variables. Structs, Classes, Interfaces, and primitives with hidden behavior such as Text and Name all qualify under this rule.
While an Array of an atomic variable type is a list of variables, Arrays do not change the 'atomicness' of a variable type.
These variables should include their type name while still considering their context.
If a class owns an instance of a complex variable, i.e. if a BP_PlayerCharacter owns a BP_Hat, it should be stored as the variable type as without any name modifications.
Example: Use Hat, Flag, and Ability not MyHat, MyFlag, and PlayerAbility.
If a class does not own the value a complex variable represents, you should use a noun along with the variable type.
Example: If a BP_Turret has the ability to target a BP_PlayerCharacter, it should store its target as TargetPlayer as when in the context of BP_Turret it should be clear that it is a reference to another complex variable type that it does not own.
Arrays follow the same naming rules as above, but should be named as a plural noun.
Example: Use Targets, Hats, and EnemyPlayers, not TargetList, HatArray, EnemyPlayerArray.
All variables that are safe to change the value of in order to configure behavior of a blueprint should be marked as Editable.
Conversely, all variables that are not safe to change or should not be exposed to designers should not be marked as editable, unless for engineering reasons the variable must be marked as Expose On Spawn.
Do not arbitrarily mark variables as Editable.
All Editable variables, including those marked editable just so they can be marked as Expose On Spawn, should have a description in their Tooltip fields that explains how changing this value affects the behavior of the blueprint.
All Editable variables should make use of slider and value ranges if there is ever a value that a variable should not be set to.
Example: A blueprint that generates fence posts might have an editable variable named PostsCount and a value of -1 would not make any sense. Use the range fields to mark 0 as a minimum.
If an editable variable is used in a Construction Script, it should have a reasonable Slider Range defined so that someone can not accidentally assign it a large value that could crash the editor.
A Value Range only needs to be defined if the bounds of a value are known. While a Slider Range prevents accidental large number inputs, an undefined Value Range allows a user to specify a value outside the Slider Range that may be considered 'dangerous' but still valid.
If a class has only a small number of variables, categories are not required.
If a class has a moderate amount of variables (5-10), all Editable variables should have a non-default category assigned. A common category is Config.
If a class has a large amount of variables, all Editable variables should be categorized into sub-categories using the category Config as the base category. Non-editable variables should be categorized into descriptive categories describing their usage.
You can define sub-categories by using the pipe character
|, i.e.Config | Animations.
Example: A weapon class set of variables might be organized as:
|-- Config
| |-- Animations
| |-- Effects
| |-- Audio
| |-- Recoil
| |-- Timings
|-- Animations
|-- State
|-- Visuals
In C++, variables have a concept of access level. Public means any code outside the class can access the variable. Protected means only the class and any child classes can access this variable internally. Private means only this class and no child classes can access this variable.
Blueprints do not have a defined concept of protected access currently.
Treat Editable variables as public variables. Treat non-editable variables as protected variables.
Unless it is known that a variable should only be accessed within the class it is defined and never a child class, do not mark variables as private. Until variables are able to be marked protected, reserve private for when you absolutely know you want to restrict child class usage.
If a variable should be editable but often untouched, mark it as Advanced Display. This makes the variable hidden unless the advanced display arrow is clicked.
To find the Advanced Display option, it is listed as an advanced displayed variable in the variable details list.
Transient variables are variables that do not need to have their value saved and loaded and have an initial value of zero or null. This is useful for references to other objects and actors who's value isn't known until run-time. This prevents the editor from ever saving a reference to it, and speeds up saving and loading of the blueprint class.
Because of this, all transient variables should always be initialized as zero or null. To do otherwise would result in hard to debug errors.
Do not use the Config Variable flag. This makes it harder for designers to control blueprint behavior. Config variables should only be used in C++ for rarely changed variables. Think of them as Advanced Advanced Display variables.
This section describes how you should author functions, events, and event dispatchers. Everything that applies to functions also applies to events, unless otherwise noted.
The naming of functions, events, and event dispatchers is critically important. Based on the name alone, certain assumptions can be made about functions. For example:
- Is it a pure function?
- Is it fetching state information?
- Is it a handler?
- Is it an RPC?
- What is its purpose?
These questions and more can all be answered when functions are named appropriately.
All functions and events perform some form of action, whether its getting info, calculating data, or causing something to explode. Therefore, all functions should all start with verbs. They should be worded in the present tense whenever possible. They should also have some context as to what they are doing.
OnRep functions, event handlers, and event dispatchers are an exception to this rule.
Good examples:
Fire- Good example if in a Character / Weapon class, as it has context. Bad if in a Barrel / Grass / any ambiguous class.Jump- Good example if in a Character class, otherwise, needs context.ReceiveMessageSortPlayerArrayGetArmOffsetGetCoordinatesUpdateTransformsEnableBigHeadModeIsEnemy- "Is" is a verb.
Bad examples:
Dead- Is Dead? Will deaden?RockProcessData- Ambiguous, these words mean nothing.PlayerState- Nouns are ambiguous.Color- Verb with no context, or ambiguous noun.
All functions for replicated with notification variables should have the form OnRep_Variable. This is forced by the Blueprint editor. If you are writing a C++ OnRep function however, it should also follow this convention when exposing it to Blueprints.
When writing a function that does not change the state of or modify any object and is purely for getting information, state, or computing a yes/no value, it should ask a question. This should also follow the verb rule.
This is extremely important as if a question is not asked, it may be assumed that the function performs an action and is returning whether that action succeeded.
Good examples:
IsDeadIsOnFireIsAliveIsSpeakingIsVisibleHasWeapon- "Has" is a verb.WasCharging- "Was" is past-tense of "be". Use "was" when referring to 'previous frame' or 'previous state'.CanReload- "Can" is a verb.
Bad examples:
Fire- Is on fire? Will fire? Do fire?OnFire- Can be confused with event dispatcher for firing.Dead- Is dead? Will deaden?Visibility- Is visible? Set visibility? A description of flying conditions?
Any function that handles an event or dispatches an event should start with On and continue to follow the verb rule. The verb may move to the end however if past-tense reads better.
Collocations of the word On are exempt from following the verb rule.
Handle is not allowed. It is 'Unreal' to use On instead of Handle, while other frameworks may prefer to use Handle instead of On.
Good examples:
OnDeath- Common collocation in gamesOnPickupOnReceiveMessageOnMessageRecievedOnTargetChangedOnClickOnLeave
Bad examples:
OnDataOnTargetHandleMessageHandleDeath
Any time an RPC is created, it should be prefixed with either Server, Client, or Multicast. No exceptions.
After the prefix, follow all other rules regarding function naming.
Good examples:
ServerFireWeaponClientNotifyDeathMulticastSpawnTracerEffect
Bad examples:
FireWeapon- Does not indicate its an RPC of some kind.ServerClientBroadcast- Confusing.AllNotifyDeath- UseMulticast, neverAll.ClientWeapon- No verb, ambiguous.
All functions must have return nodes, no exceptions.
Return nodes explicitly note that a function has finished its execution. In a world where blueprints can be filled with Sequence, ForLoopWithBreak, and backwards reroute nodes, explicit execution flow is important for readability, maintenance, and easier debugging.
The Blueprint compiler is able to follow the flow of execution and will warn you if there is a branch of your code with an unhandled return or bad flow if you use return nodes.
In situations like where a programmer may add a pin to a Sequence node or add logic after a for loop completes but the loop iteration might return early, this can often result in an accidental error in code flow. The warnings the Blueprint compiler will alert everyone of these issues immediately.
Simply, no function should have more than 50 nodes. Any function this big should be broken down into smaller functions for readability and ease of maintenance.
The following nodes are not counted as they are deemed to not increase function complexity:
- Comment
- Route
- Cast
- Getting a Variable
- Breaking a Struct
- Function Entry
- Self
This rule applies more to public facing or marketplace blueprints, so that others can more easily navigate and consume your blueprint API.
Simply, any function that has an access specificer of Public should have its description filled out.
If your project includes a plugin that defines static BlueprintCallable functions, they should have their category set to the plugin's name or a subset category of the plugin's name.
For example, Zed Camera Interface or Zed Camera Interface | Image Capturing.
This section covers things that apply to all Blueprint graphs.
Wires should have clear beginnings and ends. You should never have to mentally untangle wires to make sense of a graph. Many of the following sections are dedicated to reducing spaghetti.
Always align wires, not nodes. You can't always control the size and pin location on a node, but you can always control the location of a node and thus control the wires. Straight wires provide clear linear flow. Wiggly wires wear wits wickedly. You can straighten wires by using the Straighten Connections command with BP nodes selected. Hotkey: Q
Good example: The tops of the nodes are staggered to keep a perfectly straight white exec line.
Bad Example: The tops of the nodes are aligned creating a wiggly white exec line.
Acceptable Example: Certain nodes might not cooperate no matter how you use the alignment tools. In this situation, try to minimize the wiggle by bringing the node in closer.
If you ever have to decide between straightening a linear white exec line or straightening data lines of some kind, always straighten the white exec line.
Blocks of nodes should be wrapped in comments that describe their higher-level behavior. While every function should be well named so that each individual node is easily readable and understandable, groups of nodes contributing to a purpose should have their purpose described in a comment block. If a function does not have many blocks of nodes and its clear that the nodes are serving a direct purpose in the function's goal, then they do not need to be commented as the function name and description should suffice.
If a function or event assumes that a cast always succeeds, it should appropriately report a failure in logic if the cast fails. This lets others know why something that is 'supposed to work' doesn't. A function should also attempt a graceful recover after a failed cast if it's known that the reference being casted could ever fail to be casted.
This does not mean every cast node should have its failure handled. In many cases, especially events regarding things like collisions, it is expected that execution flow terminates on a failed cast quietly.
All nodes in all blueprint graphs must have a purpose. You should not leave dangling blueprint nodes around that have no purpose or are not executed.
This section will focus on Static Mesh assets and their internals.
Pretty simple. All meshes, regardless how they are to be used, should not be missing UVs.
Pretty simple. All meshes, regardless how they are to be used, should have valid non-overlapping UVs.
This is a subjective check on a per-project basis, but as a general rule any mesh that can be seen at varying distances should have proper LODs.
This is a subjective check on a per-asset basis, however any modular socketless assets should snap together cleanly based on the project's grid settings.
It is up to the project whether to snap based on a power of 2 grid or on a base 10 grid. However if you are authoring modular socketless assets for the marketplace, Epic's requirement is that they snap cleanly when the grid is set to 10 units or bigger.
Regardless of whether an asset is going to be used for collision in a level, all meshes should have proper collision defined. This helps the engine with things such as bounds calculations, occlusion, and lighting. Collision should also be well-formed to the asset.
This is a subjective check on a per-project basis, however all assets should be scaled correctly to their project. Level designers or blueprint authors should not have to tweak the scale of meshes to get them to confirm in the editor. Scaling meshes in the engine should be treated as a scale override, not a scale correction.
This section will focus on Niagara assets and their internals.
As mentioned in 00.1 Forbidden Identifiers, spaces and all white space characters are forbidden in identifiers. This is especially true for Niagara systems as it makes working with things significantly harder if not impossible when working with HLSL or other means of scripting within Niagara and trying to reference an identifier.
(Original Contribution by @dunenkoff)
See Terminology Note regarding "levels" vs "maps".
This section will focus on Level assets and their internals.
All levels should load with zero errors or warnings. If a level loads with any errors or warnings, they should be fixed immediately to prevent cascading issues.
You can run a map check on an open level in the editor by using the console command "map check".
It is normal during development for levels to occasionally not have lighting built. When doing a test/internal/shipping build or any build that is to be distributed however, lighting should always be built.
Levels should not have any z-fighting in all areas visible to the player.
This section will focus on Texture assets and their internals.
All textures, except for UI textures, must have its dimensions in multiples of powers of 2. Textures do not have to be square.
For example, 128x512, 1024x1024, 2048x1024, 1024x2048, 1x512.
All textures should be of a size appropriate for their standard use case. Appropriate texture density varies from project to project, but all textures within that project should have a consistent density.
For example, if a project's texture density is 8 pixel per 1 unit, a texture that is meant to be applied to a 100x100 unit cube should be 1024x1024, as that is the closest power of 2 that matches the project's texture density.
No texture should have a dimension that exceeds 8192 in size, unless you have a very explicit reason to do so. Often, using a texture this big is simply just a waste of resources.
Every texture has a Texture Group property used for LODing, and this should be set correctly based on its use. For example, all UI textures should belong in the UI texture group.
Copyright (c) 2016 Gamemakin LLC
See LICENSE