Rusty Rays

A simple cross-platform, still image raytracer implementing a Phong shading model and five-bounce reflections with attenuation. This repository contains multiple targets:

• A Rust command-line interface (CLI)
• A desktop GUI application (Electron + React)
• A Node.js N-API package that exposes the Rust core to JavaScript

See Project Overview below for details.

Project Overview

• rusty-rays-core (Rust library)
  • The rendering engine and scene parser written in Rust.
  • Consumed by the CLI and by the N-API bindings used in the desktop app.
• rusty-rays-cli (Rust binary)
  • Command-line tool to render .ray scenes using rusty-rays-core.
• rusty-rays-napi-node (Node N-API bindings)
  • Builds native Node bindings to call the Rust core from JavaScript/TypeScript.
  • Published locally into dist/ and consumed by the desktop app via a file path dependency.
• rusty-rays-desktop (Electron + React)
  • Cross-platform desktop UI that uses the N-API bindings to render scenes and manage jobs.

---

Quick Start (CLI)

• Clone the project
• Render with a one-liner from the project directory:
  • cargo run --release -- -i sample-files/sphereflake.ray
  • sample-files/sphereflake.ray can be replaced with the path to any file
  • This will render the sphereflake.ray sample input file included in this repo.
  • The resulting image will be written in BMP format to render.bmp in the project root
• Compiling
  • debug build: cargo build
  • optimized release build: cargo build --release
  • binaries in the target directory

Usage (CLI)

Input files utilize a simplified version of the Rayshade 4.0 .ray file format.

Arguments

• -i path to the input file
• -o path and file name where the resulting image should be written
  • optional
  • default output file format is BMP
  • default write location is render.bmp in the directory from the current directory
  • output file format is determined by extension. .bmp for BMP, .png for PNG, .jpeg for JPEG, etc.

Sample run command (using windows paths for inclusivity):

.\rusty-rays -i .\input-file-name.ray -o .\Pictures\renders\output-file-name.png

Logging (CLI)

• The application will create a log folder in the users cache directory
  • win: C:\Users\<user>\AppData\Local\rusty-rays\logs\
  • linux: $HOME/.cache/rusty-rays/logs/
  • mac: $HOME/Libary/Caches/rusty-rays/logs/
• The logger will default to console only logging if unable to create the log folder or file

Config (CLI)

• The application will create a config.json file in the users config directory
  • win: C:\Users\<user>\AppData\Roaming\rusty-rays\
  • linux: $HOME/.config/rusty-rays/
  • mac: $HOME/Library/Application Support/rusty-rays/
• If config.json is inaccessible, the application will use its internal default config
• If a value is missing from the config or null, the default internal config value will be used
• If max_render_threads option is set to a value less than 1 or greater than the number of physical cores, it will default to the number of physical cores.

Generating Additional Input Files (CLI)

Simple input files can be written by hand.

More complex classic benchmark input files can be generated with the Standard Procedural Databases

• .ray files can be generated by specifying the -r 8 flag.
• Note: To compile on unix systems you'll need to replace references to sscanf_s, sprint_s, and fopen_s with sscanf, sprintf, and fopen. Just follow the compiler errors.
• Note: The project needs to be compiled with the C89 standard. Add -ansi to the compiler arguments in the MakeFile (line 4).

Simplified Rayshade 4.0 File Format

You can find a quick reference sheet on the Rayshade file format here.

The original Rayshade 4.0 (Not Rayshader) program for which the rayshade file format was created, can be found here.

The Rayshade 4.0 renderer has capabilities and a feature set similar to that of blender so by extension the .ray input specification is extensive.

Rusty-Rays can parse and render the bare-bone basics of the specification. Below is a rundown of what's supported

Supported Rayshade Keywords:

• up
• eyep
• lookp
• fov
• screen
• background
• surface
  • diffuse
  • ambient
  • specular
  • specpow
  • reflect
• sphere
• polygon
• triangle
• light

---

Desktop Application

The desktop application lives in rusty-rays-desktop and uses an Electron + React UI. It depends on the local N-API package (rusty-rays-napi-node) via a file path dependency, so you must build/install the N-API project first before installing the desktop app.

Prerequisites

• Rust toolchain (for building the core and N-API native module)
• Node.js >= 24.11 and npm
• On Linux: system dependencies required by Electron may be needed (refer to your distribution docs)

One-time setup

1. Build and install the N-API package

cd rusty-rays-napi-node
npm install
cd ../

2. Install the desktop app dependencies

cd rusty-rays-desktop
npm install

Note: The desktop app references the N-API package using "rusty-rays-napi-node": "file:../rusty-rays-napi-node/dist". If you clean or rebuild the N-API project, re-run npm install in the desktop folder so the dependency stays in sync.

Run the desktop app (development)

There are two options:

• Fast dev loop with Vite renderer + Hot Module Reload (HMR) and Electron:

cd rusty-rays-desktop
npm run dev

Build the desktop app

cd rusty-rays-desktop
npm run build

Package installers

Use Electron Builder targets provided in package.json:

• Windows (NSIS):

cd rusty-rays-desktop
npm run dist:windows

• macOS (DMG):

cd rusty-rays-desktop
npm run dist:mac

• Linux (Deb):

cd rusty-rays-desktop
npm run dist:linux:deb

Artifacts are written to rusty-rays-desktop/dist/.

Troubleshooting

• If Electron cannot find native bindings, ensure that rusty-rays-napi-node/dist contains bindings/ with the correct .node binary for your platform. If it doesnt run npm run build in the napi project, then re-run npm install in rusty-rays-desktop.
• If your Node.js version is older, upgrade to >= 24.11 to satisfy the N-API package engine requirement.