---
name: comfyui_build_splash_art_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_splash_art_workflow(scene: str, *, mood: str = \"epic, cinematic\", checkpoint: str = \"IMG_juggernaut_xl_v11.safetensors\", width: int = 1024, height: int = 576, hires: bool = True, seed: int = 0, lora: str | None = None, lora_strength: float = 1.0, negative: str | None = None, steps: int = 28, cfg: float = 7.0, sampler_name: str = \"dpmpp_2m\", scheduler: str = \"karras\", upscale_by: float = 1.5, hires_denoise: float = 0.4, upscale_model: str = \"4x_foolhardy_Remacri.pth\", filename_prefix: str = \"splash_art\") -> dict"
description: "Construye el dict (API format) del workflow de UN splash art / pantalla de carga / key art 2D: ilustracion grande y dramatica en formato pantalla apaisado 16:9 (~1024x576), composicion cinematografica (wide shot) con espacio para el titulo del juego. Genera SOLO la ilustracion (el titulo/logo/barra de carga NO). Compone comfyui_build_hires_fix_workflow (si hires) o comfyui_build_txt2img_workflow + comfyui_inject_lora (estilo opcional). Hermano de comfyui_build_card_art/parallax_background_workflow. Pura, sin red ni I/O. class_types verificados contra /object_info (8GB lowvram)."
tags: [comfyui, ml, gamedev-2d, splash, key-art, loading-screen, illustration, workflow]
uses_functions: [comfyui_build_txt2img_workflow_py_ml, comfyui_build_hires_fix_workflow_py_ml, comfyui_inject_lora_py_ml]
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
  - name: scene
    desc: "Descripcion de la escena del splash (ej. 'a lone hero before a dark castle, storm', 'a spaceship fleet approaching a ringed planet', 'an ancient forest temple bathed in golden light'). Se inserta en un prompt scaffold de key art cinematografico. No puede estar vacio."
  - name: mood
    desc: "Atmosfera/tono que tine el splash (ej. 'epic, cinematic', 'dark, ominous', 'bright, hopeful', 'mysterious, ethereal'). Pasa el MISMO mood + checkpoint + lora a varias pantallas para coherencia visual del juego. keyword-only."
  - name: checkpoint
    desc: "Checkpoint del servidor. 'IMG_juggernaut_xl_v11.safetensors' (SDXL, mejor detalle, ideal para key art) por defecto; en 8GB lowvram con hires puede ser pesado: usa 'IMG_dreamshaper_8.safetensors' (SD1.5) y/o hires=False si la GPU se queda corta (OOM). keyword-only."
  - name: width
    desc: "Ancho del lienzo en px. Apaisado de pantalla -> width > height. 1024 por defecto. keyword-only."
  - name: height
    desc: "Alto del lienzo en px. 576 por defecto (16:9 exacto con width=1024). Para SDXL nativo, 1152x640 o 1344x768 lucen mejor (subir ambos manteniendo ~16:9). keyword-only."
  - name: hires
    desc: "Si True encadena la 2a pasada de detalle (UltimateSDUpscale + Remacri, re-difusion por tiles) sobre la base apaisada (key art mas detallado a pantalla completa). False deja la imagen tal cual sale del VAEDecode. keyword-only."
  - name: seed
    desc: "Semilla del KSampler (y de la pasada hires). Misma seed + misma scene -> misma ilustracion. keyword-only."
  - name: lora
    desc: "LoRA de estilo opcional en models/loras (ej. 'SD15_concept_art.safetensors', 'SDXL_cinematic.safetensors'). None = sin LoRA. Encadena la identidad visual del juego. keyword-only."
  - name: lora_strength
    desc: "Fuerza del LoRA sobre model y clip. Se clampa a [0.0, 2.0]. keyword-only."
  - name: negative
    desc: "Prompt negativo. None usa el negativo por defecto pensado para key art (ilustracion limpia, sin texto/titulo/logo/UI/marco/watermark). keyword-only."
  - name: steps
    desc: "Pasos del KSampler (y de la pasada hires). keyword-only."
  - name: cfg
    desc: "CFG del KSampler (y de la pasada hires). keyword-only."
  - name: sampler_name
    desc: "Sampler del KSampler. keyword-only."
  - name: scheduler
    desc: "Scheduler del KSampler. keyword-only."
  - name: upscale_by
    desc: "Factor de ampliacion de la pasada hires sobre la base (1.5 -> 1024x576 pasa a 1536x864). Solo si hires=True. keyword-only."
  - name: hires_denoise
    desc: "Fuerza de re-difusion de la pasada hires (0.4 por defecto: anade detalle sin alterar la composicion). Solo si hires=True. keyword-only."
  - name: upscale_model
    desc: "Modelo de upscale en models/upscale_models/ que usa la pasada hires ('4x_foolhardy_Remacri.pth'). Solo si hires=True. keyword-only."
  - name: filename_prefix
    desc: "Prefijo del PNG en output/. keyword-only."
output: "dict en API format listo para comfyui_submit_workflow: base apaisada (hires-fix si hires, txt2img si no) con prompt scaffold de key art ('{scene}, {mood}, key art, game splash screen, dramatic lighting, cinematic composition, wide shot, epic scale, atmospheric, ...') + LoRA de estilo opcional. UNA pantalla; set coherente -> llamar por scene con mismo mood/checkpoint/lora. El titulo/logo/barra de carga los pone el motor/post, no este workflow."
tested: true
tests: ["golden hires: clases CheckpointLoaderSimple/KSampler/VAEDecode/UltimateSDUpscale/UpscaleModelLoader/SaveImage; scene + 'epic, cinematic' + 'key art' + 'cinematic composition' + 'wide shot' + 'dramatic lighting' en prompt; base apaisada 1024x576 (width>height); UltimateSDUpscale.batch_size=1", "edge hires=False: sin UltimateSDUpscale/UpscaleModelLoader, SaveImage <- VAEDecode", "edge dims: width=1152/height=640 reflejados, sigue apaisado", "edge mood en prompt", "edge lora: LoraLoader con strength, KSampler.model <- LoraLoader", "edge lora_strength clamp a [0,2]", "edge hires upscale_by reflejado en UltimateSDUpscale", "error scene vacio -> ValueError", "determinismo"]
test_file_path: "python/functions/ml/comfyui_build_splash_art_workflow_test.py"
file_path: "python/functions/ml/comfyui_build_splash_art_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_splash_art_workflow import comfyui_build_splash_art_workflow

# Splash / key art apaisado 16:9 de un heroe ante un castillo en tormenta, con detalle hires.
# En 8GB lowvram va holgado con SD1.5 (IMG_dreamshaper_8); SDXL+hires es mas pesado (puede OOM).
wf = comfyui_build_splash_art_workflow(
    "a lone hero before a dark castle, storm",
    mood="epic, cinematic",
    checkpoint="IMG_dreamshaper_8.safetensors",
    hires=True,
    seed=7,
)
# Set coherente: mismo mood/checkpoint para varias pantallas, varia solo scene.
#   for s in ["title screen vista", "world map overview", "final boss arena"]:
#       wf = comfyui_build_splash_art_workflow(s, mood="epic, cinematic",
#                                              checkpoint="IMG_dreamshaper_8.safetensors", seed=7)
#       comfyui_submit_workflow(wf)  # -> comfyui_wait_result -> comfyui_fetch_output_image
# El titulo/logo/barra de carga los compone el motor de juego sobre la ilustracion resultante.
```

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

## Cuando usarla

Cuando necesites la ILUSTRACION grande de una pantalla de portada, pantalla de carga
(loading screen) o key art promocional: una escena dramatica en formato pantalla
apaisado (16:9), composicion cinematografica (wide shot, plano general) con aire para
que el motor superponga el titulo del juego. Pasa el MISMO `mood` + `checkpoint` +
(`lora`) a todas las pantallas del juego para que combinen visualmente; varia solo
`scene`. Usa `hires=True` para detalle a pantalla completa; `hires=False` para iterar
rapido. El titulo, el logo y la barra de progreso los pone el motor de juego o un paso
de post sobre la ilustracion — este builder NO los pinta.

## Gotchas

- **Genera SOLO la ilustracion, no el titulo/UI**: el titulo del juego, el logo, la
  barra de progreso de carga y cualquier texto los compone el motor/post. El prompt
  scaffold empuja a "key art, cinematic composition, wide shot" y el negativo por
  defecto rechaza "text / title / logo / UI / frame / watermark". Si quieres el titulo
  horneado en la imagen, pasa un `negative` propio sin esos terminos y describelo en
  `scene` (no recomendado: el motor compone el texto mejor y nitido).
- **Formato apaisado = `width > height`**: un splash ocupa la pantalla, que es mas
  ancha que alta. 1024x576 (SD1.5, 16:9 exacto) o 1152x640 / 1344x768 (SDXL nativo). Si
  pones width<=height pierdes el encuadre de pantalla.
- **SDXL + hires es pesado en 8GB lowvram**: el default `IMG_juggernaut_xl_v11` con
  `hires=True` re-difunde por tiles y puede dar OOM o ir muy lento. Si la GPU se queda
  corta: baja a `checkpoint="IMG_dreamshaper_8.safetensors"` (SD1.5), pon `hires=False`, o
  reduce `width/height`. Probado e2e en GPU con SD1.5 + hires (ver report 0159).
- **hires requiere UltimateSDUpscale + Remacri**: si el server responde HTTP 400
  "node type not found: UltimateSDUpscale", falta el custom node; usa `hires=False`. El
  `upscale_model` ('4x_foolhardy_Remacri.pth') debe existir en `models/upscale_models/`.
- **Coherencia del juego = mismos parametros**: si cambias `mood`/`checkpoint`/`lora`/
  `seed` entre pantallas, dejan de combinar. Fija esos y varia solo `scene`.
- `hires_denoise` alto (>0.6) en la 2a pasada puede deformar la composicion; 0.3-0.45
  anade detalle sin alterarla.
- Es una funcion **pura**: solo arma el dict. La generacion real (GPU) la hacen
  `comfyui_submit_workflow` + `comfyui_wait_result` + `comfyui_fetch_output_image`.
