---
name: comfyui_build_pixelart_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_pixelart_workflow(positive: str, negative: str = \"blurry, jpeg artifacts, gradient, smooth shading, anti-aliasing\", *, ckpt_name: str = \"juggernaut_xl_v11.safetensors\", pixel_lora: str = \"pixel-art-xl.safetensors\", lora_strength: float = 1.2, use_lcm: bool = True, lcm_lora: str = \"lcm-lora-sdxl.safetensors\", lcm_strength: float = 1.0, steps: int | None = None, cfg: float | None = None, width: int = 1024, height: int = 1024, seed: int = 0, sampler_name: str | None = None, scheduler: str | None = None, filename_prefix: str = \"pixelart\") -> dict"
description: "Construye el dict (API format) del workflow ComfyUI de pixel-art Fase 1: SDXL base + LoRA pixel-art-xl (nerijs), opcionalmente con LCM-LoRA para 8 steps. Compone comfyui_build_txt2img_workflow + comfyui_inject_multi_lora. El pixel-perfect (Fase 2) lo hace comfyui_pixelize_image, no este workflow. Pura, sin red ni I/O. class_types verificados contra /object_info (8GB lowvram)."
tags: [comfyui, ml, gamedev, gamedev-2d, pixelart, workflow, stable-diffusion, sdxl]
uses_functions: [comfyui_build_txt2img_workflow_py_ml, comfyui_inject_multi_lora_py_ml]
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
  - name: positive
    desc: "Prompt positivo. Trucos para empujar el grid: incluir 'pixel', 'isometric view', '32x32 style'. No puede estar vacio."
  - name: negative
    desc: "Prompt negativo. Por defecto evita blur/gradientes/anti-alias que estropean el look pixel."
  - name: ckpt_name
    desc: "Checkpoint SDXL base. Default 'juggernaut_xl_v11.safetensors' (el SDXL instalado; pixel-art-xl es LoRA SDXL). keyword-only."
  - name: pixel_lora
    desc: "Archivo de la LoRA de estilo pixel-art en models/loras. Default 'pixel-art-xl.safetensors'. keyword-only."
  - name: lora_strength
    desc: "Fuerza de pixel-art-xl sobre model y clip (recomendado 1.2). Se clampa a [0.0, 2.0]. keyword-only."
  - name: use_lcm
    desc: "Si True encadena LCM-LoRA SDXL y usa defaults rapidos (8 steps, cfg 1.5, sampler 'lcm', scheduler 'sgm_uniform'); si False usa defaults SDXL normales (25 steps, cfg 7, 'euler'/'normal'). keyword-only."
  - name: lcm_lora
    desc: "Archivo de la LCM-LoRA SDXL en models/loras (solo si use_lcm). Default 'lcm-lora-sdxl.safetensors'. keyword-only."
  - name: lcm_strength
    desc: "Fuerza de la LCM-LoRA sobre model y clip (recomendado 1.0). keyword-only."
  - name: steps
    desc: "Pasos del KSampler. None = usar el default del modo (8 con LCM, 25 sin). keyword-only."
  - name: cfg
    desc: "CFG del KSampler. None = default del modo (1.5 con LCM, 7 sin). keyword-only."
  - name: width
    desc: "Ancho base en px (1024 SDXL; luego downscale x8 -> 128 en Fase 2). keyword-only."
  - name: height
    desc: "Alto base en px (1024 SDXL). keyword-only."
  - name: seed
    desc: "Semilla del KSampler. keyword-only."
  - name: sampler_name
    desc: "Sampler del KSampler. None = default del modo ('lcm' con LCM, 'euler' sin). keyword-only."
  - name: scheduler
    desc: "Scheduler del KSampler. None = default del modo ('sgm_uniform' con LCM, 'normal' sin). keyword-only."
  - name: filename_prefix
    desc: "Prefijo del PNG que SaveImage escribe en output/. keyword-only."
output: "dict en API format listo para comfyui_submit_workflow: CheckpointLoaderSimple + 1 LoraLoader (pixel-art-xl) o 2 (+ lcm-lora-sdxl si use_lcm) + KSampler con params del modo + SaveImage."
tested: true
tests: ["golden use_lcm=True: 2 LoraLoader (pixel-art-xl@1.2, lcm@1.0) + KSampler steps 8/cfg 1.5/sampler lcm/sgm_uniform", "edge use_lcm=False: 1 LoraLoader + KSampler steps 25/cfg 7/euler/normal", "edge overrides steps/cfg + clamp lora_strength a 2.0", "error positive vacio -> ValueError", "determinismo"]
test_file_path: "python/functions/ml/comfyui_build_pixelart_workflow_test.py"
file_path: "python/functions/ml/comfyui_build_pixelart_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_pixelart_workflow import comfyui_build_pixelart_workflow

# Fase 1: generar el crudo pixel-art (SDXL + pixel-art-xl + LCM, 8 steps).
wf = comfyui_build_pixelart_workflow(
    "isometric tiny house, pixel, 32x32 style, vibrant colors",
    use_lcm=True,
    seed=42,
)
# -> pasar a comfyui_submit_workflow + comfyui_wait_result + comfyui_fetch_output_image
# Fase 2 (pixel-perfect): comfyui_pixelize_image(raw_png, out_png, downscale=8, colors=16)
```

O lanzable directo con: `./fn run comfyui_build_pixelart_workflow` (imprime el JSON del workflow de ejemplo).

## Cuando usarla

Cuando quieras generar arte pixel-art para un juego 2D: tiles, sprites, props.
Es la Fase 1 (genera el *look*). SIEMPRE encadénala con la Fase 2
`comfyui_pixelize_image` (downscale nearest + cuantización) para obtener pixeles
duros y paleta limitada — sin la Fase 2 el resultado es "pixelart borroso de IA".
Para tilesets, genera cada tile por separado y ensambla con `comfyui_build_grid`.

## Gotchas

- **Es API format**, no el formato de la UI. Pásalo a `comfyui_submit_workflow`,
  no lo pegues en la UI.
- **No produce pixel-perfect por sí solo**: deja pixeles irregulares y cientos de
  colores. El pixel-perfect es post-proceso (`comfyui_pixelize_image`, CPU/PIL).
- `use_lcm=True` requiere `lcm-lora-sdxl.safetensors` en models/loras y el sampler
  `lcm`; ambos verificados presentes. Da iteración rápida (8 steps) en 8GB.
- `ckpt_name` debe ser un checkpoint SDXL (pixel-art-xl es LoRA SDXL). Default
  `juggernaut_xl_v11` (no existe `sd_xl_base_1.0` instalado). SDXL en 8GB corre con
  `--lowvram`; la Fase 2 es CPU y no toca VRAM.
- Función pura: no valida contra el server. Si una LoRA/checkpoint falta, el HTTP
  400 salta al enviar con `comfyui_submit_workflow`.
