fn_registry/docs/capabilities/gamedev-2d.md

Capability group: gamedev — assets 2D para Godot (post-proceso + puente)

Cluster de funciones para producir y mover assets 2D de juego entre ComfyUI (generación) y Godot 4 (consumo). Cubre el post-proceso determinista de los crudos generados (pixelizar, recortar a alpha) y el puente de assets que los coloca en un proyecto Godot con sus import settings correctos. Todas son CPU-only: ninguna toca la GPU ni descarga modelos.

Tag plano del grupo: gamedev. Filtro: mcp__registry__fn_search query="" tag="gamedev".

Documento hermano del grupo comfyui (generación de imágenes/video/3D): este grupo empieza donde el crudo ya existe en ~/ComfyUI/output/. Diseño del puente: docs/comfyui-godot-integration.md. Planes origen: reports/0135 (pixelart), reports/0140 (VFX), reports/0137/0138 (puente Godot).

Funciones del grupo

ID	Firma corta	Qué hace
comfyui_pixelize_image_py_ml	(src, dst, *, downscale=8, colors=16, palette=None, dither=False, upscale_back=True) -> dict	Pixel-perfect: downscale nearest + cuantización a N colores o paleta fija (game-boy/pico-8/nes). Fase 2 pixelart. Impura (I/O).
comfyui_matting_luma_to_alpha_py_ml	(image_path, *, out_path=None, gamma=1.0, black_point=0.0, premultiply=False, luma_weights=(.299,.587,.114)) -> dict	Frame VFX sobre negro -> RGBA usando luminancia como alpha (translúcidos con additive blend). Impura (I/O).
comfyui_export_asset_to_godot_py_pipelines	(asset_path, kind, godot_project, *, name=None, reimport=True, godot_bin=None) -> dict	Copia el asset a res://assets/<dir>/ por kind + escribe .import + filtro Nearest si pixelart + reimport headless. Pipeline impuro.
godot_map_asset_dir_py_core	(kind) -> str	Mapea kind -> subcarpeta de res://assets/. Pura.
godot_clean_asset_name_py_core	(filename, *, override=None) -> str	Normaliza el nombre <prefijo>_NNNNN_.<ext> a snake_case seguro para res://. Pura.

Ejemplo canónico end-to-end

Flujo: crudo generado en ComfyUI -> pixelizar -> exportar a Godot con Nearest.

import sys, os
sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions"))
from ml.comfyui_pixelize_image import comfyui_pixelize_image
from ml.comfyui_matting_luma_to_alpha import comfyui_matting_luma_to_alpha
from pipelines.comfyui_export_asset_to_godot import comfyui_export_asset_to_godot

OUT = os.path.expanduser("~/ComfyUI/output")
PROJ = os.path.expanduser("~/gamedev/projects/crossy_road")

# 1. Pixelizar un sprite crudo (SDXL+pixel-art-xl) a 16 colores
px = comfyui_pixelize_image(f"{OUT}/hero_00001_.png", "/tmp/hero_pixel.png",
                            downscale=8, colors=16)

# 2. Exportarlo a Godot como pixelart (carpeta sprites/, filtro Nearest, reimport)
exp = comfyui_export_asset_to_godot("/tmp/hero_pixel.png", "pixelart", PROJ)
print(exp["dest_res_path"], exp["pixelart_filter_set"], exp["reimported"])

# Rama VFX: frame de humo sobre negro -> RGBA -> carpeta vfx/
rgba = comfyui_matting_luma_to_alpha(f"{OUT}/vfx_loop_00007_.png", gamma=1.2, black_point=0.04)
comfyui_export_asset_to_godot(rgba["out_path"], "vfx", PROJ)

Fronteras (qué NO cubre)

• Generación: este grupo no genera imágenes. La Fase 1 (SDXL + LoRA pixel-art-xl, AnimateDiff loop, etc.) vive en el grupo comfyui y necesita GPU.
• Montaje de spritesheet (grid RGBA + JSON sidecar) y builders de workflow (pixelart/VFX-loop): pendientes de la ronda siguiente (planes reports/0135 F3/F4 y reports/0140 F2/F3). Cuando se añadan, van a este mismo grupo.
• Paletas lospec por red (load_lospec_palette): no incluido. pixelize usa paletas fijas embebidas (game-boy/pico-8/nes) o lista de hex, sin HTTP.
• TileSet / SpriteFrames .tres: Godot no los deriva solos; export_asset_to_godot copia la textura y avisa, pero no genera el recurso (paso manual o futura función).

Prerequisitos / notas

• Godot CLI para el reimport headless: autodetectado en PATH y en ~/godot/Godot_v4.7-stable_linux.x86_64. Si falta, export_asset_to_godot deja el .import escrito y lo anota (no falla).
• Filtro Nearest (Godot 4): se setea global en project.godot (default_texture_filter=0), no por .import. La función lo asegura para pixelart.
• CPU-only: Pillow + numpy del venv del registry. Cero VRAM, cero red.