Laki

An assembler and emulator for the Laki stack-machine, written in ANSI C.

Laki is in early stages of development and dramatic changes are likely to occur!

This codebase was forked from the Uxn ANSI C virtual machine, and would not have been possible without the hard work of Devine Lu Linvega, Andrew Alderwick, Andrew Richards, and many others. The vast majority of this code (plus this readme) was written by them.

The primary difference between Laki and Uxn is the addition two modes (immediate and absolute) which are mixed with the existing modes (short, keep, return) to give four distinct mode combinations. This streamlines many operations to occupy less space in the program and execute slightly faster.

Renamed opcodes:

• ROT: DIG
• JCN: JIF
• JSR: JUB
• LDZ/STZ: LAZ/SAZ
• LDR/STR: LOF/SOF
• LDA/STA: LAB/SAB
• DEO/DEI: LEV/SEV
• ORA: BOR
• EOR: XOR

Replacements:

• LIT/LIT2: PSH:/PSH2:
• JMP2r: RET
• JMP2/JCN2/JSR2: JMP2a/JIF2a/JUB2a

Removed:

• NEQ has been removed (in favor of DEC). SUB can often act as a standin, or SUB2 ORA for NEQ2.

Other:

• Unsupported r return mode instructions: The simplest conversion is to wrap each instruction in two FLP instructions. Code can sometimes be reworked to reduce redundant swapping.
• Runes: Most of the primary runes (@&$=.,_!~"()[]) all function essentially the same as Uxntal. The two main differences are for immediate jumps, which by default are byte-distance. To indicate a short jump include a + sign, such as +func, ?+func, or !+func. This also applies to lambdas. In addition, the absolute short rune ; has been changed to : for consistency with . and , runes, as well as to make way for a relative short rune ;.

Build

Linux/OS X

To build the Laki emulator, you must install SDL2 for your distro. If you are using a package manager:

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(lakasm) and emulator(taka) are created in the ./bin folder.

./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:

cc src/devices/datetime.c src/devices/system.c src/devices/console.c src/devices/file.c src/laki.c -DNDEBUG -Os -g0 -s src/lakli.c -o bin/lakli

Plan 9

To build and install the Laki emulator on 9front, via npe:

mk install

If the build fails on 9front because of missing headers or functions, try again after rm -r /sys/include/npe.

Windows

Laki can be built on Windows with MSYS2. Install by downloading from their website or with Chocolatey with choco install msys2. In the MSYS shell, type:

pacman -S git mingw-w64-x86_64-gcc mingw64/mingw-w64-x86_64-SDL2
export PATH="${PATH}:/mingw64/bin"
git clone https://codeberg.org/tbsp/laki.git
cd laki
./build.sh

If you'd like to work with the Console device in taka.exe, run ./build.sh --console instead: this will bring up an extra window for console I/O unless you run taka.exe in Command Prompt or PowerShell.

Getting Started

Emulator

To launch a .aki in the emulator, point the emulator to the target rom file:

bin/taka2 bin/piano.aki

You can also use the emulator without graphics by using lakli.

Assembler

The following command will create an Laki-compatible rom from a lakital file. Point the assembler to a .lak file, followed by and the rom name:

bin/lakasm projects/examples/demos/life.lak bin/life.aki

I/O

You can send events from Laki to another application, or another instance of Laki, with the Unix pipe.

taka2 orca.aki | 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 debug
• F3 capture screen
• F4 reboot
• F5 soft reboot
• F11 toggle fullscreen
• F12 toggle decorations

GUI Buttons

• LCTRL A
• LALT B
• LSHIFT SEL
• HOME START

Need a hand?

The following resources are a good place to start:

• WastingMoves - lakital
• XXIIVV — uxntal
• XXIIVV — uxntal reference
• compudanzas — uxn tutorial
• Fediverse — #uxn tag