Uxn - Virtual Computer

So, let’s have a dedicated Uxn thread!


  • Sound potato


Uxn is a portable 8-bit virtual computer inspired by forth-machines, capable of running simple tools and games programmable in its own assembly language.

In English: Imagine a workstation that is so simple that it can be implemented in an afternoon by a single person. Imagine that every tool/application is a only a few bytes. Software for Uxn are most similar to roms for the classic Nintendo, except that the console is designed especially for doing audio/visual works - with a mouse, a keyboard, midi I/O and Control Voltage.

It was designed with an implementation-first mindset with the goal of targeting salvaged computers. The distribution of Uxn projects is not unlike downloading a rom for a console, Uxn has its own emulator.


Back in 2016, we experienced frequent failures with both software & hardware, largely due to our small energy storage and lack of reliable connectivity. The solution was to create tools that would be better suited to our needs. The objective was to replace the bloated, closed-source or subscription software that we were using to do creative work, such as Photoshop, Xcode and Ableton. We were somewhat familiar with web technologies, so we decided to build our programs on this new framework called Electron.

While solving some of our issues, Electron was rapidly increasing in size and soon joined the rest of the software that we wanted to do away with. Our focus shifted toward reducing our energy use, and to ensure reliability by removing all dependencies.

To transition toward our new goals, we developed offline web versions as temporary stand-ins while researching ways to build more resilient software. We eventually ported our tools to C, but while we had achieved ideal energy usage, portability was still an issue, so we kept looking. We learnt 6502 assembly , seeing players run our NES game on all these different platforms gave us a new idea.

And so, in 2021 we took our biggest leap yet toward longtermism and designed a small virtual machine with a focus on implementability; meaning that moving forward, our software will live on a virtual machine. In other words, the code will stop having to be ported, but instead to make something available on a new platform would our needs or devices change, the emulator remains the only piece of code to be ported, which is explicitly designed to be easily implemented.

This is where we are now. uxn may solve our cross-platform issues, while being extremely light. It took us a long while to get here, we hope that one day the Uxn versions of our software replace the desktop and web versions.


Download and install SDL2, and build the emulator and assembler.

git clone https://git.sr.ht/~rabbits/uxn

That will launch the piano demo from the examples folder.


The following command will create an Uxn-compatible rom from an uxntal file, point to a different .tal file to assemble a different rom.

bin/uxnasm projects/examples/demos/life.tal bin/life.rom

To start the rom, point the emulator to the newly created rom:

bin/uxnemu bin/life.rom

You can find additional roms here.

This will be the official thread for Uxn related things, I’m currently porting Orca for this platform. If you’re interested in learning how to program for it, I’ll be happy to help you.

Related Readings


I might see if I can get this running on my pocket c.h.i.p. this weekend. :thinking::thinking:


This is one of the coolest projects I’ve seen in a while. Are there any videos of the VM running on hardware? Tracked down the git repos of some of the ports via your wiki but they all seem to just have photos.



Pi Pico





Ok, you got me. However I can learn, I want to do this.

Curious about synth/fx engine design in particular, bitwise manipulation tricks, and whatever else I can hack to make cool stuff. I haven’t dug super deep into what you’ve posted, but these photos got me.


Was interested, but then I saw the PS Vita.
Now I’m very interested!

So many times I have wept for the untapped musical potential
of the PS Vita hardware

1 Like

Wowow that pi Pico pic with the tiny screen has got my brain all excited about a uxn eurorack module… But also the idea of a little pi 4 creative cyberdeck running uxn is very very good


Curious about synth/fx engine design in particular, bitwise manipulation tricks, and whatever else I can hack to make cool stuff. I haven’t dug super deep into what you’ve posted, but these photos got me.

@wheelersounds The design of the APU is inspired from the way the sprites are drawn on the screen. The APU takes an address to anywhere in memory, it can even point to a picture, and will use that data as unsigned waveform for the sound.

I think that I heard Pokemon on the classic gameboy didn’t have enough space to fit sounds for every monster so they would play random bits of code for the creatures. Uxn works like that a bit.

For example, here’s a SINE wave encoded in bytes

8083 8689 8c8f 9295 989b 9ea1 a4a7 aaad
b0b3 b6b9 bbbe c1c3 c6c9 cbce d0d2 d5d7
d9db dee0 e2e4 e6e7 e9eb ecee f0f1 f2f4
f5f6 f7f8 f9fa fbfb fcfd fdfe fefe fefe
fffe fefe fefe fdfd fcfb fbfa f9f8 f7f6
f5f4 f2f1 f0ee eceb e9e7 e6e4 e2e0 dedb
d9d7 d5d2 d0ce cbc9 c6c3 c1be bbb9 b6b3
b0ad aaa7 a4a1 9e9b 9895 928f 8c89 8683
807d 7a77 7471 6e6b 6865 625f 5c59 5653
504d 4a47 4542 3f3d 3a37 3532 302e 2b29
2725 2220 1e1c 1a19 1715 1412 100f 0e0c
0b0a 0908 0706 0505 0403 0302 0202 0202
0102 0202 0202 0303 0405 0506 0708 090a
0b0c 0e0f 1012 1415 1719 1a1c 1e20 2225
2729 2b2e 3032 3537 3a3d 3f42 4547 4a4d
5053 5659 5c5f 6265 686b 6e71 7477 7a7d

