Uxn-Lua

A port of the Uxn instruction set and Varvara virtual computer to the Lua language and the Love2D game engine. (削除) Is compatible with most ROMs, but runs at a much lower speed for cpu-intensive ROMs. (削除ここまで)

Original implementation by DeltaF1, updated in 2026 to current Uxn/Varvara specification.

Installation

Running the unit tests requires Busted

Running this repository as a Love game requires Love 11+

Running uxn.lua standalone requires Lua 5.3+.

Running uxnjit.lua standalone requires LuaJIT or a bitwise operations libray such as the standalone bitwise module

Quickstart

As a Love game

love .

Will try to load a file called boot.rom in the top-level directory.

love . somename.rom

Will try to load a file called somename.rom in the top-level directory.

Standalone use of the cpu

Uxn = require "uxn"
cpu = Uxn.Uxn:new()
values = {
	0x80, 0x13, -- LIT 0x13
	0x01, -- INC
	0x80, 0x37, -- LIT 0x37
	0x18, -- ADD
	0x00, -- BREAK
}
-- Copy the values offset by 255 so they start at the location of IP
for i = 1, #values do
	cpu.memory[i + 255] = values[i]
end
cpu:runUntilBreak(0x100)
-- Should print 75 or 0x4b
print(cpu.wst:pop())

CPU

Uxn:new([memory])

Optionally pass in a table that holds the contents of memory. Remember that this table is will be accessed starting at 0 unlike most Lua tables.

Uxn:runUntilBreak(addr)

Run the CPU starting at the given address until it hits a BRK instruction (0x00).

Uxn.dei[addr] = function and Uxn.deo[addr] = function

Adds a DEI/DEO handler to the specified device port. See the Varvara docs for standard device numbers.

Devices

In order to support device memory wrapping according to the specification devices use a single unified 256 byte memory region. Device handlers can be added by setting the appropriate dei/deo handler entry on the Uxn table. Device memory bytes can be directly accessed, while shorts can be accessed using the following functions.

Uxn:read_short_dev(addr)

Uxn:write_short_dev(addr, value)

Examples

Create a device handler that prints to the console every time port 0x08 is written to.

-- Add a byte port at 0x08
cpu.deo[0x08] = function(byte)
	print("wrote a byte", byte, "to port 0x08")
end

TODO

• Update tests
• Audio