package claudius

  1. Overview
  2. Docs

Description

A functional style retro-graphics library for OCaml for building generative art, demos, and games.

Tags

graphics rendering paletted

Published: 20 Aug 2025

README

Claudius - A fantasy retro computer library.

Claudius started out trying to be a functional library that works like a fantasy console system like TIC-80or PICO-8: A way to do some retro-style demo graphics programming but in OCaml rather than in LUA. In its current form it doesn't do nearly as much as those fantasy consoles, instead just concentrates on enabling you to make graphical demos, and lacks things like audio, expressive input support, sprite editors and so forth. But if your goal is to enter something like Tiny Code Christmas or Genuary, then Claudius is designed for that use case.

Credits

Sincere thanks from Claudius team to all those who have contributed or made suggestions - Claudius is made infinitely better for having diversity of influences!

Claudius uses Tamzen font as the default text font.

Using Claudius

Claudius is a library for OCaml to do retro-style graphics, and so you need to create a new project that uses Cladius. But because Claudius isn't currently in Opam, you'll need to add it into your project using one of the two methods:

Using Claudius

You should use dune to pin Claudius by adding it to the dune-project file for your repository - you can find an example project here. Basically you need to do two things:

Add the following to your dune-project file:

(pin
 (url "git+https://github.com/claudiusFX/Claudius.git")
 (package
  (name claudius)))

Then run:

$ dune pkg lock

Developing Claudius

If you want to make opensource contributions to Claudius, you are welcome to do so. For that you will need to use the below approach

If you're working on Claudius itself, then life is a bit easier using a vendor directory to add a version you can edit and commit to:

$ dune init proj myprogram
$ cd myprogram
$ mkdir vendor
$ cd vendor
$ echo "(vendored_dirs *)" > dune
$ git clone https://github.com/claudiusFX/Claudius.git
$ cd ..
$ git submodule update --init --recursive

Standard keys

Mostly Claudius doesn't have any interaction points beyond those you provide, but there are a few:

  • F1 - Show debug overlay
  • F2 - Save a screenshot to a GIF
  • F3 - Save an animation to a GIF

Docs

There are odoc documentation for most of Claudius. You can build that documentation with:

$ dune build @doc
$ open _build/default/_doc/_html/index.html

Or you can use whatever browser directly to open that index file.

Requirements

Claudius has been tested under macOS, Linux, and Windows via WSL, and requires that you have SDL 2 installed.

It requires OCaml 5 or newer (see here for installation instructions), and relies on tsdl for talking to SDL, and ounit2 for unit tests.

Troubleshooting

Some users running programs built with Claudius on Ubuntu via WSL may experience a segmentation fault causing the SDL window to crash. It can be fixed with adding the following environment variable before running your program. In your terminal enter the following commands:

$ export LIBGL_ALWAYS_SOFTWARE=1
$ dune exec myprogram

If you are using bash, you can add the above environment variable to your bashrc file:

$ echo 'export LIBGL_ALWAYS_SOFTWARE=1' >> ~/.bashrc
$ source ~/.bashrc
$ dune exec myprogram

Dependencies (5)

  1. crunch >= "4.0.0"
  2. giflib >= "1.0.3"
  3. tsdl >= "1.1.0"
  4. dune >= "3.17"
  5. ocaml >= "5.1"

Dev Dependencies (3)

  1. ocamlformat >= "0.27.0" & with-dev-setup
  2. odoc with-doc
  3. ounit2 with-test

Used by

None

Conflicts

None

OCaml

Innovation. Community. Security.