Celestia/Cel Scripting

< Celestia

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:

  1. A Celestia script writer can give inexperienced users a beautiful visual tour of a particular Celestia environment.
  2. 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.
  3. 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.
  4. 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:

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:

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> }]])

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

This article is issued from Wikibooks. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.