Parallel Launcher Avanced Star Layout Creation 🌘

This document decribes how to create and test a custom star layout for your SM64 hack.

This process is intended for romhack developers who have altered how their hack stores save data. If your hack simply uses the vanilla save format, or only uses the 8 star per course patch, then you can instead use the much simpler web UI on romhacking.com to create your star layout.

Advanced star layouts consist of a single json file that tells Parallel Launcher where to look in the save data for star progress and how it should display that information to the user.

Layout Schema

{
	"$schema": "https://parallel-launcher.ca/layout/advanced-01/schema.json",
	"format": {
		"save_type": [Optional] (string),
		"num_slots": (number),
		"slots_start": (number),
		"slot_size": (number),
		"active_bit": (number),
		"checksum_offset": (number OR null)
	},
	"groups": [
		{
			"name": (string),
			"side": (string),
			"courses": [
				{
					"name": [Optional] (string),
					"data": [
						{
							"offset": (number),
							"mask": (number)
						},
						...
					]
				},
				...
			]
		},
		...
	],
	"collectedStarIcon": [Optional] (string OR null),
	"missingStarIcon": [Optional] (string OR null)
}
		

Top Level Properties

Format Properties

Group Properties

Course Properties

Star Data Properties

Save Types

The following save types are supported:

EEPROM

The most common save format, and the kind used for vanilla SM64. Maximum save file size is 2kB (2048 bytes), but if you use more than 512 bytes, your hack may require some configuration to work on Everdrive.

SRAM

A larger save format with a maximum size of 32kB (32768 bytes). May require some configuration to work on Everdrive.

FlashRAM

The largest save format available with a maximum size of 128kB (131072 bytes). May require some configuration to work on Everdrive.

MemPak

A save format that, on console, stores data in the MemPak addon for your N64 controller. This means you cannot use both MemPak saves and rumble for the same hack. Each MemPak can hold 32kB (32768 bytes), for a total of 128kB (131072 bytes) if all four controllers are used.

Multi

This mode operates on RetroArch's raw save file (SRM), allowing you to access all of the above save formats at once. There is very little reason to actually do this. In this mode, your offsets should be given from the start of the SRM save file. The SRM save format is simply all 2kB of EEPROM, followed by all 4 MemPaks in order, followed by SRAM, followed by FlashRAM.

Testing Your Layout

You can test the basic syntax of your layout using any JSON schema validator such as this one. The schema to validate against can be found here.

To test that your layout is reading save data correctly, you can use the star layout tester in Parallel Launcher. In the classic view, right click on the rom you want to test your layout on (or, if you are in the RHDC view, select the hack and click the ≡ button beside the version selector), then select [RHDC] Test Star Layout. You can then paste the contents of your layout file into the textbox, and Parallel Launcher will validate it and show you a preview of what it will look like on your current save file. You can also click on the stars to temporarily toggle them in your save file and use the Test Layout button to test your rom with the altered save file to verify that it behaves as expected. Any changes you make to your save file here will be reverted once you close the layout tester dialog, and no progress will be submitted to RHDC, so you can freely test without worrying about breaking your save file or star progress.