Setup & Configuration

ZZAR requires several external tools to function. This guide walks through setting up all dependencies.

System Requirements

Windows

Windows 10 or later (64-bit)
4GB RAM minimum (8GB recommended)
2GB free disk space (for tools and cache)

Linux

Any modern distribution (Arch, Ubuntu, Debian, Fedora, etc.)
Python 3.8+
PyQt5
Wine (for Wwise on Linux)

Initial Setup

Launch ZZAR

Run the ZZAR executable or launch from source:

python ZZAR.py

Set Game Directory

On first launch, go to Settings and click Browse next to Game Directory.Navigate to your Zenless Zone Zero installation:Windows (Steam):

C:\Program Files (x86)\Steam\steamapps\common\ZenlessZoneZero\ZenlessZoneZero_Data

Windows (Epic):

C:\Program Files\Epic Games\ZenlessZoneZero\ZenlessZoneZero_Data

ZZAR will validate the path by checking for:

StreamingAssets/Audio/Windows/Full/

Install Required Tools

Depending on your platform, install the necessary audio tools.

Installing Wwise (Required)

Wwise is required to convert WAV files to the game’s WEM format. Without it, you can browse and play audio, but cannot create mods.

Windows Installation

Open Settings

Navigate to the Settings tab in ZZAR.

Click 'Install Wwise'

ZZAR will:

Download a minimal Wwise package (~50-100MB)
Extract it to tools/wwise/
Test WwiseConsole.exe

Wait for Installation

The download may take several minutes depending on your connection.Progress is shown in the console output.

Verify Installation

Once complete, the “Install Wwise” button should show a green checkmark.

tools/
└── wwise/
    └── WWIse/
        └── Authoring/
            └── x64/
                └── Release/
                    └── bin/
                        └── WwiseConsole.exe

Linux Installation

On Linux, Wwise requires Wine to run.

Install Wine

Arch Linux:

sudo pacman -S wine

Ubuntu/Debian:

sudo apt install wine

Fedora:

sudo dnf install wine

Verify Wine Installation

wine --version

Should output something like wine-9.0.

Install Wwise via ZZAR

Go to Settings and click Install Wwise.ZZAR will:

Download the Windows version of Wwise
Extract it
Test it via Wine

Flatpak users: Wine must be installed on your host system, not inside the Flatpak sandbox. ZZAR will call it via flatpak-spawn --host wine.

Manual Wwise Installation

If automatic installation fails, you can manually install Wwise:

Download Wwise

Get the minimal Wwise package from:

https://gitlab.com/ytnshio/ebi/-/raw/main/WWIse.zip

Extract to Tools Directory

Extract the ZIP to:

<ZZAR>/tools/wwise/

Ensure WwiseConsole.exe is at:

<ZZAR>/tools/wwise/WWIse/Authoring/x64/Release/bin/WwiseConsole.exe

Restart ZZAR

ZZAR will auto-detect the installation.

Installing FFmpeg & vgmstream

These tools handle audio conversion (WEM↔WAV and format conversions).

Windows Installation

Open Settings

Navigate to the Settings tab.

Click 'Install Audio Tools'

ZZAR will download and install:

FFmpeg: General audio conversion
vgmstream: WEM decoding

Total download: ~100-150MB

Wait for Installation

Both tools are downloaded and extracted to:

tools/audio/ffmpeg/
tools/audio/vgmstream/

# From setup_windows_audio_tools.py:17
FFMPEG_URL = "https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win64-gpl.zip"
VGMSTREAM_URL = "https://github.com/vgmstream/vgmstream/releases/latest/download/vgmstream-win64.zip"

Linux Installation

On Linux, use your package manager: Arch Linux:

sudo pacman -S ffmpeg vgmstream

Ubuntu/Debian:

sudo apt install ffmpeg vgmstream-cli

Fedora:

sudo dnf install ffmpeg
# vgmstream may need manual build

Manual vgmstream build (if not in repos):

git clone https://github.com/vgmstream/vgmstream
cd vgmstream
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)
sudo make install

After installing via package manager, restart ZZAR. It will auto-detect the tools if they’re in your PATH.

Game Path Detection

ZZAR attempts to auto-detect your game installation on first launch.

Detection Logic

ZZAR searches common install locations: Steam:

C:\Program Files (x86)\Steam\steamapps\common\ZenlessZoneZero

Epic Games:

C:\Program Files\Epic Games\ZenlessZoneZero

Custom: Registry keys and common game directories If detected, ZZAR validates that this structure exists:

<game>/ZenlessZoneZero_Data/StreamingAssets/Audio/Windows/Full/

Manual Configuration

If auto-detection fails:

Open Settings

Go to the Settings tab.

Click Browse

Navigate to your game’s installation folder.Select the folder containing ZenlessZoneZero.exe.

Verify Path

ZZAR will check that audio files exist and show a success message.

ZZAR needs the game data folder, not the launcher folder. The correct path should contain ZenlessZoneZero_Data/.

Configuration Files

ZZAR stores settings and data in platform-specific locations:

