---
name: comfyui_build_dialogue_box_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_dialogue_box_workflow(box_style: str = \"fantasy RPG dialogue box\", *, shape: str = \"rounded panel\", checkpoint: str = \"IMG_dreamshaper_8.safetensors\", width: int = 768, height: 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 = \"dialogue_box\") -> dict"
description: "Construye el dict (API format) del workflow de UNA caja de dialogo / bocadillo / panel de texto de juego (RPG, visual novel, aventura): el contenedor de UI apaisado con borde decorativo y un interior plano y vacio reservado para que el motor de juego renderice el texto de la conversacion encima. DISTINTO de comfyui_build_ui_hud_workflow (elementos sueltos: botones/barras/iconos): esto es el contenedor de dialogo completo. Compone comfyui_build_txt2img_workflow + comfyui_inject_lora (estilo opcional) + Image Rembg (fondo transparente si transparent). Hermano de comfyui_build_ui_hud/card_art_workflow. Pura, sin red ni I/O. class_types verificados contra /object_info."
tags: [comfyui, ml, gamedev-2d, ui, dialogue, dialogue-box, text-box, panel, 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: box_style
    desc: "Descriptor del estilo del contenedor de dialogo (ej. 'fantasy RPG dialogue box', 'medieval fantasy dialogue box, wood and gold', 'sci-fi terminal text box, neon glow', 'visual novel text panel, soft pastel'). Se inserta en un prompt scaffold de caja de dialogo. No puede estar vacio."
  - name: shape
    desc: "Forma del panel (ej. 'rounded panel', 'rectangular banner', 'scroll parchment', 'stone tablet', 'speech bubble'). Mantiene coherentes las cajas de un juego. 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 width/height). keyword-only."
  - name: width
    desc: "Ancho del panel en px. Apaisado de caja de dialogo -> width > height. 768 por defecto. keyword-only."
  - name: height
    desc: "Alto del panel en px. 256 por defecto (panel bajo y ancho). keyword-only."
  - name: transparent
    desc: "Si True inyecta Image Rembg y el PNG sale con alpha (fondo recortado alrededor del borde). False = panel 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 la caja de dialogo (panel limpio, interior plano y vacio, sin texto ni personajes/escena). 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 apaisada con prompt scaffold de caja de dialogo ('{box_style}, {shape}, game UI dialogue box frame, ornate border, empty flat interior for text, plain background') + LoRA de estilo opcional + Image Rembg (si transparent). UNA caja; set coherente -> llamar con mismo box_style/shape/checkpoint/lora. El texto de la conversacion lo pone el motor sobre el interior plano, no este workflow."
tested: true
tests: ["golden transparent: clases CheckpointLoaderSimple/KSampler/VAEDecode/SaveImage/Image Rembg; box_style + 'game UI dialogue box frame' + 'ornate border' + 'empty flat interior for text' + 'plain background' en prompt; SaveImage <- Rembg; transparency True", "edge transparent=False: sin Rembg, SaveImage <- VAEDecode", "edge dims apaisadas: width==896 > height==224", "edge shape en prompt", "edge lora: LoraLoader presente con strength", "error box_style vacio -> ValueError", "determinismo"]
test_file_path: "python/functions/ml/comfyui_build_dialogue_box_workflow_test.py"
file_path: "python/functions/ml/comfyui_build_dialogue_box_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_dialogue_box_workflow import comfyui_build_dialogue_box_workflow

# Una caja de dialogo medieval de madera y oro, apaisada, con fondo transparente (alpha).
wf = comfyui_build_dialogue_box_workflow(
    "medieval fantasy dialogue box, wood and gold",
    shape="rounded panel",
    transparent=True,
    seed=42,
)
# Set de cajas coherentes: misma firma de estilo, varia solo el matiz.
#   for st in ["fantasy dialogue box", "sci-fi terminal text box, neon glow",
#              "visual novel text panel, soft pastel"]:
#       wf = comfyui_build_dialogue_box_workflow(st, shape="rounded panel",
#                                                lora="SD15_detail_tweaker.safetensors", seed=42)
#       comfyui_submit_workflow(wf)  # -> comfyui_wait_result -> comfyui_fetch_output_image
# El motor de juego renderiza el texto de la conversacion sobre el interior plano.
```

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

## Cuando usarla

Cuando necesites el MARCO de la caja de texto donde aparece el dialogo de una
conversacion (RPG, visual novel, aventura grafica): un panel apaisado con borde
decorativo y un interior plano reservado para el texto del motor. Usa esto, NO
`comfyui_build_ui_hud_workflow`, cuando lo que quieres es el CONTENEDOR de dialogo
completo (con su borde y su area de texto), no un elemento suelto del HUD (boton,
barra, icono). Pasa el MISMO `box_style` + `shape` + `checkpoint` + (`lora`) a todas
las cajas de un juego para que combinen. `transparent` recorta el fondo (alpha) listo
para superponer en pantalla.

## Gotchas

- **El interior debe quedar PLANO/LISO**: el negativo por defecto rechaza
  "busy interior / cluttered / decorated interior / illustration inside" y el scaffold
  empuja a "empty flat interior for text" para que el motor escriba el texto encima sin
  competir con detalle horneado. Si el modelo decora el interior, refuerza `box_style`
  con "simple flat inner area" o pasa un `negative` propio mas estricto.
- **El texto del dialogo lo pone el motor, NO la imagen**: el negativo empuja a
  "no text / no letters / no words" para que la caja salga vacia; la conversacion se
  renderiza en el juego sobre el panel. Si quieres texto horneado (raro), pasa un
  `negative` sin "text, letters, words".
- **Diferencia con ui_hud**: ui_hud = elementos sueltos (botones, barras, iconos,
  cursores); este builder = el panel-contenedor de dialogo apaisado. No los confundas:
  si quieres un boton o una barra de vida, usa `comfyui_build_ui_hud_workflow`.
- **El recorte usa Rembg, NO luma-to-alpha**: una caja de dialogo es una pieza solida
  con silueta definida (panel + borde), rembg la recorta limpio.
  `comfyui_matting_luma_to_alpha` es para translucidos sobre negro (humo/fuego/magia)
  y aplanaria el panel — no la uses aqui.
- **Apaisado por defecto**: `width=768 > height=256` da la proporcion de panel de
  conversacion al pie de la pantalla. Un bocadillo cuadrado -> sube `height`; un banner
  muy ancho -> sube `width`.
- **Coherencia del set = mismos parametros**: si cambias `box_style`/`shape`/
  `checkpoint`/`lora`/`seed` entre cajas, dejan de combinar. Fija esos y varia solo el
  matiz del `box_style`.
- **SDXL pide mas VRAM y resolucion**: con `checkpoint="IMG_juggernaut_xl_v11.safetensors"`
  sube `width`/`height`; con IMG_dreamshaper_8 (SD1.5) deja 768x256 (holgado en 8GB lowvram).
- `transparent=False` deja el panel 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`.
