PlanetShine

Note: take a look at the other branches! :o)

Atmosphere and meshing playground. WIP.

TODO:

• Actual atmosphere rendering.
• Move the backend to vulkan (shouldn't be super hard).
• Orbits
  • Elliptic orbits, propagation
  • Non-elliptic orbits untested.
• Terrain generation, textures.
  • Textures.
  • Working on terrain in the terrain branch.
• Mesh LOD.
  • Primitive sphere LODs.

Setting Up

requirements: git, wget, python, internet connection

git clone https://github.com/monomere/pshine --recurse-submodules --shallow-submodules
cd pshine

Script

requirements: wget, python, ply

To install ply (needed for dear_bindings), do python3 -m pip install --user ply (or similar)

You can do the steps below manually, but there's a bash script that does them for you. Make sure to check the contents of the script before running it.

NB: if the script is different from the README, trust the script because I might've forgotten to update the README.

./setup.sh

---

Volk, VMA, stb_image, cgltf

The graphics backend uses stb_image, volk and VMA, cgltf. so after cloning (only once):

wget -P pshine/include/vendor https://raw.githubusercontent.com/zeux/volk/master/volk.h
wget -P pshine/src/vendor https://raw.githubusercontent.com/zeux/volk/master/volk.c
wget -P pshine/include/vendor https://raw.githubusercontent.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator/master/include/vk_mem_alloc.h
wget -P pshine/include/vendor https://raw.githubusercontent.com/nothings/stb/refs/heads/master/stb_image.h
wget -P pshine/include/vendor https://raw.githubusercontent.com/jkuhlmann/cgltf/refs/tags/v1.15/cgltf.h

Auxiliary libraries

Currently, tomlc99.

wget -P pshine/src/vendor https://raw.githubusercontent.com/cktan/tomlc99/refs/heads/master/toml.c
wget -P pshine/include/vendor https://raw.githubusercontent.com/cktan/tomlc99/refs/heads/master/toml.h

Generating the ImGui bindings

The project uses dear_bindings to generate c version of the c++ imgui headers.

mkdir -p pshine/src/vendor/cimgui/
mkdir    pshine/src/vendor/cimgui/backends/

python vendor/dear_bindings/dear_bindings.py \
  vendor/imgui/imgui.h \
  --imgui-include-dir imgui/ \
	--backend-include-dir imgui/backends/ \
	-t vendor/dear_bindings/src/templates \
	-o pshine/src/vendor/cimgui/cimgui

python vendor/dear_bindings/dear_bindings.py \
  --backend \
  --imgui-include-dir imgui/ \
	--backend-include-dir imgui/backends/ \
	--imconfig-path vendor/imgui/imgui.h \
	-t vendor/dear_bindings/src/templates \
	-o pshine/src/vendor/cimgui/backends/cimgui_impl_vulkan \
  vendor/imgui/backends/imgui_impl_vulkan.h

python vendor/dear_bindings/dear_bindings.py \
  --backend \
  --imgui-include-dir imgui/ \
	--backend-include-dir imgui/backends/ \
	--imconfig-path vendor/imgui/imgui.h \
	-t vendor/dear_bindings/src/templates \
	-o pshine/src/vendor/cimgui/backends/cimgui_impl_glfw \
  vendor/imgui/backends/imgui_impl_glfw.h

Setting the Ninja platform variables

Building

requirements: ninja modern gcc-compatible c/c++ compiler, glfw, python (optional), cpptrace/ctrace (temporarily a system dependency) requirements: rust (for giraffe, but can be removed by tweaking ninja files, as its not needed for now). I might rewrite all of this in Rust.

To build (incremental)

ninja

If you edit generate_math.py, ninja will try to regenerate the math.h header, which requires python.

NB: by default, the build.ninja file uses the full LLVM setup with lld, clang, libc++, etc. To use the system-provided stuff change the first line in build.ninja to include build.system.ninja instead. Or make your own config if you want to (or need to)!

Running

requirements: vulkan ≥1.2 (i don't really know which version tho uhh)

MacOS and MoltenVK: If you installed MoltenVK and Vulkan through Homebrew, add VK_LAYER_PATH=/opt/homebrew/opt/vulkan-validationlayers/share/vulkan/explicit_layer.d to your environment (or maybe not idk).

build/pshine/main

Linux and X11: By default pshine uses wayland, but you can pass -x11 to use X11 instead.

The planet has a radius of 6371km (Earth), the atmosphere has a height of 100km, and the camera moves at 500km/s by default.

Controls

Key	Action
F	Switch camera mode (default is arcball)
F2	Hide all UI
Shift+F2	Only hide the debug windows

Ship Mode

Key	Action
A/D	Yaw
W/S	Pitch
W/S	Roll
Shift/Ctrl	Increase/decrease velocity

Arcball Mode

Key	Action
A/D	Rotate left/right (yaw)
W/S	Rotate up/down (pitch)
X/Z	Zoom in/out

Flycam Mode

Key	Action
A/D	Move left/right
W/S	Move forward/backward
E/Q	Move down/up
←/→	Rotate on global Y axis (yaw)
↑/↓	Rotate on local X axis (pitch)

Credits

• Spaceship model by FilipZelinka, from SketchFab. Under CC BY 4.0.

TODO

• Use double precision for position data and etc.
• Fake perspective for celestial bodies.
• Fixed point math?
• Bug: mesh scale is wrong forgot to remove * 5.0f when passing atmosphere height.
• The bug is still there :( nevermind, it was correct all along. no, its still a bug....
  • THE BUG IS FIXED IT WORKSSS (precision errors)
• Separate materials for planets and meshes.
• Better API for materials? Maybe data-driven.
• Fix rotation matrices, and matrices in general.
  • Kinda did it? I'm not sure.
• Rewrite the math library generation, its so ugly.
• Stars
• Use near-origin coordinates for the "player".
• Velocity reference-frame.
• Clean up the renderer (vk.c), maybe move to C-ish C++ because its slowly becoming unbearable. Shouldn't be that much of a problem because you already need a C++ compiler for ImGui and VMA.
• Don't ignore pshine_planet::has_atmosphere.
• Fix gizmo rendering on mac!

Useful stuff

• Unite 2013 - Building a new universe in Kerbal Space Program how ksp does stuff!

Resources

This isn't the full set of resources used unfortunately.

• Survey of Efficient Representations for Independent Unit Vectors - Cigolle et al., 2014

• Tangent Spaces and Diamond Encoding

• https://stackoverflow.com/a/31662911/19776006

• https://gist.github.com/pezcode/1609b61a1eedd207ec8c5acf6f94f53a

• http://www.songho.ca/opengl/gl_projectionmatrix.html#perspective

• https://computergraphics.stackexchange.com/a/12453

• https://discourse.nphysics.org/t/reversed-z-and-infinite-zfar-in-projections/341/2

• https://playerunknownproductions.net/news/atmospheric-scattering

• https://paminerva.github.io/docs/LearnVulkan/02.F-Compute-Shader.html

• Followup: Normal Mapping Without Precomputed Tangents

• https://bgolus.medium.com/normal-mapping-for-a-triplanar-shader

• Textures: https://planetpixelemporium.com/

• Textures: https://svs.gsfc.nasa.gov/4720

• Textures: https://bjj.mmedia.is/

• https://github.com/Tw1ddle/Sky-Shader

• Bevy Bloom Impl.

• The COD Post-processing slides

• https://github.com/expenses/bloom

• https://github.com/hatoo/blackbody

• https://www.corsix.org/content/higher-quality-random-floats

• https://dotat.at/@/2023-06-23-random-double.html

• https://en.wikipedia.org/wiki/Permuted_congruential_generator

• https://github.com/rkern/pcg64

• Amazing resource for orbital mechanics: https://orbital-mechanics.space/

• Vulkan discord