guides

Getting started

A rocinante program is called a sketch. You write it in a plain text file, sketch.roci, and the roci program runs it in a window. While it runs, every time you save the file the window changes to match.

Installing

For the alpha, rocinante is built from its source, on Windows, Linux, FreeBSD, OpenBSD or macOS. You need three things: git, Odin (the language rocinante is written in) at the version named in the repository’s ODIN_VERSION file, and SDL3 (windows, input and graphics). odin version says which Odin you have.

Windows

1. Install Build Tools for Visual Studio from Microsoft’s Visual Studio downloads, with the Desktop development with C++ workload. Odin needs its compiler and the Windows SDK.
2. Download Odin from its releases (the windows-amd64 archive of the version in ODIN_VERSION), unpack it, and add its folder to your PATH.
3. Install git from git-scm.com if you do not have it. SDL3 comes with Odin, so there is nothing more to install.

Build it in a terminal (Command Prompt or PowerShell); Odin finds Visual Studio’s compiler by itself:

git clone https://github.com/sandbenders/rocinante
cd rocinante
odin build cli -out:roci.exe -o:speed

A program that opens a window needs SDL3’s library beside it on Windows: copy SDL3.dll from the vendor\sdl3 folder inside Odin’s folder (odin root prints where that is) into the folder that holds roci.exe.

Linux

Install git, clang (which Odin uses to link) and SDL3, and Odin itself where the distribution packages it:

Arch keeps its odin package current; check that odin version matches ODIN_VERSION. Debian, Ubuntu and Fedora do not package Odin (the odin package on Debian and Ubuntu is a different program, for medical imaging), so on those download Odin from its releases: the linux-amd64 or linux-arm64 archive of the version in ODIN_VERSION. Unpack it and add its folder to your PATH.

Older releases (Ubuntu 24.04, Debian 12) have no SDL3 package. Build it with the repository’s own script, which the pipelines use: tools/ci/install-sdl3.sh ~/sdl3, then point the compiler at it with export LIBRARY_PATH=~/sdl3/lib and export LD_LIBRARY_PATH=~/sdl3/lib. It needs cmake, ninja and the development packages of X11 or Wayland.

FreeBSD

FreeBSD packages Odin as odin-lang:

sudo pkg install git odin-lang sdl3

Check that odin version matches ODIN_VERSION.

OpenBSD

OpenBSD packages SDL3; Odin is built from its source, which takes a few minutes. Use the version named in ODIN_VERSION as the branch:

doas pkg_add git gmake sdl3 llvm%19
git clone --branch dev-2026-10 --depth 1 https://github.com/odin-lang/Odin
cd Odin
LLVM_CONFIG=/usr/local/llvm19/bin/llvm-config gmake release-native

Then put that Odin folder on your path (the odin program has to stay beside its base, core and vendor folders), and check that odin version matches ODIN_VERSION.

macOS

1. Install Apple’s command-line tools, which include git: xcode-select --install.
2. Install Odin and SDL3 with Homebrew: brew install odin sdl3. Check that odin version matches ODIN_VERSION; if Homebrew’s Odin is newer or older, download the macos-arm64 archive of the right version from Odin’s releases instead.

Building roci

On Linux, FreeBSD, OpenBSD and macOS:

git clone https://github.com/sandbenders/rocinante
cd rocinante
odin build cli -out:roci -o:speed

That makes the program roci in the folder (roci.exe on Windows). Put it somewhere on your path, or run it from there as ./roci (roci on Windows).

Your first sketch

roci new my-sketch
cd my-sketch
roci run

roci new makes a folder with a sketch in it, and roci run opens a window and draws it. The sketch is one line:

circle at 100 100 radius 50

Open sketch.roci in any text editor, put this line under the first one, and save:

circle at 100 100 radius 50rect at 200 60 size 160 90 fill orange

The window changes straight away; you do not have to run it again. Leave roci run going while you work.

When something is wrong

Make a mistake on purpose: change circle to circel and save. The window keeps the last good picture and shows, across the top, what went wrong, and the terminal says the same:

── I don't know the word `circel` ────────────────────── sketch.roci:1:1

1 │ circel at 100 100 radius 50
  │ ^^^^^^

A line starts with a verb, a keyword or a name, and I don't know `circel`. Check the spelling, or teach the word with `learn`.

Did you mean:  circle at 100 100 radius 50

Every message says where the problem is, what it is in plain words, and shows a line that would work. Put the word right, save, and the picture comes back. The messages page lists them all.

Other things roci does

Two keys work in every sketch window:

edit this page on GitHub