uxn tutorial

en español: tutorial de uxn

a beginner's, slow-paced and comprehensive guide for programming the varvara computer based on the uxn core.

if you prefer video, you can watch a short intro to uxn programming workshop that we taught as an introduction.

IMPORTANT (12024-03-28)! even though we updated to some extent the tutorial during our maintenance practice, and in principle everything that we say here works, keep in mind that it is written from a somewhat outdated perspective. some things are done differently now, and the tutorial doesn't cover all the possibilities in the language that exist nowadays. in doubt, always refer to the official documentation. however, we hope it's still useful to you as an introduction to the uxn ecosystem!

XXIIVV — uxn official documentation

if you'd like to contribute improving the tutorial, check out our to-do list in the roadmap and contact us!

there is an offline version of this guide as the introduction to uxn programming book, but it still needs to incorporate some of the changes we did here.

day 1

in this first section of the tutorial we talk about the basics of the uxn computer called varvara, its programming paradigm in a language called uxntal, its architecture, and why you would want to learn to program it.

we also jump right in into our first simple programs to demonstrate fundamental concepts that we will develop further in the following days.

uxn tutorial day 1

day 2

in this section we start exploring the visual aspects of the varvara computer: we talk about the fundamentals of the screen device so that we can start drawing on it!

we also discuss working with shorts (2-bytes) besides single bytes in uxntal.

uxn tutorial day 2

screenshot of the output of the program, showing 16 squares colored with different combinations of outline and fill.

day 3

here we introduce the use of the controller device in the varvara computer: this allows us to add interactivity to our programs, and to start implementing control flow in uxntal.

we also talk about logic and stack manipulation instructions in uxntal.

uxn tutorial day 3

screenshot of a possible result of running the following program; it shows a trail drawn with filled or outlined squares.

day 4

here we discuss the animation loop of the varvara computer, via its screen device vector!

we also talk about using the program memory as a space for data via "variables", in order to have some persistency of data during the runtime of our programs, and/or in order to save us from complex stack wrangling :)

uxn tutorial day 4

day 5

here we introduce the varvara mouse device to explore more possible interactions, and we cover the remaining elements of uxntal and uxn: the return stack, the return mode and the keep mode.

we also discuss possible structures to create loops and more complex programs using these resources!

uxn tutorial day 5

screenshot showing a drawing made with the mouse: wiggly lines composed of overlapped squares of two different colors

day 6

here we talk about how we can integrate everything that we have covered in order to create even more complex subroutines and programs for the varvara computer.

we base our discussion in a recreation of the classic pong game!

besides using previous strategies and snippets of code, we cover strategies for drawing and controlling multi-tile sprites, and for checking collisions.

uxn tutorial day 6

screenshot showing the stage of the pong game: a couple of paddles at the sides, and a ball at the center

day 7

here we talk about the devices in the varvara computer that we haven't covered yet: audio, file, and datetime.

this should be a light and calm end of our journey, as it has to do less with programming logic and more with the input and output conventions in these devices.

uxn tutorial day 7


appendix a: generalized rectangular tiles drawing

in this appendix we generalize the background drawing procedure discussed on day 6, into a draw-tiles subroutine that draws an arbitrary rectangle filled with a given tile.

we detail how to get to two versions of this subroutine, one that relies on heavy stack wrangling, and other one that uses variables. this in order to compare both approaches and give us a broader view of the possibilities within uxntal.

uxn tutorial appendix a

DEPRECATED appendix a: the on-screen debugger

in this appendix we introduce the use of the on-screen debugger available in uxnemu once we set up the system colors.

uxn tutorial deprecated appendix a

external resources

learn-uxn by metasyn

uxn technical documentation

uxn illustrated notes

the uxntal opcode manual

uxntal cheatsheet

uxn repository

llllllll forum

awesome uxn: awesome things from the community

#uxn in merveilles


this is a summary of the uxn instructions covered in each day of the tutorial.

short mode is covered on day 2, and return and keep mode are covered on day 5.

you can find a more detailed reference of all the opcodes in the uxntal opcode manual

the uxntal opcode manual

day 1

day 2

day 3

day 4

day 5


if you enjoyed this tutorial and found it helpful, consider sharing it and giving it your support :)

incoming links