Skip to content

Home

Jump to bottom
LGhassen edited this page Jan 18, 2021 · 14 revisions

Welcome to the Singularity wiki!

What is singularity

Singularity is a KSP mod aimed at adding black hole shaders, including gravitational lensing and accretion disk.

Other possible uses include wormholes, stars with gravitational lensing, “white holes” ( a sort of black hole with negative gravity, pushing away light).

How it works

Starting at the camera, light’s trajectory is traced around the black hole in a finite number of iterations. At every step the light’s trajectory is bent by the amount of gravity it should receive until it hits the black hole or we run out of iterations (usually the ray escapes at that point).

Once the exiting ray is determined, we try to find the resulting object color from the on-screen color+depth buffer, if that fails we try to retrieve it from a cubemap centered around the black hole. If no object is found we retrieve the color of the static galaxy background. This means you can see objects in the lensing effect whether they are on-screen or off-screen.

Physical accuracy

This is not a physically correct simulation. The idea is relatively sound, and the force exerted by gravity fades by the square of the distance, but no real physical equations or constants are used. The shader is based on Pim Schreurs’ Interstellar simulation.

Configuration

General settings

The resolutions of different cubemaps can be adjusted separately as follows:

Singularity
{
    Singularity_config
    {
        galaxyCubemapResolution = 2048
        objectCubemapResolution = 2048
    }
}

GalaxyCubemapResolution:

The resolution of the “skybox” showing the galaxy, it is the static background, this should be as high as your skybox resolution is, and is inexpensive to set to high values as it’s not re-rendered.

ObjectCubemapResolution:

The resolution of the dynamic objects around the blackhole, this is used when objects are off-screen but can be seen through the black hole, or when getting really close to the black hole. One face of this cubemap is rendered every frame, so if you have issues with performance turn this down, otherwise turn it up.

Config files for black holes

The mod loads config files using the game’s configNode system. The files should have the following structure:

Singularity
{
    Singularity_object
    {
        key=value
    }
}

Config structure

Key values to use in your config file:

Variable Description Example
name Name of the celestial object to apply the effect to “name = Mun” to turn Kerbin’s moon into a black hole
gravity The most important setting, this controls the strength of the lensing effect and the apparent size of the black hole. It is arbitrary and has no unit (the visual effect is not based on real physics). You can also put a negative value to create a sort of “white hole” that pushes light away (looks like a mirror from the front). The apparent radius of the event horizon will be around 30000 x sqrt(gravity), in meters. The maximum radius around which distorsions are visible will be around 720000 x sqrt(gravity) in meters. “gravity = 200”
hideCelestialBody If the original celestial body’s surface should be hidden. “hideCelestialBody = true” for black holes. “hideCelestialBody = false” for a star with gravitational lensing.
useAccretionDisk If the body should have an accretion disk. Note: probably doesn’t work correctly if the celestialBody is not hidden (ie the celestial body will display on top of it) “useAccretionDisk = true”
accretionDiskTexturePath Path to the accretion disk texture. Will disable accretion disk if not found. Supports dds (as of 0.91) DXT1 and DXT5, png and jpg. For dds no need to generate mipmaps as Singularity doesn't use mip maps due to the way the texture is sampled inside the raytracing loop. “accretionDiskTexturePath = /myCoolMod/accretion.dds” or “accretionDiskTexturePath = /myCoolMod/accretion.png”
useRadialTextureMapping Whether or not the texture should be mapped radially, if this is used, the bottom of the texture will be mapped to the inner radius, and the top of the texture will be mapped to the outer radius, the sides of the texture have to match. If this is not used, the texture will be mapped to a square on the disk plane, without deforming the texture, the center of the texture will be mapped to the center of the black hole. “useRadialTextureMapping = false”
accretionDiskNormal Normal direction of the accretion disk plane. (0,1,0) is “up” in KSP’s map view. “accretionDiskNormal = “
accretionDiskInnerRadius Inner radius of the accretion disk, in meters, it is best if this doesn’t intersect the black hole. “accretionDiskInnerRadius = 100000“
accretionDiskOuterRadius Outer radius of the accretion disk, in meters. “accretionDiskOuterRadius = 400000“
accretionDiskRotationSpeed How fast the accretion disk rotates, in rotations per minute. By default the disk rotates clockwise around the accretion disk normal. Negative values make it rotate counter-clockwise. “accretionDiskRotationSpeed = 6” for 1 rotation every 10 seconds
wormholeTarget Use to create a wormhole effect. If the name of another Singularity object is entered, Instead of displaying a black void, the singularity will display what is around the other singularity. The other singularity doesn’t need to have this defined but can be defined to create a two-way wormhole. Multiple singularities can have the same target. “wormholeTarget = Tylo”
scaleEnclosingMesh The black hole effect is rendered inside a “containing sphere”. This is used to scale that sphere up, only use in case you need objects very close to the black hole to not be “cut off”, like a sun corona, or if you make a very large accretion disk and it’s getting cut off. “scaleEnclosingMesh = 1”

Previewing configuration in-game

Start up your game and go in flight or in tracking station. Once ingame bring up the mod UI using ALT+S (or modifier+S).

Once you have the UI up, it displays the list of loaded Singularity objects. Select one and press “Edit Selected” and you can modify the config and test it ingame. Note that Applying will not save your config to the config file, meaning it will be lost if you exit the game or change scenes. Copy it manually and paste it to your config file. You can also print the config to the log file. The config will also be logged when you apply it.

Sample configs to get you started

Minimal config to turn Mun into a blackhole

Singularity
{
    Singularity_object
    {
        name = Mun
        gravity = 200
        hideCelestialBody = true
        useAccretionDisk = false
    }
}

One to turn Tylo into a "wormhole" to Mun

Singularity
{
    Singularity_object
    {
        name = Tylo
        gravity = 200
        hideCelestialBody = true
        useAccretionDisk = false
        wormholeTarget = Mun
    }
}

And the Sun into a black hole with accretion disk (provided the texture is there)

Singularity
{
    Singularity_object
    {
        name = Sun
        gravity = 200000000
        hideCelestialBody = true
        useAccretionDisk = true
        accretionDiskNormal = -0.5,0,1
        accretionDiskInnerRadius = 200000000
        accretionDiskOuterRadius = 6000000000
        accretionDiskTexturePath=AccretionDisk\disk.png
        accretionDiskRotationSpeed = -1
    }
}
Clone this wiki locally