Макросы UE4

```

Если значение *expr* ложно, эти макросы вызывают выдачу сообщения в лог и аварийное завершение программы (со всякими нюансами, связанными с отладкой и т.п.).

Макросы checkf/checkfSlow отличаются от простых check/checkSlow выдачей указанного сообщения с параметрами.

Если движок собран без контроля, эти макросы никаких действий не выполняют (в отличие от макросов группы verify).

Макросы, оканчивающиеся на Slow, выполняют свои функции при определённом символе DO\_GUARD\_SLOW (определён только для отладочных сборок движка), а макросы без Slow — при определённом символе DO\_CHECK (определён как в отладочных сборках, так и в сборках для разработки игры, но не определён в релизных сборках). По действиям они полностью идентичны.

### UE\_CLOG

```
UE_CLOG(Condition, CategoryName, Verbosity, Format, ...)

```

Если *Condition* правда, в лог выдаётся заданное сообщение. При этом, если *Verbosity* указывает на фатальную ошибку, выполнение программы завершается.

Похоже, что возможна компиляция без поддержки лога, однако обработка фатальных сообщений всё равно будет выполняться.

### UE\_LOG

```
UE_LOG(CategoryName, Verbosity, Format, ...)

```

В лог выдаётся заданное сообщение. При этом, если *Verbosity* указывает на фатальную ошибку, выполнение программы завершается.

Похоже, что возможна компиляция без поддержки лога, однако обработка фатальных сообщений всё равно будет выполняться.

### verify

```
verify(expr)
verifyf(expr, format,  ...)
verifySlow(expr)
verifyfSlow(expr, format,  ...)

```

Если значение *expr* ложно, эти макросы вызывают выдачу сообщения в лог и аварийное завершение программы (со всякими нюансами, связанными с отладкой и т.п.).

Макросы verifyf/verifyfSlow отличаются от простых verify/verifySlow выдачей указанного сообщения с параметрами.

Если движок собран без контроля, эти макросы не вызывают выдачи информации и завершения программы, однако, в отличие от макросов группы check), значение выражения *expr* вычисляется всегда.

Макросы, оканчивающиеся на Slow, выполняют свои функции при определённом символе DO\_GUARD\_SLOW (т.е. только в отладочных сборках), а макросы без Slow — при определённом символе DO\_CHECK (в отладочных сборках и сборках для разработки игры). По действиям они полностью идентичны.

## Макросы сбора статистики

### DEFINE\_STAT

```
DEFINE_STAT(Stat)

```

Определяет глобальную переменную с именем StatPtr\_*Stat*, которая используется для потокобезопасного сбора какой-либо статистики. Параметр Stat задаёт имя собираемой статистической информации. Например, имя STAT\_ConstructObject используется для учёта времени, расходуемого на создание объектов.

### SCOPE\_CYCLE\_COUNTER

```
SCOPE_CYCLE_COUNTER(Stat)

```

Этот макрос используется для подсчёта времени работы некоторого фрагмента кода, как правило — отдельной функции. Он размещается в самом начале блока кода (сразу после «{»). Параметр Stat задаёт имя собираемой статистической информации. Например, имя STAT\_ConstructObject используется для учёта времени, расходуемого на создание объектов; оно используется во внутренней функции StaticConstructObject\_Internal, которая косвенно вызывается из, например, шаблонной функции NewObject.

Технически этот макрос создаёт локальную переменную, конструктор и деструктор которой соответственно засекают время начала и конца жизни переменной, т.е. начала и конца выполнения кода блока, в котором макрос расположен. Это время добавляется к соответствующей глобальной переменной сбора статистики, где-либо определённой с помощью макроса DEFINE\_STAT.

## Макросы модульности

### IMPLEMENT\_GAME\_MODULE

```
IMPLEMENT_GAME_MODULE(ModuleImplClass, ModuleName)

```

Этот макрос должен использоваться вместо обычного IMPLEMENT\_MODULE в модулях, содержащих код игры, а не собственно движка.

Технически данный макрос вызывает макрос IMPLEMENT\_MODULE, не генерируя никакого собственного кода.

### IMPLEMENT\_MODULE

```
IMPLEMENT_MODULE(ModuleImplClass, ModuleName)

