Mod Selector

A modern web application designed specifically for game mod management, providing an intuitive visual interface to organize, select, and manage game modification files.

✨ Features

🎯 Core Functions

• Multi-source Folder Management - Support configuring multiple mod source directories, unified management of mod files from different sources
• Smart Mod Selection - Visual interface for selecting specific mods to use, supports batch operations
• Real-time Preview Function - Preview detailed information, images, and video content of selected mods
• One-click File Building - Automatically copy selected mod files to target directory with conflict detection
• File Organization Tools - Batch organize and rename mod files, automatically optimize directory structure

🌍 Interface Features

• Multi-language Support - Built-in Chinese, English, Japanese, and Korean interfaces
• Responsive Design - Adapts to different screen sizes, supports desktop and mobile devices
• Modern UI - Based on Material Design language, clean and beautiful
• Real-time Status Updates - Operation progress displayed in real-time, error information feedback promptly

🔧 Advanced Features

• Focus Mode - Focus display on specific folder mod functionality
• Spine Preview Integration - Support for Spine animation preview integration
• Duplicate File Detection - Intelligently detect and handle duplicate or conflicting mod files
• Configuration Management - Flexible configuration options, support for personalized customization
• Logging System - Detailed operation logs for easy troubleshooting

🚀 Quick Start

System Requirements

• Python 3.7 or higher
• Windows 10/11, macOS 10.14+, or Linux
• At least 1GB available disk space

Installation

1. Clone Repository

   git clone https://github.com/X-T-E-R/NikkeModSelector
   cd NikkeModSelector

2. Install Dependencies

   pip install -r requirements.txt

3. Run Application

   python app.py

Initial Configuration

1. Set Language - Go to settings page and select your preferred interface language

2. Configure File Paths

   • Click the "Settings" button to enter the settings page
   • Add mod source folders in "Folder Management"
   • Set output directory (mod files will be copied here)

3. Organize File Structure (Optional)

   • If your mod file structure is irregular, use the "File Organization" feature
   • The system will automatically organize files into the recommended directory structure

📁 Recommended File Structure

mod_root/
├── c010_character_name/
│   ├── mod1/
│   │   ├── c010_00_standing_xxxx
│   │   ├── c010_00_cover_xxxx
│   │   ├── c010_00_aim_xxxx
│   │   ├── preview_1.png
│   │   ├── preview_2.gif
│   │   └── preview_3.mp4
│   ├── mod2/
│   │   ├── c010_00_standing_yyyy
│   │   ├── c010_00_cover_yyyy
│   │   └── preview.png
│   └── mod3/
└── character_name（ID not required）/
    ├── mod1/
    │   ├── c015_00_standing_zzzz
    │   ├── c015_00_aim_zzzz
    │   └── preview.mp4
    └── mod2/
        └── c015_00_standing_wwww

Structure Description:

• First level: Character categories (doesn't need to start with character ID)
• Second level: Specific mod subfolders
• Third level: Mod files and preview media files

🎮 User Guide

Basic Operation Flow

1. Select Mods

   • View all configured source folders on the left side of the main page
   • Click to expand folder groups and view mod subfolders within
   • Check the mods you want to use

2. Preview and Confirm

   • The preview area on the right will show detailed information of selected mods
   • View preview images and videos (if available)
   • Confirm there are no conflicting mod files

3. Execute Build

   • Click the "Confirm Build" button
   • The system will automatically copy selected files to the output directory
   • Wait for operation completion notification

Advanced Feature Usage

Focus Mode

• Enable "Focus On" function in the first column buttons
• Only display mods contained in selected folders

Preview Function

• Generate preview files for Spine viewer on the preview page
• Need to configure Spine viewer file path in settings beforehand
• Supports image, GIF, and video preview

File Management

• Right-click on mod items in the second column to open context menu
• Support rename, delete, and other operations
• Batch select and operate on multiple mods

⚙️ Technical Architecture

Technology Stack

• Frontend Framework: NiceGUI - Python native Web UI framework
• Backend Language: Python 3.7+
• Image Processing: Pillow - For image preview and processing
• Version Control: GitPython - For update functionality
• UI Design: Material Design style

Project Structure

nice_gui/
├── app.py                 # Application entry file
├── requirements.txt       # Python dependencies
├── core/                  # Core function modules
│   ├── mod_selector.py    # Mod selector core logic
│   ├── base_settings.py   # Basic settings management
│   └── config_settings.py # Configuration file management
├── pages/                 # Page components
│   ├── main_page.py       # Main page
│   ├── settings_page.py   # Settings page
│   ├── file_organizer_page.py # File organizer page
│   └── help_page.py       # Help page
├── utils/                 # Utility functions
│   ├── localization.py    # Internationalization support
│   ├── file_helpers.py    # File operation helpers
│   └── logger.py          # Logging system
├── locales/              # Language packs
├── docs/                 # Documentation files
└── user_config/          # User configuration directory

Architecture Features

• Modular Design - Clear functional layering for easy maintenance and extension
• Responsive UI - Based on web technology, adaptive to different devices
• Plugin Configuration - Flexible configuration system supporting personalized customization
• Safe File Operations - Built-in file operation security checking mechanisms

🔧 Configuration

Configuration File Locations

• Main config file: user_config/settings.toml
• Language configuration: Auto-detect or manually set
• Log files: Under logs/ directory

🛠️ Development Guide

Development Environment Setup

1. Install Development Dependencies

   pip install -r requirements.txt
   # Install development tools (optional)
   pip install black flake8 pytest

2. Run Development Server

   python app.py

3. Code Formatting

   black .
   flake8 .

Contribution Guidelines

1. Fork this project
2. Create feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Create Pull Request

Adding New Languages

1. Create new language file in locales/ directory (e.g., fr.json)
2. Copy structure of en.json and translate all text
3. Add language support in utils/localization.py
4. Test display effects of new language

📋 FAQ

Installation and Running Issues

Q: "Module not found" error when running?
A: Please confirm all dependencies are correctly installed: pip install -r requirements.txt

Q: Cannot open web interface?
A: Check if port is occupied, can modify port number in settings

Q: Interface display abnormal?
A: Recommend using newer browser versions, Chrome, Firefox, or Edge recommended

Usage Issues

Q: File copy failed?
A: Check output directory permissions, confirm sufficient disk space, path contains no special characters

Q: Preview images not displaying?
A: Confirm image format support (JPG, PNG, GIF, etc.), correct file path

Q: Spine preview not working?
A: Check Spine viewer path configuration, confirm version compatibility

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Acknowledgments

• NiceGUI - Excellent Python Web UI framework
• Material Design - Outstanding design language
• All developers who contributed code and suggestions to this project

📞 Support & Feedback

• Issue Reports: GitHub Issues
• Feature Suggestions: GitHub Discussions
• Documentation Updates: Welcome to submit PRs to improve documentation

---

⭐ If this project helps you, please give us a star!