Script Debugging

When a compile-time error occurs, it means that the interpreter could not parse and load the script. In this case, the log file will contain an error message with:

1. A source code string with an invalid statement.
2. An error description from the interpreter.

Mismatched curly braces are the most frequent compile-time error. For example:

class Foo {		
	Foo(int a) {
		this.a = a;
	// missing closing curly brace
	~Foo() {}	
	
	void print() {
		log.message("a is %d\n",a);
	}
};

Parser::check_braces(): some errors with count of '{' and '}' symbols
Parser::preprocessor(): wrong number of braces

Among the obvious errors like incorrect syntax, there are some not so evident and more confusing. The most important are:

• Recursive includes are not tracked, so be careful with file inclusions and use defines when in doubt.
• In user class definitions make sure that all member variables are declared before they are used in a constructor or a method.
  Source code (UnigineScript)

  class Foo {		
  	Foo(int a) {
  		this.a = a;
  	}	
  	
  	~Foo() {}	
  	
  	void print() {
  		log.message("a is %d\n",a);
  	}
  };

  Variable a is not declared, so an error occurs:
  Output

  Interpreter::parse(): unknown "Foo" class member "a"

• The following and alike complex expressions lead to errors:
  Source code (UnigineScript)

  object.doSomething().doSomethingElse();
  object.doSomething()[4];

  For the first expression, the following error message occurs:
  Output

  Parser::expectSymbol(): bad '.' symbol expecting end of string

  For the second expression, the error message is:
  Output

  Parser::expectSymbol(): bad '[' symbol expecting end of string

  The point is that due to a dynamic typing the interpreter does not know what will be returned by object.doSomething(), maybe, even nothing, and that may lead to a run-time error.

When a run-time error occurs, it usually means that you are trying to manipulate a corrupt or even a non-existent object. In this case, the log file will contain an error message with:

1. An error description from the interpreter.
2. Current stack of function calls.
3. An assembly dump of an invalid statement.

Interpreter::run(): "int: 0" is not an extern class
Call stack:
00: 0x0001a84c update()
01: 0x00016565 nodesUpdate()
02: 0x0001612c Nodes::update()
Disassemble:
0x00016134: callecf  Node.getName
0x00016137: pop
0x00016138: pushv    parameters_tb
0x0001613a: callecf  WidgetTabBox.getCurrentTab

Common run-time errors:

• NULL objects. Please, don't forget to initialize declared objects and check the values returned from functions.
• Stack underflow (or overflow) when less (or more) arguments than required are provided to a function.
• Dynamic typing allows assigning a value of one type to a variable of another, for example:
  Source code (UnigineScript)

  // the following is ok
  Object object = new ObjectMesh("file.mesh");
  object = new LightWorld(vec4_one);

  However, people tend to forget what they've assigned to a variable and call inappropriate methods:
  Source code (UnigineScript)

  // the following is NOT ok, as object is not of type ObjectMesh any more
  Material m = object.getMaterial(0);

  In this case, the error message is:
  Output

  ExternClass::run_function(): can't find "class Object * __ptr64" base class in "class LightWorld * __ptr64" class

• When creating a vector, make sure you provide a correct capacity (non-negative). If the negative capacity is specified, a vector size is set to 0 by default.

  Also, when addressing vector contents, make sure an index being used exists; the same is true for maps and their keys. Also, a map key cannot be NULL.

  Source code (UnigineScript)

  int vector[2] =	( 1, 2, 3 );	// vector of 3 elements is defined
  log.message("%d\n", vector[4]);	// addressing the 4th component, which doesn't exist

  In this case, the error message is:
  Output

  UserArray::get(): bad array index 4

• Make sure you use correct swizzles with proper objects. For example, you cannot use swizzles with scalar types.
  Source code (UnigineScript)

  int a = 10;	// value of the scalar type	
  log.message("%d\n", a.x); // swizzling

  The exapmle produces the following error message:
  Output

  Variable::getSwizzle(): bad component 0 for int variable

• If a user class overloads some operator, do not forget to preserve the order of operands in the code:
  Source code (UnigineScript)

  class Foo {
  	int f;
  	Foo(int f = 0) {
  		this.f = f;
  	}
  	int operator+(Foo arg1,int arg2) {
  		return arg1.f + arg2;
  	}
  };
  
  // this is ok
  int ret = new Foo() + 5;
  
  // this is NOT ok
  ret = 5 + new Foo();

  The example produces an error:
  Output

  Variable::add(): bad operands int and user class

• Make sure that if you use wait control structure in the class method, this class method is called as a static one.
  Source code (UnigineScript)

  class Foo {
  
  	void update() { 
  		while(true) wait 1; 
  	}
  };
   
