---
name: comfyui_build_topdown_sprite_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_topdown_sprite_workflow(subject: str, *, direction: str = \"south\", style: str = \"top-down game sprite, RPG\", checkpoint: str = \"IMG_dreamshaper_8.safetensors\", size: 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 = \"topdown_sprite\") -> dict"
description: "Construye el dict (API format) del workflow de UN sprite en VISTA CENITAL (top-down) 2D: personaje/objeto visto desde arriba estilo RPG clasico/roguelike (Zelda, juegos cenitales), centrado, fondo limpio uniforme recortable a alpha, listo para un mapa de tiles top-down. Opcion `direction` (south/north/east/west) para el sprite de movimiento: las 4 vistas = misma subject/style/seed variando solo direction. DISTINTO de comfyui_build_sprite_sheet_workflow (ese es vista LATERAL/frontal de plataformas) — el negativo por defecto rechaza side/front/isometric/perspective para forzar la vista cenital. Compone comfyui_build_txt2img_workflow + comfyui_inject_lora (estilo opcional) + Image Rembg (fondo transparente si transparent). Hermano de comfyui_build_enemy_creature/prop_object/item_icon_workflow. Pura, sin red ni I/O. class_types verificados contra /object_info."
tags: [comfyui, ml, gamedev-2d, topdown, top-down, overhead, sprite, rpg, roguelike, 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: subject
    desc: "Descripcion del personaje/objeto (ej. 'a knight character', 'a wizard', 'a treasure chest', 'a slime'). Se inserta en un prompt scaffold cenital. No puede estar vacio."
  - name: direction
    desc: "Direccion de encare para el sprite de movimiento. 'south' (mirando a la camara/abajo, el frame por defecto de un sprite RPG), 'north', 'east', 'west' (tambien diagonales como 'south-east'). Las 4 vistas de caminata del MISMO personaje = misma subject/style/seed variando solo direction. None/'' = encare neutro sin direccion. keyword-only."
  - name: style
    desc: "Descriptor de estilo que mantiene consistentes los sprites del set (ej. 'top-down game sprite, RPG', 'pixel art top-down', 'Zelda-like overhead sprite', 'roguelike tile character'). Pasa el MISMO style + checkpoint + lora a todos los sprites para coherencia visual. 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 size). keyword-only."
  - name: size
    desc: "Lado del cuadrado en px (width = height = size). 512 SD1.5 por defecto. keyword-only."
  - name: transparent
    desc: "Si True inyecta Image Rembg y el PNG sale con alpha (fondo recortado, listo para colocar sobre un mapa de tiles). False = sprite opaco sobre fondo plano, recortable luego por el caller. keyword-only."
  - name: seed
    desc: "Semilla del KSampler. Misma seed + misma subject/style -> misma figura; variar solo `direction` da las vistas coherentes de movimiento. keyword-only."
  - name: lora
    desc: "LoRA de estilo/top-down opcional en models/loras (ej. 'SD15_topdown_rpg.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 vista cenital (figura entera vista desde arriba, fondo limpio, sin vistas laterales/frontales/isometricas que delatarian otra perspectiva). 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 cuadrada con prompt scaffold cenital ('{subject}, top-down view, overhead view, {direction} facing, {style}, centered, plain background, game asset, ...') + LoRA de estilo opcional + Image Rembg (si transparent). UN sprite; las 4 direcciones de un personaje -> misma subject/style/seed variando `direction`; montar el set con comfyui_build_grid."
tested: true
tests: ["golden transparent: clases CheckpointLoaderSimple/KSampler/VAEDecode/SaveImage/Image Rembg; subject + 'top-down view' + 'overhead view' + 'south facing' + 'centered' + 'game asset' en prompt; SaveImage <- Rembg; transparency True", "edge negativo cenital: rechaza side view/front view/isometric/perspective (diferenciacion del builder lateral)", "edge direction reflejada: north/east/west aparecen como '{d} facing'", "edge direction opcional: sin direction no hay 'facing' pero sigue 'top-down view'", "edge transparent=False: sin Rembg, SaveImage <- VAEDecode", "edge size: width==height==768 (cuadrado)", "edge style en prompt", "edge lora: LoraLoader presente con strength", "error subject vacio -> ValueError", "determinismo"]
test_file_path: "python/functions/ml/comfyui_build_topdown_sprite_workflow_test.py"
file_path: "python/functions/ml/comfyui_build_topdown_sprite_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_topdown_sprite_workflow import comfyui_build_topdown_sprite_workflow

# Un sprite cenital (vista desde arriba) con fondo transparente (alpha), listo para submit.
wf = comfyui_build_topdown_sprite_workflow(
    "a knight character",
    direction="south",
    style="top-down game sprite, RPG",
    transparent=True,
    seed=5,
)
# Las 4 direcciones de movimiento del MISMO personaje: misma subject/style/seed, cambia direction.
#   for d in ["south", "north", "east", "west"]:
#       wf = comfyui_build_topdown_sprite_workflow("a knight character", direction=d,
#                                                  style="top-down game sprite, RPG", seed=5)
#       comfyui_submit_workflow(wf)  # -> comfyui_wait_result -> comfyui_fetch_output_image
# Atlas de las 4 direcciones: montar los PNG resultantes con comfyui_build_grid.
```

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

## Cuando usarla

Cuando necesites sprites de un juego en VISTA CENITAL (top-down) — RPG clasico tipo
Zelda, roguelike, twin-stick, juego de mapa de tiles donde la camara mira el suelo en
picado: personajes, NPCs, objetos del mapa vistos desde arriba. Usa `direction` para
generar el set de movimiento (south/north/east/west) del mismo personaje fijando
subject/style/seed y variando solo la direccion. Pasa el MISMO `style` + `checkpoint`
+ (`lora`) a todos los sprites del juego para que combinen. `transparent` recorta el
fondo (alpha) listo para colocar sobre el mapa. Para un atlas/contact-sheet de las
direcciones, genera cada vista y monta los PNG con `comfyui_build_grid`.

**Elige este builder y NO `comfyui_build_sprite_sheet_workflow` cuando** el juego es
cenital (cámara desde arriba). El sprite_sheet es para vista LATERAL/frontal (sprite de
plataformas, de perfil o de frente). Aquí la figura se proyecta sobre el suelo y se ve
desde lo alto.

## Gotchas

- **Vista cenital vs lateral**: este builder fuerza "top-down view, overhead view" en el
  positivo y rechaza "side view / front view / 3/4 view / isometric / perspective" en el
  negativo por defecto. Si el modelo aun saca una vista lateral o frontal, refuerza
  `style` con "strict top-down, camera directly overhead, character flat on the ground" y
  sube `cfg`. La vista cenital es la mas dificil de imponer a SD1.5; con un `lora`
  top-down/RPG sale mucho mas fiable.
- **El recorte usa Rembg, NO luma-to-alpha**: un sprite cenital es un sujeto solido con
  silueta definida, rembg lo recorta limpio. `comfyui_matting_luma_to_alpha` es para
  translucidos sobre negro (humo/fuego/magia). Si el sprite es un fantasma etereo y
  quieres conservar translucidez, pon `transparent=False` y recorta con luma-to-alpha en
  un paso aparte.
- **Coherencia del set = mismos parametros**: si cambias `style`/`checkpoint`/`lora`/`seed`
  entre direcciones, las 4 vistas dejan de combinar. Fija esos y varia solo `direction`.
- **`direction` se inserta como "{direction} facing"**: `direction="east"` ->
  "east facing" en el prompt. Deja `direction=""`/None para un sprite sin direccion fija.
- **SDXL pide mas VRAM y resolucion**: con `checkpoint="IMG_juggernaut_xl_v11.safetensors"`
  sube `size` a 768/1024; con IMG_dreamshaper_8 (SD1.5) deja 512 (holgado en 8GB lowvram). Si
  hay OOM, baja `size` o usa SD1.5.
- `transparent=False` deja el sprite opaco sobre fondo plano: util si prefieres recortar
  fuera del workflow o el motor compone sobre un fondo 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`.
