---
name: comfyui_build_status_effect_icon_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_status_effect_icon_workflow(effect: str, *, ui_style: str = \"game status icon, bold symbol, flat\", checkpoint: str = \"IMG_dreamshaper_8.safetensors\", size: int = 256, transparent: bool = True, seed: int = 0, lora: str | None = None, lora_strength: float = 1.0, rembg_model: str = \"u2net\", negative: str | None = None, steps: int = 28, cfg: float = 7.0, sampler_name: str = \"dpmpp_2m\", scheduler: str = \"karras\", filename_prefix: str = \"status_effect_icon\") -> dict"
description: "Construye el dict (API format) del workflow de UN icono de estado / buff-debuff 2D (veneno, quemadura, congelacion, escudo, regeneracion, aturdimiento, velocidad, sangrado, maldicion): simbolo unico audaz y LEGIBLE A TAMANO REDUCIDO, centrado, fondo limpio uniforme, estilo de UI consistente entre estados, recortable a alpha. Tamano por defecto menor (256) por ser iconos compactos del HUD. DISTINTO de item_icon (objeto de inventario) y ui_hud (chrome grande de interfaz): es un simbolo de estado compacto. Compone comfyui_build_txt2img_workflow + comfyui_inject_lora (estilo opcional) + Image Rembg (fondo transparente si transparent). Hermano de comfyui_build_item_icon/ui_hud_workflow. Pura, sin red ni I/O. class_types verificados contra /object_info."
tags: [comfyui, ml, gamedev-2d, ui, status, buff, debuff, icon, rembg, workflow]
uses_functions: [comfyui_build_txt2img_workflow_py_ml, comfyui_inject_lora_py_ml]
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
  - name: effect
    desc: "Nombre del efecto de estado (ej. 'poison', 'burning', 'frozen', 'shield', 'regeneration', 'stun', 'speed boost', 'bleed', 'curse'). Se inserta en un prompt scaffold de icono de estado. No puede estar vacio."
  - name: ui_style
    desc: "Descriptor de estilo de UI que mantiene consistentes los iconos de un set (ej. 'game status icon, bold symbol, flat', 'sci-fi HUD status, neon glow', 'pixel art status icon', 'minimal flat status icon'). Pasa el MISMO ui_style + checkpoint + lora a todos los iconos de la barra de estados para coherencia visual. keyword-only."
  - name: checkpoint
    desc: "Checkpoint del servidor. 'IMG_dreamshaper_8.safetensors' (SD1.5, holgado en 8GB lowvram) por defecto; 'IMG_juggernaut_xl_v11.safetensors' para SDXL (mas VRAM, subir size). keyword-only."
  - name: size
    desc: "Lado del cuadrado en px (width = height = size). 256 por defecto: son iconos compactos que se muestran a tamano reducido en el HUD. keyword-only."
  - name: transparent
    desc: "Si True inyecta Image Rembg y el PNG sale con alpha (fondo recortado). False = simbolo opaco sobre fondo plano, recortable luego por el caller. keyword-only."
  - name: seed
    desc: "Semilla del KSampler. keyword-only."
  - name: lora
    desc: "LoRA de estilo opcional en models/loras (ej. 'SD15_detail_tweaker.safetensors'). None = sin LoRA. keyword-only."
  - name: lora_strength
    desc: "Fuerza del LoRA sobre model y clip. Se clampa a [0.0, 2.0]. keyword-only."
  - name: rembg_model
    desc: "Modelo Rembg ('u2net' general, 'isnet-anime' para anime). Solo se usa si transparent=True. keyword-only."
  - name: negative
    desc: "Prompt negativo. None usa el negativo por defecto pensado para iconos de estado (un simbolo simple legible, fondo limpio, sin escena/personaje/texto). keyword-only."
  - name: steps
    desc: "Pasos del KSampler. keyword-only."
  - name: cfg
    desc: "CFG del KSampler. keyword-only."
  - name: sampler_name
    desc: "Sampler del KSampler. keyword-only."
  - name: scheduler
    desc: "Scheduler del KSampler. keyword-only."
  - name: filename_prefix
    desc: "Prefijo del PNG en output/. keyword-only."
output: "dict en API format listo para comfyui_submit_workflow: base txt2img cuadrada con prompt scaffold de icono de estado ('{effect} status effect icon, {ui_style}, simple bold symbol, centered, readable at small size, plain background, ...') + LoRA de estilo opcional + Image Rembg (si transparent). UN icono; barra de estados completa -> llamar por effect con mismo ui_style/checkpoint/lora."
tested: true
tests: ["golden transparent: clases CheckpointLoaderSimple/KSampler/VAEDecode/SaveImage/Image Rembg; effect + 'status effect icon' + 'centered' + 'readable at small size' en prompt; SaveImage <- Rembg; transparency True", "edge transparent=False: sin Rembg, SaveImage <- VAEDecode", "edge size: width==height (cuadrado); default 256", "edge ui_style en prompt", "edge effect en prompt", "edge lora: LoraLoader presente con strength", "error effect vacio -> ValueError", "determinismo"]
test_file_path: "python/functions/ml/comfyui_build_status_effect_icon_workflow_test.py"
file_path: "python/functions/ml/comfyui_build_status_effect_icon_workflow.py"
---

## Ejemplo

```python
import sys, os
sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
from ml.comfyui_build_status_effect_icon_workflow import comfyui_build_status_effect_icon_workflow

# Un icono de veneno con fondo transparente (alpha), listo para submit.
wf = comfyui_build_status_effect_icon_workflow(
    "poison",
    ui_style="game status icon, bold symbol, flat, green",
    transparent=True,
    seed=42,
)
# Barra de estados coherente: misma firma de estilo para cada efecto.
#   for fx in ["burning", "frozen", "shield", "regeneration", "stun", "speed boost"]:
#       wf = comfyui_build_status_effect_icon_workflow(fx, ui_style="game status icon, bold symbol, flat",
#                                                      lora="SD15_detail_tweaker.safetensors", seed=42)
#       comfyui_submit_workflow(wf)  # -> comfyui_wait_result -> comfyui_fetch_output_image
# Atlas de estados: montar los PNG resultantes con comfyui_build_grid.
```

O lanzable directo con: `./fn run comfyui_build_status_effect_icon_workflow` (imprime nodos + class_types del ejemplo).

## Cuando usarla

Cuando necesites iconos de buff/debuff para la barra de estados de un juego (RPG,
roguelike, MOBA): veneno, quemadura, congelacion, escudo, regeneracion, aturdimiento,
velocidad, sangrado, bendicion, maldicion. El icono se pinta encima del retrato o la
barra del personaje para indicar un efecto activo, asi que la prioridad es la
LEGIBILIDAD a tamano reducido (16-32 px): un simbolo audaz y simple, no una
ilustracion recargada. Pasa el MISMO `ui_style` + `checkpoint` + (`lora`) a todos los
estados del set para que combinen visualmente; varia solo `effect`. `transparent`
recorta el fondo (alpha) listo para el motor. Para un atlas, genera cada icono y monta
los PNG con `comfyui_build_grid`.

Eligela frente a sus hermanos por el ROL del asset:
- **item_icon** -> objeto de inventario (espada, pocion, anillo): ilustracion de un
  objeto, no un simbolo de estado.
- **ui_hud** -> chrome grande de la interfaz (botones, marcos, barras de vida): piezas
  de layout, no simbolos compactos.
- **status_effect_icon (esta)** -> simbolo de estado compacto que se superpone al HUD,
  optimizado para legibilidad a tamano reducido.

## Gotchas

- **Legibilidad > detalle**: el icono se muestra a 16-32 px sobre el personaje; un
  simbolo recargado se vuelve ilegible. El prompt empuja a "simple bold symbol,
  readable at small size" y el `size` por defecto es menor (256, no 512 como
  item_icon/ui_hud). El negativo por defecto rechaza "intricate details / complex /
  cluttered" justamente por esto. Si el modelo mete una escena, refuerza `ui_style`
  con "single bold icon, minimal".
