POP files


#1

Introduction

POP files, or Pokitto Programs, are like bin files, but can contain a lot more information.

The easiest way to make a POP is with the mkpop tool. Simply drag-and-drop your bin, fill in the title/author/description fields, and optionally drag-and-drop icons and screenshots. If you don’t have icons, it’ll make an attempt at generating one based on the title. It’s good to have at least a screenshot of the title screen.

In total, 4 icons will be stored inside the POP: two small (24x24 4bpp, 24x24 16bpp) and two large (36x36 4bpp, 36x36 16bpp). Color conversion is done automatically using @Pharap’s palette:
image


File Format

POP files are composed of a series of tags, their lengths and their data. There is no header, all tags are optional and can be in any order (though the mkpop tool puts smaller tags first). Unknown tags can be safely ignored and skipped.

With one exception, all tags have the following format:
[4 bytes tag Id] [4 bytes data length ] [ data bytes ]

The CODE tag does not have a data length. All bytes, including the tag id itself until the EOF, are considered the data.
All string tags have a data length and are zero terminated.

An enum with all the tags can be found here.

These are the currently defined tags:

  • 0 - PADDING: filler data used to align the following tag (currently unused)
  • 1 - INDEX: Data contains an index of following tags/offsets (currently unused)
  • 2 - OFFSETADDRESS: Used together with the CODE tag to define where that code should be located (default is zero)
  • 3 - CODECHUNK: Contains an offset address (4 bytes) followed by the code to load to that address.
  • 4 - ENTRYPOINT: Reserved
  • 5 - CRC: Intended to verify integrity of the game currently loaded in flash. (currently unused).
  • 6 - HAT: Intended to indicate required/compatible hats
  • 7 - LONGNAME: String. Name of the game without restrictions.
  • 8 - AUTHOR: String. Name of the author(s).
  • 9 - DESCRIPTION: String. Short description of the game.
  • 10 - IMG_36X36_4BPP: Large,16 color icon bitmap data
  • 11 - IMG_24X24_4BPP: Small, 16 color icon bitmap data
  • 12 - IMG_100X24_4BPP: Wide 16 color logo bitmap data (unused)
  • 13 - IMG_110X88_4BPP: Low-res 16-color screenshot (unused)
  • 14 - IMG_36X36_565: Large, High-color icon bitmap data
  • 15 - IMG_24X24_565: Small, High-color icon bitmap data
  • 16 - IMG_100X24_565: Wide, High-color logo bitmap data (unused)
  • 17 - IMG_110X88_565: Low-res High-color screenshot (unused)
  • 18 - IMG_220X176_565: High-res, High-color screenshot
  • 0x10008000 - CODE: Code that should be loaded into the OFFSETADDRESS. This tag has no size, it’s data is the remainder of the file so it should always be the last.

The mkpop tool currently emits the following tags:

  • LONGNAME
  • AUTHOR
  • DESCRIPTION
  • IMG_24X24_4BPP
  • IMG_24X24_565
  • IMG_36X36_4BPP
  • IMG_36X36_565
  • IMG_220X176_565 (for each screenshot)
  • CODE

Reading POP files

Here’s the basic idea, adapt to your specific use-case.

struct Tag {
	uint32_t id;
	uint32_t length;
};

Tag tag;

FILE *file = FS.fopen( fileName, "r" );

// While there are still tags to read...
while( FS.fread( &tag, sizeof(tag), 1, file ) != 0 ) {

	if( tag.id == tag you want ) {

		// Found the tag you're interested in.
		// Read the data to a buffer and do something with it.
		FS.fread( buffer, tag.length, 1, file );
		break;

	} else if( tag.id == TAG_CODE ) {

		// Need to stop reading tags here.
		break;

	} else { 

		// Unknown tag, skip the data to read the next one.
		FS.fseek( file, tag.length, SEEK_CUR );

	}

}

FS.fclose(file);

#2

Maybe you should add a section about why to use pop files instead of bin files for beginners (like myself/


#3

In order to satisfy the requirements for binary distribution under some licences, I suggest you include a LICENCE tag. This could be a String type.


#4

The more beginner-oriented information will come at about the same time as the new gamedisk, I think. Things are still under development and might change.

Yes, that would be good. I’ve intended to add this tag since it was suggested in the Extensible Loader thread, but haven’t done so because the loader still doesn’t have a UI to show string tags yet.