---
name: comfyui_build_trap_hazard_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_trap_hazard_workflow(hazard: str, *, view: str = \"side\", style: str = \"game hazard trap\", 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 = \"trap_hazard\") -> dict"
description: "Construye el dict (API format) del workflow de UNA trampa/peligro de escenario de juego 2D (pinchos del suelo, sierra giratoria, foso de lava, placa de presion, columna de llamas, trampa de flechas, charco acido, descarga electrica, prensa, estaca cayendo): UN objeto de peligro JUGABLE aislado y centrado a perspectiva de juego (lateral/cenital via view), fondo limpio uniforme recortable a alpha, estilo consistente para poblar niveles. Diferenciado de comfyui_build_prop_object (peligro jugable con hitbox de daño vs objeto inerte de decoracion) y de comfyui_build_enemy_creature (trampa vs enemigo vivo). Compone comfyui_build_txt2img_workflow + comfyui_inject_lora (estilo opcional) + Image Rembg (fondo transparente si transparent). Hermano de comfyui_build_prop_object/structure/foliage_set_workflow. Pura, sin red ni I/O. class_types verificados contra /object_info."
tags: [comfyui, ml, gamedev-2d, trap, hazard, danger, scenery, environment, level, 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: hazard
    desc: "Descripcion del peligro (ej. 'spiked floor trap', 'spinning saw blade', 'lava pit', 'pressure plate', 'flame jet', 'arrow trap', 'acid pool', 'electric trap', 'falling spike', 'swinging blade', 'bear trap'). Se inserta en un prompt scaffold de trampa. No puede estar vacio."
  - name: view
    desc: "Perspectiva del juego con la que se muestra el peligro. Se inserta como '{view} view' en el prompt (ej. 'side', 'top-down', 'isometric', 'front', '3/4'). Por defecto 'side' (la mas comun para trampas de plataformas). Vacio/None -> sin clausula de vista. keyword-only."
  - name: style
    desc: "Descriptor de estilo que mantiene consistentes los peligros del set (ej. 'game hazard trap', 'pixel art hazard', 'low poly stylized trap', 'cartoon danger', 'dark fantasy trap'). Pasa el MISMO view + style + checkpoint + lora a todas las trampas del nivel 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 nivel). False = peligro opaco sobre fondo plano, recortable luego (recomendado para hazards etereos: llamas/electricidad/gas + luma-to-alpha). keyword-only."
  - name: seed
    desc: "Semilla del KSampler. Misma seed + mismo hazard/view/style -> misma trampa. keyword-only."
  - name: lora
    desc: "LoRA de estilo opcional en models/loras (ej. 'SD15_pixel_art.safetensors', 'SDXL_stylized_game_assets.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 trampas (un peligro aislado y entero, sin personajes/criaturas vivas, sin multiples objetos, 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 trampa ('{hazard}, {view} view, {style}, single hazard object, trap, dangerous, centered, plain background, game asset, high detail') + LoRA de estilo opcional + Image Rembg (si transparent). UNA trampa; para poblar un nivel -> llamar por cada hazard con mismo view/style/checkpoint/lora; contact-sheet de los peligros -> montar los PNG con comfyui_build_grid."
tested: true
tests: ["golden transparent: clases CheckpointLoaderSimple/KSampler/VAEDecode/SaveImage/Image Rembg; hazard + 'single hazard object' + 'trap' + 'centered' + 'game asset' + 'plain background' + 'side view' en prompt; SaveImage <- Rembg; transparency True", "edge transparent=False: sin Rembg, SaveImage <- VAEDecode", "edge size: width==height==768 (cuadrado)", "edge hazard al inicio del scaffold", "edge view reflejado como '{view} view'", "edge view vacio: sin clausula 'view' colgando", "edge style del set en prompt", "edge negativo anti personaje/criatura viva + multiple objects (diferenciado de enemy_creature/prop_object)", "edge lora: LoraLoader presente con strength", "edge transparent default True", "error hazard vacio -> ValueError", "determinismo"]
test_file_path: "python/functions/ml/comfyui_build_trap_hazard_workflow_test.py"
file_path: "python/functions/ml/comfyui_build_trap_hazard_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_trap_hazard_workflow import comfyui_build_trap_hazard_workflow

# Una trampa de escenario con fondo transparente (alpha), lista para soltar en el nivel.
wf = comfyui_build_trap_hazard_workflow(
    "spiked floor trap",
    view="side",
    style="game hazard trap",
    transparent=True,
    seed=7,
)
# Poblar un nivel: variar `hazard` con el MISMO view/style/checkpoint/(lora) para coherencia.
#   for h in ["spinning saw blade", "lava pit", "pressure plate", "flame jet", "acid pool"]:
#       wf = comfyui_build_trap_hazard_workflow(h, view="side", style="game hazard trap", seed=7)
#       comfyui_submit_workflow(wf)  # -> comfyui_wait_result -> comfyui_fetch_output_image
# Contact-sheet de los peligros: montar los PNG resultantes con comfyui_build_grid.
```

O lanzable directo con: `python/.venv/bin/python python/functions/ml/comfyui_build_trap_hazard_workflow.py` (imprime nodos + class_types del ejemplo). Nota: `./fn run` no admite esta firma (parámetros keyword-only con `*`), igual que los builders hermanos; usa el `__main__` del `.py`.

## Cuando usarla

Cuando necesites trampas/peligros JUGABLES para poblar niveles de un juego (plataformas,
mazmorras, roguelike, acción): pinchos del suelo, sierras giratorias, fosos de lava,
placas de presión, columnas de llamas, trampas de flechas, charcos de ácido, descargas
eléctricas, prensas, estacas cayendo. A diferencia de `comfyui_build_prop_object_workflow`
(un objeto de decoración INERTE: barril, cofre, antorcha que solo ambienta), aquí el asset
es un PELIGRO con el que el motor le asigna hitbox de daño, estado activo/inactivo y
animación de disparo/golpe. Y a diferencia de `comfyui_build_enemy_creature_workflow`
(enemigo VIVO), una trampa es un objeto/mecanismo, no una criatura — el negativo por
defecto rechaza `character / person / creature` para que no salga un enemigo. Fija `view`
(`side` por defecto) para la perspectiva del nivel y pasa el MISMO `view` + `style` +
`checkpoint` + (`lora`) a todas las trampas del set para que combinen; varía solo
`hazard`. `transparent` recorta el fondo (alpha) listo para soltar sobre el nivel. Para un
atlas/contact-sheet de los peligros, genera cada uno y monta los PNG con
`comfyui_build_grid`.

## Gotchas

- **Hazard (peligro jugable) != prop_object (decoración inerte) != enemy_creature
  (enemigo vivo)**: si lo que quieres es un objeto de escena que solo ambienta (barril,
  cofre, planta), usa `comfyui_build_prop_object_workflow`; si quieres una criatura
  enemiga, usa `comfyui_build_enemy_creature_workflow`. Este builder genera el MECANISMO
  de peligro (`single hazard object, trap, dangerous`); el negativo por defecto rechaza
  `character / person / creature / multiple objects` para no degradar a un enemigo ni a
  una escena con varios objetos.
- **El recorte usa Rembg, NO luma-to-alpha por defecto**: la mayoría de trampas son masas
  sólidas con silueta definida (pinchos metálicos, sierra, placa de presión, foso); rembg
  las recorta limpio. Pero si la trampa es **puramente etérea** (columna de llamas, arco
  eléctrico, nube de gas) y quieres conservar el falloff translúcido para blend aditivo en
  el motor, pon `transparent=False` y recorta con `comfyui_matting_luma_to_alpha` (o
  on-black + luma) fuera de este builder, igual que hacen
  `comfyui_build_status_effect_icon` / `decal_overlay`. Con rembg un efecto puramente
  translúcido perdería los bordes suaves.
- **`view` fija la perspectiva del nivel**: `side` (default) para trampas de plataformas;
  `top-down` para mazmorras cenitales; `isometric` para niveles iso; `front`/`3/4` para
  vistas frontales. Mantén el mismo `view` que el resto de assets del nivel.
- **Coherencia del set = mismos parámetros**: si cambias `view`/`style`/`checkpoint`/`lora`/
  `seed` entre trampas, el nivel deja de combinar. Fija esos y varía solo `hazard`.
- **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 un personaje, varios objetos o una escena completa, el negativo por
  defecto ya empuja a "single hazard object / no people / no creature"; refuerza `style`
  con "single isolated trap mechanism" si insiste.
- `transparent=False` deja el peligro 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`.
