From ba28d2440304b7cc4ac2f5f53fcfcf8d7ff6b9a7 Mon Sep 17 00:00:00 2001
From: Devine Lu Linvega <aliceffekt@gmail.com>
Date: Sun, 28 Dec 2025 16:45:34 -0800
Subject: [PATCH] New README

---
 README.md | 113 +++++++++---------------------------------------------
 1 file changed, 18 insertions(+), 95 deletions(-)

diff --git a/README.md b/README.md
index 6d35a45..cb24cbc 100644
--- a/README.md
+++ b/README.md
@@ -1,117 +1,40 @@
 # Uxn
 
-An assembler and emulator for the [Uxn stack-machine](https://wiki.xxiivv.com/site/uxn.html), written in ANSI C. 
+Hi!
+So you're interested in find a Varvara emulator for your system.
 
-## Build
+## Download an emulator
 
-### Linux/OS X
+First, based on what you're trying to do, you can pick one of these emulators:
 
-To build the Uxn emulator, you must install [SDL2](https://wiki.libsdl.org/) for your distro. If you are using a package manager:
+- [uxn2](https://git.sr.ht/~rabbits/uxn2)(recommended), a graphical emulator, written in SDL2.
+- [uxn11](https://git.sr.ht/~rabbits/uxn11), a partial graphical emulator, ideal for productivity.
+- [uxncli](https://git.sr.ht/~rabbits/uxncli), a terminal emulator, ideal for running cli tools.
+- [uxnmin](https://git.sr.ht/~rabbits/uxnmin), a minimal terminal emulator, ideal for bootstrapping.
 
-```sh
-sudo pacman -Sy sdl2             # Arch
-sudo apt install libsdl2-dev     # Ubuntu
-sudo xbps-install SDL2-devel     # Void Linux
-brew install sdl2                # OS X
-```
-
-Build the assembler and emulator by running the `build.sh` script. The assembler(`uxnasm`) and emulator(`uxnemu`) are created in the `./bin` folder.
-
-```sh
-./build.sh 
-	--debug # Add debug flags to compiler
-	--format # Format source code
-	--install # Copy to ~/bin
-```
-
-If you wish to build the emulator without graphics mode:
-
-```sh
-cc src/devices/datetime.c src/devices/system.c src/devices/console.c src/devices/file.c src/uxn.c -DNDEBUG -Os -g0 -s src/uxncli.c -o bin/uxncli
-```
-
-### Plan 9 
-
-To build and install the Uxn emulator on [9front](http://9front.org/), via [npe](https://git.sr.ht/~ft/npe):
-
-```rc
-mk install
-```
+## Use the emulator
 
-If the build fails on 9front because of missing headers or functions, try again after `rm -r /sys/include/npe`.
-
-### Windows
-
-Uxn can be built on Windows with [MSYS2](https://www.msys2.org/). Install by downloading from their website or with Chocolatey with `choco install msys2`. In the MSYS shell, type:
+Next, to use an emulator, open a terminal window and launch it like this:
 
 ```sh
-pacman -S git mingw-w64-x86_64-gcc mingw64/mingw-w64-x86_64-SDL2
-export PATH="${PATH}:/mingw64/bin"
-git clone https://git.sr.ht/~rabbits/uxn
-cd uxn
-./build.sh
+uxnemu program.rom argument1 argument2
 ```
 
-If you'd like to work with the Console device in `uxnemu.exe`, run `./build.sh --console` instead: this will bring up an extra window for console I/O unless you run `uxnemu.exe` in Command Prompt or PowerShell.
-
-## Getting Started
-
-### Emulator
+## Write programs
 
-To launch a `.rom` in the emulator, point the emulator to the target rom file:
+Lastly, to turn a source file into a rom, you need a compiler, like [Drifblim](https://git.sr.ht/~rabbits/uxnmin), it comes in 3 flavors.
 
 ```sh
-bin/uxnemu bin/piano.rom
+uxnemu drifblim.rom source.tal program.rom
 ```
 
-You can also use the emulator without graphics by using `uxncli`. You can find additional roms [here](https://sr.ht/~rabbits/uxn/sources), you can find prebuilt rom files [here](https://itch.io/c/248074/uxn-roms). 
-
-### Assembler 
-
-The following command will create an Uxn-compatible rom from an [uxntal file](https://wiki.xxiivv.com/site/uxntal.html). Point the assembler to a `.tal` file, followed by and the rom name:
-
-```sh
-bin/uxnasm projects/examples/demos/life.tal bin/life.rom
-```
-
-### I/O
-
-You can send events from Uxn to another application, or another instance of uxn, with the Unix pipe. For a companion application that translates notes data into midi, see the [shim](https://git.sr.ht/~rabbits/shim).
-
-```sh
-uxnemu orca.rom | shim
-```
-
-## GUI Emulator Options
-
-- `-2x` Force medium scale
-- `-3x` Force large scale
-- `-f`  Force fullscreen mode
-- `--`  Force next argument to be read as ROM name. (This is useful if your ROM file is named `-v`, `-2x`, and so forth.)
-
-## GUI Emulator Controls
-
-- `F1` toggle zoom
-- `F2` toggle debugger
-- `F3` quit
-- `F4` reboot
-- `F5` reboot(soft)
-- `F11` toggle fullscreen
-- `F12` toggle decorations
-
-### GUI Buttons
-
-- `LCTRL` A
-- `LALT` B
-- `LSHIFT` SEL 
-- `HOME` START
-
-## Need a hand?
+## Learn more
 
 The following resources are a good place to start:
 
-* [XXIIVV — uxntal](https://wiki.xxiivv.com/site/uxntal.html)
-* [XXIIVV — uxntal reference](https://wiki.xxiivv.com/site/uxntal_reference.html)
+* [XXIIVV — Uxn](https://wiki.xxiivv.com/site/uxn.html)
+* [XXIIVV — Uxntal](https://wiki.xxiivv.com/site/uxntal.html)
+* [XXIIVV — Varvara](https://wiki.xxiivv.com/site/varvara.html)
 * [compudanzas — uxn tutorial](https://compudanzas.net/uxn_tutorial.html)
 * [Fediverse — #uxn tag](https://merveilles.town/tags/uxn)