Skip to content

Addon System

Jump to bottom
Kirbeast edited this page Jul 3, 2026 · 1 revision

The addon system allows modders to distribute content as self-contained packages that can be installed, uninstalled, and managed without manually replacing files.

What is an Addon?

An addon is a .7z archive containing:

  • info.xml - A manifest file describing the addon
  • Mod files - The actual game files to be installed

The launcher searches for any .7z file in sd:/(-codespath:)/launcher/addons (or sd:/projectm/launcher/addons in the original PM launcher). Preincluded with Project M 3.5 was WiFi.7z, which served as the WiFi add-on.

Benefits

  • Easy Clean Builds: Disable all addons before applying upgrade patches. Returning to a clean build is extremely simple.
  • Tournament Friendly: Swapping custom content to original is much easier if you use your Wii at tournaments.
  • Easy Sharing: Share custom addons with others. They simply drop the file in the addons folder and use the launcher to install it—no hunting for file locations or manual backups needed.
  • Optional Content: Mod teams may officially (or unofficially) release addon packs for stages, costumes, sound effects, music packs, etc.

The info.xml Structure

<addon>
  <title>My Cool Mod</title>
  <code>MYMOD47</code>
  <version>1.0</version>
  <files>
    <file source="pf/fighter/kirby/FitKirby.pac" 
          destination="sd:/(-codespath:)/pf/fighter/kirby/FitKirby.pac" 
          md5="037b67093d5160f02c29635e6e651591" />
  </files>
</addon>

Fields explained:

  • title: Display name shown in the launcher UI (256 character max)
  • code: Unique identifier (8 character max) used to track which addon owns which files
  • version: Float for version comparison (supports upgrades)
  • files: List of files to patch, each with:
    • source: Path inside the .7z archive
    • destination: Where to install on the SD
    • md5: Expected hash of the file (integrity check)

Creating Addons

You can create addons manually by editing the info.xml file and calculating MD5 hashes for your files. Alternatively, there was an Addon XML Generator tool released for PM 3.6 that automated this process with features like drag-and-drop file uploading, auto-complete paths, and built-in MD5 calculation. Note that this tool is quite old and was designed for the original PM launcher—if you use it with BrawlModLauncher, you may need to adjust the folder paths in the generated XML to match your build's structure.

There may be addon generation built into BrawlInstaller at a later time.

How Installation Works

  1. Backup Original Files: Before replacing any file, the launcher checks if it exists. If the file differs from the expected MD5, it backs up the original to launcher/addons/backups/ using the filename only.

  2. Extract & Validate: Each file is extracted from the .7z archive, its MD5 is verified against the manifest, then written to the destination.

  3. Track Changes: The launcher logs all modified files in launcher/addons/status.xml with the addon's code, so it knows which addon owns which file.

Addon States

The launcher tracks each addon's state:

  • NOT_INSTALLED: None of the addon's files are present
  • INSTALLED: All files are present and match this addon's code
  • INCOMPLETE: Only some files are installed
  • CONFLICTING: Files are present but owned by a different addon (another addon modified them)
  • UPGRADE: A newer version of an already-installed addon is available

Uninstallation

When uninstalling, the launcher:

  1. Checks status.xml for files owned by this addon
  2. Restores the original file from backups/ if available
  3. Deletes the backup after restoration
  4. Removes the file entry from status.xml
  5. If no backup exists, simply deletes the file

Conflict Resolution

If two addons try to modify the same file:

  • The first addon installs normally and backs up the original
  • The second addon detects the file is already modified by a different code
  • The second addon is marked as CONFLICTING and won't install
  • User must uninstall the conflicting addon first

Folder Structure

sd:/projectname/
├── launcher/
│   ├── addons/
│   │   ├── MyMod.7z              # Addon package
│   │   ├── backups/              # Original file backups
│   │   │   └── fit.pac
│   │   └── status.xml            # Tracks installed files

Error Codes

Open Addon Errors

Error Description
-1 Empty or unreadable 7z file
-2 Empty or unreadable info.xml
-3 XML parsing failed
-4 No XML root element
-5 No Title element
-6 Blank Title element
-7 No Code element
-8 Blank Code element
-9 No Version element
-10 Blank Version element
-11 No Files element array
-12 No destination element in File element

Install Addon Errors

Error Description
-1 Empty or unreadable 7z file
-2 Empty or unreadable info.xml
-3 XML parsing failed
-4 No XML root element
-5 No Files element array
-6 No File element in Files array
-7 Cannot create backup file
-8 Cannot extract from 7z file
-9 Cannot write new file
-10 Cannot write log file

Uninstall Addon Errors

Error Description
-1 Empty or unreadable 7z file
-2 Empty or unreadable info.xml
-3 XML parsing failed
-4 No XML root element
-5 No Files element array
-6 (Reserved)
-7 Cannot restore file
-8 Cannot write log file

This system was originally developed for Project M to allow cosmetic and gameplay addons to be distributed and managed easily without requiring users to manually replace files or keep track of what they changed. Unfortunately Addons wear broken from 3.6 onward so they didn't see much use.

Clone this wiki locally