Since version 0.10.1, Stellarium includes a scripting feature based on the
QT Scripting Engine. This makes it possible to write small programs within Stellarium to produce presentations, set up custom configurations, and to automate repetitive tasks. Prior to version 0.10.0, Stellarium used a different scripting engine called StratoScript.
The core scripting language is ECMAScript, giving users access to all basic ECMAScript language features such as flow control, variables string manipulation and so on. Interaction with Stellarium-specific features is done via a collection of objects which represent components of Stellarium itself. See Scripting API for more details.
Prior to version 0.10.0, Stellarium had a simple scripting engine, known as
StratoScript. Using StratoScript it was possible to record and play back sequences of Stellarium commands, load and display custom images, and play sounds. In this way it was possible to make planetarium presentations - a feature used quite widely in the small planetarium community.
However StratoScript lacked many features of a real programming language - there were no variables, no flow control and no way to introspect the state of Stellarium.
The replacement scripting engine implemented in the 0.10.x series addresses these shortcomings, at the expense of a little complexity and a new language syntax.
A compatibility mode which converts StratoScript into new scripting engine on the fly is in progress.
Note: StratoScript compatibility is a build-time option. To enable this feature, Stellarium must be built using the ENABLE_STRATOSCRIPT_COMPAT=1 option to cmake.
Interation with Stellarium-specific functionality is done by calling the
public slots of instances of a group of Stellarium's core classes.
- The public slots in the class StelMainScriptAPI are available via an object named core. For example, to access StelMainScriptAPI::wait() from a script, use the scripting command: core.wait(...);
- Additional core classes have self-named objects available from the scripting engine:
Note: The Script Console has been enabled by default since version 0.10.5. It is a build-time option. To enable or disable this feature, use the ENABLE_SCRIPT_CONSOLE=1 or =0 option to cmake.
It is possible to open, edit run and save scripts using the script console window. To toggle the script console, press F12. The script console also provides an output window in which script debugging output is visible.
The best source of examples is the
scripts sub-directory of the main Stellarium source tree. This directory contains a sub-directory called tests which are not installed with Stellarium, but are nontheless useful sources of example code for various scripting features.
This script prints "Hello Universe" in the
Script Console output window.
core.debug("Hello Universe");
This script uses the
LabelMgr module to display "Hello Universe" the screen for 3 seconds.
LabelMgr.labelScreen("Hello Universe", 200, 200, true, 20, "#ff0000");
core.wait(3);
LabelMgr.deleteAllLabels();