Celestia/Cel Scripting

CEL scripting

CEL scripts are short text-based programs that Celestia can read. They contain simple commands that take control of Celestia (once it is launched) and enable a script writer to design a specific journey or set of scenes that a user of the script will see and experience. For example, a script may take the user on a short tour of the solar system, pausing briefly at all of the planets. In that way, a CEL script is used to change the position of Celestia's viewpoint.

CEL scripting is basically a sequence of commands similar to key-presses, which are executed in specific timing and at a particular speed to give viewers a visual experience that the script writer wants to display. There is however no interactivity with the user during the execution of a CEL script.

Scripts can take users to very specific locations in the Celestia universe. For example, a script can be written to take them into orbit around Venus, or take them outside the Milky Way to view it from intergalactic space. What happens when they get there is controlled by the script as well. There may be a 30 second pause, followed by a movement to another location. There may also be text displayed, to teach the user some information about a particular place.

Scripts also have the ability to change specific Celestia (render) settings. For example the rendering of orbits can be turned on/off or planets can be given a marker or alternative surface texture. Note however, when a CEL script ends or is terminated by the user, there is NO ability to reset those settings to the values they were before running the script. It is advised for the user to have their own reset.cel script, so specific Celestia (render) settings can be easily restored after running other CEL scripts.

A script can be launched from the Celestia/File/Open script... or Celestia/File/scripts drop down menu and it will run until it is complete. Meanwhile it can be paused by the user by pressing the [Spacebar] key or it can be stopped at any time by pressing the [Esc] key.
When the file extension ".cel" of a script is also correctly associated with the Celestia program, it is also possible to launch the script externally, e.g. from a hyperlink or by double clicking.

Scripts offer a Celestia user several key advantages:

A Celestia script writer can give inexperienced users a beautiful visual tour of a particular Celestia environment.
Important celestial events can be displayed for a user, controlled by script. For example, a script can take a user to 1957 to see Sputnik 1 orbiting Earth on its maiden flight. The script can put the viewer into a position just 10 meters from Sputnik, and pace it as it flies over the Soviet Union, then display a paragraph of text explaining the significance of Sputnik.
If no script were available, it might take a user many minutes to set up Celestia to go to the same spot at the same time. Also, no text would be displayed.
In the special Celestia-ED version of the Celestia program, CEL scripts have been given the ability to also command sound and music files to play. As such, scripts can be designed which choreograph complex movements of planets or spacecraft, while moving to music.

Writing Celestia Script Commands

Anyone can write a CEL script. Some knowledge of how to do so is required and is summarized below, but you do not have to be a very experienced Celestia user to write a CEL script.

The very first character in a CEL script must be an opening curly brace "{". The very last character in a script must be a closing curly brace "}".

Therefore, an empty, but valid Celestia CEL script file looks like the following:

{ }

Every script you create for Celestia will have at least one command line in it, which is a line of text instructing Celestia to set or do something.

A typical single Celestia script command line consists of the following pieces:

A command name, such as wait
A space (spacebar)
An opening curly brace "{"
Zero or more argument names, along with the value you want the argument set to.
A closing curly brace "}"

The "#" character can be used as the first character in a script line to make that line a comment line, which the script engine will ignore (not execute).

Examples:

Assign a <number> value of 5.5, to the argument duration, in the command wait, which tells Celestia to pause for the number of seconds you enter.

