---
name: comfyui_build_pixelart_workflow
kind: function
lang: py
domain: ml
version: "1.1.0"
purity: pure
signature: "def comfyui_build_pixelart_workflow(positive: str, negative: str = \"blurry, jpeg artifacts, gradient, smooth shading, anti-aliasing\", *, ckpt_name: str = \"IMG_juggernaut_xl_v11.safetensors\", pixel_lora: str = \"SDXL_pixel-art.safetensors\", lora_strength: float = 1.2, use_lcm: bool = True, lcm_lora: str = \"SDXL_lcm-lora.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, transparent: bool = True, rembg_model: str = \"u2net\", filename_prefix: str = \"pixelart\") -> dict"
description: "Construye el dict (API format) del workflow ComfyUI de pixel-art Fase 1: SDXL base + LoRA SDXL_pixel-art (nerijs), opcionalmente con LCM-LoRA para 8 steps. Si transparent (default), inyecta un nodo 'Image Rembg' tras el VAEDecode para recortar el fondo -> sprite con alpha (mismo patron que comfyui_build_item_icon_workflow); transparent=False para tiles/fondos opacos. 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-2d, pixelart, workflow, stable-diffusion, sdxl, rembg, transparent]
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 'IMG_juggernaut_xl_v11.safetensors' (el SDXL instalado; SDXL_pixel-art es LoRA SDXL). keyword-only."
  - name: pixel_lora
    desc: "Archivo de la LoRA de estilo pixel-art en models/loras. Default 'SDXL_pixel-art.safetensors'. keyword-only."
  - name: lora_strength
    desc: "Fuerza de SDXL_pixel-art 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 'SDXL_lcm-lora.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: transparent
    desc: "si True (default) inyecta 'Image Rembg' tras VAEDecode y el PNG sale con alpha (fondo recortado) — para sprites de sujeto (personajes/objetos). False deja fondo opaco — para tiles/texturas/fondos. keyword-only."
  - name: rembg_model
    desc: "modelo Rembg ('u2net' general, 'isnet-anime' anime). Solo se usa si transparent=True. 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 (SDXL_pixel-art) o 2 (+ SDXL_lcm-lora si use_lcm) + KSampler con params del modo + nodo 'Image Rembg' antes del SaveImage si transparent + SaveImage."
tested: true
tests: ["golden use_lcm=True: 2 LoraLoader (SDXL_pixel-art@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", "transparent default inyecta Image Rembg + repunta SaveImage", "transparent=False sin Rembg (SaveImage lee del VAEDecode)", "rembg_model override"]
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 + SDXL_pixel-art + 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 `SDXL_lcm-lora.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 (SDXL_pixel-art es LoRA SDXL). Default
  `IMG_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`.
- **transparent=True (default, v1.1.0)**: inyecta el nodo `Image Rembg (Remove
  Background)`. Requiere el custom node `ComfyUI-Image-Background-Remove` (o equiv.)
  instalado en el server; si falta, el `submit` devuelve error en el dict (no crashea).
  El sprite sale RGBA con fondo recortado — ideal para personajes/objetos. Para
  tiles/texturas/fondos sin contorno usar `transparent=False` (PNG opaco).

## Capability growth log

- v1.1.0 (2026-06-28) — `transparent`/`rembg_model`: inyecta `Image Rembg` tras el
  VAEDecode (mismo patron que `comfyui_build_item_icon_workflow`) para producir
  sprites con fondo transparente. Cierra el bug del pipeline pixelart que no podia
  generar sprites sin fondo (issue sprite-fix).
