C++ utilities: output, errors and settings — documentation

For engine-core and module C++

These are Reckfell native facilities, not C# functions. Include the header declaring the facility and inspect neighboring module code. Use the public SDK at the C# boundary.

Output and formatting

Facility	Behavior
`print_line(...)`	Prints arguments converted to text
`print_verbose(text)`	Prints only when verbose output is enabled
`print_line_rich(...)`	Prints supported formatting markup; appearance depends on the receiver
`ERR_PRINT(message)` / `WARN_PRINT(message)`	Report an error/warning; do not themselves return from your function
`ERR_PRINT_ONCE(message)` / `WARN_PRINT_ONCE(message)`	Suppress repeated output from that call site, not globally deduplicate identical text
`vformat(format, ...)`	Returns a native String with substituted values

Check placeholder count and meaning. If a foreign API takes a UTF-8 pointer, retain the utf8() result in a live CharString; do not retain a pointer from a temporary buffer. See core types.

Declarations: core/string/print_string.h, core/string/ustring.h. Enable verbose launch output with --verbose; it does not replace Error checks or failure handling.

Localization

Facility	Use
`TTR(text, context)`	Translate editor text in a tools build
`RTR(text, context)`	Translate text during project execution
`TTRC(literal)`	Mark a C string for extraction; does not itself translate at the call site

Translate the template with placeholders first, then format with vformat. Substituting a filename or number first can prevent a catalog-key match. Do not move editor TTR into runtime code without considering TOOLS_ENABLED. Declarations are in core/string/ustring.h.

Settings

Facility	Purpose
`GLOBAL_DEF(key, default_value)`	Define a project setting with an initial value; do not assume this overwrites an existing user value
`GLOBAL_GET(key)`	Read a project setting with overrides applied
`EDITOR_DEF(key, default_value)`	Define an editor setting
`EDITOR_GET(key)`	Read an editor setting

Define a setting in a coordinated location and read it elsewhere. Check the returned Variant type. Project and editor settings are separate domains: an identical text key does not make them the same setting.

Declarations: core/config/project_settings.h, editor/settings/editor_settings.h. Check setting names/defaults in current code rather than an old menu location.

Errors and control flow

Facility	On failure
`ERR_FAIL_COND_MSG(condition, message)`	Logs an error and returns from a void function
`ERR_FAIL_COND_V_MSG(condition, value, message)`	Logs an error and returns value
`ERR_FAIL_INDEX_MSG(index, size, message)`	Checks a valid index and returns on failure
`ERR_FAIL_INDEX_V_MSG(index, size, value, message)`	Same with an explicit return value
`ERR_FAIL_MSG(message)` / `ERR_FAIL_V_MSG(value, message)`	Unconditional error and return
`CRASH_NOW_MSG(message)`	Terminates the process; not ordinary invalid-input handling

ERR_FAIL_COND takes a failure condition, not a success condition. A native return macro does not automatically become a C# exception at a wrapper boundary. Callers must understand the returned Error, empty reference or other failure value.

Choose a failure value distinguishable from success. Give operation context in the message; error output does not replace a function result. Implementation: core/error/error_macros.h; codes: core/error/error_list.h.

Bounds and time

In the current core, MIN, MAX and CLAMP are constexpr function templates in core/typedefs.h. Supply consistent types and ordered CLAMP bounds. Comparisons are not universal NaN, overflow or input-validity checks.

Time::get_singleton()->get_ticks_usec() provides a monotonic microsecond timestamp. Subtracting two timestamps measures elapsed time, not automatically CPU-only or GPU-only cost. A single measurement including loading, allocation or logging is not a stable benchmark. For game performance, start with frame-time measurement.

Time declaration: core/os/time.h. Temporary diagnostic logging inside the measured region itself changes the result.