Defining Rules

Rules describe the naming convention for your project. This article discusses the structure of a rule and describes different methods for defining them.

Structure of a rule

At a minimum, a rule is comprised of an asset class and the desired prefix for assets of the target class. A rule can optionally specify a desired suffix. It can also specify deprecated prefixes and suffixes that should be removed by the linter before applying the desired prefix and suffix.

The following example describes a rule that requires Character assets to have the CH_ prefix. It also tells the linter to strip the deprecated prefixes Char_ and CHAR_ before applying the desired prefix.

class = "Character"
prefix = "CH_"
deprecated_prefixes = [ "Char_", "CHAR_" ]

When this rule is applied to a Character asset named CHAR_Sly, the asset will be renamed to CH_Sly. When this rule is applied to a Character asset named CH_Bentley, the linter will make no change, as the asset already conforms to the rule.

Note: The plugin does not prevent you from defining rules with conflicting or overlapping prefixes. It is up to you to make sure that each asset type has a unique prefix.

Finding the right class

To target a given asset with a rule, you need to first identify the class of that asset. To do so, open the Content Browser in the Unreal Engine Editor and navigate to the target asset. Hover over the asset with your cursor, and find the Parent Class field in the details panel that appears. For parent classes defined in code, the value will be an uninterrupted alphabet string (such as Character or Actor). Use this value verbatim as the target class. For parent classes defined in Blueprints, the value will be the full path to the class (such as /Prefixed/Test/Murray.Murray_C). In this case, use the last segment of the path (in this example, Murray_C).

Class fallback

Prefixed tries to apply the most specific rule for a given asset but falls back to a more general rule when no specific rule exists. For example, if you have two rules, one for Actor and one for Character, and you apply these rules to a Character asset, Prefixed will judge the asset using the Character rule since it is the closest parent class. However, if you only define a rule for Actor, the plugin will fall back to this rule for the asset (since it is now the closest parent class). This allows you to lean on general rules (e.g., all Actors should start with ACT_) until you need more specific ones (e.g., unless it is a Warrior, in which case it should start with WAR_).

Methods for defining rules

Rules can be defined using standard Engine settings (recommended) or using .prefix files.

Defining rules in Engine settings

Rules can be defined using standard Engine settings (.ini files). This is the recommended approach and is preferred to defining rules in .prefix files. To define rules in this manner, open the Project Settings menu in the Unreal Engine Editor (Edit > Project Settings), and navigate to the Config Rules field (Editor > Prefixed > Config Rules). You can use the interface provided here to specify one or more rules. Rules defined here are saved to DefaultEditor.ini, which is located in the Config folder of the current project.

You can also manually define rules in that file under the [/Script/Prefixed.PrefixedSettings] section. To identify the right syntax, define a rule through the Editor and copy the format of the resulting rule in the config file. You can also define rules that apply to all projects using a given Engine by adding rules to BaseEditor.ini instead (located in the Config folder of the Engine).

Installing default rules

The Unrealistic Style Guide defines a set of rules that covers most of the core Engine classes and serves as a good starting point if you do not already have your own naming convention. You can install these rules to the current Engine by navigating to the menu bar and selecting Install Default Rules (Tools > Install Default Rules). Rules will be installed to BaseEditor.ini. You may need to restart the Editor before changes will be reflected.

Defining rules in .prefix files

(Warning) The following documentation describes the process of defining rules using the legacy JSON format. This format has been deprecated in favor of rules specified in standard Engine config files (INI format) to reduce context-switching and to take advantage of the native Engine config system. Config-based rules can be specified in the Prefixed section of the Project Settings menu in the same manner as other settings. Legacy rules should be migrated to the new config-based format to avoid disruption. Support for legacy rules will be removed in Unreal Engine 5.4. To automate the migration process, use the migration tool provided at Tools > Prefixed > Migrate Legacy Rules in the Unreal Engine Editor.

While the Unrealistic Style Guide will cover the naming of most standard Engine assets, it does not handle project- or plugin-specific assets. Fortunately, Prefixed allows you to easily define your own asset naming rules or tweak pre-existing rules to fit your needs.

You can define as many or as few rules as you would like in .prefix files, which should use JSON format.

Required elements of a rule

The two required elements for a rule are a class and a prefix.

Class

The class is the type of asset that we want to define a rule for. For C++ classes, use the core class name without any modifiers. For example:

• UStaticMesh -> StaticMesh
• APlayerController -> PlayerController

For Blueprint classes, just use the full class name as it appears in Editor.

Prefix

The prefix is usually a short combination of letters that hints at the type of asset it represents. For example:

• StaticMesh -> SM_
• PlayerController -> PC_

Prefixed does not prevent you from defining rules with conflicting or overlapping prefixes. It is up to you to make sure that each asset type has a unique prefix.

Optional Elements of a Rule

There are also several optional elements for a rule, including suffix and fields for deprecated modifiers.

Suffix

The suffix is optional. It should not be used as a substitute for a unique asset type prefix. Instead, it should be used to clarify sub-types of an asset type. For example, all Textures should have the same prefix (e.g. T_), but depending on the type of texture it is (diffuse, alpha, metallic, etc.) it should have an appropriate suffix (e.g. _D, _A, _M, etc.).

Deprecated Modifiers

The dep_prefixes and dep_suffixes fields, which should be arrays of strings, may be used to specify prefixes or suffixes that have been deprecated but may still exist on your assets. For example, if all of your static meshes have the S_ prefix but should now have the SM_ prefix, you can indicate this in the rule and the linter will automatically pull out the deprecated prefix when renaming.

Example: Character

Below is what the rule would look like if you wanted subclasses of Character to have the prefix CH_.

{
  "class": "Character",
  "prefix": "CH_",
  "dep_prefixes": [
    "Char_",
    "CHAR_"
  ]
}

Overriding Rules

Keep in mind that newer rules will override older rules. This means that even if you have Engine-wide rule that Character's should have a CH_ prefix, you can override that in a project rule file that sets the prefix to CHAR_.

Hot Reloading

You do not need to restart the Editor every time you add, delete, or modify a naming rule. Prefixed detects these changes and prompts you to reload the rule set.

Click the option to Update Rule Set to bring the Editor rule set up to date.