haydee-outfit-generator 1.2.2

Automated pipeline to generate custom outfit textures for Haydee using Gemini API.

🌐 Languages: English | Русский | ไทย | 中文 | Español | العربية

Haydee Outfit Generator (Powered by Gemini)

Automated Python pipeline to generate custom outfit textures for the game Haydee using the Google Gemini API.

[!TIP] Not a fan of the command line? Check out the Haydee AI Outfit Generator GUI! It's a modern, ready-to-use graphical interface that lets you easily generate custom outfits without messing with terminals or environment variables. Download the latest release to get started instantly!

🤖 Two-Image Multi-Criteria LLM-as-a-Judge Validation

This project features an advanced automated Quality Assurance Feedback Loop. While a fast model (like gemini-3.1-flash-image) paints the textures, a stronger reasoning model (like gemini-3.1-pro) acts as a strict QA Inspector using a Two-Image Multi-Criteria approach.

The Inspector compares the generated UV texture side-by-side with the original blank template to evaluate specific structural rules independently:

1. Face Rule: Ensures the character's helmet remains completely faceless (no human features, glasses, or respirators).
2. Torso Seam Rule: Verifies that the front and back torso clothing/armor pieces match perfectly to prevent visible seams in 3D.
3. Legs Rule: Ensures the left and right legs are treated as individual limbs, preventing the AI from drawing two legs inside a single shape.

If any rule is violated, the Inspector rejects the image, provides specific feedback on exactly what broke, and forces the generator to redraw the texture correcting those specific mistakes.

✨ Generation Examples

Lunar Scout Outfit	Neon Surge Outfit	Steam Gear Outfit	Tomb Awakened Outfit
Waaagh Bot Outfit	Wastelander Outfit	Xenomorph Outfit	Berry Sweet Outfit
Tech-Priestess Outfit	Astro White Outfit	Battle Sister Outfit	Gothic Automaton Outfit
Candy Pop Outfit	Hellwalker Outfit	Retrowave Outfit	Iron Utopia Outfit

📋 Prerequisites

• Python 3.12+

🔑 Getting a Gemini API Key

1. Go to Google AI Studio.
2. Sign in with your Google account.
3. Click the "Create API key" button.
4. If prompted, read and accept the terms of service.
5. Click on "Create API key in new project" (or use an existing project).
6. Copy the generated key. You will need it for the .env file in the setup steps below.

💻 Setup (Local)

Install via pip (Recommended)

The easiest way to install the generator is directly from PyPI:

pip install haydee-outfit-generator

Install from Source

1. Clone the repository.

2. Install dependencies:

   pip install .
   

3. Copy .env.example to .env (or create one) and configure your variables:

• GEMINI_API_KEY: Your Google Gemini API Key.
• HAYDEE_PATH: Absolute path to your Haydee installation directory.
• IMAGE_RESOLUTION: (Optional) Output resolution. Default is 4K. Can be set to 2K (2048x2048) if needed.
• MODEL_NAME: (Optional) The Gemini AI model to use for texture generation. Default is gemini-3.1-flash-image-preview.
• VALIDATOR_MODEL: (Optional) The reasoning model to use for QA inspection. Default is gemini-3.1-pro-preview.

🐳 Setup (Docker)

If you prefer to run the project without installing Python locally, you can use Docker.

1. Install Docker Desktop.
2. Create your .env file and set GEMINI_API_KEY and HAYDEE_PATH.
   • Note: HAYDEE_PATH in .env must be the absolute path on your host Windows machine (e.g., C:\Program Files (x86)\Steam\steamapps\common\Haydee).

🚀 Usage

Running Locally

1. Generating a Single Outfit Run the generate command by providing the mod name, the desired style description, and optionally an author:

haydee-gen generate --name "NeonSurge" --style "cyberpunk neon lights with dark carbon fiber armor" --author "TheGamerBay"

(Tip: You can omit the generate keyword for a shorter command: haydee-gen --name ...)

Partial Generation Parameters You can selectively skip parts of the generation process to save time or API calls if you've already generated them in previous runs:

• --skip-d: Skips the generation of the diffuse texture (Suit_D.dds). A previously generated texture must exist, otherwise the command will fail. If this flag is provided, the --style argument is not mandatory.
• --skip-s: Skips the generation of the material mask and specular map (Suit_S.dds).
• --skip-n: Skips the generation of the normal map (Suit_N.dds).
• --max-retries: (Optional) Maximum number of regeneration attempts if the texture fails QA validation. Default is 3.

When skipping map generation (--skip-s or --skip-n) without generating them earlier, the generated outfit will safely fall back and use Haydee's base neutral maps for those slots.

The script will automatically read the base texture, contact the Gemini API to generate the diffuse texture (Suit_D.dds using the automated Two-Image QA validation loop), then request a material mask which is packed into a specular map (Suit_S.dds). Additionally, a custom Tangent Space Normal Map (Suit_N.dds) is generated alongside the diffuse texture to give the new AI-generated materials matching 3D relief and details. The final mod will be generated inside your Haydee/Outfits folder, ready to use!

2. Grouping Outfits into a Multi-Mod If you have generated multiple outfits and want to group them into a single mod with switchable variations (e.g., in a single "Rainbow" outfit with different colored slots):

haydee-gen group --name "Rainbow" --mods red green blue --slot-category "color" --author "TheGamerBay" --delete-sources

• --delete-sources is an optional flag that will remove the original single-mod folders and configs after successfully grouping them.

Running with Docker

You can use Docker Compose to automatically mount your Haydee directory and run the commands:

docker-compose run --rm generator generate --name "NeonSurge" --style "cyberpunk neon lights with dark carbon fiber armor"

📤 Publishing to Steam Workshop

When you are ready to share your generated outfit, you can upload it directly to the Steam Workshop using the game's built-in tools.

1. Prepare a Thumbnail

• Create a preview image for your mod (preview.png or preview.jpg).
• The image should be square (e.g., 512x512 or 256x256).
• Place this image in your mod folder.

2. Launch Edith Editor

The upload tools are located in the game's editor, not the game itself:

• Go to your Haydee root installation folder.
• Run Edith.exe.
• In the top menu bar, select Tool -> Workshop Uploader.

3. Fill in the Uploader Data

In the uploader window, fill out the following fields:

• Mod Content: At the very top of the upload form, there is a text field with a Browse button beneath it. You will use this to build the list of files to upload:
  1. Click Browse and add your mod's main folder (for example, select Outfits/NeonSurge).
  2. Click Browse again and add your .outfit definition file (for example, select Outfits/NeonSurge.outfit). (This ensures you include the full set of files required for the mod to work).
• Title: The name of your outfit (this will be displayed on Steam).
• Description: A short description of the mod (what it is, special features, etc.).
• Visibility: It is recommended to set this to Private first to verify how everything looks on the Steam page, and change it to Public later.
• Preview Image: Select the thumbnail image you prepared in step 1.

Once filled out, click Upload. If everything goes well, the status at the bottom will show "Success".

🧪 Testing

This project uses pytest for automated testing.

1. Install the development dependencies:

   pip install -r requirements-dev.txt
   

2. Run the test suite with coverage:

   pytest
   

   Note: Valid API Keys or a real Haydee installation are not required to run the tests, as external dependencies and the filesystem are safely mocked.

📄 License

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