Installing, reporting bugs, and frequently asked questions
Read all of the frequently asked questions (and their answers), or you will incur the wrath of the egg.
In these FAQ, <KSP directory> is the directory such that the KSP executable is found in <KSP directory>/KSP.exe.
See the README for the versions of KSP currently supported by Principia.
The binaries for Windows, macOS, and Ubuntu x64 can be found in the README. Unzip the archive and copy the Principia folder into the GameData folder of your installation of KSP.
Don't reuse an existing save after installing Principia for the first time, create a new one (see below). When upgrading to a new version of Principia it's fine to reuse an existing save as we maintain backward compatibility.
Additionally, never add/remove celestial bodies to an existing save, as this will corrupt your save file. Create a new save instead.
You will need to delete the [your KSP instance]/GameData/Principia folder. You can also remove the [your KSP instance]/glog folder if it is taking up a lot of space, although you do not have to. If in an existing save, your vessels might be all over the place after uninstalling.
“Trappist-1 for Principia” is a mini-mod that simulates the TRAPPIST-1 extrasolar planetary system. TRAPPIST-1 is composed of seven tightly coupled Earth-like planets orbiting close to an ultracool dwarf star where n-body gravitation plays an important role, so it's an interesting application of Principia.
The simulation uses the most recently published observational data (from K2 and Spitzer) and is based on a transit-timing variation optimization. It accurately models the real-life behavior of the planetary system: the transits are accurate to within a minute.
Our mini-mod comes as a patch on top of @GregroxMun's SLIPPIST-1 mod. To install, do the following:
- Install SLIPPIST-1.
- Install Kopernicus.
- Optionally, install RSSTimeFormatter to display the correct date for the state of the TRAPPIST-1 system.
- Download the
trappist-1 for principia fáry.zipfile, unzip it, and drop theTrappist-1 for Principiafolder in theGameDatafolder of your installation of KSP. - Start KSP and enjoy the view:
32-bit platforms are no longer supported, you must be on a 64-bit platform.
Make sure you put the DLL in the right place. The Principia DLL should be at <KSP directory>\GameData\Principia\{Linux64,MacOS64,x64}\principia.dll.
If you get the message "Dependencies, namely the Microsoft Visual C++ 2015-2019 Redistributable, were not found", well, you need to install the x64 Microsoft Visual C++ 2015-2019 Redistributable.
You need Ventura or later.
For machines with ARM processors (Apple M1 to Apple M4 and variants) some extra steps are required to make sure that the Principia shared library can be loaded: that library targets x86_64 so the necessary dependencies may not exist on your system:
/usr/bin/arch -x86_64 /bin/bash -lc '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'
/usr/bin/arch -x86_64 /bin/bash -lc 'brew install llvm@20 || brew install llvm'
chmod u+w "/Applications/KSP_osx/GameData/Principia/MacOS64/principia.so"
install_name_tool -change /usr/local/opt/llvm/lib/c++/libc++.1.dylib \
/usr/lib/libc++.1.dylib \
"/Applications/KSP_osx/GameData/Principia/MacOS64/principia.so"
install_name_tool -change /usr/local/opt/llvm/lib/c++/libc++abi.1.dylib \
/usr/lib/libc++abi.dylib \
"/Applications/KSP_osx/GameData/Principia/MacOS64/principia.so"
install_name_tool -change /usr/local/opt/llvm/lib/unwind/libunwind.1.dylib \
/usr/local/opt/llvm@20/lib/libunwind.1.dylib \
"/Applications/KSP_osx/GameData/Principia/MacOS64/principia.so"
Some users have reported that they had to copy the shared library from /Applications/KSP_osx/GameData/Principia/MacOS64/principia.so to /Applications/KSP_osx/KSP.app/Contents/Frameworks/principia.so. The reason why the library is not found at the normal place is unclear. See #4130.
Note to Linux users: we support three operating systems (Windows, macOS, and Ubuntu), not 50 operating systems (the same plus 47 weird distros of Linux). If you use a distro other than Ubuntu, the information below might be useful to you, but if it is not, you're on your own for investigating and fixing any problems that you might encounter.
You need libc++1, libc++abi1, and libunwind version 20 or later.
Also, your working directory needs to be <KSP directory>, otherwise principia.so will not be found.
Principia is linked against libraries named libc++.so.1, libc++abi.so.1, and libunwind.so.1. Users of Arch Linux have reported problems because apparently the libraries don't have the .1 suffix on their system. The fix is simply to create symlinks so that files named .1 are found by the loader.
To find which libraries are not being found run ldd <KSP directory>/GameData/Principia/Linux64/principia.so. An example output on a Redhat based distro:
linux-vdso.so.1 (0x00007ffc3cd42000)
libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f4befb43000)
libc++.so.1 => /lib64/libc++.so.1 (0x00007f4befa41000)
libc++abi.so.1 => /lib64/libc++abi.so.1 (0x00007f4befa08000)
libunwind.so.1 => not found
libm.so.6 => /lib64/libm.so.6 (0x00007f4bee320000)
libgcc_s.so.1 => /lib64/libgcc_s.so.1 (0x00007f4bef9cd000)
libc.so.6 => /lib64/libc.so.6 (0x00007f4bee143000)
/lib64/ld-linux-x86-64.so.2 (0x00007f4befb6d000)
In the example output, libunwind.so.1 is not found. We can then run ls <library directory> | grep "<library>" to see if we have it installed. For the example case, <library directory> is /lib64 (this will change depending on your distro) and <library> is libunwind. The example output for the ls command is:
libunwind-coredump.so.0
libunwind-coredump.so.0.0.0
libunwind.so.8
libunwind.so.8.0.1
libunwind-x86_64.so.8
libunwind-x86_64.so.8.0.1
So in the example, we have libunwind installed but the shared object name is libunwind.so.8 not libunwind.so.1, meaning we need to create the libunwind.so.1 symlink using sudo ln -sf /lib64/libunwind.so.8 /lib64/libunwind.so.1 (this command will differ depending on your library directory and the library).
After creating the symlink and rerunning the ldd command, we get the following:
linux-vdso.so.1 (0x00007ffc98fd3000)
libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f70071fb000)
libc++.so.1 => /lib64/libc++.so.1 (0x00007f70070f9000)
libc++abi.so.1 => /lib64/libc++abi.so.1 (0x00007f70070c0000)
libunwind.so.1 => /lib64/libunwind.so.1 (0x00007f70070a7000)
libm.so.6 => /lib64/libm.so.6 (0x00007f7006fc7000)
libgcc_s.so.1 => /lib64/libgcc_s.so.1 (0x00007f7006fa5000)
libc.so.6 => /lib64/libc.so.6 (0x00007f7006dc8000)
/lib64/ld-linux-x86-64.so.2 (0x00007f700879b000)
Showing that all Principia libraries have been found.
Steam only supports the most recent Ubuntu LTS. Users on other distros have reported that Principia is not running when launched from Steam, and running fine when launched manually. One user reported that:
if you want Steam to count the hours and such you need to create a link to the KSP executable and then add the link to the launch options in steam ("absolute path to the link" %command%)
See #4131 for details.
After installing (or uninstalling) Principia, you should start from a clean slate with all vessels on the ground. If you try to reuse an existing save, you may or may not like the result. We will restart integration of the solar system since the origin (it will take a little while the first time you start the game with Principia) and we'll move the celestials to the positions that we have computed. As an example, the Moon is likely to move quite a bit, so if you were flying towards the Moon you may find yourself going towards the-moon-is-not-here-anymore.
Timewarping with vessels is smooth at timewarp 100 000× (the maximum warp supported by the stock KSP) but janky at timewarp 1 000 000× (permitted by some mods). This can be alleviated by reducing the number of vessels in the game. In particular, asteroids being vessels as far as the game is concerned, removing them is a good idea if you are not interested in them (if you're using RealSolarSystem, these asteroids are fairly silly). In order to do that, simply delete the <KSP directory>\GameData\Squad\Parts\Misc\PotatoRoid folder.
When no vessels are present timewarp should be very smooth, even at 6 000 000× (in RealSolarSystem).
Any mod that tries to move vessels or otherwise change orbits either (1) without using engines or (2) during time warp, is incompatible with Principia.
Many mods do that, and they are as a consequence all incompatible with Principia. We document some high-profile incompatibilities below, but we cannot really know about all of them. Mod users are advised to think about possible incompatibilities when using multiple mods.
Principia comes with initial state and gravity models configs for all celestial bodies in RealSolarSystem as of 2023-06-22, plus Eris.
No other celestial bodies are supported: if RealSolarSystem is installed and unsupported celestials are found without the above configs (for instance, coming from an extension pack), the game will crash.
If you are trying to build your own solar system, you might run into stability problems. This manifests itself by a pop-up message like "Apocalypse occurred at..." and an error in the logs. To solve the problem, you might need to simulate your solar system in an external tool and find its regions of stability.
In particular, if you simply add bodies to the existing Kerbal system, even if they are themselves stable and do not perturb the Kerbal system significantly, issues will appear in the existing Jool system, whose stock version is unstable: when no modifications are made to the solar system we detect that and change the Jool system, but as soon as you have a custom system, you need to deal with Jool yourself too.
The use of Parallax, while it primarily affects graphics, changes terrain altitudes, and therefore counts as a modification of the solar system and Principia will not fix the Jool system for you automatically.
A possible solution to the Jool problem specifically is to increase the size of the orbits of the Joolian moons, while making Bop's orbit retrograde. This Kopernicus configuration will do this, like Principia does on a stock system. A word of warning: if your mod rescales the stock system, that config will not do the job; make a big (or small) retrobop yourself.
For some reason, having HDR and Bloom on with TUFX causes most of the trajectory lines generated by Principia to glow seemingly radioactively. Turning HDR or Bloom off in your TUFX Tracking Station/Map View profile should fix this.
SigmaBinary and Principia are mutually incompatible. Install one or the other. In the words of the author of SigmaBinary:
My mod is a hack to allow fake binaries in KSP physics, Principia "hacks" KSP to use real physics.
I would say, Principia should be able to provide binaries without the need of extra plugins, it's probably just a matter of setting the initial conditions correctly I would assume.
Orbital Decay and Principia are mutually incompatible. Install one or the other. Orbital Decay changes the orbits of vessels in time warp and Principia keeps an authoritative copy of the state of every vessels: the two mods would fight each other and Principia would win.
PersistentRotation and Principia are mutually incompatible. Install one or the other. PersistentRotation is not physically correct, and the two mods would fight each other.
Blueshift and Principia are mutually incompatible. Install one or the other. Blueshift does faster-than-light travel and wants to modify the positions and trajectories of vessels without applying forces, and these changes would be immediately undone by Principia. It also has nonphysical parts (NaN inertia) and parts with an id of 0, which violate the invariants expected by Principia.
We have had multiple reports of issues related to broken terrain with RSS-Reborn. In Klein and later, Principia will fail to start with an error similar to the following in the FATAL file:
F0806 20:09:52.450951 17528 ksp_plugin_adapter.cs:733] Terrain system returned NaN for altitude at latitude 150.891908356404, longitude -83.5875685995387 for celestial Ceres
It seems that this problem only exists for some versions of RSS-Reborn, although it's hard to say which one as there seem to be several lurking around. The bottom line is: if RSS-Reborn works for you, great; if it doesn't, we won't be able to support you.
This mod thinks that it can do saves from a thread other than the main thread. KSP is fundamentally not thread-safe, so crashes are sure to happen.
Multiplayer mods are fundamentally incompatible with Principia: if another player moves one of their vessel, for instance by doing a burn, the multiplayer system will want to reflect that move in your copy of the game. However, chances are that Principia will be unaware that a burn happened, so it think that the vessel is in free fall and will authoritatively reposition it based on its own computations.
So, you crashed, or something similarly unpleasant happened.
We would like to hear from this. Please create a github issue. Be specific about the kind of failure you had: did you get an Unity dialog box? Did you get a Windows dialog box, or on *nix, did the process terminate by SIGABRT? What were you doing when the game crashed? In addition, give us the specific crash files as explained below. The more information the better, otherwise we might be unable to reproduce your problem.
You probably encountered a glog CHECK failure. Go to <KSP directory>\glog, check that there is a recent FATAL file. Take the most recent FATAL and INFO files, upload them on gist. Link the gist in your github issue.
That's a folder whose name is the date in the %USERPROFILE%\AppData\LocalLow\Squad\Kerbal Space Program\Crashes or %USERPROFILE%\AppData\Local\Temp\Squad\Kerbal Space Program\Crashes directories.
Put the contents of the folder on gist as well as the contents of the %USERPROFILE%\AppData\LocalLow\Squad\Kerbal Space Program\output_log.txt and %USERPROFILE%\AppData\LocalLow\Squad\Kerbal Space Program\Player.log files at the time of the crash. This may either be a stock KSP bug or a bug on our side, we will determine that by looking at the logs. Also include the KSP.log file at the time of the crash found in your KSP installation directory.
Link the gist in your github issue.
In order to help us analyse the most complicated bugs, Principia includes a journaling mechanism that records all the interactions between KSP and Principia. We will replay these interactions to understand what happened, e.g., in case of a crash. If we ask you for a journal, please follow the following steps:
- open
Logging Settingsin the main Principia window; - select
Record journal (starts on load)at the bottom left; - do a scene change to make sure that journaling is enabled (you should see
Journaling is ONat the bottom right of the Principia window); - try to reproduce the problem that you ran into (note that journaling makes the game slow as it writes lots of data to disk);
- if you are successful in reproducing the problem, send us the relevant
*.logfiles and theJOURNAL.*file found in yourglog\Principiadirectory.
Don't forget to deselect Record journal (starts on load) or your game will be slow forever. The journal does not contain any personally identifiable information other than the name of your machine, and the names and configuration of your vessels and celestials.
The list of issues contains mostly ideas for future improvements. We use the label bug for issues that lead to incorrect behavior (not necessarily crashes, though).
The following traces are expected and harmless; seeing them in the KSP logs should not be cause for alarm:
Load(Assembly): Principia/x64/<some assembly>
AssemblyLoader: Loading assembly at <ksp path>\GameData\Principia\x64\<some assembly>.dll
Failed to load assembly <ksp path>\GameData\Principia\x64\<some assembly>.dll:
System.BadImageFormatException: Format of the executable (.exe) or library (.dll) is invalid.
<stack trace>
As outlined in the technical overview, all the work is done in native DLLs (compiled from C++) called from a comparatively lightweight C♯ adapter that handles UI and interactions with the game itself.
These native DLLs are not loaded by KSP directly, and cannot be, but KSP tries to load any DLL it sees, resulting in these exceptions.
This Imgur album shows the trip there, starting right after getting out of the atmosphere.
Note that the orbit is unstable, which means that no matter how fine your adjustments are, eventually you'll get kicked out of your orbit. However with fine enough tuning you can stay a while, and of course if you come back from time to time to correct your trajectory you can stay there as long as your have fuel. The first user to orbit an L3 point was, as far as we can tell, Yargnit, his Twitch stream has sadly disappeared.
It should really be Minmus-(Kerbin-Mun barycentre), but surprisingly, yes! As far as we know Yargnit is the one who first got there, his Twitch stream has sadly disappeared.
Ike is too big (or duna is too small).
Yes, see for instance https://goo.gl/photos/6AQCcNyskfsHG9xF7.
You can get into an eccentric orbit with inclination 63.4° even without Principia, but with Principia the inclination is crucial: with other inclinations the orbit will suffer from apsidal precession.
Eclipses can be observed (there is a toggle to disable the Sun's lens flare to help with that), however due to small errors they lose a few minutes of accuracy after a century or so. They're quite fun to watch.
For instance, this is the solar eclipse of 1952-02-25, as seen from Semnan:
Yes; we have a plotting frame for that, target-centred local-vertical, local-horizontal, which is a fan favourite. See this guide.
If you wish to ask questions, you may want to ask questions on the #principia channel, which is accessible via:
- Discord: #principia on the KSP-RO server;
- Matrix: #principia:matrix.mockingbirdnest.com;
- IRC: #principia on EsperNet.
Bear in mind however that there isn't always someone around who can answer your question right away; if no-one is around, you may want to stay on the channel for a while.
While "rails" (Keplerian evolution) is not entirely unrelated to something that could improve performance, it would do the exact opposite with the current choice of integrator. One still needs to compute the positions of all bodies every time the force on a spacecraft is needed, so the Keplerian evolution would have to be computed instead of the forces on the bodies. Given that the computation of Keplerian evolution is costly (one needs to solve Kepler's equation, which requires a big lookup table or a handful of trigonometric function evaluations) the quadratic-to-linear change is completely dwarfed by this cost for 20 or so massive bodies.
It is true that some splittings of the Hamiltonian, e.g., those given by Wisdom and Holman (1991), Duncan, Levison and Lee (1998), Beust (2003), have Keplerian parts, and we will implement these, if only for comparison purposes to see which one we keep in the final implementation.
At this point we will have code for Kepler evolution and integrators that could be shoehorned into having Keplerian-only behaviour for massive bodies, but we will nonetheless not provide Keplerian-only behaviour, because in the end we're just not interested in that, we're here for the numerical integration problem.
This would break physics. As an example, if planets were to do that, you would not get Lagrange points. It is an interesting exercise to compute the sum of the centrifugal and gravitational potentials for a body orbiting the centre of another (rather than their barycentre) in the reference frame that fixes both bodies and the orbital plane, and computing its gradient. It is easily seen that this gradient does not vanish in 5 points, but in only 3 instead.
It would hardly improve performance and it would be messy to implement. This is just the kind of algorithm that doesn't lend itself well to that. Let's look at numbers. The only thing that's performance-critical here is the computation of trajectory predictions and flight plans. For those we're simulating the interactions of all massive bodies, and only one massless body. Computing all the forces costs 30 μs, and we need to synchronize outside of the force computation. Let's say we have a pool of 8 threads. We have to enqueue pointers to our data to our threads, and dequeue them, that's 16 locks. An uncontended lock costs about 50 ns, so that's 800 ns to start working, and 800 ns to synchronize when we're done. On a task that's 30 μs when single-threaded, we've spent 1.6 μs doing nothing. Whatever we might nibble away like that is not worth it.
It all depends on whether your system was sanely designed. If it has 50 Duna-sized planets orbiting a Jool-sized body, many of these are going to interplanetary space today.
Couldn't you gain performance by ignoring the influence of far-away bodies or by using a nonsymplectic integrator instead?
We have thought about these options, and we will implement those that might yield improvements in due time in order to get as much accuracy as we can out of a given computational cost.
The Earth is not a point mass nor a homogeneous sphere: it is an extended body. This has an effect on its gravitational field that can be described by coefficients corresponding to spherical harmonics. Notably, the earth has an equatorial bulge, which corresponds to the
The initial state config gives the solar system its state as given by the JPL HORIZONS service for 1950-01-01T00:00:00 Temps Dynamique Barycentrique. The state is however integrated before the game starts, so that the game starts at 1951-01-01T00:00:00 Temps Dynamique Barycentrique.
You'll need to turn on hack gravity for the cheat menu to properly set your orbit/position, otherwise Principia will override it. You can turn off hack gravity after you set your orbit/position.