Windows

Settings:

%APPDATA%\ZZAR\settings.json

Mod Configuration:

%APPDATA%\ZZAR\mod_config.json

Mod Library:

%LOCALAPPDATA%\ZZAR\mod_library\

Cache:

%LOCALAPPDATA%\ZZAR\cache\

Linux

Settings:

~/.config/ZZAR/settings.json

Mod Configuration:

~/.config/ZZAR/mod_config.json

Mod Library:

~/.local/share/ZZAR/mod_library/

Cache:

~/.local/share/ZZAR/cache/

ZZAR follows XDG Base Directory standards on Linux for better integration with the system.

Advanced Configuration

Custom Mod Library Location

By default, mods are stored in the locations above. To change this:

Open settings.json in a text editor

Add or modify:

{
  "mod_library_path": "D:\\MyMods\\ZZAR"
}

Restart ZZAR

Wwise Custom Path

If you have Wwise installed elsewhere:

{
  "wwise_path": "C:\\Audiokinetic\\Wwise\\Authoring\\x64\\Release\\bin"
}

Cache Management

ZZAR caches:

Extracted WEM files
Converted WAV files
PCK indexes

Clear Cache:

Close ZZAR
Delete the cache directory
Restart ZZAR (cache will rebuild)

Clearing the cache can fix issues with corrupted audio files or stuck loading screens.

Troubleshooting

”Wwise is not installed” after clicking Install

Cause: Download or extraction failed. Solution:

Check your internet connection
Try manual installation (see above)
Ensure you have write permissions to the tools/ directory
On Linux, verify Wine is installed and working

”FFmpeg not found” on Windows

Cause: Installation incomplete or PATH issue. Solution:

Re-run Install Audio Tools from Settings
Check that tools/audio/ffmpeg/ exists
Restart ZZAR

”Game audio directory not found”

Cause: Game path is incorrect or game is not installed. Solution:

Verify the game is installed
Manually set the path in Settings
Ensure the path contains StreamingAssets/Audio/Windows/Full/

Wine errors on Linux

Cause: Wine is not installed or misconfigured. Solution:

# Test Wine
wine --version

# If missing, install:
sudo pacman -S wine  # Arch
sudo apt install wine  # Ubuntu/Debian

For Flatpak, install Wine on the host system:

flatpak-spawn --host wine --version

Permission denied errors

Cause: ZZAR cannot write to its data directories. Solution:

# Linux
chmod -R u+w ~/.local/share/ZZAR
chmod -R u+w ~/.config/ZZAR

# Windows (run as admin)
icacls "%LOCALAPPDATA%\ZZAR" /grant %USERNAME%:F /T

Downloads fail with SSL errors

Cause: Python’s SSL certificates are missing (common in PyInstaller builds). Solution: ZZAR automatically disables SSL verification for GitHub downloads. If issues persist, download tools manually and place them in the tools/ directory.

If you manually install tools, ensure they match the expected directory structure or ZZAR will not detect them.

Get Started

Features

Guides

Technical

Setup & Configuration

System Requirements

Windows

Linux

Initial Setup

Installing Wwise (Required)

Windows Installation

Linux Installation

Manual Wwise Installation

Installing FFmpeg & vgmstream

Windows Installation

Linux Installation

Game Path Detection

Detection Logic

Manual Configuration

Configuration Files

Windows

Linux

Advanced Configuration

Custom Mod Library Location

Wwise Custom Path

Cache Management

Troubleshooting

”Wwise is not installed” after clicking Install

”FFmpeg not found” on Windows

”Game audio directory not found”

Wine errors on Linux

Permission denied errors

Downloads fail with SSL errors

Build docs developers (and LLMs) love

Get Started

Features

Guides

Technical

​System Requirements

​Windows

​Linux

​Initial Setup

​Installing Wwise (Required)

​Windows Installation

​Linux Installation

​Manual Wwise Installation

​Installing FFmpeg & vgmstream

​Windows Installation

​Linux Installation

​Game Path Detection

​Detection Logic

​Manual Configuration

​Configuration Files

​Windows

​Linux

​Advanced Configuration

​Custom Mod Library Location

​Wwise Custom Path

​Cache Management

​Troubleshooting

​”Wwise is not installed” after clicking Install

​”FFmpeg not found” on Windows

​”Game audio directory not found”

​Wine errors on Linux

​Permission denied errors

​Downloads fail with SSL errors

Build docs developers (and LLMs) love

System Requirements

Windows

Linux

Initial Setup

Installing Wwise (Required)

Windows Installation

Linux Installation

Manual Wwise Installation

Installing FFmpeg & vgmstream

Windows Installation

Linux Installation

Game Path Detection

Detection Logic

Manual Configuration

Configuration Files

Windows

Linux

Advanced Configuration

Custom Mod Library Location

Wwise Custom Path

Cache Management

Troubleshooting

”Wwise is not installed” after clicking Install

”FFmpeg not found” on Windows

”Game audio directory not found”

Wine errors on Linux

Permission denied errors

Downloads fail with SSL errors