Note: there are no double quote marks (") around the <number> value (5.5) because double quote marks are used only to specify a <string> value.

wait { duration 5.5 }

Assign a <string> value of "Mars", to the argument object, in the select command:

Note: Here, double quote marks tell Celestia that a <string>, or text value (Mars), is being sent to it. When sending a <string> to Celestia, the value must be enclosed in double quote marks.

select { object "Mars" }

Example of a comment line.

# This is a comment line

Some Celestia CEL script commands, such as print, send more than one argument. In these cases, you enclose all arguments and their associated values between the command's opening and closing curly braces, such as:

Note: All arguments for each command must be enclosed within the command's curly braces, such as the example above shows. You may include as much white space (spaces, blank lines, etc.) as you deem necessary, and you may even specify each argument and its associated value on a different line – all for clarity.

print { text "Hello universe."  row -4  column 1  duration 5 }

-- OR --

print { text "Hello universe."
        row -4
        column 1
        duration 5 }

When you save a Celestia CEL script file to disk, the file extension must be ".cel", which allows your operating system to recognize the file as belonging to Celestia, and allows Celestia to know this file is one of its CEL scripts. Also, you must save the file as plain text. Rich Text Format files do not function in Celestia because they also contain embedded formatting information.

Index of available CEL commands

An index of the available CEL commands can be found at the CEL command index section of the CEL to CELX migration chapter.

By clicking on a specific command, you will be routed to the explanation of its functionality. The index also contains an explanation on how that CEL command can be migrated to equivalent CELX objects and methods. Before starting with CELX scripting however, you may need to have some programming experience with CEL scripting first.

CEL scripting versus CELX scripting

A main advantage of CEL scripting is that it's MUCH easier to use than CELX scripting. The syntax is easy due to the simple structure of the commands, and most of the time it's very easy to translate keyboard commands directly into their CEL counterparts.

The primary disadvantage in using CEL-scripting versus CELX-scripting is its limited flexibility, its inability to respond to keyboard commands, the absence of a possibility to reset changed user settings to the values they were before running the CEL script and a lack of support for many of the new Celestia features that appeared in Celestia version 1.6.0 and newer Celestia versions/releases.

The main differences between CEL scripting and CELX scripting are summarized below:

The extension of CEL and CELX scripts differ from each other:
- CEL script: .CEL
- CELX script: .CELX
More words and more commands make CELX scripts look more complex than CEL scripts, but it also gives your scripts more possibilities, including the usage of Lua logic (like building loops, make decisions on what to do, calculations, etc.), and interactive keyboard input.
The CEL to CELX migration section will help you with the more complex CELX equivalents of the CEL commands, so you can use these equivalents in your own script. Besides the equivalents, there are also examples included. You can copy the equivalents into your own script and modify them according your own wishes. After a while you’ll become more familiar with CELX scripting and copying or typing a sequence of CELX methods and objects will become easier each time.
Keyboard interaction is possible in CELX, but not in CEL scripting. Within CELX you can use the callback for keyboard input, which must have the name celestia_keyboard_callback. After a script activates the handling keyboard-input by calling celestia:requestkeyboard(true), any keypress will result in a call to a method with this name.
Angles in CELX are defined in radians instead of degrees in CEL.
180 degrees (half a circle) is the same as π radians = 3.14159265 radians.
You can use the Lua math.rad() and math.deg() functions to convert degrees to radians and [i]vice versa[/i]:
- radians = math.rad( <number:degrees> )
- or you can convert yourself: radians = ( <number:degrees> / 180 * 3.14159265)
- or use Lua math.pi: radians = ( <number:degrees> / 180 * math.pi)
- degrees = math.deg( <number:radians> )
- or you can convert yourself: degrees = ( <number:radians> * 180 / 3.14159265)
- or use Lua math.pi: degrees = ( <number:radians> * 180 / math.pi)
The units of the components of a position object in CELX are millionths of a light-year. When you have position components defined in km (CEL scripting) or miles, you first have to convert those components to millionths of a light year.
Therefore, you can use a constant, which must be initialized first within your CELX script:
- From km to millionths of a light year, use constant: uly_to_km = 9460730.4725808.
- From miles to millionths of a light year, use constant: uly_to_mls = 5912956.5453630.
Next you can convert km or miles to millionths of a light year as follows:
- millionths_of_a_light_year = <number:km> / uly_to_km
- millionths_of_a_light_year = <number:miles> / uly_to_mls
Be aware that some default parameter values have changed in CELX compared with the equivalent defaults in CEL scripting.
Time in CELX is defined in TDB (Barycentric Dynamical Time) instead of UTC or Juliandate, because UTC includes "leap seconds" in order to stay aligned with the Earth's varying rotation. Leap seconds happen essentially randomly, when they are needed. Although Celestia does incorporate a table of leap second times, the use of UTC in versions of Celestia before v1.5.0 caused problems when used with ephemerides which are defined using TDB.
Starting with version 1.5.0, although it still displays UTC on the screen, Celestia uses the TDB time scale internally for everything else. As a result, Celestia places objects much more accurately than before.
- To convert from Juliandate and/or UTC to TDB is explained in the section: CEL: time.
Transparency of markers can be true or false in CELX (starting from Celestia version 1.6.0). In CEL scripting there’s no possibility to enable or disable the transparency of markers. The Celestia releases 1.5.0/1.5.1 and older always displayed the markers, but from Celestia version 1.6.0 (or Celestia-ED version 1.5.1), the default marker transparency is true, resulting in disappearing markers in case of Occultations, or partially show markers on the surface of celestial objects. To overcome this, the usage of the false parameter in the CELX: object:mark() method is necessary, which also makes CELX scripting necessary, instead of CEL scripting!
Sometimes, timing can be more sensitive in CELX scripting than it is in CEL scripting, especially when lots of Lua commands and Celestia (related) methods are used within a short period of time with a high timerate value ([i]i.e.[/i] when time has been speeded up). Solving those timing issues on your own computer may not always give the same result on other computers with different CPU speeds. In those cases, the usage of a CEL equivalent part within your CELX script may give a more consistent result.
It is possible to insert CEL script parts within a CELX script by defining the following function at the beginning of your CELX script:

function CEL(source) 
   local script = celestia:createcelscript(source) 
   while script:tick() do 
      wait(0) 
   end 
end

-- Within the subsequent part of your CELX script you can now use CEL script commands as follows:
CEL([[{ <one or more lines with CEL script commands> }]])

CEL and CELX Scripts can be temporarily paused, by pressing the [Spacebar] key. Pressing the [Spacebar] key again will result in the continuation of the script.
Note: When using CEL script parts and functions within a CELX script, this pause function will not work completely correctly. Although the scene you’re looking at will pause directly, the CEL script parts and functions will continue to run in the background, resulting in a part of the script being visually skipped when you press the [Spacebar] key again to continue the script.

External Links

A slightly out-of-date summary of .CEL commands.

A list of more of the .CEL scripting commands, somewhat cryptically organized.

An example .CEL script

Some helpful .CEL and .CELX scripts for Celestia are available on Don G's Celestia Scripting Resources