Try the piano demo to see how it all works out. Here’s a little example file that plays popcorn.

To play a sound from Uxn, you need to write a few bytes to the Audio device:

#1202 .Audio0/adsr DEO2 # Enveloppe
;saw  .Audio0/addr DEO2 # Where the waveform is
#0100 .Audio0/length DEO2 # How long the waveform is
#ff   .Audio0/volume DEO # Volume/Balance
#40   .Audio0/pitch DEO # The Note, voila!

Official Documentation

When pitch is written to any of the audio devices, it starts playing an audio sample from Uxn’s memory, pointed to by addr* and length*. It loops the sample (unless told not to) until it reaches the end of the ADSR envelope defined by adsr*.

Each of the ADSR components is measured in 15ths of a second, so writing #ffff to adsr* will play a note that lasts for exactly four seconds, with each section of the envelope lasting one second. If adsr* is #0000 then no envelope will be applied: this is most useful for longer samples that are set to play once by setting the most significant bit of pitch to 1.

The envelope varies the amplitude as follows: starting at 0%, rising to 100% over the Attack section, falling to 50% over the Decay section, remaining at 50% throughout the Sustain section and finally falling to 0% over the Release section. The envelope is linearly interpolated throughout each section.

The two volume components set how loudly the next sample will play. #ff sets maximum volume for both speakers.

When pitch is written, any sample that is currently playing will be replaced with the sample defined by all the values set in the device. While the sample is playing, the output byte can be read to find the loudness of the envelope at that moment.

Audio Sample Format

All samples used by the audio devices are mono and unsigned 8-bit (also known as u8), so the space taken up by samples is minimized. The sample rate of the samples depends on length*:

length* Sample type Sample rate
> 256 Middle-C pitched sample 44,100 Hz
2–256 Single wavelength Variable

Long samples are assumed to be already pitched to Middle C and will loop (unless No Loop is 1) until the end of the envelope. To play the sample at the same rate as it was recorded, write the Middle C MIDI note number, #3c, to pitch. To play at double or half speed, for example, write an octave higher or lower to pitch.

The minimum sample size that can be pitched at 44.1 kHz to Middle C with reasonable accuracy is 337 bytes long, which represents two cycles of the 261 Hz wave. The single wavelength mode in Uxn allows much smaller samples to be used, even down to only two bytes for a square wave. In this mode the length of the entire sample is taken to be one cycle of the Middle C note, so the pitch is not heard to vary even if length* were to change between sample plays.


Such great info here!

I’m gonna elsborate with some thoughts but your reasons for creating uxn really resonated with me as i read

I feel dumb asking but how can this be losded on a ds? Haven’t used one in a long time…

The Nintendo DS has a pretty solid homebrew community, to run custom software on it, people use the carts with SD slots in them


The UxnDS emulator is a DS compatible program, that can load uxn roms. It also runs on the 3DS and make use of the 2 layers of the Uxn screen for depth, it’s pretty crazy. The DS is an excellent device for this since it has a good sound chip, a pointer and the two screen also allows for keyboard support.

Noodle on the Nintendo DS



I’m pretty sure i have that cart so i just need to find my ds and games (moved recently and it must be hiding)

gonna try loading some uxn roms on my laptop tonight to get familiar


amazing project, besides the assembler, do you know of any current projects that target the uxn vm? im interested in writing a more higher-level programming language for it, maybe something B-like?

1 Like

@cpunch There isn’t at the moment, you’d be the first to make one!

1 Like

Man, you’re gonna make me go and boot up my 3DS for the first time in ages!

What are the chances of this running on the slew of rk3326-based “retro” handhelds? I wouldn’t mind putting in the work to get it compiled & working within the UI if it’s usable with just normal controller inputs (so no touchscreen or kb+m).

That’s the same as Odroid right? I might misremember but I think someone already ported SDL2 for the device. It shouldn’t be too difficult to port. Uxn is written entirely in classic C89 and I know that there’s a complete C toolchain for these handhelds!


I’d be very interested to see this running on an FPGA. I’ve been imagining what might be possible with something like an Analogue Pocket. I bet one could even write ORCA to a flashcart if they were so inclined…

Come to think of it, if UXN can already potentially run on a GBA, then it should already be able to run on a Pocket. This is all very intriguing. Kudos.


Please lmk if you do! I have one sitting around and would be incredible to know if possible and how challenging to setup.

Uxn already runs on the GBA. I’d love to see a verilog of Uxn made – but I’m totally clueless when it comes to … the physical realm.


I’ve been interested in this since I saw some of your early videos. I have a gba and DS and look forward to giving it a try… I’d also like to get it running on Anbernic handhelds somehow? They definitely have applications running SDL2.


The DS version is the easiest to get up and running since it’s just a drop in rom, the gba has to emebbed the uxn rom. If you do get it going on the Anbernic, let me know, someone else was asking me about it this week.