---
name: comfyui_build_structure_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_structure_workflow(structure: str, *, view: str = \"isometric\", style: str = \"game building\", 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 = \"structure\") -> dict"
description: "Construye el dict (API format) del workflow de UN edificio/estructura de escenario de juego 2D (casa, torre, castillo, tienda, posada, ruina, muralla, puente, templo, faro): UN building COMPLETO y centrado a perspectiva de juego (isometrica/lateral via view), fondo limpio uniforme recortable a alpha, estilo consistente para poblar mapas/escenarios. Diferenciado de comfyui_build_prop_object (edificacion grande completa vs objeto pequeno suelto). Compone comfyui_build_txt2img_workflow + comfyui_inject_lora (estilo/iso opcional) + Image Rembg (fondo transparente si transparent). Hermano de comfyui_build_prop_object/isometric_workflow. Pura, sin red ni I/O. class_types verificados contra /object_info."
tags: [comfyui, ml, gamedev-2d, structure, building, architecture, scenery, environment, 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: structure
    desc: "Descripcion de la edificacion (ej. 'medieval house', 'wizard tower', 'stone castle', 'merchant shop', 'tavern inn', 'ruined temple', 'city wall', 'wooden bridge', 'lighthouse'). Se inserta en un prompt scaffold de building. No puede estar vacio."
  - name: view
    desc: "Perspectiva del juego con la que se muestra el edificio. Se inserta como '{view} view' en el prompt (ej. 'isometric', 'side', 'front', '3/4', 'top-down'). Por defecto 'isometric' (la mas comun para mapas iso). Vacio/None -> sin clausula de vista. keyword-only."
  - name: style
    desc: "Descriptor de estilo que mantiene consistentes las estructuras del set (ej. 'game building', 'low poly stylized building', 'pixel art building', 'fantasy RPG building', 'cartoon village building'). Pasa el MISMO view + style + checkpoint + lora a todos los edificios del mapa para coherencia. 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 soltar sobre el mapa). False = edificio opaco sobre fondo plano, recortable luego por el caller. keyword-only."
  - name: seed
    desc: "Semilla del KSampler. Misma seed + misma structure/view/style -> mismo edificio. keyword-only."
  - name: lora
    desc: "LoRA de estilo/isometrica opcional en models/loras (ej. 'SD15_isometric_game_assets.safetensors', 'SDXL_stylized_buildings.safetensors'). Para escenarios iso coherentes la LoRA iso fija el angulo 2:1. 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 estructuras (un edificio completo y entero, sin objetos pequenos/props, sin personas, fondo limpio, sin texto/recorte). 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 de building ('{structure}, {view} view, {style}, full building, complete structure, single building, centered, plain background, game asset, architecture...') + LoRA de estilo opcional + Image Rembg (si transparent). UN edificio; para poblar un mapa -> llamar por cada structure con mismo view/style/checkpoint/lora; contact-sheet de las edificaciones -> montar los PNG con comfyui_build_grid."
tested: true
tests: ["golden transparent: clases CheckpointLoaderSimple/KSampler/VAEDecode/SaveImage/Image Rembg; structure + 'full building' + 'complete structure' + 'centered' + 'game asset' + 'plain background' + 'isometric view' en prompt; SaveImage <- Rembg; transparency True", "edge transparent=False: sin Rembg, SaveImage <- VAEDecode", "edge size: width==height==768 (cuadrado)", "edge structure al inicio del scaffold", "edge view reflejado como '{view} view'", "edge view vacio: sin clausula 'view' colgando", "edge style del set en prompt", "edge edificio completo (full building/single building) y negativo anti objeto-pequeno/prop/persona (diferenciado de prop_object)", "edge lora: LoraLoader presente con strength", "edge transparent default True", "error structure vacio -> ValueError", "determinismo"]
test_file_path: "python/functions/ml/comfyui_build_structure_workflow_test.py"
file_path: "python/functions/ml/comfyui_build_structure_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_structure_workflow import comfyui_build_structure_workflow

# Un edificio de escenario con fondo transparente (alpha), listo para soltar en el mapa.
wf = comfyui_build_structure_workflow(
    "medieval blacksmith shop",
    view="isometric",
    style="game building",
    transparent=True,
    seed=7,
)
# Poblar un mapa: variar `structure` con el MISMO view/style/checkpoint/(lora) para coherencia.
#   for s in ["medieval house", "wizard tower", "stone castle", "tavern inn", "lighthouse"]:
#       wf = comfyui_build_structure_workflow(s, view="isometric", style="game building", seed=7)
#       comfyui_submit_workflow(wf)  # -> comfyui_wait_result -> comfyui_fetch_output_image
# Contact-sheet de las edificaciones: montar los PNG resultantes con comfyui_build_grid.
```

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

## Cuando usarla

Cuando necesites edificios/estructuras completas para poblar mapas o escenarios de un
juego (RPG, estrategia, isométrico, top-down, plataformas): casas, torres, castillos,
tiendas, posadas, ruinas, murallas, puentes, templos, faros. A diferencia de
`comfyui_build_prop_object_workflow` (un objeto PEQUEÑO suelto: barril, cofre, antorcha
que se deja encima de un tile), aquí el asset es una EDIFICACIÓN grande y completa que
ocupa varios tiles y define el escenario (la casa donde entra el jugador, la torre del
mapa, el castillo del boss). Fija `view` (`isometric` por defecto) para la perspectiva
del mapa y pasa el MISMO `view` + `style` + `checkpoint` + (`lora`) a todos los edificios
del set para que combinen; varía solo `structure`. `transparent` recorta el fondo (alpha)
listo para soltar sobre el mapa. Para un atlas/contact-sheet de las edificaciones, genera
cada una y monta los PNG con `comfyui_build_grid`.

## Gotchas

- **Structure (edificio completo) != prop_object (objeto pequeño suelto)**: si lo que
  quieres es un objeto de escena pequeño (barril, cofre, planta, roca) que se deja sobre
  un tile, usa `comfyui_build_prop_object_workflow`. Este builder genera la EDIFICACIÓN
  grande completa (`full building / single building`) que ocupa varios tiles; el negativo
  por defecto rechaza `small object / single item / prop / furniture` para no degradar a
  un objeto suelto.
- **El recorte usa Rembg, NO luma-to-alpha**: un edificio es una masa sólida con silueta
  definida (muros, tejado, torres), rembg lo recorta limpio. `comfyui_matting_luma_to_alpha`
  es para translúcidos sobre negro (humo/fuego/magia). Si la estructura tiene partes
  etéreas/translúcidas que quieras conservar, pon `transparent=False` y recorta aparte.
- **`view` fija la perspectiva del mapa**: `isometric` (default) para mapas iso 2:1;
  `side`/`front` para plataformas; `top-down` para cenital; `3/4` para vista de ¾. Para
  iso estricto, añade la LoRA iso (`lora="SD15_isometric_game_assets.safetensors"`), que
  fija mejor el ángulo 2:1 que solo el prompt.
- **Coherencia del set = mismos parámetros**: si cambias `view`/`style`/`checkpoint`/`lora`/
  `seed` entre edificios, el escenario deja de combinar. Fija esos y varía solo `structure`.
- **SDXL pide más VRAM y resolución**: 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.
- Si el modelo mete varios edificios, personas o lo encoge a un objeto pequeño, el
  negativo por defecto ya empuja a "single building / no people / no small object";
  refuerza `style` con "single isolated building, full structure" si insiste.
- `transparent=False` deja el edificio opaco sobre fondo plano: útil si prefieres recortar
  fuera del workflow o el motor compone sobre un fondo sólido.
- Es una función **pura**: solo arma el dict. La generación real (GPU) la hacen
  `comfyui_submit_workflow` + `comfyui_wait_result` + `comfyui_fetch_output_image`.
