placeholder
Add-on Installation

This article describes the most common procedures for installing add-ons for the space-simulator program named "Celestia". It can be downloaded for free from shatters.net/celestia. Most add-ons designed for this program can be downloaded from the Celestia Motherlode. This document does NOT describe how to create new add-ons. If you want to make your own add-ons or modify others, you should start by reading Selden Ball's Not-so Brief Introduction to Add-ons. For further information, also see the the Documentation Page of the Motherlode.

If you are new to Celestia, please read this document from start to finish, since information that is relevant to later sections is covered in earlier ones. If you try to read just the section that you want help with right now, you might miss important information that may cause problems in the future operation of the Celestia program.

Please note that probably the most add-ons were created on (and designed for) Windows operating systems. So maybe some add-ons will not work properly under Linux or Mac operating systems. If you are using Celestia with Linux or MacOS and an add-on will not work properly or not at all, do not hesitate to contact the Celestia forums.


How Celestia Determines what to Display
The Celestia application is by far the smallest part of the package that you originally download. Most of the sizes of the files in the package are due to the pictures and spatial co-ordinates of the celestial objects that Celestia draws. When Celestia launches, it reads the data from a folder on your computer called "Celestia" (Windows systems) or "Celestia Resources" (Macs). It then uses that data to determine what to display. All files that you download from this site should be saved to your hard drive and moved to certain locations within this folder. By editing or adding to these files, you can change what Celestia displays on the screen.

The Celestia Resources folder is in different places depending on your operating system. In Windows, it is located in C:\Program Files\ and is called "Celestia" (Double-click on My Computer to find it). In Mac OS X, the folder is called "CelestiaResources" and it will be where the person who installed the original Celestia program put it. This is usually in /Users/<your username>/Library/Application Support/ or within the Celestia application bundle. To find it inside the bundle, hold down the {Ctrl} key, click on the Celestia icon and select "Show Package Contents" from the menu that appears. In Linux KDE, the folder can be installed anywhere, although /opt/kde3/share/apps/celestia is the default and most likely place.

Add-ons fall fall roughly into two broad classes: replacement textures and extras. Since their methods of installation are different, we will deal with them differently.


Replacement Textures
If the files you download are nothing more than images, you are dealing with a replacement texture. Celestia supports the following image formats: JPEG or JPG, PNG, and DDS. An add-on containing replacement textures is designed to replaceme a texture that was included with the default distribution of Celestia that you downloaded, with a new one. There are two ways to install replacements textures - by replacing the original image file, or by editing the data file that points to the texture, so that it point to your new image file instead.


Replacing the image file
Replacing the image file is simple. The tricky part is detailed in the note below about image resolutions.

Open the textures folder in the Celestia resources folder, find the image file that you want to replace, and remember or write down it's exact name. Then rename the old file to something else, like -old.jpg. Place the new image file in the same folder as the old one, and re-name it so it matches the original name of the old one (paste the name from the clipboard.) When you relaunch Celestia, you should see the new texture in place of the old one. Please read the note about resolution below.


Editing the data file to refer to your new texture
Instead of renaming files above, you can change the data file that directs Celestia to the image file you want to replace. For all default textures, these files are in the folder "data" inside the Celestia resources folder. They are called "ssc" files, and they end in the 3-letter extension (ssc). Based on the names of the files, find the one that describes the textures you want to replace. Open it with a text editor and scroll down until you see the entry for the object you are trying to replace. All the syntax of the catalog file should be understandable. Replace the name of the old texture with the name of you new texture, but don't modify anything else. Save and close the catalog file. Then place the texture in the medres folder inside the textures folder inside the Celestia Resources folder. When you launch Celestia, you should see the new textures on the object whose catalog entry you edited.


Extras
Extras are add-ons which usually cause Celestia to display an object that is not present at all in the default distribution. They will usually include several files including a catalog, models, textures, and not least importantly, a README that will tell you what to do get the object to display properly. If there is a README included, simply follow its instructions to install the add-on. If there is no README, you will need to sort the file by their type, meaning the part of their name that is after the dot. For instance, after reading the list below you should immediately realize that a file called pioneer.cmod is a model file and belongs in the models folder. Place the files in the following folders according their file types.

.cmod or .3ds or .cms > Place these in the models directory.

.jpg or .png or .dds > Place these in the textures/medres directory.

.ssc or .stc or .dsc > Place these in the data directory.


Testing the Add-on
After you have installed the add-on, you'll need to quit and relaunch Celestia. This is because Celestia only reads the data files when it is launched. Any changes you make will not be apparent until you start Celestia again. If you are installing a new object in Celestia, visit the object by pressing return to bring up the target entry window. As you begin to type the name of the add-on, Celestia will try to guess what object you want. You can press the TAB key to cycle through Celestia's guesses. When the window displays the name you want, press return again. You may have to go to the solar system where the object is located before its name will appear in the target entry window. Its solar system will be visible in the .ssc catalog that came with the add-on. When the correct object has been selected, press the 'g' key to go to it. You should move toward the boject and it should come into view. If you move somewhere, but an object is not visible, make sure that rendering for that object is enabled in the Rendering menu. If the proper rendering is enabled, but you still see nothing, it is possible that the object is not defined during the time that you are simulating for Celestia. This could occur with comet Shoemaker-Levy 9, for example, which crashed into Jupiter during July 1994. Celestia will still take you to a location for objects which no longer exist, but nothing will be displayed. To view the object, set the time to something more apprpriate.

If you are installing a different texture for an object that already exists in Celestia, it may be defined as an alternate texture. To view an alternate texture, you will need to right-click on the object and select the alternate texture from the menu you see. If you still have trouble getting your new add-on to work, you may want to read the ssc, stc or dsc file for clues to how and where the object should appear in Celestia. Even the smallest error can cause Celestia to function incorrectly, so be careful.



ibiblio.org home page Page last updated: February 24, 2011