---
name: comfyui_build_title_lettering_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_title_lettering_workflow(text: str, *, letter_style: str = \"epic fantasy metallic\", checkpoint: str = \"IMG_juggernaut_xl_v11.safetensors\", width: int = 1024, height: 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 = \"title_lettering\") -> dict"
description: "Construye el dict (API format) del workflow de UN texto/logo de titulo de juego 2D: el nombre del juego o una palabra renderizada con un TRATAMIENTO de lettering (metalico, fantasy tallado, neon, piedra, fuego, cristal, madera...), formato apaisado, fondo plano recortable a alpha, para usar como logo/titulo en menus, splash o cabecera. El valor del builder es el ESTILO del lettering; la difusion NO garantiza la ortografia exacta del texto (limitacion documentada). Compone comfyui_build_txt2img_workflow + comfyui_inject_lora (estilo opcional) + Image Rembg (fondo transparente si transparent). Hermano de comfyui_build_ui_hud/splash_art_workflow. Pura, sin red ni I/O. class_types verificados contra /object_info (8GB lowvram)."
tags: [comfyui, ml, gamedev-2d, title, logo, lettering, typography, text, 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: text
    desc: "La palabra o nombre del juego a renderizar como logo (ej. 'DRAGON', 'Mystic Realms', 'VOID'). Se inserta ENTRECOMILLADO en el prompt scaffold para que el modelo lo trate como cadena literal. No puede estar vacio. La difusion no garantiza la ortografia exacta: usa palabras cortas en mayuscula y re-rollea seeds."
  - name: letter_style
    desc: "Tratamiento visual del lettering, el VALOR real del builder (ej. 'epic fantasy metallic', 'fire engraved', 'neon sci-fi glow', 'carved stone', 'cracked ice crystal', 'wooden carved', 'golden royal'). Pasa el MISMO letter_style + checkpoint + lora a varios titulos/subtitulos para coherencia de marca. keyword-only."
  - name: checkpoint
    desc: "Checkpoint del servidor. 'IMG_juggernaut_xl_v11.safetensors' (SDXL, mejor render de texto y detalle) por defecto; en 8GB lowvram con apaisado grande puede ser pesado: usa 'IMG_dreamshaper_8.safetensors' (SD1.5) y/o baja la resolucion. keyword-only."
  - name: width
    desc: "Ancho del lienzo en px. Logo de titulo -> apaisado (width > height). 1024 por defecto. keyword-only."
  - name: height
    desc: "Alto del lienzo en px. 512 por defecto (2:1 con width=1024, encuadre tipico de logotipo en una linea). Para palabras muy cortas un cuadrado tambien vale (bajar width). keyword-only."
  - name: transparent
    desc: "Si True inyecta Image Rembg y el PNG sale con alpha (fondo recortado, listo para superponer en el menu). False = lettering opaco sobre fondo plano, recortable luego por el caller. keyword-only."
  - name: seed
    desc: "Semilla del KSampler. Re-rollear seeds es la via principal para conseguir que el texto salga legible: misma text/letter_style, varias seeds, elegir el mejor. keyword-only."
  - name: lora
    desc: "LoRA de estilo opcional en models/loras (ej. un LoRA de logotipos o de tipografia tematica). 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 lettering (una pieza de texto limpia, fondo plano, sin escena/personaje; NO rechaza texto, porque el texto es el sujeto). 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 logo de texto ('the word \"{text}\" as a game logo, {letter_style} lettering, stylized typography, centered, plain background, high detail') + LoRA de estilo opcional + Image Rembg (si transparent). UN logo; titulo + subtitulos coherentes -> llamar por text con mismo letter_style/checkpoint/lora."
tested: true
tests: ["golden transparent: clases CheckpointLoaderSimple/KSampler/VAEDecode/SaveImage/Image Rembg; '\"DRAGON\"' entrecomillado + 'game logo' + 'fire engraved' + 'lettering' + 'stylized typography' en prompt; SaveImage <- Rembg; transparency True", "edge transparent=False: sin Rembg, SaveImage <- VAEDecode", "edge dims: width/height reflejados; default apaisado 1024x512 (width>height)", "edge letter_style en prompt", "edge text entrecomillado en prompt", "edge negative NO rechaza texto como sujeto (tokens text/letters/words ausentes)", "edge lora: LoraLoader presente con strength", "error text vacio -> ValueError", "determinismo"]
test_file_path: "python/functions/ml/comfyui_build_title_lettering_workflow_test.py"
file_path: "python/functions/ml/comfyui_build_title_lettering_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_title_lettering_workflow import comfyui_build_title_lettering_workflow

# El titulo "DRAGON" tallado en fuego, fondo transparente (alpha), listo para submit.
wf = comfyui_build_title_lettering_workflow(
    "DRAGON",
    letter_style="fire engraved",
    checkpoint="IMG_dreamshaper_8.safetensors",
    transparent=True,
    seed=42,
)
# Generacion real (GPU): submit -> wait -> fetch.
#   from ml.comfyui_submit_workflow import comfyui_submit_workflow
#   from ml.comfyui_wait_result import comfyui_wait_result
#   from ml.comfyui_fetch_output_image import comfyui_fetch_output_image
#   pid = comfyui_submit_workflow(wf)["prompt_id"]
#   out = comfyui_wait_result(pid)               # outputs por nodo
#   img = out[next(iter(out))]["images"][0]      # {filename, subfolder, type}
#   comfyui_fetch_output_image(img["filename"], subfolder=img["subfolder"], dest_dir="/tmp")
#
# Re-roll de seeds (la via para que el texto salga legible): misma text/letter_style,
# varias seeds, elegir el mejor -> comfyui_batch_generate(wf, seeds=[1,2,3,4]).
# Logo + subtitulo coherentes: mismo letter_style/checkpoint en ambos.
```

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

## Cuando usarla

Cuando necesites el logo de texto / titulo de un juego (el nombre, una palabra clave,
un subtitulo) con un tratamiento visual concreto para menus, pantalla de inicio,
splash o cabecera: lettering metalico, tallado en piedra/madera, neon, fuego, cristal,
oro. Genera el ESTILO del texto (lo que la difusion reproduce bien) sobre fondo plano
recortable a alpha. Pasa el MISMO `letter_style` + `checkpoint` + (`lora`) a varios
titulos/subtitulos para que la marca combine; varia solo `text`. Para el texto exacto,
re-rollea seeds (`comfyui_batch_generate`) y/o retoca en post.

Eligela frente a sus hermanos por el ROL del asset:
- **splash_art** -> la ilustracion apaisada de portada/loading (sin texto). El titulo
  se superpone encima; este builder pinta ESE titulo.
- **ui_hud** -> chrome de la interfaz (botones, marcos, barras), sin texto como sujeto.
- **title_lettering (esta)** -> el TEXTO estilizado en si (el nombre del juego como logo).

## Gotchas

- **La difusion NO garantiza la ortografia exacta del texto (limitacion clave)**: los
  modelos SD1.5/SDXL renderizan texto de forma imperfecta. Es habitual que salgan
  letras de mas, letras deformadas o palabras parecidas pero mal escritas — mas cuanto
  mas larga o rara sea `text`. El VALOR de este builder es el ESTILO del lettering, no
  la fidelidad tipografica. Mitigaciones: (1) palabras CORTAS y en MAYUSCULA; (2)
  re-rollear varias seeds (`comfyui_batch_generate`) y quedarte con la mejor; (3) subir
  a SDXL (juggernaut_xl, default) que escribe algo mejor que SD1.5; (4) retocar/recomponer
  las letras en post; o (5) dejar que el motor pinte el texto real con una fuente y usar
  esto solo como textura/tratamiento de fondo del logo.
- **El recorte usa Rembg, NO luma-to-alpha**: un logo de texto es una pieza solida con
  silueta definida (las letras tratadas); rembg recorta limpio el fondo plano dejando
  alpha. `comfyui_matting_luma_to_alpha` es para translucidos sobre negro (humo/fuego/
  magia) y se comeria las partes oscuras de un logo metalico/tallado — no la uses aqui.
  Si el lettering es un texto NEON brillante sobre negro (no solido), considera generarlo
  con `transparent=False` sobre fondo negro y aplicar luma-to-alpha tu mismo.
- **Apaisado por defecto (1024x512, 2:1)**: el titulo es una pieza de texto en una linea,
  mas ancha que alta. Para una sola palabra corta un cuadrado tambien vale (baja `width`);
  para un logo con texto en dos lineas, sube `height`.
- **Coherencia de marca = mismos parametros**: si cambias `letter_style`/`checkpoint`/
  `lora`/`seed` entre el titulo y los subtitulos, dejan de combinar. Fija esos y varia
  solo `text`.
- **SDXL pide mas VRAM**: con `checkpoint="IMG_juggernaut_xl_v11.safetensors"` (default) y
  apaisado grande en 8GB lowvram puede ir justo; si hay OOM baja a `IMG_dreamshaper_8`
  (SD1.5) y/o reduce `width`/`height`.
- `transparent=False` deja el lettering 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`.
