Служебные функции C++: вывод, ошибки и настройки

Нативные контракты, владение данными и отличие от C# API.

Для C++ ядра и модулей

Это нативные средства Reckfell, не набор функций C#. Подключайте заголовок с нужным объявлением и сверяйте соседний код модуля. На границе с C# используйте публичный SDK.

Вывод и форматирование

Средство	Поведение
`print_line(...)`	Выводит аргументы, преобразованные в текст
`print_verbose(text)`	Выводит сообщение только при включённом подробном выводе
`print_line_rich(...)`	Выводит поддерживаемую форматированную разметку; отображение зависит от приёмника
`ERR_PRINT(message)` / `WARN_PRINT(message)`	Сообщают об ошибке/предупреждении; сами по себе не выполняют возврат из вашей функции
`ERR_PRINT_ONCE(message)` / `WARN_PRINT_ONCE(message)`	Подавляют повторный вывод из данной точки вызова; это не глобальная дедупликация одинакового текста
`vformat(format, ...)`	Возвращает нативный String с подставленными значениями

Проверяйте число и смысл заполнителей формата. Если сторонний API принимает UTF-8 указатель, храните результат utf8() в живом CharString; не сохраняйте указатель из временного буфера. См. базовые типы.

Объявления: core/string/print_string.h, core/string/ustring.h. Подробный вывод запуска включается через --verbose; он не заменяет проверку Error и обработку отказа.

Локализация

Средство	Применение
`TTR(text, context)`	Перевод редакторского текста в tools-сборке
`RTR(text, context)`	Перевод текста во время выполнения проекта
`TTRC(literal)`	Маркер извлечения C-строки; сам не выполняет перевод во время вызова

Сначала переводите шаблон с заполнителями, затем форматируйте его через vformat. Если сначала подставить имя файла или число, полученная строка может не совпасть с ключом каталога. Не переносите редакторский TTR в runtime-код без учёта TOOLS_ENABLED. Исходные объявления — в core/string/ustring.h.

Настройки

Средство	Назначение
`GLOBAL_DEF(key, default_value)`	Определить настройку проекта с исходным значением; существующее пользовательское значение не следует считать перезаписанным этим вызовом
`GLOBAL_GET(key)`	Прочитать настройку проекта с применением переопределений
`EDITOR_DEF(key, default_value)`	Определить настройку редактора
`EDITOR_GET(key)`	Прочитать настройку редактора

Определяйте настройку в согласованном месте, а в остальных местах читайте её. Проверяйте тип полученного Variant. Настройки проекта и редактора — разные области: одинаковое текстовое имя не делает их одной настройкой.

Объявления: core/config/project_settings.h, editor/settings/editor_settings.h. Соглашение имени настройки и значение по умолчанию проверяйте в текущем коде, а не по старому положению пункта меню.

Условия ошибки и поток выполнения

Средство	При срабатывании
`ERR_FAIL_COND_MSG(condition, message)`	Выводит ошибку и делает `return` из функции без возвращаемого значения
`ERR_FAIL_COND_V_MSG(condition, value, message)`	Выводит ошибку и возвращает указанный value
`ERR_FAIL_INDEX_MSG(index, size, message)`	Проверяет допустимый индекс и возвращается при ошибке
`ERR_FAIL_INDEX_V_MSG(index, size, value, message)`	То же с явным возвращаемым значением
`ERR_FAIL_MSG(message)` / `ERR_FAIL_V_MSG(value, message)`	Безусловное сообщение и возврат
`CRASH_NOW_MSG(message)`	Аварийно завершает процесс; это не обработка обычного неверного ввода

Условие ERR_FAIL_COND — условие ошибки, не условие успеха. Нативный макрос возврата не превращается автоматически в исключение C# на границе обёртки. Вызывающий код должен понимать возвращённый Error, пустую ссылку или иное значение отказа.

Выбирайте возвращаемое значение так, чтобы оно не выглядело как успешный результат. Сообщение должно содержать контекст операции; поток ошибок не заменяет результат функции. Реализация — core/error/error_macros.h, коды — core/error/error_list.h.

Ограничение значений и время

MIN, MAX и CLAMP в текущем ядре — constexpr-шаблонные функции из core/typedefs.h. Для CLAMP задавайте согласованные типы и упорядоченные границы. Сравнения не являются универсальной проверкой NaN, переполнения или допустимости входных данных.

Time::get_singleton()->get_ticks_usec() позволяет получить монотонную отметку времени в микросекундах. Разность двух отметок измеряет прошедший интервал, а не автоматически стоимость только CPU или GPU. Один замер с загрузкой, выделением памяти или логированием не является устойчивым результатом бенчмарка. Для игровой производительности начните с измерения времени кадров.

Объявление времени — core/os/time.h. Временное диагностическое логирование внутри измеряемого участка само меняет результат.