Adding Planets to Celestia on macOS

tl;dr: you have to modify the application bundle.

Celestia is a space simulator: you can fly around space and look at moons and exoplants, fast forward time. It is sometimes used by sci-fi artists for worldbuilding because you can easily add new stars/planets/megastructures/spacecraft. Some people have built whole virtual worlds for storytelling in Celestia. The Orion’s Arm collaborative worldbuilding project has a collection of Celestia addons so you can explore the world of the year 10,000 AT.

But the documentation is sparse and old. As with many things: the biggest hurdle to starting is just knowing which files go in which directories.

Celestia uses .ssc (solar system catalogue) files to define planets. These are plain-text files with a syntax resembling HCL. Let’s create baby’s first planet: below is a minimal .ssc file that adds a planet “Alpha” around the star Gliese 555:

"Alpha" "Gliese 555"
{
  Texture   "asteroid.*"
  Mass      1             # Earth masses
  Radius    6378          # km
  EllipticalOrbit {
    Period          1.0 # years
    SemiMajorAxis   1.0 # long axis
    Eccentricity    0.0 # circular
  }
}

Now, what you would hope is that there exists a standard directory like ~/.celestia/planets/ you can put this into. I spent a lot of time looking through old docs and source code for this, and I’m writing this so others don’t have to. Unfortunately, at least on macOS, you have to modify the application bundle itself. This feels morally wrong, but it works.

Save the above code as alpha.ssc, and execute:

$ mkdir -p /Applications/Celestia.app/Contents/Resources/CelestiaResources/extras/
$ cp alpha.ssc /Applications/Celestia.app/Contents/Resources/CelestiaResources/extras/alpha.ssc

Open Celestia, and navigate to Gliese 555 (press enter, type “Gliese 555”, press enter, press g). You should see a new planet:

Zooming in, you can see it’s using the built-in asteroid texture:

To verify it’s reading the right file, press tilde and use the arrow keys to scroll up the logs, and you should see a line like:

Loading solar system catalog: extras/alpha.ssc

Celestia traverses the extras directory recursively, so you can put your .ssc files inside folders to organize large worldbuilding projects.