sejo vga - introduction to uxn programming

a beginner's, slow-paced and comprehensive guide of the uxntal programming language and the varvara computer.

by sejo vga

foreword by Devine Lu Linvega

written and illustrated by sejo vga

foreword by Devine Lu Linvega

published by compudanzas

compudanzas.net

compudanzas@posteo.net

this publication is licensed under the Peer Production License (2010).

commercial use encouraged for independent and collective/commons-based users.

to view a full copy of this license, see:

Peer Production License

copyfarleft - sejo vga

mexico city, january 2022

this book wouldn't have existed without the love of mel*, the encouragement by Devine Lu Linvega, Andy Alderwick and Lee Tusman, the amazing work by 100R, the supporters of compudanzas, and the inspiration from the Merveilles community.

thank you!

It is with great pleasure that I am responding to the request of a foreword to the first edition of Compudanzas' Uxntal tutorial. The Uxntal language was barely formed, and already Sejo was assembling what was to become the ultimate guide to breaking into that strange programming language. In many ways, the writing of this book was a sort of conversation, in which the documentation of the language directly impacted its evolution.

I am forever grateful for Sejo's work in assembling these clever lessons, they've helped many of today's Uxntal programmers, and I myself have often gone back to the book to refresh my memory. I am certain that it will capture the imagination of its readers, and act as an invitation to Uxn's welcoming community.

- Devine Lu Linvega

December, 2021

welcome to this beginner's, slow-paced and comprehensive guide of the uxntal programming language and the varvara computer!

this book will provide you with the basics for getting involved with the uxn ecosystem, one step at a time.

in this section we'll introduce what is uxn and why you would want to join its community. we also briefly describe the contents of each section of the book.

let's get started!

100R - uxn

uxn is the core of the varvara virtual computer. it is simple enough to be emulated by many old and new computing platforms, and to be followed by hand.

uxn is programmed in its own special programming language, uxntal.

i encourage you to read the "why create a smol virtual computer" section in the 100R page to get to know more about the story of the project:

100R - uxn

personally, i see in the uxn ecosystem the following features:

• built at a human-scale
• built for audiovisual and interactive applications
• simple architecture and instruction set (only 32 instructions!)
• offline-first: it works locally and you only need a couple of documentation files to get going
• practice and experimentation ground for computing within limits
• ported already to several years old and modern computing platforms

all these concepts sound great to me, and hopefully to you too!

however, i see in it a couple of aspects that may make it seem not too very approachable:

• its programming language, uxntal, is an assembly language
• it uses postfix notation (reverse polish notation) and it is inspired by forth machines

the idea of this guide is to explore these two aspects and reveal how they play along to give uxn its power with relatively little complexity.

the guide is divided in seven "days".

the idea is you can follow it along during one week of focus, and then you can be ready to tackle and create the applications you'd like!

in this first section we talk about the basics of the uxn computer called varvara, its programming paradigm in its language uxntal, and its architecture.

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

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.

in the third day 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.

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 :)

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!

almost done! 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.

finally, 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.