Scripting Engine

Table of Contents

• Introduction
• Scripting API
• Includes
• Script Console
• Examples
  • Minimal Script
  • Using a StelModule

Introduction

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.

Scripting API

Interaction 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(...);

• The public slots for each of the following classes are available in the scripting engine via an object with the same name as the corresponding class:
  • AsterismMgr
  • ConstellationMgr
  • CustomObjectMgr
  • HighlightMgr
  • GridLinesMgr
  • LabelMgr
  • MarkerMgr
  • LandscapeMgr
  • SporadicMeteorMgr
  • NebulaMgr
  • ScreenImageMgr
  • SolarSystem
  • StarMgr
  • StelActionMgr
  • StelAudioMgr
  • StelVideoMgr
  • StelMovementMgr
  • StelSkyDrawer
  • StelSkyLayerMgr
  • SpecialMarkersMgr
  • MilkyWay
  • ZodiacalLight
  • HipsMgr

For example, to access LandscapeMgr::setFlagAtmosphere(), use the scripting command:

LandscapeMgr.setFlagAtmosphere(true);

Note

All of these except for StelSkyDrawer are StelModule classes.

• The public slots for each of the following classes of the plugins are available in the scripting engine too:
  • Oculars
  • Satellites
  • Quasars
  • Pulsars
  • Exoplanets
  • Observability
  • EquationOfTime
  • NavStars
  • MeteorShowersMgr (The public slots in this class are available via an object named MeteorShowers)
  • ArchaeoLines
  • Calendars
  • TelescopeControl

Includes

Stellarium provides mechanism for splitting scripts on different files. Typical functions or list of variables can be stored in separate .inc file and used within script through include() command:

include("common_objects.inc");

Note

Detailed example can be found in Constellations Tour script.

Script Console

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.

Note

The Script Console is a build-time option. It has been enabled by default since version 0.10.5. To enable or disable this feature, use the ENABLE_SCRIPT_CONSOLE=1 or =0 option to cmake.

Examples

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 nonetheless useful sources of example code for various scripting features. (The directory can be browsed online. Script files end in .ssc and .inc. Download links are to the right.)

Minimal Script

This script prints "Hello Universe" in the Script Console output window.

core.debug("Hello Universe");

Using a StelModule

This script uses the LabelMgr module to display "Hello Universe" in white on the screen for 3 seconds.

LabelMgr.labelScreen("Hello Universe", 200, 200, true, 20, "#ff0000");
core.wait(3);
LabelMgr.deleteAllLabels();