# Anime Character Maker

A small Windows desktop character selector for fast diffusion-based anime sprite iteration.

## WAI-ANIMA Mini Studio

`wai_anima_studio.py` is the stripped-down prompt studio:

- One preview pane on top
- Positive and negative prompt boxes underneath
- A single `Generate` button
- A left-side Mini LoRA drawer for character prompt presets

Mini LoRAs are lightweight character presets, not trained `.safetensors` LoRA files. Each preset stores a visible character name plus hidden positive and negative prompt "guts". Clicking a tile adds the character name to the positive prompt and injects the hidden prompt pieces during generation. Selecting multiple tiles injects all of them. Deleting the character name from the positive prompt unselects the tile. Right-click a tile to edit the hidden prompt data or preview image.

The Mini LoRA drawer can collapse: click `<` in the drawer header to hide it, then click the slim `>` handle on the left edge to bring it back.

After generating an image, drag the preview image onto a Mini LoRA tile to replace that tile's preview. Recent images can be dragged onto Mini LoRA tiles the same way.

The right-side `Recent` drawer only shows images generated during the current app launch. Each launch creates a fresh dated session folder under `cache/sessions`, and the drawer's `Open` button opens that cache root in File Explorer so older session folders are still reachable without cluttering new sessions.

Drag a Recent image back onto the main preview area to restore the prompt state that created it. The studio reloads the saved visible positive/negative prompts, reselects matching Mini LoRA tiles, restores the seed, and turns on `Hold` so the next generation reuses that seed.

Generation shows a thin progress bar at the bottom edge of the image preview. It listens to ComfyUI websocket sampler progress (`value / max`), so during sampling it tracks the actual step count.

The studio also injects a small hidden prompt tuned to WAI-ANIMA's published defaults: `masterpiece, best quality, score_9, score_8, score_7` on the positive side, and `worst quality, low quality, score_1, score_2, score_3, artist name, blurry, jpeg artifacts, lowres, censor` on the negative side. With multiple selected Mini LoRAs, the global negative prompt blocks wrong counts, extras, duplicates, crowd/group shots, fusion, shared bodies, and same-face bleed.

Multiple selected Mini LoRAs are kept apart in the backend prompt. The debug text creates a first count block like `(two distinct characters:1.35)`, then shows each character's hidden positive prompt as its own block, separated with uppercase `BREAK`. In the actual ComfyUI workflow, multi-character generations use built-in regional conditioning: the first block is the global prompt, then each character prompt gets a small `1girl, solo` / `1boy, solo` / `one character, solo` regional prefix, is encoded into its own left/right/center image region, and is combined with `Conditioning (Combine)`.

If the visible positive prompt asks characters to interact, such as hugging, kissing, high-fiving, punching, holding hands, fighting, dancing, or putting arms around each other, the studio switches to overlapping center-weighted regions. It also injects the shared action into each character's regional prompt so the characters can act toward each other instead of standing in isolated slices.

Imported Mini LoRA prompts are intentionally plain WAI-ANIMA prompt fragments: character name, source anime or original-character label, and visual description only. The importer does not preserve story rules, pose instructions, "do not add" clauses, or conditional prop text from the source Vinny/Henny profiles.

The footer `Debug` button opens a live debug window with the actual expanded backend prompt, hidden character prompt blocks in order, sampler, scheduler, model, GPU, seed, LoRAs, and cache paths. Prompt text boxes support `Ctrl+Z`, `Ctrl+Y`, and `Ctrl+Shift+Z`.

Generation settings are locked in code and config:

- Model: `waiANIMA_v10.safetensors`
- Sampler: `euler_ancestral`
- Scheduler: `simple`
- Steps: `30`
- CFG: `5`
- Size: `1280 x 720`

The footer GPU picker defaults to `Auto: most VRAM`, which detects NVIDIA cards with `nvidia-smi` and picks the card with the largest VRAM on startup. You can manually choose another GPU from the dropdown. The studio sets `CUDA_VISIBLE_DEVICES` for its process and records the resolved GPU in each generation metadata file. If ComfyUI is already running before the studio opens, restart ComfyUI with the same GPU selection for the backend itself to move generation to that card.

Vinny/Henny character profiles can be imported into both source and built-app Mini LoRA folders with:

```powershell
python import_vinny_characters.py
```

The built executable is:

```powershell
dist\WaiAnimaMiniStudio.exe
```

The app uses the existing ComfyUI backend at `http://127.0.0.1:8188`. The checkpoint name is baked into the studio config, but the actual multi-GB WAI-ANIMA checkpoint file still needs to be available to ComfyUI because it is not present in this workspace.

To rebuild the mini studio:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\build_wai_anima_studio.ps1
```

It starts from the neutral full-body schoolgirl sprite prompt, then swaps prompt fragments with left/right selectors for:

- Skin, eye color, hair color, and 100 hairstyles
- 100 full outfits, which override top, bottom, socks, and shoes
- 100 tops, bottoms, socks/legwear, and shoes
- 100+ gloves/handwear, hats/headwear, and accessories, plus "none" entries
- 120 backgrounds: plain white, solid colors, and anime scene backdrops

The top-right gender control switches between separate female and male catalogs. Male mode uses a `1boy` base prompt, male-only clothing/accessory sets, and male-specific negative prompt terms so it does not reuse the female outfit pool.

The app is intentionally backend-light: it talks to your existing ComfyUI/Stability Matrix install instead of bundling multi-GB model files.

## Defaults

The default backend config mirrors your screenshot:

- Backend: `http://127.0.0.1:8188`
- Model: `waiANIMA_v10.safetensors`
- VAE: `qwen_image_vae.safetensors`
- Encoder: `qwen_3_06b_base.safetensors`
- Encoder type: `sd3`
- Sampler: `euler`
- Scheduler: `simple`
- Steps: `25`
- CFG: `5`
- Default canvas: `Full Box`, which follows the current preview panel size

