This is a Python-based tool designed to update and fix character skin mod hash IBs for the game Zenless Zone Zero (ZZZ) to ensure compatibility with the latest versions of the game.
From now on, I will only update the source code in the gui-version branch, this location will serve solely for providing key information.
📑 Table of Contents
🔎 About The Project
This project is a community-driven continuation of the original ZZZ-Mod-Fixer tool.
Since the original creator is no longer releasing updates, I have taken the initiative to independently maintain the program and keep it updated for newer game versions of Zenless Zone Zero.
- Continuous Hash Updates: The character hash database is regularly updated to support newer game versions. To see which exact game version is currently supported, please check the Releases page (where all version-specific updates are posted).
- Backup File Conflict Fix: In the original version, updated
.ini mod files often conflicted with the backup (original) .ini files when left in the same folder. I have modified the code to automatically move the old/backup .ini files to a separate folder, preventing any conflicts and keeping your mod directory clean.
- CommandList Injection Fix: Fixed the
run = CommandListSkinTexture command injection bug and added detection for newer CommandList commands such as run = CommandList\ZZMI\SetTextures and run = CommandList\RabbitFX\SetTextures.
Note: This tool is exclusively designed to fix and update character hashes skin mods. It is not intended for other types of mods or fixing any complex broken mods.
🚧 Limitations & Important Notices
Please read the following exclusions and notices before using this tool:
- Not a Fix for Every Problem: This tool does not fix mod problems that are too complex for certain characters or specific mods. Those cases still require a manual fixing approach.
- Resolution Support: Full support is only available for the
1024p and 2048p resolutions, from game version 2.2 up to 3.2 (current). Anything below that is less complete and relies only on the hashes from the previous creator (Petrascyll), so some very old mods may not be fixable.
- Do Not Update Character Mods That Are Still Safe: Do not update the hashes of character mods that are still working fine, because this can cause conflicts. Fill the main
Mods folder only with the specific character mods that are actually broken. After you have used the tool, restore the settings to how they were and move all of your mods back into the Mods folder as usual.
✅ Requirements
Before using this tool, make sure you have the following installed:
- XXMI Launcher (by SpectrumQT): This fixer is designed to work specifically with the directory structure created by this launcher.
🛠️ How to Use
Since the Revamps 2.0.0 update, the tool has moved from a CLI to an integrated GUI. The GUI tutorial below is the current one, while the old CLI tutorial is kept further down for reference only and is marked as obsolete.
🖥️ GUI Version (Current)
- Download: Download the latest
zzz-mod-fixer-v3.2.exe from the Releases page.
- Run: Run the
.exe directly from any directory. You do not need to place it inside the Mods folder, because the main Mods directory is selected from within the application itself.
- Select the Mods Directory: Inside the application, choose the main
Mods folder within your XXMI Launcher installation directory.
- Choose Your Backup Option: Decide whether the changes should be applied with or without a folder backup.
- Start the Process: Run the fix and wait for the process to complete.
- Launch: Once the process is finished, open your XXMI Launcher and launch Zenless Zone Zero.
Other Features in the GUI
- Rolling Back: Reverts mods that ended up broken after being fixed (available since version 2.1.0, with a guide inside the application).
- Check Update: Checks whether a newer version of the ZZZ Mod Fixer tool is available (available since version 2.1.0).
- Jane Remapper & Dialyn Remapper: Two additional tools alongside the ZZZ Mod Fixer.
- Basic Guide: A basic usage guide is built into the application.
Each release on the Releases page also describes how to run that specific version, so check it if something looks different from this guide.
CLI Version (Obsolete)
The CLI tutorial below is obsolete and no longer relevant, since everything moved to the GUI in version 2.0.0. It is kept here for reference only.
Download: Download the latest zzz-mod-fixer-v3.2.exe from the Releases page.Placement: Place the .exe file directly inside the Mods folder within your XXMI Launcher installation directory.
⚠️ Important: Do not create a new folder for the .exe inside the Mods folder, as the program may not work properly.
Run: Run the program and wait for the process to complete.Launch: Once the process is finished, open your XXMI Launcher and launch Zenless Zone Zero.
⚠️ Notice for Users of the Original ZZZ-Mod-Fixer
If you have previously processed your mods using Petrascyll’s original tool, you may experience conflicts due to left-over backup files that cause the mods to fail to load.
To resolve this, please choose one of the two options below:
Option 1: Quick Cleanup (Manual)
Use this option if you want to keep your current mod setup:
- Open your mod folder(s).
- Manually find and delete all old backup
.ini files that start with DISABLED_BACKUP_ (e.g., DISABLED_BACKUP_1.ini).
- Run the game via XXMI Launcher.
Option 2: Clean Setup (Highly Recommended)
This is the most recommended method to prevent any hidden conflicts and ensure the best results:
- Delete all mod folders inside your main
Mods directory.
- Replace them with fresh, untouched mod files (use backups that have never been modified or processed by Petrascyll’s original program).
- Run my
zzz-mod-fixer-v3.2.exe, select the main Mods folder inside the application, and let it automatically update them (see How to Use).
Place and run my zzz-mod-fixer-v3.2.exe inside the Mods folder to automatically update them. (CLI method, obsolete)
- Launch the game via XXMI Launcher.
🛡️ Windows Security Issues
Attention to users who have problems with Windows Security
If you’re having trouble running the zzz-mod-fixer.exe file due to Windows Security, you can run it using the run-fixer.bat file in the Source Codes folder.
So, the first thing you need to do is download the Source Codes folder in .zip format (where you want to place it). Once downloaded, extract the folder. Then, you need to copy three things. But before copying these three things, create a special folder to store the three things you’ll copy later (you can name it whatever you like).
After creating the special folder, copy these three things:
Assets/PlayerCharacterPYData folderzzz-mod-fixer.py filerun-fixer.bat file
After you’ve copied these three things, place them in your custom folder. Then you put the folder you created in the main Mods folder, not the ZZZ mods folder directly. Then, you can run the run-fixer.bat file.
Specifically for the version 2.1.0, you must use run-fixer-gui.bat instead of the CLI-based run-fixer.bat. After that, add three new files to your setup: zzz-mod-fixer-rollback.py, Jane.remapper.py and Dialyn.remapper.py. You can find the source code in the gui-version branch.
Windows Security Pop-Up Issue
If a Microsoft Defender SmartScreen pop-up appears when you try to run zzz-mod-fixer.exe, do not worry; it is not harmful. The application simply lacks a digital signature (Code Signing Certificate) because I do not have the budget to purchase one.
If the pop-up appears, simply click More Info, then click Run anyway, and the application will open.
❓ Troubleshooting & FAQs
My mod is still broken after running the fixer. What should I do?
If you have successfully run the program but your mod is still not working, please check the following:
- Check the Premium Skin Requirement: Some skin mods are specifically designed to replace premium, paid, or event-exclusive character skins rather than the character’s default skin. You must actually own that specific premium skin in-game for the mod to work. If you do not own the required premium skin, the mod will remain broken even after updating the hashes.
- Read the Mod Creator’s Instructions: Always carefully read the instructions, description, and requirements provided by the original mod author on GameBanana. Some mods require extra steps, specific settings, or unique files to function correctly. In many cases, a broken mod is caused by user error or missing a step in the author’s guide, rather than an outdated hash.
My mod textures are glitched or some parts are missing. Is it a folder issue?
Yes, poor folder organization and nested folders are the most common causes of broken mods. Please follow these rules after downloading a mod:
- Do Not Blindly Drag and Drop: When you download a
.zip or .rar mod from GameBanana and extract it, do not just blindly drop the extracted folder straight into your Mods directory.
- Rename the Folder: First, rename the extracted folder to a clear and recognizable name so you can easily identify and manage it in the future.
- Inspect the Folder Structure: Open the extracted folder and look inside before placing it.
- Is it just a flat list of files, or are there sub-folders?
- If there are sub-folders, check what they are. Sometimes, modders bundle multiple different skin options, recolors, or weapon variants for the same character in one single download. Each of these options has its own unique 3D model structures, coordinates, and hashes.
- If you blindly throw nested folders or conflicting variants into the directory without separating them, no fixer tool in the world will ever be able to repair them due to user negligence.
- Read the Local README Files: If you find a
README.txt, README.md, or any text instruction file inside the extracted mod folder, please take a moment to read it carefully. Modders often include crucial local instructions or troubleshooting tips that were not posted on their GameBanana page. Please do not skip reading these files.
🆕 Revamps 2.0.0
This time, I’ve made some changes to the ZZZ Mod Fixer tool.
What’s new
- Integrated GUI: This time, I’ve updated the ZZZ Mod Fixer by integrating an application-based UI, whereas previously it relied solely on a CLI.
- Backup Options: In this update, I have also added a folder backup option for users. This allows them to choose whether to perform changes with or without a backup—a choice that was not available in the previous CLI version.
- Adding other tools besides the ZZZ Mod Fixer tool: In this update, In this update, I have also added two tools alongside the ZZZ Mod Fixer. These additional tools originate directly from Satan1c repository and have been ported to Python by me. Here are the tools:
- Jane Remapper
- Dialyn Remapper
- Basic Guide: I have also added a basic guide feature here.
❤️ Project Origins & Credits
This project is built upon the amazing work of the original creators in the modding community.
📦 Character Hash Source
I used a data source containing character hashes from other GitHub users, the result is not entirely my own work.
⚠️ Disclaimer
This project is not my own original creation from scratch; I am simply maintaining and updating it of my own volition to keep the tool working for the community.
As this is my first time maintaining a project like this and I am working on it solo, there may still be bugs or edge cases where some mods cannot be fully repaired. I apologize for any inconvenience, and I highly appreciate your understanding and support!
评论