---
name: comfyui_build_ui_hud_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_ui_hud_workflow(element: str, *, ui_style: str = \"fantasy game UI\", checkpoint: str = \"IMG_dreamshaper_8.safetensors\", size: int = 512, 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 = \"ui_hud\") -> dict"
description: "Construye el dict (API format) del workflow de UN elemento de interfaz de juego (UI/HUD) 2D: botones, marcos/paneles, barras de vida/mana/XP, iconos de UI, cursores, vinhetas de menu. Pieza unica centrada, fondo limpio uniforme, estilo consistente entre elementos del set, recortable a alpha. Compone comfyui_build_txt2img_workflow + comfyui_inject_lora (estilo opcional) + Image Rembg (fondo transparente si transparent). Hermano de comfyui_build_item_icon/pixelart/sprite_sheet_workflow. Pura, sin red ni I/O. class_types verificados contra /object_info."
tags: [comfyui, ml, gamedev-2d, ui, hud, button, frame, bar, 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: element
    desc: "Nombre del elemento de interfaz (ej. 'health bar', 'wooden button', 'ornate frame', 'magic icon', 'menu cursor', 'mana orb'). Se inserta en un prompt scaffold de UI. No puede estar vacio."
  - name: ui_style
    desc: "Descriptor de estilo de la interfaz que mantiene consistentes las piezas de un set (ej. 'fantasy game UI', 'sci-fi HUD, neon glow', 'pixel art UI', 'minimal flat UI'). Pasa el MISMO ui_style + checkpoint + lora a todos los elementos del HUD 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). 512 SD1.5 por defecto. keyword-only."
  - name: transparent
    desc: "Si True inyecta Image Rembg y el PNG sale con alpha (fondo recortado). False = elemento 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 UI (una pieza, fondo limpio, sin personajes/escena/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 UI ('{element}, {ui_style}, game UI element, centered, clean, plain background, high detail') + LoRA de estilo opcional + Image Rembg (si transparent). UN elemento; HUD completo -> llamar por element con mismo ui_style/checkpoint/lora."
tested: true
tests: ["golden transparent: clases CheckpointLoaderSimple/KSampler/VAEDecode/SaveImage/Image Rembg; element + 'game UI element' + 'centered' + 'plain background' en prompt; SaveImage <- Rembg; transparency True", "edge transparent=False: sin Rembg, SaveImage <- VAEDecode", "edge size: width==height==768 (cuadrado)", "edge ui_style en prompt", "edge lora: LoraLoader presente con strength", "error element vacio -> ValueError", "determinismo"]
test_file_path: "python/functions/ml/comfyui_build_ui_hud_workflow_test.py"
file_path: "python/functions/ml/comfyui_build_ui_hud_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_ui_hud_workflow import comfyui_build_ui_hud_workflow

# Un marco de barra de vida ornamentado con fondo transparente (alpha), listo para submit.
wf = comfyui_build_ui_hud_workflow(
    "ornate health bar frame",
    ui_style="fantasy game UI, gold filigree",
    transparent=True,
    seed=42,
)
# HUD coherente: misma firma de estilo para cada pieza de la interfaz.
#   for el in ["wooden button", "ornate frame", "mana orb", "menu cursor"]:
#       wf = comfyui_build_ui_hud_workflow(el, ui_style="fantasy game UI",
#                                          lora="SD15_detail_tweaker.safetensors", seed=42)
#       comfyui_submit_workflow(wf)  # -> comfyui_wait_result -> comfyui_fetch_output_image
# Atlas del HUD: montar los PNG resultantes con comfyui_build_grid.
```

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

## Cuando usarla

Cuando necesites elementos de interfaz/HUD para un juego (RPG, plataformas,
roguelike) con look consistente: botones, marcos/paneles, barras de vida/mana/XP,
iconos de UI, cursores, vinhetas de menu. Pasa el MISMO `ui_style` + `checkpoint` +
(`lora`) a todas las piezas para que combinen visualmente; varia solo `element`.
`transparent` recorta el fondo (alpha) listo para el motor. Para un atlas/contact-sheet,
genera cada elemento y monta los PNG con `comfyui_build_grid`.

## Gotchas

- **El recorte usa Rembg, NO luma-to-alpha**: un elemento de UI es una pieza solida
  con silueta definida (boton, marco, barra), rembg lo recorta limpio.
  `comfyui_matting_luma_to_alpha` es para translucidos sobre negro (humo/fuego/magia)
  y aplanaria la pieza — no la uses para UI.
- **Coherencia del HUD = mismos parametros**: si cambias `ui_style`/`checkpoint`/
  `lora`/`seed` entre piezas, el set deja de combinar. Fija esos y varia solo `element`.
- **El texto/label lo pone el motor, no la imagen**: el negativo por defecto empuja
  a "no text / no label" para que la silueta quede limpia; el numero de la barra o el
  texto del boton se renderizan en el juego sobre la pieza. Si quieres texto horneado,
  pasa un `negative` propio sin "text, label".
- **SDXL pide mas VRAM y resolucion**: con `checkpoint="IMG_juggernaut_xl_v11.safetensors"`
  sube `size` a 768/1024; con IMG_dreamshaper_8 (SD1.5) deja 512 (holgado en 8GB lowvram).
- Si el modelo mete personajes o escena, el negativo por defecto ya empuja a "single
  element / plain background / no character"; refuerza `ui_style` con "isolated UI
  element" si insiste.
- `transparent=False` deja la pieza opaca 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`.
