Skip to main content
The mod manager lets you install, organize, and apply community-created audio replacement mods packaged as .zzar files. It handles mod installation, load order, conflict detection, and automatic PCK file generation.

​
What it does

The mod manager simplifies the process of using audio mods created by the community:
  • Install mods: Drop in .zzar mod packages and the manager extracts and validates them automatically
  • Organize load order: Drag mods to set priority when multiple mods modify the same audio files
  • Resolve conflicts: Automatically detects when mods conflict and lets you choose which version to use
  • Apply changes: Generates modified PCK files in your Persistent folder with one click
  • Version management: Automatically updates mods when you install newer versions

​
Key capabilities

Automatic conflict detection

When multiple mods replace the same audio file, the manager shows which mods conflict and lets you choose which version to use. Your choices are saved for future updates.

Priority-based loading

Mods at the top of the list take priority. Drag and drop to reorder mods and control which replacements win when conflicts occur.

Version tracking

When you install a new version of an existing mod, the manager automatically replaces the old version while preserving your enable/disable settings.

Metadata display

View mod details including name, author, version, description, thumbnail, and which PCK files are modified.

​
Installing mods

  1. Download a .zzar mod package from GameBanana or another source
  2. Click Install Mod in the mod manager
  3. Select the .zzar file
  4. The manager validates the package and adds it to your library
  5. Enable the mod using the toggle switch
  6. Click Apply Mods to generate modified PCK files
Mods are stored in ~/.config/ZZAR/mod_library/mods/ by default. Each mod gets a unique UUID folder containing its WEM files and metadata.

​
Managing conflicts

When you click Apply Mods with conflicting mods enabled, the manager shows a conflict resolution dialog: File-level view: See each individual file that has conflicts, with all competing mods listed. Choose which mod’s version to use for each file. Mod-level view (normal mode): See which pairs of mods conflict and how many files are affected. Choose one mod to take priority over the other.
The manager remembers your conflict resolution choices. When you apply mods again later, your saved preferences are automatically applied.

​
Mod creation mode

Enable Mod Creation Mode in the mod manager to:
  • See detailed file-level conflict information
  • Test mod combinations during development
  • Export mods you’ve created in the audio browser
This mode is designed for mod authors who need granular control over replacement behavior.

​
Load order

The mod list shows mods in priority order from top to bottom:
  • Top mods win: When conflicts occur, mods higher in the list override mods lower in the list
  • Drag to reorder: Click and drag mods to change their priority
  • Priority number: Each mod shows its priority number in the list
The load order determines which mod’s version is used when multiple mods modify the same audio file.

​
Apply process

When you click Apply Mods, the manager:
  1. Resolves conflicts based on load order and saved preferences
  2. Cleans up old files by removing outdated PCK files from the Persistent folder
  3. Loads original PCKs from your game’s StreamingAssets folder
  4. Injects replacements by modifying PCK files with mod content
  5. Writes to Persistent folder where the game loads them with higher priority
  6. Sets read-only protection on generated PCK files
The game’s original files are never modified. All changes are written to the Persistent folder, which you can safely delete to remove all mods.

​
Removing mods

To remove a mod:
  1. Right-click the mod or click the trash icon
  2. Confirm deletion
  3. The mod files and configuration are removed
  4. Click Apply Mods to regenerate PCK files without the removed mod
Disabling a mod (toggle switch) keeps it installed but excludes it from the apply process. This is useful for temporarily testing different mod combinations.

​
Mod package format

The .zzar format is a ZIP archive containing:
  • metadata.json: Mod information and replacement mappings
  • wem_files/: Directory with all replacement WEM audio files
  • thumbnail.png: Optional mod thumbnail image
The metadata specifies which PCK files are modified and maps file IDs to replacement WEM files. The mod manager validates this structure when installing mods.

​
Best practices

  • Enable one language: Only enable mods for the voice language you’re using to avoid unnecessary conflicts
  • Test incrementally: Enable new mods one at a time to identify issues
  • Read descriptions: Check mod descriptions for compatibility notes and requirements
  • Keep backups: Export mods you’ve created before making major changes
  • Update regularly: Install mod updates to get bug fixes and improvements

​
Troubleshooting

“Invalid mod package” error: The .zzar file is corrupted or incorrectly formatted. Re-download the mod or contact the author. “Missing directory” error: Set your game directory in Settings > Game Directory before applying mods. Mods not working in-game: Make sure you clicked Apply Mods after enabling them. Check that the game is closed when applying mods. Too many conflicts: Disable some mods or adjust load order to reduce conflicts. Mods that modify the same audio files will always conflict.

Build docs developers (and LLMs) love

Get started for freeTalk to us