---
name: comfyui_build_achievement_badge_workflow
kind: function
lang: py
domain: ml
version: "1.0.0"
purity: pure
signature: "def comfyui_build_achievement_badge_workflow(badge: str, *, tier: str = \"gold\", style: str = \"game achievement badge, ornate\", checkpoint: str = \"IMG_dreamshaper_8.safetensors\", size: int = 256, 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 = \"achievement_badge\") -> dict"
description: "Construye el dict (API format) del workflow de UNA insignia / medalla / logro 2D (achievement, recompensa, rango): un trofeo, una medalla con cinta, un escudo de logro, una estrella o un badge de rango que la UI de achievements pinta cuando el jugador desbloquea un hito, con TIER metalico (bronce / plata / oro / platino / diamante) que distingue el grado. Centrado, fondo limpio uniforme, recortable a alpha, estilo consistente entre insignias del set. DISTINTO de item_icon (objeto de inventario suelto, sin tier ni cinta), status_effect_icon (simbolo de estado superpuesto sin marco) y skill_tree_node (nodo enmarcado de la rejilla de talentos con estado unlocked/locked): esto es la INSIGNIA DE LOGRO/RECOMPENSA = trofeo/medalla con cinta + tier. El tier metalico y la forma de medalla/trofeo son la firma del asset. Compone comfyui_build_txt2img_workflow + comfyui_inject_lora (estilo opcional) + Image Rembg (fondo transparente si transparent). Hermano de comfyui_build_item_icon/skill_tree_node_workflow. Pura, sin red ni I/O. class_types verificados contra /object_info."
tags: [comfyui, ml, gamedev-2d, ui, achievement, badge, medal, trophy, reward, tier, ribbon, 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: badge
    desc: "Nombre / tema del logro que representa la insignia (ej. 'dragon slayer', 'first blood', '100 wins', 'explorer', 'marathon runner', 'boss killer'). Se inserta en un prompt scaffold de insignia. No puede estar vacio."
  - name: tier
    desc: "Grado del logro: 'bronze', 'silver', 'gold' (por defecto), 'platinum' o 'diamond'. Define el aspecto metalico de la medalla. Genera la familia con el mismo badge/style/seed variando solo el tier para tener las caras coherentes del mismo logro. Cualquier otro valor se inserta literal y la pista metalica cae a la de 'gold'. keyword-only."
  - name: style
    desc: "Descriptor de estilo que mantiene consistentes las insignias de un set (ej. 'game achievement badge, ornate', 'flat minimal medal', 'pixel art trophy'). Pasa el MISMO style + checkpoint + lora a todas las insignias del set 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). 256 por defecto: las insignias de logro se muestran a tamano reducido en el panel. keyword-only."
  - name: transparent
    desc: "Si True inyecta Image Rembg y el PNG sale con alpha (fondo recortado, la silueta de la medalla + cinta). False = insignia opaca sobre fondo plano, recortable luego por el caller. keyword-only."
  - name: seed
    desc: "Semilla del KSampler. Fija el mismo seed en la familia de tiers del mismo logro para que coincidan en composicion. keyword-only."
  - name: lora
    desc: "LoRA de estilo opcional en models/loras (ej. 'SD15_detail_tweaker.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 insignias (una medalla limpia, fondo limpio, sin escena/personaje/texto). 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 insignia ('{badge} achievement badge, {tier} tier ({tier hint}), {style}, medal with ribbon, centered, plain background, game UI reward, ...') + LoRA de estilo opcional + Image Rembg (si transparent). UNA insignia; un set de logros -> llamar por badge (y por tier) con mismo style/checkpoint/lora y montar el panel en el motor."
tested: true
test_file_path: python/functions/ml/comfyui_build_achievement_badge_workflow_test.py
tests: [test_golden_transparent, test_edge_transparent_false_no_rembg, test_edge_size_reflected_square, test_edge_tier_gold_default_hint, test_edge_tier_bronze_reflected, test_edge_tier_silver_reflected, test_edge_tier_unknown_falls_back_to_gold_hint, test_edge_style_reflected, test_edge_badge_reflected, test_edge_lora_injected, test_error_empty_badge, test_determinism]
file_path: python/functions/ml/comfyui_build_achievement_badge_workflow.py
---

Construye el dict (API format) del workflow de UNA insignia / medalla / logro 2D
(achievement, recompensa, rango): un trofeo, una medalla con cinta, un escudo de logro,
una estrella o un badge de rango que la UI de achievements pinta cuando el jugador
desbloquea un hito, con TIER metalico (bronce / plata / oro / platino / diamante) que
distingue el grado. Centrado, fondo limpio uniforme, recortable a alpha, estilo
consistente entre insignias del mismo set. Compone `comfyui_build_txt2img_workflow` +
`comfyui_inject_lora` (estilo opcional) + `Image Rembg` (fondo transparente si
`transparent`). Hermano de `comfyui_build_item_icon_workflow` /
`comfyui_build_skill_tree_node_workflow`. Pura, sin red ni I/O. class_types verificados
contra `/object_info`.

## Ejemplo

```python
import sys, os
sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
from ml.comfyui_build_achievement_badge_workflow import comfyui_build_achievement_badge_workflow

# Insignia de logro tier oro, medalla con cinta, fondo transparente (alpha).
wf = comfyui_build_achievement_badge_workflow(
    "dragon slayer",
    tier="gold",
    style="game achievement badge, ornate",
    transparent=True,
    seed=12345,
)
# La familia de un mismo logro (los grados del panel): mismo badge/style/seed,
# solo cambia tier. El motor intercambia el sprite segun el grado conseguido.
#   for t in ["bronze", "silver", "gold"]:
#       wf = comfyui_build_achievement_badge_workflow("dragon slayer", tier=t, seed=12345)
#       comfyui_submit_workflow(wf)  # -> comfyui_wait_result -> comfyui_fetch_output_image
# Set completo coherente: misma firma de style/checkpoint por insignia, varia badge.
```

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

## Cuando usarla

Cuando necesites las insignias del sistema de logros / recompensas de un juego: cada
achievement desbloqueado se muestra como una medalla, trofeo o escudo con cinta y un
grado metalico (bronce / plata / oro). Genera la **familia** `tier="bronze"` /
`"silver"` / `"gold"` con el mismo `badge`/`style`/`seed` para tener las caras
coherentes del mismo logro; el motor cambia el sprite segun el grado que el jugador
haya conseguido. Pasa el MISMO `style` + `checkpoint` + (`lora`) a todas las insignias
del set para que el panel de logros combine. `transparent` recorta la silueta de la
medalla + cinta (alpha) lista para el motor.

Eligela frente a sus hermanos por el ROL del asset:
- **item_icon** -> objeto de inventario (espada, pocion): ilustracion de un objeto
  suelto que el jugador usa/equipa, SIN tier ni cinta.
- **status_effect_icon** -> simbolo de estado compacto que se superpone al retrato/barra
  del personaje (envenenado, aturdido), SIN marco; optimizado para 16-32 px.
- **skill_tree_node** -> nodo ENMARCADO de la pantalla de talentos con estado
  unlocked/locked; vive en una rejilla de progresion.
- **achievement_badge (esta)** -> la INSIGNIA DE LOGRO/RECOMPENSA = trofeo/medalla con
  cinta + tier (bronce/plata/oro). Se muestra en el panel de logros.

## Gotchas

- **El tier y la cinta son la firma**: lo que distingue este builder de
  item_icon/skill_tree_node es que el asset es una medalla/trofeo con `tier` metalico y
  cinta. El negativo por defecto NO rechaza "ribbon/medal/trophy" (son parte del asset),
  pero si rechaza escenas recargadas, multiples badges y fondos sucios. Si el modelo
  ignora el tier metalico, refuerza `style` con "{tier} medal, metallic sheen".
- **La familia de tiers debe compartir parametros**: para que los grados del mismo logro
  coincidan en composicion, fija el mismo `badge`/`style`/`seed` y varia SOLO `tier`. La
  pista metalica del tier (`bronze` -> bronze/copper; `silver` -> chrome/grey; `gold` ->
  golden/yellow; `platinum`/`diamond` -> top tier) se anade automaticamente en el prompt.
  Un tier desconocido se inserta literal pero la pista cae a la de `gold`.
- **Coherencia del set = mismos parametros**: si cambias `style`/`checkpoint`/`lora`
  entre insignias, el panel deja de combinar. Fija esos y varia solo `badge` (y `tier`).
- **El recorte usa Rembg, NO luma-to-alpha**: una insignia es una pieza SOLIDA con
  silueta definida (la medalla perfila el borde, la cinta cuelga), rembg la recorta
  limpio. `comfyui_matting_luma_to_alpha` es para translucidos sobre negro (humo/fuego/
  runas brillantes) y aplanaria la medalla — no la uses para estas insignias.
- **El texto/nombre lo pone el motor, no la imagen**: el negativo por defecto empuja a
  "no text/no letters/no numbers" para que la insignia quede limpia; el nombre del logro,
  la descripcion y la fecha los renderiza el juego sobre el badge.
- **SDXL pide mas VRAM y resolucion**: con `checkpoint="IMG_juggernaut_xl_v11.safetensors"`
  sube `size` a 512; con IMG_dreamshaper_8 (SD1.5) deja 256 (holgado en 8GB lowvram).
- `transparent=False` deja la insignia opaca sobre fondo plano: util si prefieres
  recortar fuera del workflow o el motor compone sobre un slot 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`.
