Skip to main content
ZZAR uses platform-specific configuration directories to store settings, mod data, and caches. The ConfigManager class handles all configuration paths.

​
ConfigManager

​
Constructor

from src.config_manager import ConfigManager, get_config_manager

# Singleton instance (recommended)
config = get_config_manager()

# Or create new instance
config = ConfigManager()

​
Configuration Directories

​
config_dir

Stores user configuration files. Windows: 
%APPDATA%/ZZAR/
Linux: 
~/.config/ZZAR/
Access: 
from src.config_manager import get_config_dir

config_dir = get_config_dir()
print(f"Config: {config_dir}")

​
data_dir

Stores application data, caches, and mod library. Windows: 
%LOCALAPPDATA%/ZZAR/
Linux: 
~/.local/share/ZZAR/
Access: 
from src.config_manager import get_data_dir

data_dir = get_data_dir()
print(f"Data: {data_dir}")

​
Configuration Files

​
settings.json

Stores application settings. Location: {config_dir}/settings.json Access: 
from src.config_manager import get_settings_file
import json

settings_file = get_settings_file()

with open(settings_file, 'r') as f:
    settings = json.load(f)
Typical Structure: 
{
  "game_path": "/path/to/Zenless Zone Zero/",
  "language": "en_US",
  "theme": "dark",
  "auto_backup": true,
  "wwise_path": "/path/to/wwise"
}

​
mod_config.json

Stores installed mods and load order. Location: {config_dir}/mod_config.json Access: 
from src.config_manager import get_mod_config_file

mod_config_file = get_mod_config_file()
Structure: 
{
  "installed_mods": {
    "uuid-1234-5678": {
      "enabled": true,
      "priority": 0,
      "install_date": "2024-01-15T10:30:00",
      "metadata": {
        "name": "Voice Mod",
        "author": "ModAuthor",
        "version": "1.0.0",
        "replacements": {...}
      }
    }
  },
  "load_order": [
    "uuid-1234-5678",
    "uuid-8765-4321"
  ]
}

​
mod_tracker.json

Tracks persistent mod changes. Location: {config_dir}/mod_tracker.json Access: 
from src.config_manager import get_mod_tracker_file

tracker_file = get_mod_tracker_file()
Structure: 
{
  "replacements": {
    "Streamed_SFX_1.pck": {
      "134133939": {
        "wem_path": "/path/to/mod/file.wem",
        "file_type": "wem",
        "lang_id": 0,
        "date_modified": "2024-01-15T10:30:00",
        "source": "mod_manager"
      }
    }
  }
}

​
Data Directories

​
mod_library_dir

Stores installed mod files. Default Location: {data_dir}/mod_library/ Structure: 
mod_library/
  mods/
    uuid-1234-5678/
      metadata.json
      thumbnail.png
      wem_files/
        12345.wem
        67890.wem
Access: 
from src.config_manager import get_mod_library_dir, set_mod_library_dir

# Get current path
mod_lib = get_mod_library_dir()

# Set custom path
set_mod_library_dir("/custom/path/to/mods")

​
cache_dir

Stores temporary files and caches. Location: {data_dir}/cache/ Access: 
from src.config_manager import get_cache_dir

cache_dir = get_cache_dir()

​
sound_database.json

Caches sound metadata. Location: {data_dir}/sound_database.json Access: 
from src.config_manager import get_sound_database_file

db_file = get_sound_database_file()

​
fingerprint_database.json

Stores audio fingerprints for matching. Location: {data_dir}/fingerprint_database.json Access: 
from src.config_manager import get_fingerprint_database_file

fp_file = get_fingerprint_database_file()

​
Helper Functions

