A collection of Varvara application support standards.
This is a collection of various libraries used in the Varvara roms.
Theme files are the interface customization standard for Varvara software.
A .theme file begins with 6 bytes equal to the RGB values of 4 colors. You can see support overage here.
0a6f 05cf 0caf , or #000000 #aa55cc #66ccaa #ffffff
You can use the following Uxntal routine to implement theme support to your application:
@load-theme ( -- ) ;&path .File/name DEO2 #0002 .File/length DEO2 [ LIT2 -System/debug -System/r ] &loop ;&buf .File/read DEO2 .File/success DEI2 ORA ?&end POP2 JMP2r &end DUP [ LIT2 &buf $2 ] ROT DEO2 INC INC NEQk ?&loop POP2 JMP2r &path ".theme $1
Design Standard
The order in which color are used are as follows:
| Normal | Background/alpha | Selection | Foreground | Application |
|---|---|---|---|---|
| Monochromatic | Background/alpha | White | Black2 | White2 |
Emulators for monochromatic screens do not support Varvara's colors, instead will display colors 0x00 and 0x02 as black, 0x01 and 0x03 as white.
Four colors should be more than enough for any interface.
Snarf files are the clipboard standard for Varvara software.
A .snarf file contains a clipboard buffer, programs will handle clipboard operations by writing to that external invisible file. You can see support coverage here.
The cut operation deletes the selected text from the screen and puts it in the snarf buffer, snarf copies the selected text to the buffer without deleting it, paste replaces the selected text with the contents of the buffer.
( snarf ) @snarf-txt ".snarf $1 @edit-copy ( -- ) ;snarf-txt .File/name DEO2 #0100 .File/length DEO2 ;buffer .File/write DEO2 JMP2r @buffer $100
Snarf is the term for Copy on the Plan9 operating system. The operation is not to copy but to snarf. It's called snarf because snarf is what it does. There is no design document.
Symbol files are debug information about an assembled rom.
A symbols(*.sym) file is a binary format that contains a series of symbols in the format: an absolute addresses, where the first byte is the most significan byte, the second is the least significant byte, followed by a null-terminated string. They are generated by Uxntal assemblers, such as Drifblim, and are used by debugging tools, such as Beetbug, which do not otherwise have access to a program's labels.
0140 on-draw 0142 on-draw/loop 01a8 clip-tile 01f2 ...
Metadata exposes additional information about a Varvara rom.
An external program can find the location of a ROM's metadata, by forming a 16-bit address from the second and third bytes of a rom file. That program can verify that this is indeed a valid address by reading the subsequent 3 bytes which should always be 80 06 37.
| First six bytes | ||||||
|---|---|---|---|---|---|---|
| LIT2 | address | LIT | port | DEO2 | ... | |
| a0 | hb | lb | 80 | 06 | 37 | ... |
The body of the metadata can be anything, but it is recommended that it be plain-text with 0a as line separator, and that the first line be the name of the application. Here are some suggestions for lines to include in the body of the metadata:
- name: application name
- version: release id
- description: what it is
- author: who built it
The metadata is stored in the rom itself to allow the program to make use of this information internally. The entire size of the metadata should be at most 256 bytes.
Implementation
The metadata format begins with a byte for the varvara version, followed by a null-terminating text:
|0100 ( -> ) ;meta #06 DEO2 BRK @meta 00 &body ( name ) "Nasu 0a ( details ) "A 20 "Sprite 20 "Editor 0a ( author ) "By 20 "Hundred 20 "Rabbits 0a ( date ) "Jan 20 "8, 20 "2023 00 02 ( icon ) 83 =appicon ( mask ) 41 1705
If supported by the emulator, writing the metadata's address to the system device, via #06 DEO2, informs the emulator of the metadata's location, and it may choose to handle this information when a ROM is started.
Extended
The length of the metadata can be extended and host various other informations. The format for the fields is: a single byte id field, followed by a 2 bytes value field.
| Application | id | value |
|---|---|---|
| -- | 41 | Expected device mask. |
| Potato | 83 | 24x24 icon in the chr format. |
| 88 | 64x64 icon in the icn format. | |
| a0 | The application manifest. |
Reading Metadata
A program can check a rom for metadata with the following routine:
@has-meta ( filename* -- bool ) .File/name DEO2 #0003 .File/length DEO2 ;&b .File/read DEO2k DEO2 ,&litport LDR2 #8006 EQU2 ,&deo2 LDR #37 EQU AND JMP2r &b &litport $2 &deo2 $1
Manifest exposes a rom's features.
A manifest is a simple data structure that allows Varvara applications to specify what feature can be reached by shortcuts.
The manifest.tal is a support library created to this end. You can see support coverage here, it is also used in the definition of applications in Potato.
@manifest 04 "Application $1 01 'n :file-new "New $1 01 'r :file-rename "Rename $1 01 'o :file-open "Open $1 01 's :file-save "Save $1 03 "Edit $1 01 'c :edit-copy "Copy $1 01 'v :edit-paste "Paste $1 01 'x :edit-cut "Cut $1 02 "Select $1 00 1b :select-reset "Reset $1 01 'a :select-all "All $1 $1