MAGFest has written software to facilitate Challenges. A challenge is when a player launches a game at a save point with low health before a boss, keys disabled, or other significant handicap and must defeat the obstacle. From a software perspective, this means we must show a menu of challenges to the player, and allow them to chose their game. Once they make a selection, the menu is dismissed and an emulator is launched with their game and save state of choice loaded. While the game is running, we must redirect their keypresses and joystick events to the correct controls for the given emulator. We must also facilitate rapidly re-launching the challenge.

The software we have written is available at https://github.com/magfest/challenges.

The software requires configuration to operate. You must create a directory structure such as this:

/
	configs/
		Genesis/
			gens.cfg
		SNES/
			zinput.cfg
	saves/
		Genesis/
			X-Men2M8.gs0
			X-Men2.gs0
		SNES/
			X-MenMutantApocalypse.zst
	images/
		Genesis/
			X-Men2M8.png
			X-Men2.png
		SNES/
			X-MenMutantApocalypse.png
	roms/
		Genesis/
			X-Men2M8.zip
			X-Men2.zip
		SNES/
			X-MenMutantApocalypse.zip
	consoles.conf
	challenges.json

The configs directory holds the configuration files needed by the emulators. These specify settings the emulator need such as where to look for roms and saves, and what the controller map to use is. The configs are not game-specific.

The saves directory holds the save files or snapshots used by the challenges. They must be placed in the correct folder according to the emulator they are used with. The name is not important, so long as it matches what is in challenges.json. Generally they share a name with the corresponding roms. Some emulators are picky about extensions, so please make an effort to match these to the emulators used.

The images directory contains screenshots displayed in the menu system. The screenshots may be of any resolution, and may be jpgs, gifs, or pngs. Only static gifs will display correctly. Generally pngs and high resolutions are best. The names are immaterial so long as they match what is in challenges.json and are placed in the same console directory as their corresponding roms.

The roms directory contains the roms loaded by the emulators. They must be in whatever format is accepted by their corresponding emulator. Many emulators accept zip files directly, however not all. The names must match what is placed in the challenges.json file exactly.

[main]
data_dir=/opt/challenges/
config_source=<data_dir>configs/<name>/
save_destination=<data_dir>saves/<name>/
notify_text=Press space to reload, or enter to exit.
image_folder=<data_dir>images/<name>/
banner_path=<image_folder>/core/M12_Challenges_Banner.jpg

[SNES]
name=SNES
command=zsnes
arguments=
config=.zsnes

[Genesis]
name=Genesis
command=gens
arguments=--fs
config=.gens

The main section of console.conf contains global variables inherited by every other section. Each console must have the following fields, or accept a default set in the main section:

• name - Display name of this console
• command - Command to launch the emulator
• arguments - Arguments to pass the emulator at launch
• config - Directory into which the configuration must be copied
• image_folder - Directory containing this consoles images
• notify_text - Text to overlay for the player while launching
• save_destination - Directory into which saves must be placed
• config_source - Location from which config files will be copied

In addition, the banner_path and data_dir must be set.

[
    {
        "description": "Defeat Sentinel Brain and Escape!NEWLINE*  Use Any X-Men Character!",
        "difficulty": "Normal",
        "disabledKeys": "",
        "imageFile": "X-Men2M8.png",
        "readableName": "X-Men 2: Clone Wars",
        "romFile": "X-Men2M8.zip",
        "saveFile": "X-Men2M8.gs0",
        "system": "Genesis"
    },
    {
        "description": "Wipe Out X-Men Clones as Nightcrawler!NEWLINE*  No Life Power-Ups Available!NEWLINE",
        "difficulty": "Hard",
        "disabledKeys": "",
        "imageFile": "X-Men2.png",
        "readableName": "X-Men 2: Clone Wars",
        "romFile": "X-Men2.zip",
        "saveFile": "X-Men2.gs0",
        "system": "Genesis"
    },
    {
        "description": "Defeat Magneto with Beast!",
        "difficulty": "Hard",
        "disabledKeys": "",
        "imageFile": "X-MenMutantApocalypse.png",
        "readableName": "X-Men: Mutant Apocalypse",
        "romFile": "X-MenMutantApocalypse.zip",
        "saveFile": "X-MenMutantApocalypse.zst",
        "system": "SNES"
    },
]