Skip to main content
ZZAR makes it easy to install audio replacement mods packaged in the .zzar format. This guide walks you through installing, enabling, and managing mods.

​
Installing a Mod Package

1

Open the Mod Manager

Navigate to the Mod Manager tab in ZZAR’s main interface.
2

Click Install Mod

Click the Install Mod button to open the file browser.ZZAR accepts:
  • .zzar files (recommended)
  • .zip files containing valid mod metadata
3

Select Your Mod File(s)

Choose one or more mod packages to install. ZZAR supports batch installation.The last installation directory is remembered for convenience.
4

Wait for Installation

ZZAR will:
  • Validate the mod package structure
  • Check for required fields (name, author, version, replacements)
  • Verify that all referenced .wem files exist in the archive
  • Extract the mod to mod_library/mods/<uuid>/
Each mod is assigned a unique UUID and stored in your mod library at:
  • Windows: %LOCALAPPDATA%\ZZAR\mod_library\mods\
  • Linux: ~/.local/share/ZZAR/mod_library/mods/

​
Version Management

ZZAR automatically handles mod updates:
  • If you install a newer version of an existing mod (same name), the old version is automatically replaced
  • If you try to install an older version, ZZAR skips the installation and warns you
  • If you install the same version, it replaces the existing installation
Version comparison uses semantic versioning (e.g., 1.2.3).

​
Enabling and Disabling Mods

After installation, mods are disabled by default.
1

Toggle the Mod Switch

In the Mod Manager list, click the switch next to any mod to enable or disable it.
2

Apply Your Changes

Click Apply Mods to write enabled mods to the game’s Persistent folder.ZZAR will:
  • Resolve conflicts based on load order
  • Pack modified .pck files
  • Write them to <game>/Persistent/Audio/Windows/Full/
Mods only take effect in-game after clicking Apply Mods. Simply enabling a mod does not modify game files.

​
Managing Load Order

When multiple mods modify the same audio file, load order determines which mod wins.
  • Mods lower in the list override mods higher up
  • You can drag and drop mods to reorder them
  • The winning mod is highlighted in conflict resolution dialogs

​
Viewing Mod Details

Click the More Info button (ⓘ) on any mod to view:
  • Mod name, author, and version
  • Description
  • Installation date
  • Number of audio replacements
  • Thumbnail image (if included)
  • Affected .pck files

​
Removing Mods

1

Select Mods to Remove

Check the boxes next to one or more mods in the Mod Manager list.
2

Click Remove

Click the Remove button and confirm the deletion.
3

Re-apply If Needed

If the removed mod was enabled, click Apply Mods to regenerate game files without it.
Removing a mod is permanent. The mod files are deleted from your library and cannot be recovered.

​
Handling Conflicts

When multiple enabled mods replace the same audio file:
  1. ZZAR shows a Conflict Resolution dialog listing all conflicts
  2. For each conflict, you can see:
    • The sound name or file ID
    • The winning mod (based on load order)
    • The losing mods (shown in red)
  3. You can adjust load order and re-apply to change conflict winners
To minimize conflicts, enable only the mods you actively want to use, and carefully review conflict dialogs before applying.

​
Opening the Mod Library Folder

Click Open Folder in the Mod Manager to browse your mod library in your system’s file manager. This is useful for:
  • Manually backing up mods
  • Inspecting mod contents
  • Sharing mods with others

​
Troubleshooting

​
”Missing metadata.json at root of archive”

The mod package is invalid. A valid .zzar file must contain metadata.json at the root level with required fields: 
{
  "name": "My Mod",
  "author": "Username",
  "version": "1.0.0",
  "replacements": { ... }
}

​
“Referenced WEM file not found in archive”

The metadata.json references a .wem file that doesn’t exist in the package. Contact the mod author.

​
”Mod directory missing, removing from config”

ZZAR detected an orphaned mod entry (config exists but files are missing). This is automatically cleaned up.

​
Game audio doesn’t change after applying mods

Ensure:
  • The game is closed when you apply mods
  • Your game path is correctly set in Settings > Game Directory
  • The Persistent folder exists and is writable
After applying mods, check <game>/Persistent/Audio/Windows/Full/ to verify that .pck files were created with recent timestamps.

Build docs developers (and LLMs) love

Get started for freeTalk to us