RayTUI

What happens when two programmers, with nothing better to do, pair up for their Data Structures & Algorithms final? Well, RayTUI of course!

RayTUI is ray-tracing within a terminal. That's it. We wanted to combine the challenge of building a ray-tracer from scratch and figuring out how to render in a terminal to depict 3D environments!

Key Features

• Bounding volume hierarchies (BVHs)
• Simple entity component system (ECS)
• ANSI escape sequences for terminal formatting
• Global input handling
• No 3rd-party dependencies

User Guide

Requirements

• RayTUI only works on macOS (tested with Tahoe 26.4.1) and Linux.
• A C++17 compiler (gcc or clang) and CMake
• A terminal (any is fine, but we recommend Ghostty)

Setup

1. Open your terminal
2. Navigate to any folder
3. Run git clone https://github.com/njfdev/ray-tui.git
4. Run cd ray-tui
5. Run ./scripts/build.sh. Options:
   • --release Compile with release optimizations. Recommended
   • --avx For x86 systems that support SSE4.1, AVX2, and FMA, compiles with SIMD optimized BVH traversal.

The demo applications should now be successfully compiled!

Usage

⚠️ If this is your first time running on macOS, you may be prompted to allow input monitoring when running a demo. Please visit the Privacy Permissions for macOS section to learn more.

From the ray-tui folder, all you have to do is run ./build/<demo-name>. You can stop the demo by pressing CTRL-C or CMD-C.

Controls:

• WASD to move around
• Q to rotate counter-clockwise, E to rotate clockwise
• R to move up, F to move down

The available demos are listed below.

./build/cli (Realistic reflections/refractions, slower than realtime)

High resolution image was generated by shrinking terminal text scale.

./build/raytrace_demo (Simple multi-sphere and multi-light)

./build/tui_gradient (Shows terminal rendering ability)

./build/raw_inputs (Demo/test of global input handling)

Privacy Permissions for macOS

When running one of these demos for the first time within your terminal, macOS will likely prompt you for input monitoring permissions, as shown below:

The reason for this is that RayTUI uses global input handling to allow movement with the keyboard (because native terminal APIs for input handling aren't great).

To enable input monitoring, you can press the "Open System Settings" button, which should take you to Privacy & Security -> Input Monitoring in system settings. Then, you can add the terminal you are running RayTUI in to the list and enable the toggle:

Then restart the RayTUI demo, and now keyboard movement should work!