```

Этот макрос предназначен, чтобы известить движок в целом о существовании некоторого модуля и его главного класса и обеспечить его инициализацию. Он должен включаться в каждый модуль, потенциально собираемый в независимую DLL, однако он работает и для монолитной сборки.

В случае монолитной сборки данный макрос обеспечивает инициализацию модуля (технически являющегося частью exe-файла) и его регистрацию в движке, создавая статическую переменную с помощью шаблонного класса FStaticallyLinkedModuleRegistrant. Поскольку переменная является статической, вызов соответствующего конструктора производится компилятором автоматически до начала выполнения основного кода программы (WinMain и т.п.). Этим же макросом определяется не выполняющая никаких реальных действий функция инициализации модуля.

В случае модульной сборки макрос IMPLEMENT\_MODULE генерирует стандартную функцию инициализации независимого модуля InitializeModule, единственной задачей которой является динамическое создание (с помощью оператора new) экземпляра главного класса модуля и возврат указателя на него вызывающей программе (коду движка, отвечающему за загрузку и инициализацию модулей). Кроме того, вызывается макрос PER\_MODULE\_BOILERPLATE, обеспечивающий переопределение операторов динамического выделения и освобождения памяти для данного модуля (в случае с монолитной сборкой этот макрос не вызывается, поскольку он должен вызываться лишь один раз для исполняемого файла).

Независимо от вида сборки макрос IMPLEMENT\_MODULE вызывает макрос PER\_MODULE\_BOILERPLATE\_ANYLINK. В текущей версии движка последний не генерирует никакого кода, однако при необходимости он может быть определён создателем конкретного приложения.

### PER\_MODULE\_BOILERPLATE

```
PER_MODULE_BOILERPLATE

```

Этот макрос включает в модуль необходимый общий код. Если собирается монолитный проект, требуется использовать данный макрос только один раз (так, в случае с редактором UE4 для Windows он включается в файле Launch.cpp, причём используется условная трансляция – только для редактора и только при монолитной сборке). Если собирается модульный проект, этот макрос должен использоваться по одному разу в каждом модуле (как правило, в головном cpp-файле модуля).

Основную часть тела макроса составляют определения глобальных переменных, используемых для отладки:

* GFNameTableForDebuggerVisualizers
* GFNameTableForDebuggerVisualizers\_MT
* GSerialNumberBlocksForDebugVisualizers
* GObjectArrayForDebugVisualizers
* GFNameDebuggerVisualizersIsUE3

Помимо этих переменных, выполняется переопределение операторов выделения и освобождения памяти с помощью макроса REPLACEMENT\_OPERATOR\_NEW\_AND\_DELETE.

Как правило, этот макрос не используется прямо; вместо него в модуле вызывается макрос IMPLEMENT\_MODULE. Однако в монолитной сборке он должен вызываться явно, но только один раз.

### PER\_MODULE\_BOILERPLATE\_ANYLINK

```
PER_MODULE_BOILERPLATE_ANYLINK(ModuleImplClass, ModuleName)

```

Этот макрос должен встречаться один раз в любом модуле независимо от того, какой собирается движок – модульный (состоящий из exe-файла и группы dll-файлов) или монолитный (только exe-файл). Если он не определён, в файле ModuleBoilerplate.h он определяется как пустой.

Как правило, нужды в прямом использовании этого макроса нет: он включается в модуль в макросе IMPLEMENT\_MODULE.

### REPLACEMENT\_OPERATOR\_NEW\_AND\_DELETE

```
REPLACEMENT_OPERATOR_NEW_AND_DELETE

