From d293f8f84d7164ac00373c14a914fa88fb25601e Mon Sep 17 00:00:00 2001 From: d6 Date: Fri, 11 Nov 2022 18:19:37 -0500 Subject: [PATCH] proposal --- proposal.txt | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 proposal.txt diff --git a/proposal.txt b/proposal.txt new file mode 100644 index 0000000..2e6a9e8 --- /dev/null +++ b/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)