All configuration paths are accessible via helper functions: 
from src.config_manager import (
    get_config_manager,      # Get ConfigManager singleton
    get_config_dir,          # Get config directory
    get_data_dir,            # Get data directory
    get_settings_file,       # Get settings.json path
    get_mod_config_file,     # Get mod_config.json path
    get_mod_tracker_file,    # Get mod_tracker.json path
    get_mod_library_dir,     # Get mod library path
    get_default_mod_library_dir,  # Get default mod library
    set_mod_library_dir,     # Set custom mod library
    get_cache_dir,           # Get cache directory
    get_sound_database_file, # Get sound DB path
    get_fingerprint_database_file  # Get fingerprint DB
)

​
Migration

ZZAR automatically migrates old configuration from home directory: Old Locations (pre-v1.0):
  • ~/.zzar_settings.json → {config_dir}/settings.json
  • ~/.zzar_mod_config.json → {config_dir}/mod_config.json
  • ~/.zzar_mod_tracker.json → {config_dir}/mod_tracker.json
  • ~/.zzar_mod_library/ → {data_dir}/mod_library/
Check Migration: 
from src.config_manager import get_config_manager

config = get_config_manager()
migrated = config.migrate_old_config()

if migrated:
    for msg in migrated:
        print(msg)
Check Legacy Paths: 
legacy = config.get_legacy_paths()

if legacy:
    print("Found old config files:")
    for key, path in legacy.items():
        print(f"  {key}: {path}")

​
Environment Variables

​
XDG_CONFIG_HOME

Override config directory on Linux: 
export XDG_CONFIG_HOME="/custom/config"
# Config will be: /custom/config/ZZAR/

​
XDG_DATA_HOME

Override data directory on Linux: 
export XDG_DATA_HOME="/custom/data"
# Data will be: /custom/data/ZZAR/

​
APPDATA (Windows)

Windows config directory: 
set APPDATA=C:\Custom\AppData\Roaming
REM Config: C:\Custom\AppData\Roaming\ZZAR\

​
LOCALAPPDATA (Windows)

Windows data directory: 
set LOCALAPPDATA=C:\Custom\AppData\Local
REM Data: C:\Custom\AppData\Local\ZZAR\

​
Example Usage

​
Load Settings

import json
from pathlib import Path
from src.config_manager import get_settings_file

def load_settings():
    settings_file = get_settings_file()
    
    if not settings_file.exists():
        # Return defaults
        return {
            "game_path": "",
            "language": "en_US",
            "theme": "dark"
        }
    
    with open(settings_file, 'r') as f:
        return json.load(f)

def save_settings(settings):
    settings_file = get_settings_file()
    settings_file.parent.mkdir(parents=True, exist_ok=True)
    
    with open(settings_file, 'w') as f:
        json.dump(settings, f, indent=2)

# Usage
settings = load_settings()
settings['game_path'] = "/path/to/game"
save_settings(settings)

​
Custom Mod Library Location

from pathlib import Path
from src.config_manager import set_mod_library_dir, get_mod_library_dir
from src.mod_package_manager import ModPackageManager

# Set custom location
custom_lib = Path("/mnt/external/zzar_mods")
set_mod_library_dir(custom_lib)

print(f"Mod library: {get_mod_library_dir()}")

# ModPackageManager will use custom location
manager = ModPackageManager()
print(f"Manager using: {manager.mod_library_path}")

​
Check Configuration Paths

from src.config_manager import get_config_manager

config = get_config_manager()

print("Configuration Paths:")
print(f"  Config Dir:  {config.config_dir}")
print(f"  Data Dir:    {config.data_dir}")
print(f"  Settings:    {config.settings_file}")
print(f"  Mod Config:  {config.mod_config_file}")
print(f"  Mod Library: {config.mod_library_dir}")
print(f"  Cache:       {config.cache_dir}")

​
Notes

  • All directories are created automatically on first access
  • Configuration is platform-specific (Windows vs Linux)
  • Mod library can be relocated to external drives
  • Migration from old config happens automatically
  • JSON files use UTF-8 encoding with 2-space indentation
  • ConfigManager uses singleton pattern (get_config_manager())

Build docs developers (and LLMs) love

Get started for freeTalk to us