![Cinematic Shaders main banner showing the raw GTAO effect on one side and composited scene on the other](screenshots/CinematicShadersBanner2.png "Cinematic Shaders main banner")
A shader mod for Kerbal Space Program 1.12+ - GTAO and Starfield currently available, more planned...

## Available Shaders

- **GTAO (Ground-Truth Ambient Occlusion)** – Horizon-based occlusion with normal-aware filtering
- **Starfield Catalog** - Catalog-based GPU-rendered stars.  No PNG, no pixelation.
- **HUCK** - Holographic Universal Celestial Kartographer, a HUD that projects onto the background of the stars and can provide information about your current target, situation, show you navball indicators including a manuver burn indicator and retro-styled burn-bar, and also allows you to point-and-click to select stars and get more info about them.
- **STAR console** System for Tabulation of Astrometric Records, the STAR console allows you to search through all selectable entries in your current catalog and allows you to edit the name of any star.  Rename real stars in Kerbal-style or name the stars one by one in your procedurally-generated sky.  Search for a star, click it, and see it selected on the sky so you can easily find it.

## Screenshots and Comparisons

### GTAO 
![A screenshot comparing "no Ambient Occlusion" to the GTAO effect provided by the mod](screenshots/NoAOvsCSGTAO.png "No AO vs GTAO")
![A screenshot comparing "MSVO" to the GTAO effect provided by the mod](screenshots/MSVOvsCSGTAO.png "MSVO vs GTAO")
Note that GTAO may not provide the more dramatic, soft shadows MSVO can - you can enable both, and use both, if you want!  MSVO exposed by [TUFX](https://github.com/KSPModStewards/TUFX) for KSP.
![A screenshot comparing Marty Mcfly's MXAO to the GTAO effect provided by the mod](screenshots/ReShadeMXAOvsCSGTAO.png "Marty McFly's MXAO vs GTAO")
Here you can see the difference between Cinematic Shaders GTAO and the AO provided through ReShade and the MXAO shader.  The MXAO shader is an amazing piece of work, it can provide GTAO across a wide array of titles.  The comparison here is to highlight the fact that it's easier to pull off the effect in-engine because you can get the right data from the engine directly.  MXAO rebuilds that data after the fact, inferring it from the scene - a huge technical hurdle I didn't have to cross.

### Starfield Shader

## What is it? ##
This mod completely overhauls the stock Galaxy Camera, replacing the static skybox with a fully rendered catalog-based starfield. No textures are used to define the stars—the stars are generated mathematically and rendered in real-time using your GPU.

**Star Catalogs**
The starfield is driven by catalogs that define each star's position, brightness, and color. You can choose from several "real star" catalogs based on actual astronomical data from the Hipparcos satellite courtesy of the ESA, or generate your own custom starfield using the procedural generation controls.

Save and share your creations easily! All catalogs are stored as `.bin` files in the `PluginData\StarCatalogs` folder and can be shared with other players.

**Important Note**
The stars will **not** be visible on the Main Menu. You must load into a game (Space Center, Flight, or Tracking Station) to see the starfield.

Here's a shot of the real star catalog
![A screenshot showing Kerbin sitting in the big dipper and the starfield UI](screenshots/KerbinStarfieldUISS.png "The starfield UI")

Or you can make your own starfield as wild and colourful as you want it using the sliders to customize the look and feel to your preference
![A screenshot showing Kerbin sitting among a colourful and bright starfield with the UI](screenshots/KerbinStarfieldGeneratedSciFi.png "The Wild West")


### Holographic Universal Celestial Kartographer

## What is it? ##

The Holographic Universal Celestial Kartographer, or H.U.C.K., is a diegetic heads-up info display that projects onto the background of space itself.  Complete with info about your current situation, navigation indicators, maneuver burn info display, and target live target tracking info, H.U.C.K. can help you keep sight of what's important.  With full options to enable and disable each feature individually, and an industry-first *four* colour options for the phosphor display, we think you'll find H.U.C.K. can be an invaluable member of your crew.

But that's not all.  H.U.C.K. comes pre-loaded with a vast star catalog containing data on over three-thousand stars, allowing you to point-and click to to discover their names, distances, and more.  Not just a navigation aid, H.U.C.K. is your guide to the stars.  Simply enable the Kartographer, choose the visual options you want, and H.U.C.K. does the rest.

**Screenshots**
![A screenshot showing the H.U.C.K. label and basic UI](screenshots/KartographerGeneral.png "The Kartographer UI")
![A screenshot showing the H.U.C.K. target tracking indicator](screenshots/KartographerTarget.png "The Tracking Indicator")
![A screenshot showing the H.U.C.K. star catalog function](screenshots/KartographerCatalog.png "The Star Catalog")

## IMPORTANT NOTE ##

The Kartographer *requires* the starfield to be enabled in order to function, and you would not be able to access the star catalog data otherwise regardless.

### STAR Console

## What is it? ##

The System for Tabulation of Astrometic Records is a terminal-style UI that allows you to search, select, and edit the names of any star in your current catalog.  If you're using a procedural catalog the STAR console gives you access to the scan function allowing you to build a star name catalog and then change their names however you want and select them on the sky just like the stars in the Hipparcos catalogs.  With over 3,000 real star names to search through, and the scan feature providing 5,000 nameable stars for your procedural catalogs, the STAR console opens up a new level of customization for your sky.

**Screenshots**
![A screenshot showing the splash screen and settings sliders for the STAR console](screenshots/STAR_1.png "The STAR Splash screen")
![A screenshot showing editing of a star name in the STAR console](screenshots/STAR_2.png "Editing a star name")
![A screenshot showing the search function in the STAR console](screenshots/STAR_3.png "Using the star search")


## Requirements

- **KSP 1.12.x**
- **[Deferred](https://github.com/LGhassen/Deferred)** – Required for effects to function.

## Installation

Unzip the archive into your `Kerbal Space Program/` folder.

The folder structure should be: `GameData/CinematicShaders/`

## GTAO Usage

1. Open UI: Click the wireframe sphere icon on the toolbar
2. Enable: Check "Enable Ground-Truth AO" in the GTAO tab (only functional if Deferred is installed)
3. Adjust:
   - Radius: Search distance for occluders (0.5m–10m)
   - Intensity: Shadow strength multiplier (0.0–2.0)
   - Shadow Spread: Maximum pixel radius for shadows
   - Quality: Preset controlling sample count (Low/Ultra)
4. Debug: Use the "Debug Visualization" dropdown for Raw AO or normal buffer inspection

## Starfield Usage
1. Open the Cinematic Shaders UI from the toolbar button
2. Click on the **Starfield** tab
3. Click **Enable** to turn on the starfield
4. Either choose an existing catalog from the dropdown, or create a new one from scratch using the procedural generation sliders

## Kartographer Usage
1. Open the Cinematic Shaders UI from the toolbar button
2. Click Enable Kartographer from the **Kartographer** tab
3. Choose the visualizer options you want and optionally customize their appearance
4. Starfield MUST be enabled!

## STAR Console Usage
1. Click the Cinematic Shaders UI from the toolbar button
2. Switch to the Kartographer tab, and click on the STAR console button.
3. (optional) choose a screen size at the bottom of the tab.
4. Click PWR to turn the UI on, navigate as per the on-screen info.

## Known Issues

- **GTAO** - There's currently an issue with the AO processing that I'll detail in a separate KnownIssues.md file.  It affects the overall rendering and may be more noticeable in some scenes than others.
- **Starfield** - Some stars may experience some "z-fighting" which causes minor flickering/twinkling.
- **Starfield** - per-save settings are currently not functioning correctly, so your settings will persist across saves - this is incorrect, as the intent is to allow each save to have its own sky based on your choices.
- **Starfield and Singularity conflict** - Major issues with Singularity, some of which may be mitigated by installing TUFX.  This is an ongoing investigation.


## License

All **code** is licensed via MIT License – See included `LICENSE.txt` file.

HYG Database (hyg_v42.csv) and derived real-sky catalogs (.bin files 
generated from this data) are licensed under CC BY-SA 4.0:

Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
Copyright (c) Astronexus (HYG Database)

You are free to:
- Share: copy and redistribute the material
- Adapt: remix, transform, and build upon the material
Under the terms: Attribution + ShareAlike

**Important:** Real-sky catalogs derived from the HYG CSV (the included .bin files 
in `GameData/CinematicShaders/PluginData/StarCatalogs/`) are derivative works 
and inherit CC BY-SA 4.0 obligations. Procedurally generated catalogs 
(random seed, no HYG data) are original works and can be shared freely under 
any terms you choose.

**Assets**
All navball icon assets(the sdf pngs and the svg source files in the assets\ folder) are licensed under the above MIT license terms.  You are free to use, modify, copy, distribute them as you wish without attribution.

**Font**
The DEC Rainbow 100 Font, AcPlus_Rainbow100_re_66.ttf, found in the FONTS folder is licensed under CC-BY-SA-4.0 https://creativecommons.org/licenses/by-sa/4.0/ from 
https://int10h.org/oldschool-pc-fonts/  The Oldschool PC Font Resource.

Under CC-BY-SA-4.0 You are free to:
Share — copy and redistribute the material in any medium or format for any purpose, even commercially.
Adapt — remix, transform, and build upon the material for any purpose, even commercially.
The licensor cannot revoke these freedoms as long as you follow the license terms.
Under the following terms:
Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
No additional restrictions — You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
Notices:
You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.

No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.

## Credits

- GTAO implementation based on [XeGTAO](https://github.com/GameTechDev/XeGTAO)
- ESA and the Hipparcos satellite for star data
- Tiffany352 and the [Godot Starlight](https://github.com/tiffany352/godot-starlight) project for inspiration, PSF implementation.
- The Oldschool PC Font Resource (https://int10h.org/oldschool-pc-fonts/) for the awesome-looking DEC Rainbow-100 font.