---
name: comfyui_build_prop_object_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_prop_object_workflow(prop: str, *, style: str = \"game prop, isometric or side view\", 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 = \"prop_object\") -> dict"
description: "Construye el dict (API format) del workflow de UN prop/objeto de escenario de juego 2D (barril, cofre, antorcha, planta, mueble, roca, fuente, estatua, decoracion): UN objeto inanimado aislado a escala de escena y perspectiva de juego (isometrica/lateral), centrado, fondo limpio uniforme recortable a alpha, estilo consistente para poblar un nivel. Diferenciado de comfyui_build_item_icon (objeto de MUNDO vs icono plano de inventario). Compone comfyui_build_txt2img_workflow + comfyui_inject_lora (estilo opcional) + Image Rembg (fondo transparente si transparent). Hermano de comfyui_build_enemy_creature/item_icon/ui_hud_workflow. Pura, sin red ni I/O. class_types verificados contra /object_info."
tags: [comfyui, ml, gamedev-2d, prop, object, 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: prop
    desc: "Descripcion del objeto de escenario (ej. 'wooden barrel', 'treasure chest', 'lit torch', 'potted plant', 'stone fountain', 'wooden table', 'mossy rock'). Se inserta en un prompt scaffold de prop. No puede estar vacio."
  - name: style
    desc: "Descriptor de estilo/perspectiva que mantiene consistentes los props del set y los situa en el MUNDO, no en la UI (ej. 'game prop, isometric or side view', 'top-down RPG prop', 'side-scroller platformer prop', 'low poly stylized prop'). Pasa el MISMO style + checkpoint + lora a todos los props del nivel 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 soltar sobre el tilemap). False = objeto opaco sobre fondo plano, recortable luego por el caller. keyword-only."
  - name: seed
    desc: "Semilla del KSampler. Misma seed + mismo prop/style -> mismo objeto. keyword-only."
  - name: lora
    desc: "LoRA de estilo opcional en models/loras (ej. 'SD15_isometric_game_assets.safetensors', 'SDXL_stylized_props.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 props (un objeto inanimado entero, sin personas/criaturas, 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 prop ('{prop}, {style}, game asset, single object, centered, plain background, scene prop, world object, ...') + LoRA de estilo opcional + Image Rembg (si transparent). UN objeto; para poblar un nivel -> llamar por cada prop con mismo style/checkpoint/lora; contact-sheet del atrezzo -> montar los PNG con comfyui_build_grid."
tested: true
tests: ["golden transparent: clases CheckpointLoaderSimple/KSampler/VAEDecode/SaveImage/Image Rembg; prop + 'single object' + 'centered' + 'game asset' + 'plain background' en prompt; SaveImage <- Rembg; transparency True", "edge transparent=False: sin Rembg, SaveImage <- VAEDecode", "edge size: width==height==768 (cuadrado)", "edge prop al inicio del scaffold", "edge style de mundo en prompt", "edge objeto de mundo (scene prop/world object) y negativo anti-persona/criatura (diferenciado de item_icon)", "edge lora: LoraLoader presente con strength", "edge transparent default True", "error prop vacio -> ValueError", "determinismo"]
test_file_path: "python/functions/ml/comfyui_build_prop_object_workflow_test.py"
file_path: "python/functions/ml/comfyui_build_prop_object_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_prop_object_workflow import comfyui_build_prop_object_workflow

# Un prop de escenario con fondo transparente (alpha), listo para soltar en el nivel.
wf = comfyui_build_prop_object_workflow(
    "wooden treasure chest",
    style="game prop, isometric or side view",
    transparent=True,
    seed=7,
)
# Poblar un nivel: variar `prop` con el MISMO style/checkpoint/(lora) para coherencia.
#   for p in ["wooden barrel", "treasure chest", "lit torch", "potted plant", "mossy rock"]:
#       wf = comfyui_build_prop_object_workflow(p, style="game prop, isometric or side view", seed=7)
#       comfyui_submit_workflow(wf)  # -> comfyui_wait_result -> comfyui_fetch_output_image
# Contact-sheet del atrezzo: montar los PNG resultantes con comfyui_build_grid.
```

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

## Cuando usarla

Cuando necesites atrezzo/decorado de escenario para un juego (RPG, plataformas,
top-down, isometrico): barriles, cofres, antorchas, plantas, muebles, rocas,
fuentes, estatuas, decoracion. A diferencia de `comfyui_build_item_icon_workflow`
(icono PLANO de inventario para una casilla de UI), aqui el objeto es de MUNDO:
conserva la perspectiva del juego (isometrica/lateral) y la escala de la escena para
encajar con los tiles. Pasa el MISMO `style` + `checkpoint` + (`lora`) a todos los
props del nivel para que combinen visualmente; varia solo `prop`. `transparent`
recorta el fondo (alpha) listo para soltar sobre el tilemap. Para un atlas/contact-
sheet del atrezzo, genera cada prop y monta los PNG con `comfyui_build_grid`.

## Gotchas

- **Prop (objeto de mundo) != item icon (icono de inventario)**: si lo que quieres es
  un icono cuadrado plano para una casilla de UI, usa
  `comfyui_build_item_icon_workflow`. Este builder situa el objeto en la ESCENA
  (perspectiva isometrica/lateral, escala de mundo) para poblar el nivel.
- **El recorte usa Rembg, NO luma-to-alpha**: un prop es un objeto solido con silueta
  definida, rembg lo recorta limpio. `comfyui_matting_luma_to_alpha` es para
  translucidos sobre negro (humo/fuego/magia). Si el prop es etereo o translucido
  (cristal magico, llama suelta), 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 props, el atrezzo deja de combinar. Fija esos y varia solo `prop`.
- **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.
- Si el modelo mete una persona/criatura o varios objetos, el negativo por defecto ya
  empuja a "single object / no characters / no cropped"; refuerza `style` con
  "isolated object, single item, no people" si insiste.
- `transparent=False` deja el objeto 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`.