```

Этот макрос включается один раз в любой независимый (создаваемый как отдельный dll-файл) модуль и переопределяет операторы new, new[], delete и delete[]. Такое переопределение необходимо, чтобы все компоненты игры использовали одни и те же низкоуровневые подпрограммы выделения и освобождения памяти, реализованные в классе FMemory.

Как правило, использовать этот макрос в явном виде не требуется: он включается в состав модуля с помощью макроса PER\_MODULE\_BOILERPLATE, а последний, в свою очередь, – макросом IMPLEMENT\_MODULE.

## Макросы управления условной трансляцией

Значительная часть этих макросов определяется через командную строку и/или формируется в файле Build.h.

### Управление отладочными средствами

При любой сборке один и только один из следующих четырёх макросов должен быть равен единице, другие три должны быть равны нулю. Эти макросы определяют, какой уровень отладочных средств будет включаться в код движка и игры в процессе трансляции.

#### UE\_BUILD\_DEBUG

Максимальный уровень отладочных средств: сборка предназначена для отладки кода движка.

#### UE\_BUILD\_DEVELOPMENT

В код включаются все отладочные средства, кроме самых медленных: сборка предназначена для разработки игры.

#### UE\_BUILD\_SHIPPING

Отладочные средства в код не включаются: сборка предназначена для конечных пользователей.

#### UE\_BUILD\_SHIPPING\_EDITOR

Похоже, этот символ устарел. По умолчанию его использование приведёт к ошибке компиляции.

#### UE\_BUILD\_TEST

В код включается небольшой набор отладочных средств: сборка предназначена для тестирования созданной игры.

### Управление видами создаваемой программы

#### UE\_EDITOR

Равен единице, если собирается редактор, и нулю, если собирается игра. Взаимоисключающий с макросом UE\_GAME?

#### UE\_GAME

Равен единице, если собирается игра, и нулю, если собирается редактор. Взаимоисключающий с макросом UE\_EDITOR?

#### UE\_SERVER

Равен единице, если выполняется сборка кода для выделенного сервера, и нулю, если собирается код клиента или монолитной игры (не использующей клиент-серверную модель).

### Управление включаемыми возможностями

#### HACK\_HEADER\_GENERATOR

Равен единице, если необходимо генерировать некоторую дополнительную информацию для UHT (Unreal Header Tool).

#### IS\_MONOLITHIC

Равен единице, если создаётся монолитная сборка (весь код включается в единый exe-файл, а не разбит на несколько dll-файлов).

#### IS\_PROGRAM

Равен единице, если создаётся программа (компилятор шейдеров, файл-сервер и т.п.), а не игра или околоигровое приложение.

#### UE\_BUILD\_MINIMAL

Равен единице, если нужно включать лишь минимально необходимый объём функционала.

#### WITH\_AUTOMATION\_WORKER

Равен единице, если включается функциональность Automation Worker. По умолчанию она включается, для отладочной или разработочной сборки (оба макроса UE\_BUILD\_SHIPPING и UE\_BUILD\_TEST равны нулю) при условии, что не генерируется дополнительная информация для UHT (макрос HACK\_HEADER\_GENERATOR равен нулю).

#### WITH\_EDITOR

Равен единице, если в программу включается код редактора.

#### WITH\_ENGINE

Равен единице, если в программу включается код движка.

#### WITH\_HOT\_RELOAD

Равен единице, если включается поддержка «горячей» перезагрузки модулей. По умолчанию это так для любых модульных сборок, кроме релизной версии (макросы IS\_MONOLITHIC и UE\_BUILD\_SHIPPING равны нулю).

#### WITH\_HOT\_RELOAD\_CTORS

Равен единице, если используются специальные пустые конструкторы, предназначенные для «горячей» перезагрузки модулей.

В настоящее время всегда равен единице.

#### WITH\_PLUGIN\_SUPPORT

Равен единице, если включается поддержка плагинов.

#### WITH\_UNREAL\_DEVELOPER\_TOOLS

Равен единице, если в программу включается код средств разработки.

### Управление проверками

#### ALLOW\_DEBUG\_FILES

Если равен единице, из собираемой программы оказывается возможным сохранять отладочные файлы – скриншоты, результаты профилирования и т.п.

Равен единице во всех сборках, кроме релизной сборки без редактора.

#### CHECK\_PUREVIRTUALS

Равен единице, если необходимо проверять, действительно ли реализованы методы, объявленные абстрактными («чистые виртуальные функции» в терминологии Си++) в базовых классах. По умолчанию равен нулю.

#### DO\_CHECK

Если равен единице, в код включаются проверки, осуществляемые макросами checkCode, check, checkf, checkNoEntry, checkNoReentry, checkNoRecursion, verify, verifyf, ensure, ensureAlways, ensureAlwaysMsgf и ensureMsgf.

Всегда равен единице в отладочных и разработочных сборках. В тестовых сборках он равен значению макроса USE\_CHECKS\_IN\_SHIPPING, а в релизных сборках – единице, если создаётся сборка с редактором, или макросу USE\_CHECKS\_IN\_SHIPPING, если сборка не включает редактор.

#### DO\_GUARD\_SLOW

Если равен единице, в код включаются проверки, осуществляемые макросами checkSlow, checkfSlow и verifySlow.

Равен единице только в отладочных сборках (макрос UE\_BUILD\_DEBUG равен единице).

#### LOOKING\_FOR\_PERF\_ISSUES

Равен единице, если нужно включать код, проверяющий на возможные проблемы с производительностью. Этот код сам по себе медленный, поэтому его использование рекомендуется лишь тогда, когда это реально необходимо.

По умолчанию этот макрос равен нулю.

#### NO\_LOGGING

Если равен единице, протокол и вывод текстовых сообщений отключён.

Равен единице только в тестовой сборке и релизной сборке без редактора, причём в обоих случаях лишь тогда, когда макрос USE\_LOGGING\_IN\_SHIPPING равен нулю.

#### STATS

Если равен единице, в код включается сбор статистики.

Обычно равен единице для отладочных и разработочных сборок (но может быть равен нулю, если создаётся минимальная сборка или сборка только с данными редактора). Для тестовой сборки равен нулю, для релизной – единице при сборке с редактором и нулю без такового.

#### UE\_BLUEPRINT\_EVENTGRAPH\_FASTCALLS

Когда равен единице, для графов событий без параметров в блупринтах используется быстрый вызов.

Равен единице.

#### USE\_CHECKS\_IN\_SHIPPING

Равен единице, если в релизной сборке должны присутствовать проверки. По умолчанию равен нулю.

#### USE\_LOGGING\_IN\_SHIPPING

Равен единице, если в релизной сборке должен использоваться вывод протокола. По умолчанию равен нулю.

#### USE\_NETWORK\_PROFILER

Когда равен единице, включаются средства профилирования производительности сетевой подсистемы.

Значение этого макроса совпадает со значением макроса STATS.

#### USE\_UBER\_GRAPH\_PERSISTENT\_FRAME

Когда равен единице, включается механизм UberGraphPersistentFrame, ускоряющий компиляцию блупринтов в редакторе, но влекущий лишние накладные расходы.

Равен единице.