Interface: IXR_profiler

Lua script profiler namespace.

Since

OpenXRay 2025-03-19, ac4ba75d, PR #1771

Source

namespace profiler

Remarks

Requires an engine script profiler instance. Starting an already active profiler is ignored by the engine.

Methods

get_type()

get_type(this: void): 0 | 1 | 2;

Parameters

Parameter	Type
this	void

Returns

0 | 1 | 2

Currently active profiler type.

---

is_active()

is_active(this: void): boolean;

Parameters

Parameter	Type
this	void

Returns

boolean

Whether lua scripts profiler is active.

---

log_report()

Call Signature

log_report(this: void): void;

Log report of profiler measurements in game console/log file. Use default engine limit to print top N entries.

Parameters

Parameter	Type
this	void

Returns

void

Call Signature

log_report(this: void, entries_limit: number): void;

Log report of profiler measurements in game console/log file.

Parameters

Parameter	Type	Description
this	void	-
entries_limit	number	Limit of top profiling entries to print.

Returns

void

---

reset()

reset(this: void): void;

Reset measurements data of profiler.

Parameters

Parameter	Type
this	void

Returns

void

Remarks

Reset keeps the current profiling mode active and clears collected samples.

---

save_report()

save_report(this: void): void;

Save report of profiler measurements in corresponding log/perf file.

Parameters

Parameter	Type
this	void

Returns

void

Remarks

Hook reports are saved under $logs$ as *_hook_profile.log. Sampling reports are saved as *_sampling_profile.perf.

---

start()

Call Signature

start(this: void): void;

Start lua scripts profiler in default mode.

Parameters

Parameter	Type
this	void

Returns

void

Remarks

The default mode is hook profiling.

Call Signature

start(this: void, profiler_type: TXR_ProfilerType): void;

Start lua scripts profiler of provided type.

Parameters

Parameter	Type	Description
this	void	-
profiler_type	TXR_ProfilerType	Type of profiler to start (note: see global exports of type constants).

Returns

void

Remarks

Passing PROFILER_TYPE_NONE does not start profiling and only logs a message.

---

start_hook_mode()

start_hook_mode(this: void): void;

Start profiler in hook mode. Profiling performance based on lua call start/end events.

Parameters

Parameter	Type
this	void

Returns

void

Remarks

Hook mode attaches a Lua hook. If another hook is already installed, start may fail and only log the failure.

---

start_sampling_mode()

Call Signature

start_sampling_mode(this: void): void;

Start profiler in sampling mode with default sampling interval.

Parameters

Parameter	Type
this	void

Returns

void

Remarks

Sampling mode uses LuaJIT profiling. It cannot start when LuaJIT profiling is unavailable, for example with -nojit.

Call Signature

start_sampling_mode(this: void, sampling_interval: number): void;

Start profiler in sampling mode with provided sampling interval value.

Parameters

Parameter	Type	Description
this	void	-
sampling_interval	number	Interval to collect samples with luaJIT sampling profiler.

Returns

void

Remarks

The engine clamps the interval to its supported range.

---

stop()

stop(this: void): void;

Stop currently active profiler.

Parameters

Parameter	Type
this	void

Returns

void

Remarks

Stopping clears collected profiling data. Calling it while inactive only logs a message.