leonmavr/retrocube

📺👽 3D graphics engine on the terminal in standard C without third parties

⬛ retrocube ⬜

Render 3D meshes in ASCII on the command line. It runs on the standard C library.

                    +==
                ++======
             +============
          ==================
      ========================
   +===========================..
   ||+=====================.......
    ||+=================..........
    +||||===========...............
     +||||||==+.....................
      +||||||........................
       +||||||.......................
       +||||||~.......................
        +||||||....................~.%
           |||||...............~.
            ||||~..........~..
               ||.........
                ||....~

1. This implementation

In human language, the graphics are rendered more or less by the following algorithm:

rows <- terminal's height
columns <- terminal's width
// a face (surface) is a plane segment (x, y, z) restricted within 4 cube vertices
initialise a cube (6 faces)
for (r in rows):
    for (c in columns):
        z_rendered <- +inf
        have_intersection <- false
        pixel_to_draw <- (c, r)
        color_to_draw <- background
        for (surface in cube's faces):
            // from equation ax + by + cz + d = 0
            z <- surface.z(c, r)
            if (z < z_rendered) and ((c, r, z) in surface):
                z_rendered <- z
                color_to_draw <- surface.color
        draw(pixel_to_draw, color_to_draw)

2. Requirements

Currenctly there is no Windows support. You only need gcc and make:

1. gcc
2. make

3. Development and installation

3.1 Development

3.1.1 Compiling the project

The naming convention follows the one of stb. Source files are found in src and headers in include.

When compiling the from project from a clean state, you need to specify where the mesh files (those that specify how shapes are rendereed) shall be stored. You can do this by setting the PREFIX variable to your directory of choice, e.g.:

make PREFIX=~/.config/retrocube

You can run the binary with (a list of command line arguments is provided in the next section):

./cube

You can delete the binary and object files with:

make clean

3.1.2 Compiling the demos

Several demos that showcase various usages of the libraries are found in the demos directory. These are compiled independently from their own file. To compile them you need to set the PREFIX once again:

cd demos
make PREFIX=~/.config/retrocube
# then you will see some binaries and run the binary of your choice

3.2 General installation

The Makefile includes an installation command. The binary will be installed at /usr/bin/cube as:

sudo make install

Similarly, you can uninstall it from /usr/bin as:

sudo make uninstall

3.3 Installation as Nix package

On Nix (with flakes enabled) you don't need to install it and you can directly run it with:

nix run github:leonmavr/retrocube

Credits for the Nix packaging @pmarreck and @Quantenzitrone.

4. Usage

4.1 Arguments

By default the program runs forever so you can stop it with Ctr+C. Below are the command line arguments it accepts.

Short specifier	Long specifier	Argument type	Default	Description
-sx	--speedx	float	0.7	Rotational speed around the x axis (-1 to 1). If set, disables random rotations.
-sy	--speedy	float	0.4	Rotational speed around the y axis (-1 to 1). If set, disables random rotations.
-sz	--speedz	float	0.6	Rotational speed around the z axis (-1 to 1). If set, disables random rotations.
-f	--fps	int	40	Throttle the fps at which the graphics can be rendered (lower it if high CPU usage or if flicker)
-r	--random	no argument	On	Rotate the shape randomly and sinusoidally.
-cx	--cx	int	0	x-coordinate of the shapes's center in pixels
-cy	--cy	int	0	y-coordinate of the shapes's center in pixels
-cz	--cz	int	0	z-coordinate of the shapes's center in pixels
-wi	--width	int	60	Width of shape in pixels
-he	--height	int	60	Height of shape in pixels
-de	--depth	int	60	Depth of shape in pixels
-ff	--from-file	string	./mesh_files/cube.scl	The filepath to the mesh file to render. See mesh_files directory.
-mi	--maximum-iterations	int	Inf/ty	How many frames to run the program for
-up	--use-perspective	no argument	Off	Whether or not to use pinhole camera's perspective transform on rendered pixels
-be	--bounce-every	int	0	If non-zero (-be N or --bounce-every N), changes moving direction every N frames
-mx	--movex	int	2	Move the object by this many pixels along x axis per frame if bounce (-b/--bounce) is enabled.
-my	--movey	int	1	Move the object by this many pixels along y axis per frame if bounce (-b/--bounce) is enabled.
-mz	--movez	int	1	Move the object by this many pixels along z axis per frame if bounce (-b/--bounce) is enabled.

Below are two examples of running the demo binary ./cube:

./cube	./cube -b 100 -cz 300 -my -1 -mz 1 -up

4.2 Tips

1. If the CPU usage is too high (it was low on my ancient laptop), you can reduce the fps e.g. to 15 by: ./cube -f 15 or ./cube --fps 15.

5. Contributing

If you'd like to contribute, please follow the codiing guidelines (section 3.1) and make sure that it builds and runs. I'll be happy to merge new changes.

Kudos to:

• @pmarreck - Nix packaging
• @Quantenzitrone - Fixing and competing nix packaging, including the mesh text files properly, tidying up the make build
• @IchikaZou - porting to Gentoo
• Anyone else who opened an issue for helping me make this project more robust.

retrocube's Issues

SIGSEGV

i haven't investigated further, but when trying to run it with

nix run github:leonmavr/retrocube

i get a SIGSEGV

so your code seems to be broken

make failed. Not sure what dependency missing.

Distribution: Gentoo
Error output: https://dpaste.com/3Y7ZHJTRF

I have ncurses installed but not sure what go wrong.

lag with perspective and larger cube sizes

Since I updated retrocube last the command

cube -wi 200 -de 200 -he 200 -sx 0.99 -sy 0.90 -up

doesn't work properly anymore
on commit 76a13dc378c1dd611819e504d9ba6d00f9649754:

2023-09-13.16-09-56.mp4

on current HEAD (95bf2f54ff98813921d34723afb3f467dc912ad3):

2023-09-13.16-10-37.mp4

The cube offset in the videos is just because I recorded my terminal window on the left with obs and somehow obs still recorded in 1920x1080

i also tried to record with asciinema, but it didn't work well

TermSaver?

Any idea how I could turn that into a terminal saver once the computer is xy min not used

Nothing showed up in after executing ./cube

I've successfully built the file, although it has some arbitrary errors (like obj_plane_z_at_xy declared but never defined), but it builds just fine. The real problem is nothing showed up after executing ./cube. At first I thought it was because I was in terminal that has theme and I'm running the file inside tmux, but it's the same after using a different terminal. I'm guessing it has something to do with libncurses. I've tried using libncurses5-dev and libncurses and nothing works. I'm using Ubuntu 20.04.