Getting Started

Learn how to create and use Retropak files.

Creating Your First Retropak

Step 1: Prepare Your Files

Gather everything for your title:

ROM or disc image
Box art and screenshots
Manual (PDF or images)
Soundtrack (optional)
Any emulator configs (optional)

Step 2: Organize the Structure

Create a directory with this structure:

my_game/
├── retropak.json
├── software/
│   └── game.rom
├── art/
│   ├── box_front.jpg
│   ├── box_back.jpg
│   └── screenshot1.png
├── audio/
│   └── soundtrack.mp3
└── docs/
    └── manual.pdf

File Paths Matter

All paths in retropak.json must match your actual file structure exactly. They're case-sensitive on most systems!

Step 3: Create the Manifest

The retropak.json file describes everything. Start with the minimum:

Quick Start

You only need title and platform to get started. Add more metadata as you go!

{
  "schemaVersion": "1-0-0", // (1)!
  "info": {
    "title": "Sonic the Hedgehog", // (2)!
    "platform": "md" // (3)!
  },
  "media": [{ // (4)!
    "filename": "software/game.rom",
    "type": "cartridge"
  }]
}

Always use "1.0" for the current specification version
The title as it appears on the box or title screen
Platform code - md is Sega Genesis/Mega Drive
Array of software files - at least one is required

Only title and platform are required, but additional metadata provides more value:

{
  "schemaVersion": "1-0-0",
  "info": {
    "title": "Sonic the Hedgehog",
    "platform": "md",
    "developer": "Sonic Team",
    "publisher": "Sega",
    "releaseDate": "1991-06-23",
    "description": "Sega's flagship platformer introducing the blue blur.",
    "category": ["game"],
    "genre": ["platformer", "action"],
    "players": {
      "min": 1,
      "max": 1
    }
  },
  "media": [{
    "filename": "software/game.rom",
    "type": "cartridge",
    "region": "ntsc-u",
    "md5": "d41d8cd98f00b204e9800998ecf8427e" // (1)!
  }],
  "assets": {
    "boxFront": {
      "file": "art/box_front.jpg",
      "alt": "Sonic pointing forward with the game logo above" // (2)!
    },
    "manual": "docs/manual.pdf"
  }
}

Including checksums helps verify ROM authenticity and matches against known good dumps
Alt text makes your Retropak accessible to screen readers - describe what's visible!

Step 4: Package It

Zip the directory:

cd my_game
zip -r ../sonic.rpk .

Or on Windows:

Right-click the folder
Send to → Compressed (zipped) folder
Rename from .zip to .rpk

Step 5: Verify (Optional)

Validate your package:

rpk-verify sonic.rpk

Adding Assets

Box Art

Add box art with accessibility in mind:

"assets": {
  "boxFront": {
    "file": "art/box_front.jpg",
    "alt": "Front cover showing Sonic running through Green Hill Zone"
  },
  "boxBack": {
    "file": "art/box_back.jpg",
    "alt": "Back cover with screenshots and game description"
  }
}

Screenshots

Add multiple gameplay screenshots:

"gameplay": [
  {
    "file": "art/gameplay1.png",
    "alt": "Sonic collecting rings in Green Hill Zone"
  },
  {
    "file": "art/gameplay2.png",
    "alt": "Sonic fighting Dr. Robotnik boss"
  }
]

Soundtrack

Add music tracks:

"music": [
  {
    "title": "Green Hill Zone",
    "file": "audio/green_hill.mp3",
    "background": true // (1)!
  },
  {
    "title": "Boss Battle",
    "file": "audio/boss.mp3",
    "background": false // (2)!
  }
]

Calm tracks make great menu background music
Intense tracks like boss battles usually don't loop well in menus

Soundtrack Tips

The background flag helps frontends choose appropriate menu music. Pick tracks that loop smoothly and aren't too intense or quiet.

Multi-Disc Games

Sequential Discs (Final Fantasy VII)

"media": [
  {
    "filename": "software/ff7_disc1.bin",
    "label": "Disc 1",
    "type": "cdrom",
    "index": 1,
    "bootable": true
  },
  {
    "filename": "software/ff7_disc2.bin",
    "label": "Disc 2",
    "type": "cdrom",
    "index": 2,
    "bootable": false
  },
  {
    "filename": "software/ff7_disc3.bin",
    "label": "Disc 3",
    "type": "cdrom",
    "index": 3,
    "bootable": false
  }
]

Independent Discs (Gran Turismo 2)

"media": [
  {
    "id": "arcade",
    "filename": "software/gt2_arcade.bin",
    "label": "Arcade Mode Disc",
    "type": "cdrom",
    "bootable": true
  },
  {
    "id": "simulation",
    "filename": "software/gt2_sim.bin",
    "label": "Simulation Mode Disc",
    "type": "cdrom",
    "bootable": true
  }
]

ROM Verification

Add checksums for verification:

"media": [{
  "filename": "software/game.rom",
  "type": "cartridge",
  "md5": "d41d8cd98f00b204e9800998ecf8427e",
  "sha1": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
  "status": "good",
  "verified": true,
  "source": "No-Intro"
}]

Checksums must be valid hexadecimal strings:

MD5: 32 characters (e.g., d41d8cd98f00b204e9800998ecf8427e)
SHA-1: 40 characters (e.g., da39a3ee5e6b4b0d3255bfef95601890afd80709)
CRC32: 8 characters (e.g., 00000000)

Generate checksums:

md5sum game.rom
sha1sum game.rom
crc32 game.rom

Date and Code Formats

The schema enforces standardized formats for consistency:

Dates

Release dates must use ISO 8601 format (YYYY-MM-DD):

{
  "releaseDate": "1991-06-23"
}

Country Codes

Use ISO 3166-1 alpha-2 codes (2 lowercase letters):

{
  "country": "jp"
}

Common examples: us, jp, gb, de, fr, ca, au

Language Codes

Use ISO 639-1 codes (2 lowercase letters):

{
  "languages": ["en", "ja", "de"]
}

Common examples: en (English), ja (Japanese), de (German), fr (French), es (Spanish), it (Italian), pt (Portuguese), ko (Korean), zh (Chinese)

Signing Your Retropak

Cryptographic signing ensures your package hasn't been tampered with:

# Sign with GPG
rpk-sign mygame.rpk

# Sign with SSH key
rpk-sign -t ssh -k ~/.ssh/id_ed25519 mygame.rpk

This creates a signed checksum of all files. Any modification will be detected during verification.

Learn more about signing →

Best Practices

File Naming

Use underscores instead of spaces
Use lowercase for directories
Be descriptive: box_front.jpg not img1.jpg

Image Quality

Box art: 1000×1400px minimum
Screenshots: Native resolution preferred
Use PNG for logos and pixel art
Use JPEG for photos and scans

Audio

MP3 or OGG Vorbis at 192+ kbps
Embed track metadata in files
Use consistent volume levels

Compression

Use Deflate (standard ZIP)
Don't nest compressed files
Pre-compressed formats (CHD, JPEG, MP3) can use store-only