Profiling and Debugging

Functions

c_debug_message

Print a message to the C debugger.

void c_debug_message(const string&in message);

Arguments:

• const string&in message: The message to print to the C debugger's console.

Example:

void main() {
	c_debug_message("I am a debug message");
	c_debug_break();
}

get_call_stack

Get the call stack (list of functions called) at the current point in time in your script.

string get_call_stack();

Returns:

string: a formatted list of the call stack.

Remarks:

In the context of a catch block, it's better to use the last_exception_call_stack property. If you use get_call_stack(), you'll get the callstack where you are in the try statement, as opposed to the call stack that actually caused the exception being caught.

Example:

// Define some example functions.
void test1() {test2();}
void test2() {test3();}
void test3() {
	alert("Call stack", get_call_stack());
}
void main() {
	test1();
}

get_call_stack_size

Get the size of the call stack.

int get_call_stack_size();

Returns:

int: the size of the call stack (i.e. how many functions deep are you currently?)

Remarks:

This function doesn't work in the context of exceptions. If you call it in a catch block, you'll most likely get the call stack in the try block, not what actually threw the exception.

Example:

void test1() {test2();}
void test2() {test3();}
void test3() {test4();}
void test4() {
	alert("Call stack size is", get_call_stack_size());
}
void main() {
	test1();
}

get_exception_file

Get the name/path of the source file where the exception occurred.

string get_exception_file();

Returns:

string: the name/path of the file where the exception was thrown.

Example:

void main() {
	try {
		// Throw an index-out-of-bounds error.
		string[] arr = {"a", "test"};
		string item = arr[2];
	}
	catch {
		alert("Exception file path", get_exception_file());
	}
}

get_exception_function

Get the Angelscript function signature of the function that threw the exception.

string get_exception_function();

Returns:

string: the Angelscript function signature of the throwing function.

Example:

void main() {
	try {
		// Throw an index-out-of-bounds error.
		string[] arr = {"a", "test"};
		string item = arr[2];
	}
	catch {
		alert("Exception function signature", get_exception_function());
	}
}

get_exception_info

Get informative information about an exception, for example "index-out-of-bounds".

string get_exception_info();

Returns:

string: information about the exception currently being caught.

Example:

void main() {
	try {
		// Throw an index-out-of-bounds error.
		string[] arr = {"a", "test"};
		string item = arr[2];
	}
	catch {
		alert("Exception info", get_exception_info());
	}
}

get_exception_line

Get the line an exception occurred on.

int get_exception_line();

Returns:

int: the line number the exception occurred on.

Example:

void main() {
	try {
		// Throw an index-out-of-bounds error.
		string[] arr = {"a", "test"};
		string item = arr[2];
	}
	catch {
		alert("Exception line", get_exception_line());
	}
}

is_debugger_present

Determines if your app is being ran through a debugger.

bool is_debugger_present();

Returns:

bool: true if a debugger is present, false otherwise.

Example:

void main() {
	bool present = is_debugger_present();
	if (present)
		alert("Info", "A debugger is present.");
	else
		alert("Info", "A debugger is not present.");
}

throw

Throws an exception with a particular message.

void throw(const string&in msg);

Arguments:

• const string&in msg: the message to include in your exception.

Remarks:

This is presently slightly limited, the only value of the exception you can set is the message. There are plans to expand this in the future.

Example:

void main() {
	throw("Something went horribly wrong");
}

Global Properties

last_exception_call_stack

Returns the call stack of the currently thrown exception.

string last_exception_call_stack;

Remarks:

In the context of a catch block, it's better to use this property over get_call_stack(). In a catch block, get_call_stack() will return the callstack where you are in the try statement, as opposed to the call stack that actually caused the exception being caught.

Example:

void test1() {test2();}
void test2() {throw("I am an exception");}
void main() {
	try {
		test1();
	}
	catch {
		alert("Call stack", last_exception_call_stack);
	}
}

SCRIPT_COMPILED

Determine if the script is compiled or not. I.e., are you running from source?

bool SCRIPT_COMPILED;

Example:

void main() {
	alert("Example", SCRIPT_COMPILED ? "The script is currently compiled" : "The script is not currently compiled");
}

SCRIPT_CURRENT_FILE

Returns the current file your script is running form.

string SCRIPT_CURRENT_FILE;

Example:

void main() {
	alert("Your script is contained in", SCRIPT_CURRENT_FILE);
}

SCRIPT_CURRENT_FUNCTION

Returns the signature of the current function in your script.

string SCRIPT_CURRENT_FUNCTION;

Example:

void main() {
	alert("The current function is", SCRIPT_CURRENT_FUNCTION);
	random_func("", 0, 0, 0);
}
// Function with random unused parameters to showcase the function signatures.
bool random_func(const string& in a, int b, uint64 c, uint8 = 1) {
	alert("The current function is", SCRIPT_CURRENT_FUNCTION);
	return true;
}

SCRIPT_CURRENT_LINE

Returns the current line in your script as it's executing.

string SCRIPT_CURRENT_LINE;

Example:

void main() {
	alert("The current line is", SCRIPT_CURRENT_LINE);
}

SCRIPT_EXECUTABLE

Returns the path of the executable running your script.

string SCRIPT_EXECUTABLE;

Remarks:

If you're running from source, this will return the path to your NVGT binary.

Example:

void main() {
	alert("The executable path of the script is", SCRIPT_EXECUTABLE);
}