Scripting API

Home Scripting API Index

Tips and Tricks

This page gives some tips and tricks that may help to write error free and efficient code.

Use the message window

You can write messages to the message window using either 'System.out' or 'System.err'. This might help in debugging scripts or to display error messages. Messages printed to System.err will be displayed as error messages.

Example A: System.out.println("Hello World");
Example B: System.err.println("My Error Text");

Hide objects with 'setVisible(false)'

When you want to hide scene objects, do not hide objects by setting a very small scale or by moving them out of the scene. Those tricks will work to hide the object, but they are not very fast. Use SceneObjectElement.setVisible(false) instead. This is much much faster.

Optimize loops by hand

Optimizing loops will typically have the largest benefit on better performance. The script engine's compiler is not very good at optimizing loops automatically. Move as much code that can be precomputed out of the loop's body as you can.

Declare Constants as 'static final'

By declaring constants as 'static final' outside of methods, those fields can be accessed faster than other type of fields.

Avoid using 'double' and 'long'

Use 'double' and 'long' built-in types only if you really need the extra precision. Otherwise use the 32-bit types 'float' and 'int'. 'float' and 'int' are faster than their 64-bit counterparts, because the script engine internally is otimized for 32-bit types. Using 'byte' or 'short' is typically not faster than using 'int', only for arrays those are treated differently than 'int' internally. It makes sense to use 'byte' or 'short' when using larger arrays to save memory and speed up access time, otherwise simply use 'int' and everything will be fine.

Declare methods as 'static' when possible

Static methods cannot access non-static methods or fields. When a method only accesses static fields and methods, you should definitely declare the method static as well. The time it takes to dispatch a static method is faster than any other kind of method.

Declare public non-static methods as 'final' when possible

When added to the declaration of a method, the 'final' keyword will make the method non-virtual. This means that the method cannot be overloaded by sub-classes for polymorphic runtime dispatch. If your class never gets extended by a subclass, or you do not require polymorphism, you can safely declare all public methods as 'final'. Private methods cannot be polymorphic as well, so by declaring a method as private, you will achieve a similar result. The time it takes to dispatch a private or final method is faster than an ordinary non-static polymorphic method.

An NL2SCO can have more than one script

If you have a very complex and long script, it might make sense to split it up into two or more scripts. E.g. one script might take care of animating the objects, while another script animates light effects etc. This might be faster, because the scripts are executed on individual CPUs/cores parallely if your computer has multiple cores. The engine will take care of all the synchronization when the same objects are referenced from multiple scripts at the same time. This only makes sense for very long and complex scripts though.

Fastest for loop

The fastest way to iterate through all objects of an array is by using a reverse for loop. This only works if iterating reversly is acceptable.

int c = vector.length; // number of iterations
for (int i=c-1; i>=0; --i)

The reverse for loop is a bit faster than the corresponding forward loop, because it requires one byte-code instruction less inside the loop body.