  Foo f = new Foo();
  Foo::update();		// this is valid, because the method is called as a static function
  f.update();		// this would cause a crash, because a class instance is passed

  The error message is:
  Output

  Interpreter::runFunction(): depth of stack is not zero

• Use class_cast() with caution. Remember that it converts an instance of one user class to another without warnings, even if those classes have nothing in common.
• Lots of transient objects. This is not exactly an error, but if you create in a short period plenty of user class objects that soon become unused, the performance will drop every 32 frames because of garbage collector clean-ups, until all unused objects are gone. In this case, the performance drop will be caused by both a multitude of objects and expensive object destruction.

To invoke the console debugger, insert a breakpoint; instruction in the script you are working on. This type of instructions used for the precise breakpoints placing. You can insert more than one breakpoint; instruction in your script.

For example:

int a = 10;
breakpoint;	// the breakpoint instruction
int b = 1;
forloop(int i = 0; a){
	b += i;
	log.message("Iteration: %d\n",i);
	log.message("Value: %d\n",b);
}

When a breakpoint is encountered, the engine execution stops, and the application stops responding to user actions. Instead, the external console starts receiving user input.

In this console, you can step through instructions using the next command. Also it is possible to set the breakpoint during the debug process by using the break command. It is useful, for example, when you debug a loop. Or you can run the other debugger commands, if necessary.

If the console is unavailable, as in Windows release builds, this will seem as a hang-up of the engine. To avoid that, use a "breakpoint" macro defined in the file data/core/unigine.h. This macro also correctly preserves FPS values.

There is also a way to set a run-time per-function interpreter breakpoints with the specified number of arguments via the editor console. A required script instruction is triggered for breakpoint, so the engine execution stops and the external console starts to receive the user input. Moreover, it is also possible to set the breakpoint flag inside the debugger.

There are 3 types of such breakpoints: system_breakpoint, world_breakpoint and editor_breakpoint, used for system, world and editor scripts respectively.

The syntax to set the breakpoint is the following: system_breakpoint/world_breakpoint/editor_breakpoint set/remove function_name number_of_arguments.

For example, to set the breakpoint on the custom function with zero arguments printMyMessage(), type in the editor console the following:

world_breakpoint set printMyMessage 0

The debugger also supports limited autocompletion and history of commands.

With the debugger, you cannot:

• Call functions.
• Evaluate arbitrary expressions.
• Retrieve map values by arbitrary keys. Only int, float,and string keys are supported.

The debugger supports several console commands listed below.

help#

run#

next#

breakpoint;	// here the breakpoint is set
int a = 10;	
int b = 1;
int vector [3] = ( 1, 2, 3, 4);
forloop(int i = 0; a){
	b += i;
	log.message("Iteration: %d\n",i);
	log.message("Value: %d\n",b);
}

Breakpoint at 0x00000455: setvc a = int: 10
# next
Breakpoint at 0x00000458: setvc b = int: 1

stack#

calls#

dasm#

# dasm
Disassemble:
0x00000465: addvv	b i
0x00000468: popv	b
0x0000046a: pushv	i
0x0000046c: pushc	string: "Iteration: %d\n"
0x0000046e: callefr	log.message
0x00000470: pushv	b
0x00000472: pushc	string: "Value: %d\n"
0x00000474: callefr	log.message

info#

# info a b vector
a: int: 3
b: int: 1
vector: Vector of 4 elements
0: int: 1
1: int: 2
2: int: 3
3: int: 4
# info vector[1]
vector[1]: int: 2

list#

fault#

break#

int a = 10;
int b = 1;
forloop(int i = 0; a){
	b += i;
	log.message("Iteration: %d\n",i);
	log.message("Value: %d\n",b);
}

Breakpoint at 0x00000455: setvc a = int: 10
# next
Breakpoint at 0x00000458: setvc b = int: 1
# break

Disassemble:
0x00000458: ! setvc	b = int: 1
0x00000468:	  setvc	i = int: 0

Breakpoint at 0x00000455: setvc a = int: 10
# next
Breakpoint at 0x00000458: setvc b = int: 1
# break
# break

Here is a list of assembly mnemonics for the assembly dump.

Set operations:

0x00000458: setvc b = int: 1

Pop operations:

0x00000468: popv	b

Push operations:

0x0000046c: pushc	string: "Iteration: %d\n"

Call operations:

0x0000046e: callefr	log.message

Math operations:

0x0000044c: mulvc	a int: 1

0x0000044c: mulvc	a int: 2

0x0000046b: shlc	int: 1

0x00000462: borvv	a b

0x00000461: lev	b

Branch operations:

0x00000456: jnevv	a b 0x0000045f

Loops: