1. Uxn Beginnings

Monday 27th July 2026

Uxn Intro

Uxn is a tiny 8bit virtual machine with 64kb of memory. This series of posts attempts to implement each part of the machine in Kotlin with the aim of ending up with a working system that can execute Uxn roms. We'll need a basic array for memory, and a simple stack implementation, other than that a switch/when statement of some kind to implement each of the 40 opcodes (32 standard, and 8 immediate) that manipulate the stacks. Once the main Uxn machine (CPU) is implemented a computer interface is needed to read from and talk to the outside world, this is called Varvara, but we're a long way from that yet.

uxnk is a similar Kotlin Uxn implementation (and much more complete) but it only targets the JVM and uses Kotlin unsigned types instead of masked integers (Uxn values are unsigned bytes (0–255) and shorts (0–65535)). I'll reference some of uxnk's ideas while implementing this version which I'm calling kuxn for now (Kotlin-Uxn) but won't use/borrow/steal any code.

Ram

We need to model 64KB of ram (65,536 bytes). The simplest way is an integer array: val ram = IntArray(0x10000) with and 0xff used throughout to mask 8bits and and 0xffff to mimic the 16bit address space (pointer locations, memory addresses, short results).

Stacks

Uxn has two 256 byte stacks with simple push and pop operations. A stack is modelled in the simplest way possible:

class Stack {
    val data = IntArray(0x100)
    var pointer = 0
    
    //push/pop helpers
    ...

Opcodes

An opcode (operation code), eg ADD, can have three optional flags: 2, k, r (eg. ADDk, ADD2kr)

2

Short mode, makes an opcode work on shorts instead of bytes.

k

Keep, tells the stack to keep the operands rather than pop them from the stack. Where a stack has 01 and 02 on the stack a standard ADD pops both operands and pushes the result: pop 01, pop 02, then push the result push 03 leaving just 03 on the stack. ADDk leaves the operands on the stack and pushes the result: push (01 + 02) (or 1 2 + in postfix), the stack increases from two operands to three: 01 02 03.

r

Return mode. Target the return stack instead of the working stack. Again, I'll discover the implications of this as we go but it's a Forth idiom which I've only played with a little previously. A second stack gives you a convenient place to push things without having to do it in-place within a single stack.