Scripts: What are the guidelines for using core.wait()?

[jrobparsons]

I have been learning how to development scripts by studying the scripts that are integrated with Stellarium and the scripts that are in the 'test' folder.

After many of the API calls there is a core.wait().

Example (from constellations_tour.ssc) :

for (i=0; i<constellations.length; i++)
{
objName = constellations[i];
core.selectConstellationByName(objName);
StelMovementMgr.autoZoomIn(6);
core.wait(1);
StelMovementMgr.zoomTo(40,8);
core.wait(1);
ConstellationMgr.setFlagArt(true);
core.wait(10);
ConstellationMgr.setFlagArt(false);
}

Is the purpose of the core.wait() statements to synchronize the running of the script with the completion of the API calls?

In general, are API calls asynchronous operations?

Are there any general guidelines for using core.wait() in scripts?

Should a statement like StelMovementMgr.autoZoomIn(6) be followed by core.wait(1) or core.wait(6)?

Should a statement like StelMovementMgr.zoomTo(40,8); be followed by core.wait(1) or core.wait(8)?

[DavidWalley]

You have run into a problem with how Stellarium has been written. Specifically, I don't think there is an answer. I start with 0.1, and if there is a problem I double the previous value, until it works or I run it on another machine.

[gzotti]

The calls are executed when it comes to the script manager's time to do something. In above script, the waits are here to let the viewer actually look into the intended view for a second (or 10).
The most critical place to apply a wait is when you want to script an animation which either shows something in timelapse or even exports a screenshot. Here you must force cessation of the script (by calling wait() with some short interval) to allow the main loop to update everything after setting time.
Other than that, you can interweave pan and zoom in tricky ways, like slowly panning for 20 seconds and starting a 5sec zoom just 8 seconds after panning started. Just observe what happens in the script above. StelMovementMgr.autoZoomIn(6) followed by core.wait(1) will do whatever comes after that while the zoom is still running for 5 more seconds. The StelMovementMgr.zoomTo(40,8) initiates an 8-second zoom, and just a second after zoom has started, the art layer is faded in. 10 seconds later, (11 seconds after the zoom started and therefore 3 seconds after it finished), the art layer starts to be faded away again.