proposal

proposal.txt

@@ -0,0 +1,64 @@
+uxn rom metadata proposal
+
+by d6
+
+currently uxn rom files are just the data that will be loaded into the VMs
+memory on start up (starting with address 0x100 since the zero page is
+skipped). this means that the maximum rom size is 65280 bytes, although
+most roms are much smaller since trailing zeros can be left out.
+
+this simplicity is great, but comes with some (possible) downsides:
+
+ - roms aren't identifiable beyond their file name
+ - roms don't contain any attribution information, credits, or licenses
+ - roms don't contain a version information (rom version or uxn version)
+ - roms don't contain any icon or preview information
+
+while it would be nice to add all of these things that would create a major
+burden on assembler and emulator authors. i think there's an easier path
+forward.
+
+i propose adding four bytes to the start of every rom:
+
+ - the literal 3 bytes "uxn"
+ - a fourth mode byte
+
+this proposal just covers mode 0 and mode 1, but in the future we have up to
+254 other modes to use (though we might choose to forbid those later to keep
+things simple).
+
+the "uxn0" format would be exactly what we have now, just with those four
+bytes at the start. assembler authors could choose to only support creating
+"uxn0" roms without very much extra effort over what they do now. emulator
+authors could easily adapt their current work to read this format. rom files
+that lack a "uxn" at the start could continue to work as they do now.
+
+the "uxn1" format would provide some extra metadata:
+
+ - total-size   (2 bytes):  total metadata size (including "uxn1")
+ - uxn-version  (2 bytes):  0x0000 for unspecified, 0x0001 for current
+ - name-size    (1 byte):   size of the following name string in bytes
+ - name         (n bytes):  the name string (ASCII/UTF-8)
+ - version-size (1 byte):   size of the version string in bytes
+ - version      (n bytes):  the version string (ASCII/UTF-8)
+ - author-size  (1 byte):   size of the author string in bytes
+ - author       (n bytes):  the author string (ASCII/UTF-8)
+ - desc-size    (2 bytes):  size of the description string in bytes (4096 max)
+ - desc         (n bytes):  the description string (ASCII/UTF-8)
+ - icon-type    (1 byte):   the size and depth of the icon
+ - icon-palette (n bytes):  the icon's color theme
+ - icon-chr     (n bytes):  the icon's CHR data
+
+the minimal "uxn1" header size (assuming the strings and icon are all empty)
+would be 10 bytes (2 + 2 + 1 + 1 + 1 + 2 + 1). emulator implementors could
+read total-size and then seek past this metadata to read the rom data.
+
+the icon types would be:
+
+ - 0x00: no icon provided (0-byte icon-palette,    0-byte icon-chr)
+ - 0x01: 1-bit 16x16 icon (2-byte icon-palette,   32-byte icon-chr)
+ - 0x02: 1-bit 32x32 icon (2-byte icon-palette,  128-byte icon-chr)
+ - 0x03: 1-bit 64x64 icon (2-byte icon-palette,  512-byte icon-chr)
+ - 0x81: 2-bit 16x16 icon (6-byte icon-palette,   64-byte icon-chr)
+ - 0x82: 2-bit 32x32 icon (6-byte icon-palette,  256-byte icon-chr)
+ - 0x83: 2-bit 64x64 icon (6-byte icon-palette, 1024-byte icon-chr)