- **El recorte usa Rembg, NO luma-to-alpha**: un icono de estado es un simbolo solido
  con silueta definida, rembg lo recorta limpio. `comfyui_matting_luma_to_alpha` es
  para translucidos sobre negro (humo/fuego/magia) y aplanaria el simbolo — no la uses
  para estos iconos.
- **Coherencia del set = mismos parametros**: si cambias `ui_style`/`checkpoint`/
  `lora`/`seed` entre estados, la barra deja de combinar. Fija esos y varia solo
  `effect`. Una convencion util: el color habla del tipo de efecto (verde veneno, rojo
  quemadura, azul congelacion) sin sacrificar la consistencia del simbolo.
- **El texto/numero lo pone el motor, no la imagen**: el negativo por defecto empuja a
  "no text / no letters" para que la silueta quede limpia; el contador de turnos o el
  stack del buff se renderiza en el juego sobre el icono. Si quieres texto horneado,
  pasa un `negative` propio sin "text, letters".
- **SDXL pide mas VRAM y resolucion**: con `checkpoint="IMG_juggernaut_xl_v11.safetensors"`
  sube `size` a 512/768; con IMG_dreamshaper_8 (SD1.5) deja 256 (holgado en 8GB lowvram).
- `transparent=False` deja el simbolo opaco sobre fondo plano: util si prefieres
  recortar fuera del workflow o el motor compone sobre un slot solido.
- Es una funcion **pura**: solo arma el dict. La generacion real (GPU) la hacen
  `comfyui_submit_workflow` + `comfyui_wait_result` + `comfyui_fetch_output_image`.