LoRA slots are supported in `config.json`, but disabled by default so character-specific LoRAs do not fight the generic base selector prompt.

The canvas picker includes `Full Box`, classic, wide, roomy, full-width, tall, and showcase presets from `200 x 640` up to `384 x 896`. `Full Box` renders to the live preview panel dimensions so solid backgrounds and wide accessories can reach the full preview area.

## Run

1. Start ComfyUI from Stability Matrix. Your current `8188` instance already reports `--use-sage-attention` and `--highvram`.
2. Double-click `run_character_maker.bat` or run `dist\AnimeCharacterMaker.exe`.
3. The first render starts automatically. After that, use the selector arrows; each arrow updates the prompt fragment and starts a fresh render.

Backend controls now live in `⚙ Settings`, and the composed prompt is a collapsible drawer, so the selector stack can stay clean. The bottom-left button is a manual `Generate`/`Regenerate` fallback. Generated images go into `exports`.

The preview column also has character-library controls:

- `Save Picture` copies the current PNG into a timestamped character folder.
- `Select Default Character Folder` chooses the parent folder for saved characters.
- `Open All Characters Folder` opens that parent folder in File Explorer.

Each saved character folder includes the PNG, `prompt.txt`, and `character.json` with selector indices, selected names, seed, and advanced prompt settings.

Seed behavior:

- `Lock seed` is on by default and reuses the typed seed exactly.
- Uncheck `Lock seed` to roll a fresh seed on every selector change.
- Advanced `Apply` buttons follow the same rule: locked seed reuses the typed seed, unlocked seed rolls a fresh one.
- The preview area shows the last seed and generated filename underneath it.
- `Smooth preview` controls whether the enlarged preview uses filtered scaling or crisp nearest-neighbor scaling.

Rendering shows a gray loading overlay on the preview until the next image arrives.

The `Advanced` drawer under the selectors adds typed prompt fields for age, personality, and extra custom prompt text.

Advanced also includes a compact tile cabinet. Pick a category, then click a placeholder tile to select that exact option. These are text placeholders now, but the slots are ready for future preview thumbnails.

When a full outfit is active, top, bottom, socks, and shoes are visibly locked so those controls do not pretend to affect the render. Use `Unlock Top/Bottom` beside the selector header to set Full Outfit back to `None - use separate clothing`.

The selector rows and Advanced cabinet include simple white category icons for faster scanning.

Click the right-side count, such as `38/100`, to type an exact option number and jump straight to it.

The `1` button beside each count resets that selector to its first/default option. Turn on `Influence` to reveal per-selector strength sliders from `0.01` to `1.00`; those weights are injected directly into the prompt.

`SIMPLE` mode hides the full editor and leaves a centered preview with icon-only controls. Left/right changes the active selector option, the star randomizes that selector, and the small icon control changes the active selector category. Keyboard arrows work the same way: Left/Right for options, Up/Down for categories.

Advanced includes `Pose`, `Style`, and `Cheat Code` selectors with preset options and custom typed support. Cheat codes inject direct positive and negative prompt fragments such as `absurdres`, score stacks, clean hands, face charm, and backdrop locking.

Rapid selector changes interrupt the previous ComfyUI job, clear queued stale work before the next debounced render starts, and poll the backend more quickly for completed images.

Background options are worded as explicit backdrops behind the character, with extra negative prompt terms to avoid scenery being interpreted as clothing or leaving white canvas borders.

On startup, the app can generate an 8-tile base gallery. Pick a tile to adopt its gender, selectors, advanced settings, seed, and generated image, or choose `Use Default Base` to start from the normal default character.

`Recent >` opens a preview drawer backed by `cache/recent`. The app keeps the latest 1000 generations by default, with cache folder and limit controls in `⚙ Settings`.

## Build an EXE

Run this from PowerShell:

```powershell
.\build_windows_exe.ps1
```

The finished app will be at `dist\AnimeCharacterMaker.exe`.

## Mac Port And Download Site

The macOS port is configured as a native PyInstaller `.app` bundle, but it must be built on macOS:

```bash
chmod +x build_macos_app.sh
./build_macos_app.sh
```

The download website lives in `site/`. Build the Windows download zip and Mac build-kit zip with:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\create_release_packages.ps1
```

That script also creates `site/downloads/AnimeCharacterMaker-iOS-Xcode-project.zip`, a SwiftUI/Xcode wrapper project for building and signing an iPhone `.ipa` on macOS.

The local test URL is:

```text
http://127.0.0.1:8766/
```

The iPhone experiment lives at `site/iphone/`. It is a PWA-style interface with the same selector flow and a local canvas preview that runs on the current browser/device. Offline install/caching on iPhone requires serving it over HTTPS; true local diffusion on iPhone still needs a tiny converted WebGPU/Core ML-ready model path and device profiling.

Deploy the static download site to Cloudflare Pages with:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\deploy_cloudflare.ps1
```

Wrangler must be logged in first with `npx.cmd wrangler login`, or it must receive a valid Cloudflare API token through the environment.

## Useful Smoke Tests

Print the default composed prompt and option counts:

```powershell
python character_maker_app.py --print-prompt
```

Queue a 1-step ComfyUI render to verify the API path:

```powershell
python character_maker_app.py --comfy-smoke
```
